@volter/world-core 3.0.155 → 3.0.156

package/dist/src/head.d.ts

@@ -174,6 +174,9 @@ export declare function performEntries(opts: {
  * `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.
  */
+/** Whether `performAtHead` would perform an entry now (a twin whose root says `auto`, outside a pack fetch's deferred
+ *  group): a caller appending several writes at once appends them one at a time then, each performed before the next. */
+export declare function performsAtHeadNow(service: string, root?: string): boolean;
 export declare function performAtHead(service: string, action: Pick<TwinAction, 'id'>, root?: string): Promise<{
     performed: boolean;
     externalId?: string;

package/dist/src/head.js

@@ -464,6 +464,15 @@ async function performNow(opts) {
  * `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.
  */
+/** Whether `performAtHead` would perform an entry now (a twin whose root says `auto`, outside a pack fetch's deferred
+ *  group): a caller appending several writes at once appends them one at a time then, each performed before the next. */
+export function performsAtHeadNow(service, root) {
+    const request = currentCorrelationId();
+    if (request !== undefined && deferred.has(request))
+        return false;
+    const head = headOf(service, root);
+    return head.kind === 'real' && head.deploy === 'auto';
+}
 export async function performAtHead(service, action, root) {
     // a pack fetch performs its request's entries as one group after the handler (performRequestGroup)
     const request = currentCorrelationId();

package/dist/src/history.d.ts

@@ -51,7 +51,7 @@ export declare function saveHistoryView(directory: string, view: HistoryView): s
  *  (and the view document itself) and each named directory's ancestry record (its generation). A read cache keyed by this sees an
  *  ancestor's retained history truncated, replaced or its directory re-created, which the full read
  *  refuses (`historyEntries`), instead of serving a tree folded from the history it replaced. */
-export declare function inheritedHistoryKey(service: string, root?: string): string;
+export declare function inheritedHistoryKey(service: string, root?: string, meta?: string | null): string;
 export declare function inheritedHistory(service: string, root?: string): HistoryView | undefined;
 /** Capture under the directory's history lock, as appends and complete observation batches are made. */
 export declare function captureHistory(service: string, root?: string): {

package/dist/src/history.js

@@ -108,14 +108,14 @@ export function saveHistoryView(directory, view) {
         for (const dependency of dependencies)
             commitParentPin(dependency.directory, file);
         return id;
-    });
+    }, { operation: 'view pin publication' });
 }
 /** What an inherited history's content stands on, as file facts: every segment file the view names
  *  (and the view document itself) and each named directory's ancestry record (its generation). A read cache keyed by this sees an
  *  ancestor's retained history truncated, replaced or its directory re-created, which the full read
  *  refuses (`historyEntries`), instead of serving a tree folded from the history it replaced. */
-export function inheritedHistoryKey(service, root) {
-    const parent = readBranchMeta(service, root)?.parent;
+export function inheritedHistoryKey(service, root, meta) {
+    const parent = readBranchMeta(service, root, meta)?.parent;
     if (!parent?.view)
         return '';
     const store = getActiveWorldStore();
@@ -170,7 +170,7 @@ export function captureHistory(service, root) {
                 descriptor.segments.push({ directory, generation, file, start: 0, count: entries.length, digest: historyDigest(entries) });
         }
         return { view: saveHistoryView(directory, descriptor), position: historyLength(descriptor.layout), descriptor };
-    });
+    }, { operation: 'capture' });
 }
 export function originHead(service, root) {
     const raw = getActiveWorldStore().read(join(worldPaths(service, root).dir, 'origin-head.json'));
@@ -213,7 +213,7 @@ export function publishOriginHistory(service, root, remoteView, layout, entries)
         const view = saveHistoryView(directory, { version: 1, owner: { directory, generation }, layout, segments });
         store.writeAtomic(join(directory, 'origin-head.json'), JSON.stringify({ view, remoteView }));
         return { view, appended };
-    });
+    }, { operation: 'origin fetch' });
 }
 /** A changeset binds the complete inherited view, including this root's observations. */
 export function captureParentHistory(service, root) {
@@ -221,7 +221,7 @@ export function captureParentHistory(service, root) {
         const head = captureHistory(service, root);
         const position = head.position - head.descriptor.layout.branch;
         return { view: saveHistoryView(worldPaths(service, root).dir, historyPrefix(head.descriptor, position)), position };
-    });
+    }, { operation: 'capture' });
 }
 /** Compare evaluated views, so removals, reordered rows and layout changes count as drift. */
 export function historyChanges(service, before, after) {
@@ -295,7 +295,7 @@ export function historyAtInstant(service, instant, root, selectedView) {
         }
         const view = saveHistoryView(directory, { version: 1, owner: source.owner, layout, segments, ...(source.origin ? { origin: { ...source.origin, ...(keep.slice(0, source.origin.position).some(v => !v) ? { incomplete: true } : {}) } } : {}) });
         return { view, position: historyLength(layout) };
-    });
+    }, { operation: 'capture' });
 }
 /** Replace only the tracked origin layer; inherited local layers keep their exact projection order. */
 export function replaceHistoryOrigin(previous, origin, next) {

package/dist/src/index.d.ts

@@ -40,7 +40,7 @@ export { answerVendorErrors, RefusedWriteError } from './head.js';
 export { GraphqlError, type GraphqlPart, type GraphqlResolver } from './graphql-wire.js';
 export { VendorUnreachableError } from './vendor-call.js';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER } from './request-scope.js';
-export { serveHttp, serveStream, StreamListenerUnavailable, type HttpHandler, type HttpServer, type ServeHttpOptions } from './serve-http.js';
+export { serveHttp, serveStream, nodeBuiltin, StreamListenerUnavailable, type HttpHandler, type HttpServer, type ServeHttpOptions } from './serve-http.js';
 export type { TwinStream, TwinStreamConnection, TwinStreamSink } from './twin-fetch.js';
 export { privateTransportKey } from './private-transport.js';
 export { siteLabel, siteUrlOf, twinSiteUrl, twinVendorUrl } from './twin-fetch.js';
@@ -58,6 +58,7 @@ export { EngineDatabaseError, EngineUnavailableError, quoteIdent } from './manag
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.js';
 export type { Mail, SmtpRoute } from './smtp.js';
 export * as s3 from './s3/wire.js';
+export * as xml from './xml.js';
 export * as clickhouse from './clickhouse/index.js';
 export { sampleFromSchema } from './schema-sample.js';
 export * as openaiWire from './openai-wire.js';
@@ -70,6 +71,7 @@ export { presignSigV4, signSigV4, verifySigV4, type SigV4Verdict } from './sigv4
 export * as redis from './redis/index.js';
 export * as mysql from './mysql/index.js';
 export * as live from './live/index.js';
+export * as mongodb from './mongodb/index.js';
 export * as git from './git/index.js';
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from './scenario.js';
 export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.js';
@@ -77,3 +79,4 @@ export { verifyAttestationBundle } from './attestation.js';
 export { browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.js';
 export { readHostPort } from './host-port.js';
 export { assertBrowserName, browserOrigin, validateBrowserState, validateBrowserStorageState, validateBrowserContext, browserAcceptLanguage, cookieMatchesHost, type BrowserCookie, type BrowserState, type BrowserStorageState, type BrowserContext, type BrowserIndexedDB } from './browser-state.js';
+export * as managedOriginalInputs from './managed-original-inputs.js';

package/dist/src/index.js

@@ -29,7 +29,7 @@ export { GraphqlError } from "./graphql-wire.js";
 export { VendorUnreachableError } from "./vendor-call.js";
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER } from "./request-scope.js";
 // ── the serve factory ──────────────────────────────────────────────────────────────────────────
-export { serveHttp, serveStream, StreamListenerUnavailable } from "./serve-http.js";
+export { serveHttp, serveStream, nodeBuiltin, StreamListenerUnavailable } from "./serve-http.js";
 export { privateTransportKey } from "./private-transport.js";
 // where a page links a hostname its twin answers, inside the World that shows it
 export { siteLabel, siteUrlOf, twinSiteUrl, twinVendorUrl } from "./twin-fetch.js";
@@ -49,6 +49,8 @@ export { passwordHash, personOf, personWith, recordPerson } from "./people.js";
 export { EngineDatabaseError, EngineUnavailableError, quoteIdent } from "./managed-database.js";
 // S3's wire (contract "S3's wire is a kernel library too") and the git plane (contract "The git plane is a kernel library")
 export * as s3 from "./s3/wire.js";
+// Generic strict XML grammar; vendor interpretation remains in its consumer.
+export * as xml from "./xml.js";
 export * as clickhouse from "./clickhouse/index.js";
 export { sampleFromSchema } from "./schema-sample.js";
 export * as openaiWire from "./openai-wire.js";
@@ -61,6 +63,7 @@ export { presignSigV4, signSigV4, verifySigV4 } from "./sigv4.js";
 export * as redis from "./redis/index.js";
 export * as mysql from "./mysql/index.js";
 export * as live from "./live/index.js";
+export * as mongodb from "./mongodb/index.js";
 export * as git from "./git/index.js";
 // ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from "./scenario.js";
@@ -68,3 +71,4 @@ export { verifyAttestationBundle } from "./attestation.js";
 export { browserSessionToken, startBrowserSession, endBrowserSession } from "./browser-session.js";
 export { readHostPort } from "./host-port.js";
 export { assertBrowserName, browserOrigin, validateBrowserState, validateBrowserStorageState, validateBrowserContext, browserAcceptLanguage, cookieMatchesHost } from "./browser-state.js";
+export * as managedOriginalInputs from "./managed-original-inputs.js";

package/dist/src/log.d.ts

@@ -102,7 +102,7 @@ export declare function originLogPath(service: string, root?: string): string;
 /** A parent is at a URL when it is not a path on this machine. */
 export declare function isUrlParent(at: string): boolean;
 export declare function checkpointPath(service: string, root?: string): string;
-export declare function readBranchMeta(service: string, root?: string): BranchMeta | null;
+export declare function readBranchMeta(service: string, root?: string, read?: string | null): BranchMeta | null;
 export declare function writeBranchMeta(service: string, meta: BranchMeta, root?: string): void;
 /** A v1 observed row as an entry: a delta event folds its `changed.*.after`; anything else folds
  *  nothing and rides along for `listEvents`. An entry row is itself. */
@@ -130,13 +130,21 @@ export declare function landedIds(parent: Entry[]): Set<string>;
  *  before it had observed the vendor's own subject under that id (its tree was behind) must not fold
  *  the vendor's subject onto the landed one, nor send a caller who addresses the vendor's id there. */
 export declare function aliasesFrom(parent: Entry[]): Map<string, string>;
-type Subject = {
+export type Subject = {
     type: string;
     id: string;
     updatedAt: string;
     fields: SubjectFields;
 };
 export type Tree = Map<string, Subject>;
+/** One subject read by the same guarded key as a write's answer; restore the vendor's own metadata fields. */
+export declare function heldSubject(service: string, type: string, id: string, root?: string): Subject | 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 declare function foldLocalWrite(previous: Subject | undefined, type: string, id: string, fields: SubjectFields, at: string): Subject;
 /** 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. */
@@ -152,6 +160,15 @@ export declare function ownFields(r: TwinResource): Record<string, unknown>;
 export declare function dropCheckpoint(service: string, root?: string): void;
 /** Preserve each ancestor's observed-then-local overlay, including landed IDs and aliases. */
 export declare function foldHistory(entries: Entry[], layout: HistoryLayout, service?: string): 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 declare function readSubject(service: string, type: string, id: string, root?: string): TwinResource | undefined;
 export declare function readTree(service: string, root?: string, opts?: {
     until?: string;
     at?: number;
@@ -171,6 +188,10 @@ export declare function readTreeMap(service: string, root?: string, opts?: {
     at?: number;
     view?: string;
 }): Tree;
+/** 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 declare function appendToBranchLog(service: string, root: string | undefined, data: string, append: () => void): string | undefined;
 /** What changed in a service's tree since `since` (a `treeStamp` an earlier read was made at): the subjects
  *  written since, as resources; the keys (`type:id`) of those no longer in the tree; and, of the changed, the keys
  *  now at the tree's end in the order they stand there (new to the tree, or deleted and made again), which a
@@ -257,4 +278,3 @@ export declare function subjectHistory(service: string, subject: {
     type: string;
     id?: string;
 }, root?: string): Entry[];
-export {};

package/dist/src/log.js

@@ -29,14 +29,14 @@ import { canonicalStatePath, checkParent, commitParentPin, pinParent, withAncest
 import { resolveReferences } from "./references.js";
 import { hashFieldValue } from "./hash.js";
 import { worldPaths } from "./storage.js";
-import { getActiveWorldStore } from "./world-store.js";
+import { getActiveWorldStore, TREE_FILES } from "./world-store.js";
 export const CHECKPOINT_EVERY = 100;
 // Retained checkpoints and process memos are disposable projections, never history.
 const TREE_PROJECTION_VERSION = 2;
 export const DELTA_SUFFIX = '.delta';
 export function parentLogPath(service, root) { return worldPaths(service, root).events; }
-export function branchLogPath(service, root) { return join(dirname(worldPaths(service, root).events), 'actions.jsonl'); }
-export function branchMetaPath(service, root) { return join(dirname(worldPaths(service, root).events), 'branch.json'); }
+export function branchLogPath(service, root) { return join(dirname(worldPaths(service, root).events), TREE_FILES.branch); }
+export function branchMetaPath(service, root) { 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, root) { return join(dirname(worldPaths(service, root).events), 'origin.jsonl'); }
 /** A parent is at a URL when it is not a path on this machine. */
@@ -114,8 +114,9 @@ function readRows(path) {
     cache.set(path, tail !== undefined ? { rows, lines: lines.length - 1, bytes: Buffer.byteLength(content), tail } : { content, rows, lines: lines.length - 1 });
     return rows.slice();
 }
-export function readBranchMeta(service, root) {
-    const raw = getActiveWorldStore().read(branchMetaPath(service, root));
+export function readBranchMeta(service, root, read) {
+    // `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);
@@ -179,8 +180,8 @@ export function writeBranchMeta(service, meta, root) {
             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
  *  nothing and rides along for `listEvents`. An entry row is itself. */
@@ -251,7 +252,7 @@ export function appendOriginEntry(entry, root) {
             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). */
 export function parentPosition(service, root) {
@@ -300,6 +301,22 @@ function overlay(tree, type, id, fields, at) {
         delete merged.deleted;
     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, type, id, root) {
+    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, type, id, fields, at) {
+    const key = `${type}:${id}`;
+    const 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. */
@@ -402,6 +419,22 @@ export function foldHistory(entries, layout, service) {
     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, type, id, root) {
+    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, root, opts = {}) {
     return treeResources(readTreeMap(service, root, opts));
 }
@@ -414,7 +447,7 @@ export function readParentTreeMap(service, root) {
         return foldHistory([...(inherited ? historyEntries(inherited) : []), ...own], {
             ...(inherited ? { base: inherited.layout } : {}), parent: own.length, branch: 0,
         }, service);
-    });
+    }, { operation: 'tree fold' });
 }
 const treeMemos = new WeakMap();
 /** How many extensions a memo remembers the touched subjects of; a projection further behind refolds. */
@@ -422,11 +455,44 @@ const TREE_STEPS_KEPT = 64;
 function statKey(path) { 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, root) { return parentKeyOf(service, root); }
-function parentKeyOf(service, root) { return `${TREE_PROJECTION_VERSION}|${statKey(parentLogPath(service, root))}|${getActiveWorldStore().read(branchMetaPath(service, root)) ?? ''}|${inheritedHistoryKey(service, root)}`; }
+export function parentStamp(service, root) { return treeFacts(service, root).parentKey; }
+function parentKeyOf(service, root) { 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, root) {
+    // 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 !== '' };
+}
+const keptFacts = new WeakMap();
+function treeFacts(service, root) {
+    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, root) { return `${parentKeyOf(service, root)}#${statKey(branchLogPath(service, root))}`; }
+export function treeStamp(service, root) { const facts = treeFacts(service, root); return `${facts.parentKey}#${facts.branchKey}`; }
 const cloneTree = (tree) => new Map([...tree].map(([k, s]) => [k, { ...s, fields: { ...s.fields } }]));
 const memoStamp = (m) => `${m.parentKey}#${m.branchKey}`;
 /** The subject keys entries write (as foldEntries folds them), and the vendor rows an alias moves a local one onto. */
@@ -484,8 +550,11 @@ function currentTree(service, root) {
     // 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));
@@ -497,24 +566,7 @@ function currentTree(service, root) {
         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;
-            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);
@@ -526,7 +578,78 @@ function currentTree(service, root) {
             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, slot, held, fresh, branchKey, service) {
+    const keys = touchedKeys(fresh, held.aliases);
+    const from = memoStamp(held);
+    let appended;
+    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, root, data, append) {
+    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) => (key === '-' ? 0 : Number(key.slice(0, key.indexOf(':'))));
+    const fresh = [];
+    // 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
  *  written since, as resources; the keys (`type:id`) of those no longer in the tree; and, of the changed, the keys
@@ -637,7 +760,7 @@ function readTreeMapFull(service, root, opts = {}) {
             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, root) {
     return withHistoryLock(worldPaths(service, root).dir, () => {
@@ -646,7 +769,7 @@ export function cutCheckpoint(service, root) {
         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. */
 export function unpushedEntries(service, root) {
@@ -745,7 +868,7 @@ export function appendParentEntry(entry, root) {
         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
  *  entries, one sequence with a position. A clone's parent is exactly this. */
@@ -823,7 +946,7 @@ export function rebaseBranch(service, root, opts = {}) {
             dropCheckpoint(service, root);
         }
         return { moved, from, to, conflicts };
-    });
+    }, { operation: 'branch-pointer adjustment' });
 }
 /**
  * HISTORY through the kernel: every entry that touched a subject (or every subject of a type), parent

package/dist/src/managed-original-inputs.d.ts

@@ -0,0 +1,101 @@
+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 declare const originalTarget: (path: string) => boolean;
+export declare const originalRelative: (path: string) => boolean;
+export declare function referenceOf(value: unknown): OriginalInputReference;
+/** Hash and validate neutral carrier data. The caller supplies I/O; no pack/vendor behavior or import effects. */
+export declare function readSnapshot(bytes: Uint8Array, expected: string, readObject: (path: string, bytes: number) => Uint8Array): {
+    manifest: ManagedOriginalInputs;
+    objects: ReadonlyMap<string, Uint8Array>;
+};