@volter/world-core 2.0.37 → 3.0.0

package/dist/src/packRegistry.d.ts

@@ -1,6 +1,8 @@
 import { type RateBudgetDeclaration } from './rateBudget.js';
 import type { TwinAuthStrategy } from './executor.js';
 import { type ReferenceDeclaration } from './references.js';
+import type { DerivedManifest } from './derived-core.js';
+import type { DerivedSurface } from './derived.js';
 import type { TwinEmitter } from './emit.js';
 import { type StateSystemAdapters } from './state-system.js';
 /**
@@ -10,13 +12,13 @@ import { type StateSystemAdapters } from './state-system.js';
  * `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` (a line protocol)
- * is the first; `packages/twin/temporal` (gRPC: HTTP/2 framing its clients drive themselves) the
+ * entry" is STRUCTURAL rather than a missing wiring point. `@volter/twin-smtp` (a line protocol)
+ * is the first; `@volter/twin-temporal` (gRPC: HTTP/2 framing its clients drive themselves) the
  * second.
  *
  * 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
+ * A2, "the kernel does not branch on vendor identity" (`scripts/architecture-auto.ts`), forbids. The
  * specific protocol belongs on the pack's own `specSource`/`description`.
  */
 export type PackTransport = 'rest' | 'graphql' | 'web-api' | 'raw-tcp';
@@ -24,7 +26,7 @@ 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.
+ * own field, screens are the manifest's, 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
@@ -37,16 +39,16 @@ export type PackTransport = 'rest' | 'graphql' | 'web-api' | 'raw-tcp';
  */
 /** 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";
+ *  written against, and the build form it is made in (the derived pack); a change that removes or
+ *  alters a required shape bumps it, an additive change bumps minor. A package declares the major
+ *  it targets (`protocol`), and the kernel serves its own major and no other: a package that
+ *  declares another, or none, is refused. */
+export declare const PROTOCOL_VERSION = "3.0";
 export declare const PROTOCOL_MAJOR: number;
-/** Where a package's declared protocol stands against this kernel. */
+/** Where a package's declared protocol stands against this kernel: `current`, or `refused`. */
 export declare function protocolStanding(declared: string | undefined): {
     major: number;
-    standing: 'current' | 'deprecated' | 'refused' | 'assumed';
+    standing: 'current' | 'refused';
 };
 export declare const PACK_ARCHETYPES: readonly ["crud", "generative", "signed-protocol", "engine-control", "proxy"];
 export type PackArchetype = (typeof PACK_ARCHETYPES)[number];
@@ -123,8 +125,7 @@ export declare function pullOnSchedule<T>(vendor: PullVendor, pull: () => Promis
  * 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
+ * vendor id (aws's one twin answers under s3 and secretsmanager); 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
@@ -148,186 +149,95 @@ export type RoundTripWrite = {
     body?: unknown;
     headers?: Record<string, string>;
 };
+/** A pack's descriptor: docs/contributing/architecture.md, "The descriptor". */
 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). */
+        configFiles?: Array<{
+            file: string;
+            usage: 'application' | 'build' | 'deployment';
+            when?: string;
+        }>;
         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.
-     */
+    /** The door that issues the application the credentials the twin will accept (a key made on the vendor's dashboard,
+     *  and whatever names it: a database's URL, a project's id), and the env names it fills, each from a field of the
+     *  answer: `init` writes `$issue:<service>` for each, and `up`, once this twin is running, POSTs the body to the door
+     *  and sets each name to its field. A twin that holds its keys (refusing any it
+     *  did not issue) declares one, so a World's applications hold keys it issued rather than fixtures it refuses. */
+    credentialDoor?: {
+        path: string;
+        body: Record<string, unknown>;
+        fill: Record<string, string>;
+    };
+    /** Another pack of this vendor issues the API's credentials; architecture, descriptor World wiring. */
+    credentialIssuer?: string;
     prismaAdapter?: {
         adapter: string;
         export: string;
         urlEnv: string;
     };
-    /**
-     * THE WORLD'S MANAGED DATABASE — the declared exception to kernel-held state (docs/contributing/architecture.md,
-     * managed infrastructure: "A vendor whose data plane is a server in front of Postgres"): the pack's data plane is
-     * served over the World's own managed Postgres, which the runtime binds as DATA, never through the environment. At
-     * boot the runtime hands the connection URL of the World's managed `kind` service to the twin: `serve <arg> <url>` on
-     * the spawn path, the factory's `database` option in the colocated host. A World whose database is not its own
-     * managed infrastructure (none declared, or a URL outside it) binds nothing, and the twin refuses its data plane.
-     */
+    managedService?: {
+        kind: 'redis' | 'mongodb';
+        scheme: string;
+        note: string;
+    };
     managedDatabase?: {
         kind: 'postgres';
         arg: string;
         note: 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. */
+    sidePorts?: Array<{
+        name: string;
+        option: string;
+        flag: string;
+        path?: string;
+        note: string;
+    }>;
     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`. */
+    /** The pack has no vendor-backed half, and why (copied from the manifest by packOf). */
+    vendorBacked?: {
+        none: string;
+    };
     refresh?: {
         every?: string;
         webhook?: boolean;
@@ -335,51 +245,48 @@ export type TwinPack = {
             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;
     };
 };
+/** The descriptor a pack declares as data in its manifest (docs/contributing/architecture.md, "The descriptor"): the
+ *  pack's fields without the ones that are code or that the derived core supplies (the state system and refresh, round
+ *  trips and references, parity, a rate budget, the emitter, conformance fields, the engine key, pull posture). */
+export type PackDescriptor = Omit<TwinPack, 'stateSystem' | 'refresh' | 'refreshRefusal' | 'roundTrip' | 'references' | 'referenceTrip' | 'parityOrigin' | 'shapeParity' | 'rateBudget' | 'emitter' | 'conformanceFields' | 'engine' | 'pullPosture' | 'pullPostureReason'>;
 /** 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. */
+/** A derived pack's descriptor, from its manifest (`manifest.descriptor`, named by the manifest's `vendor`). Given the
+ *  pack's generated surface (a vendor of lanes: each lane's manifest and surface), the kernel derives what a pack never
+ *  writes by hand (the real-system adapters, "Where it lives"): its state system (perform, refresh, ingest), the
+ *  references its subjects hold (from the manifest's `embeds` and each `parent.field` naming its parent by id) and its
+ *  rate budget (the manifest's). A descriptor that declares any of them by hand is refused. */
+export declare function packOf(manifest: {
+    vendor: string;
+    descriptor?: Omit<TwinPack, 'vendor'>;
+} & Partial<Pick<DerivedManifest, 'rateBudget' | 'vendorBacked'>>, surface?: DerivedSurface | Record<string, {
+    manifest: DerivedManifest;
+    surface: DerivedSurface;
+}>, 
+/** the lanes beside a pack that has an API of its own */
+beside?: Record<string, {
+    manifest: DerivedManifest;
+    surface: DerivedSurface;
+}>): TwinPack;
 export declare function registerPack(pack: TwinPack): TwinPack;
 export declare function getPack(vendor: string): TwinPack | undefined;
 /** All registered packs, sorted by vendor (deterministic). */

package/dist/src/packRegistry.js

@@ -8,13 +8,14 @@
 // 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 { referenceField, registerReferences } from "./references.js";
+import { deriveStateSystem, deriveVendorStateSystem } from "./derived-real.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.
+ * own field, screens are the manifest's, 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
@@ -27,26 +28,16 @@ import { registerAuthStrategy, registerStateSystem } from "./state-system.js";
  */
 /** 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';
+ *  written against, and the build form it is made in (the derived pack); a change that removes or
+ *  alters a required shape bumps it, an additive change bumps minor. A package declares the major
+ *  it targets (`protocol`), and the kernel serves its own major and no other: a package that
+ *  declares another, or none, is refused. */
+export const PROTOCOL_VERSION = '3.0';
 export const PROTOCOL_MAJOR = Number(PROTOCOL_VERSION.split('.')[0]);
-/** Where a package's declared protocol stands against this kernel. */
+/** Where a package's declared protocol stands against this kernel: `current`, or `refused`. */
 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' };
+    const major = declared === undefined ? Number.NaN : Number(String(declared).split('.')[0]);
+    return major === PROTOCOL_MAJOR ? { major, standing: 'current' } : { 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. */
@@ -112,9 +103,53 @@ const registry = new Map();
  *  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. */
+/** A derived pack's descriptor, from its manifest (`manifest.descriptor`, named by the manifest's `vendor`). Given the
+ *  pack's generated surface (a vendor of lanes: each lane's manifest and surface), the kernel derives what a pack never
+ *  writes by hand (the real-system adapters, "Where it lives"): its state system (perform, refresh, ingest), the
+ *  references its subjects hold (from the manifest's `embeds` and each `parent.field` naming its parent by id) and its
+ *  rate budget (the manifest's). A descriptor that declares any of them by hand is refused. */
+export function packOf(manifest, surface, 
+/** the lanes beside a pack that has an API of its own */
+beside = {}) {
+    if (!manifest.descriptor)
+        throw new Error(`${manifest.vendor}: the manifest declares no descriptor (architecture, "The descriptor")`);
+    const hand = ['stateSystem', 'references', 'rateBudget'].filter((k) => manifest.descriptor[k] !== undefined);
+    if (hand.length)
+        throw new Error(`${manifest.vendor}: the descriptor declares ${hand.join(', ')} by hand; the kernel derives them from the manifest (architecture, "The real-system adapters")`);
+    const pack = { vendor: manifest.vendor, ...manifest.descriptor, ...(manifest.rateBudget ? { rateBudget: manifest.rateBudget } : {}) };
+    // a pack with no vendor-backed half says why, and derives no adapters
+    if (manifest.vendorBacked?.none)
+        return { ...pack, vendorBacked: { none: manifest.vendorBacked.none } };
+    if (!surface)
+        return pack;
+    const lanes = 'operations' in surface ? undefined : surface;
+    const units = lanes ? Object.values(lanes).map((l) => l.manifest) : [manifest, ...Object.values(beside).map((l) => l.manifest)];
+    const references = units.flatMap(derivedReferences);
+    return {
+        ...pack,
+        stateSystem: lanes ? deriveVendorStateSystem(manifest, lanes) : deriveStateSystem(manifest, surface, beside),
+        ...(references.length ? { references } : {}),
+    };
+}
+/** The references a derived manifest's subjects hold: each `embeds` field naming another resource, and each child's
+ *  `parent.field` when it holds the parent's id (a `value` template joins several parameters, so it holds no one id). */
+function derivedReferences(m) {
+    const stored = (r) => m.resources[r]?.storedAs ?? r;
+    const out = [];
+    for (const [resource, decl] of Object.entries(m.resources)) {
+        for (const [field, to] of Object.entries(decl.embeds ?? {}))
+            if (m.resources[to])
+                out.push(referenceField(stored(resource), field, stored(to)));
+        if (decl.parent && !decl.parent.value && !decl.parent.where && m.resources[decl.parent.resource])
+            out.push(referenceField(stored(resource), decl.parent.field, stored(decl.parent.resource)));
+    }
+    return out;
+}
 export function registerPack(pack) {
     if (!/^[a-z0-9-]+$/.test(pack.vendor))
         throw new Error(`invalid pack vendor id: ${pack.vendor}`);
+    if (protocolStanding(pack.protocol).standing !== 'current')
+        throw new Error(`${pack.vendor}: protocol ${pack.protocol ?? '(missing)'} refused; this kernel serves ${PROTOCOL_VERSION}`);
     if (pack.rateBudget)
         declareRateBudget(pack.vendor, pack.rateBudget);
     if (pack.stateSystem)

package/dist/src/people.d.ts

@@ -0,0 +1,13 @@
+import type { HandlerContext } from './derived-core.js';
+/** A person a vendor's pages know: their email, and whatever the vendor's sign-up keeps beside it. */
+export type Person = Record<string, unknown> & {
+    email: string;
+};
+/** A password as a World keeps it: its hash, salted by whose it is. */
+export declare const passwordHash: (email: string, password: string) => string;
+/** A person, their password's hash and the fields the vendor's sign-up keeps, recorded. */
+export declare function recordPerson(ctx: HandlerContext, email: string, password: string, fields?: Record<string, unknown>): Promise<Person>;
+/** The person with this email, or undefined. */
+export declare const personOf: (ctx: HandlerContext, email: string) => Person | undefined;
+/** The person whose email and password these are, or undefined. */
+export declare function personWith(ctx: HandlerContext, email: string, password: string): Person | undefined;

package/dist/src/people.js

@@ -0,0 +1,18 @@
+import { digest } from "./signing.js";
+const PERSON = '_person';
+/** A password as a World keeps it: its hash, salted by whose it is. */
+export const passwordHash = (email, password) => digest('sha256', `password:${email.toLowerCase()}:${password}`);
+/** A person, their password's hash and the fields the vendor's sign-up keeps, recorded. */
+export async function recordPerson(ctx, email, password, fields = {}) {
+    const lower = email.toLowerCase();
+    const person = { ...fields, email: lower, password_sha256: passwordHash(lower, password) };
+    await ctx.record(PERSON, person, `person:${lower}`);
+    return person;
+}
+/** The person with this email, or undefined. */
+export const personOf = (ctx, email) => ctx.rowsRaw(PERSON).find((p) => p.email === email.trim().toLowerCase());
+/** The person whose email and password these are, or undefined. */
+export function personWith(ctx, email, password) {
+    const person = personOf(ctx, email);
+    return person && person.password_sha256 === passwordHash(person.email, password) ? person : undefined;
+}

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

@@ -0,0 +1,5 @@
+/** A real PNG of `size`, one flat colour drawn from `seed`, its tEXt Comment `[twin-stub] <label>`. */
+export declare function placeholderPng(size: {
+    width: number;
+    height: number;
+}, seed: string, label?: string): Uint8Array;

package/dist/src/placeholder-image.js

@@ -0,0 +1,114 @@
+// A placeholder image (architecture, "A placeholder image is a kernel library too"): a real PNG of the size asked for, in
+// one flat colour drawn from a seed, labeled in a tEXt chunk as the twin's, for generative packs that run no model.
+// Importing it does nothing.
+//
+// The image data is a zlib stream (RFC 1950) of one fixed-Huffman deflate block (RFC 1951 §3.2.6): each row is the Sub
+// filter (PNG §9.2, type 1), its first pixel as literals and the rest zeros, the zeros as a literal and then copies of
+// distance 1. A flat image of any size is a few kilobytes.
+import { sha256 } from "./signing.js";
+const SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+const CRC = Array.from({ length: 256 }, (_, n) => { let c = n; for (let k = 0; k < 8; k++)
+    c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; return c >>> 0; });
+const crc32 = (b) => { let c = 0xffffffff; for (const x of b)
+    c = CRC[(c ^ x) & 0xff] ^ (c >>> 8); return (c ^ 0xffffffff) >>> 0; };
+function chunk(type, data) {
+    const out = new Uint8Array(12 + data.length);
+    const v = new DataView(out.buffer);
+    v.setUint32(0, data.length);
+    out.set([...type].map((c) => c.charCodeAt(0)), 4);
+    out.set(data, 8);
+    v.setUint32(8 + data.length, crc32(out.subarray(4, 8 + data.length)));
+    return out;
+}
+/** Deflate's bits, least significant first; a Huffman code is written most significant bit first. */
+class Bits {
+    out = [];
+    acc = 0;
+    n = 0;
+    put(value, count) { for (let i = 0; i < count; i++) {
+        this.acc |= ((value >> i) & 1) << this.n;
+        if (++this.n === 8) {
+            this.out.push(this.acc);
+            this.acc = 0;
+            this.n = 0;
+        }
+    } }
+    code(code, length) { for (let i = length - 1; i >= 0; i--)
+        this.put((code >> i) & 1, 1); }
+    bytes() { return this.n ? [...this.out, this.acc] : this.out; }
+}
+/** A literal byte in the fixed code: 0–143 are 8 bits from 0x30, 144–255 are 9 bits from 0x190. */
+const literal = (w, b) => (b < 144 ? w.code(0x30 + b, 8) : w.code(0x190 + b - 144, 9));
+/** A copy of `length` (3–258) bytes at distance 1: length codes 257–285 (7 bits from 0 for 256–279, 8 bits from 0xc0 for
+ *  280–287) with their extra bits, then distance code 0 (5 bits, distance 1). */
+const LENGTH_BASE = [3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 15, 17, 19, 23, 27, 31, 35, 43, 51, 59, 67, 83, 99, 115, 131, 163, 195, 227, 258];
+const LENGTH_EXTRA = [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 0];
+function copy(w, length) {
+    let i = LENGTH_BASE.length - 1;
+    while (LENGTH_BASE[i] > length)
+        i--;
+    const symbol = 257 + i;
+    if (symbol < 280)
+        w.code(symbol - 256, 7);
+    else
+        w.code(0xc0 + symbol - 280, 8);
+    w.put(length - LENGTH_BASE[i], LENGTH_EXTRA[i]);
+    w.code(0, 5);
+}
+function flatIdat(width, height, rgb) {
+    const w = new Bits();
+    w.put(1, 1);
+    w.put(1, 2); // the last block, fixed Huffman
+    const zeros = (width - 1) * 3;
+    for (let y = 0; y < height; y++) {
+        literal(w, 1);
+        for (const c of rgb)
+            literal(w, c);
+        if (zeros > 0) {
+            literal(w, 0);
+            let left = zeros - 1;
+            while (left > 0) {
+                const n = left > 258 ? (left - 258 < 3 ? left - 3 : 258) : left;
+                if (n < 3) {
+                    for (let k = 0; k < n; k++)
+                        literal(w, 0);
+                    left -= n;
+                    continue;
+                }
+                copy(w, n);
+                left -= n;
+            }
+        }
+    }
+    w.code(0, 7); // end of block (256)
+    // Adler-32 of the raw rows: a zero byte leaves a as it is and adds a to b
+    let a = 1;
+    let b = 0;
+    for (let y = 0; y < height; y++) {
+        for (const byte of [1, ...rgb]) {
+            a = (a + byte) % 65521;
+            b = (b + a) % 65521;
+        }
+        b = (b + a * zeros) % 65521;
+    }
+    return Uint8Array.from([0x78, 0x01, ...w.bytes(), (b >> 8) & 0xff, b & 0xff, (a >> 8) & 0xff, a & 0xff]);
+}
+/** A real PNG of `size`, one flat colour drawn from `seed`, its tEXt Comment `[twin-stub] <label>`. */
+export function placeholderPng(size, seed, label = `placeholder image, no model is run: ${seed}`) {
+    const [r, g, bl] = Buffer.from(sha256(seed), 'hex');
+    const ihdr = new Uint8Array(13);
+    const v = new DataView(ihdr.buffer);
+    v.setUint32(0, size.width);
+    v.setUint32(4, size.height);
+    ihdr.set([8, 2, 0, 0, 0], 8); // 8-bit RGB, no interlace
+    // tEXt is Latin-1 without NUL: a label's other characters (a prompt's) are written as `?`
+    const text = Uint8Array.from(`Comment\0[twin-stub] ${label.replace(/[^\x20-\x7e\xa0-\xff]/g, '?')}`, (c) => c.charCodeAt(0));
+    const parts = [Uint8Array.from(SIGNATURE), chunk('IHDR', ihdr), chunk('tEXt', text), chunk('IDAT', flatIdat(size.width, size.height, [r, g, bl])), chunk('IEND', new Uint8Array(0))];
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const p of parts) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+}