@volter/world-core 2.0.37 → 3.0.1

package/src/packRegistry.ts

@@ -9,7 +9,10 @@
 // ignore the registry entirely. Pure + deterministic.
 import { declareRateBudget, type RateBudgetDeclaration } from './rateBudget.ts';
 import type { TwinAuthStrategy } from './executor.ts';
-import { registerReferences, type ReferenceDeclaration } from './references.ts';
+import { referenceField, registerReferences, type ReferenceDeclaration } from './references.ts';
+import { deriveStateSystem, deriveVendorStateSystem } from './derived-real.ts';
+import type { DerivedManifest, VendorManifest } from './derived-core.ts';
+import type { DerivedSurface } from './derived.ts';
 import type { TwinEmitter } from './emit.ts';
 import { registerAuthStrategy, registerStateSystem, type StateSystemAdapters } from './state-system.ts';
 
@@ -20,13 +23,13 @@ import { registerAuthStrategy, registerStateSystem, type StateSystemAdapters } f
  * `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';
@@ -35,7 +38,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
@@ -48,22 +51,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 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. */
-export function protocolStanding(declared: string | undefined): { major: number; standing: 'current' | 'deprecated' | 'refused' | 'assumed' } {
-  // undeclared: written before a pack could say — the previous major once there is one, and
-  // deprecated like any pack on it; the current major only while it is the first
-  if (declared === undefined) return PROTOCOL_MAJOR > 1 ? { major: PROTOCOL_MAJOR - 1, standing: 'deprecated' } : { major: PROTOCOL_MAJOR, standing: 'assumed' };
-  const major = Number(String(declared).split('.')[0]);
-  if (!Number.isInteger(major) || major < 1) return { major: Number.NaN, standing: 'refused' };
-  if (major === PROTOCOL_MAJOR) return { major, standing: 'current' };
-  if (major === PROTOCOL_MAJOR - 1) return { major, standing: 'deprecated' };
-  return { major, standing: 'refused' };
+/** Where a package's declared protocol stands against this kernel: `current`, or `refused`. */
+export function protocolStanding(declared: string | undefined): { major: number; standing: 'current' | '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'] as const;
@@ -176,8 +173,7 @@ export async function pullOnSchedule<T>(vendor: PullVendor, pull: () => Promise<
  * 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
@@ -192,196 +188,71 @@ export type HostRule = ({ host: string } | { suffix: string } | { hostPattern: s
 
 export type RoundTripWrite = { method: string; path: string; 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'. */
+  // Each field is defined once, in docs/contributing/architecture.md, "The descriptor"; a field is added there first.
   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; 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 };
 };
 
+/** 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'>;
+
 const registry = new Map<string, TwinPack>();
 
 /** Register (or replace) a pack descriptor. Returns it.
@@ -390,8 +261,49 @@ const registry = new Map<string, TwinPack>();
  *  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: { 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 {
+  if (!manifest.descriptor) throw new Error(`${manifest.vendor}: the manifest declares no descriptor (architecture, "The descriptor")`);
+  const hand = (['stateSystem', 'references', 'rateBudget'] as const).filter((k) => (manifest.descriptor as Record<string, unknown>)[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: TwinPack = { 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 as Record<string, { manifest: DerivedManifest; surface: DerivedSurface }>);
+  const units = lanes ? Object.values(lanes).map((l) => l.manifest) : [manifest as unknown as DerivedManifest, ...Object.values(beside).map((l) => l.manifest)];
+  const references = units.flatMap(derivedReferences);
+  return {
+    ...pack,
+    stateSystem: lanes ? deriveVendorStateSystem(manifest as unknown as VendorManifest, lanes) : deriveStateSystem(manifest as unknown as DerivedManifest, surface as DerivedSurface, 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: DerivedManifest): ReferenceDeclaration[] {
+  const stored = (r: string): string => m.resources[r]?.storedAs ?? r;
+  const out: ReferenceDeclaration[] = [];
+  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: TwinPack): TwinPack {
   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) registerStateSystem(pack.vendor, pack.stateSystem);
   if (pack.auth) registerAuthStrategy(pack.vendor, pack.auth);

package/src/people.ts

@@ -0,0 +1,31 @@
+// The people a vendor's pages sign in (docs/contributing/architecture.md, "Who is on a screen"): a person is a `_person`
+// row, `person:<email>`, keeping their password's hash, never the password, written by a sign-up door or page and read
+// by a sign-in, the same way in every pack. World-ui's session kit signs them in.
+import type { HandlerContext } from './derived-core.ts';
+import { digest } from './signing.ts';
+
+/** 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 };
+
+const PERSON = '_person';
+
+/** A password as a World keeps it: its hash, salted by whose it is. */
+export const passwordHash = (email: string, password: string): string => 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: HandlerContext, email: string, password: string, fields: Record<string, unknown> = {}): Promise<Person> {
+  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: HandlerContext, email: string): Person | undefined =>
+  ctx.rowsRaw(PERSON).find((p) => p.email === email.trim().toLowerCase()) as Person | undefined;
+
+/** The person whose email and password these are, or undefined. */
+export function personWith(ctx: HandlerContext, email: string, password: string): Person | undefined {
+  const person = personOf(ctx, email);
+  return person && person.password_sha256 === passwordHash(person.email, password) ? person : undefined;
+}

package/src/placeholder-image.ts

@@ -0,0 +1,88 @@
+// 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.ts';
+
+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: Uint8Array): number => { let c = 0xffffffff; for (const x of b) c = CRC[(c ^ x) & 0xff]! ^ (c >>> 8); return (c ^ 0xffffffff) >>> 0; };
+
+function chunk(type: string, data: Uint8Array): Uint8Array {
+  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 {
+  private out: number[] = [];
+  private acc = 0;
+  private n = 0;
+  put(value: number, count: number): void { 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: number, length: number): void { for (let i = length - 1; i >= 0; i--) this.put((code >> i) & 1, 1); }
+  bytes(): number[] { 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: Bits, b: number): void => (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: Bits, length: number): void {
+  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: number, height: number, rgb: [number, number, number]): Uint8Array {
+  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: { width: number; height: number }, seed: string, label = `placeholder image, no model is run: ${seed}`): Uint8Array {
+  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;
+}