@volter/world-core 2.0.37 → 3.0.1

package/dist/src/derived-core.d.ts

@@ -1,7 +1,23 @@
 import { type TwinResource } from './serve.js';
+import { GitObjectStore } from './git/objects.js';
+import { GitRefs } from './git/refs.js';
+import { type SocketDecl, type SocketSession } from './sockets.js';
+import { type MachinePool } from './machines.js';
+import { type ApplicationAnswer, type EventRender, type EventScheme, type EventsDecl, type EventValues } from './events.js';
+import type { RateBudgetDeclaration } from './rateBudget.js';
+import { type HandlerCrypto } from './signing.js';
+import { type ManagedDatabase } from './managed-database.js';
+import { type RedisDialect, type RunItem } from './redis/engine.js';
+import { type Mail, type SmtpRoute } from './smtp.js';
+import { type MultipartPart } from './multipart.js';
+import type { CorsDecl } from './cors.js';
 import type { DerivedCall, DerivedCoreOutcome, DerivedHandler, DerivedOperation } from './derived.js';
+import type { PackDescriptor } from './packRegistry.js';
+import type { ScenarioDecision, ScenarioHandler } from './scenario.js';
 /** How a stored field gets its value when the server assigns it. `now` is the world clock in the
  *  manifest's time format; `id` the subject's id; a `value` is stored as given. */
+/** A field the server assigns: the World clock's now, the subject's id, a fixed value, or a template over the stored
+ *  fields (and `{id}`), base64-encoded when `encode` says (GitHub's `node_id`: `05:Label{id}` in base64). */
 export type FieldRule = {
     now: true;
 } | {
@@ -10,6 +26,7 @@ export type FieldRule = {
     value: unknown;
 } | {
     template: string;
+    encode?: 'base64';
 };
 /** A move of one state field, as data. `operation` is the operationId that causes it (an update
  *  that requests `to` when absent); `from` the values it leaves; `effects` the other fields it writes;
@@ -28,7 +45,7 @@ export type Transition = {
     /** placeholders `{from}`, `{to}`, `{field}`, `{id}` */
     refusal?: {
         status: number;
-        code?: string;
+        code?: string | number;
         message: string;
     };
     /** a refusal of its own for a particular current value (an invoice already `paid`) */
@@ -67,6 +84,16 @@ export type ResourceDecl = {
     /** the tree's subject type, when it differs from the resource name */
     storedAs?: string;
     idPrefix: string;
+    /** a setting held once per parent at a path of its own (`/v1/projects/{ref}/config/auth`, GET and PATCH, which the
+     *  surface names by the schema its GET answers): keyed by the path's parameter, it answers `defaults` under what was
+     *  written until first written, and an update merges into it, making it on first write */
+    setting?: {
+        defaults: Record<string, unknown>;
+    };
+    /** this resource's id template, when it is not the manifest's (`ids.template`): `{uuid}`, `{letters:20}` (twenty
+     *  lowercase letters, a Supabase project ref), `{snowflake:<epoch ms>}` (Discord's ids), or a `{prefix}`/`{n}`
+     *  template */
+    ids?: string;
     /** fields the server assigns on create */
     assigned?: Record<string, FieldRule>;
     state?: Record<string, StateField>;
@@ -96,17 +123,19 @@ export type ResourceDecl = {
     number?: {
         field: string;
     };
-    /** how this resource renders a stored subject, when it differs from the pack's; it sees the subject's
-     *  address, which a stored shape may not carry */
-    view?: (body: Record<string, unknown>, subject: {
-        id: string;
-        type: string;
-    }) => Record<string, unknown>;
-    /** an update replaces the fields it names (`replace`) or merges nested objects into them (`merge`, the default) */
-    update?: 'merge' | 'replace';
+    /** the field the vendor's answer names a subject's id by, when it is not `id` (Daily's webhook `uuid`, Twilio's `sid`,
+     *  Asana's `gid`): the subject's id is answered under it, and no `id` */
+    idAs?: string;
+    /** an update replaces the fields it names (`replace`), merges a nested object one level into them with `''` removing
+     *  a key (`merge`, the default: Stripe's metadata), or merges nested objects at every level with `null` removing a key
+     *  (`deep`: Clerk's metadata, "a deep merge … remove metadata keys at any level by setting their value to null") */
+    update?: 'merge' | 'replace' | 'deep';
     /** the stored subject id when it is not the path's last parameter: a template over the path
      *  parameters (`{vector_store_id}::{file_id}`) */
     key?: string;
+    /** a resource every tenant shares (a catalogue the vendor keeps for all, its countries or currencies): the manifest's
+     *  `tenant` does not scope it */
+    shared?: boolean;
     /** only subjects whose stored fields match are readable (a resource stored for every call but
      *  answered only when asked to be kept) */
     readableWhen?: Record<string, unknown>;
@@ -122,11 +151,129 @@ export type ResourceDecl = {
         field: string;
         direction: 'asc' | 'desc';
     };
+    /** the list's ordering parameter (`order_by=-created_at`): `[+-]<field>` over `fields`, `default` when absent; any
+     *  other field is refused with `invalid` (`{fields}` in its message names them), never ignored */
+    orderBy?: {
+        param: string;
+        fields: string[];
+        default: string;
+        invalid: ErrorSpec;
+    };
+    /** fields no two live subjects share (a permission's `key`; a membership's `organization_id` and `user_id` together):
+     *  a create or update that would make a second one is refused with `refusal`, by the core and by `ctx.conflict` */
+    unique?: Array<{
+        fields: string[];
+        refusal: ErrorSpec;
+    }>;
+    /** the subjects a delete takes with it (an organization's memberships and invitations): each resource whose `field`
+     *  holds the deleted subject's id, deleted first, each through the write path as its own delete (its events sent) */
+    cascade?: Array<{
+        resource: string;
+        field: string;
+    }>;
+    /** fields that name a subject as its id does (an organization by its id or its slug): a path's id and `ctx.find`
+     *  match either */
+    alternateKeys?: string[];
+    /** the list's search parameter (`query`): a row matches on an `exact` field's whole value or a `partial` field's
+     *  substring, case-insensitively */
+    search?: {
+        param: string;
+        exact?: string[];
+        partial?: string[];
+    };
+    /** fields that count this subject's children (an App's `installations_count`): the live subjects of `of` whose `by`
+     *  holds this one's id, only those with `present` set when it is named, plus `plus` (a customer's
+     *  `next_invoice_sequence` is one past its numbered invoices). The kernel keeps each whenever a child is written. */
+    counts?: Record<string, {
+        of: string;
+        by: string;
+        present?: string;
+        plus?: number;
+    }>;
+    /** how the vendor's state of this type is read back into a root (the real-system adapters, "Refresh"): the list that
+     *  enumerates it (once per parent, under `parent`; `complete: false` when it is not the whole type; `items`, the answer's
+     *  path to them, when the spec does not name the list it answers), the one read of a singleton, or `none` with why the
+     *  vendor offers no read-back. Every stored resource the vendor holds declares one. */
+    refresh?: {
+        list: string;
+        complete?: false;
+        items?: string;
+    } | {
+        get: string;
+    } | {
+        none: string;
+    };
+    /** the other resources one create of this one makes, and where its answer names each's id (a JSON path) */
+    companions?: Record<string, string>;
+    /** the field telling a newer copy of a subject from an older (an `updated_at`): an ingested event older than the
+     *  root's copy folds nothing */
+    version?: string;
+};
+/** How a vendor's signed webhooks are folded into a root (the real-system adapters, "Ingest"). */
+export type IngestDecl = {
+    scheme: EventScheme | ReadonlyArray<EventScheme>;
+    /** where the event names its type: a header, a body path, and a sub-action path joined to it with `.` */
+    type: {
+        header?: string;
+        body?: string;
+        action?: string;
+    };
+    /** the JSON path of the event's object */
+    object: string;
+    /** event type → the resource it carries, where `events.types` read backwards and `<resource>.created|updated|deleted`
+     *  do not say it */
+    types?: Record<string, {
+        resource: string;
+        deleted?: true;
+    }>;
+    /** an event answered instead of folded (Slack's url_verification): the body fields it matches, and the answer, a
+     *  `$body.<path>` read from the event or a literal */
+    handshake?: {
+        when: Record<string, string>;
+        answer: string;
+    };
+};
+/** Which lane a request is the vendor's gateway's to send ("Other wires: lanes"), each condition it names holding: a
+ *  path under `path` (Supabase's `/rest/v1`), a host matching `host` (a regular expression: `^secretsmanager\.`), a
+ *  header starting with `header.prefix` (AWS's `x-amz-target: secretsmanager.`), and a host not in `exceptHosts`. */
+export type LaneRoute = {
+    lane: string;
+    path?: string;
+    host?: string;
+    exceptHosts?: ReadonlyArray<string>;
+    /** a header starting with `prefix`, or, with `absent`, a request whose header does not (Clerk's Frontend API is asked
+     *  without a Backend API secret key) */
+    header?: {
+        name: string;
+        prefix: string;
+        absent?: true;
+    };
+    /** where two of the vendor's APIs share one address: the route passes a path only the root's API serves (the lane's
+     *  surface does not), which is the root's */
+    unlessOnlyRoot?: true;
+};
+/** A vendor's lanes: its routes, first match first, the lane that takes what no route names (`default`), and the
+ *  gateway's CORS. A `/_twin/` door goes to the lane whose manifest declares it. */
+export type LanesDecl = {
+    cors?: CorsDecl;
+    routes: ReadonlyArray<LaneRoute>;
+    default?: string;
 };
+/** The manifest of a vendor whose every API is a lane (Cloudflare's API v4 and R2, AWS's services): no API of its own,
+ *  only what the vendor's front says — its discovery facts, its lanes and its descriptor. */
+export type VendorManifest = {
+    vendor: string;
+    discovery?: DerivedManifest['discovery'];
+    lanes: LanesDecl;
+    descriptor: Omit<PackDescriptor, 'vendor'>;
+    ingest?: IngestDecl;
+    rateBudget?: RateBudgetDeclaration;
+};
+/** `code` as the vendor writes it: a string, or a number (Discord's JSON error codes are integers) */
 export type ErrorSpec = {
     status: number;
     message: string;
-    code?: string;
+    code?: string | number;
     param?: string;
     kind?: string;
 };
@@ -136,8 +283,12 @@ export type ErrorSpec = {
  *  vendor's way, each a (screen, control) cell. */
 export type ScreenDecl = {
     id: string;
-    kind: 'flow' | 'workspace';
+    /** a hosted flow a person is sent through, a workspace they work in, or a content host serving what the vendor stores
+     *  (its CDN: an uploaded image, a video, a default avatar) */
+    kind: 'flow' | 'workspace' | 'content';
     host: string;
+    /** every other host the screen answers on (a sandbox's dashboard and production's, one page) */
+    hosts?: string[];
     path: string;
     demand: string;
     status: 'done' | 'todo';
@@ -146,15 +297,35 @@ export type ScreenDecl = {
     source: string;
 };
 export type DerivedManifest = {
+    /** The pack's descriptor, as data (docs/contributing/architecture.md, "The descriptor"), every field but `vendor`, which
+     *  is the manifest's: the pack registers `packOf(manifest)`, so its index is a fixed file. A lane has none. */
+    descriptor?: Omit<PackDescriptor, 'vendor'>;
     vendor: string;
     /** the kernel service the pack writes */
     service: string;
     /** `json: 'always'` reads a body as JSON whatever its content type (GitHub does) */
+    /** `strict`: a vendor that refuses a body field its operation does not declare, a value of another type, or a number
+     *  outside the spec's bounds (a NestJS validation pipe: Supabase's "property x should not exist"), with its messages;
+     *  `{name}`, `{type}` (`a string`, `an integer`), `{min}` and `{max}` are filled. `ctx.fields` checks a body so. */
     body: {
         form?: {
             coerce: boolean;
         };
         json?: 'always';
+        validation?: {
+            operations?: ReadonlyArray<string>;
+            status: number;
+            missing: unknown;
+            type: unknown;
+            range: unknown;
+        };
+        strict?: {
+            status: number;
+            code?: string;
+            unknown: string;
+            type: string;
+            range: string;
+        };
     };
     /** `acceptProvided`: a create that names its own `id` keeps it (a vendor that seeds by id). The template counts
      *  (`{prefix}_{n}`), or is `{uuid}` for a vendor whose ids are UUIDs: the next is derived from the resource and its
@@ -168,7 +339,22 @@ export type DerivedManifest = {
     /** operations that only read though nothing in the spec says so (a POST that returns data):
      *  a read-only twin answers them */
     reads?: string[];
-    time: 'unix' | 'iso';
+    /** how the vendor writes an instant: Unix seconds, Unix milliseconds (Clerk's `created_at`), or ISO 8601 */
+    time: 'unix' | 'unix-ms' | 'iso';
+    /** the vendor's CORS, as its gateway answers a browser (cors.ts): the pack's fetch is served behind `withCors` */
+    cors?: CorsDecl;
+    /** the HTTP status a vendor answers every error below `below` with, when its body names the error's own status
+     *  (storage-api: 400 for every error but a 500, the body's `statusCode` the error's: `{ status: 400, below: 500 }`) */
+    errorsAnsweredAs?: {
+        status: number;
+        below: number;
+    };
+    /** the texts the vendor reads as a boolean in a parameter, compared without case (Supabase: `true`, `1`, `yes`, `on`,
+     *  `y`, `enabled` and their opposites); absent, `true` and `false`. `ctx.flag` reads with them. */
+    booleans?: {
+        truthy: string[];
+        falsy: string[];
+    };
     /** the vendor's error body, with `{message}`, `{code}`, `{param}`, `{kind}` placeholders; a
      *  placeholder with no value is left out when `errorOmitsAbsent` */
     error: unknown;
@@ -186,6 +372,18 @@ export type DerivedManifest = {
         pattern: string;
         error: ErrorSpec;
     };
+    /** request headers that carry meaning to the vendor (a tenant header such as `Stripe-Account`): recorded with a write
+     *  so its perform sends them again (the real-system adapters, "What a pack declares"); `version.header` is too */
+    headers?: string[];
+    /** the vendor's signed webhooks, folded into a root */
+    ingest?: IngestDecl;
+    /** the vendor's documented limits, charged by the executor on every live call (D8) */
+    rateBudget?: RateBudgetDeclaration;
+    /** a pack whose wire has no derived perform (a socket, a line protocol, a managed database): binding a root is refused
+     *  with this reason */
+    vendorBacked?: {
+        none: string;
+    };
     /** `withParam`: the error names the path parameter that held the unknown id */
     notFound: {
         status: number;
@@ -214,7 +412,7 @@ export type DerivedManifest = {
             encoding: 'base64-offset';
         };
         /** numbered pages (1-based `page`, the size in `limit.param`), with the vendor's `Link` header
-         *  naming the first, previous, next and last pages */
+         *  naming the first, previous, next and last pages (`link`); the envelope may name `{total_count}` and `{max_page}` */
         page?: {
             param: string;
             link: boolean;
@@ -264,15 +462,38 @@ export type DerivedManifest = {
     };
     /** how the vendor reads its credential, and what it answers without one or with a key the twin
      *  reserves as invalid, or one of a shape the vendor never issues (`keyFormat`, a pattern every key it issues
-     *  matches: Resend's begin `re_`); a request that presents no such header at all is a trusted in-process call */
+     *  matches: Resend's begin `re_`); a request that presents no such header at all is a trusted in-process call.
+     *  `held`: the key must be one the account holds, kept by its SHA-256 in a stored type's field (a token a Tokens page
+     *  made: `{ storedAs: '_access_token', hashField: 'sha256' }`), or one of the World's `standing` keys (the one its
+     *  seeds and init hand the app); any other is `invalid`. */
+    /** how the vendor reads its credential: the `header`, after its `scheme` (`''`: the header's whole value, an
+     *  `x-api-key`), or any of `also` (ElevenLabs' `xi-api-key` beside `Authorization`, Google's `?key=`); `paths` (a
+     *  regular expression) the paths it gates, every other passing ungated; a key the World issued is `held` by its hash */
     auth?: {
         header: string;
         scheme: string;
+        also?: Array<{
+            header?: string;
+            scheme?: string;
+            query?: string;
+        }>;
+        paths?: string;
         missing: ErrorSpec;
         invalidKeys: string[];
         keyFormat?: string;
         invalid: ErrorSpec;
         gateWhenAbsent: boolean;
+        held?: {
+            storedAs: string;
+            hashField: string;
+            standing?: string[]; /** a field set true on a key no longer held (OpenRouter's `disabled`) */
+            unless?: string;
+        };
+        /** operations that check a credential of their own, not the account's (Cloudflare's asset upload reads its upload
+         *  session's JWT from the same header): the gate leaves them to their handler */
+        exempt?: string[];
+        /** the vendor checks the key before it routes: a path it does not have is refused a missing or invalid key first */
+        beforeRouting?: boolean;
     };
     /** the twin door that makes the next request answer the vendor's rate-limit refusal */
     /** headers every answer carries (a request id) */
@@ -282,12 +503,105 @@ export type DerivedManifest = {
     origin?: {
         placeholder: string;
     };
-    /** while a pack moves, how its existing code renders a stored subject (named by its stored
-     *  type), so moved and unmoved operations answer the same shape */
-    view?: (storedType: string, body: Record<string, unknown>) => Record<string, unknown>;
     resources: Record<string, ResourceDecl>;
+    /** Read-only cross-pack credential subjects of the same vendor (architecture A3); no root is exposed to handlers. */
+    ownerReads?: ReadonlyArray<{
+        owner: string;
+        resource: string;
+    }>;
     /** the vendor's screens this pack serves or owes (demand decides which exist) */
     screens?: ScreenDecl[];
+    /** The discovery door's facts (`GET /twin`): what the twin is of, what it stores, and how it is authenticated. */
+    discovery?: {
+        twinOf: string;
+        stores: string;
+        identity?: string;
+        notes?: string;
+        /** a model vendor's: what its scenario scripts (the `on` keys and the `respond` shape), and a handler as an example */
+        behavior?: string;
+        exampleHandler?: ScenarioHandler;
+    };
+    /** The World's doors (architecture, "Doors, screens and the gap"): each a method and a path under `/_twin/` (with
+     *  `{param}` segments), answered by the export of `semantics/doors.ts` its id names, over the contract's context. */
+    doors?: Array<{
+        id: string;
+        method: string;
+        path: string;
+        note?: string;
+    }>;
+    /** The vendor's GraphQL API beside its REST one (`semantics/graphql.ts` over `generated/graphql-sdl.gen.json`): the
+     *  paths it is POSTed to, and the answer to a query selecting a field nothing models (`{field}`, `{type}`). */
+    graphql?: {
+        paths: ReadonlyArray<string>;
+        unmodeled: {
+            message: string;
+            type?: string;
+            status?: number;
+        };
+    };
+    /** The vendor's answer for a path nothing serves and an operation nothing models, `{method}` and `{path}` filled
+     *  (OpenAI's `Unknown request URL: {method} {path}`); the manifest's `notFound` when it names none. */
+    gap?: ErrorSpec;
+    /** The vendor's answer for a path its API serves under other methods than the request's (`405 Method not allowed:
+     *  {method} {path}`), `{method}` and `{path}` filled; the gap when it names none. */
+    wrongMethod?: ErrorSpec;
+    /** The content codings the vendor reads a request's body in (its Content-Encoding: Tinybird's "Gzip or Zstandard"
+     *  events) and answers in when the request accepts one (Accept-Encoding), and its answer for a body that does not
+     *  decode as its Content-Encoding says. The kernel decodes before routing and encodes the API's answer. */
+    encodings?: {
+        request?: ReadonlyArray<'gzip' | 'zstd' | 'deflate' | 'br'>;
+        response?: ReadonlyArray<'gzip'>;
+        undecodable?: ErrorSpec;
+    };
+    /** The content type the vendor labels a JSON answer with, when it is not the runtime's (Clerk's exact
+     *  `application/json`, which @clerk/backend reads a body as JSON only on): every JSON answer relabelled. */
+    jsonContentType?: string;
+    /** The vendor's tenancy (architecture, "The derived core"): each stored subject belongs to the tenant it was made in —
+     *  an organization, a team, an account — and a caller reaches only its own tenant's, as a parent's children are
+     *  reached under it. `field` holds it on each subject; `semantics/tenant.ts` names the caller's. The core scopes every
+     *  read, list, update and delete by it and stamps it on every create, for each resource not `shared`. */
+    tenant?: {
+        field: string;
+    };
+    /** The vendor's own lanes behind this manifest's API ("Other wires: lanes"), dispatched by the kernel before the
+     *  vendor's own doors, clock and API (LanesDecl). */
+    lanes?: LanesDecl;
+    /** A host whose first label is part of the path, as a regular expression over the request's vendor host whose first
+     *  capture is put in front of the path before routing (S3's virtual-hosted addressing: `<bucket>.<endpoint>/<key>` is
+     *  `/<bucket>/<key>`); the host itself is left as it came. */
+    pathFromHost?: string;
+    /** A prefix the vendor's hosts may put before a path (turbopuffer's region, `/aws-us-east-1`), as a regular expression
+     *  matched at the path's start: stripped before routing, so the operation it names is the one served. Its named groups
+     *  (Jira's `/ex/jira/(?<cloudId>[^/]+)`) are the operation's parameters as well. */
+    pathPrefix?: string;
+    /** A pattern over the request's vendor host whose named groups are the operation's parameters (E2B's envd answers each
+     *  sandbox at `49983-<sandboxID>.e2b.app`: `^\\d+-(?<sandboxID>[a-z0-9]+)\\.`). */
+    hostParams?: string;
+    /** The persistent wires the vendor's clients hold open (sockets.ts: Discord's Gateway): each served at its path by
+     *  the pack's `semantics/sockets.ts`, which the kernel offers every write after its webhooks. */
+    sockets?: ReadonlyArray<SocketDecl>;
+    /** The vendor speaks gRPC (architecture, "Other wires": gRPC): its server answers HTTP/2 and HTTP/1 on one port, each
+     *  rpc (by its proto unit's schema, `src/generated/proto.gen.json`) through the pack's own fetch. */
+    grpc?: true;
+    /** The vendor runs its customers' images (machines.ts: Fly's Machines): the kernel serves `POST /_twin/machine-pool`
+     *  and hands handlers the World's pool as `ctx.machines`. */
+    machines?: boolean;
+    /** A lane routed by host ("Other wires: lanes"): the hosts it serves, each exact or a suffix. The vendor's server sends
+     *  them here, and SHAPE judges the lane on them alone, never on a page or door of the vendor on another host. */
+    hosts?: ReadonlyArray<{
+        host?: string;
+        suffix?: string;
+    }>;
+    /** The path parameters whose values span segments where the spec cannot say so (an OpenAPI path has no greedy label:
+     *  GitHub's `{ref}`, QStash's `{destination}`); a Smithy model's greedy labels are the surface's own `spanning`. */
+    spanning?: ReadonlyArray<string>;
+    /** The webhooks the vendor sends for its writes, as data the kernel renders, signs, delivers and records (events.ts);
+     *  `render` is the pack's `semantics/events.ts`, how the vendor renders an event's `data` when it is not the written
+     *  object. */
+    events?: EventsDecl & {
+        render?: EventRender<WriteHookContext>;
+        values?: EventValues<WriteHookContext>;
+    };
     /** called after every stored write with the rendered resource, its stored type and the kernel operation name */
     onWrite?: (write: {
         operation: string;
@@ -301,6 +615,15 @@ export type DerivedManifest = {
         context(): Promise<WriteHookContext>;
     }) => Promise<void>;
 };
+/** A body's fields as a strict vendor checks them (`ctx.fields`, the manifest's `body.strict`). Without `strict`, every
+ *  field passes. An object or array field is not typed here: its own shape is the handler's. */
+export declare function strictFields(m: DerivedManifest, operation: DerivedOperation, body: Record<string, unknown>): {
+    fields: Record<string, unknown>;
+} | {
+    refused: Response;
+};
+/** A value as the vendor reads a boolean (`ctx.flag`, the manifest's `booleans`). */
+export declare function flagOf(m: Pick<DerivedManifest, 'booleans'>, value: unknown): boolean | undefined;
 /** A form body's bracket notation (`a[b][0][c]=v`, `expand[]=x`) as nested objects and arrays. A form carries only
  *  text: a field the operation's spec types as a number or a boolean (`scalars`, by bracket path, written by
  *  world-tooling's formScalarsOf) is read as one when its text is that literal; every other field stays the text sent
@@ -311,6 +634,7 @@ export declare function parseBracketForm(text: string, scalars?: Readonly<Record
  *  every form value is its text. */
 export declare function readParams(manifest: DerivedManifest, request: Request, operation?: DerivedOperation): Promise<Record<string, unknown>>;
 export declare function vendorError(manifest: DerivedManifest, e: ErrorSpec): Response;
+export declare const storedType: (m: DerivedManifest, resource: string) => string;
 /** A service's resources of one type, each the reader's own copy: `twinResources` filtered by type, from an index
  *  that follows each write rather than projecting the whole tree per call. */
 export declare function resourcesOfType(service: string, type: string, root?: string): TwinResource[];
@@ -320,19 +644,33 @@ export declare function resourcesOfType(service: string, type: string, root?: st
 export declare function render(r: TwinResource): Record<string, unknown>;
 /** Where the core runs: the World root it reads and writes, and its clock (the World's by default;
  *  a caller that pins an instant passes its own). */
+/** One call of a protocol-3 pack's default data (`src/semantics/seed.ts` exports `seed: SeedCall[]`): a request to the
+ *  vendor's own operation (or the pack's door), made in order against the twin by the runner `volter-world init` writes
+ *  beside the copied data. */
+export type SeedCall = {
+    method: string;
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+};
+/** Where a call is answered: the World's root, its clock, and the managed Postgres the runtime binds to the pack
+ *  (`database`, the descriptor's `managedDatabase`), which a handler reaches as `ctx.engine` — READ ONLY in every
+ *  transaction when the twin is (`readOnly`) or the request is (x-volter-read-only). */
 export type CoreScope = {
     root?: string;
     clock?: () => string;
+    database?: string;
+    readOnly?: boolean;
+    /** `semantics/tenant.ts`: the tenant the caller acts in (the manifest's `tenant`), or undefined for none */
+    tenant?: (ctx: HandlerContext) => string | undefined | Promise<string | undefined>;
 };
+/** The lane a vendor's router sent a request to (pack-fetch's laneRouter sets it). */
+export declare const LANE_HEADER = "x-volter-lane";
 /** What a coverage measurement sees of a pack's declared state logic: each move a request made and each refusal a
  *  guard gave, by the transition that decided it. Nothing is observed unless a measurement installs an observer
  *  (scripts/life-coverage.ts); serving never depends on it. */
 export type TransitionObserver = (decl: StateField, transition: Transition, outcome: 'moved' | 'refused', from: string) => void;
 export declare function observeTransitions(observer: TransitionObserver | undefined): void;
-/** The transition a request asks for on one state field, or the vendor's refusal when none applies. */
-/** What a declared machine says to one move: the transition that allows it, or the refusal it gives (and
- *  nothing when it declares neither). The derived core and `legal` ask it; so does an engine that is not
- *  HTTP-shaped (a line protocol's session), so one machine rules every wire. */
 export declare function transitionFor(field: string, decl: StateField, operationId: string, current: unknown, requested: unknown, id?: string, actor?: Actor): {
     move?: Transition;
     refusal?: ErrorSpec;
@@ -342,7 +680,7 @@ export type CoreOutcome = {
 } | {
     unmodeled: string;
 };
-/** Serve one operation from the manifest, or say why the core cannot. */
+export declare function mergeField(rule: ResourceDecl['update'], prior: unknown, next: unknown): unknown;
 export declare function serveCore(m: DerivedManifest, call: DerivedCall, scope?: CoreScope): Promise<CoreOutcome>;
 /** Server-sent events in the manifest's framing. The events are known when the answer starts: the
  *  twin decides deterministically, so the stream carries a decided answer, never a model's. */
@@ -363,13 +701,69 @@ export type SemanticsContext = {
     text: string;
     root: string | undefined;
     occurredAt: string;
+    /** The twin's own base URL as this request reached it (its links and redirects to its own pages carry it). */
+    publicBase: string;
+    /** What the World's scenario decided for this turn (a model vendor's answer: the handler matched, or the miss), on an
+     *  operation the pack's `semantics/scenario.ts` names; undefined elsewhere, or when the World carries no scenario. */
+    scenario: ScenarioDecision | undefined;
+    /** A message the vendor sends the application's own server that no declared event is (a push notification), through
+     *  the World's route and egress rule: the receiver's status, or 0 when refused or unreachable. */
+    deliver(url: string, init: RequestInit): Promise<number>;
+    /** A message the vendor sends the application's server and decides by its answer, waited on for at most `within`
+     *  milliseconds (a real-time authorization request): its status and body, or why there was none. */
+    ask(url: string, init: RequestInit, within: number): Promise<ApplicationAnswer>;
+    /** A git repository of the World, by the pack's name for it (the git plane, world-core git/): its objects in the
+     *  World's content-addressed object store (one per service), its refs in the World's store. Served over smart HTTP
+     *  (`git.serveSmartHttp`), read and written through the library's codecs. */
+    git(name: string): {
+        store: GitObjectStore;
+        refs: GitRefs;
+    };
+    /** A value the World set for its application (world-env.ts): what the app was given and the vendor must agree with (a
+     *  webhook signing secret the app verifies with), never the caller's own shell; undefined when the World sets none. */
+    worldEnv(name: string): string | undefined;
+    /** Runs `fn` as the vendor's own move, not the caller's: what time makes due (a renewal a read catches up) is
+     *  recorded with no caller, wherever a handler reaches it. */
+    asVendor<T>(fn: () => Promise<T>): Promise<T>;
+    /** A mail the vendor sends a person, over SMTP to the route its settings name (smtp.ts), under the World's egress rule;
+     *  throws when it cannot be delivered. */
+    mail(route: SmtpRoute, mail: Mail, headers?: Record<string, string>): Promise<void>;
     /** who is calling, when the manifest says how to tell */
     actor: string | undefined;
     now(): unknown;
     get(resource: string, id: string): Record<string, unknown> | undefined;
+    /** One credential subject in a manifest-declared owner's World store. Ambiguous stores refuse the read. */
+    ownerRow(owner: string, resource: string, id: string): Record<string, unknown> | undefined;
     rows(resource: string): Array<Record<string, unknown>>;
     mint(resource: string): string;
+    /** An id the vendor issues for what it does not keep (a completion's, a request's): minted, and its subject recorded,
+     *  so the next is another; a read-only request mints without recording. The resource is a declared bookkeeping type. */
+    issue(resource: string): Promise<string>;
+    /** The vendor's open sessions of one of its sockets in this World (a request answered by a session: sockets.ts). */
+    sockets(id: string): SocketSession[];
+    /** A secret for `label` (an app's client secret, a store's read token): an HMAC under a seed the World makes once, at
+     *  random, and keeps as bookkeeping no door answers. The same label gives the same secret for the World's whole life,
+     *  and no one can compute it from ids the World shows, as they can a value derived from them alone. */
+    secret(label: string): Promise<string>;
+    /** The World's machine pool (machines.ts), as the pack's `machine-pool` door enrolled it; `none` when none was. */
+    machines: MachinePool;
+    /** A signing key pair for `label` (an issuer's ID tokens, a provider's JWTs, a CA's or a log's key), PEM: RSA 2048
+     *  (the default) or Ed25519, made once, at random, when the label is first asked for, and kept as bookkeeping no door
+     *  answers, so what it signs verifies against the World's published key (ctx.crypto.jwks of the public half) and no
+     *  one can forge it from anything the pack or the World shows, as they can with a key written in the pack. */
+    signingKey(label: string, alg?: 'RS256' | 'Ed25519'): Promise<{
+        privatePem: string;
+        publicPem: string;
+    }>;
+    /** The signing key for `label` when the World has made it (`signingKey`), else undefined: for code that signs where it
+     *  cannot wait (a cookie's token, read everywhere), after a front made the key before anything is answered. */
+    heldSigningKey(label: string, alg?: 'RS256' | 'Ed25519'): {
+        privatePem: string;
+        publicPem: string;
+    } | undefined;
     write(resource: string, id: string, fields: Record<string, unknown>, operation: string): Promise<Record<string, unknown>>;
+    /** Add numeric deltas to an existing bookkeeping row under the kernel's atomic write seam. */
+    accumulate(resource: string, id: string, deltas: Record<string, number>, operation: string): Promise<void>;
     /** `write`, with what a live vendor answered when the head performed it */
     writeDetailed(resource: string, id: string, fields: Record<string, unknown>, operation: string): Promise<{
         body: Record<string, unknown>;
@@ -378,6 +772,9 @@ export type SemanticsContext = {
     }>;
     /** The id a subject has now, for an id a caller may still use from before the vendor minted its own
      *  (a branch naming a message by the ts it minted locally). */
+    /** The tree's type a resource's rows are kept under (the manifest's `storedAs`, else its name): what an operation on
+     *  it is named by (`issuing_card.create`), as the vendor names the events it sends. */
+    storedType(resource: string): string;
     resolve(resource: string, id: string): string;
     /** Answer the vendor's success envelope around several fields (`{ ok: true, ts, channel, message }`). */
     ok(fields: Record<string, unknown>): Response;
@@ -418,6 +815,8 @@ export type SemanticsContext = {
     /** Whether the machine lets `operationId` move `field` from `current` (to `to`): nothing when it
      *  does, the vendor's refusal when it does not. A move the machine does not declare throws. */
     legal(resource: string, field: string, operationId: string, current: unknown, to?: string, id?: string, actor?: Actor): ErrorSpec | undefined;
+    /** Validate the request body's top-level derived schema under body.validation, before a write. */
+    validate(): Response | undefined;
     refuse(e: ErrorSpec): Response;
     notFound(resource: string, id: string, param?: string): Response;
     reply(body: unknown, status?: number): Response;
@@ -428,7 +827,7 @@ export type SemanticsContext = {
         event?: string;
         data: unknown;
     }>): Response;
-    expand(resource: string, body: Record<string, unknown>): Record<string, unknown>;
+    expand(resource: string, body: Record<string, unknown>, paths?: string[]): Record<string, unknown>;
     /** This context at another moment of the World clock (ISO): a move time makes is written at the moment it fell due. */
     at(when: string): Promise<SemanticsContext>;
     /** This call's context over another manifest of the same service, at the same moment: a lane over its vendor's
@@ -438,6 +837,61 @@ export type SemanticsContext = {
     core(): Promise<Response | undefined>;
     /** A stored row's own fields, as the vendor's object carries them (an `id`, `type` or `updatedAt` of its own restored). */
     own(row: Record<string, unknown>): Record<string, unknown>;
+    /** A handler's own rows (views) answered as the call's list: the resource's filters, search and order, then the
+     *  manifest's paging and envelope; the vendor's refusal when the call orders by a field the resource does not take. */
+    list(resource: string, rows: Array<Record<string, unknown>>): Response;
+    /** The vendor's refusal when these fields would make a second live subject where the resource's `unique` rules allow
+     *  one (`except`: the subject being updated), or nothing. */
+    conflict(resource: string, fields: Record<string, unknown>, except?: string): Response | undefined;
+    /** A subject deleted as the vendor deletes it: every subject its resource's `cascade` names deleted first, then it,
+     *  each through the write path (`operation` names the subject's own delete when it is not `<stored type>.delete`). */
+    remove(resource: string, id: string, operation?: string): Promise<void>;
+    /** The subject a key names, by its id (an alias the caller may still use resolved) or one of the resource's
+     *  `alternateKeys` (an organization by its slug), as the vendor serves it. */
+    find(resource: string, key: string): Record<string, unknown> | undefined;
+    /** A field's new value as the resource's `update` rule merges it into the stored one (`deep`: Clerk's metadata). */
+    merge(resource: string, prior: unknown, next: unknown): unknown;
+    /** What a handler signs and hashes with (signing.ts): JWTs with a pack's key, their verification, a JWKS, an HMAC and
+     *  a SHA-256, deterministic, so no pack reaches `node:crypto` itself. */
+    crypto: HandlerCrypto;
+    /** The World's managed Postgres (managed-database.ts): one transaction per batch, as a role with its settings, or a
+     *  script. A World that binds none refuses every use with the reason (EngineUnavailableError). */
+    engine: ManagedDatabase;
+    /** A vendor's Redis (the kernel's Redis library, redis/engine.ts): a request's commands run in order over this call's
+     *  tree and clock, in the pack's own service, under its wire's dialect, in one of its databases (`database`: its keys
+     *  and scripts apart from the others'); each answered `{result}` or `{error}`, and whether any wrote. A read-only
+     *  World raises ReadOnlyError at the first write. The wire around it (Upstash's REST envelope) is the pack's. */
+    redis(commands: string[][], options: {
+        dialect: RedisDialect;
+        database?: string;
+    }): Promise<{
+        items: RunItem[];
+        wrote: boolean;
+    }>;
+    /** Another vendor's own URL answered by the World's twin of it (vendor-call.ts): a vendor's call to another as part of
+     *  its behaviour (Clerk exchanging a Google sign-in's code). A vendor the World runs no twin of is refused
+     *  (VendorUnreachableError); nothing leaves the World. */
+    vendorFetch(url: string | URL, init?: RequestInit): Promise<Response>;
+    /** A multipart/form-data body's parts in order (multipart.ts: field name, filename, media type, bytes), a part with an
+     *  empty field name included; none for any other body. */
+    parts(): Promise<MultipartPart[]>;
+    /** The pack's resource blobs (an object's bytes), by key, on the World's branch: they branch with the World, and a
+     *  read falls back to an ancestor's. The row that names a blob is the pack's; the bytes are here. */
+    blobs: {
+        put(key: string, bytes: Uint8Array): Promise<void>;
+        get(key: string): Promise<Uint8Array | null>;
+        remove(key: string): Promise<void>;
+    };
+    /** A body's fields checked against the operation's declared ones under the manifest's `body.strict`: the fields, or
+     *  the vendor's refusal of the first that is unknown, of another type or out of its bounds. */
+    fields(body: Record<string, unknown>): {
+        fields: Record<string, unknown>;
+    } | {
+        refused: Response;
+    };
+    /** A parameter as the vendor reads a boolean (the manifest's `booleans`): true, false, or undefined for a value that
+     *  is neither (absent, or text the vendor does not read as one). A boolean passes as itself. */
+    flag(value: unknown): boolean | undefined;
 };
 export type Semantics = (ctx: SemanticsContext) => Promise<Response>;
 /** The context a derived pack's handler is given ("What an author writes, and how"): the kernel's own members
@@ -453,9 +907,11 @@ export type HandlerContext = Omit<SemanticsContext, 'now' | 'core' | 'atomically
 };
 /** What a write hook reads: the writing call's context without its ways to write, so a hook that renders an event
  *  cannot write again (and run itself again). */
-export type WriteHookContext = Omit<HandlerContext, 'write' | 'record' | 'at' | 'over'>;
+export type WriteHookContext = Omit<HandlerContext, 'write' | 'record' | 'accumulate' | 'at' | 'over'>;
 /** A derived pack's handler: one operation, by its operationId, over the contract's context. */
 export type Handler = (ctx: HandlerContext) => Promise<Response>;
+/** The context the kernel opens for a call (a handler's, a door's, a screen's). Kernel-internal: packs are given it. */
+export declare function contextFor(m: DerivedManifest, call: DerivedCall, scope: CoreScope): Promise<SemanticsContext>;
 /** A pack's semantics handlers as the dispatch's handlers. */
 export declare function bindSemantics(m: DerivedManifest, handlers: Record<string, Semantics>, scope?: CoreScope): Record<string, DerivedHandler>;
 /** The derived core as the dispatch's core: it owns every operation on a resource the manifest declares. */
@@ -465,6 +921,13 @@ export declare function coreFor(m: DerivedManifest, scope?: CoreScope): {
 };
 /** Read-only refusal, API-version validation and idempotent replay, applied once around every
  *  operation a handler or the core serves. */
+/** The vendor's refusal of a request's credential under the manifest's `auth`, or undefined when it passes: what the
+ *  cross-cutting gate answers for an operation, and what a pack whose vendor checks the credential before routing (an
+ *  unknown path answers 401, as Supabase's recording shows) calls in front of its dispatch. */
+/** The header the kernel names a scenario's decision in, set by createPackFetch alone (it strips it from every request it
+ *  is sent). */
+export declare const SCENARIO_DECISION_HEADER = "x-volter-scenario-decision";
+export declare function authRefusal(m: DerivedManifest, request: Request, root?: string): Response | undefined;
 export declare function crossCutting(m: DerivedManifest, opts?: CoreScope & {
     readOnly?: boolean;
 }): (call: DerivedCall, next: () => Promise<Response>) => Promise<Response>;