@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/runtime/source-assets/repository/indexeddb-binary-asset-test-support.ts

@@ -0,0 +1,163 @@
+import type { IDBFactory } from "fake-indexeddb";
+
+import type { IndexedDbHeartbeatScheduler } from "./indexeddb-binary-asset-lifecycle";
+import {
+  createIndexedDbOwnerCollisionError,
+  type IndexedDbOwnerLivenessProvider,
+} from "./indexeddb-binary-asset-liveness";
+
+export function createManualHeartbeatScheduler() {
+  let callback: (() => Promise<void>) | undefined;
+  return {
+    active: () => callback !== undefined,
+    run: async () => callback?.(),
+    scheduler: {
+      cancel(handle) {
+        if (callback === handle) callback = undefined;
+      },
+      schedule(nextCallback) {
+        callback = nextCallback;
+        return nextCallback;
+      },
+    } satisfies IndexedDbHeartbeatScheduler,
+  };
+}
+
+function createPause() {
+  let markStarted!: () => void;
+  let resume!: () => void;
+  const started = new Promise<void>((resolve) => {
+    markStarted = resolve;
+  });
+  const wait = new Promise<void>((resolve) => {
+    resume = resolve;
+  });
+  return { begin: markStarted, resume, started, wait };
+}
+
+export function createManualOwnerLivenessProvider() {
+  const coordinationTails = new Map<string, Promise<void>>();
+  const heldByScope = new Map<string, Set<string>>();
+  let activeCoordinationCount = 0;
+  let acquireAttemptCount = 0;
+  let coordinationRequestCount = 0;
+  let queryMode: "available" | "throw" | "unknown" = "available";
+  let acquirePause: ReturnType<typeof createPause> | undefined;
+  let queryPause: ReturnType<typeof createPause> | undefined;
+  const provider: IndexedDbOwnerLivenessProvider = {
+    async acquire(scope, ownerId) {
+      acquireAttemptCount += 1;
+      const current = heldByScope.get(scope);
+      if (current?.has(ownerId)) {
+        throw createIndexedDbOwnerCollisionError(scope, ownerId);
+      }
+      const pause = acquirePause;
+      acquirePause = undefined;
+      pause?.begin();
+      await pause?.wait;
+      const held = heldByScope.get(scope) ?? new Set<string>();
+      if (held.has(ownerId)) {
+        throw createIndexedDbOwnerCollisionError(scope, ownerId);
+      }
+      heldByScope.set(scope, held);
+      held.add(ownerId);
+      let released = false;
+      return {
+        release: async () => {
+          if (released) return;
+          released = true;
+          held.delete(ownerId);
+          if (held.size === 0) heldByScope.delete(scope);
+        },
+      };
+    },
+    async query(scope) {
+      const snapshot = new Set(heldByScope.get(scope) ?? []);
+      const pause = queryPause;
+      queryPause = undefined;
+      pause?.begin();
+      await pause?.wait;
+      if (queryMode === "throw") throw new Error("lock query failed");
+      if (queryMode === "unknown") return null;
+      return snapshot;
+    },
+    async runExclusive(scope, operation) {
+      coordinationRequestCount += 1;
+      const previous = coordinationTails.get(scope) ?? Promise.resolve();
+      let release!: () => void;
+      const tail = new Promise<void>((resolve) => {
+        release = resolve;
+      });
+      coordinationTails.set(scope, tail);
+      await previous;
+      activeCoordinationCount += 1;
+      try {
+        return await operation();
+      } finally {
+        activeCoordinationCount -= 1;
+        release();
+        if (coordinationTails.get(scope) === tail) {
+          coordinationTails.delete(scope);
+        }
+      }
+    },
+  };
+
+  return {
+    activeCoordinationCount: () => activeCoordinationCount,
+    abandon(ownerId: string) {
+      for (const [scope, held] of heldByScope) {
+        held.delete(ownerId);
+        if (held.size === 0) heldByScope.delete(scope);
+      }
+    },
+    acquireAttemptCount: () => acquireAttemptCount,
+    coordinationRequestCount: () => coordinationRequestCount,
+    heldCount: () =>
+      [...heldByScope.values()].reduce((count, held) => count + held.size, 0),
+    pauseNextAcquire() {
+      acquirePause = createPause();
+      return acquirePause;
+    },
+    pauseNextQuery() {
+      queryPause = createPause();
+      return queryPause;
+    },
+    provider,
+    setQueryMode(mode: "available" | "throw" | "unknown") {
+      queryMode = mode;
+    },
+  };
+}
+
+export function requestResult<Result>(
+  request: IDBRequest<Result>,
+): Promise<Result> {
+  return new Promise((resolve, reject) => {
+    request.addEventListener("success", () => resolve(request.result));
+    request.addEventListener("error", () => reject(request.error));
+  });
+}
+
+export function transactionDone(transaction: IDBTransaction): Promise<void> {
+  return new Promise((resolve, reject) => {
+    transaction.addEventListener("complete", () => resolve());
+    transaction.addEventListener("abort", () => reject(transaction.error));
+    transaction.addEventListener("error", () => reject(transaction.error));
+  });
+}
+
+export async function openVersionOneDatabase(
+  indexedDB: IDBFactory,
+  databaseName: string,
+): Promise<IDBDatabase> {
+  const request = indexedDB.open(databaseName, 1);
+  request.addEventListener("upgradeneeded", () => {
+    request.result.createObjectStore("entries", { keyPath: "ref" });
+    const leases = request.result.createObjectStore("leases", {
+      keyPath: ["leaseId", "ref"],
+    });
+    leases.createIndex("leaseId", "leaseId", { unique: false });
+  });
+  return requestResult(request);
+}

package/templates/runtime/source-assets/repository/memory-binary-asset-repository.test.ts

@@ -0,0 +1,211 @@
+import { describe, expect, it } from "vitest";
+
+import { createMemoryToolcraftBinaryAssetRepository } from "./memory-binary-asset-repository";
+
+const binaryOptions = {
+  contentType: "model/gltf-binary",
+  durable: true,
+} as const;
+
+describe("memory binary asset repository", () => {
+  it("isolates staged entries until an atomic commit and returns defensive copies", async () => {
+    const repository = createMemoryToolcraftBinaryAssetRepository();
+    const owner = await repository.beginLease("owner");
+    const observer = await repository.beginLease("observer");
+    const bytes = new Uint8Array([1, 2, 3]);
+
+    await owner.put("source:a", bytes, binaryOptions);
+    bytes[0] = 99;
+
+    expect(owner.refs()).toEqual(["source:a"]);
+    await expect(owner.get("source:a")).resolves.toMatchObject({
+      bytes: new Uint8Array([1, 2, 3]),
+      contentType: "model/gltf-binary",
+      durable: true,
+      ref: "source:a",
+    });
+    await expect(observer.get("source:a")).resolves.toBeNull();
+    await expect(repository.get("source:a")).resolves.toBeNull();
+
+    await owner.commit();
+    const firstRead = await repository.get("source:a");
+    expect(firstRead?.bytes).toEqual(new Uint8Array([1, 2, 3]));
+    firstRead!.bytes[1] = 88;
+    await expect(repository.get("source:a")).resolves.toMatchObject({
+      bytes: new Uint8Array([1, 2, 3]),
+    });
+  });
+
+  it("rolls back every staged entry and makes completed leases terminal", async () => {
+    const repository = createMemoryToolcraftBinaryAssetRepository();
+    const rolledBack = await repository.beginLease("rollback");
+
+    await rolledBack.put("source:a", new Uint8Array([1]), binaryOptions);
+    await rolledBack.put("document:a", new Uint8Array([2]), {
+      contentType: "application/vnd.toolcraft.model-document",
+      durable: false,
+    });
+    await rolledBack.rollback();
+
+    await expect(repository.get("source:a")).resolves.toBeNull();
+    await expect(repository.get("document:a")).resolves.toBeNull();
+    await expect(rolledBack.get("source:a")).rejects.toThrow(/terminal/u);
+    expect(rolledBack.refs()).toEqual([]);
+    await expect(
+      rolledBack.put("later", new Uint8Array([3]), binaryOptions),
+    ).rejects.toThrow(/terminal/u);
+    await expect(rolledBack.commit()).rejects.toThrow(/terminal/u);
+    await expect(rolledBack.rollback()).rejects.toThrow(/terminal/u);
+
+    const committed = await repository.beginLease("commit");
+    await committed.put("source:b", new Uint8Array([4]), binaryOptions);
+    await committed.commit();
+    await expect(committed.get("source:b")).rejects.toThrow(/terminal/u);
+    expect(committed.refs()).toEqual([]);
+    await expect(
+      committed.put("later", new Uint8Array([5]), binaryOptions),
+    ).rejects.toThrow(/terminal/u);
+    await expect(committed.commit()).rejects.toThrow(/terminal/u);
+    await expect(committed.rollback()).rejects.toThrow(/terminal/u);
+  });
+
+  it("keeps identical same-lease puts idempotent and rejects conflicting replacements", async () => {
+    const repository = createMemoryToolcraftBinaryAssetRepository();
+    const lease = await repository.beginLease("same-lease-duplicate");
+
+    await lease.put("shared", new Uint8Array([1, 2]), binaryOptions);
+    await lease.put("shared", new Uint8Array([1, 2]), binaryOptions);
+
+    await expect(
+      lease.put("shared", new Uint8Array([1, 3]), binaryOptions),
+    ).rejects.toThrow(/shared/u);
+    await expect(
+      lease.put("shared", new Uint8Array([1, 2]), {
+        ...binaryOptions,
+        contentType: "application/octet-stream",
+      }),
+    ).rejects.toThrow(/shared/u);
+    await expect(
+      lease.put("shared", new Uint8Array([1, 2]), {
+        ...binaryOptions,
+        durable: false,
+      }),
+    ).rejects.toThrow(/shared/u);
+    expect(lease.refs()).toEqual(["shared"]);
+    await expect(lease.get("shared")).resolves.toMatchObject({
+      bytes: new Uint8Array([1, 2]),
+      contentType: binaryOptions.contentType,
+      durable: true,
+    });
+  });
+
+  it("rejects conflicting duplicate refs without publishing any part of the lease", async () => {
+    const repository = createMemoryToolcraftBinaryAssetRepository();
+    const first = await repository.beginLease("first");
+
+    await first.put("shared", new Uint8Array([1]), binaryOptions);
+    await first.commit();
+
+    const conflicting = await repository.beginLease("conflicting");
+    await conflicting.put("shared", new Uint8Array([2]), binaryOptions);
+    await conflicting.put("unique", new Uint8Array([3]), binaryOptions);
+
+    await expect(conflicting.commit()).rejects.toThrow(/shared/u);
+    await expect(repository.get("shared")).resolves.toMatchObject({
+      bytes: new Uint8Array([1]),
+    });
+    await expect(repository.get("unique")).resolves.toBeNull();
+    await conflicting.rollback();
+
+    const identical = await repository.beginLease("identical");
+    await identical.put("shared", new Uint8Array([1]), binaryOptions);
+    await identical.put("published", new Uint8Array([4]), binaryOptions);
+    await identical.commit();
+    await expect(repository.get("published")).resolves.toMatchObject({
+      bytes: new Uint8Array([4]),
+    });
+  });
+
+  it("deterministically gives the first concurrent commit an immutable duplicate ref", async () => {
+    const repository = createMemoryToolcraftBinaryAssetRepository();
+    const first = await repository.beginLease("first-concurrent");
+    const second = await repository.beginLease("second-concurrent");
+
+    await first.put("shared", new Uint8Array([1]), binaryOptions);
+    await first.put("first-only", new Uint8Array([2]), binaryOptions);
+    await second.put("shared", new Uint8Array([3]), binaryOptions);
+    await second.put("second-only", new Uint8Array([4]), binaryOptions);
+
+    const results = await Promise.allSettled([first.commit(), second.commit()]);
+
+    expect(results.map((result) => result.status)).toEqual([
+      "fulfilled",
+      "rejected",
+    ]);
+    await expect(repository.get("shared")).resolves.toMatchObject({
+      bytes: new Uint8Array([1]),
+    });
+    await expect(repository.get("first-only")).resolves.not.toBeNull();
+    await expect(repository.get("second-only")).resolves.toBeNull();
+    await second.rollback();
+  });
+
+  it("collects only unreachable committed refs in deterministic order", async () => {
+    const repository = createMemoryToolcraftBinaryAssetRepository();
+    const committed = await repository.beginLease("committed");
+
+    await committed.put("z-ref", new Uint8Array([1]), binaryOptions);
+    await committed.put("keep", new Uint8Array([2]), binaryOptions);
+    await committed.put("a-ref", new Uint8Array([3]), binaryOptions);
+    await committed.commit();
+
+    const staged = await repository.beginLease("staged");
+    await staged.put("staged-only", new Uint8Array([4]), binaryOptions);
+
+    await expect(repository.collect(new Set(["keep"]))).resolves.toEqual([
+      "a-ref",
+      "z-ref",
+    ]);
+    await expect(repository.get("keep")).resolves.not.toBeNull();
+    await expect(repository.get("a-ref")).resolves.toBeNull();
+    await expect(staged.get("staged-only")).resolves.not.toBeNull();
+
+    await staged.commit();
+    await expect(repository.get("staged-only")).resolves.not.toBeNull();
+  });
+
+  it("compensates for a post-commit failure by collecting the unreferenced publication", async () => {
+    const repository = createMemoryToolcraftBinaryAssetRepository();
+    const lease = await repository.beginLease("post-commit-compensation");
+
+    await lease.put("orphaned-publication", new Uint8Array([1]), binaryOptions);
+    await lease.commit();
+
+    await expect(lease.rollback()).rejects.toThrow(/terminal/u);
+    await expect(repository.get("orphaned-publication")).resolves.not.toBeNull();
+    await expect(repository.collect(new Set())).resolves.toEqual([
+      "orphaned-publication",
+    ]);
+    await expect(repository.get("orphaned-publication")).resolves.toBeNull();
+  });
+
+  it("disposes repository ownership and invalidates existing leases", async () => {
+    const repository = createMemoryToolcraftBinaryAssetRepository();
+    const lease = await repository.beginLease("disposed-owner");
+
+    await lease.put("staged", new Uint8Array([1]), binaryOptions);
+    await repository.dispose();
+    await expect(repository.dispose()).resolves.toBeUndefined();
+
+    await expect(repository.beginLease("later")).rejects.toThrow(/disposed/u);
+    await expect(repository.get("staged")).rejects.toThrow(/disposed/u);
+    await expect(repository.collect(new Set())).rejects.toThrow(/disposed/u);
+    await expect(lease.get("staged")).rejects.toThrow(/disposed|terminal/u);
+    await expect(
+      lease.put("later", new Uint8Array([2]), binaryOptions),
+    ).rejects.toThrow(/disposed|terminal/u);
+    await expect(lease.commit()).rejects.toThrow(/disposed|terminal/u);
+    await expect(lease.rollback()).rejects.toThrow(/disposed|terminal/u);
+    expect(lease.refs()).toEqual([]);
+  });
+});

package/templates/runtime/source-assets/repository/memory-binary-asset-repository.ts

@@ -0,0 +1,149 @@
+import {
+  areToolcraftBinaryAssetRepositoryEntriesEqual,
+  assertToolcraftBinaryAssetRef,
+  cloneToolcraftBinaryAssetRepositoryEntry,
+  createToolcraftBinaryAssetConflictError,
+  createToolcraftBinaryAssetRepositoryEntry,
+  type ToolcraftBinaryAssetLease,
+  type ToolcraftBinaryAssetRepository,
+  type ToolcraftBinaryAssetRepositoryEntry,
+} from "./binary-asset-repository";
+import { expandToolcraftBinaryAssetReachability } from "./binary-asset-reachability";
+
+class MemoryToolcraftBinaryAssetRepository
+  implements ToolcraftBinaryAssetRepository
+{
+  private readonly activeJobIds = new Set<string>();
+  private readonly activeLeaseDisposers = new Set<() => void>();
+  private readonly entries = new Map<
+    string,
+    ToolcraftBinaryAssetRepositoryEntry
+  >();
+  private disposed = false;
+
+  async beginLease(jobId: string): Promise<ToolcraftBinaryAssetLease> {
+    this.assertActive();
+    if (jobId.length === 0 || jobId.trim() !== jobId) {
+      throw new Error("Binary asset lease job id must be a non-empty trimmed string");
+    }
+    if (this.activeJobIds.has(jobId)) {
+      throw new Error(`Binary asset lease job "${jobId}" is already active`);
+    }
+
+    this.activeJobIds.add(jobId);
+    const staged = new Map<string, ToolcraftBinaryAssetRepositoryEntry>();
+    let terminal = false;
+
+    const assertActive = () => {
+      if (terminal) {
+        throw new Error(`Binary asset lease job "${jobId}" is terminal`);
+      }
+    };
+    const finish = () => {
+      if (terminal) return;
+      terminal = true;
+      staged.clear();
+      this.activeJobIds.delete(jobId);
+      this.activeLeaseDisposers.delete(finish);
+    };
+    this.activeLeaseDisposers.add(finish);
+
+    return {
+      commit: async () => {
+        assertActive();
+
+        for (const [ref, entry] of staged) {
+          const existing = this.entries.get(ref);
+          if (
+            existing &&
+            !areToolcraftBinaryAssetRepositoryEntriesEqual(existing, entry)
+          ) {
+            throw createToolcraftBinaryAssetConflictError(ref);
+          }
+        }
+
+        for (const [ref, entry] of staged) {
+          if (!this.entries.has(ref)) {
+            this.entries.set(
+              ref,
+              cloneToolcraftBinaryAssetRepositoryEntry(entry),
+            );
+          }
+        }
+        finish();
+      },
+      get: async (ref) => {
+        assertActive();
+        assertToolcraftBinaryAssetRef(ref);
+        const entry = staged.get(ref) ?? this.entries.get(ref);
+        return entry ? cloneToolcraftBinaryAssetRepositoryEntry(entry) : null;
+      },
+      put: async (ref, bytes, options) => {
+        assertActive();
+        const entry = createToolcraftBinaryAssetRepositoryEntry(
+          ref,
+          bytes,
+          options,
+        );
+        const existing = staged.get(ref);
+        if (existing) {
+          if (!areToolcraftBinaryAssetRepositoryEntriesEqual(existing, entry)) {
+            throw createToolcraftBinaryAssetConflictError(ref);
+          }
+          return;
+        }
+        staged.set(ref, entry);
+      },
+      refs: () => (terminal ? [] : [...staged.keys()].sort()),
+      rollback: async () => {
+        assertActive();
+        finish();
+      },
+    };
+  }
+
+  async collect(reachableRefs: ReadonlySet<string>): Promise<readonly string[]> {
+    this.assertActive();
+    const reachable = expandToolcraftBinaryAssetReachability(
+      reachableRefs,
+      this.entries.values(),
+    );
+    const deletedRefs = [...this.entries.keys()]
+      .filter((ref) => !reachable.has(ref))
+      .sort();
+
+    for (const ref of deletedRefs) {
+      this.entries.delete(ref);
+    }
+
+    return deletedRefs;
+  }
+
+  async dispose(): Promise<void> {
+    if (this.disposed) return;
+    this.disposed = true;
+    for (const disposeLease of [...this.activeLeaseDisposers]) {
+      disposeLease();
+    }
+    this.activeLeaseDisposers.clear();
+    this.activeJobIds.clear();
+    this.entries.clear();
+  }
+
+  async get(ref: string): Promise<ToolcraftBinaryAssetRepositoryEntry | null> {
+    this.assertActive();
+    assertToolcraftBinaryAssetRef(ref);
+    const entry = this.entries.get(ref);
+    return entry ? cloneToolcraftBinaryAssetRepositoryEntry(entry) : null;
+  }
+
+  private assertActive(): void {
+    if (this.disposed) {
+      throw new Error("Memory binary asset repository is disposed");
+    }
+  }
+}
+
+export function createMemoryToolcraftBinaryAssetRepository(): ToolcraftBinaryAssetRepository {
+  return new MemoryToolcraftBinaryAssetRepository();
+}

package/templates/runtime/source-assets/repository/resource-manifest.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  createToolcraftResourceManifest,
+  parseToolcraftResourceManifest,
+  serializeToolcraftResourceManifest,
+} from "./resource-manifest";
+
+describe("Toolcraft resource manifest", () => {
+  it("creates a stable, deduplicated manifest for source and derived resources", () => {
+    const manifest = createToolcraftResourceManifest({
+      canonicalDocumentRefs: ["document:z", "document:a", "document:a"],
+      derivedResourceRefs: ["repair:z", "repair:a", "repair:z"],
+      durableSourceRefs: ["source:z", "source:a", "source:a"],
+    });
+
+    expect(manifest).toEqual({
+      canonicalDocumentRefs: ["document:a", "document:z"],
+      derivedResourceRefs: ["repair:a", "repair:z"],
+      durableSourceRefs: ["source:a", "source:z"],
+      version: 1,
+    });
+    expect(serializeToolcraftResourceManifest(manifest)).toBe(
+      '{"canonicalDocumentRefs":["document:a","document:z"],"derivedResourceRefs":["repair:a","repair:z"],"durableSourceRefs":["source:a","source:z"],"version":1}',
+    );
+  });
+
+  it("strictly parses a canonical manifest without trusting unknown input", () => {
+    const canonical = {
+      canonicalDocumentRefs: ["document:a"],
+      derivedResourceRefs: ["repair:a"],
+      durableSourceRefs: ["source:a"],
+      version: 1,
+    };
+
+    expect(parseToolcraftResourceManifest(canonical)).toEqual(canonical);
+    expect(
+      parseToolcraftResourceManifest(JSON.stringify(canonical)),
+    ).toEqual(canonical);
+
+    const corruptInputs: readonly unknown[] = [
+      null,
+      [],
+      { ...canonical, version: 2 },
+      { ...canonical, unknown: true },
+      { ...canonical, durableSourceRefs: "source:a" },
+      { ...canonical, canonicalDocumentRefs: [""] },
+      { ...canonical, derivedResourceRefs: ["repair:a", "repair:a"] },
+      { ...canonical, durableSourceRefs: ["source:z", "source:a"] },
+      "{not-json",
+    ];
+
+    for (const input of corruptInputs) {
+      expect(() => parseToolcraftResourceManifest(input)).toThrow(
+        /resource manifest/u,
+      );
+    }
+  });
+
+  it("rejects a bare string instead of treating it as an iterable of character refs", () => {
+    expect(() =>
+      createToolcraftResourceManifest({
+        durableSourceRefs: "source:a" as never,
+      }),
+    ).toThrow(/resource manifest/u);
+  });
+});