@volter/world-core 3.0.155 → 3.0.157

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,5 @@ 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';
+export * as managedGoPrograms from './managed-go-programs.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,5 @@ 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";
+export * as managedGoPrograms from "./managed-go-programs.js";

package/dist/src/live/ingest.js

@@ -25,7 +25,6 @@ export function liveIngest(options) {
         let priorInit;
         let started = false;
         let metadata;
-        let refusedCodec;
         const recording = () => {
             const row = store.rows(LIVE).find((r) => r.id === stream);
             return recordingOf(row, segmentsOf(store, stream));
@@ -116,7 +115,12 @@ export function liveIngest(options) {
                         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;
@@ -137,12 +141,8 @@ export function liveIngest(options) {
                 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));
@@ -153,12 +153,8 @@ export function liveIngest(options) {
                 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));

package/dist/src/live/rtmp.js

@@ -98,6 +98,9 @@ export function rtmpSession(sink, publisher, 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?.message ?? error)}`));
         try {
             sink.end();
         }
@@ -165,6 +168,7 @@ export function rtmpSession(sink, publisher, log = () => { }) {
                     close();
                     return;
                 }
+                ended = false;
                 publishing = true;
                 publishStream = stream;
                 // user control StreamBegin (event 0) for the publish's stream, then its start
@@ -281,7 +285,7 @@ export function rtmpSession(sink, publisher, log = () => { }) {
             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?.message ?? error)}`);
             close();
         }).finally(() => { queued -= payload.length; });
@@ -447,10 +451,8 @@ export function rtmpSession(sink, publisher, 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?.message ?? error)}`));
-            phase = 'closed';
+            // Peer close and server refusal share one end, after any admission or write already under way settles.
+            close();
         },
     };
 }

package/dist/src/live/segmenter.js

@@ -39,14 +39,20 @@ export class Segmenter {
         this.avc = config;
         this.freshInit = true;
         this.keyed = false;
+        this.unkeyedSince = undefined;
         return out;
     }
     audioConfig(config) {
         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;
     }
     /** A video frame at its decode time: the segment it closes, if it closes one. */

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/machines.js

@@ -14,6 +14,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // 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.js";
 import { nodeBuiltin } from "./serve-http.js";
+import { refuseRequiredMachineTransport } from '../required-credential-transport.cjs';
 /** A declared compute capability gap, distinct from a failed admitted guest. */
 export function isMachineCapabilityGap(error) {
     return typeof error === 'object' && error !== null && 'code' in error && error.code === 'WORLD_MACHINE_CAPABILITY_GAP';
@@ -60,6 +61,7 @@ function dockerPool(world) {
     });
     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 } : {}) };
@@ -67,6 +69,7 @@ function dockerPool(world) {
         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}`]);
@@ -80,6 +83,7 @@ function dockerPool(world) {
             return { ports: published };
         },
         async exec(name, spec) {
+            refuseRequiredMachineTransport(process.env, 'Docker machine exec transport');
             const { spawn } = nodeBuiltin('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
@@ -165,7 +169,7 @@ function dockerPool(world) {
             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); },
     };