@volter/world-core 3.0.155 → 3.0.157

package/src/live/ingest.ts

@@ -57,7 +57,6 @@ export function liveIngest<C>(options: LiveIngestOptions<C>): TwinStream {
     let priorInit: number | undefined;
     let started = false;
     let metadata: Record<string, unknown> | undefined;
-    let refusedCodec: string | undefined;
 
     const recording = (): LiveRecording => {
       const row = store.rows(LIVE).find((r) => r.id === stream)!;
@@ -135,7 +134,12 @@ export function liveIngest<C>(options: LiveIngestOptions<C>): TwinStream {
             app: ask!.app, key: ask!.key, state: 'publishing', startedAt: typeof prior?.startedAt === 'string' ? prior.startedAt : now, endedAt: null,
             publishes: Number(prior?.publishes ?? 0) + 1, window: ruling.window ?? 6, segmentSeconds: ruling.segmentSeconds ?? 2, ...(ruling.retain !== undefined ? { retain: ruling.retain } : {}),
           }, 'live.publish'));
+          // Every admitted publish has its own encoder and hook state. Continuation comes from the recording above,
+          // including on a connection reused after FCUnpublish, never from the prior publish's in-memory state.
+          initIndex = -1;
           priorInit = last?.init;
+          started = false;
+          metadata = undefined;
           segmenter = new Segmenter({ targetMs: Math.max(0.5, ruling.segmentSeconds ?? 2) * 1000, offsetMs, firstSequence: last ? last.seq + 1 : 0 });
           stream = named;
           admitted = ruling;
@@ -154,7 +158,7 @@ export function liveIngest<C>(options: LiveIngestOptions<C>): TwinStream {
       async video(timestamp, payload) {
         if (!segmenter) return;
         const tag = readVideoTag(payload);
-        if (tag.kind === 'unsupported') { if (refusedCodec !== tag.codec) log(`${stream}: ${tag.codec} video is not recorded (H.264 is)`); refusedCodec = tag.codec; return; }
+        if (tag.kind === 'unsupported') throw new RtmpRefusal('NetStream.Failed', `${tag.codec} video is not supported; publish H.264.`);
         const s = segmenter;
         if (tag.kind === 'config') await keepAll(s.videoConfig(tag.config));
         else if (tag.kind === 'frame') await keepAll(overrun(() => s.videoFrame(timestamp, tag.key, tag.cts, tag.data)));
@@ -162,7 +166,7 @@ export function liveIngest<C>(options: LiveIngestOptions<C>): TwinStream {
       async audio(timestamp, payload) {
         if (!segmenter) return;
         const tag = readAudioTag(payload);
-        if (tag.kind === 'unsupported') { if (refusedCodec !== tag.codec) log(`${stream}: ${tag.codec} audio is not recorded (AAC is)`); refusedCodec = tag.codec; return; }
+        if (tag.kind === 'unsupported') throw new RtmpRefusal('NetStream.Failed', `${tag.codec} audio is not supported; publish AAC.`);
         const s = segmenter;
         if (tag.kind === 'config') await keepAll(s.audioConfig(tag.config));
         else await keepAll(overrun(() => s.audioFrame(timestamp, tag.data)));

package/src/live/rtmp.ts

@@ -124,6 +124,9 @@ export function rtmpSession(sink: TwinStreamSink, publisher: RtmpPublisher, log:
     chunks.clear();
     current = undefined;
     held = 0;
+    // A refused/ended transport owns the publish's cleanup too. An admission already awaiting the dialect settles
+    // first; messages queued behind the refusal cannot admit a new publish on the closed connection.
+    chain = chain.then(() => stop()).catch((error) => log(`the publish's end failed: ${String((error as Error)?.message ?? error)}`));
     try { sink.end(); } catch { /* the peer is gone */ }
   };
   /** A connection past a ceiling: said once, and closed. */
@@ -175,6 +178,7 @@ export function rtmpSession(sink: TwinStreamSink, publisher: RtmpPublisher, log:
         try { refusal = await publisher.publish({ app, name: named, ...(type !== undefined ? { type } : {}), ...(tcUrl !== undefined ? { tcUrl } : {}), ...(flashVer !== undefined ? { flashVer } : {}) }); }
         catch (error) { log(`publish failed: ${String((error as Error)?.message ?? error)}`); refusal = { code: 'NetStream.Publish.Denied', description: 'The server could not take the stream.' }; }
         if (refusal) { status(stream, 'error', refusal.code, refusal.description, named); close(); return; }
+        ended = false;
         publishing = true;
         publishStream = stream;
         // user control StreamBegin (event 0) for the publish's stream, then its start
@@ -257,7 +261,7 @@ export function rtmpSession(sink: TwinStreamSink, publisher: RtmpPublisher, log:
     const message: Message = { type: st.type, streamId: st.streamId, timestamp: st.timestamp, payload };
     queued += payload.length;
     if (queued > MAX_QUEUED) { overrun(`more than ${MAX_QUEUED} bytes of messages wait to be recorded`); return; }
-    chain = chain.then(() => (phase === 'closed' && message.type !== 20 ? undefined : onMessage(message))).catch((error) => {
+    chain = chain.then(() => (phase === 'closed' ? undefined : onMessage(message))).catch((error) => {
       log(`a message failed: ${String((error as Error)?.message ?? error)}`);
       close();
     }).finally(() => { queued -= payload.length; });
@@ -366,10 +370,8 @@ export function rtmpSession(sink: TwinStreamSink, publisher: RtmpPublisher, log:
     // message's bytes are not in it: only more bytes finish it, and what it may hold is bounded (MAX_HELD)
     backlog: () => queued + pending.length,
     close() {
-      clearTimeout(deadline);
-      // the connection ended: a publish still open ends with it, after every message already read
-      chain = chain.then(() => stop()).catch((error) => log(`the publish's end failed: ${String((error as Error)?.message ?? error)}`));
-      phase = 'closed';
+      // Peer close and server refusal share one end, after any admission or write already under way settles.
+      close();
     },
   };
 }

package/src/live/segmenter.ts

@@ -64,14 +64,20 @@ export class Segmenter {
     this.avc = config;
     this.freshInit = true;
     this.keyed = false;
+    this.unkeyedSince = undefined;
     return out;
   }
 
   audioConfig(config: AacConfig): Cut[] {
     if (this.aac && same(this.aac.asc, config.asc)) return [];
-    const out = this.aac ? this.flush() : [];
+    const out = this.flush();
     this.aac = config;
     this.freshInit = true;
+    // A configuration boundary has no running video segment. Its first frame must be a new keyframe, and the
+    // audio sample clock belongs to the new configuration (which may have a different sample rate).
+    this.keyed = false;
+    this.unkeyedSince = undefined;
+    this.audioNext = undefined;
     return out;
   }
 

package/src/log.ts

@@ -30,7 +30,7 @@ import { resolveReferences } from './references.ts';
 import { hashFieldValue } from './hash.ts';
 import type { SubjectFields } from './hash.ts';
 import { worldPaths } from './storage.ts';
-import { getActiveWorldStore } from './world-store.ts';
+import { getActiveWorldStore, TREE_FILES } from './world-store.ts';
 import type { WorldServiceEvent } from './types.ts';
 import type { TwinResource } from './serve.ts';
 
@@ -97,8 +97,8 @@ const TREE_PROJECTION_VERSION = 2;
 export const DELTA_SUFFIX = '.delta';
 
 export function parentLogPath(service: string, root?: string): string { return worldPaths(service, root).events; }
-export function branchLogPath(service: string, root?: string): string { return join(dirname(worldPaths(service, root).events), 'actions.jsonl'); }
-export function branchMetaPath(service: string, root?: string): string { return join(dirname(worldPaths(service, root).events), 'branch.json'); }
+export function branchLogPath(service: string, root?: string): string { return join(dirname(worldPaths(service, root).events), TREE_FILES.branch); }
+export function branchMetaPath(service: string, root?: string): string { return join(dirname(worldPaths(service, root).events), TREE_FILES.pointer); }
 /** The fetched cache of a URL parent's whole log — what `fetch` extends and a read folds up to the position. */
 export function originLogPath(service: string, root?: string): string { return join(dirname(worldPaths(service, root).events), 'origin.jsonl'); }
 /** A parent is at a URL when it is not a path on this machine. */
@@ -173,8 +173,9 @@ function readRows<T>(path: string): T[] {
   return rows.slice();
 }
 
-export function readBranchMeta(service: string, root?: string): BranchMeta | null {
-  const raw = getActiveWorldStore().read(branchMetaPath(service, root));
+export function readBranchMeta(service: string, root?: string, read?: string | null): BranchMeta | null {
+  // `read`: branch.json's text where the caller has just read it (a tree's stamp reads it once for both uses).
+  const raw = read !== undefined ? read : getActiveWorldStore().read(branchMetaPath(service, root));
   if (raw === null) return null;
   const meta = parseExactJson(raw) as BranchMeta & { parent?: { root?: string; parentCount?: number; branchCount?: number } };
   // a pointer written before positions were one number: the parent's whole log is parent then branch
@@ -228,8 +229,8 @@ export function writeBranchMeta(service: string, meta: BranchMeta, root?: string
       getActiveWorldStore().mkdir(dirname(path));
       getActiveWorldStore().writeAtomic(path, `${JSON.stringify(meta, null, 2)}\n`);
       if (meta.parent?.directory && !isUrlParent(meta.parent.at)) commitParentPin(meta.parent.directory, path);
-    });
-  });
+    }, { operation: 'pointer publication' });
+  }, { operation: 'pointer publication' });
 }
 
 /** A v1 observed row as an entry: a delta event folds its `changed.*.after`; anything else folds
@@ -304,7 +305,7 @@ export function appendOriginEntry(entry: Entry, root?: string): { appended: bool
     if (readRows<{ id?: string }>(path).some((r) => r.id === entry.id)) return { appended: false };
     store.append(path, `${JSON.stringify(entry)}\n`);
     return { appended: true };
-  }));
+  }, { operation: 'origin append' }), { operation: 'origin append' });
 }
 
 /** Where the parent stands now: the length of its whole log (live at a path, the cache for a URL). */
@@ -338,7 +339,7 @@ export function aliasesFrom(parent: Entry[]): Map<string, string> {
 }
 
 const META = new Set(['id', 'type', 'updatedAt']);
-type Subject = { type: string; id: string; updatedAt: string; fields: SubjectFields };
+export type Subject = { type: string; id: string; updatedAt: string; fields: SubjectFields };
 export type Tree = Map<string, Subject>;
 
 /** Last write per field. `deleted: true` is the tombstone a delete carries; it holds until the subject
@@ -351,6 +352,24 @@ function overlay(tree: Tree, type: string, id: string, fields: SubjectFields, at
   tree.set(key, { ...existing, updatedAt: at, fields: merged });
 }
 
+/** One subject read by the same guarded key as a write's answer; restore the vendor's own metadata fields. */
+export function heldSubject(service: string, type: string, id: string, root?: string): Subject | undefined {
+  const row = readSubject(service, type, id, root);
+  return row ? { type: row.type, id: row.id, updatedAt: row.updatedAt, fields: ownFields(row) } : undefined;
+}
+
+/**
+ * One local write folded onto its subject as the tree folds its entry (`overlay`): the subject as it was (undefined
+ * for one new to the tree) is copied, never changed. A command's writes staged in `ctx.batch` are read back by
+ * folding them this way, so a read inside the batch sees what the tree will hold once they land (derived-core.ts).
+ */
+export function foldLocalWrite(previous: Subject | undefined, type: string, id: string, fields: SubjectFields, at: string): Subject {
+  const key = `${type}:${id}`;
+  const tree: Tree = previous ? new Map([[key, { ...previous, fields: { ...previous.fields } }]]) : new Map();
+  overlay(tree, type, id, fields, at);
+  return tree.get(key)!;
+}
+
 /** Fold entries onto a tree, in order: `set` overlays its fields and applies its projection; a
  *  reverted entry folds nothing; a `confirm` row (v1) folds nothing. `skip` names entries the
  *  parent already holds. */
@@ -447,6 +466,22 @@ export function foldHistory(entries: Entry[], layout: HistoryLayout, service?: s
   foldAliases(tree, aliasesFrom(parent), service);
   return tree;
 }
+/**
+ * One subject of the current tree as a resource, by its type and id: the resource `projectResources(...).find` gives
+ * for the same type and id, read by the subject's key without cloning or projecting the rest of the tree. Every subject is
+ * held under `${type}:${id}` (overlay is the only setter, and an alias re-keys through it), so the key is the
+ * subject. A write's answer read back the whole tree this way (serve.ts, applyTwinWrite's `resource`), once per
+ * written subject: a derived pack writing each document, index and collection of a database's startup paid a
+ * projection of every subject the World holds for each (S2 R17).
+ */
+export function readSubject(service: string, type: string, id: string, root?: string): TwinResource | undefined {
+  const key = `${type}:${id}`;
+  const held = currentTree(service, root).tree.get(key);
+  // a type or id holding ':' can share a key with another (type, id): only the subject itself is it
+  if (!held || held.type !== type || held.id !== id) return undefined;
+  return treeResources(new Map([[key, { ...held, fields: { ...held.fields } }]]))[0];
+}
+
 export function readTree(service: string, root?: string, opts: { until?: string; at?: number; view?: string } = {}): TwinResource[] {
   return treeResources(readTreeMap(service, root, opts));
 }
@@ -460,7 +495,7 @@ export function readParentTreeMap(service: string, root?: string): Tree {
     return foldHistory([...(inherited ? historyEntries(inherited) : []), ...own], {
       ...(inherited ? { base: inherited.layout } : {}), parent: own.length, branch: 0,
     }, service);
-  });
+  }, { operation: 'tree fold' });
 }
 
 // A READ'S TREE, MEMOIZED per store and per process or isolate. What a read folds is named by cheap
@@ -483,11 +518,44 @@ const TREE_STEPS_KEPT = 64;
 function statKey(path: string): string { const s = getActiveWorldStore().stat(path); return s ? `${s.size}:${s.mtimeMs}` : '-'; }
 /** What a service's PARENT side at `root` is folded from (its parent log, branch.json and inherited history), as one
  *  string: while it stands, its aliases and landed ids are the same, whatever the branch's own log does. */
-export function parentStamp(service: string, root?: string): string { return parentKeyOf(service, root); }
-function parentKeyOf(service: string, root?: string): string { return `${TREE_PROJECTION_VERSION}|${statKey(parentLogPath(service, root))}|${getActiveWorldStore().read(branchMetaPath(service, root)) ?? ''}|${inheritedHistoryKey(service, root)}`; }
+export function parentStamp(service: string, root?: string): string { return treeFacts(service, root).parentKey; }
+function parentKeyOf(service: string, root?: string): string { return parentFacts(service, root).key; }
+/** The parent side's key, and whether it names a file outside the tree's own directory (an inherited view). */
+function parentFacts(service: string, root?: string): { key: string; inherits: boolean } {
+  // branch.json is small and every stamp needs it: kept while its own facts stand (world-store.ts readKept), so an
+  // unchanged pointer costs one check. Its text is still in the key, so a changed pointer still moves the stamp.
+  const store = getActiveWorldStore(), pointer = branchMetaPath(service, root);
+  const meta = store.readKept ? store.readKept(pointer) : store.read(pointer);
+  const inherited = inheritedHistoryKey(service, root, meta);
+  return { key: `${TREE_PROJECTION_VERSION}|${statKey(parentLogPath(service, root))}|${meta ?? ''}|${inherited}`, inherits: inherited !== '' };
+}
+// ONE QUESTION PER STAMP, WHERE THE STORE KEEPS A GENERATION (world-store.ts FsWorldStore.generation, which states
+// what makes it sound and where that stops). A stamp was three questions of the file system, on every operation of
+// every twin: the parent log, the pointer and the branch log, the first two of files a World with no parent does not
+// have. The facts are kept under the generation read BEFORE them, and served while the generation still reads the
+// same. Never kept: where the directory has no generation yet (nothing has been written there by a store that keeps
+// one), and where the parent side names files of other directories (an inherited view: its ancestors' writes move no
+// generation here). Both are asked in full, as before.
+type TreeFacts = { parentKey: string; branchKey: string };
+const keptFacts = new WeakMap<object, Map<string, TreeFacts & { generation: string }>>();
+function treeFacts(service: string, root?: string): TreeFacts {
+  const store = getActiveWorldStore();
+  const branchLog = branchLogPath(service, root);
+  if (!store.generation) return { parentKey: parentKeyOf(service, root), branchKey: statKey(branchLog) };
+  const directory = dirname(branchLog);
+  const generation = store.generation(directory);
+  let kept = keptFacts.get(store);
+  if (!kept) { kept = new Map(); keptFacts.set(store, kept); }
+  const held = kept.get(directory);
+  if (generation !== null && held?.generation === generation) return held;
+  const parent = parentFacts(service, root);
+  const facts = { parentKey: parent.key, branchKey: statKey(branchLog) };
+  if (generation !== null && !parent.inherits) kept.set(directory, { ...facts, generation }); else kept.delete(directory);
+  return facts;
+}
 /** What a service's tree (and every subject's history) at `root` is folded from, as one string: while it
  *  stands, nothing was written. A pack that projects the tree into its own state memoizes on it. */
-export function treeStamp(service: string, root?: string): string { return `${parentKeyOf(service, root)}#${statKey(branchLogPath(service, root))}`; }
+export function treeStamp(service: string, root?: string): string { const facts = treeFacts(service, root); return `${facts.parentKey}#${facts.branchKey}`; }
 const cloneTree = (tree: Tree): Tree => new Map([...tree].map(([k, s]) => [k, { ...s, fields: { ...s.fields } }]));
 const memoStamp = (m: TreeMemo): string => `${m.parentKey}#${m.branchKey}`;
 
@@ -529,7 +597,7 @@ function currentTree(service: string, root?: string): { tree: Tree; memo?: TreeM
   // A hit needs no lock: a memo is only ever stored from a fold made under the history lock, and while the
   // facts still match that fold, nothing was written since. A writer mid-batch has moved them.
   const unlocked = memos.get(slot);
-  if (unlocked && unlocked.parentKey === parentKeyOf(service, root) && unlocked.branchKey === statKey(branchLogPath(service, root))) return { tree: unlocked.tree, memo: unlocked };
+  if (unlocked) { const facts = treeFacts(service, root); if (unlocked.parentKey === facts.parentKey && unlocked.branchKey === facts.branchKey) return { tree: unlocked.tree, memo: unlocked }; }
   return withHistoryLock(worldPaths(service, root).dir, () => {
     const parentKey = parentKeyOf(service, root); const branchKey = statKey(branchLogPath(service, root));
     const held = memos.get(slot);
@@ -539,19 +607,7 @@ function currentTree(service: string, root?: string): { tree: Tree; memo?: TreeM
     if (held && held.parentKey === parentKey && branch.length >= held.branchCount
       && (held.branchCount === 0 ? held.lastBranchId === null : branch[held.branchCount - 1]?.id === held.lastBranchId)
       && !branch.slice(held.branchCount).some((e) => e.op === 'revert')) {
-      const fresh = branch.slice(held.branchCount);
-      const keys = touchedKeys(fresh, held.aliases);
-      const from = memoStamp(held);
-      let appended: string[];
-      try {
-        appended = insertionsDuring(held.tree, () => {
-          foldEntries(held.tree, fresh, held.landed);
-          foldAliases(held.tree, held.aliases, service, keys);
-        });
-      } catch (error) { memos.delete(slot); throw error; } // a half-folded memo is never read again
-      Object.assign(held, { branchKey, branchCount: branch.length, lastBranchId: last(branch) });
-      held.steps.push({ from, to: memoStamp(held), keys, appended });
-      if (held.steps.length > TREE_STEPS_KEPT) held.steps.splice(0, held.steps.length - TREE_STEPS_KEPT);
+      extendMemo(memos, slot, held, branch.slice(held.branchCount), branchKey, service);
       return { tree: held.tree, memo: held };
     }
     const tree = readTreeMapFull(service, root);
@@ -563,7 +619,66 @@ function currentTree(service: string, root?: string): { tree: Tree; memo?: TreeM
       return { tree, memo };
     }
     return { tree };
-  });
+  }, { operation: 'tree fold' });
+}
+
+/** The memo extended in place by `fresh`, the branch log's entries after its own, which leave the log at `branchKey`,
+ *  with the step that records the subjects they touched. */
+function extendMemo(memos: Map<string, TreeMemo>, slot: string, held: TreeMemo, fresh: Entry[], branchKey: string, service: string): void {
+  const keys = touchedKeys(fresh, held.aliases);
+  const from = memoStamp(held);
+  let appended: string[];
+  try {
+    appended = insertionsDuring(held.tree, () => {
+      foldEntries(held.tree, fresh, held.landed);
+      foldAliases(held.tree, held.aliases, service, keys);
+    });
+  } catch (error) { memos.delete(slot); throw error; } // a half-folded memo is never read again
+  Object.assign(held, { branchKey, branchCount: held.branchCount + fresh.length, lastBranchId: fresh.length ? fresh[fresh.length - 1]!.id : held.lastBranchId });
+  held.steps.push({ from, to: memoStamp(held), keys, appended });
+  if (held.steps.length > TREE_STEPS_KEPT) held.steps.splice(0, held.steps.length - TREE_STEPS_KEPT);
+}
+
+// AN OWN APPEND EXTENDS THE READS' MEMO (S2 R17c). A write appended its entries and the next read found the facts
+// moved, so it took the history lock, read the facts again and the log's new bytes, and extended the memo with the
+// entries this process had just written: in a tab, where each of those is a call into the kernel, about twenty calls
+// per command that writes, taken again by the command after it. The writer, still holding the history lock, extends
+// the memo with its own entries and keeps the tree's facts under the generation its own write left, so the next read
+// asks one question. It does so only where the store can say its write was the one write since the generation it
+// read just before (`generationAfterOwnWrite`), the facts were kept under that generation and the memo stood at them,
+// the parent side's facts read after the append are still the kept ones, and the log grew by exactly its bytes;
+// otherwise it extends nothing, and the next read checks as before.
+/** Append `data` (whole JSONL lines of a service's branch log, `append` writing them) and, when the reads' memo held
+ *  the tree as it stood, extend it by them. Called holding the directory's history lock. Answers the log's facts
+ *  after the append (`size:mtimeMs`) when it read them, for a caller keyed on the same. */
+export function appendToBranchLog(service: string, root: string | undefined, data: string, append: () => void): string | undefined {
+  const store = getActiveWorldStore();
+  const memos = treeMemos.get(store);
+  const slot = `${service}\u0000${root ?? ''}`;
+  const held = memos?.get(slot);
+  const branchLog = branchLogPath(service, root);
+  const directory = dirname(branchLog);
+  const kept = keptFacts.get(store)?.get(directory);
+  const standing = held !== undefined && kept !== undefined && kept.parentKey === held.parentKey && kept.branchKey === held.branchKey;
+  const before = standing && store.generation && store.generationAfterOwnWrite ? store.generation(directory) : null;
+  append();
+  if (!memos || !held || !kept || before === null || kept.generation !== before) return undefined;
+  const after = store.generationAfterOwnWrite!(directory, before);
+  if (after === null) return undefined;
+  // read after the generation, as treeFacts reads its facts. The parent side is read again too: a writer the generation
+  // does not see (an older version's, or one that died before its second byte) may have moved it under the kept
+  // generation, and carried forward its old key would outlive every append this process makes (S2 R17c review).
+  const branchKey = statKey(branchLog);
+  if (parentKeyOf(service, root) !== kept.parentKey) return branchKey;
+  const grown = (key: string): number => (key === '-' ? 0 : Number(key.slice(0, key.indexOf(':'))));
+  const fresh: Entry[] = [];
+  // line numbers in a refusal count from this append's first line
+  parseLines(`${branchLog} (appended)`, data.split('\n'), 0, fresh);
+  if (grown(branchKey) !== grown(held.branchKey) + Buffer.byteLength(data) || fresh.some((e) => e.op === 'revert')) return branchKey;
+  // the write has landed: a fold that fails here drops the memo (extendMemo) and the next read folds in full, never failing the write
+  try { extendMemo(memos, slot, held, fresh, branchKey, service); } catch { return branchKey; }
+  keptFacts.get(store)!.set(directory, { parentKey: kept.parentKey, branchKey, generation: after });
+  return branchKey;
 }
 
 /** What changed in a service's tree since `since` (a `treeStamp` an earlier read was made at): the subjects
@@ -649,7 +764,7 @@ function readTreeMapFull(service: string, root?: string, opts: { until?: string;
     getActiveWorldStore().writeAtomic(checkpointPath(service, root), JSON.stringify({ parentDigest, branchDigest, branchCount: branch.length, subjects: [...tree.values()], ...(now === facts ? { facts } : {}) }));
   }
   return tree;
-  });
+  }, { operation: 'tree fold' });
 }
 export function cutCheckpoint(service: string, root?: string): void {
   return withHistoryLock(worldPaths(service, root).dir, () => {
@@ -657,7 +772,7 @@ export function cutCheckpoint(service: string, root?: string): void {
   const subjects = [...readTreeMap(service, root).values()];
   const inherited = inheritedHistory(service, root); const own = ownParentEntries(service, root);
   getActiveWorldStore().writeAtomic(checkpointPath(service, root), JSON.stringify({ parentDigest: hashFieldValue({ projectionVersion: TREE_PROJECTION_VERSION, inherited, own }), branchDigest: hashFieldValue(branchEntries(service, root)), branchCount: branchEntries(service, root).length, subjects }));
-  });
+  }, { operation: 'checkpoint' });
 }
 
 /** The branch's entries the parent does not hold: `set` rows, not reverted, not landed. */
@@ -744,7 +859,7 @@ export function appendParentEntry(entry: Entry, root?: string): { appended: bool
     index.ids.add(entry.id);
     index.key = statKey(path);
     return { appended: true };
-  }));
+  }, { operation: 'parent append' }), { operation: 'parent append' });
 }
 
 /** The whole log of a twin as a served world hands it out: the parent view, then the branch's own
@@ -815,7 +930,7 @@ export function rebaseBranch(service: string, root?: string, opts: { origin?: bo
     dropCheckpoint(service, root);
   }
   return { moved, from, to, conflicts };
-  });
+  }, { operation: 'branch-pointer adjustment' });
 }
 
 /**

package/src/machines.ts

@@ -6,6 +6,7 @@
 // is reached only when a compute pool is asked to act. The light pool delegates to the host's Substrate adapter.
 import { refuseReadOnlyWrite } from './request-scope.ts';
 import { nodeBuiltin } from './serve-http.ts';
+import { refuseRequiredMachineTransport } from '../required-credential-transport.cjs';
 
 export type MachineSpec = { name: string; image: string; env?: Record<string, string>; ports?: number[]; command?: string[]; checks?: Array<{ port: number; type: 'http' | 'tcp'; path?: string }>; resetOnStop?: boolean; mounts?: Array<{ name: string; path: string }>; signal?: AbortSignal; startTimeoutMs?: number };
 export type GuestImage = { context: string; dockerfile?: string; runtime?: 'node' | 'bun' | 'python' | 'deno'; command?: string[]; cwd?: string; env?: Record<string, string>; prepared?: boolean };
@@ -94,6 +95,7 @@ function dockerPool(world: string): MachinePool {
   });
   return {
     kind: 'docker',
+    async admitRun() { refuseRequiredMachineTransport(process.env, 'Docker machine application transport'); },
     async status(name) {
       const state = JSON.parse(await docker(['inspect', '--format', '{{json .State}}', containerName(world, name)]));
       return state.Running ? { state: 'started' } : { state: 'exited', exitCode: state.ExitCode, ...(state.Error ? { reason: state.Error } : {}) };
@@ -101,6 +103,7 @@ function dockerPool(world: string): MachinePool {
     async ports() { throw new Error('port discovery requires the light guest backing'); },
     async files() { throw new Error('file access requires the light guest backing'); },
     async run(spec) {
+      refuseRequiredMachineTransport(process.env, 'Docker machine application transport');
       const name = containerName(world, spec.name);
       await docker(['rm', '-f', name]).catch(() => undefined);
       const env = Object.entries(spec.env ?? {}).flatMap(([k, v]) => ['-e', `${k}=${v}`]);
@@ -114,6 +117,7 @@ function dockerPool(world: string): MachinePool {
       return { ports: published };
     },
     async exec(name, spec) {
+      refuseRequiredMachineTransport(process.env, 'Docker machine exec transport');
       const { spawn } = nodeBuiltin<typeof import('node:child_process')>('node:child_process');
       const env = Object.entries(spec.env ?? {}).flatMap(([k, v]) => ['-e', `${k}=${v}`]);
       // the shell names its own pid first, then becomes the process: its pid is the process's
@@ -176,7 +180,7 @@ function dockerPool(world: string): MachinePool {
       return fetch(`http://127.0.0.1:${host}${source.pathname}${source.search}`, { method: request.method, headers, body, redirect: 'manual', signal: request.signal });
     },
     async pause(name) { await docker(['pause', containerName(world, name)]); },
-    async resume(name) { await docker(['unpause', containerName(world, name)]); },
+    async resume(name) { refuseRequiredMachineTransport(process.env, 'Docker machine resume transport'); await docker(['unpause', containerName(world, name)]); },
     async stop(name) { await docker(['stop', containerName(world, name)]).catch(() => undefined); },
     async remove(name) { await docker(['rm', '-f', containerName(world, name)]).catch(() => undefined); },
   };

package/src/managed-go-programs.ts

@@ -0,0 +1,146 @@
+/** Tagged managed Go operation metadata. This structural reader grants no
+ * source/image correspondence, filesystem custody, catalog admission or exec. */
+import { posix } from 'node:path';
+
+export interface NativeGoKitReference {
+  package: { name: string; version: string };
+  target: 'wasm32-wali-go-single-thread';
+  releaseSha256: string;
+  producerSha256: string;
+  sourceSha256: string;
+  selection: { path: string; sha256: string };
+  recipe: { path: string; sha256: string };
+  installedRoot: string;
+}
+export interface NativeGoOperation {
+  sourceService: string;
+  role: 'server' | 'prerequisite' | 'health';
+  kit: string;
+  program: { name: string; version: string; manifestId: string; manifestSha256: string; path: string };
+  /** Resolved arguments require separate comparison with the full source. */
+  args: string[];
+  /** Names of existing World values, never caller secrets in this record. */
+  environmentBindings: Record<string, string>;
+  requires: { service: string; condition: 'service_started' | 'service_healthy' | 'service_completed_successfully' }[];
+}
+export interface NativeGoReference {
+  version: 2;
+  implementation: string;
+  release: string;
+  directory: string;
+  snapshotSha256: string;
+  declarationSha256: string;
+  image: string;
+  kits: Record<string, NativeGoKitReference>;
+  server: NativeGoOperation;
+  prerequisites: NativeGoOperation[];
+  health: NativeGoOperation;
+}
+
+const fail = (field: string): never => { throw new Error('Native Go operation metadata is invalid: ' + field); };
+function object(value: unknown, fields: readonly string[], label: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return fail(label);
+  const row = value as Record<string, unknown>;
+  if (Object.keys(row).length !== fields.length || fields.some(key => !Object.hasOwn(row, key))) return fail(label);
+  return row;
+}
+function text(value: unknown, label: string): string {
+  if (typeof value !== 'string' || !value || value.includes('\0')) return fail(label);
+  return value;
+}
+function digest(value: unknown, label: string): string {
+  const out = text(value, label);
+  if (!/^[a-f0-9]{64}$/u.test(out)) return fail(label);
+  return out;
+}
+function relativePath(value: unknown, label: string): string {
+  const out = text(value, label);
+  if (out.startsWith('/') || out.includes('\\') || posix.normalize(out) !== out
+    || out.split('/').some(part => !part || part === '.' || part === '..')) return fail(label);
+  return out;
+}
+function installedPath(value: unknown, label: string): string {
+  const out = text(value, label);
+  if (!out.startsWith('/opt/programs/') || out.includes('\\') || posix.normalize(out) !== out
+    || out.split('/').slice(1).some(part => !part || part === '.' || part === '..')) return fail(label);
+  return out;
+}
+function pin(value: unknown, label: string): { path: string; sha256: string } {
+  const row = object(value, ['path', 'sha256'], label);
+  return { path: relativePath(row.path, label + '.path'), sha256: digest(row.sha256, label + '.sha256') };
+}
+function kit(value: unknown, label: string): NativeGoKitReference {
+  const row = object(value, ['package', 'target', 'releaseSha256', 'producerSha256', 'sourceSha256', 'selection', 'recipe', 'installedRoot'], label);
+  const pack = object(row.package, ['name', 'version'], label + '.package');
+  if (row.target !== 'wasm32-wali-go-single-thread') return fail(label + '.target');
+  return { package: { name: text(pack.name, label + '.package.name'), version: text(pack.version, label + '.package.version') },
+    target: row.target, releaseSha256: digest(row.releaseSha256, label + '.releaseSha256'),
+    producerSha256: digest(row.producerSha256, label + '.producerSha256'), sourceSha256: digest(row.sourceSha256, label + '.sourceSha256'),
+    selection: pin(row.selection, label + '.selection'), recipe: pin(row.recipe, label + '.recipe'),
+    installedRoot: installedPath(row.installedRoot, label + '.installedRoot') };
+}
+function operation(value: unknown, role: NativeGoOperation['role'], kits: Record<string, NativeGoKitReference>, label: string): NativeGoOperation {
+  const row = object(value, ['sourceService', 'role', 'kit', 'program', 'args', 'environmentBindings', 'requires'], label);
+  const selected = text(row.kit, label + '.kit');
+  if (row.role !== role || !Object.hasOwn(kits, selected)) return fail(label + '.role/kit');
+  const provider = kits[selected]!;
+  const command = object(row.program, ['name', 'version', 'manifestId', 'manifestSha256', 'path'], label + '.program');
+  const path = installedPath(command.path, label + '.program.path'), version = text(command.version, label + '.program.version');
+  if (version !== provider.package.version || !path.startsWith(provider.installedRoot + '/')) return fail(label + '.program placement/version');
+  if (!Array.isArray(row.args)) return fail(label + '.args');
+  const args: string[] = [];
+  for (const arg of row.args) {
+    if (typeof arg !== 'string' || arg.includes('\0')) return fail(label + '.args.' + args.length);
+    args.push(arg);
+  }
+  if (!row.environmentBindings || typeof row.environmentBindings !== 'object' || Array.isArray(row.environmentBindings)) return fail(label + '.environmentBindings');
+  const bindings: Record<string, string> = Object.create(null);
+  for (const [name, value] of Object.entries(row.environmentBindings)) {
+    const source = text(value, label + '.environmentBindings.' + name);
+    if (![name, source].every(item => /^[A-Za-z_][A-Za-z0-9_]*$/u.test(item))) return fail(label + '.environmentBindings name');
+    bindings[name] = source;
+  }
+  if (!Array.isArray(row.requires)) return fail(label + '.requires');
+  const dependencies: NativeGoOperation['requires'] = [];
+  for (const value of row.requires) {
+    const edge = object(value, ['service', 'condition'], label + '.requires');
+    if (edge.condition !== 'service_started' && edge.condition !== 'service_healthy' && edge.condition !== 'service_completed_successfully')
+      return fail(label + '.requires.condition');
+    const service = text(edge.service, label + '.requires.service');
+    if (dependencies.some(prior => prior.service === service)) return fail(label + '.requires duplicate service');
+    dependencies.push({ service, condition: edge.condition });
+  }
+  return { sourceService: text(row.sourceService, label + '.sourceService'), role, kit: selected,
+    program: { name: text(command.name, label + '.program.name'), version, manifestId: text(command.manifestId, label + '.program.manifestId'),
+      manifestSha256: digest(command.manifestSha256, label + '.program.manifestSha256'), path },
+    args, environmentBindings: bindings, requires: dependencies };
+}
+
+/** All fields are declared data. The later owned consumer must authenticate
+ * the complete source, kit, original image and admitted installed manifests. */
+export function nativeGoReference(value: unknown): NativeGoReference {
+  const row = object(value, ['version', 'implementation', 'release', 'directory', 'snapshotSha256', 'declarationSha256', 'image', 'kits', 'server', 'prerequisites', 'health'], 'reference');
+  if (row.version !== 2) return fail('version');
+  const image = text(row.image, 'image');
+  if (!/^[^\s@]+@sha256:[a-f0-9]{64}$/u.test(image)) return fail('image');
+  if (!row.kits || typeof row.kits !== 'object' || Array.isArray(row.kits) || !Object.keys(row.kits).length) return fail('kits');
+  const kits: Record<string, NativeGoKitReference> = Object.create(null);
+  for (const [name, value] of Object.entries(row.kits)) kits[text(name, 'kit name')] = kit(value, 'kits.' + name);
+  const server = operation(row.server, 'server', kits, 'server'), health = operation(row.health, 'health', kits, 'health');
+  const implementation = text(row.implementation, 'implementation'), release = text(row.release, 'release');
+  if (kits[server.kit]!.package.name !== implementation || kits[server.kit]!.package.version !== release
+    || health.sourceService !== server.sourceService) return fail('server/health implementation');
+  if (!Array.isArray(row.prerequisites)) return fail('prerequisites');
+  const prerequisites: NativeGoOperation[] = [];
+  for (const value of row.prerequisites)
+    prerequisites.push(operation(value, 'prerequisite', kits, 'prerequisites.' + prerequisites.length));
+  if (new Set(prerequisites.map(item => item.sourceService)).size !== prerequisites.length
+    || prerequisites.some(item => item.sourceService === server.sourceService)) return fail('prerequisite service');
+  const usedKits = new Set([server.kit, health.kit, ...prerequisites.map(item => item.kit)]);
+  if (Object.keys(kits).some(name => !usedKits.has(name))) return fail('unconsumed kit');
+  for (const item of prerequisites) if (!server.requires.some(edge => edge.service === item.sourceService && edge.condition === 'service_completed_successfully'))
+    return fail('server prerequisite completion edge');
+  return { version: 2, implementation, release, directory: relativePath(row.directory, 'directory'),
+    snapshotSha256: digest(row.snapshotSha256, 'snapshotSha256'), declarationSha256: digest(row.declarationSha256, 'declarationSha256'),
+    image, kits, server, prerequisites, health };
+}