@remnic/core 9.69.33 → 9.69.35

package/src/storage/cas-revision-store.test.ts

@@ -0,0 +1,459 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { mkdir, mkdtemp, readFile, readdir, rm, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { CasRevisionStore } from "./cas-revision-store.js";
+
+async function withStore(run: (store: CasRevisionStore, root: string) => Promise<void>): Promise<void> {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-cas-store-"));
+  try {
+    await run(new CasRevisionStore(root), root);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+function shardPathFor(root: string, target: string): string {
+  const relative = path.relative(root, target).split(path.sep).join("/");
+  const hash = createHash("sha256").update(relative).digest("hex");
+  return path.join(root, ".offline-sync", "cas-revisions", `${hash}.json`);
+}
+
+test("a second reservation refuses while a pending transaction stands; abort restores the standing token (#2813 P1 C)", async () => {
+  await withStore(async (store, root) => {
+    const target = path.join(root, "memories", "fact-a.md");
+
+    const a = await store.beginRevisionTransaction(target);
+    assert.equal((await store.readRevisionStatus(target)).status, "unavailable", "pending is never ownership");
+    await a.commit();
+    assert.deepEqual(await store.readRevisionStatus(target), {
+      status: "present",
+      revision: a.pendingRevision,
+    });
+
+    // Writer B reserves while the shard holds a standing committed token.
+    const b = await store.beginRevisionTransaction(target);
+    assert.ok(b.pendingRevision > a.pendingRevision, "the reserved token exceeds the standing token");
+    // Writer C cannot reserve while B's PENDING marker stands — concurrent
+    // ownership is impossible: the ambiguity refuses the new transaction.
+    await assert.rejects(store.beginRevisionTransaction(target), /pending finalization/);
+    assert.equal(
+      (await store.readRevisionStatus(target)).status,
+      "unavailable",
+      "readers see recovery-needed, never B's pending token and never absence",
+    );
+
+    // B's memory write failed: the abort restores A's standing token.
+    await b.abort();
+    assert.deepEqual(await store.readRevisionStatus(target), {
+      status: "present",
+      revision: a.pendingRevision,
+    });
+
+    // The next reservation still exceeds the standing committed token.
+    const c = await store.beginRevisionTransaction(target);
+    assert.ok(c.pendingRevision > a.pendingRevision);
+    await c.commit();
+    assert.deepEqual(await store.readRevisionStatus(target), {
+      status: "present",
+      revision: c.pendingRevision,
+    });
+    assert.notEqual(a.pendingRevision, c.pendingRevision, "two owned commits never share a receipt");
+  });
+});
+
+test("reconcilePendingRevision publishes or discards with the known write outcome (#2813 P1 C)", async () => {
+  await withStore(async (store, root) => {
+    const target = path.join(root, "memories", "fact-b.md");
+    assert.equal(await store.reconcilePendingRevision(target, true), "absent", "no shard is a no-op");
+
+    const a = await store.beginRevisionTransaction(target);
+    await a.commit();
+    assert.equal(await store.reconcilePendingRevision(target, true), "committed", "an already-committed shard is untouched");
+
+    // A crashed transaction whose memory write LANDED: the pending token
+    // publishes as the standing receipt.
+    const b = await store.beginRevisionTransaction(target);
+    assert.equal(await store.reconcilePendingRevision(target, true), "reconciled");
+    assert.deepEqual(await store.readRevisionStatus(target), {
+      status: "present",
+      revision: b.pendingRevision,
+    });
+
+    // A crashed transaction whose memory write did NOT land: the previous
+    // standing token is restored.
+    const c = await store.beginRevisionTransaction(target);
+    assert.equal(await store.reconcilePendingRevision(target, false), "reconciled");
+    assert.deepEqual(await store.readRevisionStatus(target), {
+      status: "present",
+      revision: b.pendingRevision,
+    });
+
+    // From a fresh target (no standing token), a discarded reservation
+    // returns the shard to genuine absence.
+    const fresh = path.join(root, "memories", "fact-c.md");
+    const d = await store.beginRevisionTransaction(fresh);
+    assert.equal(await store.reconcilePendingRevision(fresh, false), "reconciled");
+    assert.equal((await store.readRevisionStatus(fresh)).status, "absent");
+    assert.equal(
+      await readFile(path.join(root, "memories", "fact-c.md"), "utf8").then(
+        () => true,
+        () => false,
+      ),
+      false,
+      "sanity: the store never touches the memory file itself",
+    );
+    assert.ok(d.pendingRevision.length > 0);
+  });
+});
+
+test("a pre-two-phase shard without state reads as committed and mints forward (#2813 P1 C)", async () => {
+  await withStore(async (store, root) => {
+    const target = path.join(root, "memories", "fact-legacy.md");
+    const relative = path.relative(root, target).split(path.sep).join("/");
+    const legacyToken = "2026-08-01T00:00:00.000Z";
+    await mkdir(path.dirname(shardPathFor(root, target)), { recursive: true });
+    await writeFile(
+      shardPathFor(root, target),
+      `${JSON.stringify({ version: 1, path: relative, revision: legacyToken })}\n`,
+      "utf8",
+    );
+    assert.deepEqual(await store.readRevisionStatus(target), { status: "present", revision: legacyToken });
+
+    const next = await store.beginRevisionTransaction(target);
+    assert.ok(next.pendingRevision > legacyToken);
+    await next.commit();
+    const shard = JSON.parse(await readFile(shardPathFor(root, target), "utf8")) as {
+      state?: string;
+      revision?: string;
+    };
+    assert.equal(shard.state, "committed");
+    assert.equal(shard.revision, next.pendingRevision);
+  });
+});
+
+test("a symlinked cas-revisions directory is rejected at the store boundary (#2813 P1 A)", async () => {
+  await withStore(async (store, root) => {
+    const target = path.join(root, "memories", "fact-guard.md");
+    const a = await store.beginRevisionTransaction(target);
+    await a.commit();
+
+    const escapeRoot = await mkdtemp(path.join(os.tmpdir(), "remnic-cas-store-escape-"));
+    try {
+      const shardDir = path.join(root, ".offline-sync", "cas-revisions");
+      await rm(shardDir, { recursive: true, force: true });
+      await symlink(escapeRoot, shardDir);
+
+      const status = await store.readRevisionStatus(target);
+      assert.equal(status.status, "unavailable", "the symlinked sidecar is never read through");
+      await assert.rejects(store.beginRevisionTransaction(target));
+      await assert.rejects(store.reconcilePendingRevision(target, true));
+      assert.deepEqual(await readdir(escapeRoot), [], "no lock, shard, or temp file escaped the root");
+    } finally {
+      await rm(escapeRoot, { recursive: true, force: true });
+    }
+  });
+});
+
+test("a corrupt state-bearing shard is unavailability, never absence (#2813 P1 C)", async () => {
+  await withStore(async (store, root) => {
+    const target = path.join(root, "memories", "fact-corrupt.md");
+    await mkdir(path.dirname(shardPathFor(root, target)), { recursive: true });
+    await writeFile(
+      shardPathFor(root, target),
+      `${JSON.stringify({ version: 1, path: "x", revision: "2026-08-01T00:00:00.000Z", state: "bogus" })}\n`,
+      "utf8",
+    );
+    const status = await store.readRevisionStatus(target);
+    assert.equal(status.status, "unavailable");
+    await assert.rejects(store.beginRevisionTransaction(target), /unreadable/);
+  });
+});
+
+test("recoverPendingRevision aborts a crashed reservation whose write never landed (#2807)", async () => {
+  await withStore(async (store, root) => {
+    const target = path.join(root, "memories", "fact-restart-abort.md");
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, "standing bytes", "utf8");
+
+    const a = await store.beginRevisionTransaction(target);
+    await a.commit();
+    // Crash between reserve and the durable write: the file is unchanged,
+    // so the baseline fingerprint still matches.
+    const b = await store.beginRevisionTransaction(target);
+
+    assert.equal(await store.recoverPendingRevision(target), "aborted");
+    assert.deepEqual(await store.readRevisionStatus(target), {
+      status: "present",
+      revision: a.pendingRevision,
+    });
+    assert.equal(await store.recoverPendingRevision(target), "committed", "idempotent once reconciled");
+
+    // Same crash from a fresh target (no standing receipt, absent file):
+    // the aborted reservation returns the shard to genuine absence.
+    const fresh = path.join(root, "memories", "fact-restart-fresh.md");
+    const f = await store.beginRevisionTransaction(fresh);
+    assert.equal(await store.recoverPendingRevision(fresh), "aborted");
+    assert.equal((await store.readRevisionStatus(fresh)).status, "absent");
+    assert.ok(f.pendingRevision.length > 0);
+  });
+});
+
+test("an evidenced gated recovery defers a reserve-only marker to the path-locked write path (#2807)", async () => {
+  await withStore(async (store, root) => {
+    const target = path.join(root, "memories", "fact-restart-gate.md");
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, "standing bytes", "utf8");
+    const a = await store.beginRevisionTransaction(target);
+    await a.commit();
+
+    // A reserve-only marker is indistinguishable from a LIVE transaction
+    // between reserve and write, so an unlocked read must not abort it.
+    const b = await store.beginRevisionTransaction(target);
+    assert.equal(
+      await store.recoverPendingRevision(target, { onlyWithWriteEvidence: true }),
+      "reserved",
+    );
+    assert.equal((await store.readRevisionStatus(target)).status, "unavailable", "the marker still stands");
+    // The live transaction proceeds undisturbed and commits normally.
+    await writeFile(target, "landed bytes", "utf8");
+    await b.writeLanded();
+    await b.commit();
+    assert.deepEqual(await store.readRevisionStatus(target), {
+      status: "present",
+      revision: b.pendingRevision,
+      committedDigest: store.digestContent("landed bytes"),
+    });
+  });
+});
+
+test("recoverPendingRevision publishes a crashed reservation whose write landed (#2807)", async () => {
+  await withStore(async (store, root) => {
+    const target = path.join(root, "memories", "fact-restart-commit.md");
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, "old durable bytes", "utf8");
+    const a = await store.beginRevisionTransaction(target);
+    await a.commit();
+
+    const b = await store.beginRevisionTransaction(target);
+    await writeFile(target, "new durable bytes", "utf8");
+    await b.writeLanded();
+    // Crash between writeLanded and commit: the marker holds the evidence.
+
+    const shard = JSON.parse(await readFile(shardPathFor(root, target), "utf8")) as {
+      state?: string;
+      baselineDigest?: unknown;
+      expectedDigest?: unknown;
+    };
+    assert.equal(shard.state, "pending");
+    assert.match(String(shard.baselineDigest), /^[0-9a-f]{64}$/, "the reserve-time fingerprint is persisted");
+    assert.match(String(shard.expectedDigest), /^[0-9a-f]{64}$/, "the post-write fingerprint is persisted");
+    assert.equal(JSON.stringify(shard).includes("old durable bytes"), false, "no memory content is persisted");
+
+    assert.equal(await store.recoverPendingRevision(target), "committed");
+    assert.deepEqual(await store.readRevisionStatus(target), {
+      status: "present",
+      revision: b.pendingRevision,
+      committedDigest: store.digestContent("new durable bytes"),
+    });
+    assert.equal(await store.recoverPendingRevision(target), "committed", "idempotent");
+  });
+});
+
+test("recoverPendingRevision fails closed on an ambiguous durable change (#2807)", async () => {
+  await withStore(async (store, root) => {
+    const target = path.join(root, "memories", "fact-restart-ambiguous.md");
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, "old durable bytes", "utf8");
+    const a = await store.beginRevisionTransaction(target);
+    await a.commit();
+
+    const b = await store.beginRevisionTransaction(target);
+    await assert.rejects(store.beginRevisionTransaction(target), /pending finalization/, "new reservations refuse");
+    await b.writeLanded();
+    // After the crash the file changes again — neither the expected
+    // fingerprint nor the baseline can explain the current bytes.
+    await writeFile(target, "unexplained third state", "utf8");
+
+    await assert.rejects(store.recoverPendingRevision(target), /ambiguous[\s\S]{0,512}Refusing to guess/);
+    assert.equal((await store.readRevisionStatus(target)).status, "unavailable");
+    await assert.rejects(store.beginRevisionTransaction(target), /ambiguous/, "new reservations refuse");
+    assert.equal(
+      await store.reconcilePendingRevision(target, true),
+      "reconciled",
+      "the known-outcome path remains the operator's manual tool",
+    );
+  });
+});
+
+test("recoverPendingRevision never guesses on a legacy pending marker without evidence (#2807)", async () => {
+  await withStore(async (store, root) => {
+    const target = path.join(root, "memories", "fact-legacy-pending.md");
+    const relative = path.relative(root, target).split(path.sep).join("/");
+    await mkdir(path.dirname(shardPathFor(root, target)), { recursive: true });
+    await writeFile(
+      shardPathFor(root, target),
+      `${JSON.stringify({
+        version: 1,
+        path: relative,
+        revision: "2026-08-01T00:00:00.000Z",
+        state: "pending",
+        previous: "2026-07-31T00:00:00.000Z",
+      })}\n`,
+      "utf8",
+    );
+
+    await assert.rejects(store.recoverPendingRevision(target), /no crash evidence[\s\S]{0,512}Refusing to guess/);
+    assert.equal((await store.readRevisionStatus(target)).status, "unavailable");
+  });
+});
+test("beginRevisionTransaction with expectedContent persists expectedDigest in pending marker before memory write (P1 A)", async () => {
+  await withStore(async (store, root) => {
+    const target = path.join(root, "memories", "fact-p1a-prewrite.md");
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, "baseline content", "utf8");
+
+    // Establish standing receipt for baseline
+    const initial = await store.beginRevisionTransaction(target, "baseline content");
+    await initial.commit();
+
+    const expectedContent = "new expected content";
+    const txn = await store.beginRevisionTransaction(target, expectedContent);
+
+    // Inspect the shard before the memory write occurs:
+    const shard = JSON.parse(await readFile(shardPathFor(root, target), "utf8")) as {
+      state?: string;
+      baselineDigest?: string;
+      expectedDigest?: string;
+      writeLanded?: boolean;
+    };
+    assert.equal(shard.state, "pending");
+    assert.equal(shard.writeLanded, false, "new pending markers are not landed");
+    assert.ok(shard.baselineDigest, "baseline digest is persisted");
+    assert.equal(
+      shard.expectedDigest,
+      store.digestContent(expectedContent),
+      "expected digest is persisted before memory write",
+    );
+
+    // Case 1: Crash BEFORE memory write (file remains at baseline content):
+    assert.equal(await store.recoverPendingRevision(target), "aborted");
+    assert.equal((await store.readRevisionStatus(target)).status, "present");
+    assert.equal(
+      (await store.readRevisionStatus(target) as { revision: string }).revision,
+      initial.pendingRevision,
+      "aborted transaction restored standing receipt",
+    );
+
+    // Case 2: Fresh transaction, memory write lands, crash AFTER memory write:
+    const txn2 = await store.beginRevisionTransaction(target, expectedContent);
+    await writeFile(target, expectedContent, "utf8");
+    assert.equal(
+      await store.recoverPendingRevision(target, { onlyWithWriteEvidence: true }),
+      "reserved",
+      "pre-recorded expectedDigest is not unlocked write evidence",
+    );
+    assert.equal(await store.recoverPendingRevision(target), "committed");
+    assert.deepEqual(await store.readRevisionStatus(target), {
+      status: "present",
+      revision: txn2.pendingRevision,
+      committedDigest: store.digestContent(expectedContent),
+    });
+  });
+});
+
+test("writeLanded sets the landed marker and unlocked mismatch is ambiguous (#2813 P1)", async () => {
+  await withStore(async (store, root) => {
+    const target = path.join(root, "memories", "fact-write-landed-marker.md");
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, "old bytes", "utf8");
+    const standing = await store.beginRevisionTransaction(target, "old bytes");
+    await standing.commit();
+
+    const next = await store.beginRevisionTransaction(target, "new bytes");
+    await writeFile(target, "new bytes", "utf8");
+    assert.equal(
+      await store.recoverPendingRevision(target, { onlyWithWriteEvidence: true }),
+      "reserved",
+    );
+    await next.writeLanded();
+    const landedShard = JSON.parse(await readFile(shardPathFor(root, target), "utf8")) as {
+      writeLanded?: boolean;
+      expectedDigest?: string;
+    };
+    assert.equal(landedShard.writeLanded, true);
+    assert.equal(landedShard.expectedDigest, store.digestContent("new bytes"));
+    await writeFile(target, "third-party rewrite", "utf8");
+    await assert.rejects(
+      store.recoverPendingRevision(target, { onlyWithWriteEvidence: true }),
+      /ambiguous[\s\S]{0,512}Refusing to guess/,
+    );
+  });
+});
+
+test("legacy pending shards without writeLanded treat expectedDigest as already landed (#2813 P1)", async () => {
+  await withStore(async (store, root) => {
+    const target = path.join(root, "memories", "fact-legacy-landed.md");
+    const relative = path.relative(root, target).split(path.sep).join("/");
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, "legacy landed bytes", "utf8");
+    const expectedDigest = store.digestContent("legacy landed bytes");
+    await mkdir(path.dirname(shardPathFor(root, target)), { recursive: true });
+    await writeFile(
+      shardPathFor(root, target),
+      `${JSON.stringify({
+        version: 1,
+        path: relative,
+        revision: "2026-08-01T00:00:00.000Z",
+        state: "pending",
+        previous: "2026-07-31T00:00:00.000Z",
+        baselineDigest: store.digestContent("old bytes"),
+        expectedDigest,
+      })}\n`,
+      "utf8",
+    );
+
+    assert.equal(
+      await store.recoverPendingRevision(target, { onlyWithWriteEvidence: true }),
+      "committed",
+      "absent writeLanded plus expectedDigest is legacy landed evidence",
+    );
+    assert.deepEqual(await store.readRevisionStatus(target), {
+      status: "present",
+      revision: "2026-08-01T00:00:00.000Z",
+      committedDigest: expectedDigest,
+    });
+  });
+});
+
+test("legacy landed pending whose file no longer matches expectedDigest is ambiguous (#2813 P1)", async () => {
+  await withStore(async (store, root) => {
+    const target = path.join(root, "memories", "fact-legacy-mismatch.md");
+    const relative = path.relative(root, target).split(path.sep).join("/");
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, "third-party rewrite", "utf8");
+    await mkdir(path.dirname(shardPathFor(root, target)), { recursive: true });
+    await writeFile(
+      shardPathFor(root, target),
+      `${JSON.stringify({
+        version: 1,
+        path: relative,
+        revision: "2026-08-01T00:00:00.000Z",
+        state: "pending",
+        previous: "2026-07-31T00:00:00.000Z",
+        baselineDigest: store.digestContent("old bytes"),
+        expectedDigest: store.digestContent("expected landed bytes"),
+      })}\n`,
+      "utf8",
+    );
+
+    await assert.rejects(
+      store.recoverPendingRevision(target, { onlyWithWriteEvidence: true }),
+      /ambiguous[\s\S]{0,512}Refusing to guess/,
+    );
+    assert.equal((await store.readRevisionStatus(target)).status, "unavailable");
+  });
+});