@sincpro/client-framework 0.6.0 → 1.1.0

package/dist/codegen/{domain.js → services/domain.js}

@@ -1,8 +1,15 @@
-import { answerOf, claimed, contextOf, deprecationOf, docOf, headerOf, identifierOf, keyOf, localOf, sorted, } from "./names.js";
+import { aliasOf, answerOf, claimed, contextOf, deprecationOf, docOf, headerOf, identifierOf, keyOf, localOf, sorted, } from "../domain/names.js";
 /**
  * The DTOs of a bounded context as TypeScript, out of the contract sincpro_framework exports:
- * a type per model, per shared definition a model or an operation reaches, and per operation's
- * input and answer. Only types — nothing in the file runs.
+ * a type per model, per shared definition a model or an operation reaches, per operation's
+ * input and answer, and per domain event when the contract carries them. Only types — nothing in
+ * the file runs.
+ *
+ * Context: types, never classes. The wire is JSON, and a type says exactly what it holds — a
+ * decimal as text, a page as `{items, count, cursor}` —, where a class would claim more unless
+ * every field had a reader. And the local bus routes by class: a generated class extending
+ * `Command` could be registered and executed locally, the confusion between a remote operation
+ * and a local use case this package keeps apart. Events read best as a union narrowed by `name`.
  *
  * Context: the file is a snapshot for whoever writes code — a person, or an agent reading the
  * repository —, never the truth at runtime: the transport keeps reading the live definition and
@@ -46,11 +53,17 @@ function keyNote(schema) {
         return undefined;
     return `The key of a \`${said.relation}\`.`;
 }
-function scopeOf(metamodel) {
+/**
+ * What each reference of a rendering names. `input`: the rendering is what a caller SENDS — an
+ * operation's input —, so a model there is its `<Name>Input`, whose fields follow the contract's
+ * `required`, not the record a read answers whole.
+ */
+function scopeOf(metamodel, shared, input = false) {
     const definitions = metamodel.$defs ?? {};
     const scope = {
-        reached: new Set(),
-        imports: new Set(),
+        reached: shared?.reached ?? new Set(),
+        imports: shared?.imports ?? new Set(),
+        inputs: shared?.inputs ?? new Set(),
         refer: (ref) => {
             const model = ref.startsWith(MODELS);
             if (!model && !ref.startsWith(DEFINITIONS))
@@ -60,7 +73,10 @@ function scopeOf(metamodel) {
             if (model || name in metamodel.models) {
                 if (!(name in metamodel.models))
                     throw new Error(`"${ref}" names no model of ${contextOf(metamodel)}`);
-                return identifierOf(name);
+                if (!input)
+                    return identifierOf(name);
+                scope.inputs.add(name);
+                return `${identifierOf(name)}Input`;
             }
             const imported = IMPORTED[name];
             if (imported !== undefined) {
@@ -86,16 +102,13 @@ function optional(name, property, schema, record) {
         return EXPANDED.has(property["x-sincpro"]?.type ?? "");
     return !(schema.required ?? []).includes(name);
 }
-/**
- * The records a to-many holds, when `property` is one — however the contract writes it: the
- * collection a reading answers (`{items, count, cursor}`, sincpro_framework 3.33 on) or, before
- * that, a bare array, which said less than the wire sent.
- */
+/** The records a to-many holds, when `property` is one: the `items` of the collection a reading
+ *  answers (`{items, count, cursor}`). */
 function heldRecords(property) {
     if (!TO_MANY.has(property["x-sincpro"]?.type ?? ""))
         return undefined;
-    const held = property.properties?.["items"] ?? property;
-    return held.type === "array" ? held.items : undefined;
+    const held = property.properties?.["items"];
+    return held?.type === "array" ? held.items : undefined;
 }
 /**
  * A property's TypeScript. A to-many inside a record is an `EntityCollection` of its records —
@@ -179,21 +192,37 @@ function operationDoc(metamodel, local, operation) {
     ].filter((one) => one !== undefined);
     return (docOf([operation.description, `${facts.join(" · ")}.`, deprecationOf(metamodel, operation)], "") || `/** ${local} */\n`);
 }
+/** What the server says of an event: its words, then its wire name and who records or hears it. */
+function eventDoc(metamodel, name, event) {
+    const alias = aliasOf(metamodel);
+    const facts = [
+        `\`${name}\` on the wire`,
+        event.recorded ? `recorded by «${alias}»` : undefined,
+        event.handled ? `handled by «${alias}»` : undefined,
+    ].filter((one) => one !== undefined);
+    return docOf([event.description, `${facts.join(" · ")}.`], "");
+}
 /**
  * The TypeScript of every DTO of `metamodel`, as the text of one file.
  *
  * 1. The models, by name: an entity's contract, a related model by its own name.
  * 2. Each operation, by its local name (its identity without `<context>.`): its input as
- *    `<Name>` and its answer by the backend's own name for it (`answerOf`: `ResponseX`), with
- *    `<Name>Answer` kept as a deprecated alias — or as `<Name>Answer` when it has no name.
- * 3. The shared definitions those reach — and the ones those reach, until none is new —, but
+ *    `<Name>` and its answer by the backend's own name for it (`answerOf`: `ResponseX`) — or as
+ *    `<Name>Answer` when it has no name.
+ * 3. A model an input carries — and the ones it carries, until none is new — as `<Name>Input`:
+ *    what a caller sends follows the contract's `required`; the server fills the rest.
+ * 4. Each domain event, when the contract carries them, by its class's name (`title`): a record
+ *    as it is received — every field present, `name` its wire name as a literal —, and
+ *    `DomainEvent`, the union of them all, which a `switch` on `name` narrows.
+ * 5. The shared definitions those reach — and the ones those reach, until none is new —, but
  *    never one a package of the stack already types (`Criteria`).
  * Final: a header that says where it came from and not to edit it, the imports, then models,
- *    definitions and operations, each sorted by name; two of them with one TypeScript name are
- *    refused, naming both.
+ *    definitions, operations and events, each sorted by name; two of them with one TypeScript
+ *    name are refused, naming both.
  */
 export function domainFileOf(metamodel) {
     const scope = scopeOf(metamodel);
+    const sent = scopeOf(metamodel, scope, true);
     const definitions = metamodel.$defs ?? {};
     const claim = claimed();
     const models = sorted(metamodel.models).map(([name, schema]) => {
@@ -210,19 +239,47 @@ export function domainFileOf(metamodel) {
             ? "unknown"
             : (streamed(operation.output, scope) ?? typeOf(operation.output, scope, 0, false));
         const written = [
-            `${operationDoc(metamodel, local, operation)}export type ${local} = ${typeOf(operation.input, scope, 0, false)};`,
+            `${operationDoc(metamodel, local, operation)}export type ${local} = ${typeOf(operation.input, sent, 0, false)};`,
         ];
         if (!answered.has(named)) {
             answered.add(named);
             claim(named, `the answer of ${identity}`);
             written.push(`/** What \`${local}\` answers. */\nexport type ${named} = ${answer};`);
         }
-        if (named !== `${local}Answer`) {
-            claim(`${local}Answer`, `the old name of the answer of ${identity}`);
-            written.push(`/** @deprecated The backend calls it \`${named}\`: use that name. */\nexport type ${local}Answer = ${named};`);
-        }
         return written;
     });
+    // An event is a fact received whole: every field is there, as in a record a read answers. An
+    // event whose class is also a model — a context's base event, when a Feature hears it — is
+    // that model's type, narrowed to its own name: one class, one type.
+    const members = [];
+    const events = sorted(metamodel.events ?? {}).flatMap(([name, event]) => {
+        const type = identifierOf(event.title);
+        if (event.title in metamodel.models) {
+            members.push(`(${type} & { name: ${JSON.stringify(name)} })`);
+            return [];
+        }
+        claim(type, `event ${name}`);
+        members.push(type);
+        return [
+            `${eventDoc(metamodel, name, event)}export type ${type} = ${typeOf(event.schema, scope, 0, true)};`,
+        ];
+    });
+    if (members.length > 0) {
+        claim("DomainEvent", "the union of the domain events");
+        events.push(`${docOf([`Every domain event of «${aliasOf(metamodel)}» in the contract: a \`switch\` on \`name\` tells which.`], "")}export type DomainEvent =\n${members.map((one) => `  | ${one}`).join("\n")};`);
+    }
+    const inputs = new Map();
+    for (let pending = [...scope.inputs]; pending.length > 0;) {
+        for (const name of pending) {
+            const schema = metamodel.models[name];
+            inputs.set(name, `${docOf([`What a caller sends of a \`${name}\`: what the contract requires; the server fills the rest.`], "")}export type ${identifierOf(name)}Input = ${typeOf(schema, sent, 0, false)};`);
+        }
+        pending = [...scope.inputs].filter((name) => !inputs.has(name));
+    }
+    const sentModels = [...inputs.keys()].sort().map((name) => {
+        claim(`${identifierOf(name)}Input`, `what a caller sends of model ${name}`);
+        return inputs.get(name);
+    });
     const written = new Map();
     for (let pending = [...scope.reached]; pending.length > 0;) {
         for (const name of pending) {
@@ -244,5 +301,5 @@ export function domainFileOf(metamodel) {
     const imports = [...byPackage.keys()]
         .sort()
         .map((from) => `import type { ${byPackage.get(from).join(", ")} } from "${from}";`);
-    return `${[headerOf("The DTOs", metamodel), ...(imports.length === 0 ? [] : [imports.join("\n")]), ...models, ...shared, ...operations].join("\n\n")}\n`;
+    return `${[headerOf("The DTOs", metamodel), ...(imports.length === 0 ? [] : [imports.join("\n")]), ...models, ...sentModels, ...shared, ...operations, ...events].join("\n\n")}\n`;
 }

package/dist/codegen/{entities.d.ts → services/entities.d.ts}

@@ -1,12 +1,13 @@
-import type { Metamodel } from "./metamodel.js";
+import type { Metamodel } from "../domain/metamodel.js";
 import { type GenerateOptions } from "./rest.js";
 /**
  * The TypeScript of the entities of `metamodel`, as the text of one file next to its `domain.ts`.
  *
  * 1. Per model, by name: the one `search` a transport reads for it (`own` when there are
  *    several) — none, and the model gets no entity, said in the file's own doc.
- * 2. Its `get`, `edit` and `preview` the same way, the record's field written `{id}`, and its
- *    `export` — every record of a criteria as a file — by its path.
+ * 2. Its `get`, `edit` and `preview` the same way, the record's field written `{id}`; its
+ *    `events` — a record's `DomainEvents` — as `history`, the same way; and its `export` — every
+ *    record of a criteria as a file — by its path.
  * 3. Every write of role `command` that concerns it: with `target` when its body names the
  *    record, as it is when it creates one; its body typed without that field.
  * Final: an `entity<T, C>()` per model listed, keyed `<domain>:<kind>`, and `entities`, all of

package/dist/codegen/{entities.js → services/entities.js}

@@ -1,5 +1,5 @@
-import { entityKeyOf } from "../client/contract.js";
-import { aliasOf, answerOf, claimed, DOMAIN_MODULE, FRAMEWORK, headerOf, identifierOf, isEntity, localOf, methodOf, pluralOf, sorted, } from "./names.js";
+import { entityKeyOf } from "../../client/domain/contract.js";
+import { aliasOf, answerOf, claimed, DOMAIN_MODULE, FRAMEWORK, headerOf, identifierOf, isEntity, localOf, methodOf, pluralOf, sorted, } from "../domain/names.js";
 import { ownerOf, restOf, WRITES, } from "./rest.js";
 /** The one operation of `role` for `entity` a transport can call, by `own` when there are many. */
 function oneOf(candidates, role) {
@@ -90,6 +90,19 @@ function entitySourceOf(metamodel, model, domain, options, claim) {
         const route = `${write.found.rest.method} ${recordPath(write.found.rest, field)}`;
         routes.push(`  ${role}: ${JSON.stringify(route)},`);
     }
+    // A record's events (sincpro_framework's `DomainEvents`): its history, read by the record's key.
+    const events = oneOf(reads("events", isGet), "events");
+    if (events !== undefined) {
+        if ("missing" in events)
+            missing.push(`history: ${events.missing}`);
+        else {
+            const field = events.found.operation.targets[model];
+            if (field !== undefined && events.found.rest.fields.length === 1)
+                routes.push(`  history: ${JSON.stringify(recordPath(events.found.rest, field))},`);
+            else
+                missing.push(`history: \`${events.found.local}\` is at ${events.found.rest.path}`);
+        }
+    }
     const exported = oneOf(reads("export", isGet), "export");
     if (exported !== undefined) {
         if ("missing" in exported)
@@ -142,8 +155,9 @@ function entitySourceOf(metamodel, model, domain, options, claim) {
  *
  * 1. Per model, by name: the one `search` a transport reads for it (`own` when there are
  *    several) — none, and the model gets no entity, said in the file's own doc.
- * 2. Its `get`, `edit` and `preview` the same way, the record's field written `{id}`, and its
- *    `export` — every record of a criteria as a file — by its path.
+ * 2. Its `get`, `edit` and `preview` the same way, the record's field written `{id}`; its
+ *    `events` — a record's `DomainEvents` — as `history`, the same way; and its `export` — every
+ *    record of a criteria as a file — by its path.
  * 3. Every write of role `command` that concerns it: with `target` when its body names the
  *    record, as it is when it creates one; its body typed without that field.
  * Final: an `entity<T, C>()` per model listed, keyed `<domain>:<kind>`, and `entities`, all of

package/dist/codegen/{rest.d.ts → services/rest.d.ts}

@@ -1,4 +1,4 @@
-import type { Metamodel, Operation } from "./metamodel.js";
+import type { Metamodel, Operation } from "../domain/metamodel.js";
 /**
  * How REST reaches each operation of a contract, as the generated client and entities write it.
  *

package/dist/codegen/{scaffold.d.ts → services/scaffold.d.ts}

@@ -1,4 +1,4 @@
-import type { Metamodel } from "./metamodel.js";
+import type { Metamodel } from "../domain/metamodel.js";
 /**
  * A bounded context's skeleton, written ONCE beside what is generated — the files that are the
  * application's from then on:
@@ -7,7 +7,7 @@ import type { Metamodel } from "./metamodel.js";
  *       generated/                         `sincpro-client generate` — regenerated, never edited
  *       infrastructure/dependencies.ts     what the services can count on: the generated client
  *       infrastructure/bounded_context.ts  its Feature and ApplicationService, and how it is made
- *       services/index.ts                  the services, by the name each is reached by
+ *       services/index.ts                  registers command classes and their services
  *       index.ts                           `export const project` — ready to use
  *
  * Context: the layout sincpro_framework gives a service (`dependencies.py`, `framework.py`,
@@ -17,8 +17,11 @@ import type { Metamodel } from "./metamodel.js";
  * whole every time.
  */
 export type ScaffoldOptions = {
-    /** Where the application's transport is exported (`export const transport`), from the
-     *  bounded context's folder. `../common/infrastructure/transport` by default. */
-    transport?: string;
+    /**
+     * Where the application exports how it reaches its services (`export const operations`, an
+     * `OperationTransport`: REST, JSON-RPC, a platform's), from the bounded context's folder.
+     * `../common/infrastructure/operations` by default.
+     */
+    operations?: string;
 };
 export declare function scaffoldFilesOf(metamodel: Metamodel, options?: ScaffoldOptions): Record<string, string>;

package/dist/codegen/{scaffold.js → services/scaffold.js}

@@ -1,9 +1,8 @@
-import { aliasOf, FRAMEWORK } from "./names.js";
+import { aliasOf, FRAMEWORK } from "../domain/names.js";
 /** Names the skeleton's `index.ts` cannot give its constant. */
 const TAKEN = new Set([
-    "transport",
-    "features",
-    "applicationServices",
+    "operations",
+    "registerServices",
     ..."break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield let static implements interface package private protected public await".split(" "),
 ]);
 /** `sales-orders` → `SalesOrders`. */
@@ -27,11 +26,12 @@ export function scaffoldFilesOf(metamodel, options = {}) {
     const name = TAKEN.has(bare) ? `${bare}BoundedContext` : bare;
     const Dependencies = `${Name}Dependencies`;
     const client = metamodel.bindings !== undefined;
-    const transport = options.transport ?? at("..", "common", "infrastructure", "transport");
+    const operations = options.operations ?? at("..", "common", "infrastructure", "operations");
     const dependencies = [
         HEADER(`What the services of «${alias}» can count on`),
         "",
-        `import type { Transport, UseBoundedContext } from "${FRAMEWORK}";`,
+        `import type { OperationTransport } from "${FRAMEWORK}";`,
+        `import type { BoundedContext } from "${at(FRAMEWORK, "core")}";`,
         ...(client ? ["", `import { clientOf } from "${at("..", "generated", "client")}";`] : []),
         "",
         `/** What every service of «${alias}» finds on \`this\`${client ? ": `this.client`, the service's operations" : ""}. */`,
@@ -44,10 +44,10 @@ export function scaffoldFilesOf(metamodel, options = {}) {
         "}",
         "",
         "export function registerDependencies(",
-        `  bc: UseBoundedContext<${Dependencies}>,`,
-        `  ${client ? "transport" : "_transport"}: Transport,`,
+        `  bc: BoundedContext<${Dependencies}>,`,
+        `  ${client ? "operations" : "_operations"}: OperationTransport,`,
         ") {",
-        ...(client ? [`  bc.addDependency("client", clientOf(transport));`] : []),
+        ...(client ? [`  bc.addDependency("client", clientOf(operations));`] : []),
         "  return bc;",
         "}",
         "",
@@ -58,60 +58,56 @@ export function scaffoldFilesOf(metamodel, options = {}) {
         "import {",
         "  ApplicationService as BaseApplicationService,",
         "  Feature as BaseFeature,",
-        "  type Transport,",
-        "  UseBoundedContext,",
-        `} from "${FRAMEWORK}";`,
+        "  BoundedContext,",
+        "  type Command,",
+        "  type DomainEvent,",
+        `} from "${at(FRAMEWORK, "core")}";`,
+        `import type { OperationTransport } from "${FRAMEWORK}";`,
         "",
-        `import type { ${Name}Features } from "${at("..", "services")}";`,
         `import { type ${Dependencies}, registerDependencies } from "${at(".", "dependencies")}";`,
         "",
-        `/** A Feature of «${alias}»: its dependencies typed on \`this\`, and \`this.context\`. */`,
-        `export class Feature extends BaseFeature<${Dependencies}> {}`,
+        `/** A Feature of «${alias}» — of a Command, or a subscriber of an event: its dependencies typed on \`this\`, and \`this.context\`. */`,
+        "export abstract class Feature<C extends Command<R> | DomainEvent, R> extends BaseFeature<C, R> {",
+        ...(client ? [`  declare readonly client: ${Dependencies}["client"];`] : []),
+        "}",
         "",
-        `/** An ApplicationService of «${alias}»: the same, and \`this.feature.<Name>\` for each Feature. */`,
-        "export class ApplicationService extends BaseApplicationService<",
-        `  ${Dependencies},`,
-        `  ${Name}Features`,
-        "> {}",
+        `/** An ApplicationService of «${alias}»: the same, and \`this.featureBus.execute(dto)\`. */`,
+        "export abstract class ApplicationService<C extends Command<R> | DomainEvent, R> extends BaseApplicationService<C, R> {",
+        ...(client ? [`  declare readonly client: ${Dependencies}["client"];`] : []),
+        "}",
         "",
-        `export function config${Name}BoundedContext(name: string, transport: Transport) {`,
-        `  return registerDependencies(new UseBoundedContext<${Dependencies}>(name), transport);`,
+        `export function config${Name}BoundedContext(name: string, operations: OperationTransport) {`,
+        `  return registerDependencies(new BoundedContext<${Dependencies}>(name), operations);`,
         "}",
         "",
     ].join("\n");
     const services = [
         HEADER(`What «${alias}» offers`),
         "",
-        "/**",
-        ` * Each service by the name it is reached by — \`${name}.Issues.close(…)\`. A Feature groups the`,
-        " * operations of one part of the domain; an ApplicationService composes the Features:",
-        " *",
-        " *     // services/issues.ts",
-        ` *     export class Issues extends Feature {`,
-        " *       close(input: dto.CommandCloseIssue) {",
-        " *         return this.client.closeIssue(input);",
-        " *       }",
-        " *     }",
-        " */",
-        "export const features = {};",
-        "export const applicationServices = {};",
+        `import type { BoundedContext } from "${at(FRAMEWORK, "core")}";`,
+        `import type { ${Dependencies} } from "${at("..", "infrastructure", "dependencies")}";`,
         "",
-        `export type ${Name}Features = typeof features;`,
+        "/** Register local Command classes with their Features and ApplicationServices.",
+        " * Generated DTO types are remote contracts, not runtime command constructors: import",
+        ` * them under their own name — \`import type * as remote from "${at("..", "generated", "domain")}"\` —`,
+        " * and let a local Command implement one (`implements remote.CommandCancelIssue`).",
+        " * Register with context.feature(CommandClass)(FeatureClass) or",
+        " * context.appService(CommandClass)(ApplicationServiceClass).",
+        " */",
+        `export function registerServices(_context: BoundedContext<${Dependencies}>): void {}`,
         "",
     ].join("\n");
     const index = [
         HEADER(`«${alias}», ready to use`),
         "",
-        `import { transport } from "${transport}";`,
+        `import { operations } from "${operations}";`,
         "",
         `import { config${Name}BoundedContext } from "${at(".", "infrastructure", "bounded_context")}";`,
-        `import { applicationServices, features } from "${at(".", "services")}";`,
+        `import { registerServices } from "${at(".", "services")}";`,
         "",
-        `/** «${alias}»: \`${name}.<Service>.<method>(…)\` — from a screen, a test, another bounded context. */`,
-        `export const ${name} = config${Name}BoundedContext(${JSON.stringify(alias)}, transport).register({`,
-        "  features,",
-        "  applicationServices,",
-        "});",
+        `/** «${alias}»: \`${name}.execute(new Command(...))\`. */`,
+        `export const ${name} = config${Name}BoundedContext(${JSON.stringify(alias)}, operations);`,
+        `registerServices(${name});`,
         "",
     ].join("\n");
     return {

package/dist/common/failures.d.ts

@@ -0,0 +1,83 @@
+import type { FailureKind, NextStep, Problem } from "@sincpro/criteria";
+/**
+ * What kind of failure an error is, whatever raised it — the backend's `common/failures`, read
+ * on a client: a refusal the server explained, a request nobody answered, a run a screen
+ * cancelled, a local domain's own refusal, another backend's error a platform translated.
+ *
+ *     failureOf(new TransportError("/pay", 409, problem))   ->  { kind: "conflict", nextStep: "refresh_and_retry", … }
+ *     failureOf(new TransportError("/pay", null, null))      ->  { kind: "unknown_outcome", fault: true, … }
+ *     failureOf(new CreditExhausted())                       ->  what the class declares (`failureKind`)
+ *     failureOf(new TypeError("x"))                          ->  { kind: "internal", fault: true, … }
+ *
+ * Context: every client decides the same things about a failure — show it or report it, retry it
+ * or set it aside, ask to sign in again —, and each app was deciding them its own way. The words
+ * are the wire's (`FailureKind`, `NextStep`, `Problem` from @sincpro/criteria), the rules the
+ * backend's: a retryable kind is retried after `retryAfter`; a permanent one fails the same way on
+ * every attempt and is set aside; a fault is the system's problem and is reported. An error says
+ * its own kind (`failureKind`, as the backend's errors do), so nothing here knows who raised it:
+ * a platform's adapter translates its backend's errors into errors that declare one.
+ */
+export type Failure = {
+    readonly kind: FailureKind;
+    /** UPPER_SNAKE and stable: what a client switches on. */
+    readonly reason: string;
+    /** What the caller does next. */
+    readonly nextStep: NextStep;
+    /** Whether sending the same thing again — as it is, or after a fresh read — may succeed. */
+    readonly retryable: boolean;
+    /** Seconds to wait before retrying; none when retrying does not help. */
+    readonly retryAfter: number | undefined;
+    /** It fails the same way on every attempt: a queue sets it aside, never retries it. */
+    readonly permanent: boolean;
+    /** The system's problem — a bug, a server down, no answer —, not an answer to the caller. */
+    readonly fault: boolean;
+    /** Whoever asked stopped waiting: not a failure of anyone. */
+    readonly aborted: boolean;
+    /** What the server said, when it said it. */
+    readonly problem: Problem | undefined;
+};
+/**
+ * What an error can say about itself — on the instance or as a static of its class:
+ *
+ *     class CreditExhausted extends Error {
+ *       static readonly failureKind = "exhausted";
+ *       readonly retryAfter = 30;
+ *     }
+ */
+export type DeclaredFailure = {
+    readonly failureKind?: FailureKind;
+    readonly reason?: string;
+    readonly retryAfter?: number;
+};
+/** The kinds that fail the same way on every attempt — set aside at the first failure. */
+export declare const PERMANENT_KINDS: ReadonlySet<FailureKind>;
+/**
+ * The kind each wire's own code stands for, when an answer carries no `Problem` — the backend's
+ * tables, read back, so a transport of any wire (REST, JSON-RPC, gRPC, another backend's) builds
+ * errors that declare the same kinds:
+ *
+ *     class RpcError extends Error {
+ *       constructor(readonly code: number, message: string) { super(message); }
+ *       get failureKind() { return kindOfJsonRpcCode(this.code); }
+ *     }
+ */
+export declare function kindOfHttpStatus(status: number): FailureKind;
+/** The kind a gRPC status code stands for — the backend's gRPC table, read back. */
+export declare function kindOfGrpcCode(code: number): FailureKind;
+/** The kind a JSON-RPC error code stands for — the backend's catalogue, read back. */
+export declare function kindOfJsonRpcCode(code: number): FailureKind;
+/**
+ * The failure `error` is.
+ *
+ * 1. Whoever asked stopped waiting (`AbortError`): aborted — a write may have run, so its kind is
+ *    `unknown_outcome`, but it is nobody's failure.
+ * 2. What the error declares (`failureKind`, `reason`, `retryAfter`), on itself or its class.
+ * 3. What the server said (`problem`, a `Problem` — the same over REST, JSON-RPC and gRPC): its
+ *    kind, reason, next step and wait.
+ * 4. A REST answer (`TransportError`) with a status and no problem: the kind its HTTP status
+ *    stands for. Another wire's transport declares its kind instead (`kindOfGrpcCode`,
+ *    `kindOfJsonRpcCode`).
+ * 5. A request that got no answer (`status: null`): `unknown_outcome` — it may have run.
+ * Final: anything else is `internal`, a fault.
+ */
+export declare function failureOf(error: unknown): Failure;