@volter/world-core 2.0.0

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

@@ -0,0 +1,452 @@
+import { type TwinResource } from './serve.js';
+import type { DerivedCall, DerivedCoreOutcome, DerivedHandler, DerivedOperation } from './derived.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. */
+export type FieldRule = {
+    now: true;
+} | {
+    id: true;
+} | {
+    value: unknown;
+} | {
+    template: string;
+};
+/** 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;
+ *  `refusal` what the vendor answers when `from` does not hold. */
+/** Who moves a state: a caller of the API (the default), the person on a vendor's hosted page or
+ *  another outside party (`external`), the vendor on its own (`vendor`), or time (`time`). A move
+ *  that is not the API's never answers an API call's legality. */
+export type Actor = 'api' | 'external' | 'vendor' | 'time';
+export type Transition = {
+    operation?: string;
+    actor?: Actor;
+    from: string[] | '*';
+    /** the value it moves to; absent, the value stays (a guard that moves nothing) */
+    to?: string;
+    effects?: Record<string, FieldRule>;
+    /** placeholders `{from}`, `{to}`, `{field}`, `{id}` */
+    refusal?: {
+        status: number;
+        code?: string;
+        message: string;
+    };
+    /** a refusal of its own for a particular current value (an invoice already `paid`) */
+    refusals?: Record<string, {
+        status: number;
+        code?: string;
+        message: string;
+    }>;
+    /** where the rule comes from: a docs URL, the SDK's types, or a recording */
+    source: string;
+};
+/** A state field's machine. Values compare as strings, so a boolean field reads `'true'`/`'false'`, and
+ *  a field that is absent reads as `initial`. `derive` names states a stored value only implies (a
+ *  timestamp that is 0 until something happens), tried in order. `vendorInitial` is where the vendor
+ *  starts a subject when the twin starts it elsewhere. */
+export type StateField = {
+    initial: string | boolean;
+    transitions: Transition[];
+    derive?: Array<{
+        state: string;
+        when: {
+            equals?: unknown;
+            gt?: number;
+            truthy?: boolean;
+            absent?: boolean;
+        };
+    }>;
+    vendorInitial?: string;
+};
+/** What a move to `to` stores in the field: a boolean field's value is a boolean, and a derived field's
+ *  value is written by the move's effects (a state name is not a timestamp), so it stores nothing itself. */
+export declare function storedState(decl: StateField, to: string | undefined): unknown;
+/** The state a stored value is in, by the field's machine. */
+export declare function stateOf(decl: StateField, value: unknown): string;
+export type ResourceDecl = {
+    /** the tree's subject type, when it differs from the resource name */
+    storedAs?: string;
+    idPrefix: string;
+    /** fields the server assigns on create */
+    assigned?: Record<string, FieldRule>;
+    state?: Record<string, StateField>;
+    /** state candidates the manifest rules are not state */
+    notState?: string[];
+    /** id-holding fields a caller may ask to receive embedded, and the resource each holds */
+    embeds?: Record<string, string>;
+    /** 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
+     *  holds it, and the parent resource, whose not-found answers a missing parent */
+    /** `param` is the path parameter naming the parent, or `params` several with `value` the template
+     *  that joins them into what `field` stores (`{owner}/{repo}`). `where` finds the parent by its stored
+     *  fields when its stored id is not what the path names (a repository stored as `repo:7` with `owner`
+     *  and `name`, addressed as `{owner}/{repo}`): each stored field against a template over the path. */
+    parent?: {
+        param?: string;
+        params?: string[];
+        value?: string;
+        field: string;
+        resource: string;
+        allowDeleted?: boolean;
+        where?: 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 */
+    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 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;
+    /** 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>;
+    /** this resource's not-found answer when it is not the manifest's: a message (`{id}`), or an
+     *  error code (an RPC vendor's `channel_not_found`) */
+    notFound?: string | {
+        code: string;
+        message?: string;
+    };
+    /** query parameters of the list operation that filter on the same-named field */
+    filters?: string[];
+    order?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    };
+};
+export type ErrorSpec = {
+    status: number;
+    message: string;
+    code?: string;
+    param?: string;
+    kind?: string;
+};
+/** A vendor screen a World serves (docs/contributing/architecture.md, "Screens"). A `flow` is a hosted
+ *  page an application sends its user through, held to its documented round trip; a `workspace` is a
+ *  screen people work in. `demand` says who reaches it; `controls` names what a person acts on, the
+ *  vendor's way, each a (screen, control) cell. */
+export type ScreenDecl = {
+    id: string;
+    kind: 'flow' | 'workspace';
+    host: string;
+    path: string;
+    demand: string;
+    status: 'done' | 'todo';
+    controls?: string[];
+    /** the vendor's documentation of the round trip or the screen */
+    source: string;
+};
+export type DerivedManifest = {
+    vendor: string;
+    /** the kernel service the pack writes */
+    service: string;
+    /** `json: 'always'` reads a body as JSON whatever its content type (GitHub does) */
+    body: {
+        form?: {
+            coerce: boolean;
+        };
+        json?: 'always';
+    };
+    /** `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
+     *  count, so a World mints the same ids every run */
+    ids: {
+        template: string;
+        acceptProvided?: boolean;
+    };
+    /** operations the derived core must not claim though their resource is declared: served by
+     *  the pack's existing code, or a gap, until someone models them */
+    unmodeled?: string[];
+    /** 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';
+    /** the vendor's error body, with `{message}`, `{code}`, `{param}`, `{kind}` placeholders; a
+     *  placeholder with no value is left out when `errorOmitsAbsent` */
+    error: unknown;
+    errorOmitsAbsent?: boolean;
+    /** the `{kind}` an error takes when it names none */
+    defaultKind?: string;
+    /** what a write to a read-only twin answers */
+    readOnly: ErrorSpec;
+    /** what a body labelled JSON that does not parse answers; absent, a 400 in the vendor's error body */
+    malformedBody?: ErrorSpec;
+    /** a request header that selects the vendor's API version, and the answer to a malformed one
+     *  (`{value}` in its message is the header's value) */
+    version?: {
+        header: string;
+        pattern: string;
+        error: ErrorSpec;
+    };
+    /** `withParam`: the error names the path parameter that held the unknown id */
+    notFound: {
+        status: number;
+        message: string;
+        code?: string;
+        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: {
+        style: 'envelope';
+        envelope: unknown;
+        limit: {
+            param: string;
+            default: number;
+            max: number;
+        };
+        after?: string;
+        before?: string;
+        unknownCursor?: 'start' | 'end';
+        /** an opaque cursor over positions (`{next_cursor}` in the envelope; empty on the last page),
+         *  in place of id cursors: `base64-offset` is base64 of `{"o":<offset>}` */
+        cursor?: {
+            param: string;
+            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 */
+        page?: {
+            param: string;
+            link: boolean;
+        };
+        /** offset paging: `param` names how many items to skip; the page sits under the operation's envelope key beside the
+         *  envelope, whose `{total_count}` is the count before paging (Tremendous's `{ orders: [...], total_count }`) */
+        offset?: {
+            param: string;
+        };
+        /** page sizes by operationId, where a vendor's lists differ from `limit` (Tremendous: orders 10/500, invoices 10/10) */
+        limits?: Record<string, {
+            default: number;
+            max: number;
+        }>;
+        /** envelopes by operationId, where a vendor's lists differ from `envelope` (Tremendous gives `total_count` on orders,
+         *  rewards and invoices, and none on campaigns, funding sources or webhooks) */
+        envelopes?: Record<string, unknown>;
+    };
+    /** an RPC vendor's success envelope, merged into every answer, with the resource under the
+     *  operation's envelope key (`{ ok: true, channel: {...} }`) */
+    success?: Record<string, unknown>;
+    /** who is calling, from the request's credential (and the tree, where the vendor keeps tokens) */
+    identity?: (authorization: string | null, root?: string) => string;
+    deleted: unknown;
+    expandParam?: string;
+    /** server-sent events: `data` lines, optionally `event:` lines named by each event, and the
+     *  sentinel a finished stream ends with */
+    sse?: {
+        named: boolean;
+        done?: string;
+    };
+    /** an operation whose stream is framed otherwise (named events, no sentinel) */
+    streamFor?: Record<string, {
+        named: boolean;
+        done?: string;
+    }>;
+    /** the vendor's idempotency header: a write repeated with the same key answers the stored
+     *  answer; the same key with other parameters answers `conflict` */
+    /** `methods` defaults to POST; `onlySuccess` (replay only 2xx answers) to false; without
+     *  `conflict`, a key replays its first answer whatever the parameters */
+    idempotency?: {
+        header: string;
+        storedAs: string;
+        conflict?: ErrorSpec;
+        methods?: string[];
+        onlySuccess?: boolean;
+    };
+    /** 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 */
+    auth?: {
+        header: string;
+        scheme: string;
+        missing: ErrorSpec;
+        invalidKeys: string[];
+        keyFormat?: string;
+        invalid: ErrorSpec;
+        gateWhenAbsent: boolean;
+    };
+    /** the twin door that makes the next request answer the vendor's rate-limit refusal */
+    /** headers every answer carries (a request id) */
+    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;
+    };
+    /** 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>;
+    /** the vendor's screens this pack serves or owes (demand decides which exist) */
+    screens?: ScreenDecl[];
+    /** called after every stored write with the rendered resource, its stored type and the kernel operation name */
+    onWrite?: (write: {
+        operation: string;
+        storedType: string;
+        body: Record<string, unknown>;
+        root?: string;
+        occurredAt: string;
+        request: Request;
+    }) => Promise<void>;
+};
+/** 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`). */
+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. */
+export declare function readParams(manifest: DerivedManifest, request: Request, operation?: DerivedOperation): Promise<Record<string, unknown>>;
+export declare function vendorError(manifest: DerivedManifest, e: ErrorSpec): Response;
+/** 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[];
+/** 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>;
+/** 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). */
+export type CoreScope = {
+    root?: string;
+    clock?: () => string;
+};
+/** 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;
+};
+export type CoreOutcome = {
+    served: Response;
+} | {
+    unmodeled: string;
+};
+/** Serve one operation from the manifest, or say why the core cannot. */
+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. */
+export declare function sse(m: DerivedManifest, events: Array<{
+    event?: string;
+    data: unknown;
+}>, operationId?: string): Response;
+/** What a semantics handler works with: the request's parameters, the tree through the pack's view,
+ *  the write path (which runs the manifest's write hook), and the declared machine. A handler never
+ *  imports the kernel; this is its whole interface. */
+export type SemanticsContext = {
+    call: DerivedCall;
+    params: Record<string, unknown>;
+    /** the last path parameter: the subject an item operation names */
+    id: string | undefined;
+    /** the request body as the vendor reads it (an array, where the vendor takes one), and its text */
+    body: unknown;
+    text: string;
+    root: string | undefined;
+    occurredAt: string;
+    /** who is calling, when the manifest says how to tell */
+    actor: string | undefined;
+    now(): unknown;
+    get(resource: string, id: string): Record<string, unknown> | undefined;
+    rows(resource: string): Array<Record<string, unknown>>;
+    mint(resource: string): string;
+    write(resource: string, id: string, fields: Record<string, unknown>, operation: string): Promise<Record<string, unknown>>;
+    /** `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>;
+        id: string;
+        vendorData?: unknown;
+    }>;
+    /** 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). */
+    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;
+    /** A stored row as it is kept, bookkeeping (`_`) fields and tombstones included. */
+    row(resource: string, id: string, opts?: {
+        withDeleted?: boolean;
+    }): Record<string, unknown> | undefined;
+    rowsRaw(resource: string, opts?: {
+        withDeleted?: boolean;
+    }): Array<Record<string, unknown>>;
+    /** Every stored subject of the pack, of every type, in the tree's order (a projection folding many types at once). */
+    tree(): Array<Record<string, unknown>>;
+    /** The writes that touched a subject, in order: its history. */
+    history(resource: string, id: string): Array<{
+        operation?: string;
+        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>;
+    /** 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`. */
+    atomically<T>(decide: (rows: (resource: string) => Array<Record<string, unknown>>) => {
+        value: T;
+        write?: {
+            resource: string;
+            id: string;
+            fields: Record<string, unknown>;
+            operation: string;
+        };
+    }): Promise<T>;
+    /** Answer bytes or text as they are (a file's content), with the vendor's headers. */
+    raw(body: BodyInit | null, init?: {
+        status?: number;
+        headers?: Record<string, string>;
+    }): Response;
+    /** 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;
+    refuse(e: ErrorSpec): 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 }`). */
+    wrap(body: Record<string, unknown>, extra?: Record<string, unknown>): Response;
+    /** Answer as a server-sent event stream, framed as the manifest says. */
+    sse(events: Array<{
+        event?: string;
+        data: unknown;
+    }>): Response;
+    expand(resource: string, body: Record<string, unknown>): 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>;
+    /** The generic core's answer to this call, or undefined where the core does not serve it. */
+    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>;
+};
+export type Semantics = (ctx: SemanticsContext) => Promise<Response>;
+/** 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. */
+export declare function coreFor(m: DerivedManifest, scope?: CoreScope): {
+    owns: (o: DerivedOperation) => boolean;
+    serve: (call: DerivedCall) => Promise<DerivedCoreOutcome>;
+};
+/** Read-only refusal, API-version validation and idempotent replay, applied once around every
+ *  operation a handler or the core serves. */
+export declare function crossCutting(m: DerivedManifest, opts?: CoreScope & {
+    readOnly?: boolean;
+}): (call: DerivedCall, next: () => Promise<Response>) => Promise<Response>;
+/** 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>;