@volter/twin 0.1.0 → 0.1.1

package/src/storage.ts

@@ -1,10 +1,9 @@
-import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
-import { hostname } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import {
   GenericWorldStateSchema,
   WorldServiceEventSchema,
 } from './schemas.ts';
+import { getActiveWorldStore } from './world-store.ts';
 import type {
   AppendEventResult,
   CommitQueuedEventsResult,
@@ -45,8 +44,23 @@ function assertServiceName(service: string): string {
   return service;
 }
 
+/**
+ * IDENTITY SEAM for the request journal (serve.ts). `worldPaths` is the single funnel every
+ * state read/write in every pack goes through, so it is also the one place a twin says, in its
+ * own words, WHO it is (`service`) and WHERE its state lives (`root`) — the two things an HTTP
+ * layer that only sees `Bun.serve({fetch})` cannot know. serve.ts installs an observer here so
+ * the journal it writes lands beside that twin's `actions.jsonl` instead of guessing a root.
+ * Nothing else may use this: it is a one-slot observability hook, never a control seam.
+ */
+let worldPathsObserver: ((service: string, root: string | undefined) => void) | undefined;
+
+export function observeWorldPaths(observer: (service: string, root: string | undefined) => void): void {
+  worldPathsObserver = observer;
+}
+
 export function worldPaths(service: string, root?: string): WorldPaths {
   const safeService = assertServiceName(service);
+  worldPathsObserver?.(safeService, root);
   const resolvedRoot = projectRoot(root);
   const dir = join(worldStateRoot(root), safeService);
   return {
@@ -63,9 +77,8 @@ export function worldPaths(service: string, root?: string): WorldPaths {
 }
 
 function readJsonl<T>(path: string): T[] {
-  if (!existsSync(path)) return [];
   const rows: T[] = [];
-  for (const [index, line] of readFileSync(path, 'utf8').split('\n').entries()) {
+  for (const [index, line] of getActiveWorldStore().readLines(path).entries()) {
     if (!line.trim()) continue;
     try {
       rows.push(JSON.parse(line) as T);
@@ -81,7 +94,9 @@ function readJsonl<T>(path: string): T[] {
  *  file that is expected to exist; guard with existsSync first when absence is allowed. */
 export function readJsonFile<T>(path: string): T {
   try {
-    return JSON.parse(readFileSync(path, 'utf8')) as T;
+    const raw = getActiveWorldStore().read(path);
+    if (raw === null) throw new Error('no such file');
+    return JSON.parse(raw) as T;
   } catch (error) {
     throw new Error(`${path}: invalid JSON: ${(error as Error).message}`);
   }
@@ -100,17 +115,11 @@ export function readJsonFile<T>(path: string): T {
  * fsync per append. See ARCHITECTURE.md D1.
  */
 export function appendDurable(path: string, data: string): void {
-  const fd = openSync(path, 'a');
-  try {
-    appendFileSync(fd, data);
-    if (process.env.VOLTER_DURABLE === '1') fsyncSync(fd);
-  } finally {
-    closeSync(fd);
-  }
+  getActiveWorldStore().append(path, data);
 }
 
 /**
- * Opt-in structured stderr logging for the audit trail (ARCHITECTURE-REVIEW-TODOS D3):
+ * Opt-in structured stderr logging for the audit trail (the July 2026 architecture review, row D3):
  * one line per action-log append and per push-ledger row, so "who reviewed the change
  * that caused this real write" is mechanically greppable from a single log stream via
  * `correlationId`. Off by default — mirrors the VOLTER_DURABLE opt-in policy above: no
@@ -122,121 +131,22 @@ export function twinLog(kind: string, details: Record<string, unknown>): void {
 }
 
 function appendJsonl(path: string, value: unknown): void {
-  mkdirSync(dirname(path), { recursive: true });
-  appendDurable(path, `${JSON.stringify(value)}\n`);
-}
-
-function sleepSync(ms: number): void {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-
-/** How long a lock may live before an acquirer treats it as abandoned. Above the 10s
- *  wait timeout so a live-but-slow holder is never reclaimed out from under itself. */
-const LOCK_STALE_MS = 60_000;
-
-type LockHolder = { pid: number; hostname: string; at: string };
-
-function readLockHolder(lockPath: string): LockHolder | null {
-  try {
-    return JSON.parse(readFileSync(lockPath, 'utf8')) as LockHolder;
-  } catch {
-    return null; // missing, empty (mid-write), or malformed
-  }
-}
-
-function pidAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    // ESRCH → no such process (dead); EPERM → exists but not ours to signal (alive)
-    return (error as NodeJS.ErrnoException).code === 'EPERM';
-  }
-}
-
-/** A lock is stale when its holder is provably gone (same host + dead pid) or it has
- *  outlived LOCK_STALE_MS. The age falls back to the lockfile's own mtime when the
- *  `at` record is unreadable — so a writer that crashed between creating the lock and
- *  recording itself is still eventually reclaimed, while a freshly-created (recent
- *  mtime) empty lock is left alone, avoiding a race with the live writer. */
-function lockIsStale(lockPath: string): boolean {
-  const holder = readLockHolder(lockPath);
-  if (holder && holder.hostname === hostname() && Number.isInteger(holder.pid) && !pidAlive(holder.pid)) {
-    return true;
-  }
-  const recordedAt = holder && typeof holder.at === 'string' ? Date.parse(holder.at) : NaN;
-  let stamp = recordedAt;
-  if (!Number.isFinite(stamp)) {
-    try {
-      stamp = statSync(lockPath).mtimeMs;
-    } catch {
-      return false; // lock vanished — let the next openSync settle it
-    }
-  }
-  return Date.now() - stamp > LOCK_STALE_MS;
+  const store = getActiveWorldStore();
+  store.mkdir(dirname(path));
+  store.append(path, `${JSON.stringify(value)}\n`);
 }
 
-/** Run `fn` holding an exclusive cross-process file lock (the same primitive the event log
- *  uses). Used to make read-then-append critical sections atomic across processes. The
- *  lockfile records `{pid, hostname, at}`; a contender that finds a stale lock (dead pid or
- *  age > LOCK_STALE_MS) reclaims it by atomically renaming it aside — so a crashed holder
- *  can't wedge the world forever. Reclaim is race-safe: only the process that wins the
- *  rename clears the stale inode, and the exclusive `wx` create still decides the winner. */
+/** Run `fn` holding an exclusive cross-process lock, via the active store. On the fs
+ *  store this is the reclaimable file lock the event log uses; on an in-memory,
+ *  single-instance store it is a synchronous pass-through. Used to make read-then-append
+ *  critical sections atomic. Public so world-runtime can guard concurrent `upWorld`
+ *  claims of one instance dir with the SAME lock semantics the event log uses (TWIN-36). */
 export function withFileLock<T>(lockPath: string, fn: () => T): T {
-  mkdirSync(dirname(lockPath), { recursive: true });
-  const started = Date.now();
-  let fd: number | null = null;
-  while (fd === null) {
-    try {
-      fd = openSync(lockPath, 'wx');
-    } catch (error) {
-      const code = (error as NodeJS.ErrnoException).code;
-      if (code !== 'EEXIST') throw error;
-      if (lockIsStale(lockPath)) {
-        const holder = readLockHolder(lockPath);
-        const salvage = `${lockPath}.stale.${process.pid}.${Date.now()}`;
-        try {
-          renameSync(lockPath, salvage);
-        } catch (renameError) {
-          if ((renameError as NodeJS.ErrnoException).code === 'ENOENT') continue; // another contender reclaimed it
-          throw renameError;
-        }
-        console.warn(
-          `[world] reclaiming stale storage lock ${lockPath} (held by pid ${holder?.pid ?? '?'} on ${holder?.hostname ?? '?'} since ${holder?.at ?? 'unknown'})`,
-        );
-        try {
-          unlinkSync(salvage);
-        } catch { /* the moved-aside stale inode; safe to leave if unlink fails */ }
-        continue; // retry the exclusive create immediately
-      }
-      if (Date.now() - started > 10_000) {
-        throw new Error(`Timed out waiting for world storage lock: ${lockPath}`);
-      }
-      sleepSync(25);
-    }
-  }
-
-  // Record the holder so a later contender can detect staleness. Best-effort: a write
-  // failure here doesn't weaken exclusivity, only staleness diagnostics.
-  try {
-    writeFileSync(fd, `${JSON.stringify({ pid: process.pid, hostname: hostname(), at: new Date().toISOString() } satisfies LockHolder)}\n`);
-  } catch { /* ignore */ }
-
-  try {
-    return fn();
-  } finally {
-    closeSync(fd);
-    try {
-      unlinkSync(lockPath);
-    } catch { /* already reclaimed by a stale-lock sweep */ }
-  }
+  return getActiveWorldStore().withLock(lockPath, fn);
 }
 
 function writeJsonAtomic(path: string, value: unknown): void {
-  mkdirSync(dirname(path), { recursive: true });
-  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
-  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
-  renameSync(tmp, path);
+  getActiveWorldStore().writeAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
 }
 
 export function listEvents(service: string, root?: string): WorldServiceEvent[] {
@@ -264,8 +174,8 @@ type EventsIndex = { size: number; mtimeMs: number; ids: Set<string>; keys: Set<
 const eventsIndexCache = new Map<string, EventsIndex>();
 
 function eventsFileStamp(eventsPath: string): { size: number; mtimeMs: number } {
-  if (!existsSync(eventsPath)) return { size: 0, mtimeMs: 0 };
-  const stat = statSync(eventsPath);
+  const stat = getActiveWorldStore().stat(eventsPath);
+  if (!stat) return { size: 0, mtimeMs: 0 };
   return { size: stat.size, mtimeMs: stat.mtimeMs };
 }
 
@@ -293,10 +203,11 @@ function findEventRow(eventsPath: string, id: string, idempotencyKey: string): W
 }
 
 function ensureEventDirs(paths: WorldPaths): void {
-  mkdirSync(paths.dir, { recursive: true });
-  mkdirSync(paths.resources, { recursive: true });
-  mkdirSync(paths.cursors, { recursive: true });
-  mkdirSync(paths.ingests, { recursive: true });
+  const store = getActiveWorldStore();
+  store.mkdir(paths.dir);
+  store.mkdir(paths.resources);
+  store.mkdir(paths.cursors);
+  store.mkdir(paths.ingests);
 }
 
 /** Exported so other modules that share a service's events log (e.g. egress.ts,
@@ -306,6 +217,16 @@ export function eventsLockPath(paths: WorldPaths): string {
   return join(paths.dir, 'events.jsonl.lock');
 }
 
+/**
+ * Serializes mutations that can change a service's projected state, regardless of whether the
+ * durable row lands in events.jsonl or actions.jsonl. The per-log locks still protect their own
+ * append/dedupe mechanics; this outer lock makes a projection-based decision linearizable against
+ * connector observations as well as local actions.
+ */
+export function projectionLockPath(paths: WorldPaths): string {
+  return join(paths.dir, 'projection.lock');
+}
+
 /**
  * The append body, assuming the caller already holds `eventsLockPath(paths)`. Split
  * out so `commitQueuedEvents` can run a whole batch of appends (and the rebuild that
@@ -355,7 +276,8 @@ export function appendEvent(event: WorldServiceEvent, root?: string): AppendEven
   const parsed = WorldServiceEventSchema.parse(event);
   const paths = worldPaths(parsed.service, root);
   ensureEventDirs(paths);
-  return withFileLock(eventsLockPath(paths), () => appendEventLocked(parsed, paths));
+  return withFileLock(projectionLockPath(paths), () =>
+    withFileLock(eventsLockPath(paths), () => appendEventLocked(parsed, paths)));
 }
 
 function queuedEventId(event: WorldServiceEvent): string {
@@ -373,8 +295,9 @@ export function enqueueEvent(
 ): EnqueueEventResult {
   const parsed = WorldServiceEventSchema.parse(event);
   const paths = worldPaths(parsed.service, options.root);
-  mkdirSync(paths.dir, { recursive: true });
-  mkdirSync(paths.ingests, { recursive: true });
+  const store = getActiveWorldStore();
+  store.mkdir(paths.dir);
+  store.mkdir(paths.ingests);
   const queued: QueuedWorldServiceEvent = {
     id: options.id ?? queuedEventId(parsed),
     service: parsed.service,
@@ -417,7 +340,7 @@ export function commitQueuedEvents(
   const queued = listQueuedEvents(service, options.root).sort((a, b) => a.event.occurredAt.localeCompare(b.event.occurredAt) || a.receivedAt.localeCompare(b.receivedAt) || a.id.localeCompare(b.id));
   const limit = options.limit ?? queued.length;
 
-  return withFileLock(eventsLockPath(paths), () => {
+  return withFileLock(projectionLockPath(paths), () => withFileLock(eventsLockPath(paths), () => {
     let committed = 0;
     let skipped = 0;
     const eventIds: string[] = [];
@@ -433,7 +356,7 @@ export function commitQueuedEvents(
     }
     if (committed > 0) rebuildGenericState(service, options.root);
     return { service, queued: Math.min(queued.length, limit), committed, skipped, eventIds };
-  });
+  }));
 }
 
 // NOTE: annotation read/write (listAnnotations/addAnnotation/createAnnotation) moved
@@ -486,7 +409,7 @@ export function rebuildGenericState(service: string, root?: string): GenericWorl
 
 export function loadState<T = unknown>(service: string, root?: string): T | null {
   const paths = worldPaths(service, root);
-  if (!existsSync(paths.state)) return null;
+  if (!getActiveWorldStore().exists(paths.state)) return null;
   return readJsonFile<T>(paths.state);
 }
 
@@ -528,7 +451,7 @@ export type ScrubResult = {
  *  use. storage.ts itself only accounts for events.jsonl/event-queue.jsonl/
  *  state.json/resources/cursors/ingests; the rest are written by other modules
  *  that share the same service dir (actions.ts, pushLedger.ts, plan.ts, lease.ts,
- *  refs.ts, fork.ts, queueLifecycle.ts) — this set MUST stay in sync with every
+ *  refs.ts, fork.ts, queueLifecycle.ts, and connector-owned coordination) — this set MUST stay in sync with every
  *  one of them so scrubService never demands --force for an ordinary twin. */
 const KNOWN_SERVICE_ENTRIES = new Set([
   'events.jsonl',
@@ -555,6 +478,9 @@ const KNOWN_SERVICE_ENTRIES = new Set([
   // refs.ts: remote/local checkpoint refs, under refs/remote/<provider>/<name>.json
   // and refs/local/<forkId>.json.
   'refs',
+  // Vendor connectors may keep private, non-secret workflow leases and monotone observation clocks
+  // here when an async provider span must be serialized across processes.
+  'connector-workflows',
 ]);
 
 function isKnownServiceEntry(name: string): boolean {
@@ -565,29 +491,32 @@ function isKnownServiceEntry(name: string): boolean {
  *  storage.ts is known to create. A directory that doesn't exist yet trivially
  *  looks fine (scrub will just no-op on it). */
 function looksLikeServiceStateDir(dir: string): boolean {
-  if (!existsSync(dir)) return true;
-  return readdirSync(dir).every((entry) => isKnownServiceEntry(entry));
+  const store = getActiveWorldStore();
+  if (!store.exists(dir)) return true;
+  return store.list(dir).every((entry) => isKnownServiceEntry(entry));
 }
 
 /** The whole world dir "looks like" ours when every entry in it is itself a
  *  directory that looks like a service state dir (each service gets one subdir
  *  under worldStateRoot — see worldPaths). */
 function looksLikeWorldStateDir(dir: string): boolean {
-  if (!existsSync(dir)) return true;
-  return readdirSync(dir).every((entry) => {
+  const store = getActiveWorldStore();
+  if (!store.exists(dir)) return true;
+  return store.list(dir).every((entry) => {
     const full = join(dir, entry);
-    return statSync(full).isDirectory() && looksLikeServiceStateDir(full);
+    return (store.stat(full)?.isDirectory ?? false) && looksLikeServiceStateDir(full);
   });
 }
 
 /** Every file under `dir`, path relative to `dir`, depth-first. Used to report
  *  exactly what scrub is about to remove before it removes it. */
 function listFilesRecursive(dir: string, base: string = dir): string[] {
-  if (!existsSync(dir)) return [];
+  const store = getActiveWorldStore();
+  if (!store.exists(dir)) return [];
   const out: string[] = [];
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) out.push(...listFilesRecursive(full, base));
+  for (const name of store.list(dir)) {
+    const full = join(dir, name);
+    if (store.stat(full)?.isDirectory) out.push(...listFilesRecursive(full, base));
     else out.push(full.slice(base.length + 1));
   }
   return out;
@@ -599,7 +528,8 @@ function scrubDir(
   looksLike: (d: string) => boolean,
   options: { force?: boolean },
 ): ScrubResult {
-  if (!existsSync(dir)) {
+  const store = getActiveWorldStore();
+  if (!store.exists(dir)) {
     return { target: dir, removed: [], message: `nothing to scrub: ${label} (${dir}) does not exist` };
   }
   if (!options.force && !looksLike(dir)) {
@@ -609,7 +539,7 @@ function scrubDir(
     );
   }
   const removed = listFilesRecursive(dir);
-  rmSync(dir, { recursive: true, force: true });
+  store.remove(dir);
   return { target: dir, removed, message: `scrubbed ${label}: removed ${removed.length} file(s) under ${dir}` };
 }
 
@@ -629,4 +559,3 @@ export function scrubWorld(options: { root?: string; force?: boolean } = {}): Sc
   const dir = worldStateRoot(options.root);
   return scrubDir(dir, 'entire world state dir', looksLikeWorldStateDir, options);
 }
-

package/src/sync.ts

@@ -23,15 +23,26 @@ import { performExternalWrite } from './egress.ts';
 import type { EgressWriteResult } from './egress.ts';
 import { acquireLease, releaseLease } from './lease.ts';
 import type { WorldRemoteRef } from './refs.ts';
-import { buildShadowState, recordObservedDelta } from './shadow.ts';
+import { NonFastForwardPushError } from './pushLedger.ts';
+import { buildShadowState, recordObservedDeltaLocked, remoteRefs } from './shadow.ts';
 import type { SubjectFields } from './shadow.ts';
+import { eventsLockPath, projectionLockPath, twinLog, withFileLock, worldPaths } from './storage.ts';
 import { twinResources } from './serve.ts';
 import type { TwinResource } from './serve.ts';
 import { reconcileRequiresApproval } from './reconcile.ts';
 import type { ReconcilePlan } from './reconcile.ts';
 
 // A resource observed from (or destined for) the real vendor.
-export type SyncResource = { type: string; id: string; fields: SubjectFields };
+export type SyncResource = {
+  type: string;
+  id: string;
+  fields: SubjectFields;
+  /** When the PROVIDER says this resource last changed. One pull can carry subjects of
+   *  different ages — a comment written an hour ago rides the same poll as the issue it
+   *  hangs off — and the poll clock would date them all alike, so a resource that knows
+   *  its own instant says so here and the pull's `occurredAt` covers only the rest. */
+  occurredAt?: string;
+};
 
 export type PullResult = { observed: number; deltasAppended: number; unchanged: number };
 
@@ -41,6 +52,11 @@ export type PullResult = { observed: number; deltasAppended: number; unchanged:
  * is the pure fold. Only changed fields produce a delta (recordObservedDelta is
  * a no-op when nothing differs), so re-pulling identical state appends nothing.
  *
+ * `occurredAt` here is the POLL's instant — the fallback for resources that carry no
+ * provider timestamp of their own. A resource that does (`SyncResource.occurredAt`)
+ * dates its own delta, because a consumer ordering a feed wants the moment the vendor
+ * changed the thing, not the moment we happened to look.
+ *
  * `redact` (TWIN-45 dev/01 — implemented, not just documented) is an optional
  * transform applied to each resource BEFORE it is folded into the event log, so
  * a sensitive field never lands on disk in the first place — a redact-on-pull
@@ -60,22 +76,25 @@ export function syncPull(opts: {
   redact?: (resource: SyncResource) => SyncResource;
 }): PullResult {
   const { service, resources, occurredAt, root } = opts;
-  let deltasAppended = 0;
-  let unchanged = 0;
-  // Rebuild the shadow once; recordObservedDelta appends to the log and the next
-  // build reflects it, so process sequentially.
-  for (const raw of resources) {
-    const res = opts.redact ? opts.redact(raw) : raw;
+  const paths = worldPaths(service, root);
+  // One connector pull is one observed snapshot. Keep every resource delta under the same outer
+  // projection lock so a state-dependent local write cannot interleave halfway through it.
+  return withFileLock(projectionLockPath(paths), () => withFileLock(eventsLockPath(paths), () => {
+    let deltasAppended = 0;
+    let unchanged = 0;
     const shadow = buildShadowState(service, () => null, root);
-    const result = recordObservedDelta(
-      shadow,
-      { service, subject: { type: res.type, id: res.id }, observed: res.fields, occurredAt, ...(opts.actor ? { actor: opts.actor } : {}) },
-      root,
-    );
-    if (result.changed) deltasAppended += 1;
-    else unchanged += 1;
-  }
-  return { observed: resources.length, deltasAppended, unchanged };
+    for (const raw of resources) {
+      const res = opts.redact ? opts.redact(raw) : raw;
+      const result = recordObservedDeltaLocked(
+        shadow,
+        { service, subject: { type: res.type, id: res.id }, observed: res.fields, occurredAt: res.occurredAt ?? occurredAt, ...(opts.actor ? { actor: opts.actor } : {}) },
+        paths,
+      );
+      if (result.changed) deltasAppended += 1;
+      else unchanged += 1;
+    }
+    return { observed: resources.length, deltasAppended, unchanged };
+  }));
 }
 
 export type PushItemResult = { id: string; type: string; status: EgressWriteResult['status']; externalId?: string };
@@ -117,11 +136,38 @@ export async function syncPush(opts: {
   approve: boolean;
   root?: string;
   actor?: { kind: 'agent' | 'human' | 'bot' | 'system'; id?: string };
+  /** R14 non-fast-forward gate. Capture with `remoteRefs(service, subjects, root, 'raw')`
+   *  AT THE MOMENT the plan's `real` input was pulled, and pass the map here. Before any
+   *  write, every toPush subject's ref is re-read in the SAME raw mode — a plan is stale
+   *  the moment ANY mirror event lands after its pull, our own push confirmations
+   *  included (a pushTransaction that confirmed between capture and push moved the
+   *  remote; this plan's fields predate it). Any moved ref, or any toPush subject the
+   *  capture did not cover (fail-closed: unknown base = no claim), refuses the WHOLE push
+   *  before the lease is acquired or `write` is called — zero side effects.
+   *  Omitted = ungated (pre-R14 callers), logged. */
+  expectedRefs?: Record<string, string | null>;
 }): Promise<PushResult> {
   const { service, plan, write, root } = opts;
   if (reconcileRequiresApproval(plan) && !opts.approve) {
     throw new Error(`sync push for ${service} requires approval (unresolved conflicts, or a twin-wins push overwriting a real-side change); pass approve:true to push`);
   }
+  if (opts.expectedRefs !== undefined) {
+    const uncovered = plan.toPush.map((item) => `${item.type}:${item.id}`).filter((key) => !(key in opts.expectedRefs!));
+    if (uncovered.length > 0) {
+      throw new Error(`sync push for ${service}: expectedRefs covers no base for ${uncovered.join(', ')} — re-capture refs (remoteRefs …, 'raw') for every toPush subject`);
+    }
+    const current = remoteRefs(service, plan.toPush.map((item) => ({ type: item.type, id: item.id })), root, 'raw');
+    const drifted: Record<string, { base: string | null; current: string | null }> = {};
+    for (const item of plan.toPush) {
+      const key = `${item.type}:${item.id}`;
+      if (current[key] !== opts.expectedRefs[key]) {
+        drifted[key] = { base: opts.expectedRefs[key] ?? null, current: current[key] ?? null };
+      }
+    }
+    if (Object.keys(drifted).length > 0) throw new NonFastForwardPushError(`sync-push:${service}`, drifted);
+  } else {
+    twinLog('sync.push.ungated', { service, items: plan.toPush.length });
+  }
   const lease = acquireLease({
     service, provider: opts.remoteRef.provider, remoteRef: opts.remoteRef, planId: `sync-push:${service}`,
     holder: opts.holder, id: opts.leaseId, acquiredAt: opts.acquiredAt, expiresAt: opts.expiresAt, root,

package/src/twin-fetch.ts

@@ -0,0 +1,115 @@
+// THE ONE HTTP ADAPTATION (runtime contract R12b): most packs' serve path is the same
+// ~20 lines of glue — the keyless GET /twin manifest door, the body read, a header map,
+// the dispatch into `handle<Vendor>TwinRequest` with the WORLD instant, and a JSON
+// response. That glue is a MECHANISM, so it lives here once; a pack's differences are
+// VALUES (its manifest, its header threading, its static handler options, its extra
+// response headers). A pack whose wire genuinely exceeds this shape (SSE streaming,
+// multipart adaptation, raw-bytes responses) writes its own fetch instead — openai is
+// that reference; this adapter is the reference for everyone else.
+//
+// Workerd-clean by construction: no Bun APIs, no fs, no clock but worldNow() — the same
+// closure serves under Bun.serve locally and mounted in-process on Cloudflare.
+import { worldNow } from './world-clock.ts';
+
+export type TwinFetchHandlerResult = {
+  status: number;
+  body: unknown;
+  headers?: Record<string, string>;
+};
+
+/** The common handler request shape. Extra vendor fields ride `handlerOptions` (static,
+ *  per instance) and `extras` (derived per request); handlers ignore keys they don't
+ *  declare, so the union is safe to pass wholesale. */
+export type TwinFetchHandlerRequest = {
+  method: string;
+  path: string;
+  body: string;
+  headers: Record<string, string>;
+  readOnly: boolean;
+  occurredAt: string;
+  root?: string;
+} & Record<string, unknown>;
+
+export interface TwinFetchAdapterConfig {
+  root?: string;
+  readOnly?: boolean;
+  /** The keyless GET /twin body — a value (stateful packs: statefulTwinManifest(...)) or
+   *  a thunk (generative packs build theirs around the scenario engine). */
+  manifest: unknown | (() => unknown);
+  /** GET /twin/scenario body (thunk) — scenario-carrying packs only. */
+  scenarioStatus?: () => unknown;
+  /** THE STORE DOOR (R5c, mirror purity R3): named, deterministic projections over stored
+   *  state, served at `GET /twin/store/<name>` and listed in the manifest as `stores`. A
+   *  mirror reads twin state ONLY through this door — never by importing the handler or a
+   *  `-twin-internal` module — so the vendor API lacking a listing endpoint (resend has no
+   *  list-emails) no longer breeds a bespoke `/_twin/*` route per mirror. Keyed in the skin
+   *  like every state read (only bare `GET /twin` is keyless). */
+  stores?: Record<string, () => unknown | Promise<unknown>>;
+  /** Per-request vendor extras (header threading: stripe-version, notion-version, …). */
+  extras?: (request: Request, url: URL) => Record<string, unknown>;
+  /** Static per-instance handler options (e.g. rateLimitPerSecond). */
+  handlerOptions?: Record<string, unknown>;
+  /** Extra response headers on every non-door reply (e.g. stripe's request-id, and
+   *  postmark's `connection: close` Bun-socket workaround — inert under workerd). */
+  responseHeaders?: Record<string, string>;
+}
+
+export function createTwinFetchFromHandler(
+  handler: (request: TwinFetchHandlerRequest) => TwinFetchHandlerResult | Promise<TwinFetchHandlerResult>,
+  config: TwinFetchAdapterConfig,
+): (request: Request) => Promise<Response> {
+  const readOnly = config.readOnly ?? false;
+  return async function twinFetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    const cleanPath = url.pathname.replace(/\/+$/, '') || '/';
+    if (request.method === 'GET' && cleanPath === '/twin') {
+      const manifest = typeof config.manifest === 'function' ? (config.manifest as () => unknown)() : config.manifest;
+      const storeNames = Object.keys(config.stores ?? {}).sort();
+      if (storeNames.length > 0 && manifest !== null && typeof manifest === 'object') {
+        const m = manifest as Record<string, unknown>;
+        const doors = m.doors !== null && typeof m.doors === 'object' ? (m.doors as Record<string, unknown>) : {};
+        // The manifest EDUCATES: it lists the store names and names the door's path.
+        return Response.json({ ...m, stores: storeNames, doors: { ...doors, store: 'GET /twin/store/<name>' } });
+      }
+      return Response.json(manifest);
+    }
+    if (request.method === 'GET' && cleanPath === '/twin/scenario' && config.scenarioStatus !== undefined) {
+      return Response.json(config.scenarioStatus());
+    }
+    if (request.method === 'GET' && cleanPath.startsWith('/twin/store/')) {
+      const name = cleanPath.slice('/twin/store/'.length);
+      const store = config.stores?.[name];
+      if (store === undefined) return Response.json({ error: 'unknown store', store: name, stores: Object.keys(config.stores ?? {}).sort() }, { status: 404 });
+      return Response.json(await store()); // a projection may read through the handler (async) — the door awaits it
+    }
+    const body = request.method === 'GET' || request.method === 'HEAD' ? '' : await request.text();
+    const headers: Record<string, string> = {};
+    request.headers.forEach((value, key) => { headers[key] = value; });
+    // FIXED FIELDS WIN (review B1): handlerOptions/extras spread FIRST, so no config —
+    // and via extras, no WIRE INPUT — can override method/path/body/readOnly or the
+    // world instant. A client-settable occurredAt would be a direct R9 hole.
+    const result = await handler({
+      ...config.handlerOptions,
+      ...config.extras?.(request, url),
+      method: request.method,
+      path: url.pathname + (url.search || ''),
+      body,
+      headers,
+      readOnly,
+      occurredAt: worldNow(),
+      ...(config.root !== undefined ? { root: config.root } : {}),
+    });
+    // A null/undefined body is an EMPTY reply (`JSON.stringify(null)` would serve the
+    // four bytes "null") — and so is the estate's own 204 idiom, `body: ''` with a
+    // null-body status: workerd THROWS on any body with 204/205/304 (review B2), where
+    // Bun silently serves '""' — either way a wire break on exactly one lane.
+    const nullBodyStatus = result.status === 204 || result.status === 205 || result.status === 304;
+    if (result.body === null || result.body === undefined || (nullBodyStatus && result.body === '')) {
+      return new Response(null, { status: result.status, headers: { ...config.responseHeaders, ...result.headers } });
+    }
+    return new Response(JSON.stringify(result.body), {
+      status: result.status,
+      headers: { 'content-type': 'application/json', ...config.responseHeaders, ...result.headers },
+    });
+  };
+}

package/src/validate.ts

@@ -2,10 +2,10 @@
 // reconcile (no write left without a recorded result past the grace window). NOTE:
 // annotation integrity (quotes resolve, events annotated, …) moved to
 // @volter/tracker/world-annotations — that's a verification (tracker) concern.
-import { existsSync, readdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { listEgressLedger } from './egress.ts';
 import { worldStateRoot } from './storage.ts';
+import { getActiveWorldStore } from './world-store.ts';
 
 export type WorldValidationFinding = {
   level: 'error' | 'warning';
@@ -35,11 +35,12 @@ function stringValue(value: unknown): string {
 }
 
 export function discoverWorldServices(root: string): string[] {
+  const store = getActiveWorldStore();
   const worldRoot = worldStateRoot(root);
-  if (!existsSync(worldRoot)) return [];
-  return readdirSync(worldRoot, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory() && existsSync(join(worldRoot, entry.name, 'events.jsonl')))
-    .map((entry) => entry.name)
+  if (!store.exists(worldRoot)) return [];
+  return store
+    .list(worldRoot)
+    .filter((name) => (store.stat(join(worldRoot, name))?.isDirectory ?? false) && store.exists(join(worldRoot, name, 'events.jsonl')))
     .sort();
 }