@volter/world-core 3.0.155 → 3.0.157

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

@@ -68,6 +68,8 @@ export type Transition = {
 export type StateField = {
     initial: string | boolean;
     transitions: Transition[];
+    /** Plain updates may repeat the current representation without another state move. */
+    unchanged?: 'allow';
     derive?: Array<{
         state: string;
         when: {
@@ -139,6 +141,8 @@ export type ResourceDecl = {
         resource: string;
         allowDeleted?: boolean;
         where?: Record<string, string>;
+        /** Global subject paths omit the collection's parent labels; tenancy still applies. */
+        whenNamed?: true;
         /** 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>;
@@ -215,7 +219,9 @@ export type ResourceDecl = {
      *  holds this one's id (or vendor `parentKey`), only those with `present` set or `absent` unset when named and without
      *  any matching `unless` field, plus `plus` (a customer's
      *  `next_invoice_sequence` is one past its numbered invoices). `by` may be a dot path; exact field names take
-     *  precedence. The kernel keeps each whenever a child is written. */
+     *  precedence. The kernel keeps each whenever a child is written, the parent it left too when the write moves it; `of`
+     *  may name a bookkeeping type no resource declares, written with `ctx.record`. A count is kept by the lane that
+     *  declares it: a child another lane writes is not counted there. */
     counts?: Record<string, {
         of: string;
         by: string;
@@ -261,6 +267,10 @@ export type ResourceDecl = {
     } | {
         get: string;
         known?: true;
+        gone?: {
+            status: number;
+            says: string;
+        };
     }) & {
         params?: Record<string, string>;
         headers?: Record<string, string>;
@@ -376,6 +386,17 @@ export type ErrorSpec = {
     param?: string;
     kind?: string;
 };
+/** How a form value outside its spec's list is refused (DerivedOperation.enums): the error, its message filled with
+ *  `{param}` (the bracket name) and `{values}` (the values it takes); `documented`, values the vendor documents outside
+ *  its spec, by operation and path; `version`, the header naming the API version a request is made at and the version
+ *  the spec is, so a request pinned to another version, whose lists the pack does not hold, is not checked. */
+export type EnumRefusal = ErrorSpec & {
+    documented?: Record<string, Record<string, string[]>>;
+    version?: {
+        header: string;
+        served: 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
@@ -401,6 +422,14 @@ export type ScreenDecl = {
      *  takes, with its demand (an upload bucket a page posts a lease's form to: Reddit's S3 hosts) (architecture, "A page
      *  at a World's place") */
     takes?: ReadonlyArray<'POST'>;
+    /** a workspace page that shows one record: the stored type and the path parameter its id fills (a pull request's
+     *  page, `{number}`); `?show=<type>:<id>` asked of the pack's workspaces opens it (architecture, "Workspace") */
+    shows?: {
+        type: string;
+        param: string;
+    };
+    /** the stored types a workspace page lists, where `?show=` lands for a record no page shows by itself */
+    lists?: ReadonlyArray<string>;
     /** the vendor's documentation of the round trip or the screen */
     source: string;
 };
@@ -443,6 +472,7 @@ export type DerivedManifest = {
     body: {
         form?: {
             coerce: boolean;
+            enumRefusal?: EnumRefusal;
         };
         json?: 'always';
         validation?: {
@@ -458,6 +488,7 @@ export type DerivedManifest = {
             unknown: string;
             type: string;
             range: string;
+            arrays?: Record<string, 'string'>;
         };
     };
     /** `acceptProvided`: a create that names its own `id` keeps it (a vendor that seeds by id). The template counts
@@ -469,6 +500,13 @@ export type DerivedManifest = {
     };
     /** operations the derived core must not claim though their resource is declared: a gap until someone models them */
     unmodeled?: string[];
+    /** documented variants of a served operation that no demand asks for, by operation: each a parameter present
+     *  (`pause_collection`), present on any item of a list (`items[].price_data`), or with a value
+     *  (`payment_method_data.type=sepa_debit`, `payment_method_types[]=sepa_debit`), or holding one entry of a comma-separated
+     *  value (`tweet.fields~=geo`; a parameter whose name holds a dot is read by that name). A request asking one is answered the
+     *  manifest's gap before its handler runs, as an operation no handler serves is (architecture, "Creating a pack",
+     *  step 7), so no pack line answers it */
+    variants?: Record<string, 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[];
@@ -506,6 +544,9 @@ export type DerivedManifest = {
     readOnly: ErrorSpec;
     /** what a body labelled JSON that does not parse answers; absent, a 400 in the vendor's error body */
     malformedBody?: ErrorSpec;
+    /** the vendor's front merges repeated slashes in a path before it routes (nginx's default `merge_slashes`): a request
+     *  to `//r/x//about` is `/r/x/about`, merged on arrival before a door, a screen or an operation is matched */
+    mergeSlashes?: boolean;
     /** 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?: {
@@ -702,7 +743,13 @@ export type DerivedManifest = {
         method: string;
         path: string;
         note?: string;
+        redactBody?: string[];
     }>;
+    /** REST refresh binds observed tenant metadata through the root account identity endpoint. */
+    refreshIdentity?: {
+        operation: string;
+        field: 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?: {
@@ -939,8 +986,6 @@ export type SemanticsContext = {
     /** 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;
     /** 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>;
@@ -985,13 +1030,28 @@ export type SemanticsContext = {
     /** 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<{
+    createUnique(resource: string, fields: Record<string, unknown> | ((id: string) => Record<string, unknown>), operation: string, options?: {
+        input: 'omit';
+    }): 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>;
+    change(resource: string, id: string, decide: (row: Record<string, unknown>) => Record<string, unknown> | undefined, operation: string, options?: {
+        input: 'omit';
+    }): Promise<Record<string, unknown> | undefined>;
     write(resource: string, id: string, fields: Record<string, unknown>, operation: string): Promise<Record<string, unknown>>;
+    /**
+     * One command's writes as one group (S2 R17; docs/contributing/architecture.md, "A command's writes as one group").
+     * Inside `fn`, `write` stages its write and answers the row as it will stand; `row` and `rowsRaw` read the tree with
+     * the staged writes folded over it, as it will be once they land. When `fn` returns or throws, every staged write
+     * lands, in order, as one append; then its value is answered or its error thrown. Every other way to write, or to
+     * wait on a write, lands the staged writes first; any other read of the tree (`get`, `rows`, `tree`, `history`, ...)
+     * while writes are staged is refused, never answered without them. Each write keeps its own action, id, ordinal,
+     * moment and recorded request. Where the pack has write hooks, events, sockets or counts, a state observer is on,
+     * a head performs, or ids are aliased, `fn` simply runs, each write landing as it is made.
+     */
+    batch<T>(fn: () => Promise<T>): Promise<T>;
     /** 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 */
@@ -1115,6 +1175,16 @@ export type SemanticsContext = {
         put(key: string, bytes: Uint8Array): Promise<void>;
         get(key: string): Promise<Uint8Array | null>;
         remove(key: string): Promise<void>;
+        /** a body written as it arrives (a request's own stream), kept only when `accept` holds for its size and SHA-256:
+         *  an upload of a large object never held whole. True when kept */
+        putStream(key: string, body: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>, accept: (written: {
+            size: number;
+            sha256: string;
+        }) => boolean): Promise<boolean>;
+        /** a blob's length, or null when there is none: a large object is answered without loading it */
+        size(key: string): Promise<number | null>;
+        /** the bytes `start`..`endInclusive` of a blob (a ranged read where the store has one), or null when there is none */
+        range(key: string, start: number, endInclusive: number): Promise<Uint8Array | null>;
     };
     /** 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. */
@@ -1141,13 +1211,20 @@ 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' | 'create' | 'createUnique' | 'change' | 'issue' | 'record' | 'accumulate' | 'at' | 'over'>;
+export type WriteHookContext = Omit<HandlerContext, 'write' | 'batch' | '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. */
 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 first of a request's form parameters whose value is not one its spec lists (DerivedOperation.enums), with the
+ *  bracket name a form gives it (`spending_controls[spending_limits][0][interval]`) and the values it takes. */
+export declare function valueOutside(params: Record<string, unknown>, enums: Readonly<Record<string, ReadonlyArray<string>>>): {
+    param: string;
+    values: ReadonlyArray<string>;
+} | undefined;
+/** Whether a request's parameters ask one of the operation's undemanded variants (DerivedManifest.variants). */
+export declare function variantAsked(params: Record<string, unknown>, variants: readonly string[], headers?: Headers): boolean;
 /** 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;