feat(sqlite): inspect offline snapshots with selective evidence

.agents/skills/reverse-engineer-anything/SKILL.md

@@ -83,6 +83,15 @@ explicit path or endpoint and do not need it.
   absent metadata does not prove a binary is not Go, and unparsed text records
   remain explicit. See the
   [Go binary guide](https://github.com/morluto/rea/blob/main/docs/go-binaries.md).
+
+- Explicit local SQLite database snapshot: `inspect_sqlite_database`. Inspect
+  with Node.js 24.x >=24.15 or 26+ providing native SQLite limits. Read schema
+  first (compact inventory by default), or select an exact ordinary table
+  and `columns` when rows are needed. Defaults are selected-table schema and
+  20 rows; request `schema_scope: "database"` for the complete stored schema. Preserve both database and existing sibling WAL identity; row samples
+  report truncation and have unspecified order. Use a quiescent snapshot rather
+  than assuming a live database/WAL pair was copied atomically. See the
+  [SQLite guide](https://github.com/morluto/rea/blob/main/docs/sqlite-databases.md).
 - Explicit Linux ELF file for offline layout, symbols, relocations or static
   mitigation evidence: `inspect_binary_layout`. This target-free operation uses
   caller-supplied pwntools without opening a disassembler database. Preserve its

.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md

@@ -11,6 +11,21 @@ unparsed module-text line. A missing record is an unknown, not proof of a
 non-Go binary; observed metadata does not authenticate its claims. Function,
 source and type recovery remain a separate native-analysis question.
 
+## SQLite snapshots
+
+Use `inspect_sqlite_database` with an explicit local database snapshot for its
+schema and optional rows from one exact ordinary table. It requires Node.js
+24.x >=24.15 or 26+ with the native `DatabaseSync.limits` API. It also consumes the
+existing sibling `-wal`; retain both original digests when citing its result.
+Default output is a compact inventory; a selected table expands only its own
+schema and samples 20 rows. Select `columns` to avoid irrelevant or large cells,
+and request `schema_scope: "database"` only for complete schema details.
+Choose `row_limit` when a finite sample is useful and keep truncation and
+unspecified row order explicit. Virtual tables, shadow tables and views are
+schema facts, not row-read targets. REA inspects private copies and leaves
+the source files untouched; obtain a coherent quiescent database/WAL snapshot
+before inspection. See [SQLite snapshots](https://github.com/morluto/rea/blob/main/docs/sqlite-databases.md).
+
 ## Recorded Linux crashes
 
 Use `inspect_recorded_crash` with an explicit Linux x86-64 ELF core path to

.github/workflows/ci.yml

@@ -209,6 +209,11 @@ jobs:
           if-no-files-found: error
           retention-days: 7
 
+  sqlite-runtime:
+    needs: [changes, build]
+    if: needs.changes.outputs.code == 'true'
+    uses: ./.github/workflows/sqlite-runtime.yml
+
   test:
     name: Test (coverage + timing)
     needs: [changes, test-shard]
@@ -659,6 +664,7 @@ jobs:
         static,
         build,
         test-shard,
+        sqlite-runtime,
         test,
         conformance-fixtures,
         windows-native-build,

.github/workflows/sqlite-runtime.yml

@@ -0,0 +1,37 @@
+name: SQLite runtime compatibility
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+env:
+  HUSKY: "0"
+
+jobs:
+  sqlite:
+    name: SQLite runtime compatibility (Node ${{ matrix.node }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        # Exercise unavailable-runtime diagnostics, the first supported release,
+        # and new patches on both supported lines without hand-editing versions.
+        # The repository-pinned Node 24 version also runs the complete test suite.
+        node: ["22.x", "24.15.0", "24.x", "26.x"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          check-latest: true
+          cache: npm
+      - run: npm ci
+      - uses: actions/download-artifact@v4
+        with:
+          name: rea-test-runtime
+          path: .
+      - name: Verify SQLite discovery, inspection and cleanup
+        run: npm run test:sqlite:run

README.md

@@ -157,6 +157,7 @@ Additional tools and host support depend on the target:
 | Go binaries            | Embedded compiler version, modules, replacements and build settings                  | Built-in static ELF/PE/thin Mach-O inspection; no Go installation required                                                            |
 | WASM artifact          | Validation, sections, exact import/export WAT forms and decoded WAT                  | Caller-supplied WABT 1.0.42; `inspect_wasm_artifact`                                                                                  |
 | EVM bytecode           | Dispatch selectors, byte offsets, inferred arguments and mutability                  | Local raw/hex carrier on Linux x64; [offline EVM guide](docs/evm-bytecode.md)                                                         |
+| SQLite databases       | Tables, columns, indexes, views, triggers and selected ordinary-table rows           | Local database/WAL snapshot; Node.js 24.x >=24.15 or 26+ with native SQLite limits                                                    |
 | Recorded Linux crashes | Raw notes, every recorded thread's registers/signals and optional mapping candidates | Caller-supplied pwntools on Linux x64; optional GDB/pwndbg; [recorded crashes](docs/recorded-crashes.md)                              |
 | JavaScript / Electron  | Modules, imports, source maps, routes, IPC and native add-on relationships           | Node.js and npm; [application analysis](https://rea.tools/guides/javascript/)                                                         |
 | Websites               | Page structure, scripts, network observations and requested screenshots              | A Chrome-family browser; [browser analysis](https://rea.tools/guides/browser/)                                                        |

docs/.vitepress/config.ts

@@ -43,6 +43,7 @@ export default defineConfig({
           { text: "Android applications", link: "/android-analysis" },
           { text: "Apple applications", link: "/apple-application-analysis" },
           { text: "Firmware", link: "/firmware-analysis" },
+          { text: "SQLite databases", link: "/sqlite-databases" },
         ],
       },
       {

docs/cli.md

@@ -62,6 +62,14 @@ unpack .NET single-file hosts or decode IL2CPP metadata. NativeAOT method bodies
 require native analysis. See the [managed-code guide](managed-code-analysis.md)
 for supported deployment forms, selection semantics, and coverage limits.
 
+## SQLite snapshots
+
+For a local database snapshot, use `rea inspect-sqlite-database PATH --json`.
+Add `--table NAME --row-limit 20` to read a bounded sample from an ordinary
+table. This command does not require a native analysis provider. See
+[SQLite database snapshots](sqlite-databases.md) for database/WAL identity,
+source-file handling and row-value semantics.
+
 ## Native analysis
 
 Inspect embedded Go build metadata without installing Go or configuring a

docs/sqlite-databases.md

@@ -0,0 +1,144 @@
+# SQLite database snapshots
+
+`inspect_sqlite_database` / `inspect-sqlite-database` inspects one explicitly
+selected local SQLite database snapshot without an active native analysis
+target. Use it to understand application storage, configuration or retained
+database evidence. No separate SQLite installation is required.
+
+This operation requires Node.js 24.x >=24.15 or 26+ with the native
+`DatabaseSync.limits` API. The worker verifies that capability before querying
+the copied database. Other REA features retain their published Node.js 22.x,
+24.x or 26+ requirements.
+
+`rea capabilities` reports `inspect_sqlite_database` availability and the
+runtime requirement without opening a database. Unsupported runtimes show
+`available: false`, `availability_code: "unsupported_version"`, and an upgrade
+note while the inventory command still succeeds.
+
+```sh
+rea capabilities --json
+rea inspect-sqlite-database ./application.sqlite --json
+rea inspect-sqlite-database ./application.sqlite --table settings --column key --column value --row-limit 20 --json
+```
+
+```json
+{
+  "name": "inspect_sqlite_database",
+  "arguments": {
+    "path": "/artifacts/application.sqlite",
+    "table": "settings",
+    "columns": ["key", "value"],
+    "row_limit": 20
+  }
+}
+```
+
+MCP paths must be absolute filesystem paths on the current host. CLI paths
+resolve against the operator's working directory. Select a quiescent snapshot:
+stop the writer or obtain a consistent database/WAL pair using the application's
+backup workflow before inspection. A file copy of a live pair does not establish
+an atomic SQLite snapshot, even if no change is detected during inspection.
+
+## Returned evidence
+
+Without a table selection, the default `schema_scope` is `inventory`: compact
+table metadata and index, view and trigger names, without SQL declarations or
+column details. Selecting a table defaults to `selected_table`, which expands
+that table and its indexes and triggers. Explicit `schema_scope: "database"`
+(or CLI `--schema-scope database`) expands all stored declarations and supported
+columns. `schema.completeness` refers to the reported scope; omitted column
+details are marked `not_requested`. SQL declarations retain the original text. Virtual and
+shadow tables are identified as such; their supported metadata coverage is
+reported. If a virtual table cannot be resolved, possible backing tables have
+`kind: "unknown"` and an explicit limitation; their rows are refused. Unrelated
+ordinary tables remain selectable. Schema inventory does not execute views,
+triggers or arbitrary SQL.
+
+Rows are optional. `table` selects one exact ordinary-table name. `columns`
+(CLI repeated `--column`) selects exact visible column names in the requested
+order; omission selects all visible columns, including generated columns.
+Unselected cells are not evaluated or projected. Column selection requires a
+table and at least one name; empty-string identifiers are valid. `row_limit`
+requires `table`, defaults to 20 and accepts positive safe integers. Samples
+remain subject to the byte and worker resource limits below, regardless of row count. The result reports
+the selected limit, returned count and whether more rows were observed. Row
+order is unspecified; a truncated sample does not prove anything about omitted
+records. View, virtual-table and shadow-table row reads are unsupported.
+
+SQLite integers are decimal strings so every signed 64-bit value survives JSON
+serialization. Real values retain their numbers; `"Infinity"`, `"-Infinity"`
+and `"-0"` explicitly preserve infinities and negative zero through JSON.
+Text returns the decoded string together with its bytes as hex and the database
+encoding, preserving malformed text that the SQLite binding may replace for
+display. Blobs are hex, and SQL NULL is a distinct tagged value.
+
+Database and existing sibling `-wal` files have separate original SHA-256 and
+byte counts. The Evidence subject identifies the original database file;
+the WAL identity is also necessary to interpret pending committed data. The
+SQLite engine version is reported with the observed result. Neither digest is
+a claim that the database is healthy, complete or trusted.
+
+## Source files and failures
+
+REA copies the selected database and existing sibling WAL to an owned private
+temporary directory before SQLite opens them. Source files are not opened by
+SQLite, so its locks or shared-memory sidecars cannot modify the original
+snapshot. Temporary copies and the owned worker are cleaned up on success,
+failure and cancellation. Extension loading and schema trust are disabled.
+Empty rollback journals and fully zeroed journal headers left by successful
+`TRUNCATE` and `PERSIST` commits are accepted after stable identity checks.
+Journal headers are checked both before and after acquisition; unchanged file
+metadata alone does not establish that a journal remains inactive.
+Other retained rollback journals are refused because recovery is outside this
+profile. Journal files are never modified or copied into the worker snapshot.
+
+A provider admits at most two inspections through acquisition, worker execution
+and cleanup. Additional requests receive a typed capacity error before reading
+files or creating workers; retry after an active inspection finishes. This
+bounds simultaneous input buffering and private snapshot/worker counts.
+
+The database and WAL together are limited to 256 MiB. SQLite values/records,
+SQL statements and the complete worker JSON reply each have a 16 MiB limit.
+The owned worker has a 256 MiB JavaScript heap limit and a 30-second inspection
+deadline. SQLite native allocations are separate from the JavaScript heap;
+overall native heap and total resident memory are not capped. Row limits do not
+override these byte and resource limits. Resource-limit failures do not return
+an incomplete schema as successful complete evidence.
+
+MCP also applies its configured response budget to the complete Evidence
+envelope. If delivery exceeds that budget, it reports a transport constraint
+with guidance for exporting retained Evidence, requesting a matching larger
+client/server response budget or using complete CLI JSON output.
+
+A cancellation received after the worker has completed does not erase the
+completed observation. If subsequent private-root cleanup fails, the error
+retains the completed Evidence and the resource owner for cleanup retry. MCP
+records that Evidence before delivering the error, which carries its retained
+evidence ID for later retrieval or export.
+
+Changed input identities, special files, malformed databases, unsupported
+formats and resource failures are reported as errors with the selected path and
+meaningful reason. Encrypted databases, database repair, arbitrary SQL,
+cross-database queries and live capture are outside this inspection's coverage.
+
+## Compatibility verification
+
+Run `npm run test:sqlite` after changing the SQLite adapter or its shared
+process, filesystem, CLI or MCP boundaries. It prepares the compiled runtime
+and runs SQLite service, snapshot, inspection, cleanup and public CLI/MCP
+tests. Directory-based selection includes new SQLite service and boundary
+tests automatically. `npm run test:sqlite:run` runs the same cases when the
+compiled runtime and generated test artifacts are already current.
+
+The reusable SQLite CI workflow consumes the shared build artifact and tests
+the latest Node 22.x unavailable-runtime diagnostics, the minimum supported
+24.15.0 release, and the latest 24.x and 26.x releases. The repository-pinned
+runtime also runs the full suite. CI's required gate waits for every selected
+SQLite matrix job; a failed, cancelled, skipped or missing selected lane blocks
+the gate. Workflow changes themselves select the build and compatibility lane.
+
+PR checks run against GitHub's merge with the current base branch. A later
+change to `main` can introduce failures outside SQLite; inspect the failing
+job and recheck the updated merge before treating an earlier green run as
+current verification. Compatibility checks detect regressions, but cannot
+guarantee that an arbitrary future upstream change remains compatible.

package.json

@@ -244,6 +244,8 @@
     "verify:native-calls": "npm run build:cached && node scripts/verify-native-calls.mjs",
     "verify:native-ui:permissions": "npm run build:cached && node scripts/verify-native-ui.mjs --allow-permission-denial",
     "test:focused": "node scripts/run-development-tests.mjs focused",
+    "test:sqlite": "npm run test:prepare && npm run test:sqlite:run",
+    "test:sqlite:run": "vitest run src/application/sqlite/ tests/boundary/sqlite/ tests/acceptance/sqliteDatabaseCli.test.ts tests/boundary/mcp/serverLifecycleMcp.test.ts",
     "build:windows-native": "node scripts/build-windows-native.mjs",
     "verify:windows-native:artifact": "node scripts/verify-windows-native-artifact.mjs",
     "prepublishOnly": "npm run verify:windows-native:artifact",

scripts/ci/plan.mjs

@@ -24,6 +24,7 @@ const NATIVE_TEST_OWNERS = ["apple", "package"];
 const GUARDED_WORKFLOWS = new Set([
   ".github/workflows/release.yml",
   ".github/workflows/real-ghidra-windows.yml",
+  ".github/workflows/sqlite-runtime.yml",
 ]);
 // Sources compiled by build-conformance-fixtures.mjs. The readiness journey
 // analyzes the built C fixture as well as its own applications.

scripts/ci/required.mjs

@@ -2,7 +2,7 @@ const jobs = JSON.parse(process.env.CI_JOBS);
 const outputs = jobs.changes.outputs;
 const required = ["changes", "static", "test"];
 const lanes = {
-  code: ["build", "test-shard"],
+  code: ["build", "test-shard", "sqlite-runtime"],
   runtime: ["windows-native-build", "package-e2e"],
   package: ["windows-curated"],
   apple: ["apple-artifacts"],

scripts/lib/catalog-builders.mjs

@@ -29,6 +29,7 @@ export const toolFamilyCatalog = (sources) => {
         ...sources.evmContracts.EVM_TOOL_CONTRACTS,
         ...sources.goContracts.GO_TOOL_CONTRACTS,
         ...sources.wasmContracts.WASM_TOOL_CONTRACTS,
+        ...sources.sqliteContracts.SQLITE_TOOL_CONTRACTS,
       ],
     },
     {
@@ -207,6 +208,10 @@ export const providerCatalog = (sources) => {
       identity: sources.goProvider.GO_BINARY_PROVIDER_IDENTITY,
       contracts: sources.goContracts.GO_TOOL_CONTRACTS,
     },
+    {
+      identity: sources.sqliteDomain.SQLITE_PROVIDER_IDENTITY,
+      contracts: sources.sqliteContracts.SQLITE_TOOL_CONTRACTS,
+    },
     {
       identity: sources.artifactProviders.ARTIFACT_GRAPH_PROVIDER,
       contracts: sources.artifactContracts.ARTIFACT_TOOL_CONTRACTS,

scripts/lib/catalog-core.mjs

@@ -50,6 +50,8 @@ const SOURCE_PATHS = {
   wasmContracts: "dist/contracts/wasm/wasmToolContracts.js",
   wasmProvider: "dist/wasm/WabtRelease.js",
   evmContracts: "dist/contracts/evm/evmToolContracts.js",
+  sqliteContracts: "dist/contracts/sqlite/sqliteToolContracts.js",
+  sqliteDomain: "dist/domain/sqlite/sqliteDatabase.js",
   evmProvider: "dist/evm/EvmoleRelease.js",
   goContracts: "dist/contracts/go/goToolContracts.js",
   goProvider: "dist/go/GoBinaryProvider.js",

scripts/lib/module-boundaries.mjs

@@ -5,6 +5,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 const PURE_LAYERS = new Set(["domain", "contracts"]);
 const MIGRATED_PROVIDER_ROOTS = new Set([
+  "sqlite",
   "evm",
   "go",
   "wasm",

src/application/CapabilityInventory.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { sqliteDatabaseCapability } from "./sqlite/SqliteDatabaseCapability.js";
 import type {
   OptionalProviderLoadFailures,
   OptionalProviderLoadFailure,
@@ -341,6 +342,15 @@ const workflowAvailabilityFor = ({
 }: AvailabilityContext): Availability | null => {
   if (name === "inspect_go_binary")
     return { reason: "available", remediation: null };
+  if (name === "inspect_sqlite_database") {
+    const capability = sqliteDatabaseCapability(process.versions.node);
+    return capability.available
+      ? { reason: "available", remediation: null }
+      : {
+          reason: "provider_unavailable",
+          remediation: capability.reason,
+        };
+  }
   if (name === "trace_web_module_imports")
     return {
       reason: "available",

src/application/DirectAnalysisStatus.ts

@@ -4,6 +4,9 @@ import { createServerIdentity } from "../serverIdentity.js";
 import { silentLogger } from "../logger.js";
 import type { Logger } from "pino";
 import type { DirectAnalysisDependencies } from "./DirectAnalysisDependencies.js";
+import { providerCapabilitySet } from "../contracts/toolOutputSchemaPrimitives.js";
+import { providerCapabilitySets } from "./binary/BinarySessionStatus.js";
+import { sqliteDatabaseCapability } from "./sqlite/SqliteDatabaseCapability.js";
 
 /** Read target-free provider status and operation availability. */
 export const runSessionStatus = async (
@@ -17,8 +20,15 @@ export const runSessionStatus = async (
   if (!config.ok) return { error: projectAnalysisError(config.error) };
   const session = await dependencies.createBinarySession(config.value, logger);
   try {
+    const status = jsonObjectSchema.parse(session.status());
     return {
-      ...jsonObjectSchema.parse(session.status()),
+      ...status,
+      capabilities: [
+        ...providerCapabilitySet.array().parse(status.capabilities),
+        ...providerCapabilitySets([
+          sqliteDatabaseCapability(process.versions.node),
+        ]),
+      ],
       server_identity: createServerIdentity({
         startedAt: new Date().toISOString(),
       }),