fix: make OPFS finalization and public cache repair failure-atomic

STO-RR-01. finalizePut re-acquired the origin mutation lease it was already holding. A Web Lock is not reentrant, so an ordinary PUT stopped for good at FINALIZE; it now calls the locked cleanup directly. A strict non-reentrant fake lease manager pins one acquire and one release per finalization. The adapter no longer reports a failed finalization as a plain write success either: the journal row stays COMMITTED for reconciliation, but the caller is told the write did not settle. STO-RR-02. A failure raised while serving a validated request now carries that request's kind. Defaulting every catch to CAPABILITIES made the client's own expected-kind check reject genuine quota, integrity and abort failures as protocol breaches and report them as UNSUPPORTED. Only an envelope the runtime could not read still answers at protocol level. STO-RR-03. The worker client decodes a response instead of adopting it: exact own-data descriptors, the negotiated protocol version, the exact awaited kind, a code inside the closed BrowserDataFailure set and a boolean retryable. An accessor, a proxy trap, an inherited or extra field and an unknown code all close the call as UNSUPPORTED rather than leaving it to time out. STO-RR-04. A marker read that fails transiently is unknown, not damaged, so it no longer deletes the candidate that may be serving traffic. Only a confirmed corrupt or missing marker enters the repair path. STO-RR-05. Staging never deletes a candidate it did not create. A repair replaces exact entries in place, so a failed fetch leaves every healthy asset and the active release usable; a candidate this call created is still removed on failure. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-14 14:00:41 +09:00
parent ca210d3bc5
commit 6a8281a941
8 changed files with 785 additions and 76 deletions
@@ -764,3 +764,373 @@ describe("OPFS worker client lifecycle", () => {
    });
  });
 });
+
+/**
+ * STO-RR-01. A Web Lock is not reentrant. Any path that re-acquires the origin
+ * mutation lease while already holding it stops making progress forever, and a
+ * lock the runtime waits on cannot be observed by a fake that hands out an
+ * unlimited number of leases.
+ */
+function strictNonReentrantLeases(
+  counters: { acquires: number; releases: number },
+): OpfsMutationLeaseManager {
+  let held = false;
+  return {
+    async acquire() {
+      if (held) {
+        // A second holder waits for the first to release. Nothing here ever
+        // does, which is exactly what a deadlock looks like.
+        return await new Promise<never>(() => {});
+      }
+      held = true;
+      counters.acquires += 1;
+      let released = false;
+      return {
+        release() {
+          if (released) return;
+          released = true;
+          held = false;
+          counters.releases += 1;
+        },
+      };
+    },
+  };
+}
+
+function withTimeout<Value>(
+  operation: Promise<Value>,
+  label: string,
+  ms = 200,
+): Promise<Value> {
+  return Promise.race([
+    operation,
+    new Promise<never>((_resolve, reject) => {
+      setTimeout(() => reject(new Error(`${label} did not settle`)), ms);
+    }),
+  ]);
+}
+
+describe("STO-RR-01 OPFS finalization under a non-reentrant lock", () => {
+  async function completedPut(
+    runtime: ReturnType<typeof createOpfsWorkerRuntime>,
+    transactionId: string,
+  ): Promise<OpfsPreparedObject> {
+    expect(
+      await runtime.handleRequest(
+        beginRequest(`request_begin_${transactionId}`, transactionId, scopeA),
+      ),
+    ).toMatchObject({ ok: true });
+    expect(
+      await runtime.handleRequest({
+        requestId: `request_append_${transactionId}`,
+        protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
+        kind: "APPEND_CHUNK",
+        scope: scopeA,
+        transactionId,
+        sequence: 0,
+        bytes: new Uint8Array([9]).buffer,
+      }),
+    ).toMatchObject({ ok: true });
+    const finished = await runtime.handleRequest({
+      requestId: `request_finish_${transactionId}`,
+      protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
+      kind: "FINISH_PUT",
+      scope: scopeA,
+      transactionId,
+    });
+    expect(finished).toMatchObject({ ok: true });
+    return preparedValue(finished);
+  }
+
+  it("finalizes a normal PUT with exactly one lock acquisition", async () => {
+    const root = new MemoryDirectory();
+    const counters = { acquires: 0, releases: 0 };
+    const runtime = createOpfsWorkerRuntime({
+      root: root as unknown as FileSystemDirectoryHandle,
+      crypto: globalThis.crypto,
+      policy: runtimePolicy,
+      leaseManager: strictNonReentrantLeases(counters),
+      dedicatedWorker: true,
+      supportsSynchronousAccessHandles: false,
+    });
+    const transactionId = "transaction_final_0001";
+    const prepared = await completedPut(runtime, transactionId);
+    const before = counters.acquires;
+
+    const finalized = await withTimeout(
+      runtime.handleRequest({
+        requestId: "request_finalize_0001",
+        protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
+        kind: "FINALIZE_PUT",
+        transactionId,
+        preparedObject: prepared,
+      }),
+      "FINALIZE_PUT",
+    );
+
+    expect(finalized).toMatchObject({ ok: true });
+    expect(counters.acquires - before).toBe(1);
+    expect(counters.acquires).toBe(counters.releases);
+    expect(
+      root.has([
+        "authorities",
+        scopeA.authorityToken,
+        scopeA.namespaceToken,
+        scopeA.partitionToken,
+        "staging",
+        transactionId,
+      ]),
+    ).toBe(false);
+  });
+
+  it("leaves the lock free for the next mutation after a finalized PUT", async () => {
+    const root = new MemoryDirectory();
+    const counters = { acquires: 0, releases: 0 };
+    const runtime = createOpfsWorkerRuntime({
+      root: root as unknown as FileSystemDirectoryHandle,
+      crypto: globalThis.crypto,
+      policy: runtimePolicy,
+      leaseManager: strictNonReentrantLeases(counters),
+      dedicatedWorker: true,
+      supportsSynchronousAccessHandles: false,
+    });
+    const first = "transaction_final_0002";
+    const prepared = await completedPut(runtime, first);
+    await withTimeout(
+      runtime.handleRequest({
+        requestId: "request_finalize_0002",
+        protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
+        kind: "FINALIZE_PUT",
+        transactionId: first,
+        preparedObject: prepared,
+      }),
+      "first FINALIZE_PUT",
+    );
+
+    const second = "transaction_final_0003";
+    await expect(
+      withTimeout(completedPut(runtime, second), "second PUT"),
+    ).resolves.toMatchObject({ descriptor: { objectId: "object_12345678" } });
+    expect(counters.acquires).toBe(counters.releases);
+  });
+});
+
+/**
+ * STO-RR-02. A failure raised while serving a validated request must answer
+ * that request. Defaulting the response kind to `CAPABILITIES` made the client's
+ * own expected-kind check reject it as a protocol breach, so a quota or
+ * integrity failure reached the caller as `UNSUPPORTED`.
+ */
+describe("STO-RR-02 worker failure responses echo the request kind", () => {
+  const failingRoot = {
+    async getDirectoryHandle(): Promise<FileSystemDirectoryHandle> {
+      throw new DOMException("Out of room", "QuotaExceededError");
+    },
+    async getFileHandle(): Promise<FileSystemFileHandle> {
+      throw new DOMException("Out of room", "QuotaExceededError");
+    },
+    async removeEntry(): Promise<void> {
+      throw new DOMException("Out of room", "QuotaExceededError");
+    },
+    async *entries(): AsyncIterableIterator<never> {},
+  } as unknown as FileSystemDirectoryHandle;
+
+  it("keeps the validated kind on every failure path", async () => {
+    const counters = { acquires: 0, releases: 0 };
+    const runtime = createOpfsWorkerRuntime({
+      root: failingRoot,
+      crypto: globalThis.crypto,
+      policy: runtimePolicy,
+      leaseManager: strictNonReentrantLeases(counters),
+      dedicatedWorker: true,
+      supportsSynchronousAccessHandles: false,
+    });
+
+    const requests: readonly OpfsWorkerRequest[] = [
+      beginRequest("request_kind_begin", "transaction_kind_0001", scopeA),
+      {
+        requestId: "request_kind_remove",
+        protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
+        kind: "REMOVE_OBJECT",
+        scope: scopeA,
+        objectId: "object_12345678",
+        generation: 1,
+      },
+      {
+        requestId: "request_kind_cleanup",
+        protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
+        kind: "CLEANUP_TRANSACTION",
+        scope: scopeA,
+        transactionId: "transaction_kind_0001",
+      },
+      {
+        requestId: "request_kind_orphans",
+        protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
+        kind: "LIST_ORPHAN_CANDIDATES",
+        scope: scopeA,
+        olderThanEpochMs: 1,
+        maxEntries: 1,
+      },
+    ];
+
+    for (const request of requests) {
+      const response = await runtime.handleRequest(request);
+      expect(response).toMatchObject({
+        ok: false,
+        kind: request.kind,
+        requestId: request.requestId,
+        protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
+      });
+    }
+  });
+
+  it("still reports a protocol-level failure for an unreadable envelope", async () => {
+    const counters = { acquires: 0, releases: 0 };
+    const runtime = createOpfsWorkerRuntime({
+      root: failingRoot,
+      crypto: globalThis.crypto,
+      policy: runtimePolicy,
+      leaseManager: strictNonReentrantLeases(counters),
+      dedicatedWorker: true,
+      supportsSynchronousAccessHandles: false,
+    });
+
+    expect(
+      await runtime.handleRequest({
+        requestId: "request_kind_broken",
+        protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
+        kind: "NOT_A_KIND",
+      }),
+    ).toMatchObject({ ok: false, kind: "CAPABILITIES" });
+  });
+});
+
+/**
+ * STO-RR-03. The client decoder is the trust boundary for anything a worker
+ * says. A `code` that is merely a string lets an arbitrary value escape the
+ * closed `BrowserDataFailure` taxonomy into application code.
+ */
+describe("STO-RR-03 worker responses are decoded against closed sets", () => {
+  function respondingWorker(
+    reply: (request: OpfsWorkerRequest) => unknown,
+  ): OpfsWorkerLike {
+    const listeners = new Set<(event: MessageEvent<unknown>) => void>();
+    return {
+      postMessage(message: unknown) {
+        const response = reply(message as OpfsWorkerRequest);
+        queueMicrotask(() => {
+          for (const listener of listeners) {
+            listener({ data: response } as MessageEvent<unknown>);
+          }
+        });
+      },
+      addEventListener(_type: "message", listener: (event: MessageEvent<unknown>) => void) {
+        listeners.add(listener);
+      },
+      removeEventListener(_type: "message", listener: (event: MessageEvent<unknown>) => void) {
+        listeners.delete(listener);
+      },
+    } as unknown as OpfsWorkerLike;
+  }
+
+  const hostileReplies: readonly (readonly [string, (request: OpfsWorkerRequest) => unknown])[] = [
+    [
+      "unknown failure code",
+      (request) => ({
+        requestId: request.requestId,
+        protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
+        kind: request.kind,
+        ok: false,
+        failure: { code: "EVIL", retryable: false },
+      }),
+    ],
+    [
+      "unknown request kind",
+      (request) => ({
+        requestId: request.requestId,
+        protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
+        kind: "NOT_A_KIND",
+        ok: false,
+        failure: { code: "UNAVAILABLE", retryable: false },
+      }),
+    ],
+    [
+      "non-boolean retryable",
+      (request) => ({
+        requestId: request.requestId,
+        protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
+        kind: request.kind,
+        ok: false,
+        failure: { code: "UNAVAILABLE", retryable: "yes" },
+      }),
+    ],
+    [
+      "inherited failure fields",
+      (request) => ({
+        requestId: request.requestId,
+        protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
+        kind: request.kind,
+        ok: false,
+        failure: Object.create({ code: "UNAVAILABLE", retryable: false }) as object,
+      }),
+    ],
+    [
+      "throwing getter",
+      (request) => {
+        const response: Record<string, unknown> = {
+          requestId: request.requestId,
+          protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
+          ok: false,
+          failure: { code: "UNAVAILABLE", retryable: false },
+        };
+        Object.defineProperty(response, "kind", {
+          enumerable: true,
+          get: () => {
+            throw new TypeError("hostile getter");
+          },
+        });
+        return response;
+      },
+    ],
+    [
+      "extra own field",
+      (request) => ({
+        requestId: request.requestId,
+        protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
+        kind: request.kind,
+        ok: false,
+        failure: { code: "UNAVAILABLE", retryable: false, injected: 1 },
+      }),
+    ],
+  ];
+
+  for (const [label, reply] of hostileReplies) {
+    it(`closes a ${label} as UNSUPPORTED without rejecting`, async () => {
+      const gateway = createOpfsWorkerGateway({
+        worker: respondingWorker(reply),
+        policy: runtimePolicy,
+        createRequestId: () => `request_hostile_${label.replace(/\W/gu, "")}`,
+      });
+      const result = await withTimeout(gateway.capabilities(), label);
+      expect(result.ok).toBe(false);
+      expect(result.ok ? null : result.error.code).toBe("UNSUPPORTED");
+    });
+  }
+
+  it("still admits a well-formed closed failure", async () => {
+    const gateway = createOpfsWorkerGateway({
+      worker: respondingWorker((request) => ({
+        requestId: request.requestId,
+        protocolVersion: OPFS_WORKER_PROTOCOL_VERSION,
+        kind: request.kind,
+        ok: false,
+        failure: { code: "QUOTA_EXCEEDED", retryable: true },
+      })),
+      policy: runtimePolicy,
+      createRequestId: () => "request_wellformed_1234",
+    });
+    const result = await withTimeout(gateway.capabilities(), "well-formed");
+    expect(result.ok).toBe(false);
+    expect(result.ok ? null : result.error.code).toBe("QUOTA_EXCEEDED");
+  });
+});