@volter/twin 0.1.0 → 0.1.1

package/src/index.ts

@@ -17,9 +17,51 @@ export * as controlPlane from './control-plane.ts';
 // the spec derivers) is NOT part of the runtime kernel — it lives in @volter/twin-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 } from './packRegistry.ts';
-export type { PackTransport, TwinPack } from './packRegistry.ts';
-
+export { clearRegistry, getPack, hasPack, listPacks, registerPack, pullPosture, assertContinuousPullAllowed, pullOnSchedule, resolvePullVendor, DEFAULT_PULL_POSTURE, DEFAULT_PULL_TRIGGER } from './packRegistry.ts';
+export type { PackTransport, PullPosture, PullTrigger, PullVendor, 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, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from './scenario.ts';
+export { WORLD_CLOCK_ENV, worldNow } from './world-clock.ts';
+export { createTwinFetchFromHandler } from './twin-fetch.ts';
+export type { RemoteExecute, RemoteExecuteRequest, RemoteExecuteResponse } from './remote-execute.ts';
+export type { TwinFetchAdapterConfig, TwinFetchHandlerRequest, TwinFetchHandlerResult } from './twin-fetch.ts';
+export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, 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,
@@ -61,6 +103,8 @@ export {
   diffSubjectFields,
   hashFieldValue,
   recordObservedDelta,
+  remoteRefs,
+  subjectKey,
 } from './shadow.ts';
 export type {
   DeltaObservation,
@@ -82,6 +126,7 @@ export {
   listEvents,
   listQueuedEvents,
   loadState,
+  projectionLockPath,
   readJsonFile,
   rebuildGenericState,
   rebuildState,
@@ -90,6 +135,10 @@ export {
   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).
@@ -108,6 +157,30 @@ export type {
   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';
+// 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,
+} from './blob-store.ts';
+export type { BlobStore } from './blob-store.ts';
 export {
   loadPollCursor,
   pollCursorPath,
@@ -135,12 +208,20 @@ export type {
 } from './validate.ts';
 export {
   applyTwinWrite,
+  applyTwinWriteAtomic,
   createTwinServer,
+  journalTwinRequest,
   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';
@@ -170,6 +251,7 @@ export { createVisualizerServer, renderTwinHtml } from './visualizer.ts';
 export {
   appendAction,
   appendTransactionCommit,
+  checkPrecondition,
   confirmAction,
   listActions,
   listTransactionCommits,
@@ -177,6 +259,7 @@ export {
   pendingEmits,
   pendingTransactionCommits,
   projectResources,
+  revertAction,
   TwinActionPreconditionError,
 } from './actions.ts';
 export type {
@@ -212,11 +295,61 @@ export {
   supersedeQueueRow,
 } from './queueLifecycle.ts';
 export type { QueueCounts, QueueRowStatus, QueueRowWithStatus, QueueStatusTransition } from './queueLifecycle.ts';
-export { abandonPush, appendPushRecord, latestPushByActionId, listPushLedger, pushTransaction, unconfirmedPushes, UnreconciledPushError } from './pushLedger.ts';
+export { abandonPush, appendPushRecord, assertFastForward, latestPushByActionId, listPushLedger, NonFastForwardPushError, pushTransaction, unconfirmedPushes, UnreconciledPushError } from './pushLedger.ts';
 export type { PushOutcome, PushStatus, WorldPushRecord } from './pushLedger.ts';
 export { acquireLease, activeLease, isLeaseActive, LeaseHeldError, listLeases, releaseLease } from './lease.ts';
 export type { WorldApplyLease } from './lease.ts';
-export { applyPlan, buildApplyPlan, listPlans, pendingConflicts, planRequiresApproval, readPlan, writePlan } from './plan.ts';
-export type { ActionMapper, ApplyResult, ProviderCall, WorldApplyPlan } from './plan.ts';
+export { applyPlan, approvedPendingActionSet, assertPendingActionsApproved, buildApplyPlan, buildLocalActionPlan, latestPlanReview, listPlanReviews, listPlans, pendingConflicts, planRequiresApproval, readPlan, recordPlanReview, transactionSetId, writePlan } from './plan.ts';
+export type { ActionMapper, ApplyResult, ApprovedPendingActionSet, LocalActionPlan, PlanReviewDecision, PlanReviewRecord, ProviderCall, WorldApplyPlan } from './plan.ts';
 export { formatStatus, worldStatus } from './status.ts';
 export type { WorldStatus } from './status.ts';
+// The CHANGESET primitive + the ledger DIFF (docs/OPERATIONAL_VCS.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,
+  formatChangeset,
+  formatChangesetStatus,
+  formatLedgerDelta,
+  formatReplayReport,
+  formatVerification,
+  MARKER_KIND,
+  normalizeChangeset,
+  parseVerifierExpression,
+  replayChangeset,
+  runChangesetVerifiers,
+  summarizeByVendor,
+  twinWriteShape,
+  withVerification,
+  worldBootMarker,
+  WORLD_BOOT_MARKER_ID,
+} from './changeset.ts';
+export type {
+  Changeset,
+  ChangesetAction,
+  ChangesetApproval,
+  ChangesetReadiness,
+  ChangesetVerification,
+  ChangesetVerifier,
+  ChangesetVerifierResult,
+  LedgerDelta,
+  LedgerPosition,
+  LedgerRef,
+  ReplayActionResult,
+  ReplayReport,
+  ReplayTarget,
+  VendorSummary,
+  WorldMarker,
+} from './changeset.ts';

package/src/lease.ts

@@ -3,10 +3,10 @@
 // divergent histories onto the same remote baseline. Invariant: at most one active
 // (unreleased, unexpired) lease per (provider, remoteRef.name). Deterministic:
 // caller supplies id/acquiredAt/expiresAt and `now` for expiry checks (no clock).
-import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { WorldRemoteRef } from './refs.ts';
 import { readJsonFile, withFileLock, worldPaths } from './storage.ts';
+import { getActiveWorldStore } from './world-store.ts';
 
 export type WorldApplyLease = {
   id: string;
@@ -44,8 +44,7 @@ function acquireLockPath(service: string, root?: string): string {
 
 export function listLeases(service: string, root?: string): WorldApplyLease[] {
   const dir = leasesDir(service, root);
-  if (!existsSync(dir)) return [];
-  return readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => readJsonFile<WorldApplyLease>(join(dir, f)));
+  return getActiveWorldStore().list(dir).filter((f) => f.endsWith('.json')).map((f) => readJsonFile<WorldApplyLease>(join(dir, f)));
 }
 
 export function isLeaseActive(lease: WorldApplyLease, now: string): boolean {
@@ -59,8 +58,7 @@ export function activeLease(service: string, provider: string, refName: string,
 
 function writeLease(lease: WorldApplyLease, root?: string): WorldApplyLease {
   const path = leasePath(lease.service, lease.id, root);
-  mkdirSync(join(path, '..'), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(lease, null, 2)}\n`);
+  getActiveWorldStore().write(path, `${JSON.stringify(lease, null, 2)}\n`);
   return lease;
 }
 
@@ -91,7 +89,7 @@ export function acquireLease(
 
 export function releaseLease(service: string, id: string, opts: { root?: string; at?: string } = {}): WorldApplyLease {
   const path = leasePath(service, id, opts.root);
-  if (!existsSync(path)) throw new Error(`no such lease: ${id}`);
+  if (!getActiveWorldStore().exists(path)) throw new Error(`no such lease: ${id}`);
   const lease = readJsonFile<WorldApplyLease>(path);
   return writeLease({ ...lease, releasedAt: opts.at ?? new Date().toISOString() }, opts.root);
 }

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 Bun.sleep(IDLE_SLEEP_MS);
+}

package/src/packRegistry.ts

@@ -7,12 +7,170 @@
 //
 // This is an optional convenience, NOT a kernel that defines the twin: a pack can
 // ignore the registry entirely. Pure + deterministic.
-export type PackTransport = 'rest' | 'graphql' | 'web-api';
+import { declareRateBudget, type RateBudgetDeclaration } from './rateBudget.ts';
+import type { TwinEmitter } from './emit.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).
+ */
+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 `qstash.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 TwinPack = {
   /** vendor id / service, e.g. 'stripe'. */
   vendor: string;
   transport: PackTransport;
+  /** The serve-family (see PackArchetype). Every pack declares one. */
+  archetype?: PackArchetype;
   /** subject types the twin serves, e.g. ['customer','charge','payment_intent']. */
   resources: string[];
   /** the `world-<vendor>` operator bin, if any. */
@@ -30,13 +188,101 @@ export type TwinPack = {
    *  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[];
+  };
+  /**
+   * 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;
+  /**
+   * 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;
 };
 
 const registry = new Map<string, TwinPack>();
 
-/** Register (or replace) a pack descriptor. Returns it. */
+/** 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);
   registry.set(pack.vendor, pack);
   return pack;
 }