@volter/world-core 2.0.0

package/src/mirror-shell.ts

@@ -0,0 +1,15 @@
+// A pack's mirror shell as a World serves it, at /<org>/<world>/<vendor>/mirror/ (the served World's
+// mount and the hosted supervisor's): its <base> becomes the twin's place under the World, so the
+// mirror's reads go to the World's wire; its assets stay under mirror/; and its own `#/` routes stay on
+// the shell. A mirror links its routes as href="#/…", which the browser resolves against <base> — the
+// twin's API path, not the shell — so a capture-phase handler moves the hash on the page instead.
+
+const HASH_LINKS = `<script>document.addEventListener('click',function(e){var a=e.target&&e.target.closest&&e.target.closest('a[href^="#"]');if(!a||e.defaultPrevented||e.button!==0||e.metaKey||e.ctrlKey||e.shiftKey||e.altKey)return;e.preventDefault();location.hash=a.getAttribute('href');},true);</script>`;
+
+/** The shell's HTML mounted at `base` (the twin's place, ending in '/'). */
+export function mirrorShellUnder(html: string, base: string): string {
+  const mounted = html
+    .replace(/<base href="[^"]*">/, `<base href="${base}">`)
+    .replace(/(href|src)="assets\//g, '$1="mirror/assets/');
+  return mounted.includes('</head>') ? mounted.replace('</head>', `${HASH_LINKS}</head>`) : `${HASH_LINKS}${mounted}`;
+}

package/src/observe.ts

@@ -0,0 +1,130 @@
+// OBSERVE — the kernel's fold for the second difference between simulated and real: how the tree
+// is kept current (company contract "Refresh is the kernel's fold", ruled 2026-09-06).
+//
+// A pack's refresh and ingest code hand the kernel RESOURCES, never rows. The kernel diffs each
+// against the upstream view and appends to the ROOT's log (the parent log — the vendor's history as
+// observed) only what changed: one entry per changed subject, carrying the changed fields; an
+// unchanged resource appends nothing; a listing the adapter declares complete tombstones what it
+// no longer holds. A refresh runs inside a scope that collects the adapter's observations and folds
+// them as one batch; an ingest observes directly, one resource at a time.
+import { withAncestryLock } from './ancestry.ts';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { appendParentEntry, readParentTreeMap, type Entry, type Tree } from './log.ts';
+import { hashFieldValue, type SubjectFields } from './hash.ts';
+import { worldNow } from './world-clock.ts';
+
+export type ObservedResource = { type: string; id: string; fields: SubjectFields; deleted?: boolean };
+export type ObserveReport = { observed: number; appended: number; unchanged: number; removed: number };
+
+export type Observation = { service: string; root?: string } & (
+  | { resource: ObservedResource }
+  | { resources: ObservedResource[]; complete?: string[] }
+);
+// ONE sink per process, whichever copy of the kernel a pack resolved: a pack installed beside a
+// world carries its own `@volter/world-core`, and its observations must reach the scope the runtime
+// opened. A module-level instance would be one per copy; a process-global symbol is one per process.
+const SINK = Symbol.for('volter.observe.sink');
+// created on first use, never at import: a mirror's CLIENT bundle (target browser) carries this module
+// through the pack's shared helpers, and a browser has no AsyncLocalStorage — constructing one at load
+// would kill the whole client ("not a constructor") for a scope the browser never opens
+const sink = (): AsyncLocalStorage<Observation[]> => ((globalThis as Record<symbol, unknown>)[SINK] ??= new AsyncLocalStorage<Observation[]>()) as AsyncLocalStorage<Observation[]>;
+
+/** Run `fn` with every `observeResource` inside it COLLECTED instead of folded; the caller folds the
+ *  batch (`observeResources`) once `fn` returns. The kernel's refresh does this around an adapter. */
+export async function collectObservations<T>(fn: () => Promise<T>): Promise<{ value: T; observations: Observation[] }> {
+  const observations: Observation[] = [];
+  const value = await sink().run(observations, fn);
+  return { value, observations };
+}
+
+/** Fold a collected batch: one `observeResources` per service, `complete` applied to each. */
+export function foldObservations(observations: Observation[], opts: { root?: string; at?: string; complete?: string[]; batch?: string } = {}): ObserveReport {
+  const total: ObserveReport = { observed: 0, appended: 0, unchanged: 0, removed: 0 };
+  const groups = new Map<string, { service: string; root?: string; resources: ObservedResource[]; complete: Set<string> }>();
+  for (const o of observations) {
+    const root = opts.root ?? o.root;
+    const key = JSON.stringify([o.service, root]);
+    let group = groups.get(key);
+    if (!group) { group = { service: o.service, root, resources: [], complete: new Set(opts.complete) }; groups.set(key, group); }
+    if ('resource' in o) group.resources.push(o.resource);
+    else for (const resource of o.resources) group.resources.push(resource);
+    if ('resources' in o) for (const type of o.complete ?? []) group.complete.add(type);
+  }
+  for (const { service, root, resources, complete } of groups.values()) {
+    const r = foldResources(service, resources, { ...opts, root, complete: [...complete] });
+    total.observed += r.observed; total.appended += r.appended; total.unchanged += r.unchanged; total.removed += r.removed;
+  }
+  return total;
+}
+
+/** One observed resource: collected when a refresh scope is open, else folded onto the root's log now. */
+export function observeResource(service: string, resource: ObservedResource, opts: { root?: string; at?: string } = {}): ObserveReport {
+  const collecting = typeof AsyncLocalStorage === 'function' ? sink().getStore() : undefined;
+  if (collecting) { collecting.push({ service, resource, ...(opts.root !== undefined ? { root: opts.root } : {}) }); return { observed: 1, appended: 0, unchanged: 0, removed: 0 }; }
+  return observeResources(service, [resource], opts);
+}
+
+function stable(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'undefined';
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  const o = value as Record<string, unknown>;
+  return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${stable(o[k])}`).join(',')}}`;
+}
+
+/** The fold: diff each resource against upstream state, append what changed to the root's log. `complete`
+ *  names the types this batch listed in full — a subject of such a type the batch does not hold is
+ *  tombstoned. Entry ids are content-addressed, so the same observation folds once. */
+export function observeResources(service: string, resources: ObservedResource[], opts: { root?: string; at?: string; complete?: string[]; batch?: string } = {}): ObserveReport {
+  const collecting = typeof AsyncLocalStorage === 'function' ? sink().getStore() : undefined;
+  if (collecting) {
+    collecting.push({ service, resources, ...(opts.root !== undefined ? { root: opts.root } : {}), ...(opts.complete ? { complete: opts.complete } : {}) });
+    return { observed: resources.length, appended: 0, unchanged: 0, removed: 0 };
+  }
+  return foldResources(service, resources, opts);
+}
+
+function foldResources(service: string, resources: ObservedResource[], opts: { root?: string; at?: string; complete?: string[]; batch?: string }): ObserveReport {
+  return withAncestryLock(() => {
+  const at = opts.at ?? worldNow();
+  // one look is one batch: every entry it appends carries the same id, and no position may split it
+  const batch = opts.batch ?? `obs:${service}:${at}`;
+  const tree: Tree = readParentTreeMap(service, opts.root);
+  const report: ObserveReport = { observed: resources.length, appended: 0, unchanged: 0, removed: 0 };
+  const seen = new Set<string>();
+  const append = (subject: { type: string; id: string }, fields: SubjectFields): boolean => {
+    const entry: Entry = {
+      id: `observed:${service}:${subject.type}:${subject.id}:${hashFieldValue({ subject, fields, at })}`,
+      service, op: 'set', operation: 'observed', subject, occurredAt: at, actor: { kind: 'system', id: 'vendor' }, fields, batch,
+    };
+    const { appended } = appendParentEntry(entry, opts.root);
+    const key = `${subject.type}:${subject.id}`;
+    const existing = tree.get(key) ?? { type: subject.type, id: subject.id, updatedAt: at, fields: {} };
+    const merged: SubjectFields = { ...existing.fields, ...fields };
+    if (existing.fields.deleted === true && fields.deleted !== true) delete merged.deleted;
+    tree.set(key, { ...existing, updatedAt: at, fields: merged });
+    return appended;
+  };
+  for (const r of resources) {
+    const key = `${r.type}:${r.id}`;
+    seen.add(key);
+    const existing = tree.get(key);
+    if (r.deleted) {
+      if (existing && existing.fields.deleted !== true) { if (append({ type: r.type, id: r.id }, { deleted: true })) report.removed += 1; }
+      else report.unchanged += 1;
+      continue;
+    }
+    const changed: SubjectFields = {};
+    for (const [k, v] of Object.entries(r.fields)) if (v !== undefined && (existing === undefined || stable(existing.fields[k]) !== stable(v))) changed[k] = v;
+    if (Object.keys(changed).length === 0 && existing !== undefined && existing.fields.deleted !== true) { report.unchanged += 1; continue; }
+    if (existing?.fields.deleted === true && Object.keys(changed).length === 0) Object.assign(changed, r.fields); // resurrected as it stands
+    if (append({ type: r.type, id: r.id }, changed)) report.appended += 1; else report.unchanged += 1;
+  }
+  for (const type of opts.complete ?? []) {
+    for (const s of tree.values()) {
+      if (s.type !== type || seen.has(`${s.type}:${s.id}`) || s.fields.deleted === true) continue;
+      if (append({ type: s.type, id: s.id }, { deleted: true })) report.removed += 1;
+    }
+  }
+  return report;
+  });
+}

package/src/pack-assets.ts

@@ -0,0 +1,81 @@
+// THE PACK-ASSET SEAM (runtime contract R20). A pack may ship bytes it serves byte-for-byte —
+// clerk's vendored clerk-js dist (136 files, 14.5 MB), a mirror shell — that are neither
+// committed text (size) nor world-state blobs (R11's seam is keyed under a world's state root
+// and filled by requests). They are PACK assets: read-only, versioned with the package, the
+// same on every world. This seam is how a pack reaches them without touching a host: the
+// pack declares them on its descriptor (`assets`), reads them through `getActivePackAssets()`,
+// and the SHELL binds the store — the Bun shell reads the pack's own tree, workerd the
+// static-assets binding the mirror shells already deploy through. A pack that reads its tree
+// with Bun.file or import.meta is host-bound (R12b); one that reads through here is not.
+// No node builtins at module scope: `@volter/world-core`'s index re-exports this module and every mirror
+// client bundle (browser target) pulls the index in — a static `node:fs`/`node:url` import here
+// broke every mirror bundle the day the seam landed. The local store reads through Bun's file
+// API at call time; the worker store never touches a filesystem.
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+export interface PackAssetStore {
+  /** The asset at `relPath` inside the pack `vendor`'s directory (e.g. `client/clerk.browser.js`),
+   *  as a Response carrying the bytes and a content type — or null when the pack ships no such
+   *  file. `relPath` is confined to the pack's own tree: a traversal never resolves. */
+  fetch(vendor: string, relPath: string): Promise<Response | null>;
+}
+
+const CONTENT_TYPES: Record<string, string> = {
+  '.js': 'application/javascript; charset=utf-8', '.mjs': 'application/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8',
+  '.html': 'text/html; charset=utf-8', '.json': 'application/json; charset=utf-8', '.map': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml', '.png': 'image/png', '.ico': 'image/x-icon', '.woff2': 'font/woff2', '.woff': 'font/woff', '.txt': 'text/plain; charset=utf-8',
+};
+export function assetContentType(relPath: string): string {
+  const dot = relPath.lastIndexOf('.');
+  return (dot >= 0 ? CONTENT_TYPES[relPath.slice(dot)] : undefined) ?? 'application/octet-stream';
+}
+
+/** A relative path confined to a pack's tree: no absolute, no `..`, no empty segment. */
+export function confinedAssetPath(relPath: string): string | null {
+  if (relPath.startsWith('/') || relPath.includes('\\') || relPath.includes('\0')) return null;
+  const segs = relPath.split('/');
+  if (segs.some((s) => s === '' || s === '.' || s === '..')) return null;
+  return segs.join('/');
+}
+
+/** The Bun shell's store: the pack's own directory under the catalog (`packages/twin/<vendor>`).
+ *  `twinDir` ends with a slash. */
+export class LocalPackAssets implements PackAssetStore {
+  constructor(private readonly twinDir: string) {}
+  async fetch(vendor: string, relPath: string): Promise<Response | null> {
+    const safe = confinedAssetPath(relPath);
+    if (safe === null || !/^[a-z][a-z0-9-]*$/.test(vendor)) return null;
+    const file = `${this.twinDir}${vendor}/${safe}`; // confined: no `..`, no absolute, no empty segment (above)
+    if (!existsSync(file) || !statSync(file).isFile()) return null;
+    return new Response(readFileSync(file), { status: 200, headers: { 'content-type': assetContentType(safe) } });
+  }
+}
+
+/** The workerd shell's store: the static-assets binding, where the deploy step places each
+ *  pack's declared assets under `/{vendor}/pack/<relPath>` beside the mirror shells. */
+export class BindingPackAssets implements PackAssetStore {
+  constructor(private readonly assets: { fetch(request: Request): Promise<Response> }) {}
+  async fetch(vendor: string, relPath: string): Promise<Response | null> {
+    const safe = confinedAssetPath(relPath);
+    if (safe === null) return null;
+    const res = await this.assets.fetch(new Request(`https://pack-assets/${vendor}/pack/${safe}`));
+    if (res.status !== 200) return null;
+    return new Response(res.body, { status: 200, headers: { 'content-type': assetContentType(safe) } });
+  }
+}
+
+let active: PackAssetStore | undefined;
+/** The bound store — the Bun shell's local tree unless a shell bound another. */
+export function getActivePackAssets(): PackAssetStore {
+  if (active === undefined) active = new LocalPackAssets(new URL('../../twin/', import.meta.url).pathname);
+  return active;
+}
+export function setActivePackAssets(store: PackAssetStore): PackAssetStore | undefined {
+  const previous = active; active = store; return previous;
+}
+/** `getActivePackAssets().fetch(...)` with the pack's declared fallback: the first path that exists. */
+export async function packAsset(vendor: string, ...candidates: string[]): Promise<Response | null> {
+  const store = getActivePackAssets();
+  for (const c of candidates) { const r = await store.fetch(vendor, c); if (r !== null) return r; }
+  return null;
+}

package/src/packRegistry.ts

@@ -0,0 +1,408 @@
+// Pack registry (the twins architecture notes → "Optional shared
+// libraries"; #1). A lightweight, dependency-free way for vendor twins to *declare*
+// themselves so tooling can discover them — "add a vendor" gets cheaper. A pack
+// EXPORTS a `TwinPack` descriptor (no import side-effects); a consumer that imports
+// the packs it wants registers them and queries the registry. The kernel never
+// imports packs (no dependency inversion) — discovery is the consumer's choice.
+//
+// This is an optional convenience, NOT a kernel that defines the twin: a pack can
+// ignore the registry entirely. Pure + deterministic.
+import { declareRateBudget, type RateBudgetDeclaration } from './rateBudget.ts';
+import type { TwinAuthStrategy } from './executor.ts';
+import { registerReferences, type ReferenceDeclaration } from './references.ts';
+import type { TwinEmitter } from './emit.ts';
+import { registerAuthStrategy, registerStateSystem, type StateSystemAdapters } from './state-system.ts';
+
+/**
+ * How a pack's clients ADDRESS it. The first three are HTTP API styles; `raw-tcp` is the
+ * RAW-PROTOCOL class — a pack whose clients speak a line protocol directly over a TCP socket
+ * rather than HTTP, so none of the HTTP machinery applies: no `browserRouting`, and no entry in
+ * the injector's `VENDOR_HOSTS` host map is possible (the injector patches http/fetch and never
+ * sees the traffic). Such a pack is wired into a world through app-read host/port env instead,
+ * and this value is what tells a reader that "no injector entry" is STRUCTURAL rather than a
+ * missing wiring point. `packages/twin/smtp` is the first.
+ *
+ * Deliberately the transport CLASS, not the protocol name: naming the wire protocol would put a
+ * vendor id in the kernel the moment a pack is named after its protocol, which is exactly what
+ * `scripts/architecture.test.ts`'s "kernel does not branch on vendor identity" forbids. The
+ * specific protocol belongs on the pack's own `specSource`/`description`.
+ */
+export type PackTransport = 'rest' | 'graphql' | 'web-api' | 'raw-tcp';
+
+/**
+ * The pack's SERVE-FAMILY — the axis the invariant matrix keys strictness off, DECLARED
+ * because it is the pack's own claim about what kind of thing it is (a heuristic over file
+ * shapes would be the loose-scan disease). Orthogonal facts stay derived: transport is its
+ * own field, a mirror is mirrorMutations in gate.ts, webhooks are the events module.
+ *   'crud'            — stateful resource CRUD behind the vendor's API (the default family;
+ *                       includes ingestion→grouping packs — the ingest door is a trait).
+ *   'generative'      — model-shaped surface serving deterministic stubs/scenarios; "cannot
+ *                       run the model" is the invariant, never a gap.
+ *   'signed-protocol' — the wire is a signature/format protocol (SigV4 + XML/AWS-JSON …):
+ *                       request authentication IS the fidelity surface.
+ *   'engine-control'  — a control plane driving a REAL execution engine behind an injected
+ *                       seam (fly's runtime, github's git plane, supabase's external stack).
+ *   'proxy'           — the vendor itself is a forwarding plane (tunnel).
+ */
+/** THE PLATFORM PROTOCOL VERSION (runtime contract R16): `major.minor`. The major names the
+ *  descriptor shape, the factory signature, the doors and the adapter contract a package is
+ *  written against; a change that removes or alters a required shape bumps it, an additive
+ *  change bumps minor. A package declares the major it targets (`protocol`); the kernel serves
+ *  its own major, the previous one under a deprecation warning for one cycle, and refuses two
+ *  back. Undeclared reads as the previous major (deprecated) once there is one. */
+export const PROTOCOL_VERSION = '2.0';
+export const PROTOCOL_MAJOR = Number(PROTOCOL_VERSION.split('.')[0]);
+/** Where a package's declared protocol stands against this kernel. */
+export function protocolStanding(declared: string | undefined): { major: number; standing: 'current' | 'deprecated' | 'refused' | 'assumed' } {
+  // undeclared: written before a pack could say — the previous major once there is one, and
+  // deprecated like any pack on it; the current major only while it is the first
+  if (declared === undefined) return PROTOCOL_MAJOR > 1 ? { major: PROTOCOL_MAJOR - 1, standing: 'deprecated' } : { major: PROTOCOL_MAJOR, standing: 'assumed' };
+  const major = Number(String(declared).split('.')[0]);
+  if (!Number.isInteger(major) || major < 1) return { major: Number.NaN, standing: 'refused' };
+  if (major === PROTOCOL_MAJOR) return { major, standing: 'current' };
+  if (major === PROTOCOL_MAJOR - 1) return { major, standing: 'deprecated' };
+  return { major, standing: 'refused' };
+}
+
+export const PACK_ARCHETYPES = ['crud', 'generative', 'signed-protocol', 'engine-control', 'proxy'] as const;
+export type PackArchetype = (typeof PACK_ARCHETYPES)[number];
+
+/**
+ * How often this vendor's REAL API may be pulled — a property of the VENDOR's rate limits, so it
+ * belongs to the pack that knows them, not to every world that might sync one (same argument as
+ * `browserRouting`: vendor knowledge in the descriptor, kernel stays vendor-agnostic).
+ *
+ * - `'continuous'` — limits are generous and well-documented, so a scheduled/shadow world may sync
+ *   this vendor on a cadence (slack, github: thousands/hour, per-method tiers, clear headers).
+ * - `'on-demand'` — limits are tight, opaque, cost-based, or punish bursts with long lockouts, so a
+ *   real pull happens ONLY when a human/agent explicitly asks for one. Never on a schedule, never
+ *   as a side effect of booting a world. Figma is the cautionary case: undocumented cost-based
+ *   limits, and a burst of renders cost this project a ~4.5-DAY token lockout (2026-07-25).
+ *
+ * DEFAULT IS `'on-demand'` when omitted — deliberately the safe direction. A pack that hasn't
+ * thought about its limits must not be assumed schedulable; being wrong that way costs a slower
+ * sync, while being wrong the other way costs a lockout.
+ */
+export type PullPosture = 'continuous' | 'on-demand';
+
+/** The posture to assume for a pack that doesn't declare one. Conservative on purpose. */
+export const DEFAULT_PULL_POSTURE: PullPosture = 'on-demand';
+
+/** A pack's effective posture — its declaration, or the conservative default. */
+export function pullPosture(pack: Pick<TwinPack, 'pullPosture'>): PullPosture {
+  return pack.pullPosture ?? DEFAULT_PULL_POSTURE;
+}
+
+/**
+ * What may name a vendor at a pull seam: the pack descriptor itself (the pack knows its own
+ * posture — no registration needed) or a vendor id resolved through the registry. The id form is
+ * the convenient one; it is also the one that FAILS CLOSED, because an id nothing registered
+ * resolves to a posture-less descriptor, i.e. the conservative default.
+ */
+export type PullVendor = string | Pick<TwinPack, 'vendor' | 'pullPosture'>;
+
+/**
+ * Why a pull is happening — the distinction the posture rule actually turns on.
+ *
+ * - `'scheduled'` — a cadence, a poll loop, a shadow tick, or any pull that happens as a side
+ *   effect of something else (booting a world, a cron). Allowed for `'continuous'` vendors ONLY.
+ * - `'explicit'` — a human/agent asked for THIS pull, now. Sanctioned for any vendor; it is the
+ *   only way an on-demand vendor is ever supposed to be pulled.
+ *
+ * Omitted ⇒ `'scheduled'`, matching the posture default: an unlabeled pull is treated as the
+ * dangerous kind, so labeling is what unlocks the vendor, never silence.
+ */
+export type PullTrigger = 'scheduled' | 'explicit';
+
+/** The trigger to assume when a caller does not say. Conservative on purpose. */
+export const DEFAULT_PULL_TRIGGER: PullTrigger = 'scheduled';
+
+/** Resolve a `PullVendor` to the descriptor whose posture governs it. Unregistered ⇒ no posture. */
+export function resolvePullVendor(vendor: PullVendor): Pick<TwinPack, 'vendor' | 'pullPosture'> {
+  if (typeof vendor !== 'string') return vendor;
+  return getPack(vendor) ?? { vendor };
+}
+
+/**
+ * Guard a SCHEDULED/continuous sync. Throws for a vendor that may only be pulled on demand.
+ *
+ * This is the mechanical form of the rule — worlds differ in what they may pull:
+ *   • sealed (hermetic OA cycle worlds) pull NOTHING; they seed synthetic state over loopback and
+ *     an egress guard blocks the internet, so posture is irrelevant there;
+ *   • shadow/scheduled worlds sync real state on a cadence — `'continuous'` vendors ONLY;
+ *   • on-demand pulls are explicit, operator-invoked, and may target any vendor.
+ * A scheduled world that quietly includes an on-demand vendor is how a lockout happens, so it
+ * fails loudly here instead.
+ */
+export function assertContinuousPullAllowed(vendor: PullVendor): void {
+  const pack = resolvePullVendor(vendor);
+  if (pullPosture(pack) === 'continuous') return;
+  const undeclared = pack.pullPosture === undefined;
+  throw new Error(
+    `pull posture: "${pack.vendor}" is on-demand — it must NOT be pulled on a schedule or as a side ` +
+      `effect of booting a world. Its rate limits are tight/opaque enough that a burst risks a long ` +
+      `lockout. Pull it explicitly when someone asks, through the pack's guarded connector; a sealed ` +
+      `world should seed synthetic state locally instead. If this vendor's limits are genuinely ` +
+      `generous, declare pullPosture:'continuous' on its TwinPack and say why.` +
+      (undeclared
+        ? ` (Nothing declared a posture for "${pack.vendor}" — either no pack is registered under ` +
+          `that id (registerPack) or its TwinPack omits pullPosture. Silence is not permission: the ` +
+          `conservative default applied. If this pull is a one-off someone asked for, say so at the ` +
+          `call site — pass the explicit trigger instead of putting it on a cadence.)`
+        : ''),
+  );
+}
+
+/**
+ * The ONE sanctioned way to pull a vendor on a cadence. Asserts the posture BEFORE `pull` runs, so
+ * a refused vendor makes ZERO vendor requests — the guard has to sit in front of the network call,
+ * not behind it (guarding the fold, e.g. `syncPull`, would be theatre: the request already went out).
+ *
+ * Wrap any scheduler/cron/loop's pull in this and the rule enforces itself:
+ *   `await pullOnSchedule(pack, () => syncSlackFromReal(client, opts))`
+ * An explicit, human-asked pull does NOT go through here — it calls the connector directly, which is
+ * exactly the sanctioned path for an on-demand vendor.
+ */
+export async function pullOnSchedule<T>(vendor: PullVendor, pull: () => Promise<T>): Promise<T> {
+  assertContinuousPullAllowed(vendor);
+  return pull();
+}
+
+/**
+ * One injector host rule — DATA the committed inject.cjs compiles, never a function. Exactly one
+ * selector: `host` (exact), `suffix` (endsWith), or `hostPattern` (a RegExp SOURCE over the
+ * hostname — regional families like `^s3[.-][a-z0-9-]+\.amazonaws\.com$`). `pathPattern` (a
+ * RegExp source over the pathname) splits a host shared between packs. `key` names the routing
+ * identity the rule belongs to — the `<KEY>_TWIN_URL` env stem — when it is not the pack's own
+ * vendor id (aws's consolidated twin answers under s3 / dynamodb / … ; gemini serves the
+ * `googleauth` token exchange); a key belongs to ONE pack. `exclude: true` carves a host out of
+ * the key's includes (`.upstash.io` minus `*-vector.upstash.io`): a key matches when any include
+ * matches and no exclude does. Validated by scripts/pack-facts.ts: keys are `[a-z0-9-]+`, a
+ * foreign key is never another pack's vendor id, belongs to one pack, and must appear in the
+ * pack's `adoption.worldIds` (the world wires `<KEY>_TWIN_URL` from there); a pack must claim its
+ * own vendor id too; no key is exclude-only; `exclude` is `true` or absent.
+ */
+export type HostRule = ({ host: string } | { suffix: string } | { hostPattern: string }) & {
+  pathPattern?: string;
+  key?: string;
+  exclude?: true;
+};
+
+export type RoundTripWrite = { method: string; path: string; body?: unknown; headers?: Record<string, string> };
+
+export type TwinPack = {
+  /** vendor id / service, e.g. 'stripe'. */
+  vendor: string;
+  transport: PackTransport;
+  /** Optional native frontend of the same state owner, selected explicitly on the pack CLI. */
+  nativeTransport?: { protocol: string; flag: string; upstreamEnv: string };
+  /** The serve-family (see PackArchetype). Every pack declares one. */
+  archetype?: PackArchetype;
+  /** The platform protocol MAJOR this package targets (R16), e.g. '1'. Undeclared reads as the
+   *  previous major (deprecated), or as the current major (recorded as assumed) while it is the first;
+   *  the scaffolder declares it. */
+  protocol?: string;
+  /** Pack-shipped assets (R20): files or directories under the pack dir the serve path reads through
+   *  the pack-asset seam (`getActivePackAssets`), never off the host. Declared so the deploy step
+   *  can place them behind the workerd assets binding. Paths relative to the pack dir. */
+  assets?: string[];
+  /** R2, resource level: declared subject types the twin genuinely serves but no replay can create —
+   *  born only of the vendor's own catalog, scheduler, account or a pull. Each names WHY. The cell
+   *  stays debt (adopted, never faked), but legibly: the runner separates these from open gaps. */
+  resourcesUnreachable?: Record<string, string>;
+  /** subject types the twin serves, e.g. ['customer','charge','payment_intent']. */
+  resources: string[];
+  /** the `world-<vendor>` operator bin, if any. */
+  bin?: string;
+  /** conformance field map { object: { field: type } } — vendored or derived from the spec. */
+  conformanceFields?: Record<string, Record<string, string>>;
+  /** where the exact surface came from (a spec path) — provenance for re-derivation. */
+  specSource?: string;
+  /** one-line human description. */
+  description?: string;
+  /** How this vendor's BROWSER SDK addresses its API — used by the zero-edit dev proxy so
+   *  the kernel proxy stays vendor-agnostic (it forwards/rewrites by these values, never by a
+   *  hardcoded vendor table). `apiPathPrefix`: the same-origin path the browser SDK calls
+   *  (e.g. Stripe.js → '/v1/'). `loaderHost`: the absolute API host to strip from the loaded
+   *  SDK so its calls become same-origin (e.g. 'https://api.stripe.com'). Omit for vendors
+   *  with no browser SDK. */
+  browserRouting?: { apiPathPrefix: string; loaderHost?: string };
+  /** How often this vendor's REAL API may be pulled. Omitted ⇒ `'on-demand'` (see `PullPosture`).
+   *  Declare `'continuous'` only for a vendor whose published limits genuinely tolerate a
+   *  scheduled sync, and say why in `pullPostureReason`. */
+  pullPosture?: PullPosture;
+  /** Why this posture — the limits that justify it. Required in review for `'continuous'`, since
+   *  that is the claim that can cost a lockout if it's wrong. */
+  pullPostureReason?: string;
+  /**
+   * The vendor's CLIENT-SIDE RATE BUDGET — the ceiling, window and per-endpoint weights the pack's
+   * guarded connector enforces before a live call goes out. Vendor knowledge as DATA, exactly like
+   * `browserRouting`: the mechanism is the kernel's (`rateBudget.ts`), the numbers are the pack's.
+   *
+   * `registerPack` forwards this to `declareRateBudget`, so registering a pack arms its budget.
+   * A pack that omits it is NOT unlimited — any budget built for that vendor falls back to
+   * `DEFAULT_RATE_BUDGET` (see its docstring). `pullPosture` says "do not SCHEDULE this vendor";
+   * this says "and here is the ceiling on an EXPLICIT pull". They are complementary, not
+   * substitutes — the posture guards cadence seams, the budget guards the call itself.
+   */
+  rateBudget?: RateBudgetDeclaration;
+  /**
+   * The pack's DELIVER support (`emit` — see emit.ts): how to synthesize this vendor's
+   * signed event/webhook deliveries from current twin state. Vendor knowledge on the
+   * descriptor, like `browserRouting`; the kernel engine (`emitTwinEvent`) is generic.
+   * The operator surface is the pack's own bin (`world-<vendor> emit`); a consumer that
+   * registered the pack can also drive it via `volter-twin emit <vendor>`.
+   */
+  emitter?: TwinEmitter;
+  /**
+   * SERVE FACTORY OVERRIDE — normally DERIVED, declared only under ambiguity. The colocated
+   * host (world-runtime/src/host.ts) mounts a pack by its `create<Name>TwinServer` factory
+   * export (`({port,root,readOnly}) => {port,stop}`); `scripts/pack-facts.ts` reads that
+   * export's name off the module, so a pack with exactly ONE such export declares nothing.
+   * A pack exporting SEVERAL factories declares here which one `cli.ts serve` would have
+   * booted — the judgment the exports alone cannot reveal (linear serves its DERIVED server
+   * by default; the hand-written one is behind a flag). Must name a function export of the
+   * pack's index module matching /^create\w*TwinServer$/.
+   */
+  serveExport?: string;
+  /**
+   * ADOPTION — how application repos betray that they talk to this vendor, so
+   * `volter-world covers`/`init` can attribute the signal to this pack. Vendor knowledge as
+   * DATA, same doctrine as `browserRouting`/`rateBudget`: the detector mechanism lives in
+   * world-runtime; the names live here. Absorbs the central `SDK_TWINS` / `SDK_SCOPE_VENDORS` /
+   * `ENV_STEM_VENDORS` / `VENDOR_WORLD_IDS` maps (the one wiring point NO gate enforced —
+   * the class that let `@planetscale/database` escape, twin#255).
+   */
+  adoption?: {
+    /** every official npm client of the API surface this pack models, e.g. ['stripe']. */
+    sdks?: string[];
+    /** PyPI distribution names (PEP 503 normalized: lowercase, `-`) the vendor's Python SDKs
+     *  ship under — the Python half of adoption discovery and coverage (`covers`). */
+    pypi?: string[];
+    /** npm scope prefixes whose members all belong to this vendor, e.g. ['@upstash/']. */
+    scopes?: string[];
+    /** credential-env-var stems, e.g. ['STRIPE'] for STRIPE_SECRET_KEY et al. */
+    envStems?: string[];
+    /** additional world service ids this vendor answers to (the VENDOR_WORLD_IDS case). */
+    worldIds?: string[];
+    /** Vendor-facing tool packages whose calls belong to supporting workflow rather than the
+     * application itself. The use is saved and selected by World discovery policy. */
+    tools?: Array<{ package: string; usage: 'build' | 'deployment' }>;
+  };
+  /**
+   * INTERCEPTION — the vendor hosts whose traffic the injector must route to this twin,
+   * as serializable data (the committed `inject.cjs` table is GENERATED from these — it must
+   * stay dependency-free preloaded CJS, so it consumes compiled output, never imports packs).
+   * Exactly one of `hosts` or `hostsNone` per pack once migration completes: silence is not a
+   * ruling. `pathPattern` (a RegExp source string, applied to the URL pathname) splits shared
+   * hosts (the youtube/googleauth case). Absorbed `VENDOR_HOSTS`'s per-pack keys + the retired NO_INJECTOR_ENTRY
+   * allowlist (hostsNone IS the ruling now).
+   */
+  hosts?: HostRule[];
+  /** Why this pack deliberately has NO injector entry (explicit-endpoint wiring only). */
+  hostsNone?: string;
+  /**
+   * HOSTS A TWIN CLAIMS WHILE IT RUNS — names a person makes answer to this vendor (a custom domain connected to a
+   * bucket), which no descriptor can list. The twin lists the ones it answers now at its own `door` (GET, answering
+   * `{ "hosts": [...] }`), and the World routes them to it as DNS would the vendor's; a host a descriptor's `hosts`
+   * names is never taken from another pack this way.
+   */
+  hostsClaimed?: { door: string; note: string };
+  /**
+   * WORLD WIRING — the env var the vendor's own SDK documents for overriding its base URL,
+   * which `volter-world init` injects pointing at the twin. `endpointEnvNone` declares the
+   * deliberate absence WITH its reason (inventing a var the app never reads would make
+   * `covers` report coverage while traffic still reaches the real vendor — the exact lie the
+   * proof exists to catch). Absorbs init.ts's `APP_READ_ENDPOINT_ENV` map, where these
+   * reasons lived as comments. Exactly one of the two once migration completes.
+   */
+  endpointEnv?: { name: string; templates?: Record<string, string>; note: string };
+  /** Why this pack deliberately injects no endpoint env (see `endpointEnv`). */
+  endpointEnvNone?: string;
+  /**
+   * PRISMA — the driver adapter a Prisma client reaches this database twin through, as DATA.
+   * Prisma's client-engine build (the one a tab runs, and the one its edge client uses) refuses
+   * to construct without a driver adapter; an application that constructs `new PrismaClient()`
+   * against the vendor's URL gets this adapter from ITS OWN dependencies, constructed on the
+   * URL in `urlEnv` (the endpoint template's variable), by the injector. The adapter package is
+   * never installed by the World: absent from the application, the client is left as it was.
+   */
+  prismaAdapter?: { adapter: string; export: string; urlEnv: string };
+  /** PROTOCOL 2 — the pack's half of the REAL state system (state-system.ts): perform one entry
+   *  against the vendor, refresh the parent log from it, ingest one signed webhook. All over the
+   *  kernel executor; the pack never holds a credential. Registered with the pack. */
+  stateSystem?: StateSystemAdapters;
+  /** PROTOCOL 2 — how a root is kept current, the pack's way: `every` schedules a pull in a served
+   *  world (the root's `refresh.every` overrides), `webhook` says the vendor pushes to the ingest
+   *  door, `onDemand.atMost` is the least time between `volter twin <v> refresh` runs (a throttle for
+   *  a rate-limited vendor). Absorbs `pullPosture`. */
+  refresh?: { every?: string; webhook?: boolean; onDemand?: { atMost: string } };
+  /** PROTOCOL 2 — a minimal write on the vendor's wire the kernel can send blind (or a short
+   *  sequence whose LAST write creates something new every time): the branch round-trip
+   *  (docs/contributing/architecture.md#evidence) sends it, checkpoints, branches, sends it again on the branch, and
+   *  proves the tree contract with no pack code. */
+  roundTrip?: RoundTripWrite | RoundTripWrite[];
+  /** PROTOCOL 2 — which fields of which subject types hold another subject's id (docs/contributing/architecture.md
+   *  #alias-aware-lookup-at-the-request-boundary): the kernel resolves them through an adopted vendor id, in the tree and at the perform. */
+  references?: ReferenceDeclaration[];
+  /** PROTOCOL 2 — with `references`: a write on the wire that references the `roundTrip` write's subject;
+   *  `{{field}}` in its path or body is the referenced subject's field. The round-trip gate sends it
+   *  after simulating the parent's adoption and checks the reference followed. */
+  referenceTrip?: RoundTripWrite;
+  /** PROTOCOL 2 — shape parity (roadmap 4c): the origin the parity gate hands the refresh adapter when it
+   *  refreshes the twin from itself (`http://twin` + whatever path the adapter reads its scope from), and
+   *  `'held'` once the write handler and the refresh adapter store the same shape (the gate then asserts). */
+  parityOrigin?: string;
+  shapeParity?: 'held';
+  /** PROTOCOL 2 — a refresh that cannot be exercised for effect when the parity gate refreshes the twin
+   *  from itself, and the refusal it answers with instead: `refusal` is text its thrown error carries,
+   *  `reason` why (an identity pull the twin's own wire refuses without a consent-minted token; a pulled
+   *  id inside the twin's reserved local namespace). The gate runs the refresh and passes it only on
+   *  that refusal; any other error fails. */
+  refreshRefusal?: { refusal: string; reason: string };
+  /** PROTOCOL 2 — HOW THIS VENDOR AUTHENTICATES, so the kernel executor can apply the sealed
+   *  credential the way the vendor actually reads it (docs/concepts/the-model.md#the-rules, rule 5). Absent means header
+   *  replacement, which is what `credential.headers` has always done — declare this ONLY for a
+   *  vendor that reads its key from the query string or wants a signature computed per request. */
+  auth?: TwinAuthStrategy;
+  /** PROTOCOL 2 — the ENGINE beside the tree, when the pack's state has a second half that is not a
+   *  projection (a git plane, S3 bytes, a SQL engine): the module that owns every write outside the
+   *  world store. The tree references engine objects by hash; the gate keeps such writes there. */
+  engine?: { module: string; note?: string };
+};
+
+const registry = new Map<string, TwinPack>();
+
+/** Register (or replace) a pack descriptor. Returns it.
+ *
+ *  Side effect, deliberately: a `rateBudget` declaration on the descriptor is ARMED here, so
+ *  registering a pack is enough to give its vendor the ceiling it declared. `declareRateBudget`
+ *  is idempotent for an identical declaration and REFUSES a widening one, so re-registering is
+ *  safe and "register a fatter pack descriptor to buy a bigger budget" is not a move. */
+export function registerPack(pack: TwinPack): TwinPack {
+  if (!/^[a-z0-9-]+$/.test(pack.vendor)) throw new Error(`invalid pack vendor id: ${pack.vendor}`);
+  if (pack.rateBudget) declareRateBudget(pack.vendor, pack.rateBudget);
+  if (pack.stateSystem) registerStateSystem(pack.vendor, pack.stateSystem);
+  if (pack.auth) registerAuthStrategy(pack.vendor, pack.auth);
+  if (pack.references) registerReferences(pack.vendor, pack.references);
+  registry.set(pack.vendor, pack);
+  return pack;
+}
+
+export function getPack(vendor: string): TwinPack | undefined {
+  return registry.get(vendor);
+}
+
+/** All registered packs, sorted by vendor (deterministic). */
+export function listPacks(): TwinPack[] {
+  return [...registry.values()].sort((a, b) => a.vendor.localeCompare(b.vendor));
+}
+
+export function hasPack(vendor: string): boolean {
+  return registry.has(vendor);
+}
+
+/** Clear the registry (tests). */
+export function clearRegistry(): void {
+  registry.clear();
+}