@volter/world-core 2.0.0

package/dist/src/packRegistry.d.ts

@@ -0,0 +1,374 @@
+import { type RateBudgetDeclaration } from './rateBudget.js';
+import type { TwinAuthStrategy } from './executor.js';
+import { type ReferenceDeclaration } from './references.js';
+import type { TwinEmitter } from './emit.js';
+import { type StateSystemAdapters } from './state-system.js';
+/**
+ * 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 declare const PROTOCOL_VERSION = "2.0";
+export declare const PROTOCOL_MAJOR: number;
+/** Where a package's declared protocol stands against this kernel. */
+export declare function protocolStanding(declared: string | undefined): {
+    major: number;
+    standing: 'current' | 'deprecated' | 'refused' | 'assumed';
+};
+export declare const PACK_ARCHETYPES: readonly ["crud", "generative", "signed-protocol", "engine-control", "proxy"];
+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 declare const DEFAULT_PULL_POSTURE: PullPosture;
+/** A pack's effective posture — its declaration, or the conservative default. */
+export declare function pullPosture(pack: Pick<TwinPack, 'pullPosture'>): PullPosture;
+/**
+ * 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 declare const DEFAULT_PULL_TRIGGER: PullTrigger;
+/** Resolve a `PullVendor` to the descriptor whose posture governs it. Unregistered ⇒ no posture. */
+export declare function resolvePullVendor(vendor: PullVendor): Pick<TwinPack, 'vendor' | 'pullPosture'>;
+/**
+ * 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 declare function assertContinuousPullAllowed(vendor: PullVendor): void;
+/**
+ * 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 declare function pullOnSchedule<T>(vendor: PullVendor, pull: () => Promise<T>): Promise<T>;
+/**
+ * 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;
+    };
+};
+/** 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 declare function registerPack(pack: TwinPack): TwinPack;
+export declare function getPack(vendor: string): TwinPack | undefined;
+/** All registered packs, sorted by vendor (deterministic). */
+export declare function listPacks(): TwinPack[];
+export declare function hasPack(vendor: string): boolean;
+/** Clear the registry (tests). */
+export declare function clearRegistry(): void;

package/dist/src/packRegistry.js

@@ -0,0 +1,142 @@
+// 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 } from "./rateBudget.js";
+import { registerReferences } from "./references.js";
+import { registerAuthStrategy, registerStateSystem } from "./state-system.js";
+/**
+ * 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) {
+    // 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'];
+/** The posture to assume for a pack that doesn't declare one. Conservative on purpose. */
+export const DEFAULT_PULL_POSTURE = 'on-demand';
+/** A pack's effective posture — its declaration, or the conservative default. */
+export function pullPosture(pack) {
+    return pack.pullPosture ?? DEFAULT_PULL_POSTURE;
+}
+/** The trigger to assume when a caller does not say. Conservative on purpose. */
+export const DEFAULT_PULL_TRIGGER = 'scheduled';
+/** Resolve a `PullVendor` to the descriptor whose posture governs it. Unregistered ⇒ no posture. */
+export function resolvePullVendor(vendor) {
+    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) {
+    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(vendor, pull) {
+    assertContinuousPullAllowed(vendor);
+    return pull();
+}
+const registry = new Map();
+/** 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) {
+    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) {
+    return registry.get(vendor);
+}
+/** All registered packs, sorted by vendor (deterministic). */
+export function listPacks() {
+    return [...registry.values()].sort((a, b) => a.vendor.localeCompare(b.vendor));
+}
+export function hasPack(vendor) {
+    return registry.has(vendor);
+}
+/** Clear the registry (tests). */
+export function clearRegistry() {
+    registry.clear();
+}

package/dist/src/placeholder-remote.d.ts

@@ -0,0 +1,22 @@
+import type { TwinAction } from './actions.js';
+import type { WorldServiceEvent } from './types.js';
+export declare const PLACEHOLDER_REMOTE = "placeholder";
+/** The window is per WORLD SERVICE ROOT, not per state service: a twin may record under a state
+ *  service that is not its world service id (slack records under `chat`), and every state service
+ *  of one twin lives under the same root — so the marker sits at the root's state dir. */
+export declare function placeholderPullMarkerPath(_service: string, root?: string): string;
+/** Is the service's placeholder-pull window open? */
+export declare function placeholderPullActive(service: string, root?: string): boolean;
+export declare function beginPlaceholderPull(service: string, root?: string, at?: string): void;
+export declare function endPlaceholderPull(service: string, root?: string): void;
+/** Open the window around `fn` (in-process seeding). */
+export declare function withPlaceholderPull<T>(service: string, root: string | undefined, fn: () => T | Promise<T>): Promise<T>;
+/** The observed events a local write becomes when it is a pull from the placeholder: the write's
+ *  own subject and fields, plus every resource its projection creates or updates. A projection
+ *  DELETE has no observed form (the placeholder holds what exists, not what was removed) and is
+ *  refused loudly — a seed creates the world, it does not un-create it. */
+export declare function placeholderEventsFor(action: TwinAction): WorldServiceEvent[];
+/** Land `action` as the placeholder's observed facts. Caller holds the service locks. */
+export declare function landAsPlaceholder(action: TwinAction, root?: string): {
+    events: WorldServiceEvent[];
+};

package/dist/src/placeholder-remote.js

@@ -0,0 +1,86 @@
+// THE PLACEHOLDER REMOTE (docs/concepts/the-model.md#a-branch-is-a-position-not-a-copy, "default data"): a fresh twin is a clone of the
+// coherent default data its pack ships, and that seed is a PULL, never a pending write. While a
+// service's placeholder-pull window is open — a marker file under its state dir, read through the
+// active world store like the world clock — every local `set` write the twin accepts lands as an
+// OBSERVED event from the placeholder (origin `virtual`, provenance `placeholder`) and no action row
+// is appended: `main` equals `origin/main` when the seed ends, `diff` is empty, nothing is pending,
+// and no real remote linked later is ever offered the seed. The placeholder has no origin and no
+// credential, so it can never be a push target; a pull from it again is "back to the defaults".
+import { appendParentEntry, toEntry } from "./log.js";
+import { join } from 'node:path';
+import { worldPaths, worldStateRoot } from "./storage.js";
+import { WorldServiceEventSchema } from "./schemas.js";
+import { hashFieldValue } from "./hash.js";
+import { getActiveWorldStore } from "./world-store.js";
+export const PLACEHOLDER_REMOTE = 'placeholder';
+/** The window is per WORLD SERVICE ROOT, not per state service: a twin may record under a state
+ *  service that is not its world service id (slack records under `chat`), and every state service
+ *  of one twin lives under the same root — so the marker sits at the root's state dir. */
+export function placeholderPullMarkerPath(_service, root) {
+    return join(worldStateRoot(root), 'placeholder-pull');
+}
+/** Is the service's placeholder-pull window open? */
+export function placeholderPullActive(service, root) {
+    return getActiveWorldStore().exists(placeholderPullMarkerPath(service, root));
+}
+export function beginPlaceholderPull(service, root, at = new Date().toISOString()) {
+    const path = placeholderPullMarkerPath(service, root);
+    const store = getActiveWorldStore();
+    store.mkdir(join(path, '..'));
+    store.write(path, `${JSON.stringify({ remote: PLACEHOLDER_REMOTE, openedAt: at })}\n`);
+}
+export function endPlaceholderPull(service, root) {
+    const path = placeholderPullMarkerPath(service, root);
+    if (getActiveWorldStore().exists(path))
+        getActiveWorldStore().remove(path);
+}
+/** Open the window around `fn` (in-process seeding). */
+export async function withPlaceholderPull(service, root, fn) {
+    beginPlaceholderPull(service, root);
+    try {
+        return await fn();
+    }
+    finally {
+        endPlaceholderPull(service, root);
+    }
+}
+/** The observed events a local write becomes when it is a pull from the placeholder: the write's
+ *  own subject and fields, plus every resource its projection creates or updates. A projection
+ *  DELETE has no observed form (the placeholder holds what exists, not what was removed) and is
+ *  refused loudly — a seed creates the world, it does not un-create it. */
+export function placeholderEventsFor(action) {
+    const observations = [];
+    if (action.fields)
+        observations.push({ subject: action.subject, fields: action.fields });
+    for (const c of action.projection?.creates ?? [])
+        observations.push({ subject: { type: c.type, id: c.id }, fields: c.fields });
+    for (const u of action.projection?.updates ?? [])
+        observations.push({ subject: { type: u.type, id: u.id }, fields: u.fields });
+    if (action.projection?.deletes?.length)
+        throw new Error(`placeholder pull: ${action.service} ${action.operation ?? action.op} deletes ${action.projection.deletes.map((d) => `${d.type}:${d.id}`).join(', ')} — a seed creates the placeholder world, it cannot remove from it`);
+    return observations.map((o) => {
+        const contentHash = hashFieldValue({ subject: o.subject, fields: o.fields, operation: action.operation ?? action.op });
+        const id = `placeholder:${action.service}:${o.subject.type}:${o.subject.id}:${contentHash}`;
+        return WorldServiceEventSchema.parse({
+            id,
+            service: action.service,
+            type: `${action.service}.${o.subject.type}.delta`,
+            schemaVersion: 1,
+            idempotencyKey: id,
+            occurredAt: action.occurredAt,
+            observedAt: action.occurredAt,
+            origin: 'virtual',
+            subject: o.subject,
+            data: { changed: Object.fromEntries(Object.entries(o.fields).map(([k, v]) => [k, { after: v }])), provenance: PLACEHOLDER_REMOTE, remote: PLACEHOLDER_REMOTE },
+        });
+    });
+}
+/** Land `action` as the placeholder's observed facts. Caller holds the service locks. */
+export function landAsPlaceholder(action, root) {
+    const paths = worldPaths(action.service, root);
+    const events = placeholderEventsFor(action);
+    // v2: the placeholder's rows land as ENTRIES on the parent log (one row kind), marked as the placeholder's
+    for (const event of events)
+        appendParentEntry({ ...toEntry(event), provenance: 'placeholder' }, root);
+    return { events };
+}

package/dist/src/proxy.d.ts

@@ -0,0 +1,25 @@
+/** How one vendor's browser SDK is routed to its twin. Supplied by the caller. */
+export interface VendorRoute {
+    /** The vendor's twin origin, e.g. http://127.0.0.1:12111 */
+    origin: string;
+    /** Same-origin browser API path that belongs to this vendor, e.g. '/v1/' */
+    apiPathPrefix: string;
+    /** Absolute API host to strip from the vendor's browser loader so calls become
+     *  same-origin (e.g. 'https://api.stripe.com'). Omit if the SDK already calls same-origin. */
+    loaderHost?: string;
+}
+export interface TwinProxyOptions {
+    /** Your app's origin, e.g. http://localhost:3000 */
+    target: string;
+    /** vendor → routing. */
+    map: Record<string, VendorRoute>;
+    /** Extra local service origins whose redirects should be rewritten back to this proxy origin. */
+    redirectOrigins?: string[];
+    /** Listen port (0 = ephemeral). */
+    port?: number;
+}
+export interface TwinProxy {
+    port: number;
+    stop(): void;
+}
+export declare function createTwinProxy(opts: TwinProxyOptions): TwinProxy;