@volter/world-core 3.0.37 → 3.0.39

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

@@ -9,8 +9,10 @@ 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';
+export { ownField, parseBracketForm } from './form.js';
 import { type MultipartPart } from './multipart.js';
 import type { CorsDecl } from './cors.js';
+import { type TwinAction } from './actions.js';
 import type { DerivedCall, DerivedCoreOutcome, DerivedHandler, DerivedOperation } from './derived.js';
 import type { PackDescriptor } from './packRegistry.js';
 import type { ScenarioDecision, ScenarioHandler } from './scenario.js';
@@ -39,7 +41,8 @@ export type Transition = {
     operation?: string;
     actor?: Actor;
     from: string[] | '*';
-    /** the value it moves to; absent, the value stays (a guard that moves nothing) */
+    /** the value it moves to; absent, the value stays (a guard that moves nothing), and absent with a `refusal`, the
+     *  operation is refused in the `from` states (a move another transition allows from there is taken first) */
     to?: string;
     effects?: Record<string, FieldRule>;
     /** placeholders `{from}`, `{to}`, `{field}`, `{id}` */
@@ -90,8 +93,8 @@ export type ResourceDecl = {
     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}`
+    /** this resource's id template, when it is not the manifest's (`ids.template`): `{uuid}`, `{ksuid}` (Clerk's), `{letters:20}` (twenty
+     *  lowercase letters, a Supabase project ref), `{digits:16}` (fixed-width decimal), `{snowflake:<epoch ms>}` (Discord's ids), or a `{prefix}`/`{n}`
      *  template */
     ids?: string;
     /** fields the server assigns on create */
@@ -101,6 +104,24 @@ export type ResourceDecl = {
     notState?: string[];
     /** id-holding fields a caller may ask to receive embedded, and the resource each holds */
     embeds?: Record<string, string>;
+    /** `embeds` fields the vendor answers embedded on every answer, asked or not (its schema gives the object with no id
+     *  alternative: Stripe's issuing card's `cardholder`): still stored as the id, hydrated from the current object */
+    alwaysEmbedded?: string[];
+    /** the vendor's own fields whose names begin with `_` (GitHub's `_links`, a HAL object's), which the vendor answers:
+     *  answered like any field, where every other `_` field is the pack's bookkeeping and never answered */
+    vendorUnderscored?: string[];
+    /** Stored fields omitted from vendor views, without renaming them in retained state. Raw rows and
+     *  ctx.own retain them for parent scope and semantics; get, rows, render and core answers omit them. */
+    viewOmit?: readonly string[];
+    /** fields the vendor answers as a list of the current children of another resource (Stripe's subscription `items`:
+     *  its subscription_items), built on every answer from the child rows whose `by` field holds this id, in the order
+     *  they were made, each through the child's own view and its embedding; never a stored copy. `list` is the list's own
+     *  fields around `data`, where `{id}` is this resource's id and `"{count}"` the children's number */
+    collections?: Record<string, {
+        resource: string;
+        by: string;
+        list?: Record<string, unknown>;
+    }>;
     /** this resource's deletion answer, when it is not the manifest's (`vector_store.deleted`) */
     deleted?: unknown;
     /** a child addressed under its parent: the path parameter naming the parent, the stored field that
@@ -117,6 +138,9 @@ export type ResourceDecl = {
         resource: string;
         allowDeleted?: boolean;
         where?: Record<string, string>;
+        /** private fields a child observed under its parent keeps from the parent's parameters (`_jurisdiction:
+         *  '{jurisdiction}'`), where the child's own read names none and a later read under it needs one ("Refresh") */
+        keep?: Record<string, string>;
     };
     /** a number the resource counts per parent (a repository's issue numbers, a thread's messages):
      *  the stored field, set on create to one past the highest among its siblings */
@@ -174,6 +198,10 @@ export type ResourceDecl = {
     /** 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[];
+    /** fields that pair a subject a deploy settled with no vendor id with the vendor's copy a refresh observes (Slack's
+     *  `channel_join` message, made by `conversations.join` and answered by no id: its `subtype` and `user`), where the
+     *  `alternateKeys` do not; a subject missing one is never paired by them ("Refresh", adoption) */
+    adoptBy?: 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?: {
@@ -182,24 +210,80 @@ export type ResourceDecl = {
         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
+     *  holds this one's id (or vendor `parentKey`), only those with `present` set when it is named and without
+     *  any matching `unless` field, 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;
+        parentKey?: string;
         present?: string;
+        unless?: Record<string, unknown>;
         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?: {
+     *  vendor offers no read-back. Every stored resource the vendor holds declares one. `{ get, known: true }`: the vendor
+     *  lists no whole type, so the World's own subjects of it are each read again by `get` (a 404 is one gone), and what
+     *  those reads observe anchors its children's lists; completeness is those subjects alone. */
+    /** `next`: where an answer names the next page's cursor (AWS's `NextToken`), sent back as `cursor` (the same name
+     *  unless said) in the query, or in the body of a list asked by POST (an RPC list: AWS JSON's `x-amz-target`); a
+     *  map of parameter to answer path where a page names several (S3's `key-marker` and `upload-id-marker`); `more`, the
+     *  answer's flag that another page follows (S3's `IsTruncated`). `headers`: fixed headers of the list, `{name}` filled
+     *  from the parent's parameters; `variants`: header sets each listed in turn, one type whole across them (R2's
+     *  jurisdictions). A blob read by an `operation` (a GET of the unit's surface, filled from the subject's fields and
+     *  its parent's parameters) keeps the bytes in the World's blobs, their key in `field`, and in `headersField` the
+     *  answer's headers `keepHeaders` names (a name ending `*` a prefix: `x-amz-meta-*`), both fields private. */
+    refresh?: ({
         list: string;
+        unpaginated?: true;
+        keyed?: true;
+        detail?: string;
+        detailMerge?: string;
+        detailWith?: Record<string, string>;
         complete?: false;
         items?: string;
+        shape?: RefreshShape;
+        next?: string | Record<string, string>;
+        nextLink?: {
+            header: string;
+            rel: string;
+            query: string;
+            when?: Record<string, string>;
+        };
+        cursor?: string;
+        more?: string;
     } | {
         get: string;
+        known?: true;
+    }) & {
+        params?: Record<string, string>;
+        headers?: Record<string, string>;
+        variants?: ReadonlyArray<{
+            headers: Record<string, string>;
+        }>;
+        blobs?: ReadonlyArray<{
+            path: string;
+            key: string;
+            resource?: string;
+            fields?: Record<string, string>;
+        } | {
+            operation: string;
+            field: string;
+            headers?: Record<string, string>;
+            headersField?: string;
+            keepHeaders?: string[];
+        }>;
+        query?: Record<string, string>;
+        idAs?: string;
+        graphql?: {
+            query: string;
+            variables?: Record<string, unknown>;
+            items: string;
+            pageInfo?: string;
+            cursor?: string;
+        };
     } | {
         none: string;
     };
@@ -225,6 +309,15 @@ export type IngestDecl = {
     types?: Record<string, {
         resource: string;
         deleted?: true;
+        /** where this type carries its object, when not at `object` (GitHub's `issue`, `pull_request`, `comment`) */
+        object?: string;
+        /** the JSON path of the value the resource's `parent.field` holds, when the event names its parent beside the object
+         *  (GitHub's `repository.full_name`, the `{owner}/{repo}` its children are stored under) */
+        parent?: string;
+        /** where the object names the subject's id when not as the resource does (Resend's email events: `email_id`) */
+        id?: string;
+        /** the fields the event's type itself says (Resend's `email.delivered` is the email's `last_event: 'delivered'`) */
+        fields?: Record<string, unknown>;
     }>;
     /** 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 */
@@ -323,6 +416,14 @@ export type PerformHookArgs = {
 };
 export type PerformHook = (args: PerformHookArgs) => Promise<import('./head.js').PushOutcome>;
 export type DerivedManifest = {
+    /** Vendor data-plane hosts mapped to an already-running customer guest. */
+    machineRoutes?: ReadonlyArray<{
+        host: string;
+        resource: string;
+        where: Record<string, string>;
+        name: string;
+        port: number | string;
+    }>;
     /** 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'>;
@@ -365,6 +466,14 @@ 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[];
+    /** operations of the vendor's API that set an account up rather than use it: an operator registering an OAuth client
+     *  on the vendor's own admin routes, as a person makes settings on the vendor's site. Each is recorded as a door's
+     *  write is (the World's own), so a deploy never offers it to the vendor and the vendor-backed acceptance holds it as
+     *  what the account already has; `why` says who performs it and where */
+    accountSetup?: Array<{
+        operation: string;
+        why: string;
+    }>;
     /** 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` */
@@ -399,7 +508,8 @@ export type DerivedManifest = {
         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 */
+     *  so its perform sends them again (the real-system adapters, "What a pack declares"); `version.header` is too. A name
+     *  ending `*` is a prefix: every header it begins (S3's `x-amz-meta-*`, an object's own metadata). */
     headers?: string[];
     /** the vendor's signed webhooks, folded into a root */
     ingest?: IngestDecl;
@@ -422,13 +532,14 @@ export type DerivedManifest = {
     notFound: {
         status: number;
         message: string;
-        code?: string;
+        code?: string | number;
         kind?: string;
         withParam?: boolean;
     };
     /** the list envelope (placeholders `{data}`, `{has_more}`, `{url}`, `{first_id}`, `{last_id}`),
-     *  its page size, its cursors, and where an unknown cursor starts: the first page or past the end */
-    list: {
+     *  its page size, its cursors, and where an unknown cursor starts: the first page or past the end.
+     *  Absent when the unit serves no stored list; the core does not own lists without this declaration. */
+    list?: {
         style: 'envelope';
         envelope: unknown;
         limit: {
@@ -444,8 +555,18 @@ export type DerivedManifest = {
         cursor?: {
             param: string;
             encoding: 'base64-offset';
+        } | {
+            param: string;
+            encoding: 'offset-template';
+            template: string;
+            link: {
+                previous: string;
+                next: string;
+                results: string;
+                cursor: string;
+            };
         };
-        /** numbered pages (1-based `page`, the size in `limit.param`), with the vendor's `Link` header
+        /** numbered pages (1-based, the size in `limit.param`), with the vendor's `Link` header
          *  naming the first, previous, next and last pages (`link`); the envelope may name `{total_count}` and `{max_page}` */
         page?: {
             param: string;
@@ -526,17 +647,30 @@ export type DerivedManifest = {
         /** 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[];
+        /** ordered API-skin error wires, selected before scenario matching and ordinary routing */
+        wires?: Array<{
+            paths: string;
+            error: DerivedManifest['error'];
+            missing?: ErrorSpec;
+            invalid?: ErrorSpec;
+        }>;
         /** 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) */
+    /** headers every answer carries (a request id); a value's `{hex:N}` is filled per answer, from the World's count of
+     *  answers (so a second World answers the same ids in the same order), unless the handler set the header itself */
     answerHeaders?: Record<string, string>;
     /** an origin the pack writes into URLs it mints, rewritten in every JSON answer to where this
      *  twin is reached for the request (twinPublicBase) */
     origin?: {
         placeholder: string;
     };
+    /** Disclosed local connection fields, separate from vendor response schemas. */
+    worldFields?: Record<string, Record<string, {
+        type: 'array' | 'object' | 'string' | 'number' | 'boolean';
+        why: string;
+    }>>;
     resources: Record<string, ResourceDecl>;
     /** Read-only cross-pack credential subjects of the same vendor (architecture A3); no root is exposed to handlers. */
     ownerReads?: ReadonlyArray<{
@@ -608,9 +742,22 @@ export type DerivedManifest = {
      *  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 prefix the vendor serves as its own base path (Discord answers `/api` and `/api/v9` as `/api/v10`, the spec's), as
+     *  a regular expression matched at the path's start: put in place of the surface's base path before routing, so an
+     *  operation compiled under the spec's base answers each. Perform and refresh send the spec's base, as the SDK does. */
+    basePathAlias?: 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 vendor host a lane's calls go to when it carries the call's parameters (R2's `<account>.r2.cloudflarestorage.com`):
+     *  `{name}` filled from the call's parameters, `values` a parameter's literal in the host (the real-system adapters,
+     *  "Lanes"). Perform and refresh send to `https://<host><path>`. */
+    remoteHost?: {
+        template: string;
+        values?: Record<string, Record<string, string>>;
+    };
+    /** Named operation parameters from vendor routing headers (shared-host compute services). */
+    headerParams?: Record<string, 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>;
@@ -658,14 +805,6 @@ export declare function strictFields(m: DerivedManifest, operation: DerivedOpera
 };
 /** 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
- *  (`metadata[order]=007`, `name=2024`). */
-/** A field set as the object's own, whatever its name (`__proto__`, `constructor` and `prototype` are data a caller
- *  may name: Stripe's metadata keys are the caller's), never through what the object inherits. */
-export declare function ownField(node: Record<string, unknown> | unknown[], key: string, value: unknown): void;
-export declare function parseBracketForm(text: string, scalars?: Readonly<Record<string, string | undefined>>): Record<string, unknown>;
 /** A request's parameters, its query's and its body's. With the manifest's `body.form.coerce`, a form's fields the
  *  operation's spec types as numbers or booleans are read as them (parseBracketForm); without an operation (a twin door)
  *  every form value is its text. */
@@ -678,19 +817,34 @@ export declare function resourcesOfType(service: string, type: string, root?: st
 /** The vendor's view of a stored subject: its own fields, bookkeeping (`_`) left out. */
 /** A stored subject as the vendor's object: its id first (the subject's, unless the pack kept an id of its own), then
  *  the fields the pack wrote, bookkeeping (`_`) and the kernel's updatedAt left out. */
-export declare function render(r: TwinResource): Record<string, unknown>;
+export declare function render(r: TwinResource, vendorUnderscored?: readonly string[]): 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. An ordinary path is relative to the twin base. A call naming a browser uses the
  *  vendor's absolute URL and is exported separately as `browserSeed`, after the ordinary `seed` calls. */
+/** How a refresh list's answer items become subjects' fields where each is not one subject's object (architecture,
+ *  "Refresh"): `scalar`, a bare item is that field; `value` (with `keyed`), a scalar map value is that field and, with
+ *  `keyAs`, the map key is that field rather than the id; `spread`, an item expands into the array at `path`, each
+ *  element an object or a scalar named `as`, beside the item's fields `carry` names (field: path in the item). */
+export type RefreshShape = {
+    scalar?: string;
+    value?: string;
+    keyAs?: string;
+    spread?: {
+        path: string;
+        as?: string;
+        carry?: Record<string, string>;
+    };
+};
 export type SeedCall = {
     browser?: string;
     method: string;
     path: string;
     body?: unknown;
-    headers?: Record<string, string>;
+    headers?: Record<string, string>; /** the instant the account made it, before the World's time: the call is made with the World clock frozen there */
+    at?: 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
@@ -710,9 +864,18 @@ 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 type TransitionEntry = {
+    action: TwinAction;
+    field: string;
+    actor: Actor;
+};
+export type TransitionObserver = (decl: StateField, transition: Transition, outcome: 'moved' | 'refused', from: string, entry?: TransitionEntry) => void;
 export declare function observeTransitions(observer: TransitionObserver | undefined): void;
-export declare function transitionFor(field: string, decl: StateField, operationId: string, current: unknown, requested: unknown, id?: string, actor?: Actor): {
+/** 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, entry?: TransitionEntry): {
     move?: Transition;
     refusal?: ErrorSpec;
 };
@@ -747,14 +910,11 @@ export type SemanticsContext = {
     /** 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
+     *  World's repository-scoped content-addressed object store, 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;
@@ -772,6 +932,8 @@ export type SemanticsContext = {
     /** who is calling, when the manifest says how to tell */
     actor: string | undefined;
     now(): unknown;
+    /** Render a stored row or vendor view using its resource declaration, retaining the stored subject id fallback. */
+    render(row: Record<string, unknown>, resource?: string): Record<string, 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;
@@ -782,6 +944,11 @@ export type SemanticsContext = {
     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[];
+    /** Hold this read until the World writes (held-reads.ts: HTTP long polling): true when a write of one of the named
+     *  resources lands in this World, false when `ms` pass or the client hangs up; at once false in a read-only World. */
+    awaitWrite(resources: ReadonlyArray<string>, ms: number): Promise<boolean>;
+    /** Observe a condition until it holds or the caller's timeout/cancellation, waking on writes and pollMs. */
+    awaitCondition(resources: ReadonlyArray<string>, ms: number, pollMs: number, condition: () => Promise<boolean>): Promise<boolean>;
     /** 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. */
@@ -802,6 +969,15 @@ export type SemanticsContext = {
         privatePem: string;
         publicPem: string;
     } | undefined;
+    /** Allocate a stored occurrence and append its fields under one action lock. The optional field factory is pure. */
+    create(resource: string, fields: Record<string, unknown> | ((id: string) => Record<string, unknown>), operation: string): Promise<Record<string, unknown>>;
+    /** Create under declared unique keys and the action lock; a collision returns the existing own-field view without a write. */
+    createUnique(resource: string, fields: Record<string, unknown> | ((id: string) => Record<string, unknown>), operation: string): Promise<{
+        created: boolean;
+        row: Record<string, unknown>;
+    }>;
+    /** Decide an update from the current live stored row under the action lock; undefined leaves it unchanged. */
+    change(resource: string, id: string, decide: (row: Record<string, unknown>) => Record<string, unknown> | undefined, operation: string): Promise<Record<string, unknown> | 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>;
@@ -834,8 +1010,8 @@ export type SemanticsContext = {
         fields?: Record<string, unknown>;
         occurredAt?: string;
     }>;
-    /** Write a bookkeeping subject (a `_`-prefixed type the vendor never serves), minting its id when none is given. */
-    record(type: string, fields: Record<string, unknown>, id?: string): Promise<string>;
+    /** Write bookkeeping without the incoming request; an explicit operation observes its checked state move. Mint an id when none is given. */
+    record(type: string, fields: Record<string, unknown>, id?: string, operation?: string): Promise<string>;
     /** Decide a write from the tree as it stands and make it, with nothing written between the read
      *  and the write (a minted number, a first poll that moves a subject). `decide` returns the write,
      *  or nothing to write; the answer is its `value`. */
@@ -859,6 +1035,8 @@ export type SemanticsContext = {
     /** Validate the request body's top-level derived schema under body.validation, before a write. */
     validate(): Response | undefined;
     refuse(e: ErrorSpec): Response;
+    /** Answer the manifest's declared unserved capability gap. */
+    gap(): Response;
     notFound(resource: string, id: string, param?: string): Response;
     reply(body: unknown, status?: number): Response;
     /** Answer in the vendor's success envelope under this operation's key (`{ ok: true, channel }`). */
@@ -948,7 +1126,7 @@ 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' | 'accumulate' | 'at' | 'over'>;
+export type WriteHookContext = Omit<HandlerContext, 'write' | 'create' | 'createUnique' | 'change' | 'issue' | '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. */
@@ -977,7 +1155,7 @@ export declare function crossCutting(m: DerivedManifest, opts?: CoreScope & {
  *  coming (another wire's mutation, a door, a screen) — and answered with the vendor's own read-only
  *  error; `GET /twin` advertises `requestScopes`. The pack's catch-up runs under `runAsVendorMove`
  *  (request-scope.ts), so time's moves still land when a read-only request is what arrives. */
-export declare function derivedRequestScopes<F extends (request: Request) => Promise<Response>>(m: DerivedManifest, fetch: F): F;
+export declare function derivedRequestScopes<F extends (request: Request) => Promise<Response>>(m: DerivedManifest, fetch: F, readOnly?: boolean): F;
 /** A semantics context for a request no surface operation names: another wire's (GraphQL) resolvers
  *  get the same interface as a handler, named by the operation id the wire gives. */
 export declare function semanticsContext(m: DerivedManifest, request: Request, operation: DerivedOperation, scope?: CoreScope): Promise<SemanticsContext>;