@volter/world-core 3.0.155 → 3.0.156

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/managed-original-inputs.ts

@@ -0,0 +1,163 @@
+/** Source-bound files at a managed replacement. No vendor interpretation or host paths. */
+import * as nodeCrypto from 'node:crypto';
+const digest = (algorithm: 'sha1' | 'sha256', value: string | Uint8Array): string => nodeCrypto.createHash(algorithm).update(value).digest('hex');
+export interface OriginalInputReference {
+  version: 1;
+  /** Relative to the needs file, or to the World configuration after init copies it. */
+  root: string;
+  manifest: "manifest.json";
+  sha256: string;
+  inventoryDigest: string;
+}
+
+export interface OriginalInputCapability {
+  version: 1;
+  manifestArg: "--original-inputs";
+  rootArg: "--original-root";
+  digestArg: "--original-inputs-sha256";
+  /** Image paths whose complete overlay contents the consumer requires. */
+  paths: string[];
+}
+
+export interface OriginalInputEntry {
+  target: string;
+  type: "file" | "directory" | "link";
+  mode: number;
+  bytes?: number;
+  sha256?: string;
+  object?: string;
+  link?: string;
+  source: { kind: "image" | "project"; path: string; layer?: string; blob?: string };
+}
+
+export interface ManagedOriginalInputs {
+  kind: "volter.managed-original-inputs";
+  version: 1;
+  service: string;
+  family: string;
+  /** Canonical selected service declaration; used to refuse a different stack on reuse. */
+  declaration: string;
+  source: { image: string; manifest: string; config: string; layers: string[]; commit: string; compose: string; composeSha256: string; composeBytes: number; composeObject: string };
+  /** Authenticated complete image metadata, before the declared mounts overlay it. */
+  imageInventory: Array<{ target: string; type: string; mode: number; bytes: number; layer: string; link?: string }>;
+  imageInventoryDigest: string;
+  projectInventory: Array<{ path: string; mode: number; blob: string }>;
+  projectInventoryDigest: string;
+  roots: string[];
+  /** Complete contents beneath roots, plus every original project bind mount. */
+  inventory: OriginalInputEntry[];
+  inventoryDigest: string;
+  start: {
+    imageConfig: Record<string, unknown>;
+    service: Record<string, unknown>;
+    imageEntrypoint: string[] | null;
+    imageCommand: string[] | null;
+    command?: string[];
+    entrypoint?: string[];
+    environment: Record<string, string>;
+    envFiles: Array<{ path: string; bytes: number; sha256: string; object: string }>;
+    unset: string[];
+    selfHosts: string[];
+    mounts: Array<{ kind: string; source?: string; target: string; readOnly: boolean }>;
+  };
+}
+
+export const originalTarget = (path: string): boolean => path === "/" || (path.startsWith("/") && !path.slice(1).split("/").some(part => !part || part === "." || part === ".." || /[\0\r\n\\]/u.test(part)));
+export const originalRelative = (path: string): boolean => !!path && !path.split("/").some(part => !part || part === "." || part === ".." || /[\0\r\n\\:]/u.test(part));
+
+const hex = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const oci = (value: unknown): value is string => typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value);
+const bytesOf = (value: unknown): value is number => Number.isSafeInteger(value) && Number(value) >= 0;
+const strings = (value: unknown): value is string[] => Array.isArray(value) && value.every(entry => typeof entry === 'string' && !/[\0\r\n]/.test(entry));
+const bound = 128 * 1024 * 1024;
+
+export function referenceOf(value: unknown): OriginalInputReference {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Original inputs need a versioned reference');
+  const ref = value as OriginalInputReference;
+  if (ref.version !== 1 || ref.manifest !== 'manifest.json' || typeof ref.root !== 'string' || !originalRelative(ref.root) || !hex(ref.sha256) || !hex(ref.inventoryDigest)
+    || Object.keys(ref).some(key => !['version', 'root', 'manifest', 'sha256', 'inventoryDigest'].includes(key))) throw new Error('Invalid original-input reference');
+  return { ...ref };
+}
+
+/** Hash and validate neutral carrier data. The caller supplies I/O; no pack/vendor behavior or import effects. */
+export function readSnapshot(bytes: Uint8Array, expected: string, readObject: (path: string, bytes: number) => Uint8Array): { manifest: ManagedOriginalInputs; objects: ReadonlyMap<string, Uint8Array> } {
+  if (!(bytes instanceof Uint8Array) || bytes.length > 64 * 1024 * 1024 || !hex(expected) || digest('sha256', bytes) !== expected) throw new Error('Original-input manifest identity differs');
+  const manifest = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)) as ManagedOriginalInputs;
+  const source = manifest.source, start = manifest.start;
+  if (manifest.kind !== 'volter.managed-original-inputs' || manifest.version !== 1 || typeof manifest.service !== 'string' || !manifest.service || typeof manifest.family !== 'string' || !/^[a-z][a-z0-9-]*$/.test(manifest.family)
+    || typeof manifest.declaration !== 'string' || !source || !/^[a-f0-9]{40}$/.test(source.commit) || !/^[A-Za-z0-9./:_-]+@sha256:[a-f0-9]{64}$/.test(source.image)
+    || !oci(source.manifest) || !oci(source.config) || !Array.isArray(source.layers) || !source.layers.every(oci) || !originalRelative(source.compose)
+    || !Array.isArray(manifest.imageInventory) || !Array.isArray(manifest.projectInventory) || !Array.isArray(manifest.inventory) || !strings(manifest.roots) || !manifest.roots.length || !manifest.roots.every(originalTarget) || new Set(manifest.roots).size !== manifest.roots.length
+    || !hex(manifest.imageInventoryDigest) || digest('sha256', JSON.stringify(manifest.imageInventory)) !== manifest.imageInventoryDigest
+    || !hex(manifest.inventoryDigest) || digest('sha256', JSON.stringify(manifest.inventory)) !== manifest.inventoryDigest
+    || !hex(manifest.projectInventoryDigest) || digest('sha256', JSON.stringify(manifest.projectInventory)) !== manifest.projectInventoryDigest
+    || !start || !start.imageConfig || typeof start.imageConfig !== 'object' || Array.isArray(start.imageConfig) || !start.service || typeof start.service !== 'object' || Array.isArray(start.service)
+    || !strings(start.selfHosts) || !start.selfHosts.length || !strings(start.unset) || !Array.isArray(start.envFiles) || !Array.isArray(start.mounts)
+    || !start.environment || typeof start.environment !== 'object' || Array.isArray(start.environment) || Object.entries(start.environment).some(([key, value]) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || typeof value !== 'string')
+    || [start.imageEntrypoint, start.imageCommand].some(value => value !== null && !strings(value)) || [start.command, start.entrypoint].some(value => value !== undefined && !strings(value))) throw new Error('Invalid original-input manifest');
+  if (JSON.stringify(JSON.parse(manifest.declaration)) !== JSON.stringify(start.service) || start.service.name !== manifest.service
+    || JSON.stringify(start.command) !== JSON.stringify(start.service.command) || JSON.stringify(start.entrypoint) !== JSON.stringify(start.service.entrypoint)
+    || JSON.stringify(start.imageEntrypoint) !== JSON.stringify(start.imageConfig.Entrypoint ?? null) || JSON.stringify(start.imageCommand) !== JSON.stringify(start.imageConfig.Cmd ?? null)
+    || !Array.isArray(start.service.volumes)
+    || JSON.stringify(start.mounts.map(mount => [mount.kind, mount.source ?? null, mount.target, mount.readOnly])) !== JSON.stringify((start.service.volumes as ManagedOriginalInputs['start']['mounts']).map(mount => [mount.kind, mount.source ?? null, mount.target, mount.readOnly]))) throw new Error('Original-input start declaration differs');
+  const project = new Map<string, ManagedOriginalInputs['projectInventory'][number]>();
+  for (const entry of manifest.projectInventory) {
+    if (!entry || !originalRelative(entry.path) || project.has(entry.path) || ![0o100644, 0o100755, 0o120000, 0o160000].includes(entry.mode) || !/^[a-f0-9]{40}$/.test(entry.blob)) throw new Error('Invalid original project inventory');
+    project.set(entry.path, entry);
+  }
+  const image = new Map<string, ManagedOriginalInputs['imageInventory'][number]>();
+  for (const entry of manifest.imageInventory) {
+    if (!entry || !originalTarget(entry.target) || image.has(entry.target) || !['file', 'directory', 'link', 'other'].includes(entry.type) || !Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o7777 || !bytesOf(entry.bytes) || !source.layers.includes(entry.layer)
+      || (entry.type === 'link' && (typeof entry.link !== 'string' || /[\0\r\n\\]/.test(entry.link)))) throw new Error('Invalid original image inventory');
+    image.set(entry.target, entry);
+  }
+  const targets = new Set<string>(), selected = new Map<string, OriginalInputEntry>(), expectedObjects = new Map<string, number>();
+  const hold = (entry: { sha256?: string; bytes?: number; object?: string }): void => {
+    if (!hex(entry.sha256) || !bytesOf(entry.bytes) || entry.object !== `objects/${entry.sha256}` || (expectedObjects.has(entry.sha256) && expectedObjects.get(entry.sha256) !== entry.bytes)) throw new Error('Invalid original-input payload identity');
+    expectedObjects.set(entry.sha256, entry.bytes);
+  };
+  for (const entry of manifest.inventory) {
+    if (!entry || !originalTarget(entry.target) || targets.has(entry.target) || !['file', 'directory', 'link'].includes(entry.type) || !Number.isInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o7777 || !entry.source || !['image', 'project'].includes(entry.source.kind)) throw new Error('Invalid original-input inventory');
+    targets.add(entry.target);
+    selected.set(entry.target, entry);
+    if (entry.source.kind === 'image') {
+      const original = image.get(entry.source.path);
+      if (!original || original.layer !== entry.source.layer || original.type !== entry.type || original.mode !== entry.mode || (entry.type === 'file' && original.bytes !== entry.bytes) || (entry.type === 'link' && original.link !== entry.link)) throw new Error('Original-input image provenance differs');
+    } else {
+      const original = project.get(entry.source.path);
+      if (!originalRelative(entry.source.path) || (entry.type === 'file' && (!original || original.blob !== entry.source.blob || (original.mode & 0o777) !== entry.mode))) throw new Error('Original-input project provenance differs');
+    }
+    if (entry.type === 'file') hold(entry);
+    else if (entry.object !== undefined || entry.bytes !== undefined || entry.sha256 !== undefined || (entry.type === 'link' && (typeof entry.link !== 'string' || /[\0\r\n\\]/.test(entry.link)))) throw new Error('Invalid original-input non-file');
+  }
+  for (const mount of start.mounts) if (!mount || !['bind', 'named', 'anonymous'].includes(mount.kind) || !originalTarget(mount.target) || typeof mount.readOnly !== 'boolean' || (mount.source !== undefined && typeof mount.source !== 'string')) throw new Error('Invalid original-input mount declaration');
+  const roots = new Set(manifest.roots), mounted = new Set(start.mounts.filter(mount => mount.kind === 'bind').map(mount => mount.target));
+  const under = (path: string, roots: ReadonlySet<string>): boolean => {
+    for (let at = path;; at = at.slice(0, at.lastIndexOf('/')) || '/') {
+      if (roots.has(at)) return true;
+      if (at === '/') return false;
+    }
+  };
+  for (const entry of image.values()) if (under(entry.target, roots) && !under(entry.target, mounted)) {
+    const captured = selected.get(entry.target);
+    if (!captured || captured.source.kind !== 'image' || captured.source.path !== entry.target) throw new Error('Original image input was omitted from its declared root');
+  }
+  hold({ sha256: source.composeSha256, bytes: source.composeBytes, object: source.composeObject });
+  for (const file of start.envFiles) {
+    if (!file || !originalRelative(file.path)) throw new Error('Invalid original-input env_file');
+    hold(file);
+  }
+  if ([...expectedObjects.values()].reduce((sum, bytes) => sum + bytes, 0) > bound) throw new Error('Original-input snapshot exceeds its byte bound');
+  const objects = new Map<string, Uint8Array>();
+  for (const [sha256, size] of expectedObjects) {
+    const data = readObject(`objects/${sha256}`, size);
+    if (!(data instanceof Uint8Array) || data.length !== size || digest('sha256', data) !== sha256) throw new Error('Original-input payload bytes differ');
+    objects.set(sha256, data.slice());
+  }
+  for (const entry of manifest.inventory) if (entry.type === 'file' && entry.source.kind === 'project') {
+    const data = objects.get(entry.sha256!)!, header = new TextEncoder().encode(`blob ${data.length}\0`), blob = new Uint8Array(header.length + data.length);
+    blob.set(header); blob.set(data, header.length);
+    if (digest('sha1', blob) !== entry.source.blob) throw new Error('Original-input project blob identity differs');
+  }
+  return { manifest, objects };
+}

package/src/mongodb/client.ts

@@ -0,0 +1,27 @@
+// A MongoDB client over any byte exchange: the other side of ./stream.ts, so a journey speaks the wire as an
+// application's driver does. It sends one command document as an OP_MSG and returns the document the server
+// answered; it reads what the protocol answers and decides nothing.
+// source: archive:https://registry.npmjs.org/mongodb/-/mongodb-6.20.0.tgz#sha256=a12bd599cb4f39cdf222b32380ea3efd1f60c6d88615e0700632a303a9006b02!/package/src/cmap/commands.ts "moreToCome is an OP_MSG only concept"
+import { MongoOp, decodeMsg, encodeMsg, type MongoCodec, type MongoDocument } from './stream.ts';
+
+/** Sends bytes and returns every byte the server answered to them. */
+export type MongoExchange = (bytes: Uint8Array) => Promise<Uint8Array>;
+
+/** A client on one connection: `command` sends a document to `database` and resolves with the reply document,
+ *  whatever its `ok`. A reply that is not one whole OP_MSG answering this request is an error. */
+export function mongoClient(exchange: MongoExchange, codec: MongoCodec): { command(database: string, command: MongoDocument): Promise<MongoDocument> } {
+  let nextRequest = 0;
+  return {
+    async command(database, command) {
+      const requestId = ++nextRequest;
+      const answered = await exchange(encodeMsg(codec, { ...command, $db: database }, requestId, 0));
+      if (answered.length < 16) throw new Error('the server answered no message');
+      const view = new DataView(answered.buffer, answered.byteOffset, answered.byteLength);
+      const length = view.getInt32(0, true), responseTo = view.getInt32(8, true), opcode = view.getInt32(12, true);
+      if (length !== answered.length) throw new Error(`the server answered ${answered.length} bytes, and its message says ${length}`);
+      if (opcode !== MongoOp.MSG) throw new Error(`the server answered opcode ${opcode}, not OP_MSG`);
+      if (responseTo !== requestId) throw new Error(`the server answered request ${responseTo}, not ${requestId}`);
+      return decodeMsg(codec, answered).document;
+    },
+  };
+}

package/src/mongodb/index.ts

@@ -0,0 +1,5 @@
+// THE KERNEL'S MONGODB WIRE (`@volter/world-core/mongodb`): MongoDB's message framing as a TwinStream, and its client.
+// A pack that serves MongoDB passes what a command means (its engine) and the document codec; the kernel names no vendor.
+// docs/contributing/architecture.md, "Other wires", the MongoDB wire.
+export * from './stream.ts';
+export * from './client.ts';