@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/asset-workflow/hosted-asset-materialization.ts

@@ -0,0 +1,236 @@
+/**
+ * Materialize a project's DECLARED asset packs (`asset-manifest.json`, D-AP1)
+ * from the `cloud-asset-library` Worker into a `StorageBackend`, recording
+ * the same provenance ledger (`.volter/assets.json`, D-AP3) every other
+ * materialization site writes.
+ *
+ * This is the D-AP4 mechanism: a project's DECLARED packs are materialized
+ * from the `cloud-asset-library` worker (existing manifest + object routes),
+ * writing the same ledger.
+ *
+ * Exported for the open path to CALL rather than
+ * wired into `seedIfEmpty` here, so any declared pack (in the template or an
+ * example) reuses it without change. The template's `asset-manifest.json` is
+ * `{"packs": {}}` today, so calling this against the shipped template is a
+ * documented, harmless no-op: `declared` reports 0 and nothing is fetched.
+ *
+ * FAIL CLOSED AND LOUD, never fabricate (the anti-shim rule): a network
+ * failure, a 404, or a sha256 mismatch aborts THAT entry only — nothing is
+ * written for it — and is reported in the returned result; it never blocks
+ * the other declared entries and never substitutes placeholder bytes.
+ *
+ * ## The expected digest comes from the DECLARATION, never from the response
+ *
+ * Every entry pins `sha256` in `asset-manifest.json` (see
+ * `asset-pack-manifest.ts`), and that pin is the only authority here. Reading
+ * the expected digest out of the worker's own `/v1/assets/<id>` record instead
+ * would authenticate nothing on the FIRST fetch — a moved or tampered library
+ * answers self-consistently (its record and its bytes agree), the bytes get
+ * written, and its digest becomes the project's permanent `sourceHash` in the
+ * ledger. So: the record's digest must MATCH the pin (a disagreement is a
+ * refusal naming the asset), the fetched bytes are verified against the pin,
+ * and the pin is what the ledger records.
+ *
+ * ## "Already materialized" means the FILE is there, not just the record
+ *
+ * Idempotent and retry-safe: an entry is skipped only when the ledger has it
+ * AND its destination exists. Skipping on the ledger record alone made the
+ * broken case unrepairable — a project whose bytes were deleted, or whose
+ * ledger outlived a failed write, reported success forever, and the reopen
+ * retry (`project-manager.ts`) plus the Retry banner both skipped exactly the
+ * entry they existed to refetch.
+ */
+
+import { sha256Hex } from '@volter/sdk/kit/bytes-codec';
+import type { StorageBackend } from '@volter/sdk/kit/storage-types';
+import { normalizeLedgerPath } from './asset-ledger';
+import {
+  readAssetLedgerFromBackend,
+  recordAssetMaterializationInBackend,
+} from './asset-ledger-backend';
+/** Project-relative path of the pack declaration (D-AP1) — sibling of
+ *  `volter.project.json` in the template/every example, and (per D-AP4) one of
+ *  the plain-text files the browser build's seed writes alongside the rest
+ *  of the template source. */
+import {
+  ASSET_MANIFEST_PATH,
+  type FlattenedPackEntry,
+  flattenAssetPacks,
+  parseAssetPackManifest,
+} from './asset-pack-manifest';
+import {
+  cloudAssetObjectUrl,
+  DEFAULT_CLOUD_ASSET_BASE_URL,
+  fetchCloudAssetRecord,
+} from './cloud-asset-client';
+
+export { ASSET_MANIFEST_PATH };
+
+export interface AssetPackMaterializationFailure {
+  readonly entry: FlattenedPackEntry;
+  readonly reason: string;
+}
+
+export interface AssetPackMaterializationResult {
+  /** Total entries declared across every pack. */
+  readonly declared: number;
+  readonly materialized: FlattenedPackEntry[];
+  /** Recorded in the ledger AND present on disk — nothing to do, not a failure. */
+  readonly alreadyPresent: FlattenedPackEntry[];
+  readonly failed: AssetPackMaterializationFailure[];
+}
+
+export interface MaterializeAssetPacksOptions {
+  /** Test-only override of the deployed worker's base URL. */
+  readonly baseUrl?: string;
+  readonly signal?: AbortSignal;
+  /** Called once per entry, after it is attempted. */
+  readonly onProgress?: (
+    entry: FlattenedPackEntry,
+    outcome: 'materialized' | 'already-present' | 'failed',
+  ) => void;
+}
+
+/**
+ * Materialize every pack entry `backend` declares in its own
+ * `asset-manifest.json` that is not already in the ledger.
+ *
+ * Reads the manifest from `backend` itself (not the repo), whichever backend
+ * the caller is already using.
+ */
+export async function materializeDeclaredAssetPacks(
+  backend: StorageBackend,
+  options: MaterializeAssetPacksOptions = {},
+): Promise<AssetPackMaterializationResult> {
+  const entries = await declaredPackEntries(backend);
+  const result: AssetPackMaterializationResult = {
+    declared: entries.length,
+    materialized: [],
+    alreadyPresent: [],
+    failed: [],
+  };
+  if (entries.length === 0) return result;
+
+  const ledger = await readAssetLedgerFromBackend(backend);
+  for (const entry of entries) {
+    if (options.signal?.aborted) break;
+    // A ledger record is a record, not the bytes — see the module header.
+    if (ledger[normalizeLedgerPath(entry.dest)] && (await backend.exists(entry.dest))) {
+      result.alreadyPresent.push(entry);
+      options.onProgress?.(entry, 'already-present');
+      continue;
+    }
+    try {
+      await materializeOne(backend, entry, options);
+      result.materialized.push(entry);
+      options.onProgress?.(entry, 'materialized');
+    } catch (error) {
+      result.failed.push({ entry, reason: error instanceof Error ? error.message : String(error) });
+      options.onProgress?.(entry, 'failed');
+    }
+  }
+  return result;
+}
+
+async function declaredPackEntries(backend: StorageBackend): Promise<FlattenedPackEntry[]> {
+  if (!(await backend.exists(ASSET_MANIFEST_PATH))) return [];
+  const raw = await backend.read(ASSET_MANIFEST_PATH);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `${ASSET_MANIFEST_PATH} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  return flattenAssetPacks(parseAssetPackManifest(parsed));
+}
+
+async function materializeOne(
+  backend: StorageBackend,
+  entry: FlattenedPackEntry,
+  options: MaterializeAssetPacksOptions,
+): Promise<void> {
+  const fetched = await fetchVerifiedPackEntry(entry, options);
+  await backend.write(entry.dest, fetched.bytes);
+  await recordAssetMaterializationInBackend(backend, {
+    destPath: entry.dest,
+    key: entry.key,
+    license: fetched.license,
+    // The PIN, not the library's reported digest — identical here by the
+    // check inside `fetchVerifiedPackEntry`, and the pin is the fact this
+    // project reviewed.
+    sourceSha256: entry.sha256,
+  });
+}
+
+/** The bytes of one declared pack entry, plus the library's license string. */
+export interface VerifiedPackEntryBytes {
+  readonly bytes: Uint8Array;
+  /** The library's own license string, for the ledger. */
+  readonly license: string;
+}
+
+/**
+ * Fetch and VERIFY one declared pack entry, writing nothing.
+ *
+ * This is the whole network + trust sequence — record lookup, pin/record
+ * cross-check, byte fetch, digest verification — with the destination IO left
+ * to the caller, because the two materialization sites differ only in where the
+ * bytes land: this module writes through a `StorageBackend` (browser/hosted),
+ * and `packages/volter-cli/src/asset-packs.ts` writes to the filesystem for an
+ * on-disk project the editor's `add` command just declared a pack into. Extracted so neither
+ * site can drift from the other on the part that matters — a second copy of
+ * "fetch then trust" is exactly how trust-on-first-use gets reintroduced.
+ *
+ * Throws on every failure and never returns partial bytes.
+ */
+export async function fetchVerifiedPackEntry(
+  entry: FlattenedPackEntry,
+  options: MaterializeAssetPacksOptions = {},
+): Promise<VerifiedPackEntryBytes> {
+  const separator = entry.key.indexOf(':');
+  if (separator < 0) throw new Error(`Malformed asset key "${entry.key}" (expected "source:id").`);
+  const source = entry.key.slice(0, separator);
+  const assetId = entry.key.slice(separator + 1);
+  if (source !== 'local') {
+    throw new Error(
+      `Asset key "${entry.key}": only the "local" (cloud-hosted) source can be materialized ` +
+        'from the cloud worker.',
+    );
+  }
+  const baseUrl = options.baseUrl ?? DEFAULT_CLOUD_ASSET_BASE_URL;
+  const fetchOptions = options.signal ? { baseUrl, signal: options.signal } : { baseUrl };
+  const record = await fetchCloudAssetRecord(assetId, fetchOptions);
+  if (!record) throw new Error(`"${entry.key}" is not hosted by the cloud asset library.`);
+  const file = record.files[0];
+  if (!file) throw new Error(`"${entry.key}" has no files in the cloud library.`);
+  if (file.dependencies.length > 0) {
+    throw new Error(
+      `"${entry.key}" has ${file.dependencies.length} dependency file(s) — a pack entry names ` +
+        'exactly one destination file.',
+    );
+  }
+  // The cloud record must AGREE with the checked-in pin before a byte is
+  // fetched. A library that has moved on is a legitimate event; silently
+  // adopting its new bytes is not (see the module header).
+  if (file.main.sha256 !== entry.sha256) {
+    throw new Error(
+      `"${entry.key}" → ${entry.dest}: the cloud library reports sha256:${file.main.sha256} but ` +
+        `${ASSET_MANIFEST_PATH} pins sha256:${entry.sha256}. Nothing was fetched or written; ` +
+        'the pin is only re-cut by a reviewed change to the declaration.',
+    );
+  }
+  const url = cloudAssetObjectUrl(baseUrl, assetId, 0);
+  const response = await fetch(url, options.signal ? { signal: options.signal } : {});
+  if (!response.ok) throw new Error(`${url} returned ${response.status} ${response.statusText}.`);
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  const actual = await sha256Hex(bytes);
+  if (actual !== entry.sha256) {
+    throw new Error(
+      `"${entry.key}" → ${entry.dest}: ${url} delivered sha256:${actual} but the declaration ` +
+        `pins sha256:${entry.sha256}. Nothing was written.`,
+    );
+  }
+  return { bytes, license: record.license };
+}

package/src/kit/asset-workflow/image-view-scale.ts

@@ -0,0 +1,31 @@
+/**
+ * Integer zoom for pixel art: a fractional factor resamples the art, and a
+ * resampled sheet is a blur with the correct pixels still in the file.
+ */
+
+/** Largest scale that fits `src` inside `box` without resampling. */
+export function integerFitScale(
+  srcWidth: number,
+  srcHeight: number,
+  boxWidth: number,
+  boxHeight: number,
+): number {
+  if (srcWidth <= 0 || srcHeight <= 0 || boxWidth <= 0 || boxHeight <= 0) return 1;
+  const growX = srcWidth <= boxWidth ? Math.floor(boxWidth / srcWidth) : 0;
+  const growY = srcHeight <= boxHeight ? Math.floor(boxHeight / srcHeight) : 0;
+  const grow = Math.min(growX, growY);
+  if (grow >= 1) return grow;
+  return 1 / Math.max(Math.ceil(srcWidth / boxWidth), Math.ceil(srcHeight / boxHeight));
+}
+
+export type ImageScaleMode = 'fit' | 1 | 4 | 8;
+
+export function resolveImageScale(
+  mode: ImageScaleMode,
+  srcWidth: number,
+  srcHeight: number,
+  boxWidth: number,
+  boxHeight: number,
+): number {
+  return mode === 'fit' ? integerFitScale(srcWidth, srcHeight, boxWidth, boxHeight) : mode;
+}

package/src/kit/asset-workflow/import-contract.ts

@@ -0,0 +1,124 @@
+import { isContainedRelativePath } from '@volter/sdk/session/relative-path-guard';
+import { z } from 'zod';
+
+export const assetImportSettingsSchema = z
+  .object({
+    scale: z.number().positive().default(1),
+    sourceUnits: z.enum(['auto', 'mm', 'cm', 'm', 'in', 'ft']).default('auto'),
+    upAxis: z.enum(['auto', 'x', 'y', 'z']).default('auto'),
+    forwardAxis: z.enum(['auto', 'x', '-x', 'y', '-y', 'z', '-z']).default('auto'),
+    normals: z.enum(['preserve', 'generate', 'recalculate']).default('preserve'),
+    tangents: z.enum(['preserve', 'generate', 'discard']).default('preserve'),
+    materials: z.enum(['import', 'discard']).default('import'),
+    textures: z.enum(['copy', 'embed', 'discard']).default('copy'),
+    animations: z.array(z.string()).default([]),
+    meshOptimization: z.enum(['none', 'safe', 'aggressive']).default('safe'),
+    retainSource: z.boolean().default(true),
+  })
+  .strict();
+export type AssetImportSettings = z.infer<typeof assetImportSettingsSchema>;
+
+const safePathSchema = z
+  .string()
+  .min(1)
+  .refine(isContainedRelativePath, 'Path must stay within the source/project root.');
+
+const importFileSchema = z
+  .object({
+    path: safePathSchema,
+    url: z.string().min(1),
+    hash: z.string().min(8),
+    size: z.number().int().nonnegative(),
+    role: z.enum(['primary', 'dependency', 'material', 'texture']),
+  })
+  .strict();
+
+export const assetImportPlanSchema = z
+  .object({
+    version: z.literal(1),
+    id: z.string().min(1),
+    identity: z
+      .object({
+        familyId: z.string().min(1),
+        variantId: z.string().min(1),
+        deliveryId: z.string().min(1),
+        source: z.string().min(1).optional(),
+        displayName: z.string().min(1).optional(),
+      })
+      .strict(),
+    sourceFiles: z.array(importFileSchema).min(1),
+    generatedFiles: z.array(safePathSchema),
+    destination: safePathSchema,
+    contentKind: z
+      .enum(['model', 'animation-only', 'image', 'audio', 'material', 'data'])
+      .default('model'),
+    targetSkeleton: z.string().optional(),
+    settings: assetImportSettingsSchema,
+    conflicts: z.array(
+      z
+        .object({ path: z.string(), resolution: z.enum(['reuse', 'update', 'rename', 'cancel']) })
+        .strict(),
+    ),
+    attribution: z
+      .object({
+        sourceUrl: z.string(),
+        author: z.string(),
+        license: z.string(),
+        text: z.string(),
+      })
+      .strict(),
+    sourceHash: z.string().min(8),
+    runtimeReady: z.boolean(),
+    backend: z.enum(['native', 'three', 'blender']),
+    createdAt: z.string(),
+  })
+  .superRefine((plan, context) => {
+    if (plan.contentKind === 'animation-only' && plan.runtimeReady && !plan.targetSkeleton) {
+      context.addIssue({
+        code: 'custom',
+        path: ['targetSkeleton'],
+        message: 'Runtime-ready animation-only imports require a compatible target skeleton.',
+      });
+    }
+  });
+export type AssetImportPlan = z.infer<typeof assetImportPlanSchema>;
+
+export const assetImportResultSchema = z
+  .object({
+    version: z.literal(1),
+    planId: z.string(),
+    status: z.enum(['imported', 'skipped', 'failed', 'cancelled']),
+    writtenFiles: z.array(
+      z
+        .object({ path: z.string(), hash: z.string(), size: z.number().int().nonnegative() })
+        .strict(),
+    ),
+    skippedFiles: z.array(z.string()),
+    issues: z.array(
+      z.object({ code: z.string(), stage: z.string(), message: z.string() }).strict(),
+    ),
+  })
+  .strict();
+export type AssetImportResult = z.infer<typeof assetImportResultSchema>;
+
+export type AssetImportStage = 'fetch' | 'convert' | 'validate' | 'commit';
+export interface AssetImportProgress {
+  stage: AssetImportStage;
+  item: string;
+  loaded: number;
+  total: number;
+}
+
+export type AssetConflictKind =
+  | 'same-identity-same-hash'
+  | 'same-identity-updated'
+  | 'different-identity-same-name'
+  | 'user-edited-output';
+export function safeConflictResolution(
+  kind: AssetConflictKind,
+): 'reuse' | 'update' | 'rename' | 'cancel' {
+  if (kind === 'same-identity-same-hash') return 'reuse';
+  if (kind === 'same-identity-updated') return 'update';
+  if (kind === 'different-identity-same-name') return 'rename';
+  return 'cancel';
+}

package/src/kit/asset-workflow/ledger-write-lock.ts

@@ -0,0 +1,244 @@
+/**
+ * The two mechanical halves of "a read-modify-write of one file never loses a
+ * record", shared by the ledger's two I/O sides (`../../server/
+ * asset-ledger-store.ts` over `node:fs`, `./asset-ledger-backend.ts` over a
+ * `StorageBackend`).
+ *
+ * Why the ledger needs this at all: `.volter/assets.json` (D-AP3) is updated by
+ * READING it, adding one entry, and writing the whole object back. Two of those
+ * in flight interleave — both read the old object, the later write wins, and the
+ * earlier record is gone with no error anywhere. Two materializations at once is
+ * ordinary, not exotic: two the editor's `edit` command sessions on one project, `npm run
+ * asset-packs:sync` while an editor is prewarming, two tabs on one project
+ * both retrying their declared packs on reopen.
+ *
+ * Neither half alone is enough, which is why both are here:
+ *
+ *   - `createSerializer` — an in-process (in-realm) promise chain per key. This
+ *     is what makes concurrency INSIDE one process correct, and it is the only
+ *     mechanism that can, since a file lock cannot exclude its own holder.
+ *   - `withExclusiveLock` — a lock FILE, which is the only thing a second
+ *     process/realm can see. Injected I/O (`ExclusiveLockIO`) so the same
+ *     waiting/stale-breaking policy runs over `node:fs` and over a
+ *     `StorageBackend` without either being reimplemented.
+ *
+ * This module is deliberately a helper, not a system: no ownership of when a
+ * ledger is written, no retries of the caller's work, no state beyond the map a
+ * `createSerializer` call hands back.
+ */
+
+/** File operations `withExclusiveLock` needs. One lock path per instance. */
+export interface ExclusiveLockIO {
+  /** Create the lock holding `content` iff absent. `false` when already held. */
+  createIfAbsent(content: string): Promise<boolean>;
+  /** The held lock's content, or `null` if it has since vanished. */
+  read(): Promise<string | null>;
+  /**
+   * Delete the lock ONLY while it still holds `expected`. Must tolerate an
+   * already-absent lock, and must leave a lock holding anything else alone.
+   *
+   * There is deliberately no unconditional delete: every deletion in this
+   * module is either "release the lock I took" or "break the corpse I judged
+   * stale", and both name the exact content they mean. A caller that could
+   * delete whatever is there deletes ANOTHER writer's live lock whenever its
+   * own view is one step out of date — which is how two writers used to end up
+   * inside the critical section at once.
+   *
+   * The compare and the delete must be ATOMIC WITH RESPECT TO EACH OTHER, and
+   * that requirement is on the implementer, not on this module. A backend that
+   * reads, compares, then deletes as separate steps reintroduces the same
+   * defect one level down: two waiters both compare against the corpse, the
+   * first deletes it, acquires and enters, and the second's delete — already
+   * past its comparison — removes the winner's fresh lock and lets it in behind
+   * it. The two shipped backends each pay for this: the browser one runs inside
+   * the `navigator.locks` name `writeIfAbsent` takes, and the `node:fs` one has
+   * no atomic compare-and-delete at all and uses `removeIfHeldByTakeover`.
+   */
+  removeIfHeldBy(expected: string): Promise<void>;
+}
+
+/**
+ * The atomic single steps a takeover-based compare-and-delete needs. Each
+ * instance belongs to ONE attempt: the aside path is chosen by the caller and
+ * unique per attempt, so two concurrent attempts can never collide on it.
+ *
+ * On `node:fs` these are `rename`, `readFile`, `rm` and `writeFile` with the
+ * `wx` flag — every one a single syscall, which is the whole reason the
+ * algorithm below can be reasoned about at all.
+ */
+export interface LockTakeoverOps {
+  /**
+   * Atomically move the lock to this attempt's aside path. `false` when the
+   * lock was not there — which, when several attempts race, is how every
+   * attempt but one finds out that it lost.
+   */
+  moveAside(): Promise<boolean>;
+  /** Content of the moved-aside lock; `null` if it is somehow not there. */
+  readAside(): Promise<string | null>;
+  deleteAside(): Promise<void>;
+  /** Put `content` back at the lock path, ONLY while it is still absent. */
+  restoreIfAbsent(content: string): Promise<boolean>;
+}
+
+/**
+ * `removeIfHeldBy` for a filesystem that has no atomic compare-and-delete:
+ * SEIZE the lock with one atomic move, and only then compare.
+ *
+ * What this buys, and it is the entire point: for a given lock, AT MOST ONE
+ * attempt can move it aside. Every other racer's `moveAside` reports `false`
+ * and deletes nothing, so it loops, re-reads, and sees the winner's fresh
+ * stamp. Read-then-delete could not offer this — its comparison is a snapshot,
+ * and a snapshot is stale by the time the delete runs.
+ *
+ * If the seized content is NOT the content this attempt judged, this attempt had
+ * no business taking it: put it straight back, then drop the aside copy.
+ *
+ * RESIDUAL — stated precisely, because it is not zero. Between the move and the
+ * restore, the lock path is briefly absent. A writer whose `createIfAbsent`
+ * lands in exactly that gap acquires while the lock's real holder is still
+ * inside its critical section. Reaching it takes two coincidences: the content
+ * must change between the caller's read and this move (the holder of a stamp
+ * older than `staleAfterMs` releasing, and a successor acquiring, inside that
+ * window), AND a third writer's create must land inside the restore window.
+ * POSIX offers no primitive that closes it — there is no atomic
+ * compare-and-delete — and closing it would take a lease/heartbeat protocol
+ * with a "your lock was compromised" callback, which this helper deliberately
+ * is not.
+ */
+export async function removeIfHeldByTakeover(
+  ops: LockTakeoverOps,
+  expected: string,
+): Promise<void> {
+  if (!(await ops.moveAside())) return;
+  const seized = await ops.readAside();
+  if (seized !== null && seized !== expected) await ops.restoreIfAbsent(seized);
+  await ops.deleteAside();
+}
+
+export interface ExclusiveLockOptions {
+  /**
+   * How long a lock may be held before another writer BREAKS it.
+   *
+   * Breaking, rather than failing, is deliberate: the holder of a lock file is
+   * usually a process that has since died (Ctrl-C in the middle of
+   * `asset-packs:sync`, a closed tab), and a provenance record must not be
+   * refused forever because of a corpse. A real holder finishes in single-digit
+   * milliseconds, so this is orders of magnitude above the honest wait — and it
+   * is also the loop bound, so waiting can never deadlock.
+   */
+  readonly staleAfterMs?: number;
+  /** Poll interval while a live lock is held. */
+  readonly retryDelayMs?: number;
+  /** Recorded in the lock so a human can see who holds it. */
+  readonly owner?: string;
+  readonly now?: () => number;
+  readonly sleep?: (ms: number) => Promise<void>;
+  /**
+   * The per-ATTEMPT unique part of the stamp. Injectable so a test can name the
+   * attempts it schedules; never for production use.
+   *
+   * It is load-bearing rather than cosmetic: `removeIfHeldBy` can only tell "my
+   * lock" from "someone else's lock" if no two attempts can ever write the same
+   * stamp, and `{at, owner}` alone repeats whenever two writers with the same
+   * owner name land in the same millisecond.
+   */
+  readonly token?: () => string;
+}
+
+const DEFAULT_STALE_AFTER_MS = 10_000;
+const DEFAULT_RETRY_DELAY_MS = 15;
+
+/** Same guarded form as `../storage/index.ts` — `crypto` is absent in a
+ *  non-secure browser context, and a missing token must not fail a write. */
+function defaultToken(): string {
+  return globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random()}`;
+}
+
+/** Run `work` while holding an exclusive on-disk lock, always releasing it. */
+export async function withExclusiveLock<T>(
+  io: ExclusiveLockIO,
+  work: () => Promise<T>,
+  options: ExclusiveLockOptions = {},
+): Promise<T> {
+  const staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+  const retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+  const now = options.now ?? Date.now;
+  const sleep =
+    options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const token = options.token ?? defaultToken;
+
+  for (;;) {
+    const stamp = JSON.stringify({ at: now(), owner: options.owner ?? 'unknown', token: token() });
+    if (await io.createIfAbsent(stamp)) {
+      try {
+        return await work();
+      } finally {
+        // Release only OUR lock: if a waiter judged it stale and its successor
+        // has already taken the lock, `stamp` is no longer the content and this
+        // is a no-op. An unconditional delete here would hand the successor's
+        // lock to whoever came next.
+        await io.removeIfHeldBy(stamp);
+      }
+    }
+    const held = await io.read();
+    // Gone between the failed create and this read — race the create again.
+    if (held === null) continue;
+    if (now() - lockHeldSince(held) > staleAfterMs) {
+      // Break the exact corpse we judged, not "whatever is there now" — an
+      // unconditional delete here removes the lock of whoever broke this same
+      // corpse a step ahead of us, and lets us walk in behind them.
+      //
+      // `held` is a SNAPSHOT: by the time the io acts on it, another waiter may
+      // have broken this corpse and acquired. That is why `removeIfHeldBy` is
+      // required to compare and delete atomically (see its doc comment) rather
+      // than being handed a "delete if this is still there" hint it can act on
+      // late — the atomicity is what makes at most one waiter break one corpse.
+      // The entrant is then decided only by `createIfAbsent`, and the loser of
+      // that race loops, re-reads, and sees the winner's fresh stamp.
+      await io.removeIfHeldBy(held);
+      continue;
+    }
+    await sleep(retryDelayMs);
+  }
+}
+
+/**
+ * When the holder took the lock. An unreadable stamp reports epoch 0, i.e.
+ * immediately stale: a lock whose age cannot be established cannot be waited
+ * out honestly, and refusing to write provenance because of an unparseable
+ * scratch file would be the worse failure.
+ */
+function lockHeldSince(content: string): number {
+  try {
+    const parsed = JSON.parse(content) as { at?: unknown };
+    return typeof parsed.at === 'number' ? parsed.at : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * A per-key promise chain: `serialize(key, work)` starts `work` only after
+ * every earlier `work` for that key has settled (rejections included — one
+ * failed write must not wedge the queue).
+ *
+ * Each call returns its OWN map, so two independent callers can never collide
+ * on a key that happens to spell the same.
+ */
+export function createSerializer(): <T>(key: string, work: () => Promise<T>) => Promise<T> {
+  const tails = new Map<string, Promise<unknown>>();
+  return <T>(key: string, work: () => Promise<T>): Promise<T> => {
+    const previous = tails.get(key) ?? Promise.resolve();
+    const result = previous.then(work, work);
+    // Swallow only on the CHAIN copy — the returned promise still rejects.
+    const tail = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    tails.set(key, tail);
+    void tail.then(() => {
+      if (tails.get(key) === tail) tails.delete(key);
+    });
+    return result;
+  };
+}