@volter/twin 0.1.0 → 0.1.1

package/src/serve.ts

@@ -9,10 +9,318 @@
 // is a repo". The only serve-time policy here is `readOnly`: a twin accepts local
 // writes (as actions) unless you start it read-only (a pure mirror of pulled
 // reality). Forking is a separate data operation (fork.ts), never a serve mode.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash } from 'node:crypto';
+import { dirname, join } from 'node:path';
 import type { SubjectFields } from './shadow.ts';
 import { hashFieldValue } from './shadow.ts';
-import { appendActionIfAbsent, projectResources } from './actions.ts';
-import type { TwinActionPrecondition } from './actions.ts';
+import { appendActionIfAbsent, decideAndAppendAction, projectResources } from './actions.ts';
+import type { ActionProjection, TwinAction, TwinActionPrecondition } from './actions.ts';
+import { observeWorldPaths, worldPaths } from './storage.ts';
+import { getActiveWorldStore } from './world-store.ts';
+
+// ── the request journal: the INSPECT half of the read path ─────────────────────────────────────
+// `actions.jsonl` records MUTATIONS only, so a twin's READS are invisible to `volter-world tail`
+// — an empty-catalog GET that 404s leaves no trace, and "did the app even ask?" is unanswerable.
+// The journal is the minimal honest answer: an OPT-IN (VOLTER_TWIN_REQUEST_JOURNAL=1) per-twin
+// `requests.jsonl` beside `actions.jsonl`, one line per served HTTP request. Size-capped: at ~1 MB
+// the file rotates once to `requests.jsonl.1` (previous rotation overwritten), so an enabled
+// journal can never grow unbounded. `volter-world tail --requests` merges these lines live.
+//
+// WHAT A LINE CARRIES. `{at, method, path, status}` — the shape — plus, when the request presented
+// one, the CREDENTIAL SHAPE: which header/query-param NAMES carried a credential-looking value,
+// each with a truncated sha256 FINGERPRINT of the value. Never the value, never the rest of the
+// query string, never a body. That is what makes the journal answer the question a twin exists to
+// answer and could not: *which credential arrived, in which header?* Two different fingerprints
+// under `dd-api-key` and `dd-application-key` say "two distinct keys arrived, in their own named
+// headers"; the same fingerprint on two rows says "the same value came back"; a missing name says
+// the caller sent nothing. Reading a fingerprint back to its secret is not possible — it is
+// sha256, truncated — so the file stays safe to paste into an issue.
+//
+// The query string used to be dropped whole (it carries tokens), which is precisely why a
+// query-placed key was invisible: the journal now names the credential PARAMS and fingerprints
+// them, and still records `path` without its query.
+//
+// A fingerprint is not a vault: it is sha256 of the value, so a LOW-entropy credential (`"test"`)
+// is guessable from its fingerprint by anyone who guesses the value first. It is exactly the right
+// strength for its job — telling two credentials apart, and recognising one across requests.
+//
+// WHERE IT IS WIRED. Not per-pack. Every vendor pack mounts its own `Bun.serve({fetch})` inside a
+// `create<Vendor>TwinServer({port, root, readOnly})` factory — there is no shared middleware, but
+// there IS a shared CONSTRUCTOR, so `installTwinRequestJournal()` (below, called once at module
+// load) wraps `Bun.serve` and journals every twin's fetch handler. The pack writes no journaling
+// line at all; the four packs that used to call `journalTwinRequest` themselves no longer do.
+// Measured coverage: 67 of the 69 pack HTTP servers journal with zero pack-side code. The two that
+// do not are STRUCTURAL, not missed — `smtp` is a raw-TCP `Bun.listen` mail listener with no HTTP
+// surface, and termfleet's PROVIDER server is `node:http` + socket.io (its registry server, which
+// is `Bun.serve`, is covered). Anything that mounts an HTTP twin through `Bun.serve` is covered by
+// construction; anything that does not is a second transport and would need its own seam.
+
+export type TwinCredentialShape = {
+  /** header name (lowercased) or query-param name the credential arrived under. */
+  name: string;
+  /** where it sat on the request. */
+  in: 'header' | 'query';
+  /** the auth SCHEME when the value carried one (`Bearer`, `Basic`, `AWS4-HMAC-SHA256`). A scheme
+   *  is not a secret, and it is what distinguishes "a bearer token arrived" from "a named vendor
+   *  header arrived" — the exact confusion this journal was added to end. */
+  scheme?: string;
+  /** `sha256:<16 hex>` of the value (of the credential part when a scheme was present). Stable
+   *  across processes and runs, so equal fingerprints mean equal values; non-reversible. */
+  fp?: string;
+  /** the name arrived with an EMPTY value — the "the SDK sent the header but no key" case. */
+  empty?: true;
+};
+
+export type TwinRequestJournalEntry = {
+  at?: string;
+  method: string;
+  path: string;
+  status: number;
+  /** credential-looking headers/query params that arrived, named + fingerprinted, never quoted. */
+  credentials?: TwinCredentialShape[];
+};
+
+/** ~1 MB cap before a one-deep rotation — small enough to never matter on disk, large enough for
+ *  tens of thousands of entries (a shape line is ~80 bytes). */
+const REQUEST_JOURNAL_MAX_BYTES = 1_000_000;
+
+/**
+ * Does this header/param NAME look like it carries a credential? Deliberately a generic word
+ * predicate, never a vendor table: the kernel must not learn that Datadog calls its keys
+ * `DD-API-KEY` or that Postmark calls its tokens `X-Postmark-Server-Token`. Both fall out of
+ * `key`/`token` as name segments, and so does every vendor that has not been written yet.
+ */
+const CREDENTIAL_NAME = /(?:^|[-_.])(?:auth|authorization|token|jwt|key|apikey|secret|credential|credentials|signature|sig|password|passwd|pwd|session|sessionid|cookie|access[-_]?token|refresh[-_]?token)(?:[-_.]|$)/i;
+
+/** Auth schemes recognised in a value even when the NAME says nothing (`Bearer …` in `x-custom`). */
+const CREDENTIAL_SCHEME = /^(Bearer|Basic|Digest|Token|Negotiate|NTLM|OAuth|Signature|Hawk|AWS4-HMAC-SHA256|SharedKey|SharedKeyLite|GoogleLogin)\s+(\S[\s\S]*)$/i;
+
+/** Non-reversible, stable fingerprint. 64 bits of sha256 — enough that two distinct credentials
+ *  never collide in a journal, far too little to walk back to a real key. */
+export function credentialFingerprint(value: string): string {
+  return `sha256:${createHash('sha256').update(value, 'utf8').digest('hex').slice(0, 16)}`;
+}
+
+function credentialShapeFor(name: string, value: string, where: 'header' | 'query'): TwinCredentialShape | undefined {
+  const scheme = CREDENTIAL_SCHEME.exec(value);
+  if (!scheme && !CREDENTIAL_NAME.test(name)) return undefined;
+  const lower = name.toLowerCase();
+  if (value === '') return { name: lower, in: where, empty: true };
+  if (scheme) return { name: lower, in: where, scheme: scheme[1]!, fp: credentialFingerprint(scheme[2]!) };
+  return { name: lower, in: where, fp: credentialFingerprint(value) };
+}
+
+/**
+ * The credential SHAPE of one request: every credential-looking header and query param, named and
+ * fingerprinted, sorted for stable diffing. Values never leave this function.
+ */
+export function twinRequestCredentials(headers: Headers | Record<string, string>, url?: string | URL): TwinCredentialShape[] {
+  const shapes: TwinCredentialShape[] = [];
+  const seen = new Set<string>();
+  const add = (name: string, value: string, where: 'header' | 'query') => {
+    const shape = credentialShapeFor(name, value, where);
+    if (!shape) return;
+    const key = `${shape.in}:${shape.name}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    shapes.push(shape);
+  };
+  try {
+    if (typeof (headers as Headers).forEach === 'function') {
+      (headers as Headers).forEach((value, name) => add(name, value, 'header'));
+    } else {
+      for (const [name, value] of Object.entries(headers as Record<string, string>)) add(name, String(value), 'header');
+    }
+  } catch { /* a malformed header bag must not fail a serve */ }
+  try {
+    if (url !== undefined) {
+      const search = typeof url === 'string' ? new URL(url, 'http://twin.invalid').search : url.search;
+      for (const [name, value] of new URLSearchParams(search)) add(name, value, 'query');
+    }
+  } catch { /* an unparseable URL must not fail a serve */ }
+  return shapes.sort((a, b) => (a.in === b.in ? a.name.localeCompare(b.name) : a.in.localeCompare(b.in)));
+}
+
+export function twinRequestJournalEnabled(env: Record<string, string | undefined> = process.env): boolean {
+  return env.VOLTER_TWIN_REQUEST_JOURNAL === '1';
+}
+
+/** Where a service's request journal lives: beside its `actions.jsonl`. */
+export function twinRequestJournalPath(service: string, root?: string): string {
+  return join(dirname(worldPaths(service, root).events), 'requests.jsonl');
+}
+
+/**
+ * Append one served request to the journal — a no-op unless VOLTER_TWIN_REQUEST_JOURNAL=1, so
+ * the default path does zero I/O. Never throws: an observability append must not fail a serve.
+ */
+export function journalTwinRequest(service: string, entry: TwinRequestJournalEntry, root?: string): void {
+  if (!twinRequestJournalEnabled()) return;
+  try {
+    const store = getActiveWorldStore();
+    const path = twinRequestJournalPath(service, root);
+    store.mkdir(dirname(path));
+    const size = store.stat(path)?.size ?? 0;
+    if (size >= REQUEST_JOURNAL_MAX_BYTES) {
+      // one-deep rotation: the previous overflow is overwritten, the live file starts fresh.
+      store.writeAtomic(`${path}.1`, store.read(path) ?? '');
+      store.write(path, '');
+    }
+    const line = JSON.stringify({
+      at: entry.at ?? new Date().toISOString(),
+      method: entry.method.toUpperCase(),
+      path: entry.path.split('?')[0], // the query STRING never lands; its credential params do, named + fingerprinted
+      status: entry.status,
+      ...(entry.credentials?.length ? { credentials: entry.credentials } : {}),
+    });
+    store.append(path, `${line}\n`);
+  } catch {
+    // journaling is best-effort observability; the serve path must not care
+  }
+}
+
+// ── how a wrapped `Bun.serve` learns which twin it is ──────────────────────────────────────────
+// `Bun.serve({port, fetch})` carries neither the vendor id nor the state root — both live in the
+// factory's closure. They are recoverable without touching a single pack, because handling a
+// request makes the pack call the kernel, and every kernel state path funnels through
+// `worldPaths(service, root)` (storage.ts). Observing the FIRST such call a server makes is the
+// twin naming itself: `datadog` under `/tmp/world/data/datadog`. It is cached per server, so only
+// the first request pays for it. A server whose first request touches no state falls back to the
+// call site (`packages/twin/<vendor>/…` or `@volter/twin-<vendor>`) and the process's `--root`
+// argument, which is how the world runtime launches every twin.
+
+export const TWIN_JOURNAL_IDENTITY = Symbol.for('volter.twin.requestJournal.identity');
+const JOURNAL_SHIM_INSTALLED = Symbol.for('volter.twin.requestJournal.installed');
+
+export type TwinJournalIdentity = { service: string; root?: string };
+
+/** One capture slot per in-flight request, so two twins co-located in ONE process (the shared
+ *  host) can never read each other's identity off a racing sibling's first request.
+ *
+ *  LAZY ON PURPOSE, and this is load-bearing rather than style. Mirror-UI packs import their own
+ *  server module into the BROWSER bundle and rely on Bun tree-shaking the server-only half away
+ *  (see any `*-mirror-ui.ts` header). A module-scope `new AsyncLocalStorage()` is a side effect,
+ *  so it survives tree-shaking and lands in the client — where `node:async_hooks` does not
+ *  resolve, `new` throws at bundle evaluation, and the React app never mounts. That took out
+ *  every mirror UI in the estate at once. Nothing in this module may run at module scope. */
+let identityCapture: AsyncLocalStorage<{ identity?: TwinJournalIdentity }> | undefined;
+
+function identitySlot(): AsyncLocalStorage<{ identity?: TwinJournalIdentity }> {
+  identityCapture ??= new AsyncLocalStorage<{ identity?: TwinJournalIdentity }>();
+  return identityCapture;
+}
+
+function observeIdentityFromWorldPaths(): void {
+  observeWorldPaths((service, root) => {
+    const slot = identityCapture?.getStore();
+    if (!slot || slot.identity !== undefined) return;
+    slot.identity = root === undefined ? { service } : { service, root };
+  });
+}
+
+/** The `--root DIR` a twin was launched with (the world runtime's spawn contract), if any. */
+function rootFromArgv(argv: readonly string[] = process.argv): string | undefined {
+  const index = argv.indexOf('--root');
+  const value = index >= 0 ? argv[index + 1] : undefined;
+  return value && !value.startsWith('--') ? value : undefined;
+}
+
+/** The vendor a `Bun.serve` call site belongs to, from its module path. Infra packages are not
+ *  vendors, so they are skipped: whoever called THEM is the twin. */
+const INFRA_PACKAGES = new Set(['control-plane', 'world-runtime', 'tooling', 'attach', 'browser-assets', 'twins-host']);
+
+export function vendorFromStack(stack: string | undefined): string | undefined {
+  if (!stack) return undefined;
+  const pattern = /(?:packages[\\/]twin[\\/]|@volter[\\/]twin-)([A-Za-z0-9_-]+)/g;
+  for (const match of stack.matchAll(pattern)) {
+    const name = match[1]!;
+    if (!INFRA_PACKAGES.has(name)) return name;
+  }
+  return undefined;
+}
+
+
+
+/**
+ * Wrap `Bun.serve` so EVERY twin's HTTP surface journals, with no per-pack line. Idempotent
+ * (a `Symbol.for` marker survives a second copy of this module) and a strict pass-through when
+ * VOLTER_TWIN_REQUEST_JOURNAL is not `1` — the default path adds one function call per request
+ * and does zero I/O. Called once at module load, below; exported so a test can assert it.
+ *
+ * A pack that knows its own identity may declare it by putting `{service, root}` on the serve
+ * options under `TWIN_JOURNAL_IDENTITY` (a symbol key Bun's option reader ignores). Nothing in
+ * the estate needs to: `createTwinServer` is the only caller, because it is the one server whose
+ * service is an argument rather than a fact about the pack.
+ */
+export function installTwinRequestJournal(): boolean {
+  const bun = (globalThis as { Bun?: { serve?: unknown } }).Bun;
+  if (!bun || typeof bun.serve !== 'function') return false; // not Bun (node tooling) — nothing to wrap
+  const original = bun.serve as (...args: unknown[]) => { port?: number };
+  if ((original as unknown as Record<symbol, unknown>)[JOURNAL_SHIM_INSTALLED]) return true;
+  // Registered HERE, not at module scope, for the same reason the capture slot is lazy: a
+  // module-scope registration is a side effect that survives tree-shaking into the client.
+  observeIdentityFromWorldPaths();
+
+  const wrapped = function serve(this: unknown, options: unknown, ...rest: unknown[]) {
+    const config = options as (Record<string | symbol, unknown> & { fetch?: (...a: unknown[]) => unknown }) | undefined;
+    if (!config || typeof config.fetch !== 'function') return original.apply(this, [options, ...rest]);
+    const declared = config[TWIN_JOURNAL_IDENTITY] as TwinJournalIdentity | undefined;
+    // Resolved once per SERVER, not per request: a twin's identity is a constant of the server.
+    let identity: TwinJournalIdentity | undefined = declared;
+    // Captured HERE, at the `Bun.serve` call, because this is the only moment the pack's own
+    // module is on the stack — by the time a request is served, Bun is the caller.
+    const callSiteVendor = declared ? undefined : vendorFromStack(new Error().stack);
+    const inner = config.fetch as (this: unknown, request: Request, server: unknown) => unknown;
+    const journaling = async function (this: unknown, request: Request, server: unknown) {
+      if (!twinRequestJournalEnabled()) return inner.call(this, request, server);
+      const slot: { identity?: TwinJournalIdentity } = {};
+      let status = 500;
+      try {
+        const response = (await identitySlot().run(slot, () => inner.call(this, request, server))) as Response | undefined;
+        if (response instanceof Response) status = response.status;
+        else if (response === undefined) return response; // upgraded (websocket) — nothing served
+        return response;
+      } finally {
+        // Only an OBSERVED identity is cached: it is the twin's own words. A fallback is
+        // per-request, so the first request that touches state upgrades every later one instead
+        // of locking a guessed root in for the life of the server.
+        identity ??= slot.identity;
+        const resolved = identity ?? fallbackIdentity(callSiteVendor);
+        if (resolved) {
+          const url = new URL(request.url);
+          journalTwinRequest(resolved.service, {
+            method: request.method,
+            path: url.pathname,
+            status,
+            credentials: twinRequestCredentials(request.headers, url),
+          }, resolved.root);
+        }
+      }
+    };
+    return original.apply(this, [{ ...config, fetch: journaling }, ...rest]);
+  };
+  Object.defineProperty(wrapped, JOURNAL_SHIM_INSTALLED, { value: true });
+  (bun as { serve: unknown }).serve = wrapped;
+  return true;
+}
+
+/** Identity for a server whose first request touched no state: the vendor that owns the calling
+ *  module, plus the `--root` the world runtime launched this twin with. */
+function fallbackIdentity(callSiteVendor: string | undefined): TwinJournalIdentity | undefined {
+  const service = process.env.VOLTER_TWIN_JOURNAL_SERVICE || callSiteVendor;
+  if (!service || !/^[A-Za-z0-9_-]+$/.test(service)) return undefined;
+  const root = rootFromArgv();
+  return root === undefined ? { service } : { service, root };
+}
+
+// One call, at module load. `@volter/twin`'s entrypoint re-exports this module, and every pack
+// that serves imports the kernel, so wrapping here is what makes the journal a property of the
+// PRODUCT rather than of the four packs that once remembered to call it.
+//
+// It is a no-op wherever `Bun.serve` is absent, which is what keeps it safe in a browser bundle:
+// off-Bun it returns before touching `node:async_hooks`, `process.argv`, or the storage hook.
+installTwinRequestJournal();
 
 // A subject rendered as a vendor resource: its folded current fields + identity.
 export type TwinResource = { id: string; type: string; updatedAt: string } & Record<string, unknown>;
@@ -27,6 +335,69 @@ export function twinResources(service: string, root?: string): TwinResource[] {
 // Result of a local twin write — it is an ACTION, not an egress/real write.
 export type TwinWriteResult = { status: 'performed' | 'replayed'; actionId: string };
 
+export type TwinWriteInput = {
+  operation: string;
+  provider?: string;
+  subjectType: string;
+  subjectId: string;
+  fields: SubjectFields;
+  input?: Record<string, unknown>;
+  projection?: ActionProjection;
+  occurredAt?: string;
+  actor?: { kind: 'agent' | 'human' | 'bot' | 'system'; id?: string };
+  preconditions?: TwinActionPrecondition[];
+  correlationId?: string;
+  uniqueness?: string;
+};
+
+export type AtomicTwinWriteDecision<T> =
+  | { kind: 'skip'; value: T }
+  | { kind: 'write'; value: T; write: TwinWriteInput };
+
+function actionForTwinWrite(service: string, write: TwinWriteInput): TwinAction {
+  const occurredAt = write.occurredAt ?? new Date().toISOString();
+  // Idempotency: dedup a RE-ISSUED IDENTICAL write only. The key includes a hash of the write
+  // CONTENT, not just the timestamp. `undefined` keys are omitted by canonicalJson, preserving
+  // every pre-input/projection action id for existing packs.
+  const contentHash = hashFieldValue({ operation: write.operation, subjectId: write.subjectId, fields: write.fields, input: write.input, projection: write.projection });
+  const actionId = `twin:${service}:${write.operation}:${write.subjectId}:${occurredAt}:${contentHash}${write.uniqueness ? `:${write.uniqueness}` : ''}`;
+  return {
+    id: actionId,
+    service,
+    op: 'set',
+    operation: write.operation,
+    subject: { type: write.subjectType, id: write.subjectId },
+    occurredAt,
+    ...(write.actor ? { actor: write.actor } : {}),
+    ...(write.preconditions?.length ? { preconditions: write.preconditions } : {}),
+    ...(write.correlationId ? { correlationId: write.correlationId } : {}),
+    ...(write.input ? { input: write.input } : {}),
+    fields: write.fields,
+    ...(write.projection ? { projection: write.projection } : {}),
+  };
+}
+
+/**
+ * Decide a state-dependent local write and append it under the same cross-process action lock.
+ * Use this when acceptance or the new fields depend on current projected state; a caller-side
+ * read followed by `applyTwinWrite` is not atomic across processes.
+ */
+export async function applyTwinWriteAtomic<T>(
+  service: string,
+  prepare: (resources: readonly TwinResource[]) => AtomicTwinWriteDecision<T>,
+  root?: string,
+): Promise<{ value: T; result?: TwinWriteResult }> {
+  const committed = decideAndAppendAction(service, (resources) => {
+    const decision = prepare(resources);
+    if (decision.kind === 'skip') return { kind: 'skip', value: decision.value };
+    return { kind: 'append', value: decision.value, action: actionForTwinWrite(service, decision.write) };
+  }, root);
+  return {
+    value: committed.value,
+    ...(committed.action ? { result: { status: committed.appended ? 'performed' : 'replayed', actionId: committed.action.id } } : {}),
+  };
+}
+
 // Resolve a read request against the twin's resources. Returns the matched
 // resource(s) + an HTTP-ish status, deterministically from state.
 //   GET /                       -> { service, mode, resourceTypes, count }
@@ -63,38 +434,41 @@ export function resolveTwinRead(
 // vendor is a separate, explicit step that records egress + confirms the action.
 export async function applyTwinWrite(
   service: string,
-  write: { operation: string; provider?: string; subjectType: string; subjectId: string; fields: SubjectFields; occurredAt?: string; actor?: { kind: 'agent' | 'human' | 'bot' | 'system'; id?: string }; preconditions?: TwinActionPrecondition[]; correlationId?: string },
+  write: TwinWriteInput,
   root?: string,
 ): Promise<{ result: TwinWriteResult; resource: TwinResource }> {
-  const occurredAt = write.occurredAt ?? new Date().toISOString();
+  const action = actionForTwinWrite(service, write);
   // Idempotency: dedup a RE-ISSUED IDENTICAL write only. The key includes a hash of the write
   // CONTENT (operation + subject + fields), not just the timestamp — so two DIFFERENT writes to
   // the same subject in the same millisecond are BOTH kept (previously the second silently
   // no-opped: e.g. a sprint "start" then "close" in the same ms lost the close). Check + append
   // run atomically under the actions lock, so concurrent processes can't double-apply either.
-  const contentHash = hashFieldValue({ operation: write.operation, subjectId: write.subjectId, fields: write.fields });
-  const actionId = `twin:${service}:${write.operation}:${write.subjectId}:${occurredAt}:${contentHash}`;
+  //
+  // The UNIQUENESS SEAM: some vendor operations are billable OCCURRENCES, not idempotent state
+  // writes — every call is a distinct action even when byte-identical in the same millisecond
+  // (an AI completion: the real vendor runs + bills each call; two identical rapid calls must
+  // ledger as TWO actions, never collapse). A pack passes a per-call `uniqueness` value (e.g.
+  // randomUUID()) and the content-dedupe stops applying to that action. Leave it unset for
+  // ordinary resource writes, where replay-dedupe is the correct semantics.
   // correlationId (D3): pass a caller-supplied request-scoped id through (e.g. propagated
   // from an inbound HTTP request id) so it lands on the action row; appendActionIfAbsent
   // generates one when omitted, so it's never missing.
-  const { appended } = appendActionIfAbsent(
-    { id: actionId, service, op: 'set', operation: write.operation, subject: { type: write.subjectType, id: write.subjectId }, occurredAt, ...(write.actor ? { actor: write.actor } : {}), ...(write.preconditions?.length ? { preconditions: write.preconditions } : {}), ...(write.correlationId ? { correlationId: write.correlationId } : {}), fields: write.fields },
-    root,
-  );
+  const { appended } = appendActionIfAbsent(action, root);
   // Resolve by (type, id) — an id alone is ambiguous when two resource TYPES share it.
   const resource = projectResources(service, root).find((r) => r.type === write.subjectType && r.id === write.subjectId)
-    ?? ({ id: write.subjectId, type: write.subjectType, updatedAt: occurredAt, ...write.fields } as TwinResource);
-  return { result: { status: appended ? 'performed' : 'replayed', actionId }, resource };
+    ?? ({ id: write.subjectId, type: write.subjectType, updatedAt: action.occurredAt, ...write.fields } as TwinResource);
+  return { result: { status: appended ? 'performed' : 'replayed', actionId: action.id }, resource };
 }
 
 export function createTwinServer(options: { service: string; root?: string; port?: number; readOnly?: boolean }): { port: number; stop: () => void } {
   const readOnly = options.readOnly ?? false;
-  const server = Bun.serve({
+  const serveOptions = {
     port: options.port ?? 0,
     idleTimeout: 60,
-    async fetch(request) {
+    async fetch(request: Request) {
       const url = new URL(request.url);
-      const json = (status: number, body: unknown) => new Response(JSON.stringify(body, null, 2), { status, headers: { 'content-type': 'application/json' } });
+      const json = (status: number, body: unknown) =>
+        new Response(JSON.stringify(body, null, 2), { status, headers: { 'content-type': 'application/json' } });
       if (request.method === 'GET') {
         // Re-read per request so a concurrently-syncing twin serves fresh state.
         const { status, body } = resolveTwinRead(options.service, url.pathname, { root: options.root });
@@ -115,6 +489,14 @@ export function createTwinServer(options: { service: string; root?: string; port
       }, options.root);
       return json(result.status === 'replayed' ? 200 : 201, { status: result.status, resource });
     },
+  };
+  // This generic server's twin is an ARGUMENT, not a fact about a pack, so it NAMES ITSELF for the
+  // request journal rather than being recognised from its call site. Every vendor pack is journaled
+  // without declaring anything (installTwinRequestJournal, above); this is the lone declaration.
+  Object.defineProperty(serveOptions, TWIN_JOURNAL_IDENTITY, {
+    value: { service: options.service, ...(options.root !== undefined ? { root: options.root } : {}) },
+    enumerable: true,
   });
+  const server = Bun.serve(serveOptions);
   return { port: server.port ?? 0, stop: () => server.stop(true) };
 }

package/src/shadow.ts

@@ -1,7 +1,8 @@
 import { createHash } from 'node:crypto';
 import { isEgressEventType } from './egress.ts';
-import { appendEvent, createEvent, listEvents } from './storage.ts';
-import type { AppendEventResult, WorldServiceEvent } from './types.ts';
+import { appendEvent, appendEventLocked, createEvent, listEvents, worldPaths } from './storage.ts';
+import { getActiveWorldStore } from './world-store.ts';
+import type { AppendEventResult, WorldPaths, WorldServiceEvent } from './types.ts';
 
 export const DELTA_TYPE_SUFFIX = '.delta';
 
@@ -31,7 +32,11 @@ export type SubjectFieldExtractor = (event: WorldServiceEvent) => SubjectFields
 
 export type FieldChange = { before: unknown; after: unknown };
 
-function canonicalJson(value: unknown): string {
+/** Deterministic JSON: object keys sorted, `undefined` entries dropped, arrays in order.
+ *  The one canonicalizer in this package — `hashFieldValue` (action-id content hashing) and
+ *  `changesetContentHash` (approval binds to exact bytes) must agree on what "same content"
+ *  means, so they share this function rather than each rolling their own. */
+export function canonicalJson(value: unknown): string {
   if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
   if (value && typeof value === 'object') {
     const entries = Object.entries(value as Record<string, unknown>)
@@ -47,10 +52,67 @@ export function hashFieldValue(value: unknown): string {
   return createHash('sha256').update(canonicalJson(value)).digest('hex').slice(0, 16);
 }
 
-function subjectKey(subject: { type: string; id: string }): string {
+export function subjectKey(subject: { type: string; id: string }): string {
   return `${subject.type}:${subject.id}`;
 }
 
+/**
+ * The per-subject REMOTE REF (runtime contract R14): the id of the last event in the
+ * observed mirror that moved the remote from THIS action's point of view. Null = the
+ * mirror has never seen the subject.
+ *
+ * This is the git remote-tracking ref of the model: an action stamps these at authoring
+ * time (its merge base), and push compares them again — a moved ref means someone else
+ * changed the remote since we last looked, and the push must refuse (non-fast-forward).
+ *
+ * What "someone else" means differs by moment, so the reader has three MODES:
+ * - AUTHORING (mode omitted): every push confirmation this world has ever written
+ *   (`confirmed:{service}:…` ids) is excluded — everything already confirmed at
+ *   authoring time was, by construction, pushed before this action existed.
+ * - PUSH (mode `{countAsDrift}`): self-confirmations are excluded EXCEPT the listed
+ *   event ids — pushLedger.ts lists the confirmations of the pushed action's
+ *   DESCENDANTS (actions authored after it), which count as drift: pushing a stale
+ *   action once a newer one already landed remotely is the out-of-order lost update.
+ *   Orphaned self-confirm events (a crash between confirmAction's event append and its
+ *   confirm row — referenced by no row) stay excluded in this mode, matching what the
+ *   authoring stamp saw; counting them would wedge the subject behind a permanent
+ *   phantom drift.
+ * - RAW (mode 'raw'): nothing is excluded — the last mirror event, period. The sync
+ *   plane's capture/compare mode: a reconcile plan is stale the moment ANY event lands
+ *   after its `real` pull, our own confirmations included (syncPush, sync.ts).
+ *
+ * Reads the event log raw (JSON.parse of id/type/subject only, no schema validation) —
+ * this runs on the applyTwinWrite hot path, where a full zod parse per append is the
+ * exact O(N·M) cost storage.ts already had to engineer out of appendEvent.
+ */
+export type RemoteRefsMode = 'raw' | { countAsDrift: ReadonlySet<string> };
+
+export function remoteRefs(
+  service: string,
+  subjects: Array<{ type: string; id: string }>,
+  root?: string,
+  mode?: RemoteRefsMode,
+): Record<string, string | null> {
+  const wanted = new Map(subjects.map((s) => [subjectKey(s), null as string | null]));
+  if (wanted.size === 0) return {};
+  const selfConfirmed = `confirmed:${service}:`;
+  const path = worldPaths(service, root).events;
+  for (const line of getActiveWorldStore().readLines(path)) {
+    if (!line.trim()) continue;
+    let event: { id?: string; type?: string; subject?: { type: string; id: string } };
+    try { event = JSON.parse(line) as typeof event; } catch { continue; }
+    if (!event.id || !event.type || !event.subject) continue;
+    if (isEgressEventType(event.type)) continue;
+    if (mode !== 'raw' && event.id.startsWith(selfConfirmed)) {
+      const countAsDrift = mode !== undefined && mode.countAsDrift.has(event.id);
+      if (!countAsDrift) continue;
+    }
+    const key = subjectKey(event.subject);
+    if (wanted.has(key)) wanted.set(key, event.id);
+  }
+  return Object.fromEntries(wanted);
+}
+
 function isDeltaEvent(event: WorldServiceEvent): boolean {
   return event.type.endsWith(DELTA_TYPE_SUFFIX) && typeof event.data.changed === 'object';
 }
@@ -150,10 +212,10 @@ export type DeltaResult =
  * The delta idempotencyKey is derived from the after-state hashes, so the
  * same observed change never appends twice.
  */
-export function recordObservedDelta(
+function recordObservedDeltaWith(
   state: ShadowState,
   observation: DeltaObservation,
-  root?: string,
+  appendFn: (event: WorldServiceEvent) => AppendEventResult,
 ): DeltaResult {
   const shadow = state.subjects[subjectKey(observation.subject)];
   const changes = diffSubjectFields(shadow, observation.observed);
@@ -186,7 +248,24 @@ export function recordObservedDelta(
       changed: changes,
     },
   });
-  const append = appendEvent(event, root);
+  const append = appendFn(event);
   if (append.appended) applyFields(state, append.event, deltaAfterFields(append.event));
   return { changed: true, event: append.event, changes, append };
 }
+
+export function recordObservedDelta(
+  state: ShadowState,
+  observation: DeltaObservation,
+  root?: string,
+): DeltaResult {
+  return recordObservedDeltaWith(state, observation, (event) => appendEvent(event, root));
+}
+
+/** Internal batch seam: caller already owns the service projection + events locks. */
+export function recordObservedDeltaLocked(
+  state: ShadowState,
+  observation: DeltaObservation,
+  paths: WorldPaths,
+): DeltaResult {
+  return recordObservedDeltaWith(state, observation, (event) => appendEventLocked(event, paths));
+}