@volter/world-core 2.0.37 → 3.0.0

package/dist/src/index.js

@@ -1,102 +1,59 @@
-// @volter/world-core — the shared state kernel and vendor-independent runtime libraries.
-// Protocol-2 packs read the checkpointed tree and write through the head's state system.
-// The kernel owns logs, branches, landing and receipts; each pack owns its vendor's wire
-// and resource semantics. See docs/concepts/the-model.md and docs/contributing/architecture.md.
-// Compatibility exports below are not a second state model. Refer to their implementations
-// before using older operator helpers; removed v1 entry points fail explicitly.
-// Conformance/validation tooling (capability + spec + recorded-diff + UI harnesses and
-// the spec derivers) is NOT part of the runtime kernel — it lives in @volter/world-tooling,
-// a dev dependency. A twin runs without it; only tests and the conformance scripts use it.
-// Pack registry — vendor twins self-describe (TwinPack) so tooling discovers them.
-export { clearRegistry, getPack, hasPack, listPacks, registerPack, pullPosture, assertContinuousPullAllowed, pullOnSchedule, resolvePullVendor, DEFAULT_PULL_POSTURE, DEFAULT_PULL_TRIGGER, PROTOCOL_VERSION, PROTOCOL_MAJOR, protocolStanding } from "./packRegistry.js";
-// The DELIVER verb (`emit`) — vendor-agnostic engine + CLI glue; packs declare a TwinEmitter
-// (their event catalog, endpoints-from-state, and signed synthesis) on `TwinPack.emitter`.
-export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from "./scenario.js";
-export { WORLD_CLOCK_ENV, worldNow } from "./world-clock.js";
-export { WORLD_ENV_NAMES_ENV, worldEnvValue } from "./world-env.js";
-export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, twinPublicBase, withRequestScopes } from "./twin-fetch.js";
-export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from "./request-scope.js";
-export { compileSurface, createDerivedFetch, matchOperation } from "./derived.js";
-export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from "./trace-context.js";
-export { bindSemantics, coreFor, crossCutting, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from "./derived-core.js";
-export { emitTwinEvent, eventSubscriptionMatches, listEmittable, runEmitCli } from "./emit.js";
-// The vendor-agnostic CLIENT-SIDE RATE BUDGET — the fail-closed backstop a pack's guarded client
-// routes every live vendor call through. The MECHANISM is here; the per-vendor ceiling/window/
-// weights are DATA the pack declares (`TwinPack.rateBudget` / `declareRateBudget`). Exported so an
-// operator can inspect spend (`snapshot`) and a caller can catch `RateBudgetError` by type; there
-// is deliberately no export that disables the guard, and a vendor with no declaration falls back
-// to `DEFAULT_RATE_BUDGET` rather than to no limit at all.
-export { DEFAULT_RATE_BUDGET, MAX_RATE_BUDGET_CEILING, MAX_RATE_BUDGET_WINDOW_MS, MIN_RATE_BUDGET_WEIGHT, MIN_RATE_BUDGET_WINDOW_MS, RateBudget, RateBudgetError, declareRateBudget, hasRateBudgetDeclaration, listRateBudgets, priceCall, rateBudgetPath, rateBudgetPolicy, rateBudgetWeight, resetToSeconds, assertBudgetGuardIntact, } from "./rateBudget.js";
-export { GenericWorldStateSchema, WorldActorSchema, WorldExternalRefSchema, WorldServiceEventSchema, WorldSubjectSchema, } from "./schemas.js";
-// NOTE: source books (event→tracker-source mapping) moved OUT of the world — it was
-// the last tracker coupling. It now lives at `@volter/tracker/world-source-books`,
-// so `@volter/world-core` is a pure twin runtime.
-export { loadWorldConfig, } from "./worldConfig.js";
-export { DELTA_TYPE_SUFFIX, diffSubjectFields, hashFieldValue, subjectKey, deltaAfterFields } from "./hash.js";
-export { appendDurable, appendEvent, createEvent, emptyGenericState, genericWorldReducer, listEvents, loadState, projectionLockPath, readJsonFile, rebuildGenericState, rebuildState, 
-// Scrub: delete pulled data at rest (TWIN-45) — the honest, plain-`rm` counterpart to
-// sync pull's fold-into-the-log. See docs/concepts/data-and-keys.md for the full data-at-rest story.
-scrubService, scrubWorld, stateDirName, 
-// Opt-in structured stderr logging (VOLTER_TWIN_LOG=1) for the audit trail. Public so a
-// CONNECTOR can say on the same stream when the vendor handed it a truncated page — a
-// silent shortfall is the one thing a pull must never pass off as the whole resource.
-twinLog, 
-// The kernel's cross-process mutual-exclusion primitive (exclusive-create lockfile with
-// stale-holder reclaim). Public so world-runtime can guard concurrent `upWorld` claims of
-// one instance dir with the SAME lock semantics the event log uses (TWIN-36).
-withFileLock, worldPaths, worldStateRoot, 
-// Where another pack's store is in a World (architecture A3), and the variable the runtime names its data directory in.
-ownerStoreRoots, WORLD_DATA_ENV, } from "./storage.js";
-// The pluggable persistence seam: the sync WorldStore interface, its fs (default) and
-// in-memory implementations, the active-store injection point, and the async
-// hydrate/flush boundary a serverless (Durable Object / KV / redis) entry uses.
-export { FsWorldStore, MemoryWorldStore, getActiveWorldStore, setActiveWorldStore, withWorldStore, hydrateInto, flushFrom, } from "./world-store.js";
-export { SqlWorldStore } from "./world-store-sql.js";
-// The blob seam (runtime contract R11): byte storage behind byte-carrying handlers, so a
-// serverless namespace puts bytes in object storage while local worlds keep today's layout.
-export { FsBlobStore, MemoryBlobStore, blobDigest, getActiveBlobStore, setActiveBlobStore, withBlobStore, readBlobRange, } from "./blob-store.js";
-export { applyTwinWrite, applyTwinWriteAtomic, createTwinServer, CALLER_HEADER, journalTwinRequest, twinRequestJournalFailures, twinRequestCredentials, readTwinRequestJournal, resolveTwinRead, twinRequestJournalEnabled, twinRequestJournalPath, readTwinRequestJournalFrom, twinResources, } from "./serve.js";
-export { createTwinProxy } from "./proxy.js";
-export { forkTwin, isFork, readForkMeta, } from "./fork.js";
-export { appendAction, appendTransactionCommit, checkPrecondition, confirmAction, listActions, listTransactionCommits, pendingActions, pushablePendingActions, isTwinBookkeeping, pendingTransactionCommits, projectResources, projectOwnerResources, OwnerStoreAmbiguousError, revertAction, TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from "./actions.js";
-// ── Operator control plane (R19/R20): remote refs, queue lifecycle, push ledger,
-// apply leases, plan, status. (the twins architecture notes)
-// The CHANGESET primitive + the ledger DIFF (docs/concepts/the-model.md v0) — "commit" and
-// "diff" for operational reality: a cross-service base marker, the ledger delta since it, and
-// the content-addressed, replayable changeset over that delta. State-level by construction
-// (it reads the same per-service action ledgers `actions.ts` writes); `volter-world` supplies
-// world discovery and thin verbs on top.
-export { approveChangeset, assertMarkerBelongsTo, assertSafeChangesetName, assertValidVerifiers, buildChangeset, captureMarker, changesetContentHash, changesetHashMatches, changesetReadiness, approverOf, CHANGESET_KIND, diffLedgers, formatApplication, formatChangeset, formatRebaseReport, narrateActions, narrationDrift, rebaseChangeset, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, MARKER_KIND, normalizeChangeset, parseVerifierExpression, replayChangeset, runChangesetVerifiers, summarizeByVendor, twinWriteShape, withApplication, withVerification, worldBootMarker, WORLD_BOOT_MARKER_ID, } from "./changeset.js";
-export { getActivePackAssets, setActivePackAssets, packAsset, assetContentType, confinedAssetPath, LocalPackAssets, BindingPackAssets } from "./pack-assets.js";
-// The git plane (contract "The git plane is a kernel library"): objects, packs, refs, smart HTTP.
+// @volter/world-core — the pack contract (docs/contributing/architecture.md, "The pack contract: the kernel's root").
+// This root is everything a Protocol 3 pack may import from the kernel, and nothing else: the manifest's and the
+// descriptor's types, the handler contract, the derived fetch and core a pack's fetch.ts builds, the serve factory's
+// pieces, the kernel's deterministic helpers and the scenario grammar. The kernel itself (the log and the tree read
+// and written directly, the head, the stores, the runtime's scopes) and the plugin contract's surfaces are
+// `@volter/world-core/runtime`, which a pack never imports.
+import { bindSemantics as bindAny } from "./derived-core.js";
+import { packOf as packOfAny, registerPack as registerAny } from "./packRegistry.js";
+/** The descriptor a manifest declares, with its vendor ("The descriptor"); given the pack's generated surface (a vendor of
+ *  lanes: each lane's manifest and surface), with the real-system adapters the kernel derives from them. */
+export const packOf = (manifest, surface) => packOfAny(manifest, surface);
+/** The pack registered, so the World finds it. */
+export const registerPack = (pack) => registerAny(pack);
+export { verifyEvent } from "./events.js";
+export { deriveStateSystem, deriveVendorStateSystem } from "./derived-real.js";
+export { machinePool } from "./machines.js";
+/** A pack's handlers, by operationId, bound to the manifest: each is answered over the contract's context. */
+export const bindSemantics = (m, handlers, scope = {}) => bindAny(m, handlers, scope);
+// ── the derived fetch ──────────────────────────────────────────────────────────────────────────
+export { createPackFetch, createVendorFetch } from "./pack-fetch.js";
+export { createDerivedFetch } from "./derived.js";
+export { coreFor, crossCutting, derivedRequestScopes, vendorError } from "./derived-core.js";
+export { answerVendorErrors, RefusedWriteError } from "./head.js";
+// a GraphQL API's resolvers (`semantics/graphql.ts`), and the error one answers with the vendor's type
+export { GraphqlError } from "./graphql-wire.js";
+// what `ctx.vendorFetch` throws when the other vendor cannot be reached (a vendor's call to another as its own behaviour)
+export { VendorUnreachableError } from "./vendor-call.js";
+export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER } from "./request-scope.js";
+// ── the serve factory ──────────────────────────────────────────────────────────────────────────
+export { serveHttp, serveStream } from "./serve-http.js";
+export { statefulTwinManifest, twinManifest } from "./scenario.js";
+export { assetContentType, packAsset } from "./pack-assets.js";
+export { bytesResponse, contentTypeOf, fileResponse } from "./file-response.js";
+// ── the kernel's deterministic helpers ─────────────────────────────────────────────────────────
+export { certificateOf, digest, digestBytes, equalSecrets, oauth1BaseString, oauth1Encode, oauth1Header, oauth1Signature, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, md5, publicKeyOf, sha256, signWith, SIGNING_ALGORITHMS, uuidFrom, verifyWith } from "./signing.js";
+export { blobDigest } from "./blob-store.js";
+// compressed bytes a wire carries (a SARIF upload), over web streams
+export { gunzip, gzip } from "./bytes.js";
+// a row's own fields, where the tree's reserved ones (id, type, updatedAt) shadow the vendor's of the same name
+export { ownFields } from "./log.js";
+// the people a vendor's pages sign in (a `_person` row with its password's hash)
+export { passwordHash, personOf, personWith, recordPerson } from "./people.js";
+// the World's managed Postgres a handler reaches as `ctx.engine` (managed-database.ts), and a mail's route (`ctx.mail`)
+export { EngineDatabaseError, EngineUnavailableError, quoteIdent, worldClockSql } 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";
+export * as clickhouse from "./clickhouse/index.js";
+export { sampleFromSchema } from "./schema-sample.js";
+export * as openaiWire from "./openai-wire.js";
+export * as anthropicWire from "./anthropic-wire.js";
+export * as protobuf from "./protobuf.js";
+export * as grpc from "./grpc-wire.js";
+export { acceptH2Connection } from "./h2.js";
+export { placeholderPng } from "./placeholder-image.js";
+export { presignSigV4, signSigV4, verifySigV4 } from "./sigv4.js";
+export * as redis from "./redis/index.js";
 export * as git from "./git/index.js";
-// The push arm: the kernel's transaction over a pack's one `perform<Name>Action` (contract section of that name).
-// The placeholder remote (contract section of that name): the seed is a pull, never a pending write.
-export { PLACEHOLDER_REMOTE, beginPlaceholderPull, endPlaceholderPull, placeholderPullActive, placeholderPullMarkerPath, withPlaceholderPull, placeholderEventsFor } from "./placeholder-remote.js";
-export { ownFields, subjectHistory, rebaseBranch, cutCheckpoint, appendParentEntry, wholeLog, branchEntries, branchLogPath, branchMetaPath, CHECKPOINT_EVERY, dropCheckpoint, foldEntries, landedCopy, landedIds, parentEntries, parentLogPath, position, readBranchMeta, readTree, toEntry, toEvent, unpushedEntries, writeBranchMeta } from "./log.js";
-export { sealCredential, openSealedCredential, MemoryCredentialStorage, keySealer, transitSealer } from "./credential.js";
-export { validateRemoteOrigin, buildRemoteExecute } from "./executor.js";
-export { clearRoot, authStrategyFor, clearStateSystems, NO_SECRETS_CHECK, readRoot, registerAuthStrategy, registerStateSystem, rootPath, runChecks, stateSystemFor, writeRoot } from "./state-system.js";
-export { observeAppends } from "./actions.js";
-export { appendActionIfAbsent, appendActionOccurrence } from "./actions.js";
-// PROTOCOL 2 — the head and the fold (company contract "The head", "Refresh is the kernel's fold")
-export { answerVendorErrors, performEntries, performAtHead, deployableEntries, headOf, boundRoot, loadChecks, loadCheck, openRootCredential, resealRootCredential, destinationOf, openSealedRecord, sealsThroughVault, rootCustody, sealingKey, setCheckLoader, setSealingKeySource, setSealer, currentSealer, openSealedAt, userKek, userKekPath, vendorOf, worldRootOf, RefusedWriteError, VendorWriteError, HeadError } from "./head.js";
-export { observeResource, observeResources, collectObservations, foldObservations } from "./observe.js";
-export { readTreeMap, readParentTreeMap, treeStamp, treeChangesSince, originEntries, appendOriginEntry, originLogPath, isUrlParent, parentPosition, positionAt, splitsBatch, assertBatchBoundary } from "./log.js";
-// v1 left the kernel (contract "Just like Neon", 5): the names a protocol 1 pack still imports throw on
-// their first call, so the catalog stays importable and a pack out of date fails loudly.
-export * from "./v1-removed.js";
-export { referenceField, registerReferences, packReferences, resolveReferences } from "./references.js";
-// the HTTP server seam: the one place the serve path meets the runtime (Bun or Node)
-export { serveHttp, nodeBuiltin, WORLD_BOOT_PATH } from "./serve-http.js";
-// two runtime-neutral helpers for a pack's serve path: a file as a Response, a mirror's client bundle
-export { fileResponse, contentTypeOf } from "./file-response.js";
-export { bundleClient, filePathOf } from "./client-bundle.js";
-// the brand's tokens and faces for a Volter page (the console, the site, the UI kit), fetched at build
-export { brandTokensResponse } from "./brand-tokens.js";
-export { readResourceBlob, readResourceBlobRange, resourceBlobSize, resourceChain } from "./resource-blob.js";
-export { mirrorShellUnder } from "./mirror-shell.js";
-export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, withStateRemoval } from "./ancestry.js";
-export { captureHistory, captureParentHistory, historyChanges, historyAtInstant, historyDigest, historyEntries, historyLength, historyPrefix, inheritedHistory, originHead, publishOriginHistory, readHistoryView } from "./history.js";
-export { foldHistory } from "./log.js";
-export { volterHome } from "./volter-home.js";
+// ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────
+export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from "./scenario.js";

package/dist/src/log.js

@@ -20,11 +20,11 @@
 // and the fold skips a branch entry whose id the parent already holds. Nothing is suppressed,
 // rebound or quarantined by a bookkeeping row; `unpushed` is the branch log minus what the parent
 // holds. The parent log accepts the v1 observed-event rows too (`toEntry` reads a delta event as
-// an entry; a non-delta observation folds nothing and is kept for `listEvents`), so a protocol 1
-// pack's own fold of the logs keeps working while it is deprecated.
+// an entry; a non-delta observation folds nothing and is kept for `listEvents`), so a World whose
+// log was written in that form still reads.
 import { captureHistory, historyChanges, historyEntryTime, historyEntries, historyLength, historyPrefix, inheritedHistory, inheritedHistoryKey, originHead, readHistoryView, replaceHistoryOrigin, saveHistoryView, validateHistoryOrigin } from "./history.js";
 import { dirname, join } from 'node:path';
-import { canonicalStatePath, checkParent, commitParentPin, pinParent, withAncestryLock } from "./ancestry.js";
+import { canonicalStatePath, checkParent, commitParentPin, pinParent, withAncestryLock, withHistoryLock } from "./ancestry.js";
 import { resolveReferences } from "./references.js";
 import { hashFieldValue } from "./hash.js";
 import { worldPaths } from "./storage.js";
@@ -122,7 +122,9 @@ export function readBranchMeta(service, root) {
     return meta;
 }
 export function writeBranchMeta(service, meta, root) {
-    withAncestryLock(() => {
+    // Under the branch's own history lock (a capture of its parent's nests inside it, child before ancestor); only the
+    // pin and the pointer's publication take the coordinator.
+    withHistoryLock(worldPaths(service, root).dir, () => {
         if (meta.parent && (!Number.isInteger(meta.parent.position) || meta.parent.position < 0))
             throw new Error('Invalid branch position');
         const path = branchMetaPath(service, root);
@@ -141,6 +143,7 @@ export function writeBranchMeta(service, meta, root) {
             previousParents.push({ directory: old.parent.directory, generation: old.parent.generation });
         if (previousParents.length)
             meta = { ...meta, previousParents: [...new Map(previousParents.map(p => [p.directory, p])).values()] };
+        let local;
         if (meta.parent && !isUrlParent(meta.parent.at)) {
             const directory = canonicalStatePath(worldPaths(service, meta.parent.at).dir);
             const view = meta.parent.view ?? captureHistory(service, meta.parent.at).view;
@@ -149,9 +152,8 @@ export function writeBranchMeta(service, meta, root) {
                 throw new Error('Composed history view must belong to this branch');
             const descriptor = readHistoryView(viewDirectory, view);
             historyPrefix(descriptor, meta.parent.position);
-            const parent = meta.parent;
-            const generation = pinParent(directory, path, parent.generation);
-            meta = { ...meta, parent: { ...parent, view, at: canonicalStatePath(parent.at), directory, generation } };
+            // the parent the view was captured from: a parent removed or re-created since is refused at the pin
+            local = { directory, view, generation: meta.parent.generation ?? (viewDirectory === directory ? descriptor.owner.generation : undefined) };
         }
         if (meta.parent && isUrlParent(meta.parent.at) && !meta.parent.view) {
             const head = originHead(service, root);
@@ -164,10 +166,17 @@ export function writeBranchMeta(service, meta, root) {
             else
                 throw new Error('Origin has no completed immutable history view');
         }
-        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);
+        withAncestryLock(() => {
+            if (local && meta.parent) {
+                const parent = meta.parent;
+                const generation = pinParent(local.directory, path, local.generation);
+                meta = { ...meta, parent: { ...parent, view: local.view, at: canonicalStatePath(parent.at), directory: local.directory, generation } };
+            }
+            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);
+        });
     });
 }
 /** A v1 observed row as an entry: a delta event folds its `changed.*.after`; anything else folds
@@ -234,7 +243,7 @@ export function appendOriginEntry(entry, root) {
     const path = originLogPath(entry.service, root);
     const store = getActiveWorldStore();
     store.mkdir(dirname(path));
-    return withAncestryLock(() => store.withLock(`${path}.lock`, () => {
+    return withHistoryLock(worldPaths(entry.service, root).dir, () => store.withLock(`${path}.lock`, () => {
         if (readRows(path).some((r) => r.id === entry.id))
             return { appended: false };
         store.append(path, `${JSON.stringify(entry)}\n`);
@@ -386,7 +395,7 @@ export function readTree(service, root, opts = {}) {
 /** The upstream view for observation diffing, without this root's local overlay. Inherited
  *  history keeps its own layout: an ancestor's local writes are part of our pinned base. */
 export function readParentTreeMap(service, root) {
-    return withAncestryLock(() => {
+    return withHistoryLock(worldPaths(service, root).dir, () => {
         const inherited = inheritedHistory(service, root);
         const own = ownParentEntries(service, root);
         return foldHistory([...(inherited ? historyEntries(inherited) : []), ...own], {
@@ -459,12 +468,12 @@ function currentTree(service, root) {
         treeMemos.set(store, memos);
     }
     const slot = `${service}\u0000${root ?? ''}`;
-    // A hit needs no coordinator: a memo is only ever stored from a fold made under it, and while the
+    // 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 };
-    return withAncestryLock(() => {
+    return withHistoryLock(worldPaths(service, root).dir, () => {
         const parentKey = parentKeyOf(service, root);
         const branchKey = statKey(branchLogPath(service, root));
         const held = memos.get(slot);
@@ -548,7 +557,7 @@ export function treeChangesSince(service, root, since) {
     return { stamp, changed: treeResources(present), removed, appended: [...order.keys()].filter((k) => tree.has(k)) };
 }
 function readTreeMapFull(service, root, opts = {}) {
-    return withAncestryLock(() => {
+    return withHistoryLock(worldPaths(service, root).dir, () => {
         if (opts.at !== undefined || opts.view !== undefined) {
             const view = opts.view ? readHistoryView(worldPaths(service, root).dir, opts.view) : captureHistory(service, root).descriptor;
             const at = opts.at ?? historyLength(view.layout);
@@ -603,7 +612,7 @@ function readTreeMapFull(service, root, opts = {}) {
     });
 }
 export function cutCheckpoint(service, root) {
-    return withAncestryLock(() => {
+    return withHistoryLock(worldPaths(service, root).dir, () => {
         dropCheckpoint(service, root);
         const subjects = [...readTreeMap(service, root).values()];
         const inherited = inheritedHistory(service, root);
@@ -691,7 +700,7 @@ export function appendParentEntry(entry, root) {
     const path = parentLogPath(entry.service, root);
     const store = getActiveWorldStore();
     store.mkdir(dirname(path));
-    return withAncestryLock(() => store.withLock(`${path}.lock`, () => {
+    return withHistoryLock(worldPaths(entry.service, root).dir, () => store.withLock(`${path}.lock`, () => {
         let indexes = parentIdIndex.get(store);
         if (!indexes) {
             indexes = new Map();
@@ -724,7 +733,7 @@ export function wholeLog(service, root) {
  * result, never a stop. An unbranched world (no pointer) has nothing to rebase.
  */
 export function rebaseBranch(service, root, opts = {}) {
-    return withAncestryLock(() => {
+    return withHistoryLock(worldPaths(service, root).dir, () => {
         const meta = readBranchMeta(service, root);
         if (!meta?.parent)
             return { moved: false, from: 0, to: 0, conflicts: [] };

package/dist/src/machines.d.ts

@@ -0,0 +1,50 @@
+export type MachineSpec = {
+    name: string;
+    image: string;
+    env?: Record<string, string>;
+    ports?: number[];
+    command?: string[];
+};
+export type MachineRun = {
+    ports: Array<{
+        internal: number;
+        host: number;
+    }>;
+};
+/** A process started in a machine: its pid, and what it writes and how it ends, as they happen. */
+export type MachineProcess = {
+    pid: number;
+    events: AsyncIterable<{
+        stdout?: string;
+    } | {
+        stderr?: string;
+    } | {
+        exit: number;
+    }>;
+};
+export type ExecSpec = {
+    args: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+};
+export type MachinePool = {
+    readonly kind: 'docker' | 'none' | 'fake';
+    /** runs the image; a failure (no container runtime, an image that will not start) rejects with the runtime's message */
+    run(spec: MachineSpec): Promise<MachineRun>;
+    /** starts a process in a running machine; a machine the pool does not run rejects */
+    exec(name: string, spec: ExecSpec): Promise<MachineProcess>;
+    stop(name: string): Promise<void>;
+    remove(name: string): Promise<void>;
+    /** the fake pool's record of what it was asked */
+    readonly asked?: Array<{
+        act: 'run' | 'exec' | 'stop' | 'remove';
+        name: string;
+        spec?: MachineSpec;
+        exec?: ExecSpec;
+    }>;
+};
+export declare const MACHINE_POOL = "_machine_pool";
+export declare const POOL_KINDS: readonly ["docker", "none", "fake"];
+/** The pool of a kind, for a World (`world`: the mark its containers carry). */
+export declare function machinePool(kind: MachinePool['kind'], world?: string): MachinePool;
+export declare function poolFor(service: string, root: string | undefined, kind: MachinePool['kind']): MachinePool;

package/dist/src/machines.js

@@ -0,0 +1,151 @@
+// The World's machine pool (architecture, "Other wires: … machines"): what runs a vendor's customer's image when the
+// vendor is one that runs images (Fly's Machines). It is a platform provider enrolled through the kernel's door
+// `POST /_twin/machine-pool`, recorded in the pack's own tree; a handler reaches it as `ctx.machines`. `docker` runs
+// each machine as a local container with its internal ports published on loopback; `none` runs nothing; `fake`
+// records what it was asked (capability verification). Nothing here runs at module scope, and `node:child_process`
+// is reached only when a docker pool is asked to act.
+import { nodeBuiltin } from "./serve-http.js";
+export const MACHINE_POOL = '_machine_pool';
+export const POOL_KINDS = ['docker', 'none', 'fake'];
+/** A container's name for a machine: the World's prefix, the World's own mark (a machine id repeats across Worlds and
+ *  branches, which mint alike), then the vendor's machine name made safe for docker. */
+const containerName = (world, name) => `volter-world-machine-${world}-${name.replace(/[^A-Za-z0-9_.-]/g, '-')}`;
+// an image's pull is the slow step: a run may take two minutes before the pool gives up; anything else, thirty seconds
+const RUN_TIMEOUT_MS = 120_000;
+const STEP_TIMEOUT_MS = 30_000;
+function dockerPool(world) {
+    // asynchronous, so a pull never holds the World's other requests (or a socket's heartbeats) behind it
+    const docker = (args, timeout = STEP_TIMEOUT_MS) => new Promise((resolve, reject) => {
+        const { execFile } = nodeBuiltin('node:child_process');
+        execFile('docker', args, { encoding: 'utf8', timeout }, (error, stdout, stderr) => (error ? reject(new Error(String(stderr || error.message).trim())) : resolve(String(stdout).trim())));
+    });
+    return {
+        kind: 'docker',
+        async run(spec) {
+            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}`]);
+            const ports = (spec.ports ?? []).flatMap((p) => ['-p', `127.0.0.1::${p}`]);
+            await docker(['run', '-d', '--name', name, ...env, ...ports, spec.image, ...(spec.command ?? [])], RUN_TIMEOUT_MS);
+            const published = [];
+            for (const internal of spec.ports ?? []) {
+                const line = (await docker(['port', name, String(internal)])).split('\n')[0] ?? '';
+                published.push({ internal, host: Number(line.split(':').at(-1)) });
+            }
+            return { ports: published };
+        },
+        async exec(name, spec) {
+            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
+            const child = spawn('docker', ['exec', '-i', ...env, ...(spec.cwd ? ['-w', spec.cwd] : []), containerName(world, name), 'sh', '-c', 'echo "@pid $$"; exec "$@"', 'sh', ...spec.args], { stdio: ['ignore', 'pipe', 'pipe'] });
+            const queue = [];
+            let wake;
+            let done = false;
+            let pid;
+            let head = '';
+            let stderr = '';
+            let settle;
+            const pidKnown = new Promise((resolve, reject) => { settle = { resolve, reject }; child.on('error', reject); });
+            const push = (e) => { queue.push(e); wake?.(); };
+            child.stdout.setEncoding('utf8').on('data', (chunk) => {
+                if (pid === undefined) {
+                    // the pid line may arrive split across chunks: nothing is output until its newline is read
+                    head += chunk;
+                    const nl = head.indexOf('\n');
+                    if (nl < 0)
+                        return;
+                    const m = /^@pid (\d+)$/.exec(head.slice(0, nl));
+                    if (!m) {
+                        push({ stdout: head });
+                        head = '';
+                        return;
+                    }
+                    pid = Number(m[1]);
+                    settle?.resolve(pid);
+                    chunk = head.slice(nl + 1);
+                    head = '';
+                }
+                if (chunk)
+                    push({ stdout: chunk });
+            });
+            child.stderr.setEncoding('utf8').on('data', (chunk) => { if (pid === undefined)
+                stderr += chunk; push({ stderr: chunk }); });
+            child.on('close', (code, signal) => {
+                // a machine the pool does not run (docker exec fails before the shell starts) rejects, with docker's words
+                if (pid === undefined)
+                    settle?.reject(new Error(stderr.trim() || `the process did not start (exit ${code ?? signal})`));
+                // a process ended by a signal exits as a shell reports it: 128 and the signal's number
+                const signals = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 };
+                push({ exit: code ?? (signal ? 128 + (signals[signal] ?? 0) : 0) });
+                done = true;
+                wake?.();
+            });
+            const events = {
+                async *[Symbol.asyncIterator]() {
+                    for (;;) {
+                        while (queue.length) {
+                            const e = queue.shift();
+                            yield e;
+                            if ('exit' in e)
+                                return;
+                        }
+                        if (done)
+                            return;
+                        await new Promise((r) => { wake = r; });
+                    }
+                },
+            };
+            let timer;
+            const timeout = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('the process did not start')), STEP_TIMEOUT_MS); });
+            try {
+                return { pid: await Promise.race([pidKnown, timeout]), events };
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+        async stop(name) { await docker(['stop', containerName(world, name)]).catch(() => undefined); },
+        async remove(name) { await docker(['rm', '-f', containerName(world, name)]).catch(() => undefined); },
+    };
+}
+/** The pool of a kind, for a World (`world`: the mark its containers carry). */
+export function machinePool(kind, world = 'world') {
+    if (kind === 'docker')
+        return dockerPool(world);
+    if (kind === 'fake') {
+        const asked = [];
+        return {
+            kind, asked,
+            async run(spec) { asked.push({ act: 'run', name: spec.name, spec }); return { ports: (spec.ports ?? []).map((internal) => ({ internal, host: 40_000 + internal })) }; },
+            async exec(name, spec) {
+                asked.push({ act: 'exec', name, exec: spec });
+                // a fake process: its pid the count of processes asked, and it ends at once
+                const pid = asked.filter((a) => a.act === 'exec').length + 100;
+                return { pid, events: (async function* () { yield { exit: 0 }; })() };
+            },
+            async stop(name) { asked.push({ act: 'stop', name }); },
+            async remove(name) { asked.push({ act: 'remove', name }); },
+        };
+    }
+    return {
+        kind: 'none', async run() { return { ports: [] }; },
+        async exec() { throw new Error('no machine runs in this World: its machine pool is none'); },
+        async stop() { }, async remove() { },
+    };
+}
+/** A vendor's pool in a World, one per World and kind for the life of the process (a fake pool keeps what it was asked). */
+const pools = new Map();
+export function poolFor(service, root, kind) {
+    const key = `${service}\0${root ?? ''}\0${kind}`;
+    let pool = pools.get(key);
+    if (!pool) {
+        // the World's mark: a short digest of the vendor and the World's tree, so two Worlds' machines never share a name
+        let h = 0;
+        for (const ch of `${service}:${root ?? ''}`)
+            h = (Math.imul(h, 31) + ch.charCodeAt(0)) >>> 0;
+        pool = machinePool(kind, h.toString(16).padStart(8, '0'));
+        pools.set(key, pool);
+    }
+    return pool;
+}

package/dist/src/managed-database.d.ts

@@ -0,0 +1,86 @@
+/** One statement of a batch; `values` travel as bind parameters (text, or null), never in the SQL text. */
+export type Statement = {
+    text: string;
+    values?: ReadonlyArray<string | null>;
+};
+/** What one statement answered: its columns and rows in Postgres's text format, and its command tag. */
+export type StatementResult = {
+    fields: string[];
+    rows: Array<Array<string | null>>;
+    command: string;
+};
+/** A Postgres error as the backend reported it (SQLSTATE and its fields), what a vendor's server passes through. */
+export declare class EngineDatabaseError extends Error {
+    readonly code: string;
+    readonly detail: string | null;
+    readonly hint: string | null;
+    constructor(message: string, fields: {
+        code?: string;
+        detail?: string;
+        hint?: string;
+    });
+}
+/** The World's database cannot be reached: none is bound, or it does not answer. */
+export declare class EngineUnavailableError extends Error {
+    constructor(message: string);
+}
+/** One transaction: as `role` (none: the twin's own login role, the vendor's servers' own work), with transaction-local
+ *  `settings` (`request.jwt.claims`, `search_path`), READ ONLY when `readOnly` (a write is refused by Postgres itself,
+ *  25006), ended with ROLLBACK when `rollback` (a permission probe asked of Postgres and undone). */
+export type Batch = {
+    role?: string;
+    settings?: Record<string, string>;
+    readOnly?: boolean;
+    rollback?: boolean;
+    statements: Statement[];
+};
+export interface ManagedDatabase {
+    /** Whether the World binds a database at all (a World with none refuses every batch). */
+    readonly bound: boolean;
+    /** One transaction as one pipeline and one Sync; the answer is the batch's own statements', in order. */
+    batch(batch: Batch): Promise<StatementResult[]>;
+    /** A whole SQL script as one simple Query (a vendor's migrations, several statements to a file). */
+    script(text: string): Promise<void>;
+}
+/** The transaction-local setting every batch a handler makes carries: the World clock at the call (ctx.occurredAt). */
+export declare const WORLD_CLOCK_SETTING = "volter.world_clock";
+/** The World clock inside the database, for the schemas a vendor lays (its migrations stamp rows with Postgres's
+ *  `now()`, which reads the wall clock): `volter.now()`, the World clock the batch set or the wall clock where none is
+ *  set, and every column default in `schemas` that reads `now()` or `CURRENT_TIMESTAMP` (alone or inside an expression,
+ *  GoTrue's `timezone('utc', now())`) rewritten to read it. Run after the schemas are laid; running it again changes
+ *  nothing. A trigger or function that calls `now()` itself is the pack's to redefine. */
+export declare function worldClockSql(schemas: string[]): string;
+/** Quote an identifier the way Postgres's quote_ident does for a name that needs it. */
+export declare function quoteIdent(name: string): string;
+/** The part of a Postgres driver the kernel uses: node-postgres's (`pg`) Pool and its clients. */
+type PgClient = {
+    query(query: unknown): unknown;
+    release(error?: Error): void;
+};
+type PgPool = {
+    connect(): Promise<PgClient>;
+    end(): Promise<void>;
+    on(event: 'error', listener: (error: Error) => void): unknown;
+};
+export type DatabaseDriver = {
+    Pool: new (config: {
+        connectionString: string;
+        max: number;
+        idleTimeoutMillis: number;
+        connectionTimeoutMillis: number;
+    }) => PgPool;
+};
+/** A Postgres driver a host registers in place of node-postgres. */
+export declare function useDatabaseDriver(given: DatabaseDriver): void;
+/** The World's Postgres at `url` (the runtime's binding, never the environment); with `readOnly`, every transaction is
+ *  READ ONLY whatever the batch asks (a read-only twin or request: Postgres itself refuses a write, 25006); with `clock`,
+ *  every batch carries the World clock as `volter.world_clock`. */
+export declare function managedDatabase(url: string, options?: {
+    readOnly?: boolean;
+    clock?: string;
+}): ManagedDatabase;
+/** A handler's database when the World binds none: every use is the refusal naming what to add. */
+export declare function unboundDatabase(service: string): ManagedDatabase;
+/** Close every connection this process holds (a test's teardown; a served twin's connections end with it). */
+export declare function closeManagedDatabases(): Promise<void>;
+export {};