@volter/world-core 2.0.0

package/dist/src/serve.js

@@ -0,0 +1,507 @@
+// Twin serve layer (the twins architecture notes, increment 1): answer vendor-shaped
+// READS from the local event-sourced state — the "local twin" read path. An app
+// or agent points at this instead of the real vendor; it responds from local
+// state with the real service unreachable.
+//
+// There is ONE twin, not a set of "modes". Pulling reality, writing locally, and
+// forking are operations on the same substrate (events + local actions + the
+// projection over them), not exclusive modes — see the architecture doc, "a twin
+// 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 { serveHttp, setServeDecorator, WORLD_BOOT_PATH } from "./serve-http.js";
+import { performAtHead } from "./head.js";
+import { createHash } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { hashFieldValue } from "./hash.js";
+import { appendActionIfAbsent, appendActionOccurrence, decideAndAppendAction, projectResources } from "./actions.js";
+import { observeWorldPaths, worldPaths } from "./storage.js";
+import { getActiveWorldStore } from "./world-store.js";
+/** The journal read back: every entry kept for a service, oldest first (an empty list when the journal is off or empty). */
+export function readTwinRequestJournal(service, root) {
+    const path = twinRequestJournalPath(service, root);
+    const out = [];
+    for (const file of [`${path}.1`, path]) {
+        const text = getActiveWorldStore().read(file);
+        if (!text)
+            continue;
+        for (const line of text.split('\n')) {
+            if (!line)
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch { /* a torn line at rotation */ }
+        }
+    }
+    return out;
+}
+/** ~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) {
+    return `sha256:${createHash('sha256').update(value, 'utf8').digest('hex').slice(0, 16)}`;
+}
+function credentialShapeFor(name, value, where) {
+    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, url) {
+    const shapes = [];
+    const seen = new Set();
+    const add = (name, value, where) => {
+        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.forEach === 'function') {
+            headers.forEach((value, name) => add(name, value, 'header'));
+        }
+        else {
+            for (const [name, value] of Object.entries(headers))
+                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 = process.env) {
+    return env.VOLTER_TWIN_REQUEST_JOURNAL === '1';
+}
+/** Where a service's request journal lives: beside its `actions.jsonl`. */
+export function twinRequestJournalPath(service, root) {
+    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, entry, root) {
+    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,
+            ...(typeof entry.ms === 'number' ? { ms: entry.ms } : {}),
+            ...(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');
+/** 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;
+function identitySlot() {
+    identityCapture ??= new AsyncLocalStorage();
+    return identityCapture;
+}
+function observeIdentityFromWorldPaths() {
+    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 = process.argv) {
+    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(['world-runtime', 'world-tooling', 'world-attach', 'world-browser-assets', 'world-host']);
+export function vendorFromStack(stack) {
+    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() {
+    // a browser bundle (a mirror UI carrying the kernel): nothing to wrap, nothing to touch
+    if (typeof window !== 'undefined' || typeof document !== 'undefined')
+        return false;
+    const bun = globalThis.Bun;
+    const original = bun && typeof bun.serve === 'function' ? bun.serve : undefined;
+    if (original && original[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();
+    // every server made through the seam (serve-http.ts) journals — on Node this is the only wrap
+    setServeDecorator((options) => journalingFetch(options, vendorFromStack(new Error().stack)));
+    if (!original)
+        return false; // Node: no global to wrap; the seam carries the journal
+    const wrapped = function serve(options, ...rest) {
+        const config = options;
+        if (!config || typeof config.fetch !== 'function')
+            return original.apply(this, [options, ...rest]);
+        // 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 = config[TWIN_JOURNAL_IDENTITY] ? undefined : vendorFromStack(new Error().stack);
+        return original.apply(this, [{ ...config, fetch: journalingFetch(config, callSiteVendor) }, ...rest]);
+    };
+    Object.defineProperty(wrapped, JOURNAL_SHIM_INSTALLED, { value: true });
+    bun.serve = wrapped;
+    return true;
+}
+/** The journaling form of a server's fetch handler: identity resolved once per SERVER (declared
+ *  under TWIN_JOURNAL_IDENTITY, else observed from the first state-touching request, else the
+ *  call-site vendor + `--root`), every request journaled with its method, path and status. */
+function journalingFetch(config, callSiteVendor) {
+    if (config.twinRequestJournal === false)
+        return config.fetch;
+    {
+        const declared = config[TWIN_JOURNAL_IDENTITY];
+        // Resolved once per SERVER, not per request: a twin's identity is a constant of the server.
+        let identity = declared;
+        const inner = config.fetch;
+        const journaling = async function (request, server) {
+            // The World's own boot probe (serve-http.ts, WORLD_BOOT_PATH) is not the app's traffic: never journaled.
+            if (!twinRequestJournalEnabled() || new URL(request.url).pathname === WORLD_BOOT_PATH)
+                return inner.call(this, request, server);
+            const slot = {};
+            let status = 500;
+            const startedAt = Date.now();
+            try {
+                const response = (await identitySlot().run(slot, () => inner.call(this, request, server)));
+                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,
+                        ms: Date.now() - startedAt,
+                        credentials: twinRequestCredentials(request.headers, url),
+                    }, resolved.root);
+                }
+            }
+        };
+        return journaling;
+    }
+}
+/** 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) {
+    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/world-core`'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();
+// The twin's current view = the OBSERVED mirror (events.jsonl) with the local
+// ACTION log (actions.jsonl) projected over it (R18). Observed facts and local
+// actions are kept separate; this is the single projected read model.
+export function twinResources(service, root) {
+    return projectResources(service, root);
+}
+function actionForTwinWrite(service, write) {
+    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 });
+    // A caller-supplied identity MAY carry an occurrence ordinal, and must: `actionId`'s one
+    // legitimate caller is replay, and a replayed changeset that contains a REPEAT carries the
+    // source's `<base>#1` verbatim. A guard here that rejected ordinal suffixes — added to stop a
+    // pack squatting slot #5 — threw on exactly that replay, and nothing had tested "replay a
+    // repeat" (found 2026-09-04 in review). The squat it guarded against is a misuse of a
+    // replay-only field, is LOUD on collision, and corrupts nothing; breaking the CI primitive to
+    // prevent it was the wrong trade.
+    const actionId = write.actionId
+        ?? (write.idempotencyKey
+            ? `twin:${service}:${write.operation}:${write.subjectId}:idem:${write.idempotencyKey}`
+            : `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.idempotencyKey ? { idempotencyKey: write.idempotencyKey } : {}),
+        ...(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(service, prepare, root) {
+    // Same ruling as applyTwinWrite: a local write is an OCCURRENCE unless the caller supplied
+    // identity. The mode rides on the decision because only the callback knows which write it chose.
+    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),
+            identity: decision.write.idempotencyKey || decision.write.actionId ? 'caller' : 'occurrence',
+        };
+    }, root);
+    // as applyTwinWrite: a seed's write is the placeholder's default data, never performed
+    const head = committed.action && committed.appended && !committed.placeholder ? await performAtHead(service, committed.action, root) : { performed: false };
+    return {
+        value: committed.value,
+        ...(committed.action ? { result: { status: committed.appended ? 'performed' : 'replayed', actionId: committed.action.id, ...(head.externalId ? { externalId: head.externalId } : {}) } } : {}),
+    };
+}
+// 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 }
+//   GET /<type>                 -> list of resources of that type
+//   GET /<type>/<id>            -> one resource (id may be url-encoded)
+export function resolveTwinRead(service, pathname, opts = {}) {
+    const resources = twinResources(service, opts.root);
+    const parts = pathname.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
+    if (parts.length === 0) {
+        const types = [...new Set(resources.map((r) => r.type))].sort();
+        return { status: 200, body: { service, resourceTypes: types, count: resources.length } };
+    }
+    const type = parts[0];
+    const ofType = resources.filter((r) => r.type === type);
+    if (parts.length === 1) {
+        return { status: 200, body: { type, count: ofType.length, items: ofType } };
+    }
+    const id = decodeURIComponent(parts.slice(1).join('/'));
+    const found = ofType.find((r) => r.id === id);
+    if (!found)
+        return { status: 404, body: { error: 'not_found', type, id } };
+    return { status: 200, body: found };
+}
+// Simulator/fork-mode write: the twin ACCEPTS a write as a LOCAL ACTION appended
+// to the action log (R18) — NOT an observed event and NOT an egress/real write.
+// State is the mirror with this action projected over it, so a subsequent read
+// returns the change. The observed event log is untouched; the real service is
+// provably untouched (no network I/O, no egress). Pushing the action to the real
+// vendor is a separate, explicit step that records egress + confirms the action.
+export async function applyTwinWrite(service, write, root) {
+    const action = actionForTwinWrite(service, write);
+    // A LOCAL VENDOR WRITE IS AN OCCURRENCE. Two calls are two actions, even byte-identical in the
+    // same instant, and the ordinal in the action id says which occurrence this is. The kernel used
+    // to derive identity from (content + occurredAt millisecond) and drop a repeat as `replayed`,
+    // which silently lost any write returning a subject to a value it previously held — permanently,
+    // under a pinned world clock, where every write in a world shares one instant. That default cost
+    // github, slack and jira live defects while the recipe told each pack to defend itself with a
+    // per-write ordinal and a fifth of the catalog opted out via `uniqueness`. A default every pack
+    // must remember to defend against is not a default. See docs/contributing/adding-a-twin.md
+    // #5-build-on-the-shared-kernel--dont-reinvent, "A local write is an occurrence".
+    //
+    // AT-MOST-ONCE is opt in, by KEY: `idempotencyKey` makes the id a function of the caller's own
+    // request identity, so a re-issue collapses onto the first and answers `replayed`. Content can
+    // never decide this — it cannot separate the same request delivered twice from the same change
+    // made twice — which is why the kernel no longer tries.
+    //
+    // `uniqueness` is subsumed and still honoured: it was the escape hatch packs reached for when
+    // the default was backwards (a billable AI completion that must ledger every call), and with
+    // occurrence semantics it is simply redundant rather than wrong.
+    //
+    // correlationId (D3): a caller-supplied request-scoped id lands on the action row; the appenders
+    // generate one when omitted, so it's never missing.
+    const committed = write.idempotencyKey || write.actionId
+        ? appendActionIfAbsent(action, root)
+        : appendActionOccurrence(action, root);
+    // The COMMITTED action's id, not the one computed before the lock: an occurrence past the first
+    // carries an ordinal, and a caller told the base id would be naming an action that is not there.
+    const { appended, action: landed } = committed;
+    // THE HEAD (head.ts): a twin whose root says `auto` performs the entry now, before the app is
+    // answered; the vendor's id, when it minted one, is the id the answer carries.
+    // a write landed as the placeholder's default data (a seed) is a pull, never a commit: the head is not asked
+    const head = appended && !committed.placeholder ? await performAtHead(service, landed, root) : { performed: false };
+    const answerId = head.externalId ?? write.subjectId;
+    const result = { status: appended ? 'performed' : 'replayed', actionId: landed.id, ...(head.externalId ? { externalId: head.externalId } : {}), ...(head.data !== undefined ? { vendorData: head.data } : {}) };
+    // THE WRITTEN RESOURCE, read when a caller asks for it. Projecting the whole tree after every write to answer it
+    // made each write O(tree) and a batch of N writes O(N x tree), whether or not the caller used the answer (a Timestream
+    // seed of a member's wearable history stalled its twin for minutes). Resolved by (type, id): an id alone is ambiguous
+    // when two resource TYPES share it.
+    let resolved;
+    return {
+        result,
+        get resource() {
+            return resolved ??= projectResources(service, root).find((r) => r.type === write.subjectType && r.id === answerId)
+                ?? { id: answerId, type: write.subjectType, updatedAt: landed.occurredAt, ...write.fields };
+        },
+    };
+}
+export async function createTwinServer(options) {
+    const readOnly = options.readOnly ?? false;
+    const serveOptions = {
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        async fetch(request) {
+            const url = new URL(request.url);
+            const json = (status, body) => 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 });
+                return json(status, body);
+            }
+            // Writes are accepted as local actions unless this twin was started read-only.
+            if (readOnly)
+                return json(405, { error: 'read_only', hint: 'this twin was started read-only; omit readOnly to accept writes' });
+            const parts = url.pathname.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
+            if (parts.length < 2)
+                return json(400, { error: 'write_needs_type_and_id', hint: 'POST /<type>/<id> with a JSON body of fields' });
+            let fields;
+            try {
+                fields = (await request.json());
+            }
+            catch {
+                return json(400, { error: 'invalid_json_body' });
+            }
+            // AT-MOST-ONCE OVER HTTP, the way vendors spell it. A local write is an occurrence, so an
+            // identical repeat POST is a second action and answers 201 — which is the truth, and a change
+            // from the old content-dedupe behaviour. A caller that means "the same request again" sends
+            // `Idempotency-Key`, exactly as Stripe and others define it, and gets 200 `replayed`. Without
+            // this the `replayed` arm below was unreachable on the kernel's own write endpoint.
+            const idempotencyKey = request.headers.get('idempotency-key') ?? undefined;
+            let committed;
+            try {
+                committed = await applyTwinWrite(options.service, {
+                    operation: `${request.method.toLowerCase()}.${parts[0]}`,
+                    subjectType: parts[0],
+                    subjectId: decodeURIComponent(parts.slice(1).join('/')),
+                    fields,
+                    actor: { kind: 'agent' },
+                    ...(idempotencyKey ? { idempotencyKey } : {}),
+                }, options.root);
+            }
+            catch (e) {
+                // A key REUSED WITH A DIFFERENT PAYLOAD is the caller's error, and the vendors that have
+                // this header say so with a 400 and an `idempotency_error` code. The kernel raises it as a
+                // conflicting-duplicate throw, which this server was letting escape as a 500 HTML page —
+                // found 2026-09-04 in review, one day after the header was wired. Anything else is still
+                // a genuine failure and still propagates.
+                if (idempotencyKey && e instanceof Error && e.message.startsWith('Conflicting duplicate twin action')) {
+                    return json(400, { error: 'idempotency_error', message: `Keys for idempotent requests can only be used with the same parameters they were first used with. Try using a key other than '${idempotencyKey}' if you meant to execute a different request.` });
+                }
+                throw e;
+            }
+            const { result, resource } = committed;
+            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 = await serveHttp(serveOptions);
+    return { port: server.port, stop: () => { void server.stop(true); } };
+}

package/dist/src/shared-blob-index.d.ts

@@ -0,0 +1,4 @@
+export declare function sharedBlobIndex(root: string, destinationDevice: number, digest: string): {
+    reuse(temporary: string, size: number): boolean;
+    record(key: string): void;
+};

package/dist/src/shared-blob-index.js

@@ -0,0 +1,126 @@
+// A disposable lookup cache, not a byte store. Only owning World files retain payloads.
+import { createHash } from 'node:crypto';
+import { closeSync, constants, fstatSync, ftruncateSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, rmSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+const MAX_BUCKET_BYTES = 128 * 1024;
+const MAX_ENTRIES = 32;
+const MAX_PATHS = 4;
+function privateFile(stat) {
+    return stat.isFile() && stat.nlink === 1 && (!process.getuid || stat.uid === process.getuid()) && (stat.mode & 0o077) === 0;
+}
+function privateDirectory(root) {
+    try {
+        const stat = lstatSync(root);
+        return stat.isDirectory() && (stat.mode & 0o077) === 0 && (!process.getuid || stat.uid === process.getuid());
+    }
+    catch {
+        return false;
+    }
+}
+function readIndex(file) {
+    let fd;
+    try {
+        fd = openSync(file, constants.O_RDONLY | constants.O_NONBLOCK | (constants.O_NOFOLLOW ?? 0));
+        const stat = fstatSync(fd);
+        if (!privateFile(stat) || stat.size > MAX_BUCKET_BYTES)
+            return {};
+        const parsed = JSON.parse(readFileSync(fd, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        const index = {};
+        for (const [key, paths] of Object.entries(parsed).slice(-MAX_ENTRIES)) {
+            if (!/^\d+:[a-f0-9]{64}$/.test(key) || !Array.isArray(paths))
+                continue;
+            index[key] = paths.filter((path) => typeof path === 'string' && path.length <= 4096 && isAbsolute(path)).slice(0, MAX_PATHS);
+        }
+        return index;
+    }
+    catch {
+        return {};
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function digestFile(file, size) {
+    const fd = openSync(file, 'r');
+    try {
+        const hash = createHash('sha256');
+        const buffer = Buffer.allocUnsafe(64 * 1024);
+        let remaining = size;
+        while (remaining > 0) {
+            const length = readSync(fd, buffer, 0, Math.min(buffer.length, remaining), null);
+            if (!length)
+                return null;
+            hash.update(buffer.subarray(0, length));
+            remaining -= length;
+        }
+        if (readSync(fd, buffer, 0, 1, null))
+            return null;
+        return hash.digest('hex');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function sharedBlobIndex(root, destinationDevice, digest) {
+    // 256 buckets with bounded entries/bytes keep metadata bounded across roots and devices.
+    const file = join(root, `${digest.slice(0, 2)}.json`);
+    const entry = `${destinationDevice}:${digest}`;
+    return {
+        reuse(temporary, size) {
+            if (!privateDirectory(root))
+                return false;
+            for (const candidate of readIndex(file)[entry] ?? []) {
+                try {
+                    const source = lstatSync(candidate);
+                    if (!source.isFile() || source.dev !== destinationDevice || source.size !== size
+                        || (process.getuid && source.uid !== process.getuid()))
+                        continue;
+                    linkSync(candidate, temporary);
+                    // Check the actual linked file, not a source path that could have been replaced.
+                    const linked = lstatSync(temporary);
+                    if (linked.isFile() && linked.dev === destinationDevice && linked.size === size
+                        && (!process.getuid || linked.uid === process.getuid()) && digestFile(temporary, size) === digest)
+                        return true;
+                }
+                catch { /* A cache miss, stale path, unsupported link, or corrupt candidate. */ }
+                rmSync(temporary, { force: true });
+            }
+            return false;
+        },
+        record(key) {
+            try {
+                const path = resolve(key);
+                if (path.length > 4096)
+                    return;
+                const index = readIndex(file);
+                const paths = [path, ...(index[entry] ?? []).filter((old) => old !== path)].slice(0, MAX_PATHS);
+                delete index[entry];
+                index[entry] = paths;
+                let text = JSON.stringify(index);
+                while (Object.keys(index).length > MAX_ENTRIES || Buffer.byteLength(text) > MAX_BUCKET_BYTES) {
+                    delete index[Object.keys(index)[0]];
+                    text = JSON.stringify(index);
+                }
+                mkdirSync(root, { recursive: true, mode: 0o700 });
+                if (!privateDirectory(root))
+                    return;
+                // A torn/concurrent index update is just a cache miss. Writing the bounded
+                // bucket directly avoids retaining metadata temp files after SIGKILL.
+                const fd = openSync(file, constants.O_WRONLY | constants.O_CREAT | constants.O_NONBLOCK | (constants.O_NOFOLLOW ?? 0), 0o600);
+                try {
+                    if (!privateFile(fstatSync(fd)))
+                        return;
+                    ftruncateSync(fd, 0);
+                    writeFileSync(fd, text);
+                }
+                finally {
+                    closeSync(fd);
+                }
+            }
+            catch { /* Index storage is optional: the World already owns its complete bytes. */ }
+        },
+    };
+}