fix(sqlite): preserve snapshot admission failure semantics

Refuse oversized database and WAL inputs before acquisition with exact observed bytes and export guidance. Keep initial path failures separate from file-set changes and retain cleanup and partial observations on late growth.

Refs #4208, #4188, #4141, #4127

Co-authored-by: hima <1ep23ic023@eastpoint.ac.in>
Co-authored-by: Royce <roycelam@umich.edu>

src/sqlite/SqliteDatabaseFailures.ts

@@ -79,7 +79,7 @@ export const sqliteDatabaseFailure = (
     return new AnalysisInputError(operation, { cause }, [
       {
         path: ["path"],
-        reason: cause.reason === "limit" ? "out_of_range" : "invalid_format",
+        reason: "invalid_format",
         message: cause.message,
       },
     ]);
@@ -110,7 +110,12 @@ export const sqliteDatabaseFailure = (
             "The selected SQLite database is held open by another process without read sharing. Close that application or inspect a copy, then retry.",
         },
       );
-    if (cause.code === "ENOENT" || cause.code === "ENOTDIR")
+    if (
+      cause.code === "ENOENT" ||
+      cause.code === "ENOTDIR" ||
+      cause.code === "ELOOP" ||
+      cause.code === "ENAMETOOLONG"
+    )
       return new AnalysisInputError(operation, { cause }, [
         {
           path: ["path"],

src/sqlite/SqliteDatabaseSnapshot.ts

@@ -3,7 +3,12 @@ import { constants, type BigIntStats } from "node:fs";
 import { join } from "node:path";
 import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
 import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
-import { AnalysisInputError } from "../domain/analysisErrorCore.js";
+import {
+  AnalysisCapabilityUnavailableError,
+  AnalysisInputError,
+  AnalysisResourceConstraintError,
+} from "../domain/analysisErrorCore.js";
+import { SQLITE_PROVIDER_IDENTITY } from "../domain/sqlite/sqliteDatabase.js";
 import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
 import {
   readStableArtifact,
@@ -15,6 +20,49 @@ const fileSystem: StableArtifactFileSystem = {
   lstat: (path) => lstat(path, { bigint: true }),
   open,
 };
+
+/** Probe a generated sibling only after the caller-selected database is observed. */
+const optionalSidecarStat = async (
+  path: string,
+  databasePath: string,
+  observedDatabase: BigIntStats,
+  member: "WAL" | "rollback journal",
+  selectedFileSystem: StableArtifactFileSystem,
+): Promise<BigIntStats | null> => {
+  let observedSidecar: BigIntStats | null;
+  try {
+    observedSidecar = await optionalStat(path, selectedFileSystem);
+  } catch (cause: unknown) {
+    if (
+      cause instanceof Error &&
+      "code" in cause &&
+      cause.code === "ENAMETOOLONG"
+    ) {
+      const currentDatabase = await duringAcquisition(databasePath, () =>
+        optionalStat(databasePath, selectedFileSystem),
+      );
+      if (!sameState(observedDatabase, currentDatabase))
+        throw new ArtifactReaderFailure(
+          "integrity",
+          `SQLite snapshot file set changed before sidecar inspection: ${databasePath}`,
+          { cause },
+        );
+      const remedy =
+        "Use the application's supported consistent offline export or copy workflow to move the complete known database file set to a shorter path. Do not rename a live database or omit its WAL or journal.";
+      throw new AnalysisCapabilityUnavailableError(
+        SQLITE_PROVIDER_IDENTITY.id,
+        "inspect_sqlite_database",
+        `Cannot safely address the derived SQLite ${member} path (${String(cause.code)}): ${path}`,
+        {
+          cause,
+          userMessage: `The derived SQLite ${member} path is too long to inspect safely (ENAMETOOLONG). ${remedy}`,
+        },
+      );
+    }
+    throw cause;
+  }
+  return observedSidecar;
+};
 const optionalStat = async (
   path: string,
   selectedFileSystem: StableArtifactFileSystem,
@@ -50,13 +98,35 @@ const duringAcquisition = async <T>(
     if (
       cause instanceof Error &&
       "code" in cause &&
-      ["ENOENT", "ENOTDIR", "ELOOP"].includes(String(cause.code))
+      ["ENOENT", "ENOTDIR", "ELOOP", "ENAMETOOLONG"].includes(
+        String(cause.code),
+      )
     )
       throw new ArtifactReaderFailure(
         "integrity",
         `SQLite snapshot file set changed during acquisition: ${path}`,
         { cause },
       );
+    if (cause instanceof ArtifactReaderFailure && cause.reason === "limit") {
+      const changed = new ArtifactReaderFailure(
+        "integrity",
+        `SQLite snapshot file set exceeded its observed size during acquisition: ${path}`,
+        {
+          cause,
+          ...(cause.partialObservation === undefined
+            ? {}
+            : { partialObservation: cause.partialObservation }),
+        },
+        cause.details,
+      );
+      if (cause.cleanup !== undefined)
+        throw ArtifactReaderFailure.withCleanup(
+          changed,
+          cause.cleanup,
+          cause.partialObservation,
+        );
+      throw changed;
+    }
     throw cause;
   }
 };
@@ -186,30 +256,50 @@ export const captureSqliteDatabaseSnapshot = async (
   selectedFileSystem: StableArtifactFileSystem = fileSystem,
 ) => {
   signal?.throwIfAborted();
-  const paths = [path, `${path}-wal`, `${path}-journal`];
-  const before = await Promise.all(
-    paths.map((path) => optionalStat(path, selectedFileSystem)),
-  );
-  const database = before[0];
-  const wal = before[1];
-  if (database === undefined || wal === undefined || before[2] === undefined)
-    throw new Error("Incomplete database file-set observation");
+  const walPath = `${path}-wal`;
+  const journalPath = `${path}-journal`;
+  const paths = [path, walPath, journalPath] as const;
+  const database = await optionalStat(path, selectedFileSystem);
   if (database === null) throw missingDatabase(path);
-  if (before[2] !== null)
+  const wal = await optionalSidecarStat(
+    walPath,
+    path,
+    database,
+    "WAL",
+    selectedFileSystem,
+  );
+  const journal = await optionalSidecarStat(
+    journalPath,
+    path,
+    database,
+    "rollback journal",
+    selectedFileSystem,
+  );
+  const before = [database, wal, journal] as const;
+  const selectedSize = database.size + (wal?.size ?? 0n);
+  if (selectedSize > BigInt(SQLITE_DATABASE_LIMITS.inputBytes))
+    throw new AnalysisResourceConstraintError(
+      "inspect_sqlite_database",
+      "file-size",
+      `Selected SQLite database and WAL total ${selectedSize.toString()} bytes, exceeding the combined ${String(SQLITE_DATABASE_LIMITS.inputBytes)}-byte offline snapshot budget: ${path}`,
+      {
+        sqlite_snapshot_input_bytes: SQLITE_DATABASE_LIMITS.inputBytes,
+        observed_sqlite_snapshot_input_bytes: selectedSize.toString(),
+      },
+      {
+        remediationAction:
+          "Use the application's supported export workflow to create a consistent, smaller offline SQLite snapshot containing only the relevant data, then inspect that snapshot. REA will not truncate or modify the selected source.",
+      },
+    );
+  if (journal !== null)
     await verifyInactiveJournal(
       `${path}-journal`,
-      before[2],
+      journal,
       selectedFileSystem,
       resourceScope,
       "initial",
       signal,
     );
-  const selectedSize = database.size + (wal?.size ?? 0n);
-  if (selectedSize > BigInt(SQLITE_DATABASE_LIMITS.inputBytes))
-    throw new ArtifactReaderFailure(
-      "limit",
-      `Selected SQLite database and WAL exceed the combined ${String(SQLITE_DATABASE_LIMITS.inputBytes)}-byte snapshot budget: ${path}`,
-    );
   const snapshotPath = join(root, "database.snapshot");
   const captured = await readObservedArtifact(
     path,
@@ -252,10 +342,10 @@ export const captureSqliteDatabaseSnapshot = async (
   }
   // Identity alone does not establish an inactive journal when timestamps are
   // coarse. Re-read the header after copying, using the same validity owner.
-  if (before[2] !== null)
+  if (journal !== null)
     await verifyInactiveJournal(
       `${path}-journal`,
-      before[2],
+      journal,
       selectedFileSystem,
       resourceScope,
       "after-copy",

src/sqlite/SqliteDatabaseSnapshotLimits.test.ts

@@ -0,0 +1,194 @@
+import { lstat, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { expect, it } from "vitest";
+
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import type { StableArtifactFileSystem } from "../artifacts/readStableArtifact.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import type { AnalysisPartialObservation } from "../domain/analysisErrorBase.js";
+import { captureSqliteDatabaseSnapshot } from "./SqliteDatabaseSnapshot.js";
+import { SQLITE_DATABASE_LIMITS } from "./SqliteDatabaseLimits.js";
+import { sqliteDatabaseFailure } from "./SqliteDatabaseFailures.js";
+
+it("reports filesystem sizes above the safe-integer range exactly before opening files", async () => {
+  const databaseBytes = BigInt(Number.MAX_SAFE_INTEGER) + 1n;
+  const walBytes = 17n;
+  const workspace = await mkdtemp(join(tmpdir(), "rea-sqlite-budget-"));
+  const databasePath = join(workspace, "selected.db");
+  const walPath = `${databasePath}-wal`;
+  const journalPath = `${databasePath}-journal`;
+  const privateRoot = join(workspace, "private");
+  await writeFile(databasePath, "tiny fixture");
+  const stat = await lstat(databasePath, { bigint: true });
+  const open = async (): Promise<never> => {
+    throw new Error("An over-budget source must be refused before open");
+  };
+  const fileSystem: StableArtifactFileSystem = {
+    lstat: async (path) => {
+      if (path === journalPath)
+        throw Object.assign(new Error("journal absent"), { code: "ENOENT" });
+      const size =
+        path === databasePath
+          ? databaseBytes
+          : path === walPath
+            ? walBytes
+            : stat.size;
+      return Object.assign(
+        Object.create(Object.getPrototypeOf(stat)) as typeof stat,
+        stat,
+        { size },
+      );
+    },
+    open,
+  };
+  const resourceScope = new ArtifactResourceScope();
+
+  try {
+    const failure = await captureSqliteDatabaseSnapshot(
+      databasePath,
+      privateRoot,
+      resourceScope,
+      undefined,
+      fileSystem,
+    ).then(
+      () => {
+        throw new Error("Expected the oversized snapshot to be refused");
+      },
+      (cause: unknown) => cause,
+    );
+    const projected = projectAnalysisError(
+      sqliteDatabaseFailure(failure, databasePath, "artifact-read"),
+    );
+    expect(failure).toMatchObject({
+      _tag: "AnalysisResourceConstraintError",
+      operation: "inspect_sqlite_database",
+      resource: "file-size",
+      reportedLimits: {
+        sqlite_snapshot_input_bytes: SQLITE_DATABASE_LIMITS.inputBytes,
+        observed_sqlite_snapshot_input_bytes: (
+          databaseBytes + walBytes
+        ).toString(),
+      },
+      remediationAction: expect.stringContaining(
+        "smaller offline SQLite snapshot",
+      ),
+    });
+    expect(projected).toMatchObject({
+      code: "resource_constraint",
+      category: "resource_constraint",
+      retryable: false,
+      details: {
+        reported_limits: {
+          sqlite_snapshot_input_bytes: SQLITE_DATABASE_LIMITS.inputBytes,
+          observed_sqlite_snapshot_input_bytes: (
+            databaseBytes + walBytes
+          ).toString(),
+        },
+      },
+      remediation: {
+        action: expect.stringContaining("supported export workflow"),
+      },
+    });
+    await expect(readdir(privateRoot)).rejects.toMatchObject({
+      code: "ENOENT",
+    });
+  } finally {
+    await resourceScope.close();
+    await rm(workspace, { force: true, recursive: true });
+  }
+});
+
+it.each([
+  { label: "incomplete cleanup", retainCleanup: true },
+  { label: "partial observation without cleanup", retainCleanup: false },
+])(
+  "preserves $label when a late read-limit failure becomes changed evidence",
+  async ({ retainCleanup }) => {
+    const workspace = await mkdtemp(join(tmpdir(), "rea-sqlite-read-cleanup-"));
+    const databasePath = join(workspace, "selected.db");
+    await writeFile(databasePath, "tiny fixture");
+    const stat = await lstat(databasePath, { bigint: true });
+    const cleanup = {
+      reason: "fixture file-handle close failed",
+      resources: [databasePath],
+    };
+    const partialObservation = {
+      operation: "address_to_file_offset",
+      address: "0x1000",
+      provider_file_offset: 16,
+      provider_source_path: null,
+      provider_image_header_hex: null,
+      original_file_offset: {
+        available: false,
+        reason: "fixture observation",
+      },
+    } satisfies AnalysisPartialObservation;
+    const details = {
+      logicalPath: "selected.db",
+      declaredSha256: null,
+      calculatedSha256: null,
+      unpacked: false,
+    };
+    const primary = new ArtifactReaderFailure(
+      "limit",
+      "Selected artifact grew beyond its byte limit",
+      { partialObservation },
+      details,
+    );
+    const limitFailure = retainCleanup
+      ? ArtifactReaderFailure.withCleanup(primary, cleanup)
+      : primary;
+    const fileSystem: StableArtifactFileSystem = {
+      lstat: async (path) => {
+        if (path === `${databasePath}-journal`)
+          throw Object.assign(new Error("journal absent"), { code: "ENOENT" });
+        return stat;
+      },
+      open: async () => {
+        throw limitFailure;
+      },
+    };
+    const resourceScope = new ArtifactResourceScope();
+
+    try {
+      const failure = await captureSqliteDatabaseSnapshot(
+        databasePath,
+        join(workspace, "private"),
+        resourceScope,
+        undefined,
+        fileSystem,
+      ).then(
+        () => {
+          throw new Error("Expected the changed snapshot to be rejected");
+        },
+        (cause: unknown) => cause,
+      );
+      expect(failure).toMatchObject({ reason: "integrity" });
+      if (retainCleanup)
+        expect(failure).toMatchObject({
+          cleanup,
+          cause: expect.any(ArtifactReaderFailure),
+        });
+      expect(failure).toMatchObject({ partialObservation, details });
+      const projectedFailure = sqliteDatabaseFailure(
+        failure,
+        databasePath,
+        "artifact-read",
+      );
+      if (retainCleanup) {
+        expect(projectedFailure).toBeInstanceOf(ProviderCleanupError);
+        expect(projectedFailure).toMatchObject({
+          cleanupIncomplete: true,
+          cleanupResources: cleanup.resources,
+        });
+      }
+    } finally {
+      await resourceScope.close();
+      await rm(workspace, { force: true, recursive: true });
+    }
+  },
+);