@volter/world-core 2.0.36 → 3.0.0

package/src/protobuf.ts

@@ -0,0 +1,251 @@
+// PROTOCOL BUFFERS (architecture, "Other wires": the gRPC wire): a message's proto3 JSON form
+// (https://protobuf.dev/programming-guides/json/) to its binary encoding (https://protobuf.dev/programming-guides/encoding/)
+// and back, over the schema the derive writes for a proto unit (`src/generated/proto.gen.json`, twin-standard's
+// `protoSchema`). A handler reads and answers the JSON form; the wire carries the bytes. The JSON form names a field by
+// its JSON name, writes 64-bit integers as decimal strings, bytes as base64, enums by their value names, a map as an
+// object, and leaves out a field holding its default; `google.protobuf.Timestamp`, `Duration`, the wrappers and `Empty`
+// take their own JSON forms. Importing it does nothing.
+
+type Row = Record<string, unknown>;
+export type ProtoField = { name: string; json: string; number: number; type: string; kind: 'scalar' | 'message' | 'enum'; repeated?: true; map?: { key: string; value: string; valueKind: 'scalar' | 'message' | 'enum' } };
+export type ProtoSchema = {
+  messages: Record<string, ProtoField[]>;
+  enums: Record<string, Record<string, number>>;
+  rpcs: Record<string, { operation: string; request: string; response: string; serverStreams?: true; clientStreams?: true }>;
+};
+
+const VARINT = new Set(['int32', 'int64', 'uint32', 'uint64', 'sint32', 'sint64', 'bool']);
+const FIXED64 = new Set(['fixed64', 'sfixed64', 'double']);
+const FIXED32 = new Set(['fixed32', 'sfixed32', 'float']);
+const LONG = new Set(['int64', 'uint64', 'sint64', 'fixed64', 'sfixed64']);
+const WRAPPERS: Record<string, string> = {
+  'google.protobuf.DoubleValue': 'double', 'google.protobuf.FloatValue': 'float', 'google.protobuf.Int64Value': 'int64',
+  'google.protobuf.UInt64Value': 'uint64', 'google.protobuf.Int32Value': 'int32', 'google.protobuf.UInt32Value': 'uint32',
+  'google.protobuf.BoolValue': 'bool', 'google.protobuf.StringValue': 'string', 'google.protobuf.BytesValue': 'bytes',
+};
+const ENC = new TextEncoder();
+const DEC = new TextDecoder();
+
+const wireOf = (f: { type: string; kind: string }): number =>
+  f.kind === 'enum' || VARINT.has(f.type) ? 0 : FIXED64.has(f.type) ? 1 : FIXED32.has(f.type) ? 5 : 2;
+
+// ── writing ────────────────────────────────────────────────────────────────────────────────────
+
+class Writer {
+  private parts: number[] = [];
+  varint(v: bigint): void {
+    let x = BigInt.asUintN(64, v);
+    while (x >= 0x80n) { this.parts.push(Number((x & 0x7fn) | 0x80n)); x >>= 7n; }
+    this.parts.push(Number(x));
+  }
+  tag(number: number, wire: number): void { this.varint((BigInt(number) << 3n) | BigInt(wire)); }
+  bytes(b: Uint8Array): void { this.varint(BigInt(b.length)); for (const x of b) this.parts.push(x); }
+  raw(b: Uint8Array): void { for (const x of b) this.parts.push(x); }
+  fixed(v: bigint | number, size: 4 | 8, float = false): void {
+    const buf = new DataView(new ArrayBuffer(size));
+    if (float) { if (size === 8) buf.setFloat64(0, Number(v), true); else buf.setFloat32(0, Number(v), true); }
+    else if (size === 8) buf.setBigUint64(0, BigInt.asUintN(64, BigInt(v)), true); else buf.setUint32(0, Number(BigInt.asUintN(32, BigInt(v))), true);
+    for (const x of new Uint8Array(buf.buffer)) this.parts.push(x);
+  }
+  done(): Uint8Array { return Uint8Array.from(this.parts); }
+}
+
+const zigzag = (v: bigint, bits: 32 | 64): bigint => (v << 1n) ^ (v >> BigInt(bits - 1));
+const b64decode = (s: string): Uint8Array => Uint8Array.from(atob(s.replace(/-/g, '+').replace(/_/g, '/')), (c) => c.charCodeAt(0));
+const b64encode = (b: Uint8Array): string => btoa(Array.from(b, (x) => String.fromCharCode(x)).join(''));
+
+function enumNumber(schema: ProtoSchema, type: string, v: unknown): number {
+  if (typeof v === 'number') return v;
+  const n = schema.enums[type]?.[String(v)];
+  if (n === undefined) throw new Error(`protobuf: ${String(v)} is not a value of ${type}`);
+  return n;
+}
+
+function writeScalar(w: Writer, type: string, v: unknown): void {
+  switch (type) {
+    case 'int32': case 'int64': case 'uint32': case 'uint64': w.varint(BigInt(v as string | number)); break;
+    case 'sint32': w.varint(zigzag(BigInt(v as number), 32)); break;
+    case 'sint64': w.varint(zigzag(BigInt(v as string), 64)); break;
+    case 'bool': w.varint(v ? 1n : 0n); break;
+    case 'fixed64': case 'sfixed64': w.fixed(BigInt(v as string), 8); break;
+    case 'double': w.fixed(Number(v), 8, true); break;
+    case 'fixed32': case 'sfixed32': w.fixed(Number(v), 4); break;
+    case 'float': w.fixed(Number(v), 4, true); break;
+    default: throw new Error(`protobuf: ${type} is not a packable scalar`);
+  }
+}
+
+/** A well-known type's JSON form as the message it stands for, or undefined for any other type. */
+function wellKnownIn(type: string, v: unknown): Row | undefined {
+  if (type === 'google.protobuf.Timestamp' && typeof v === 'string') {
+    const ms = Date.parse(v);
+    const frac = /\.(\d+)/.exec(v)?.[1] ?? '';
+    return { seconds: String(Math.floor(ms / 1000)), nanos: Number(frac.padEnd(9, '0').slice(0, 9)) };
+  }
+  if (type === 'google.protobuf.Duration' && typeof v === 'string') {
+    const [s, f = ''] = v.replace(/s$/, '').split('.');
+    return { seconds: s, nanos: (s!.startsWith('-') ? -1 : 1) * Number(f.padEnd(9, '0').slice(0, 9)) };
+  }
+  if (WRAPPERS[type] !== undefined) return { value: v };
+  return undefined;
+}
+
+function writeValue(schema: ProtoSchema, w: Writer, f: { number: number; type: string; kind: string }, v: unknown): void {
+  if (f.kind === 'message') { w.tag(f.number, 2); w.bytes(encodeMessage(schema, f.type, v)); return; }
+  if (f.kind === 'enum') { w.tag(f.number, 0); w.varint(BigInt(enumNumber(schema, f.type, v))); return; }
+  if (f.type === 'string') { w.tag(f.number, 2); w.bytes(ENC.encode(String(v))); return; }
+  if (f.type === 'bytes') { w.tag(f.number, 2); w.bytes(typeof v === 'string' ? b64decode(v) : (v as Uint8Array)); return; }
+  w.tag(f.number, wireOf(f)); writeScalar(w, f.type, v);
+}
+
+/** A message's JSON form (proto3 JSON) as its binary encoding. */
+export function encodeMessage(schema: ProtoSchema, type: string, value: unknown): Uint8Array {
+  const known = wellKnownIn(type, value);
+  const v = (known ?? (value && typeof value === 'object' ? value : {})) as Row;
+  const fields = schema.messages[type];
+  if (!fields) throw new Error(`protobuf: ${type} is not a message of the schema`);
+  const w = new Writer();
+  for (const f of fields) {
+    const x = v[f.json] ?? v[f.name];
+    if (x === undefined || x === null) continue;
+    if (f.map) {
+      for (const [k, mv] of Object.entries(x as Row)) {
+        const entry = new Writer();
+        const keyType = f.map.key;
+        writeValue(schema, entry, { number: 1, type: keyType, kind: 'scalar' }, keyType === 'bool' ? k === 'true' : k);
+        writeValue(schema, entry, { number: 2, type: f.map.value, kind: f.map.valueKind }, mv);
+        w.tag(f.number, 2); w.bytes(entry.done());
+      }
+    } else if (f.repeated) {
+      const list = x as unknown[];
+      if (f.kind === 'enum' || (f.kind === 'scalar' && f.type !== 'string' && f.type !== 'bytes')) {
+        // proto3 packs repeated scalars and enums
+        const packed = new Writer();
+        for (const item of list) { if (f.kind === 'enum') packed.varint(BigInt(enumNumber(schema, f.type, item))); else writeScalar(packed, f.type, item); }
+        w.tag(f.number, 2); w.bytes(packed.done());
+      } else for (const item of list) writeValue(schema, w, f, item);
+    } else writeValue(schema, w, f, x);
+  }
+  return w.done();
+}
+
+// ── reading ────────────────────────────────────────────────────────────────────────────────────
+
+class Reader {
+  at = 0;
+  constructor(readonly b: Uint8Array) {}
+  get done(): boolean { return this.at >= this.b.length; }
+  varint(): bigint {
+    let out = 0n; let shift = 0n;
+    for (;;) {
+      if (this.at >= this.b.length) throw new Error('protobuf: a varint runs past the end');
+      const x = this.b[this.at++]!;
+      out |= BigInt(x & 0x7f) << shift;
+      if (!(x & 0x80)) return out;
+      shift += 7n;
+    }
+  }
+  take(n: number): Uint8Array {
+    if (n < 0 || this.at + n > this.b.length) throw new Error(`protobuf: a field runs past the message's end (${n} bytes at ${this.at} of ${this.b.length})`);
+    const out = this.b.subarray(this.at, this.at + n); this.at += n; return out;
+  }
+  bytes(): Uint8Array { return this.take(Number(this.varint())); }
+  skip(wire: number): void {
+    if (wire === 0) this.varint(); else if (wire === 1) this.take(8); else if (wire === 5) this.take(4); else if (wire === 2) this.bytes();
+    else throw new Error(`protobuf: wire type ${wire} is not supported`);
+  }
+}
+
+const unzigzag = (v: bigint): bigint => (v >> 1n) ^ -(v & 1n);
+
+function readScalar(r: Reader, type: string): unknown {
+  switch (type) {
+    case 'int32': return Number(BigInt.asIntN(32, r.varint()));
+    case 'uint32': return Number(BigInt.asUintN(32, r.varint()));
+    case 'int64': return String(BigInt.asIntN(64, r.varint()));
+    case 'uint64': return String(BigInt.asUintN(64, r.varint()));
+    case 'sint32': return Number(unzigzag(r.varint()));
+    case 'sint64': return String(unzigzag(r.varint()));
+    case 'bool': return r.varint() !== 0n;
+    case 'fixed64': return String(new DataView(r.take(8).slice().buffer).getBigUint64(0, true));
+    case 'sfixed64': return String(new DataView(r.take(8).slice().buffer).getBigInt64(0, true));
+    case 'double': return new DataView(r.take(8).slice().buffer).getFloat64(0, true);
+    case 'fixed32': return new DataView(r.take(4).slice().buffer).getUint32(0, true);
+    case 'sfixed32': return new DataView(r.take(4).slice().buffer).getInt32(0, true);
+    case 'float': return new DataView(r.take(4).slice().buffer).getFloat32(0, true);
+    default: throw new Error(`protobuf: ${type} is not a scalar`);
+  }
+}
+
+function enumName(schema: ProtoSchema, type: string, n: number): string | number {
+  for (const [name, v] of Object.entries(schema.enums[type] ?? {})) if (v === n) return name;
+  return n;
+}
+
+function readValue(schema: ProtoSchema, r: Reader, f: { type: string; kind: string }, wire: number): unknown {
+  if (f.kind === 'message') return decodeMessage(schema, f.type, r.bytes());
+  if (f.kind === 'enum') return enumName(schema, f.type, Number(BigInt.asIntN(32, r.varint())));
+  if (f.type === 'string') return DEC.decode(r.bytes());
+  if (f.type === 'bytes') return b64encode(r.bytes());
+  void wire;
+  return readScalar(r, f.type);
+}
+
+/** A well-known message's JSON form from its decoded fields, or the fields as they are for any other type. */
+function wellKnownOut(type: string, m: Row): unknown {
+  if (type === 'google.protobuf.Timestamp') {
+    const whole = new Date(Number(m.seconds ?? 0) * 1000).toISOString().replace(/\.000Z$/, '');
+    const nanos = Number(m.nanos ?? 0);
+    return `${whole}${protoFraction(nanos)}Z`;
+  }
+  if (type === 'google.protobuf.Duration') {
+    const seconds = BigInt(String(m.seconds ?? '0'));
+    const nanos = Number(m.nanos ?? 0);
+    const negative = seconds < 0n || nanos < 0;
+    return `${negative ? '-' : ''}${seconds < 0n ? -seconds : seconds}${protoFraction(Math.abs(nanos))}s`;
+  }
+  if (WRAPPERS[type] !== undefined) return m.value ?? (WRAPPERS[type] === 'bool' ? false : WRAPPERS[type] === 'string' || WRAPPERS[type] === 'bytes' ? '' : 0);
+  return m;
+}
+
+/** ProtoJSON emits 0, 3, 6 or 9 fractional digits, retaining the full nanosecond value. */
+function protoFraction(nanos: number): string {
+  if (!nanos) return '';
+  const digits = String(nanos).padStart(9, '0');
+  return `.${digits.slice(0, nanos % 1e6 === 0 ? 3 : nanos % 1000 === 0 ? 6 : 9)}`;
+}
+
+/** A message's binary encoding as its JSON form (proto3 JSON; a field at its default is left out). */
+export function decodeMessage(schema: ProtoSchema, type: string, bytes: Uint8Array): unknown {
+  const fields = schema.messages[type];
+  if (!fields) throw new Error(`protobuf: ${type} is not a message of the schema`);
+  const byNumber = new Map(fields.map((f) => [f.number, f] as const));
+  const out: Row = {};
+  const r = new Reader(bytes);
+  while (!r.done) {
+    const key = Number(r.varint());
+    const number = key >>> 3;
+    const wire = key & 7;
+    const f = byNumber.get(number);
+    if (!f) { r.skip(wire); continue; }
+    if (f.map) {
+      const entry = new Reader(r.bytes());
+      let k: unknown; let v: unknown;
+      while (!entry.done) {
+        const ek = Number(entry.varint());
+        if ((ek >>> 3) === 1) k = readValue(schema, entry, { type: f.map.key, kind: 'scalar' }, ek & 7);
+        else if ((ek >>> 3) === 2) v = readValue(schema, entry, { type: f.map.value, kind: f.map.valueKind }, ek & 7);
+        else entry.skip(ek & 7);
+      }
+      ((out[f.json] ??= {}) as Row)[String(k ?? '')] = v;
+    } else if (f.repeated) {
+      const list = (out[f.json] ??= []) as unknown[];
+      // a packed run of scalars or enums, or one element
+      if (wire === 2 && (f.kind === 'enum' || (f.kind === 'scalar' && f.type !== 'string' && f.type !== 'bytes'))) {
+        const packed = new Reader(r.bytes());
+        while (!packed.done) list.push(f.kind === 'enum' ? enumName(schema, f.type, Number(BigInt.asIntN(32, packed.varint()))) : readScalar(packed, f.type));
+      } else list.push(readValue(schema, r, f, wire));
+    } else out[f.json] = readValue(schema, r, f, wire);
+  }
+  return wellKnownOut(type, out);
+}

package/src/redis/engine.ts

@@ -84,7 +84,7 @@ export class ReadOnlyError extends Error {
   }
 }
 
-/** Redis's type name for a stream, as TYPE answers it (a Redis type, not the `stream` pack: scripts/architecture.test.ts). */
+/** Redis's type name for a stream, as TYPE answers it (a Redis type, not a pack name: scripts/architecture-auto.ts A2). */
 const STREAM = 'stream' as const;
 export const KEY_TYPES = ['string', 'list', 'set', 'hash', 'zset', STREAM] as const;
 export type KeyType = typeof KEY_TYPES[number];

package/src/request-scope.ts

@@ -11,7 +11,7 @@
 // runs under `runAsVendorMove` and still lands under a read-only request, as a real vendor renews a
 // subscription whoever is looking.
 //
-// Created on first use, never at import: a browser bundle of a mirror client carries the kernel and
+// Created on first use, never at import: a browser bundle carries the kernel and
 // has no AsyncLocalStorage (see serve.ts identitySlot).
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { runWithTraceparent, traceparentForDelivery } from './trace-context.ts';
@@ -26,9 +26,13 @@ export function isReadOnlyRequest(request: Request | { headers: Headers }): bool
 
 /** A write a read-only request attempted: refused before anything was written (rule D3's 405). */
 export class ReadOnlyRequestError extends Error {
-  constructor(readonly service: string) {
+  // a field, not a parameter property: Node runs this module with its types stripped (an application importing the
+  // World clock), and stripping takes no parameter property
+  readonly service: string;
+  constructor(service: string) {
     super(`${service}: this request is read-only (${READ_ONLY_REQUEST_HEADER}: 1); it cannot write`);
     this.name = 'ReadOnlyRequestError';
+    this.service = service;
   }
 }
 
@@ -53,14 +57,14 @@ export async function runAsReadOnlyRequest<T>(fn: () => T | Promise<T>): Promise
 }
 
 /** Run `fn` as the VENDOR's own move (a pack's catch-up): its writes land even under a read-only
- *  request. Outside one it changes nothing. */
+ *  request, and are recorded as the World's own moves, never as the caller's API call (inVendorMove). */
 export function runAsVendorMove<T>(fn: () => T): T {
   const current = writeScope().getStore();
   // the vendor's move is its own span of the request's trace (a delivery's shape): what it writes is joined to the
   // trace, never to the request's caller, who did not make it
   const own = traceparentForDelivery();
   const run = own ? () => runWithTraceparent(own, fn) : fn;
-  return current ? writeScope().run({ ...current, vendorMove: true }, run) : run();
+  return writeScope().run(current ? { ...current, vendorMove: true } : { readOnly: false, vendorMove: true, refusals: [] }, run);
 }
 
 /** Whether this runs as the vendor's own move (runAsVendorMove). */

package/src/resource-blob.ts

@@ -13,6 +13,19 @@ export async function readResourceBlob(service: string, key: string, root?: stri
   return null;
 }
 
+/** Write a resource payload on this branch (a stored object's bytes), where a read finds it first. */
+export async function writeResourceBlob(service: string, key: string, bytes: Uint8Array, root?: string): Promise<void> {
+  assertResourceKey(key);
+  await getActiveBlobStore().put(join(worldPaths(service, root).resources, key), bytes);
+}
+
+/** Remove this branch's copy of a resource payload; an ancestor's stays its own (the row that named it is what a
+ *  deletion ends). */
+export async function removeResourceBlob(service: string, key: string, root?: string): Promise<void> {
+  assertResourceKey(key);
+  await getActiveBlobStore().remove(join(worldPaths(service, root).resources, key));
+}
+
 /** A service's resources dir at this branch, then at each retained ancestor's: where a read resolves a payload, and
  *  what a listing that mints ids covers, so a branch serves bytes its parent received and never re-mints a parent's id. */
 export function resourceChain(service: string, root?: string): string[] {

package/src/runtime.ts

@@ -0,0 +1,344 @@
+// @volter/world-core/runtime — the kernel itself and the vendor-independent runtime libraries: the log and the tree
+// read and written directly, checkpoints, branches, landing and receipts, the head, the stores, the runtime's scopes and
+// clocks, and the plugin contract's surfaces. It is the runtime's, the CLI's, the host's and the tooling's. A Protocol 3
+// pack never imports it: its contract is the root, `@volter/world-core` (docs/contributing/architecture.md, "The pack
+// contract: the kernel's root"). Removed v1 entry points fail explicitly. Conformance and validation tooling lives in
+// @volter/world-tooling, a dev dependency.
+// Pack registry — vendor twins self-describe (TwinPack) so tooling discovers them.
+export { clearRegistry, getPack, hasPack, listPacks, packOf, 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, TWIN_REQUEST_SCOPES, twinPublicBase, withRequestScopes } from './twin-fetch.ts';
+export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.ts';
+export { compileSurface, createDerivedFetch, matchOperation } from './derived.ts';
+export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.ts';
+export type { Traceparent } from './trace-context.ts';
+export type { DerivedCall, DerivedCoreOutcome, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface } from './derived.ts';
+export { authRefusal, bindSemantics, coreFor, crossCutting, flagOf, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.ts';
+export { deliverEvents, fillEnvelope, signEvent, signEventAll, verifyEvent } from './events.ts';
+export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from './signing.ts';
+export type { HandlerCrypto, Jwk, Jwks, JwtVerdict, SigningKey } from './signing.ts';
+export type { EventDelivery, EventRender, EventScheme, EventsDecl, EventTransport, EventWrite } from './events.ts';
+export type { Actor, CoreScope, DerivedManifest, ErrorSpec, FieldRule, Handler, HandlerContext, ResourceDecl, WriteHookContext, ScreenDecl, Semantics, SemanticsContext, StateField, Transition, TransitionObserver, SeedCall } 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,
+  // 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.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,
+  CALLER_HEADER,
+  callerForHeader,
+  callerFromHeader,
+  journalTwinRequest,
+  readTwinRequestJournalFrom,
+  type TwinRequestJournalCursor,
+  twinRequestJournalFailures,
+  twinRequestCredentials,
+  readTwinRequestJournal,
+  recordedInput,
+  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,
+  projectOwnerResources,
+  OwnerStoreAmbiguousError,
+  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,
+  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.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';
+export { installedPackageDir, packRepository, isDerivedPack, vendorPackageDir, vendorOfPackModule } from './pack-paths.ts';
+
+// The git plane (contract "The git plane is a kernel library"): objects, packs, refs, smart HTTP.
+export * as git from './git/index.ts';
+// S3's wire (contract "S3's wire is a kernel library too"): its XML, CORS, lifecycle, delete batches, ETags, body bytes.
+export * as s3 from './s3/wire.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 { aliasesFrom, 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, keySealer, transitSealer, type Rewrapped, type Sealer, type TransitSealerOptions, type SealedByVault, type SealedUnderKey } 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';
+
+// 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.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';
+
+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, serveStream, nodeBuiltin, WORLD_BOOT_PATH, type HttpServer, type ServeHttpOptions, type HttpHandler } from './serve-http.ts';
+// two runtime-neutral helpers for a serve path: a file as a Response, a page's client bundle
+export { fileResponse, contentTypeOf } from './file-response.ts';
+export { bundleClient, filePathOf } 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 { multipartBoundary, multipartParts, type MultipartPart } from './multipart.ts';
+export { corsHeaders, withCors, type CorsDecl } from './cors.ts';
+export { vendorFetch, VendorUnreachableError } from './vendor-call.ts';
+export { closeManagedDatabases, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver, WORLD_CLOCK_SETTING, worldClockSql, type DatabaseDriver } from './managed-database.ts';
+export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.ts';
+export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobSize, resourceChain, writeResourceBlob } from './resource-blob.ts';
+
+export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, withHistoryLock, withHistoryLocks, withStateLock, 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';