@volter/world-core 2.0.0

package/src/git/smart-http.ts

@@ -0,0 +1,149 @@
+// SMART HTTP (gitprotocol-http, protocol v0): what `git clone|fetch|push` speak to a server. The
+// twin answers the advertisement (`info/refs?service=`), upload-pack (wants, haves, done → NAK
+// and a pack of the closure the client lacks) and receive-pack (ref commands, a pack, a
+// report-status) with nothing but the object store, the refs and a push policy. Protocol v2 is
+// not advertised; a client that asks for it falls back to v0 on this answer, as git specifies.
+import { GitObjectStore, decodeCommit, decodeTag, decodeTree, type GitObjectType } from './objects.ts';
+import { readPack, writePack } from './pack.ts';
+import type { GitRefs } from './refs.ts';
+
+const ENC = new TextEncoder(); const DEC = new TextDecoder();
+export const ZERO_SHA = '0'.repeat(40);
+export const FLUSH = new Uint8Array([0x30, 0x30, 0x30, 0x30]);
+export function pktLine(s: string | Uint8Array): Uint8Array {
+  const body = typeof s === 'string' ? ENC.encode(s) : s; const len = (body.length + 4).toString(16).padStart(4, '0');
+  const out = new Uint8Array(body.length + 4); out.set(ENC.encode(len), 0); out.set(body, 4); return out;
+}
+/** Pkt-lines up to and including the first flush; `rest` is what follows (a pack, on push). */
+export function readPktLines(bytes: Uint8Array): { lines: string[]; rest: Uint8Array } {
+  const lines: string[] = []; let at = 0;
+  while (at + 4 <= bytes.length) {
+    const len = parseInt(DEC.decode(bytes.subarray(at, at + 4)), 16);
+    if (Number.isNaN(len)) return { lines, rest: bytes.subarray(at) };
+    if (len === 0) return { lines, rest: bytes.subarray(at + 4) };
+    if (len < 4) { at += 4; continue; } // v2 delimiter/response-end packets: no payload
+    lines.push(DEC.decode(bytes.subarray(at + 4, at + len))); at += len;
+  }
+  return { lines, rest: bytes.subarray(at) };
+}
+/** Every pkt-line in the body across all flushes (stateless clients batch haves between flushes); `rest` follows the first flush. */
+export function readAllPktLines(bytes: Uint8Array): { lines: string[]; rest: Uint8Array } {
+  const first = readPktLines(bytes); const lines = [...first.lines]; let cur = first.rest;
+  while (cur.length >= 4 && /^[0-9a-f]{4}$/.test(DEC.decode(cur.subarray(0, 4))) && !cur.subarray(0, 4).every((b, i) => b === 'PACK'.charCodeAt(i))) { const n = readPktLines(cur); lines.push(...n.lines); if (n.rest.length === cur.length) break; cur = n.rest; }
+  return { lines, rest: first.rest };
+}
+const SHA = /^[0-9a-f]{40}$/;
+function cat(...parts: Uint8Array[]): Uint8Array { const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0)); let o = 0; for (const p of parts) { out.set(p, o); o += p.length; } return out; }
+
+export type Service = 'git-upload-pack' | 'git-receive-pack';
+const CAPS: Record<Service, string> = { 'git-upload-pack': 'ofs-delta no-progress agent=volter-twin', 'git-receive-pack': 'report-status delete-refs ofs-delta agent=volter-twin' };
+
+/** `GET info/refs?service=<service>`: the ref advertisement, HEAD first as a symref. */
+export function advertisement(service: Service, refs: GitRefs): Uint8Array {
+  const all = refs.list(); const head = refs.head(); const headSha = refs.get(head);
+  const caps = `${CAPS[service]} symref=HEAD:${head}`;
+  const lines: Uint8Array[] = [pktLine(`# service=${service}\n`), FLUSH];
+  if (headSha) lines.push(pktLine(`${headSha} HEAD\0${caps}\n`));
+  const rest = all;
+  if (!headSha && rest.length === 0) lines.push(pktLine(`${ZERO_SHA} capabilities^{}\0${caps}\n`));
+  let first = headSha === null;
+  for (const r of rest) { lines.push(pktLine(first ? `${r.sha} ${r.name}\0${caps}\n` : `${r.sha} ${r.name}\n`)); first = false; }
+  lines.push(FLUSH);
+  return cat(...lines);
+}
+
+/** Every object reachable from `roots`, stopping at `seen`. */
+async function closure(store: GitObjectStore, roots: string[], seen: Set<string>): Promise<Array<{ type: GitObjectType; payload: Uint8Array; sha: string }>> {
+  const out: Array<{ type: GitObjectType; payload: Uint8Array; sha: string }> = []; const stack = [...roots];
+  while (stack.length) {
+    const sha = stack.pop()!; if (seen.has(sha)) continue; seen.add(sha);
+    const obj = await store.read(sha); if (!obj) continue;
+    out.push({ ...obj, sha });
+    if (obj.type === 'commit') { const c = decodeCommit(obj.payload); stack.push(c.tree, ...c.parents); }
+    else if (obj.type === 'tree') { for (const e of decodeTree(obj.payload)) if (e.mode !== '160000') stack.push(e.sha); }
+    else if (obj.type === 'tag') stack.push(decodeTag(obj.payload).object);
+  }
+  return out;
+}
+async function reachable(store: GitObjectStore, roots: string[]): Promise<Set<string>> { const seen = new Set<string>(); await closure(store, roots, seen); return seen; }
+
+/** `POST git-upload-pack`: wants and haves in, NAK and (once `done`) the pack out. */
+export async function uploadPack(body: Uint8Array, store: GitObjectStore): Promise<Uint8Array> {
+  const { lines } = readAllPktLines(body);
+  const wants = lines.filter((l) => l.startsWith('want ')).map((l) => l.slice(5, 45)).filter((s) => SHA.test(s));
+  const haves = lines.filter((l) => l.startsWith('have ')).map((l) => l.slice(5, 45)).filter((s) => SHA.test(s));
+  const done = lines.some((l) => l.trim() === 'done');
+  const known: string[] = []; for (const h of haves) if (await store.has(h)) known.push(h);
+  for (const w of wants) if (!(await store.has(w))) return pktLine(`ERR upload-pack: not our ref ${w}\n`);
+  if (!done) return pktLine('NAK\n');
+  const seen = await reachable(store, known); const objects = await closure(store, wants, seen);
+  return cat(pktLine('NAK\n'), await writePack(objects));
+}
+
+export type RefCommand = { old: string; new: string; name: string; /** false when `new` does not descend from `old` (a force push); true for creates, deletes and fast-forwards. */ fastForward: boolean };
+/** Bounded ancestry walk: is `ancestor` reachable from `sha` through parents? */
+export async function isAncestor(store: GitObjectStore, ancestor: string, sha: string, limit = 5000): Promise<boolean> {
+  const seen = new Set<string>(); const stack = [sha];
+  while (stack.length && seen.size < limit) { const s = stack.pop()!; if (s === ancestor) return true; if (seen.has(s)) continue; seen.add(s); const o = await store.read(s); if (o?.type === 'commit') stack.push(...decodeCommit(o.payload).parents); }
+  return false;
+}
+export type PushPolicy = (cmd: RefCommand) => string | null | Promise<string | null>;
+/** `POST git-receive-pack`: commands and a pack in, refs updated under `policy`, report-status out. */
+export async function receivePack(body: Uint8Array, store: GitObjectStore, refs: GitRefs, policy: PushPolicy = () => null): Promise<{ response: Uint8Array; applied: RefCommand[] }> {
+  const { lines, rest } = readPktLines(body);
+  const commands: RefCommand[] = lines.map((l) => l.split('\0')[0]!.trim()).filter(Boolean).map((l) => { const [o, n, name] = l.split(' '); return { old: o!, new: n!, name: name!, fastForward: true }; }).filter((c) => SHA.test(c.old) && SHA.test(c.new) && /^refs\/[^\s]+$/.test(c.name));
+  const report: Uint8Array[] = [];
+  let unpack = 'ok';
+  if (rest.length >= 12) { try { await readPack(rest, store); } catch (e) { unpack = (e as Error).message; } }
+  report.push(pktLine(`unpack ${unpack}\n`));
+  const applied: RefCommand[] = [];
+  const existing = refs.list().map((r) => r.name);
+  const verdicts: Array<{ cmd: RefCommand; reason: string | null }> = [];
+  for (const cmd of commands) {
+    const current = refs.get(cmd.name) ?? ZERO_SHA;
+    let reason: string | null = unpack === 'ok' ? null : 'unpacker error';
+    if (!reason && current !== cmd.old) reason = 'fetch first';
+    if (!reason && current === ZERO_SHA && existing.some((n) => n.startsWith(`${cmd.name}/`) || cmd.name.startsWith(`${n}/`))) reason = 'ref name conflict';
+    if (!reason && cmd.new !== ZERO_SHA && !(await store.has(cmd.new))) reason = 'missing necessary objects';
+    if (!reason && cmd.old !== ZERO_SHA && cmd.new !== ZERO_SHA) cmd.fastForward = await isAncestor(store, cmd.old, cmd.new);
+    if (!reason) reason = await policy(cmd);
+    verdicts.push({ cmd, reason });
+  }
+  // Apply under the refs lock, re-reading each old value: a racing push that won in between is
+  // told `fetch first` rather than silently overwritten.
+  refs.withLock(() => {
+    for (const v of verdicts) {
+      if (!v.reason && (refs.get(v.cmd.name) ?? ZERO_SHA) !== v.cmd.old) v.reason = 'fetch first';
+      if (v.reason) { report.push(pktLine(`ng ${v.cmd.name} ${v.reason}\n`)); continue; }
+      if (v.cmd.new === ZERO_SHA) refs.delete(v.cmd.name); else refs.set(v.cmd.name, v.cmd.new);
+      applied.push(v.cmd); report.push(pktLine(`ok ${v.cmd.name}\n`));
+    }
+  });
+  report.push(FLUSH);
+  return { response: cat(...report), applied };
+}
+
+export type GitRepo = { store: GitObjectStore; refs: GitRefs; policy?: PushPolicy; onPush?: (applied: RefCommand[]) => void | Promise<void> };
+/** Route one request under a repo: returns null when the path is not a smart-HTTP endpoint. */
+export async function serveSmartHttp(req: Request, repo: GitRepo, tailPath: string): Promise<Response | null> {
+  const url = new URL(req.url);
+  if (req.method === 'GET' && tailPath === 'info/refs') {
+    const service = url.searchParams.get('service') as Service | null;
+    if (service !== 'git-upload-pack' && service !== 'git-receive-pack') return new Response('smart HTTP only', { status: 403 });
+    return new Response(advertisement(service, repo.refs) as unknown as BodyInit, { headers: { 'content-type': `application/x-${service}-advertisement`, 'cache-control': 'no-cache' } });
+  }
+  if (req.method === 'POST' && (tailPath === 'git-upload-pack' || tailPath === 'git-receive-pack')) {
+    return serveSmartHttpPost(new Uint8Array(await req.arrayBuffer()), req.headers.get('content-encoding') ?? '', repo, tailPath);
+  }
+  return null;
+}
+/** The POST half of `serveSmartHttp` for a caller that already holds the body: a push pack is
+ *  the size of the repository, so re-wrapping it in a Request only to read it back is a full copy. */
+export async function serveSmartHttpPost(body: Uint8Array, contentEncoding: string, repo: GitRepo, tailPath: 'git-upload-pack' | 'git-receive-pack'): Promise<Response> {
+  if (contentEncoding.includes('gzip')) body = new Uint8Array(await new Response(new Response(body as unknown as BodyInit).body!.pipeThrough(new DecompressionStream('gzip'))).arrayBuffer());
+  const headers = { 'content-type': `application/x-${tailPath}-result`, 'cache-control': 'no-cache' };
+  if (tailPath === 'git-upload-pack') return new Response((await uploadPack(body, repo.store)) as unknown as BodyInit, { headers });
+  const { response, applied } = await receivePack(body, repo.store, repo.refs, repo.policy);
+  if (applied.length && repo.onPush) await repo.onPush(applied);
+  return new Response(response as unknown as BodyInit, { headers });
+}

package/src/hash.ts

@@ -0,0 +1,66 @@
+// HASHING AND THE DELTA READER — the one canonicalizer in this package, the content hash every
+// id and every changeset hash is built on, and the reader of a v1 delta row's `after` values.
+// (What else shadow.ts held — refs, bases, observed deltas as a row kind — left with v1.)
+import { createHash } from 'node:crypto';
+import type { WorldServiceEvent } from './types.ts';
+
+
+export const DELTA_TYPE_SUFFIX = '.delta';
+
+export type SubjectFields = Record<string, unknown>;
+
+/**
+ * Maps a world event to the subject fields it observes, or null when the
+ * event says nothing about remote subject state (comments, egress records, …).
+ * Extractors are provider-specific; the shadow engine is not.
+ */
+export type SubjectFieldExtractor = (event: WorldServiceEvent) => SubjectFields | null;
+
+export type FieldChange = { before: unknown; after: unknown };
+
+/** 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>)
+      .filter(([, item]) => item !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`);
+    return `{${entries.join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+export function hashFieldValue(value: unknown): string {
+  return createHash('sha256').update(canonicalJson(value)).digest('hex').slice(0, 16);
+}
+
+export function subjectKey(subject: { type: string; id: string }): string {
+  return `${subject.type}:${subject.id}`;
+}
+
+/** Field-level diff of freshly observed subject fields against a shadow of them. */
+export type SubjectShadow = { subject: { type: string; id: string }; fields: SubjectFields; fieldHashes: Record<string, string>; latestEventId: string; updatedAt: string };
+export function diffSubjectFields(shadow: SubjectShadow | undefined, observed: SubjectFields): Record<string, FieldChange> {
+  const changed: Record<string, FieldChange> = {};
+  for (const [field, after] of Object.entries(observed)) {
+    if (after === undefined) continue;
+    const beforeHash = shadow?.fieldHashes[field];
+    if (beforeHash !== undefined && beforeHash === hashFieldValue(after)) continue;
+    changed[field] = { before: shadow?.fields[field], after };
+  }
+  return changed;
+}
+
+export function isDeltaEvent(event: WorldServiceEvent): boolean { return typeof event.type === 'string' && event.type.endsWith(DELTA_TYPE_SUFFIX); }
+
+/** THE canonical delta reader: a v1 delta row's `changed.<field>.after` values. */
+export function deltaAfterFields(event: WorldServiceEvent): SubjectFields {
+  const changed = (event.data as { changed?: Record<string, FieldChange> }).changed ?? {};
+  const fields: SubjectFields = {};
+  for (const [field, change] of Object.entries(changed)) fields[field] = change.after;
+  return fields;
+}

package/src/head.ts

@@ -0,0 +1,318 @@
+// THE HEAD — where a write is applied (company contract "The head", ruled 2026-09-06).
+//
+// Every write is an entry first. Then the twin's head says what happens to it: no root, or a root
+// under `gated`/`hold`, and the entry waits (simulated); a root under `auto`, and the entry is
+// PERFORMED NOW, in the process that serves the twin, before the app is answered — checks, then the
+// pack's perform adapter over the kernel executor with the credential opened from its seal, then
+// the landed copy with the receipt. The push door and `volter world deploy` perform through the
+// same `performEntries`; there is no hook and no phase ledger. The receipt on the entry is the
+// record: a `deployed` copy is never performed again, a `failed` one is retried.
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { confirmAction, isTwinBookkeeping, resolveSubjectId, revertAction, type TwinAction } from './actions.ts';
+import { openSealedCredential, sealCredential, type CredentialPayload, type SealedCredential } from './credential.ts';
+import { buildRemoteExecute, validateRemoteOrigin, type CredentialCustody } from './executor.ts';
+import { getPack } from './packRegistry.ts';
+import type { RemoteExecute } from './remote-execute.ts';
+import { aliasesFrom, branchEntries, parentEntries, readTree, type Entry, type Receipt } from './log.ts';
+import { resolveReferences } from './references.ts';
+import { authStrategyFor, NO_SECRETS_CHECK, readRoot, runChecks, stateSystemFor, type Check, type DeployPolicy, type RootConfig, type StateSystemAdapters } from './state-system.ts';
+import { stateDirName, worldPaths } from './storage.ts';
+import { worldNow } from './world-clock.ts';
+import { getActiveWorldStore } from './world-store.ts';
+
+// ── the pack's perform adapter ──────────────────────────────────────────────────────────────
+
+/** What a perform answers: the id the vendor minted (the local id when it kept ours), its URL, and
+ *  the vendor's answer as fields for the landed copy. */
+export type PushOutcome = { externalId: string; url?: string; data?: Record<string, unknown> };
+/** What a perform is handed beside the executor: a resolver from a local id to the vendor's (an
+ *  entry authored against `twin-1` crosses against `REAL-42` once that subject's landing adopted it). */
+/** `credential`: the sealed credential's keyed fingerprint (credential.ts — an HMAC under the user's key,
+ *  never the secret and no offline oracle for it), so a pack keys its budget ledger per real credential:
+ *  every World and branch performing with one vendor key then shares that key's one allowance. */
+export type PerformContext = { resolve: (type: string, localId: string) => string; service?: string; root?: string; credential?: string };
+export type PerformAction = (execute: RemoteExecute, action: TwinAction, ctx: PerformContext) => Promise<PushOutcome>;
+export function performContext(service: string, root?: string, credential?: string): PerformContext {
+  return { resolve: (type, localId) => resolveSubjectId(service, type, localId, root), service, ...(root !== undefined ? { root } : {}), ...(credential !== undefined ? { credential } : {}) };
+}
+/** The keyed fingerprint of the root's sealed credential, or undefined when none is sealed. */
+function rootCredentialFingerprint(root: BoundRoot): string | undefined {
+  const sealed = getActiveWorldStore().read(root.credential);
+  if (sealed === null) return undefined;
+  const fingerprint = (JSON.parse(sealed) as SealedCredential).fingerprint;
+  return typeof fingerprint === 'string' && fingerprint !== '' ? fingerprint : undefined;
+}
+
+// ── the user's key and the sealed credential ────────────────────────────────────────────────
+
+/** The user's key-encryption key: `$XDG_CONFIG_HOME/volter/kek` (created on first use). */
+export function userKekPath(): string {
+  const base = process.env.XDG_CONFIG_HOME && process.env.XDG_CONFIG_HOME !== '' ? process.env.XDG_CONFIG_HOME : join(homedir(), '.config');
+  return join(base, 'volter', 'kek');
+}
+export function userKek(): string {
+  const path = userKekPath();
+  if (existsSync(path)) return readFileSync(path, 'utf8').trim();
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const key = Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString('base64');
+  writeFileSync(path, `${key}\n`, { mode: 0o600 });
+  chmodSync(path, 0o600);
+  return key;
+}
+
+/** Where the key that wraps every sealed credential comes from. A local World uses the user's key
+ *  file (`userKek`); a hosted World's host supplies its deployment's secret once at start. */
+let sealingKeySource: (() => string) | null = null;
+export function setSealingKeySource(source: (() => string) | null): void { sealingKeySource = source; }
+export function sealingKey(): string { return sealingKeySource ? sealingKeySource() : userKek(); }
+
+/** A root as a world materializes it: the config plus the path of the sealed credential. */
+export type BoundRoot = RootConfig & { credential: string };
+
+/** Open the credential a root names, under the user's key. */
+export async function openRootCredential(root: BoundRoot, vendor: string = vendorOf(root)): Promise<CredentialPayload> {
+  const sealed = getActiveWorldStore().read(root.credential);
+  if (sealed === null) throw new Error(`no credential sealed for ${vendor} — \`printf '<token>' | volter twin ${vendor} credential\``);
+  return openSealedCredential(sealingKey(), JSON.parse(sealed) as SealedCredential, vendor);
+}
+/** Seal a credential the vendor rotated (an `exchange` with `rotate`) where the root's was, under the same key and
+ *  slot. It is the same credential: its placedAt and fingerprint stay (a pack's budget keys its ledger by the
+ *  fingerprint, and a new one per grant would start the ledger over), and rotatedAt says when. */
+export async function resealRootCredential(root: BoundRoot, payload: CredentialPayload, vendor: string = vendorOf(root)): Promise<void> {
+  const store = getActiveWorldStore();
+  const held = store.read(root.credential);
+  const before = held === null ? null : (JSON.parse(held) as SealedCredential);
+  const now = new Date().toISOString();
+  const sealed = await sealCredential(sealingKey(), payload, before?.placedAt ?? now, vendor);
+  store.write(root.credential, `${JSON.stringify({ ...sealed, ...(before ? { fingerprint: before.fingerprint } : {}), rotatedAt: now }, null, 2)}\n`, { secret: true });
+}
+/** The root's custody for an exchange that rotates: the credential as sealed now, and the seal of a rotated one. */
+export function rootCustody(root: BoundRoot, vendor: string = vendorOf(root)): CredentialCustody {
+  // the credential's identity: its path and its fingerprint, which a rotation keeps and a user's re-seal of another
+  // credential changes, so a token exchanged for one account never answers for the next
+  const held = getActiveWorldStore().read(root.credential);
+  const fingerprint = held === null ? '' : String((JSON.parse(held) as SealedCredential).fingerprint ?? '');
+  return { key: `${root.credential}#${fingerprint}`, open: () => openRootCredential(root, vendor), seal: (credential) => resealRootCredential(root, credential, vendor) };
+}
+/** The vendor a root belongs to: its credential is sealed under the vendor's name. */
+export function vendorOf(root: BoundRoot): string { return basename(root.credential, '.json'); }
+/** The world a root belongs to: the credential sits at `<world>/.volter/credentials/<vendor>.json`. */
+export function worldRootOf(root: BoundRoot): string { return resolve(dirname(root.credential), '..', '..'); }
+
+// ── the world's checks ──────────────────────────────────────────────────────────────────────
+
+/** The checks a world runs before any entry is performed: the shipped no-secrets check, then every
+ *  file under `.volter/checks/` exporting `{ name, run }`. */
+export async function loadChecks(worldRoot: string): Promise<Check[]> {
+  const dir = join(resolve(worldRoot), stateDirName(), 'checks');
+  const out: Check[] = [NO_SECRETS_CHECK];
+  for (const file of getActiveWorldStore().list(dir).filter((f) => /\.(ts|js|mjs)$/.test(f)).sort()) out.push(await checkLoader(join(dir, file), file.replace(/\.(ts|js|mjs)$/, '')));
+  return out;
+}
+
+/** How a check file becomes a Check. Locally the file is imported; a hosted World's host supplies a
+ *  loader that runs the check in an isolate of its own, with no network and nothing of the World's. */
+export type CheckLoader = (path: string, name: string) => Promise<Check>;
+const importCheck: CheckLoader = async (path, name) => {
+  const mod = (await import(path)) as { check?: Check; default?: Check };
+  const check = mod.check ?? mod.default;
+  if (!check || typeof check.run !== 'function') throw new Error(`${path} must export a check { name, run }`);
+  return { name: check.name ?? name, run: check.run };
+};
+let checkLoader: CheckLoader = importCheck;
+export function setCheckLoader(loader: CheckLoader | null): void { checkLoader = loader ?? importCheck; }
+/** One check file through the host's loader: what placing a check validates with. */
+export function loadCheck(path: string, name: string): Promise<Check> { return checkLoader(path, name); }
+
+// ── the head ────────────────────────────────────────────────────────────────────────────────
+
+export type Head = { kind: 'simulated' } | { kind: 'real'; deploy: DeployPolicy; root: BoundRoot };
+
+/** The root a state service under `root` is bound to — its own root.json, else a sibling state's
+ *  (slack records under `chat`; the root was written under `slack`). */
+export function boundRoot(service: string, root?: string): BoundRoot | null {
+  const own = readRoot(service, root) as BoundRoot | null;
+  if (own?.credential) return own;
+  const stateRoot = dirname(worldPaths(service, root).dir);
+  const store = getActiveWorldStore();
+  const states = store.list(stateRoot).filter((name) => store.stat(join(stateRoot, name))?.isDirectory);
+  for (const state of states) { if (state === service) continue; const r = readRoot(state, root) as BoundRoot | null; if (r?.credential) return r; }
+  return null;
+}
+
+/** What this twin's head does with a write. */
+export function headOf(service: string, root?: string): Head {
+  const bound = boundRoot(service, root);
+  return bound ? { kind: 'real', deploy: bound.deploy, root: bound } : { kind: 'simulated' };
+}
+
+/** A check refused the write: the entry is in the log as refused; the pack answers in the vendor's error shape. */
+export class RefusedWriteError extends Error {
+  constructor(readonly check: string, readonly reason: string, readonly actionId: string) { super(`${check}: ${reason}`); this.name = 'RefusedWriteError'; }
+}
+/** The head could not be bound for a write that needed it (no credential sealed, no adapter registered,
+ *  no root): a server-side fault, answered as one. */
+export class HeadError extends Error {
+  constructor(message: string) { super(message); this.name = 'HeadError'; }
+}
+/** The vendor refused or failed the write: the entry is in the log as failed, with the vendor's words. */
+export class VendorWriteError extends Error {
+  constructor(message: string, readonly actionId: string) { super(message); this.name = 'VendorWriteError'; }
+}
+
+export type DeployReport = {
+  /** entries performed by this call */
+  pushed: number;
+  deployed: Array<{ actionId: string; externalId?: string; at: string; /** what the vendor answered, as the adapter returned it */ data?: unknown }>;
+  /** the first refusal; nothing after it was attempted */
+  refused?: { actionId: string; check: string; reason: string };
+  /** the first failure, with the vendor's words; nothing after it was attempted */
+  failed?: { actionId: string; error: string };
+  /** entries after the refusal or failure, not attempted */
+  skipped: string[];
+  /** entries whose landed copy already said `deployed` — not performed again */
+  replayed: string[];
+};
+
+/** The receipt a branch entry's latest landed copy carries, if any. */
+function receiptsByEntry(parent: Entry[]): Map<string, Receipt> {
+  const out = new Map<string, Receipt>();
+  for (const e of parent) if (e.landsId && e.receipt) out.set(e.landsId, e.receipt);
+  return out;
+}
+
+/** The branch entries a root twin still has to perform: `set` rows, not reverted, whose landed copy
+ *  is absent or says `failed`/`skipped` (a `deployed` or `refused` copy settles the entry). */
+export function deployableEntries(service: string, root?: string): TwinAction[] {
+  const parent = parentEntries(service, root);
+  const receipts = receiptsByEntry(parent);
+  const branch = branchEntries(service, root);
+  const reverted = new Set(branch.filter((e) => e.op === 'revert' && e.revertsActionId).map((e) => e.revertsActionId!));
+  return branch.filter((e) => {
+    if (e.op !== 'set' || reverted.has(e.id) || isTwinBookkeeping(e as TwinAction)) return false;
+    const r = receipts.get(e.id);
+    return r === undefined || r.status === 'failed' || r.status === 'skipped';
+  }) as TwinAction[];
+}
+
+const queues = new Map<string, Promise<unknown>>(); // one performer per twin: wire writes perform in append order
+
+/**
+ * PERFORM this twin's deployable entries against its root, in order, checks in front of every one,
+ * stopping at the first refusal or failure. Each outcome lands as the entry's copy with its receipt
+ * on the parent log. `actionIds` narrows to a changeset's (or one write's) entries.
+ */
+export async function performEntries(opts: {
+  service: string;
+  root?: string;
+  actionIds?: string[];
+  at?: string;
+  checks?: Check[];
+  adapters?: StateSystemAdapters;
+  execute?: RemoteExecute;
+}): Promise<DeployReport> {
+  const key = `${opts.root ?? ''}::${opts.service}`;
+  const prior = queues.get(key) ?? Promise.resolve();
+  const run = prior.then(() => performNow(opts), () => performNow(opts));
+  queues.set(key, run.catch(() => undefined));
+  return run;
+}
+
+async function performNow(opts: Parameters<typeof performEntries>[0]): Promise<DeployReport> {
+  const { service, root } = opts;
+  const head = headOf(service, root);
+  if (head.kind !== 'real') throw new Error(`the ${service} twin has no root — nothing to perform against`);
+  const vendor = vendorOf(head.root);
+  const adapters = opts.adapters ?? stateSystemFor(vendor) ?? stateSystemFor(service);
+  if (!adapters?.perform) throw new Error(`the ${vendor} twin has no perform adapter — a protocol 2 pack names one in its descriptor and registers itself (registerPack)`);
+  const execute = opts.execute ?? buildRemoteExecute(validateRemoteOrigin(head.root.url, { allowInsecureLoopback: true }), await openRootCredential(head.root, vendor), authStrategyFor(vendor), getPack(vendor)?.hosts, { custody: rootCustody(head.root, vendor) });
+  const checks = opts.checks ?? (await loadChecks(worldRootOf(head.root)));
+  const deployable = deployableEntries(service, root);
+  const entries = opts.actionIds === undefined ? deployable : opts.actionIds.map((id) => deployable.find((a) => a.id === id)).filter((a): a is TwinAction => a !== undefined);
+  const report: DeployReport = { pushed: 0, deployed: [], skipped: [], replayed: [] };
+  if (opts.actionIds) {
+    const settled = receiptsByEntry(parentEntries(service, root));
+    for (const id of opts.actionIds) if (settled.get(id)?.status === 'deployed') report.replayed.push(id);
+  }
+  let stopped = false;
+  for (const action of entries) {
+    if (stopped) { report.skipped.push(action.id); continue; }
+    const at = opts.at ?? worldNow();
+    const verdict = await runChecks(checks, action, readTree(service, root));
+    if (verdict) {
+      confirmAction({ service, actionId: action.id, subject: action.subject, fields: action.fields ?? {}, occurredAt: at, receipt: { status: 'refused', reason: `${verdict.name}: ${verdict.reason}` }, ...(root !== undefined ? { root } : {}) });
+      report.refused = { actionId: action.id, check: verdict.name, reason: verdict.reason };
+      stopped = true;
+      continue;
+    }
+    try {
+      // a declared reference to an adopted id is resolved before the pack sees the entry: the vendor is
+      // asked about #7, never the local #3 (docs/contributing/architecture.md#alias-aware-lookup-at-the-request-boundary)
+      const fields = resolveReferences(service, action.subject.type, action.fields ?? {}, aliasesFrom(parentEntries(service, root)));
+      const outcome = await adapters.perform(execute, fields === action.fields ? action : { ...action, fields }, performContext(service, root, rootCredentialFingerprint(head.root)));
+      // the vendor's answer, when the adapter returned one as fields, is what the landed copy holds
+      const answered = outcome.data !== null && typeof outcome.data === 'object' && !Array.isArray(outcome.data) ? (outcome.data as Record<string, unknown>) : {};
+      confirmAction({
+        service, actionId: action.id, subject: action.subject, fields: { ...fields, ...answered }, occurredAt: at,
+        ...(outcome.externalId ? { vendorSubjectId: outcome.externalId } : {}),
+        receipt: { status: 'deployed', ...(outcome.url ? { url: outcome.url } : {}) },
+        ...(root !== undefined ? { root } : {}),
+      });
+      report.pushed += 1;
+      report.deployed.push({ actionId: action.id, at, ...(outcome.externalId ? { externalId: outcome.externalId } : {}), ...(outcome.data !== undefined ? { data: outcome.data } : {}) });
+    } catch (error) {
+      // a write the pack itself refuses (it can never be sent: its subject never reached the vendor) is
+      // settled as refused, as a check's refusal is, so the next deploy moves on to the entry after it;
+      // anything else failed and stays deployable for a retry
+      if (error instanceof RefusedWriteError) {
+        confirmAction({ service, actionId: action.id, subject: action.subject, fields: action.fields ?? {}, occurredAt: at, receipt: { status: 'refused', reason: error.message }, ...(root !== undefined ? { root } : {}) });
+        report.refused = { actionId: action.id, check: error.check, reason: error.reason };
+        stopped = true;
+        continue;
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      confirmAction({ service, actionId: action.id, subject: action.subject, fields: action.fields ?? {}, occurredAt: at, receipt: { status: 'failed', reason: message }, ...(root !== undefined ? { root } : {}) });
+      report.failed = { actionId: action.id, error: message };
+      stopped = true;
+    }
+  }
+  return report;
+}
+
+/**
+ * The write path's second half (serve.ts): a write just appended to a twin whose head is real and
+ * `auto` is performed now. Returns the vendor's id when it minted one, so the answer carries it.
+ * Raises `RefusedWriteError` / `VendorWriteError` for the pack to answer in the vendor's shape.
+ */
+export async function performAtHead(service: string, action: Pick<TwinAction, 'id'>, root?: string): Promise<{ performed: boolean; externalId?: string; data?: unknown }> {
+  const head = headOf(service, root);
+  if (head.kind !== 'real' || head.deploy !== 'auto') return { performed: false };
+  let report: DeployReport;
+  try { report = await performEntries({ service, actionIds: [action.id], ...(root !== undefined ? { root } : {}) }); }
+  catch (error) { throw error instanceof HeadError ? error : new HeadError(error instanceof Error ? error.message : String(error)); }
+  // under live use an entry the vendor did not take does not stay in the tree: the app was told no, the
+  // world says no — a revert lands (the receipt stays on the original, so the log shows what happened)
+  const undone = report.refused?.actionId === action.id || report.failed?.actionId === action.id;
+  if (undone) revertAction({ service, actionId: action.id, occurredAt: worldNow(), ...(root !== undefined ? { root } : {}) });
+  if (report.refused?.actionId === action.id) throw new RefusedWriteError(report.refused.check, report.refused.reason, action.id);
+  if (report.failed?.actionId === action.id) throw new VendorWriteError(report.failed.error, action.id);
+  const done = report.deployed.find((d) => d.actionId === action.id);
+  return { performed: done !== undefined, ...(done?.externalId ? { externalId: done.externalId } : {}), ...(done?.data !== undefined ? { data: done.data } : {}) };
+}
+
+/** Wrap a pack's fetch: a `RefusedWriteError` or `VendorWriteError` the head raised becomes the
+ *  vendor's own error body (the pack's `shape`), so an app under live use sees what the vendor
+ *  would have said. Anything else propagates. */
+export function answerVendorErrors(fetch: (request: Request) => Promise<Response>, shape: (error: RefusedWriteError | VendorWriteError) => Response): (request: Request) => Promise<Response> {
+  return async (request: Request): Promise<Response> => {
+    try { return await fetch(request); } catch (error) {
+      if (error instanceof RefusedWriteError || error instanceof VendorWriteError) return shape(error);
+      // a head that could not be bound is a server error, answered as one (never a runtime's fallback
+      // page); anything else the twin threw propagates as it always did
+      if (error instanceof HeadError) return Response.json({ error: error.message }, { status: 500 });
+      throw error;
+    }
+  };
+}