@volter/twin 0.1.0 → 0.1.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@volter/twin",
-  "version": "0.1.0",
-  "description": "Local twins of SaaS APIs — the kernel + control plane: append-only event log, projection, mirror/simulator/fork modes, egress write-ledger, connectors, and the operator control plane (status/plan/lease/refs/queue/fork). Point your real vendor SDK at a faithful, stateful local replica.",
+  "version": "0.1.1",
+  "description": "Local twins of SaaS APIs \u2014 the kernel + control plane: append-only event log, projection, mirror/simulator/fork modes, egress write-ledger, connectors, and the operator control plane (status/plan/lease/refs/queue/fork). Point your real vendor SDK at a faithful, stateful local replica.",
   "keywords": [
     "twin",
     "local",
@@ -23,9 +23,8 @@
     "access": "public"
   },
   "files": [
-    "src",
-    "dist",
     "inject.cjs",
+    "src",
     "client",
     "test-fixtures",
     "README.md",
@@ -42,30 +41,21 @@
   "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/control-plane#readme",
   "type": "module",
   "exports": {
-    ".": {
-      "types": "./dist/src/index.d.ts",
-      "default": "./dist/src/index.js"
-    },
-    "./args": {
-      "types": "./dist/src/args.d.ts",
-      "default": "./dist/src/args.js"
-    },
-    "./schemas": {
-      "types": "./dist/src/schemas.d.ts",
-      "default": "./dist/src/schemas.js"
-    },
-    "./inject": "./inject.cjs"
+    ".": "./src/index.ts",
+    "./args": "./src/args.ts",
+    "./lifecycle": "./src/lifecycle.ts",
+    "./schemas": "./src/schemas.ts",
+    "./inject": "./inject.cjs",
+    "./attach": "./attach.cjs",
+    "./storage": "./src/storage.ts"
   },
   "bin": {
-    "volter-twin": "dist/src/cli.js"
+    "volter-twin": "src/cli.ts"
   },
   "scripts": {
     "cli": "bun run src/cli.ts",
     "test": "bun test src/*.test.ts",
-    "typecheck": "tsc --noEmit",
-    "build": "node scripts/build.mjs",
-    "prepack": "node scripts/prepare-publish.mjs prepack",
-    "postpack": "node scripts/prepare-publish.mjs postpack"
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "zod": "^4.4.2"

package/src/actions.ts

@@ -12,11 +12,12 @@
 // Projection = observed mirror, then apply each `set` transaction in order,
 // skipping any transaction that was reverted or confirmed.
 import { randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { buildShadowState } from './shadow.ts';
+import { buildShadowState, canonicalJson, hashFieldValue, remoteRefs, subjectKey } from './shadow.ts';
 import type { SubjectFields } from './shadow.ts';
-import { appendDurable, appendEvent, twinLog, withFileLock, worldPaths } from './storage.ts';
+import { appendDurable, appendEventLocked, eventsLockPath, projectionLockPath, twinLog, withFileLock, worldPaths } from './storage.ts';
+import { WorldServiceEventSchema } from './schemas.ts';
+import { getActiveWorldStore } from './world-store.ts';
 import type { WorldServiceEvent } from './types.ts';
 import type { TwinResource } from './serve.ts';
 
@@ -72,6 +73,8 @@ export type TwinAction = {
   // op 'confirm': the prior action id now reflected as an observed event.
   confirmsActionId?: string;
   observedEventId?: string;
+  /** Every observed row materialized by a compound confirmation; observedEventId is the primary. */
+  observedEventIds?: string[];
   /** Optional machine-readable hint for how a UI/pack should construct a revert. */
   revert?: TwinActionRevertSpec;
   /**
@@ -83,6 +86,16 @@ export type TwinAction = {
    * alone, with no dependence on actionId/pushId naming conventions.
    */
   correlationId?: string;
+  /**
+   * The action's MERGE BASE against the remote (runtime contract R14, non-fast-forward
+   * rule): per touched subject, the observed mirror's remote ref (shadow.ts remoteRefs)
+   * at authoring time — null when the mirror had never seen the subject. Stamped by the
+   * appenders on every `set` action; pushTransaction compares these refs again at push
+   * time and REFUSES when any has moved (someone else changed the remote), demanding
+   * fetch + reconcile. Authoring metadata like correlationId: excluded from replay
+   * identity, so an identical retry converges on the first commit's (older, safer) basis.
+   */
+  shadowBasis?: Record<string, string | null>;
 };
 export type TwinTransactionCommit = TwinAction;
 export type TwinTransactionCommitOp = TwinActionOp;
@@ -99,6 +112,7 @@ function actionsPath(service: string, root?: string): string {
   return join(dirname(worldPaths(service, root).events), 'actions.jsonl');
 }
 const actionsLock = (service: string, root?: string): string => `${actionsPath(service, root)}.lock`;
+const projectionLock = (service: string, root?: string): string => projectionLockPath(worldPaths(service, root));
 
 /** Every appended action carries a correlationId — generate one when the caller
  *  hasn't supplied it, so downstream joins (push ledger, logs) always have an id
@@ -108,33 +122,123 @@ function withCorrelationId(action: TwinAction): TwinAction {
   return action.correlationId ? action : { ...action, correlationId: randomUUID() };
 }
 
+/** Subjects a `set` action touches: its own subject, every projection resource, and every
+ *  precondition subject — a precondition established the action's validity against that
+ *  subject's state, so remote movement there is drift for this action too. */
+function touchedSubjects(action: TwinAction): Array<{ type: string; id: string }> {
+  const out = new Map<string, { type: string; id: string }>();
+  out.set(subjectKey(action.subject), action.subject);
+  for (const r of [
+    ...(action.projection?.creates ?? []),
+    ...(action.projection?.updates ?? []),
+    ...(action.projection?.deletes ?? []),
+  ]) out.set(subjectKey(r), { type: r.type, id: r.id });
+  for (const p of action.preconditions ?? []) out.set(subjectKey(p.subject), p.subject);
+  return [...out.values()];
+}
+
+/** Stamp the merge base (R14): every appended `set` action records the remote ref of each
+ *  subject it touches. Runs inside the appenders' projection lock, so the stamped refs
+ *  and the precondition evaluation see the same mirror. */
+function withShadowBasis(action: TwinAction, root?: string): TwinAction {
+  if (action.op !== 'set' || action.shadowBasis) return action;
+  return { ...action, shadowBasis: remoteRefs(action.service, touchedSubjects(action), root) };
+}
+
 function appendActionRaw(action: TwinAction, root?: string): void {
   const path = actionsPath(action.service, root);
-  mkdirSync(dirname(path), { recursive: true });
+  getActiveWorldStore().mkdir(dirname(path));
   appendDurable(path, `${JSON.stringify(action)}\n`);
   twinLog('action.append', { service: action.service, id: action.id, op: action.op, correlationId: action.correlationId });
 }
 
+function replayBody(action: TwinAction): string {
+  const { correlationId: _correlationId, shadowBasis: _shadowBasis, ...stampedBody } = action;
+  // A confirmation is content-addressed by the observed event ids. Its timestamp is observation
+  // metadata, just like the occurredAt/observedAt values that appendEvent ignores when replaying
+  // one content-addressed event. Two reconcilers confirming the same bytes at different wall-clock
+  // instants must therefore converge on the first durable confirmation rather than conflict.
+  const body = stampedBody.op === 'confirm'
+    ? (({ occurredAt: _occurredAt, ...confirmation }) => confirmation)(stampedBody)
+    : stampedBody;
+  return canonicalJson(body);
+}
+
+function existingExactAction(action: TwinAction, root?: string): TwinAction | undefined {
+  const existing = listActions(action.service, root).find((candidate) => candidate.id === action.id);
+  if (!existing) return undefined;
+  if (replayBody(existing) !== replayBody(action)) {
+    throw new Error(`Conflicting duplicate twin action: ${action.service}/${action.id}`);
+  }
+  return existing;
+}
+
 export function appendAction(action: TwinAction, root?: string): TwinAction {
-  const stamped = withCorrelationId(action);
-  assertPreconditions(stamped, root);
-  // Cross-process line-atomic append (same lock the dedup path uses, so writes from a
-  // backend + a browser proxy sharing one twin can't interleave or race a check-then-append).
-  withFileLock(actionsLock(stamped.service, root), () => appendActionRaw(stamped, root));
-  return stamped;
+  // Evaluate and append under the service projection and actions locks. A precondition is a
+  // compare-and-set, not an advisory validation: checking outside either lock would let another
+  // writer invalidate it before this action lands. The shadow basis is stamped under the same
+  // lock so the recorded merge base is the mirror the preconditions were checked against.
+  return withFileLock(projectionLock(action.service, root), () => withFileLock(actionsLock(action.service, root), () => {
+    const stamped = withShadowBasis(withCorrelationId(action), root);
+    assertPreconditions(stamped, root);
+    appendActionRaw(stamped, root);
+    return stamped;
+  }));
 }
 
-/** Append `action` only if no action with the same id already exists — the whole
- *  check-then-append runs under the actions lock, so it's atomic across processes (two
- *  concurrent identical writes converge to ONE action; distinct writes both land). */
+/** Append `action` only if no exact action with the same id already exists — the whole
+ *  replay/precondition/append decision runs under the service projection + actions locks, so it's
+ *  atomic across processes (two concurrent identical writes converge to ONE action; distinct
+ *  writes both land). A reused id with different content fails loudly. */
 export function appendActionIfAbsent(action: TwinAction, root?: string): { action: TwinAction; appended: boolean } {
-  const stamped = withCorrelationId(action);
-  assertPreconditions(stamped, root);
-  return withFileLock(actionsLock(stamped.service, root), () => {
-    const exists = listActions(stamped.service, root).some((a) => a.id === stamped.id);
-    if (!exists) appendActionRaw(stamped, root);
-    return { action: stamped, appended: !exists };
-  });
+  return withFileLock(projectionLock(action.service, root), () => withFileLock(actionsLock(action.service, root), () => {
+    const identified = withCorrelationId(action);
+    // An exact retry is already committed. Resolve it before re-evaluating author-time
+    // preconditions against the state that first commit intentionally changed — and
+    // before paying the basis stamp's event-log read (the replayed path stays cheap).
+    const existing = existingExactAction(identified, root);
+    if (existing) return { action: existing, appended: false };
+    const stamped = withShadowBasis(identified, root);
+    assertPreconditions(stamped, root);
+    appendActionRaw(stamped, root);
+    return { action: stamped, appended: true };
+  }));
+}
+
+export type AtomicActionDecision<T> =
+  | { kind: 'skip'; value: T }
+  | { kind: 'append'; action: TwinAction; value: T };
+
+/**
+ * Evaluate current projected state and optionally append one action under ONE service projection
+ * transaction (the shared projection lock plus the action-log lock). This is the narrow
+ * state-dependent seam for vendor operations whose acceptance and resulting fields depend on the
+ * latest observed + local projection (for example, immutable version publish).
+ *
+ * The callback must remain synchronous and side-effect free: it computes a decision from the
+ * supplied snapshot. Durable state changes only through the returned action, which this helper
+ * appends before releasing the lock.
+ */
+export function decideAndAppendAction<T>(
+  service: string,
+  decide: (resources: TwinResource[]) => AtomicActionDecision<T>,
+  root?: string,
+): { value: T; action?: TwinAction; appended: boolean } {
+  return withFileLock(projectionLock(service, root), () => withFileLock(actionsLock(service, root), () => {
+    const resources = projectResources(service, root);
+    const decision = decide(resources);
+    if (decision.kind === 'skip') return { value: decision.value, appended: false };
+    if (decision.action.service !== service) {
+      throw new Error(`Atomic action service mismatch: expected ${service}, got ${decision.action.service}`);
+    }
+    const identified = withCorrelationId(decision.action);
+    const existing = existingExactAction(identified, root);
+    if (existing) return { value: decision.value, action: existing, appended: false };
+    const stamped = withShadowBasis(identified, root);
+    assertPreconditionsAgainst(stamped, resources);
+    appendActionRaw(stamped, root);
+    return { value: decision.value, action: stamped, appended: true };
+  }));
 }
 
 export function appendTransactionCommit(commit: TwinTransactionCommit, root?: string): TwinTransactionCommit {
@@ -143,9 +247,8 @@ export function appendTransactionCommit(commit: TwinTransactionCommit, root?: st
 
 export function listActions(service: string, root?: string): TwinAction[] {
   const path = actionsPath(service, root);
-  if (!existsSync(path)) return [];
-  return readFileSync(path, 'utf8')
-    .split('\n')
+  return getActiveWorldStore()
+    .readLines(path)
     .filter((line) => line.trim())
     .map((line) => JSON.parse(line) as TwinAction);
 }
@@ -158,22 +261,38 @@ function projectedField(resource: TwinResource | undefined, field: string): unkn
   return resource[field];
 }
 
-function assertPreconditions(action: TwinAction, root?: string): void {
+/** The kernel's ONE deterministic check: does `actual` satisfy the precondition expression?
+ *  Shared by write-time preconditions (here), plan conflict detection (plan.ts) and changeset
+ *  verifiers (changeset.ts) — one evaluator, so a check means the same thing everywhere. */
+export function checkPrecondition(precondition: TwinActionPrecondition, actual: unknown): boolean {
+  switch (precondition.op) {
+    case 'exists': return actual !== undefined;
+    case 'not_exists': return actual === undefined;
+    case 'eq': case 'version_eq': return Object.is(actual, precondition.value);
+    case 'neq': return !Object.is(actual, precondition.value);
+    default: return false;
+  }
+}
+
+/** Look a precondition subject's field up in projected resources (undefined = no resource or
+ *  no field — exactly what `exists`/`not_exists` distinguish). */
+export function projectedPreconditionValue(precondition: TwinActionPrecondition, resources: TwinResource[]): unknown {
+  const resource = resources.find((r) => r.type === precondition.subject.type && r.id === precondition.subject.id);
+  return projectedField(resource, precondition.field);
+}
+
+function assertPreconditionsAgainst(action: TwinAction, resources: TwinResource[]): void {
   if (!action.preconditions?.length) return;
-  const resources = projectResources(action.service, root);
   for (const precondition of action.preconditions) {
-    const resource = resources.find((r) => r.type === precondition.subject.type && r.id === precondition.subject.id);
-    const actual = projectedField(resource, precondition.field);
-    const passes =
-      precondition.op === 'exists' ? actual !== undefined
-        : precondition.op === 'not_exists' ? actual === undefined
-          : precondition.op === 'eq' || precondition.op === 'version_eq' ? Object.is(actual, precondition.value)
-            : precondition.op === 'neq' ? !Object.is(actual, precondition.value)
-              : false;
-    if (!passes) throw new TwinActionPreconditionError(action.id, precondition);
+    const actual = projectedPreconditionValue(precondition, resources);
+    if (!checkPrecondition(precondition, actual)) throw new TwinActionPreconditionError(action.id, precondition);
   }
 }
 
+function assertPreconditions(action: TwinAction, root?: string): void {
+  assertPreconditionsAgainst(action, projectResources(action.service, root));
+}
+
 /**
  * Project the action log over the observed mirror → current twin resources.
  * `set` actions overlay fields (creating subjects that don't exist in the mirror);
@@ -234,30 +353,96 @@ export function confirmAction(opts: {
   actionId: string;
   subject: { type: string; id: string };
   fields: SubjectFields;
+  /** Additional observed resources confirmed by the same compound action. They are folded before
+   *  the primary subject, under the same service projection lock. */
+  additionalObservations?: Array<{ subject: { type: string; id: string }; fields: SubjectFields }>;
   occurredAt: string;
   root?: string;
-}): { observedEventId: string } {
-  const observedEventId = `confirmed:${opts.service}:${opts.subject.type}:${opts.subject.id}:${opts.actionId}`;
-  appendEvent(
-    {
+}): { observedEventId: string; observedEventIds: string[] } {
+  const observations = [
+    ...(opts.additionalObservations ?? []),
+    { subject: opts.subject, fields: opts.fields },
+  ];
+  const events = observations.map((observation) => {
+    // Content-address the observation, not merely the action. If a process crashes after writing
+    // observations but before the confirm row, a retry over newer mutable remote state appends a
+    // new observation instead of conflicting with the abandoned row's id.
+    const contentHash = hashFieldValue({ actionId: opts.actionId, subject: observation.subject, fields: observation.fields });
+    const observedEventId = `confirmed:${opts.service}:${observation.subject.type}:${observation.subject.id}:${opts.actionId}:${contentHash}`;
+    return WorldServiceEventSchema.parse({
       id: observedEventId,
       service: opts.service,
-      type: `${opts.service}.${opts.subject.type}.delta`,
+      type: `${opts.service}.${observation.subject.type}.delta`,
       schemaVersion: 1,
       idempotencyKey: observedEventId,
       occurredAt: opts.occurredAt,
       observedAt: opts.occurredAt,
       origin: 'external', // confirmed by the real vendor → an observed fact
-      subject: opts.subject,
-      data: { changed: Object.fromEntries(Object.entries(opts.fields).map(([k, v]) => [k, { after: v }])) },
-    } as unknown as WorldServiceEvent,
-    opts.root,
-  );
-  appendAction(
-    { id: `confirm:${opts.actionId}`, service: opts.service, op: 'confirm', subject: opts.subject, occurredAt: opts.occurredAt, confirmsActionId: opts.actionId, observedEventId },
-    opts.root,
-  );
-  return { observedEventId };
+      subject: observation.subject,
+      data: { changed: Object.fromEntries(Object.entries(observation.fields).map(([k, v]) => [k, { after: v }])) },
+    }) as WorldServiceEvent;
+  });
+  const observedEventIds = events.map((event) => event.id);
+  const observedEventId = observedEventIds.at(-1)!;
+  const paths = worldPaths(opts.service, opts.root);
+  const confirm: TwinAction = {
+    id: `confirm:${opts.actionId}:${hashFieldValue(observedEventIds)}`,
+    service: opts.service,
+    op: 'confirm',
+    subject: opts.subject,
+    occurredAt: opts.occurredAt,
+    confirmsActionId: opts.actionId,
+    observedEventId,
+    observedEventIds,
+  };
+  // One outer projection lock prevents local decisions or connector observations from observing
+  // an in-process half-confirm. The writes remain separate append-only rows, so crash recovery is
+  // deliberately idempotent: every event and the confirm action have content-addressed ids.
+  withFileLock(projectionLock(opts.service, opts.root), () => {
+    withFileLock(eventsLockPath(paths), () => {
+      for (const event of events) appendEventLocked(event, paths);
+    });
+    withFileLock(actionsLock(opts.service, opts.root), () => {
+      const stamped = withCorrelationId(confirm);
+      if (!existingExactAction(stamped, opts.root)) appendActionRaw(stamped, opts.root);
+    });
+  });
+  return { observedEventId, observedEventIds };
+}
+
+export type RevertOutcome =
+  | { status: 'reverted'; revertId: string }
+  | { status: 'already-reverted' }
+  | { status: 'confirmed' }
+  | { status: 'not-found' }
+  | { status: 'not-revertable'; op: TwinActionOp };
+
+/**
+ * Revert one pending `set` action — decision AND append under the service projection +
+ * actions locks, so a concurrent writer (a connector confirming the same action from
+ * another process) cannot land between the check and the revert: the whole read-decide-
+ * append is ONE critical section. Idempotent: a repeat answers 'already-reverted'.
+ * Only `set` rows are revertable — reverting a revert or a confirm is a category error.
+ */
+export function revertAction(opts: { service: string; actionId: string; occurredAt: string; root?: string }): RevertOutcome {
+  return withFileLock(projectionLock(opts.service, opts.root), () => withFileLock(actionsLock(opts.service, opts.root), (): RevertOutcome => {
+    const all = listActions(opts.service, opts.root);
+    const target = all.find((a) => a.id === opts.actionId);
+    if (target === undefined) return { status: 'not-found' };
+    if (target.op !== 'set') return { status: 'not-revertable', op: target.op };
+    if (all.some((a) => a.op === 'confirm' && a.confirmsActionId === opts.actionId)) return { status: 'confirmed' };
+    if (all.some((a) => a.op === 'revert' && a.revertsActionId === opts.actionId)) return { status: 'already-reverted' };
+    const revert: TwinAction = withCorrelationId({
+      id: `revert:${opts.actionId}`,
+      service: opts.service,
+      op: 'revert',
+      subject: target.subject,
+      occurredAt: opts.occurredAt,
+      revertsActionId: opts.actionId,
+    });
+    appendActionRaw(revert, opts.root);
+    return { status: 'reverted', revertId: revert.id };
+  }));
 }
 
 /** Local pending actions (set, not reverted, not yet confirmed) — the divergence from the mirror. */

package/src/blob-store.ts

@@ -0,0 +1,136 @@
+// THE BLOB SEAM (runtime contract R11) — byte storage behind every handler that touches
+// raw bytes (slack file uploads, jira attachments), so a serverless namespace can put its
+// bytes in object storage while local worlds keep today's on-disk layout unchanged.
+//
+// Why bytes get their OWN seam instead of riding WorldStore: WorldStore is string-typed by
+// design (JSONL rows, JSON sidecars — the hydrate/flush snapshot is a path→string map), and
+// blob bytes must never enter that snapshot: they can be large, they never participate in
+// preconditions or projection, and they are served/accepted at the edge. Blob KEYS live in
+// string state; bytes live here. That separation is what keeps namespace snapshots small
+// enough for a Durable Object's memory (runtime contract R11–R14).
+//
+// ASYNC-NATIVE, unlike WorldStore: the sync kernel never reads blobs mid-projection — bytes
+// are read/written at the request edge (upload accept, download serve), which is already
+// async in every server. So there is no hydrate-whole-namespace step for blobs and no sync
+// constraint to honor: an R2/S3 adapter implements this interface directly, per request.
+//
+// Keys are PATHS (the FsWorldStore convention): the fs backend uses them verbatim on disk,
+// so packs keep computing today's exact layout (…/resources/blobs/sha256/<ab>/<hex>) and
+// local worlds change NOTHING — scrub, backup, and inspection all still see the same tree.
+// A remote adapter maps the path to an object key (namespace prefix + path).
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export interface BlobStore {
+  /** Bytes at `key`, or null when absent. Never throws for a missing key. */
+  get(key: string): Promise<Uint8Array | null>;
+  /** Store bytes at `key`, atomically (a reader never observes a torn blob). Creating
+   *  parent "directories" is the store's job; idempotent overwrite is allowed (content-
+   *  addressed callers never rewrite different bytes under one key). */
+  put(key: string, bytes: Uint8Array): Promise<void>;
+  exists(key: string): Promise<boolean>;
+  /** Remove the blob (or, for a prefix ending in '/', everything under it — namespace
+   *  reset uses this). A missing key is not an error. */
+  remove(key: string): Promise<void>;
+  /** Keys currently stored under `prefix` (full keys, sorted). Lifecycle/reset tooling
+   *  only — the serve path addresses blobs by exact key. */
+  list(prefix: string): Promise<string[]>;
+  /** Byte size at `key`, or null when absent. */
+  size(key: string): Promise<number | null>;
+}
+
+/** Today's layout, verbatim: keys are filesystem paths. */
+export class FsBlobStore implements BlobStore {
+  async get(key: string): Promise<Uint8Array | null> {
+    if (!existsSync(key)) return null;
+    return new Uint8Array(readFileSync(key));
+  }
+  async put(key: string, bytes: Uint8Array): Promise<void> {
+    mkdirSync(dirname(key), { recursive: true });
+    // Write-then-rename so a crash mid-write never leaves a truncated blob that a
+    // content-addressed caller would forever report as present (the slack-blobs rule,
+    // now the seam's rule).
+    const tmp = `${key}.tmp.${process.pid}`;
+    writeFileSync(tmp, bytes);
+    renameSync(tmp, key);
+  }
+  async exists(key: string): Promise<boolean> {
+    return existsSync(key);
+  }
+  async remove(key: string): Promise<void> {
+    rmSync(key, { force: true, recursive: key.endsWith('/') });
+  }
+  async list(prefix: string): Promise<string[]> {
+    const out: string[] = [];
+    const walk = (dir: string): void => {
+      if (!existsSync(dir)) return;
+      for (const name of readdirSync(dir, { withFileTypes: true })) {
+        const child = join(dir, name.name);
+        if (name.isDirectory()) walk(child);
+        else if (!name.name.includes('.tmp.')) out.push(child);
+      }
+    };
+    walk(prefix.replace(/\/$/, ''));
+    return out.sort();
+  }
+  async size(key: string): Promise<number | null> {
+    if (!existsSync(key)) return null;
+    return statSync(key).size;
+  }
+}
+
+/** In-memory backend — tests and hydration rehearsals; also the shape an R2/S3 adapter
+ *  implements (same interface, object keys instead of paths). */
+export class MemoryBlobStore implements BlobStore {
+  private blobs = new Map<string, Uint8Array>();
+  async get(key: string): Promise<Uint8Array | null> {
+    const bytes = this.blobs.get(key);
+    return bytes === undefined ? null : new Uint8Array(bytes);
+  }
+  async put(key: string, bytes: Uint8Array): Promise<void> {
+    this.blobs.set(key, new Uint8Array(bytes));
+  }
+  async exists(key: string): Promise<boolean> {
+    return this.blobs.has(key);
+  }
+  async remove(key: string): Promise<void> {
+    if (key.endsWith('/')) {
+      for (const k of [...this.blobs.keys()]) if (k.startsWith(key)) this.blobs.delete(k);
+    } else this.blobs.delete(key);
+  }
+  async list(prefix: string): Promise<string[]> {
+    return [...this.blobs.keys()].filter((k) => k.startsWith(prefix.replace(/\/$/, ''))).sort();
+  }
+  async size(key: string): Promise<number | null> {
+    return this.blobs.get(key)?.length ?? null;
+  }
+}
+
+/** Content-address helper shared by byte-carrying packs: sha256 hex of the bytes. */
+export function blobDigest(bytes: Uint8Array): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+// Active-store scoping, the world-store.ts pattern exactly: default fs; a serverless entry
+// (or a test) swaps in its adapter for the scope of a request.
+let activeBlobStore: BlobStore = new FsBlobStore();
+
+export function getActiveBlobStore(): BlobStore {
+  return activeBlobStore;
+}
+
+export function setActiveBlobStore(store: BlobStore): BlobStore {
+  const previous = activeBlobStore;
+  activeBlobStore = store;
+  return previous;
+}
+
+export async function withBlobStore<T>(store: BlobStore, fn: () => Promise<T> | T): Promise<T> {
+  const previous = setActiveBlobStore(store);
+  try {
+    return await fn();
+  } finally {
+    setActiveBlobStore(previous);
+  }
+}