@volter/world-core 2.0.0

package/src/history.ts

@@ -0,0 +1,246 @@
+// Immutable views over shared append-only segments. A position is meaningful within a view.
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { resolveReferences } from './references.ts';
+import { canonicalJson } from './hash.ts';
+import { canonicalStatePath, checkParent, commitParentPin, pinParent, stateGeneration, withAncestryLock } from './ancestry.ts';
+import { getActiveWorldStore } from './world-store.ts';
+import { worldPaths } from './storage.ts';
+import { aliasesFrom, foldHistory, branchEntries, isUrlParent, readBranchMeta, toEntry, type Entry } from './log.ts';
+
+export type HistoryLayout = { base?: HistoryLayout; parent: number; branch: number };
+type Segment = { directory: string; generation: string; file: 'events.jsonl' | 'actions.jsonl' | 'origin.jsonl'; start: number; count: number; digest: string };
+export type HistoryOrigin = { at: string; directory: string; generation: string; view: string; position: number; remoteView?: string; depth: number; incomplete?: boolean };
+export type HistoryView = { version: 1; owner: { directory: string; generation: string }; layout: HistoryLayout; segments: Segment[]; origin?: HistoryOrigin };
+export type HistoryReference = { view: string; position: number };
+export function validateHistoryOrigin(origin: HistoryOrigin, layout?: HistoryLayout): void {
+  if (!origin || typeof origin.at !== 'string' || !origin.at || typeof origin.directory !== 'string' || !origin.directory || typeof origin.generation !== 'string' || !origin.generation || !/^[a-f0-9]{64}$/.test(origin.view) || (origin.remoteView !== undefined && !/^[a-f0-9]{64}$/.test(origin.remoteView)) || !Number.isSafeInteger(origin.position) || origin.position < 0 || !Number.isSafeInteger(origin.depth) || origin.depth < 0 || origin.depth > 128 || (origin.incomplete !== undefined && typeof origin.incomplete !== 'boolean')) throw new Error('Invalid tracked origin metadata');
+  if (layout) {
+    let layer = layout;
+    for (let i = 0; i < origin.depth; i++) { if (!layer.base) throw new Error('Tracked origin layer is absent from the history layout'); layer = layer.base; }
+    if (!origin.incomplete && historyLength(layer) !== origin.position) throw new Error('Tracked origin position does not match its history layer');
+  }
+}
+export const historyEntryTime = (entry: Entry): number => Date.parse(entry.receipt?.at ?? entry.occurredAt);
+export const historyDigest = (value: unknown): string => createHash('sha256').update(canonicalJson(value)).digest('hex');
+export function historyLength(layout: HistoryLayout, depth = 0): number {
+  if (!layout || depth > 128 || !Number.isSafeInteger(layout.parent) || layout.parent < 0 || !Number.isSafeInteger(layout.branch) || layout.branch < 0) throw new Error('Invalid history layout');
+  const length = (layout.base ? historyLength(layout.base, depth + 1) : 0) + layout.parent + layout.branch;
+  if (!Number.isSafeInteger(length)) throw new Error('History position exceeds the safe integer range');
+  return length;
+}
+const viewPath = (directory: string, id: string) => {
+  if (!/^[a-f0-9]{64}$/.test(id)) throw new Error('Invalid history view identity');
+  return join(directory, 'views', `${id}.json`);
+};
+function rows(directory: string, file: Segment['file']): Entry[] {
+  return getActiveWorldStore().readLines(join(directory, file)).filter(line => line.trim()).map(line => toEntry(JSON.parse(line)));
+}
+function sliceLayout(layout: HistoryLayout, at: number): HistoryLayout {
+  const base = layout.base ? historyLength(layout.base) : 0;
+  return { ...(layout.base ? { base: sliceLayout(layout.base, Math.min(at, base)) } : {}), parent: Math.min(Math.max(0, at - base), layout.parent), branch: Math.min(Math.max(0, at - base - layout.parent), layout.branch) };
+}
+export function readHistoryView(directory: string, id: string): HistoryView {
+  const raw = getActiveWorldStore().read(viewPath(directory, id));
+  if (raw === null) throw new Error(`Missing retained history view ${id}`);
+  const { dependencies: _dependencies, ...view } = JSON.parse(raw) as HistoryView & { dependencies?: unknown };
+  if (view.version !== 1 || historyDigest({ ...view, dependencies: _dependencies }) !== id) throw new Error(`Invalid retained history view ${id}`);
+  historyLength(view.layout);
+  if (view.origin) validateHistoryOrigin(view.origin, view.layout);
+  if (!view.owner || typeof view.owner.directory !== 'string' || typeof view.owner.generation !== 'string' || !Array.isArray(view.segments) || view.segments.some(s => typeof s.directory !== 'string' || typeof s.generation !== 'string' || !['events.jsonl', 'actions.jsonl', 'origin.jsonl'].includes(s.file) || !Number.isSafeInteger(s.start) || s.start < 0 || !Number.isSafeInteger(s.count) || s.count < 0 || !/^[a-f0-9]{64}$/.test(s.digest))) throw new Error('Invalid history segments');
+  return view;
+}
+export function historyEntries(view: HistoryView): Entry[] {
+  checkParent(view.owner.directory, view.owner.generation);
+  const entries = view.segments.flatMap(span => {
+    checkParent(span.directory, span.generation);
+    const entries = rows(span.directory, span.file).slice(span.start, span.start + span.count);
+    if (entries.length !== span.count || historyDigest(entries) !== span.digest) throw new Error(`Retained history prefix was changed: ${span.directory}/${span.file}`);
+    return entries;
+  });
+  if (entries.length !== historyLength(view.layout)) throw new Error('Invalid history view layout');
+  return entries;
+}
+export function historyPrefix(view: HistoryView, at: number): HistoryView {
+  if (!Number.isInteger(at) || at < 0 || at > historyLength(view.layout)) throw new Error(`Invalid history position ${at}`);
+  historyEntries(view);
+  let left = at;
+  const segments: Segment[] = [];
+  for (const span of view.segments) {
+    if (left === 0) break;
+    const count = Math.min(left, span.count);
+    segments.push(count === span.count ? span : { ...span, count, digest: historyDigest(rows(span.directory, span.file).slice(span.start, span.start + count)) });
+    left -= count;
+  }
+  return { ...view, layout: sliceLayout(view.layout, at), segments, ...(view.origin && at < view.origin.position ? { origin: { ...view.origin, incomplete: true } } : {}) };
+}
+export function saveHistoryView(directory: string, view: HistoryView): string {
+  return withAncestryLock(() => {
+    if (view.origin) validateHistoryOrigin(view.origin, view.layout);
+    const dependencies = [...new Map([view.owner, ...view.segments, ...(view.origin ? [view.origin] : [])].map(s => [s.directory, { directory: s.directory, generation: s.generation }])).values()];
+    const id = historyDigest({ ...view, dependencies }); const file = viewPath(directory, id);
+    if (getActiveWorldStore().exists(file)) return id;
+    for (const dependency of dependencies) pinParent(dependency.directory, file, dependency.generation);
+    getActiveWorldStore().writeAtomic(file, JSON.stringify({ ...view, dependencies }));
+    for (const dependency of dependencies) commitParentPin(dependency.directory, file);
+    return id;
+  });
+}
+/** 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: string, root?: string): string {
+  const parent = readBranchMeta(service, root)?.parent;
+  if (!parent?.view) return '';
+  const store = getActiveWorldStore();
+  const fact = (path: string): string => { const st = store.stat(path); return st ? `${st.size}:${st.mtimeMs}` : '-'; };
+  const directory = parent.viewDirectory ?? (isUrlParent(parent.at) ? worldPaths(service, root).dir : worldPaths(service, parent.at).dir);
+  let raw: string | null; let at: string;
+  try { at = viewPath(directory, parent.view); raw = store.read(at); } catch { return 'invalid-view'; }
+  if (raw === null) return 'missing-view';
+  const view = JSON.parse(raw) as HistoryView;
+  const directories = new Set<string>([view.owner?.directory ?? '', ...(view.segments ?? []).map((sp) => sp.directory)]);
+  if (!isUrlParent(parent.at)) directories.add(worldPaths(service, parent.at).dir);
+  const files = [...new Set((view.segments ?? []).map((sp) => join(sp.directory, sp.file)))].sort();
+  return `${at}=${fact(at)};${files.map((f) => `${f}=${fact(f)}`).join(',')};${[...directories].sort().map((d) => `${d}=${fact(join(d, 'ancestry.json'))}`).join(',')}`;
+}
+export function inheritedHistory(service: string, root?: string): HistoryView | undefined {
+  const parent = readBranchMeta(service, root)?.parent;
+  if (!parent) return undefined;
+  if (!parent.view) throw new Error('Branch has no immutable history view; recreate this disposable World');
+  const directory = parent.viewDirectory ?? (isUrlParent(parent.at) ? worldPaths(service, root).dir : worldPaths(service, parent.at).dir);
+  if (parent.viewDirectory && canonicalStatePath(parent.viewDirectory) !== canonicalStatePath(worldPaths(service, root).dir)) throw new Error('Composed history view must belong to this branch');
+  if (!isUrlParent(parent.at)) checkParent(worldPaths(service, parent.at).dir, parent.generation);
+  return historyPrefix(readHistoryView(directory, parent.view), parent.position);
+}
+/** Capture under the same coordinator as append and complete observation batches. */
+export function captureHistory(service: string, root?: string): { view: string; position: number; descriptor: HistoryView } {
+  return withAncestryLock(() => {
+    const directory = canonicalStatePath(worldPaths(service, root).dir);
+    getActiveWorldStore().mkdir(directory);
+    if (!getActiveWorldStore().exists(join(directory, 'history-format.json'))) getActiveWorldStore().writeAtomic(join(directory, 'history-format.json'), '{"version":1}');
+    const generation = stateGeneration(directory);
+    const inherited = inheritedHistory(service, root);
+    const parent = rows(directory, 'events.jsonl'); const branch = branchEntries(service, root);
+    const origin = readBranchMeta(service, root)?.origin;
+    const descriptor: HistoryView = { version: 1, owner: { directory, generation }, layout: { ...(inherited ? { base: inherited.layout } : {}), parent: parent.length, branch: branch.length }, segments: [...(inherited?.segments ?? [])], ...(origin ? { origin: { ...origin, depth: origin.depth + 1 } } : {}) };
+    for (const [file, entries] of [['events.jsonl', parent], ['actions.jsonl', branch]] as const) {
+      if (entries.length) descriptor.segments.push({ directory, generation, file, start: 0, count: entries.length, digest: historyDigest(entries) });
+    }
+    return { view: saveHistoryView(directory, descriptor), position: historyLength(descriptor.layout), descriptor };
+  });
+}
+export function originHead(service: string, root?: string): { view: string; remoteView: string } | null {
+  const raw = getActiveWorldStore().read(join(worldPaths(service, root).dir, 'origin-head.json'));
+  return raw === null ? null : JSON.parse(raw);
+}
+/** A complete remote view shares cached rows by content, never by mutable offsets or entry ID. */
+export function publishOriginHistory(service: string, root: string, remoteView: string, layout: HistoryLayout, entries: Entry[]): { view: string; appended: number } {
+  return withAncestryLock(() => {
+    if (entries.length !== historyLength(layout)) throw new Error('Incomplete origin history view');
+    const directory = canonicalStatePath(worldPaths(service, root).dir); const store = getActiveWorldStore(); store.mkdir(directory);
+    if (!store.exists(join(directory, 'history-format.json'))) store.writeAtomic(join(directory, 'history-format.json'), '{"version":1}');
+    const generation = stateGeneration(directory); const cached = rows(directory, 'origin.jsonl');
+    const index = new Map(cached.map((entry, i) => [historyDigest(entry), i]));
+    const segments: Segment[] = []; let appended = 0;
+    for (const entry of entries) {
+      const key = historyDigest(entry); let start = index.get(key);
+      if (start === undefined) { start = cached.length; store.append(join(directory, 'origin.jsonl'), `${JSON.stringify(entry)}\n`); cached.push(entry); index.set(key, start); appended++; }
+      const last = segments.at(-1);
+      if (last && last.start + last.count === start) { last.count++; }
+      else segments.push({ directory, generation, file: 'origin.jsonl', start, count: 1, digest: historyDigest([entry]) });
+    }
+    for (const span of segments) span.digest = historyDigest(cached.slice(span.start, span.start + span.count));
+    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 };
+  });
+}
+
+/** A changeset binds the complete inherited view, including this root's observations. */
+export function captureParentHistory(service: string, root?: string): HistoryReference {
+  return withAncestryLock(() => {
+    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 };
+  });
+}
+/** Compare evaluated views, so removals, reordered rows and layout changes count as drift. */
+export function historyChanges(service: string, before: HistoryView, after: HistoryView): Entry[] {
+  const oldEntries = historyEntries(before); const newEntries = historyEntries(after);
+  const oldTree = foldHistory(oldEntries, before.layout, service); const newTree = foldHistory(newEntries, after.layout, service);
+  const aliases = aliasesFrom(newEntries); const changes: Entry[] = [];
+  for (const key of new Set([...oldTree.keys(), ...newTree.keys()])) {
+    const old = oldTree.get(key); const next = newTree.get(key) ?? (old && aliases.has(key) ? newTree.get(`${old.type}:${aliases.get(key)}`) : undefined);
+    const fields: Record<string, unknown> = {};
+    const oldFields = old ? resolveReferences(service, old.type, old.fields, aliases) : {};
+    for (const field of new Set([...Object.keys(oldFields), ...Object.keys(next?.fields ?? {})])) if (canonicalJson(oldFields[field]) !== canonicalJson(next?.fields[field])) fields[field] = next?.fields[field];
+    if (old && !next) fields.deleted = true;
+    if (!Object.keys(fields).length) continue;
+    const subject = old ?? next!;
+    changes.push({ id: `view-delta:${historyDigest({ key, fields })}`, service, op: 'set', subject: { type: subject.type, id: subject.id }, occurredAt: next?.updatedAt ?? old!.updatedAt, fields });
+  }
+  return changes;
+}
+
+/** A timestamp can select across layers; represent it as a view, never a misleading offset. */
+export function historyAtInstant(service: string, instant: string, root?: string, selectedView?: string): HistoryReference {
+  return withAncestryLock(() => {
+    const stamp = Date.parse(instant); if (!Number.isFinite(stamp)) throw new Error('Invalid history instant');
+    const directory = worldPaths(service, root).dir;
+    const source = selectedView ? readHistoryView(directory, selectedView) : captureHistory(service, root).descriptor;
+    const entries = historyEntries(source); const keep = entries.map(e => historyEntryTime(e) <= stamp);
+    // A contiguous observation batch is one indivisible look.
+    for (let i = 0; i < entries.length;) {
+      let end = i + 1; while (entries[i]?.batch && end < entries.length && entries[end]?.batch === entries[i]?.batch) end++;
+      if (keep.slice(i, end).some(Boolean)) for (let j = i; j < end; j++) keep[j] = true;
+      i = end;
+    }
+    let offset = 0;
+    const layoutOf = (layout: HistoryLayout): HistoryLayout => {
+      const base = layout.base ? layoutOf(layout.base) : undefined;
+      const parent = keep.slice(offset, offset + layout.parent).filter(Boolean).length; offset += layout.parent;
+      const branch = keep.slice(offset, offset + layout.branch).filter(Boolean).length; offset += layout.branch;
+      return { ...(base ? { base } : {}), parent, branch };
+    };
+    const layout = layoutOf(source.layout); const segments: Segment[] = []; offset = 0;
+    for (const span of source.segments) {
+      for (let i = 0; i < span.count;) {
+        if (!keep[offset + i]) { i++; continue; }
+        const start = i; while (i < span.count && keep[offset + i]) i++;
+        segments.push({ ...span, start: span.start + start, count: i - start, digest: historyDigest(entries.slice(offset + start, offset + i)) });
+      }
+      offset += span.count;
+    }
+    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) };
+  });
+}
+
+/** Replace only the tracked origin layer; inherited local layers keep their exact projection order. */
+export function replaceHistoryOrigin(previous: HistoryView, origin: HistoryOrigin, next: HistoryOrigin): HistoryView {
+  let layer = previous.layout;
+  for (let depth = 0; depth < origin.depth; depth++) {
+    if (!layer.base) throw new Error('Tracked origin layer is absent from the inherited view');
+    layer = layer.base;
+  }
+  const count = historyLength(layer);
+  const before = historyEntries(previous);
+  checkParent(origin.directory, origin.generation);
+  if (!origin.incomplete) {
+    const expected = historyPrefix(readHistoryView(origin.directory, origin.view), origin.position);
+    if (count !== origin.position || historyDigest(before.slice(0, count)) !== historyDigest(historyEntries(expected)) || historyDigest(layer) !== historyDigest(expected.layout)) throw new Error('Tracked origin does not match the inherited history layer');
+  }
+  checkParent(next.directory, next.generation);
+  const replacement = historyPrefix(readHistoryView(next.directory, next.view), next.position);
+  const suffix: Segment[] = [];
+  let skip = count;
+  for (const span of previous.segments) {
+    if (skip >= span.count) { skip -= span.count; continue; }
+    suffix.push(skip === 0 ? span : { ...span, start: span.start + skip, count: span.count - skip, digest: historyDigest(rows(span.directory, span.file).slice(span.start + skip, span.start + span.count)) });
+    skip = 0;
+  }
+  const layoutOf = (layout: HistoryLayout, depth: number): HistoryLayout => depth === 0 ? replacement.layout : { ...layout, base: layoutOf(layout.base!, depth - 1) };
+  return { ...previous, layout: layoutOf(previous.layout, origin.depth), segments: [...replacement.segments, ...suffix], origin: { ...next, depth: origin.depth } };
+}

package/src/index.ts

@@ -0,0 +1,323 @@
+// @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.ts';
+export type { PackTransport, PullPosture, PullTrigger, PullVendor, RoundTripWrite, TwinPack } from './packRegistry.ts';
+// 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.ts';
+export { WORLD_CLOCK_ENV, worldNow } from './world-clock.ts';
+export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.ts';
+export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, twinPublicBase } from './twin-fetch.ts';
+export { compileSurface, createDerivedFetch, matchOperation } from './derived.ts';
+export type { DerivedCall, DerivedCoreOutcome, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface } from './derived.ts';
+export { bindSemantics, coreFor, crossCutting, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.ts';
+export type { Actor, CoreScope, DerivedManifest, ErrorSpec, FieldRule, ResourceDecl, ScreenDecl, Semantics, SemanticsContext, StateField, Transition, TransitionObserver } from './derived-core.ts';
+export type { RemoteExecute, RemoteExecuteRequest, RemoteExecuteResponse } from './remote-execute.ts';
+export type { TwinFetchAdapterConfig, TwinFetchHandlerRequest, TwinFetchHandlerResult, TwinStream, TwinStreamConnection, TwinStreamSink } from './twin-fetch.ts';
+export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.ts';
+export { emitTwinEvent, eventSubscriptionMatches, listEmittable, runEmitCli } from './emit.ts';
+export type { EmitDeliveryResult, EmitEndpoint, EmitReport, EmittableEvent, SynthesizedDelivery, TwinEmitter } from './emit.ts';
+// 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.ts';
+export type {
+  RateBudgetDeclaration,
+  RateBudgetErrorKind,
+  RateBudgetOptions,
+  RateBudgetPolicy,
+  RateBudgetReservation,
+  RateBudgetSnapshot,
+  RateBudgetWeightRule,
+} from './rateBudget.ts';
+export {
+  GenericWorldStateSchema,
+  WorldActorSchema,
+  WorldExternalRefSchema,
+  WorldServiceEventSchema,
+  WorldSubjectSchema,
+} from './schemas.ts';
+// 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.ts';
+export type {
+  WorldConfig,
+  WorldServiceConfig,
+} from './worldConfig.ts';
+export {
+  DELTA_TYPE_SUFFIX,
+  diffSubjectFields,
+  hashFieldValue,
+  subjectKey, deltaAfterFields } from './hash.ts';
+export type {
+  FieldChange,
+  SubjectFields,
+} from './hash.ts';
+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,
+} from './storage.ts';
+export type {
+  AppendEventResult,
+  CommitQueuedEventsResult,
+  GenericWorldState,
+  EnqueueEventResult,
+  QueuedWorldServiceEvent,
+  WorldPaths,
+  WorldReducer,
+  WorldServiceEvent,
+} from './types.ts';
+export type { ScrubResult } from './storage.ts';
+// 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.ts';
+export type { WorldStore, WorldStat, HydrationSource, HydrationSink } from './world-store.ts';
+export type { CheckLoader } from './head.ts';
+export { SqlWorldStore } from './world-store-sql.ts';
+export type { SqlExec } from './world-store-sql.ts';
+// 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.ts';
+export type { BlobStore } from './blob-store.ts';
+export {
+  applyTwinWrite,
+  applyTwinWriteAtomic,
+  createTwinServer,
+  journalTwinRequest,
+  twinRequestCredentials,
+  readTwinRequestJournal,
+  resolveTwinRead,
+  twinRequestJournalEnabled,
+  twinRequestJournalPath,
+  twinResources,
+} from './serve.ts';
+export type {
+  AtomicTwinWriteDecision,
+  TwinRequestJournalEntry,
+  TwinResource,
+  TwinWriteInput,
+  TwinWriteResult,
+} from './serve.ts';
+export { createTwinProxy } from './proxy.ts';
+export type { TwinProxy, TwinProxyOptions, VendorRoute } from './proxy.ts';
+export {
+  forkTwin,
+  isFork,
+  readForkMeta,
+} from './fork.ts';
+export type { ForkMeta } from './fork.ts';
+export {
+  appendAction,
+  appendTransactionCommit,
+  checkPrecondition,
+  confirmAction,
+  listActions,
+  listTransactionCommits,
+  pendingActions,
+  pushablePendingActions,
+  isTwinBookkeeping,
+  pendingTransactionCommits,
+  projectResources,
+  revertAction,
+  TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from './actions.ts';
+export type {
+  ActionProjection,
+  ProjectedDelivery,
+  ProjectedResource,
+  ProjectedResourcePatch,
+  ProjectedResourceRef,
+  TwinAction,
+  TwinActionOp,
+  TwinActionPrecondition,
+  TwinActionPreconditionOp,
+  TwinActionRevertSpec,
+  TwinTransactionCommit,
+  TwinTransactionCommitOp,
+  TwinTransactionPrecondition,
+  TwinTransactionRevertSpec,
+} from './actions.ts';
+// ── 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,
+  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.ts';
+export type {
+  ApplyReceipt,
+  RebaseActionResult,
+  RebaseReport,
+  RebaseTarget,
+  Changeset,
+  ChangesetAction,
+  ChangesetApplication,
+  CompensationEntry,
+  ChangesetApproval,
+  ChangesetReadiness,
+  ChangesetVerification,
+  ChangesetVerifier,
+  ChangesetVerifierResult,
+  LedgerDelta,
+  LedgerPosition,
+  LedgerRef,
+  ReplayActionResult,
+  ReplayReport,
+  ReplayTarget,
+  VendorSummary,
+  WorldMarker,
+} from './changeset.ts';
+export { getActivePackAssets, setActivePackAssets, packAsset, assetContentType, confinedAssetPath, LocalPackAssets, BindingPackAssets, type PackAssetStore } from './pack-assets.ts';
+
+// The git plane (contract "The git plane is a kernel library"): objects, packs, refs, smart HTTP.
+export * as git from './git/index.ts';
+
+// 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.ts';
+
+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.ts';
+export type { BranchMeta, Entry, EntryOp, Receipt } from './log.ts';
+export { sealCredential, openSealedCredential, MemoryCredentialStorage } from './credential.ts';
+export type { CredentialPayload, CredentialStorage, SealedCredential } from './credential.ts';
+export { validateRemoteOrigin, buildRemoteExecute, type CredentialCustody } from './executor.ts';
+export type { TwinAuthStrategy } from './executor.ts';
+export { clearRoot, authStrategyFor, clearStateSystems, NO_SECRETS_CHECK, readRoot, registerAuthStrategy, registerStateSystem, rootPath, runChecks, stateSystemFor, writeRoot } from './state-system.ts';
+export type { Check, CheckVerdict, DeployPolicy, RootConfig, StateSystemAdapters } from './state-system.ts';
+export { observeAppends } from './actions.ts';
+export { appendActionIfAbsent, appendActionOccurrence } from './actions.ts';
+
+// 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, rootCustody, sealingKey, setCheckLoader, setSealingKeySource, userKek, userKekPath, vendorOf, worldRootOf, RefusedWriteError, VendorWriteError, HeadError } from './head.ts';
+export type { BoundRoot, DeployReport, Head, PerformAction, PerformContext, PushOutcome } from './head.ts';
+export { observeResource, observeResources, collectObservations, foldObservations } from './observe.ts';
+export type { ObservedResource, ObserveReport, Observation } from './observe.ts';
+export { readTreeMap, readParentTreeMap, treeStamp, treeChangesSince, originEntries, appendOriginEntry, originLogPath, isUrlParent, parentPosition, positionAt, splitsBatch, assertBatchBoundary } from './log.ts';
+
+// 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.ts';
+export { referenceField, registerReferences, packReferences, resolveReferences, type ReferenceDeclaration } from './references.ts';
+// the HTTP server seam: the one place the serve path meets the runtime (Bun or Node)
+export { serveHttp, nodeBuiltin, WORLD_BOOT_PATH, type HttpServer, type ServeHttpOptions, type HttpHandler } from './serve-http.ts';
+// 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.ts';
+export { bundleClient } from './client-bundle.ts';
+// 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.ts';
+
+export { readResourceBlob, readResourceBlobRange, resourceBlobSize, resourceChain } from './resource-blob.ts';
+export { mirrorShellUnder } from './mirror-shell.ts';
+
+export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, withStateRemoval } from './ancestry.ts';
+
+export { captureHistory, captureParentHistory, historyChanges, historyAtInstant, historyDigest, historyEntries, historyLength, historyPrefix, inheritedHistory, originHead, publishOriginHistory, readHistoryView } from './history.ts';
+export type { HistoryView, HistoryLayout, HistoryReference, HistoryOrigin } from './history.ts';
+export { foldHistory } from './log.ts';
+export { volterHome } from './volter-home.ts';

package/src/lifecycle.ts

@@ -0,0 +1,8 @@
+// Bun busy-spins on a top-level promise that can never settle when no other event-loop handle
+// remains. Twin CLIs use this timer-backed hold after starting their servers so an unexpectedly
+// closed server cannot turn an otherwise idle process into a full-core loop.
+const IDLE_SLEEP_MS = 86_400_000;
+
+export async function keepProcessAlive(): Promise<never> {
+  while (true) await new Promise<void>(resolve => setTimeout(resolve, IDLE_SLEEP_MS));
+}