@sincpro/client-framework 0.6.0 → 1.0.0

package/dist/client/{memory.d.ts → adapters/memory.d.ts}

@@ -1,4 +1,4 @@
-import { type Draft, type Method, type Transport } from "./transport.js";
+import { type Draft, type Method, type Transport } from "../domain/transport.js";
 import type { AnyRecord, Criteria, Meta, Problem } from "@sincpro/criteria";
 /**
  * A server held in memory: tables of rows with their definition, answered with the same

package/dist/client/{memory.js → adapters/memory.js}

@@ -1,5 +1,5 @@
-import { TransportError, } from "./transport.js";
-import { pack, readValues } from "../common/serialization.js";
+import { TransportError, } from "../domain/transport.js";
+import { pack, readValues } from "../../common/serialization.js";
 import { answer, answerGroups } from "@sincpro/criteria/engine";
 /**
  * A deep copy written and read by the wire's rules (`pack`, `readValues`): what a real server

package/dist/{adapters → client/adapters}/parquet.d.ts

@@ -1,4 +1,4 @@
-import type { Decoder } from "../client/transport.js";
+import type { Decoder } from "../domain/transport.js";
 import type { AnyRecord, Count, Dropped, Envelope } from "@sincpro/criteria";
 /**
  * A page sincpro_framework answered as Parquet, read into what JSON would have sent — the

package/dist/client/{rest.d.ts → adapters/rest.d.ts}

@@ -1,4 +1,4 @@
-import { type Decoder, type Transport } from "./transport.js";
+import { type Decoder, type Transport } from "../domain/transport.js";
 import { type Criteria } from "@sincpro/criteria";
 /**
  * The REST wire of sincpro_framework (`FastApiGateway`).

package/dist/client/{rest.js → adapters/rest.js}

@@ -1,5 +1,5 @@
-import { definitionOf, modelAt, } from "./discovery.js";
-import { TransportError, } from "./transport.js";
+import { TransportError, } from "../domain/transport.js";
+import { definitionOf, modelAt, } from "../services/discovery.js";
 import { readProblem } from "@sincpro/criteria";
 import { RestError, restSource } from "@sincpro/criteria/rest";
 /** The keys of an answer that are not the record: what is left is the record's own field. */

package/dist/client/{entity.d.ts → domain/entity.d.ts}

@@ -49,7 +49,7 @@ export type CommandAnswers = Readonly<Record<string, unknown>>;
  *       save: "PUT /invoices/{id}",
  *       preview: "POST /invoices/preview",
  *       commands: { confirm: "POST /invoices/{id}/confirm", cancel: "POST /invoices/{id}/cancel" },
- *       history: { route: "/billing-events", type: "Invoice" },
+ *       history: "/invoices/{id}/events",
  *     });
  *
  * Its Commands may be typed too — what each one is sent with, by name (`CommandBodies`), and
@@ -92,11 +92,9 @@ export type Entity<T extends AnyRecord = AnyRecord, C extends CommandBodies = Co
      *  `action`. Declared, a save sends the record whole as the form holds it — not the fields
      *  that changed under `save` — and it is also where the draft is kept. */
     edit?: WriteRoute;
-    /** Its business events: the context's events route, and the `entity_type` they carry. */
-    history?: {
-        route: string;
-        type: string;
-    };
+    /** Its business events: where ONE record's events are read (sincpro_framework's
+     *  `DomainEvents`), `{id}` where its key goes — a page of them, as a list answers. */
+    history?: string;
     /** Every record of a criteria as a file: the route `exportRoute` fills, `downloadRoute` asks. */
     export?: string;
     /** Which fields are its description, state, picture… when they are not the conventional
@@ -191,10 +189,8 @@ export type EntityRoutes<C extends CommandBodies = CommandBodies> = CommandRoute
     draft?: string;
     /** `"PUT /invoices/{id}/edit"`: the use case that answers sincpro_framework's `Edit`. */
     edit?: string;
-    history?: {
-        route: string;
-        type: string;
-    };
+    /** `"/invoices/{id}/events"`: a record's events (`DomainEvents[Invoice, …]`), oldest first. */
+    history?: string;
     /** `"/invoices/export"`: every record of a criteria as a file (`Export[Invoice, Streamed]`),
      *  asked through `exportRoute` and `downloadRoute`. */
     export?: string;

package/dist/client/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The seam with a server: the `Transport` port and its implementations, entities with typed
+ * commands, the service's client contract, and how a run's trace and context reach the wire.
+ *
+ *   domain/    the port and the server's words: `Transport`, `TransportError`, `entity()`, the
+ *              client contract
+ *   adapters/  REST, memory, and Parquet (optional entry `./parquet`)
+ *   services/  discovery, retry keys, propagation (`traceparent`, `sincpro-context`)
+ */
+export { type MemoryOptions, type MemoryTable, memoryTransport, } from "./adapters/memory.js";
+export { type RestOptions, restTransport, urlOf, type VersionDrift, } from "./adapters/rest.js";
+export { type ClientContract, entityKeyOf, kindOf, metasOf, versionsOf, } from "./domain/contract.js";
+export { bodyFor, type CommandAnswers, type CommandBodies, type CommandRoute, type Entity, entity, type EntityRef, type EntityRoutes, type ExportFormat, exportRoute, listRoute, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, SCOPE_PARAM, scopeOfRef, startingValuesOf, type SummaryFields, type SummaryPart, TRAIL_PARAM, WITH_PARAM, type WriteRoute, writeRoute, } from "./domain/entity.js";
+export { type CallOptions, type Decoder, type Download, downloadRoute, type Draft, type Method, type One, readRoute, type SendOptions, type Transport, TransportError, } from "./domain/transport.js";
+export { bindable, bindTransport, headersOf, } from "./services/propagation.js";
+export { type RetryKeys, retryKeys, unanswered, } from "./services/retry.js";

package/dist/client/index.js

@@ -0,0 +1,16 @@
+/**
+ * The seam with a server: the `Transport` port and its implementations, entities with typed
+ * commands, the service's client contract, and how a run's trace and context reach the wire.
+ *
+ *   domain/    the port and the server's words: `Transport`, `TransportError`, `entity()`, the
+ *              client contract
+ *   adapters/  REST, memory, and Parquet (optional entry `./parquet`)
+ *   services/  discovery, retry keys, propagation (`traceparent`, `sincpro-context`)
+ */
+export { memoryTransport, } from "./adapters/memory.js";
+export { restTransport, urlOf, } from "./adapters/rest.js";
+export { entityKeyOf, kindOf, metasOf, versionsOf, } from "./domain/contract.js";
+export { bodyFor, entity, exportRoute, listRoute, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, SCOPE_PARAM, scopeOfRef, startingValuesOf, TRAIL_PARAM, WITH_PARAM, writeRoute, } from "./domain/entity.js";
+export { downloadRoute, readRoute, TransportError, } from "./domain/transport.js";
+export { bindable, bindTransport, headersOf, } from "./services/propagation.js";
+export { retryKeys, unanswered, } from "./services/retry.js";

package/dist/client/services/propagation.d.ts

@@ -0,0 +1,32 @@
+import type { Transport } from "../domain/transport.js";
+import { type Execution } from "../../context/domain/execution.js";
+/** Whether a value is a `Transport`: what a run binds to itself even without `BIND`. */
+export declare function isTransport(value: unknown): value is Transport;
+/**
+ * What every request of an execution carries: its trace (`traceparent`, W3C) and its context
+ * (`sincpro-context`, the header sincpro_framework's entrances read, written with `plainCodec`).
+ * Nothing when there is no trace and no context that travels.
+ */
+export declare function headersOf(execution: Execution): Record<string, string>;
+/**
+ * The transport, writing the execution's headers on every call — the caller's own headers of a
+ * call still win.
+ *
+ * Context: the transport's own headers (`restTransport({ headers })`) are the session's — the
+ * token, the tenant — the same for every call; these are the use case's, different for two use
+ * cases running at once, so they travel per call (`CallOptions`).
+ */
+export declare function bindTransport(transport: Transport, execution: Execution): Transport;
+/**
+ * A client made over a transport, made again over the transport bound to each execution it is
+ * used in. What a generated `clientOf(transport)` answers, so a Feature that calls
+ * `this.client.sendIssue(…)` sends that request with its own trace.
+ *
+ *     export function clientOf(transport: Transport) {
+ *       return bindable(transport, (transport) => ({ sendIssue: (body) => transport.send(…) }));
+ *     }
+ *
+ * Context: it takes the function that makes the client, not the client — rebuilding through
+ * `clientOf` itself would make TypeScript infer `clientOf` from its own return.
+ */
+export declare function bindable<T extends object>(transport: Transport, make: (transport: Transport) => T): T;

package/dist/{services/execution.js → client/services/propagation.js}

@@ -1,16 +1,8 @@
-import { CONTEXT_HEADER, plainCodec, travels } from "../context/codec.js";
-/**
- * A dependency that has something to say about the execution it is used in: given that
- * execution, it answers itself bound to it. The transport and every generated client are;
- * any other dependency of a bounded context is handed as it is.
- */
-export const BIND = Symbol.for("sincpro.client-framework.bind");
-function isBindable(value) {
-    return (value !== null &&
-        (typeof value === "object" || typeof value === "function") &&
-        typeof value[BIND] === "function");
-}
-function isTransport(value) {
+import { plainCodec } from "../../context/adapters/plain-codec.js";
+import { CONTEXT_HEADER, travels } from "../../context/domain/codec.js";
+import { BIND } from "../../context/domain/execution.js";
+/** Whether a value is a `Transport`: what a run binds to itself even without `BIND`. */
+export function isTransport(value) {
     if (value === null || typeof value !== "object")
         return false;
     const one = value;
@@ -83,11 +75,3 @@ export function bindable(transport, make) {
     });
     return client;
 }
-/** A dependency as the execution should see it: bound when it can be, as it is otherwise. */
-export function bindDependency(value, execution) {
-    if (isBindable(value))
-        return value[BIND](execution);
-    if (isTransport(value))
-        return bindTransport(value, execution);
-    return value;
-}

package/dist/client/{retry.js → services/retry.js}

@@ -1,4 +1,4 @@
-import { TransportError } from "./transport.js";
+import { TransportError } from "../domain/transport.js";
 /** Whether a failure leaves it unknown if the Command ran — so a retry must reuse its key. */
 export function unanswered(error) {
     if (!(error instanceof TransportError))

package/dist/codegen/{metamodel.d.ts → domain/metamodel.d.ts}

@@ -53,6 +53,21 @@ export type Operation = {
     /** The operation that replaces it, by identity. */
     replacement?: string | null;
 };
+/**
+ * A domain event of the bounded context — in a contract exported with its events
+ * (`export-client-contract --events`), keyed by its wire name (`DomainEvent.name`).
+ */
+export type EventDescription = {
+    /** Its class's name on the server: the type it is written as. */
+    title: string;
+    description?: string | null;
+    /** One of the bounded context's own events: its aggregates record it. */
+    recorded: boolean;
+    /** A Feature of the bounded context is registered for it: it subscribes. */
+    handled: boolean;
+    /** Every field it carries — the envelope and what happened —, `name` a constant. */
+    schema: Schema;
+};
 /** How REST reaches an operation: its method and its whole path, `{field}` where a field goes. */
 export type RestBinding = {
     method: string;
@@ -80,14 +95,14 @@ export type Metamodel = {
     /** The name the gateways publish it under (`FastApiGateway({"project": …})`): what a client
      *  names the context by. */
     alias?: string;
-    /** The bounded context's name, as sincpro_framework 3.32 wrote it before `bounded_context`. */
-    context?: string;
     version: string;
     /** Every shape the contract names: an entity (it has an `identity`) or a value it holds. */
     models: Readonly<Record<string, Schema>>;
     /** By the Command's identity, `"<bounded_context>.<Class>"`. */
     operations: Readonly<Record<string, Operation>>;
     $defs?: Readonly<Record<string, Schema>>;
+    /** Its domain events, by wire name — only when the contract was exported with them. */
+    events?: Readonly<Record<string, EventDescription>>;
     /** By wire, then by the Command's identity. */
     bindings?: Bindings;
 };

package/dist/codegen/{names.d.ts → domain/names.d.ts}

@@ -13,7 +13,7 @@ export declare function keyOf(name: string): string;
 export declare function sorted<V>(record: Readonly<Record<string, V>>): [string, V][];
 /** `{ Issue: "issue_id" }`: a record of texts as TypeScript writes it, keys sorted. */
 export declare function recordLiteral(record: Readonly<Record<string, string>>): string;
-/** The bounded context's own name: `bounded_context`, or `context` in a 3.32 contract. */
+/** The bounded context's own name: what every operation's identity starts with. */
 export declare function contextOf(metamodel: Metamodel): string;
 /** What a client names the context by: its `alias`, else its own name. */
 export declare function aliasOf(metamodel: Metamodel): string;
@@ -30,7 +30,7 @@ export declare function localOf(metamodel: Metamodel, identity: string): string;
  *
  * Context: the ubiquitous language. The backend writes `CommandCancelIssue` → `ResponseCancelIssue`,
  * and a client that calls it `CommandCancelIssueAnswer` makes a person learn two words for one
- * thing. The `<Name>Answer` it used to write stays as a deprecated alias of the backend's name.
+ * thing.
  */
 export declare function answerOf(metamodel: Metamodel, identity: string): string;
 /** The method an operation is called by: `CommandSendIssue` → `sendIssue`. */

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

@@ -32,9 +32,9 @@ export function recordLiteral(record) {
     const entries = sorted(record).map(([key, value]) => `${keyOf(key)}: ${JSON.stringify(value)}`);
     return entries.length === 0 ? "{}" : `{ ${entries.join(", ")} }`;
 }
-/** The bounded context's own name: `bounded_context`, or `context` in a 3.32 contract. */
+/** The bounded context's own name: what every operation's identity starts with. */
 export function contextOf(metamodel) {
-    const name = metamodel.bounded_context ?? metamodel.context;
+    const name = metamodel.bounded_context;
     if (name === undefined)
         throw new Error("the contract names no bounded context");
     return name;
@@ -100,7 +100,7 @@ function answersOf(metamodel) {
  *
  * Context: the ubiquitous language. The backend writes `CommandCancelIssue` → `ResponseCancelIssue`,
  * and a client that calls it `CommandCancelIssueAnswer` makes a person learn two words for one
- * thing. The `<Name>Answer` it used to write stays as a deprecated alias of the backend's name.
+ * thing.
  */
 export function answerOf(metamodel, identity) {
     let known = ANSWERS.get(metamodel);

package/dist/codegen/{cli.js → entrypoint/cli.js}

@@ -1,19 +1,20 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { CheckError, checkImports } from "./check.js";
-import { clientFileOf } from "./client.js";
-import { domainFileOf } from "./domain.js";
-import { entitiesFileOf } from "./entities.js";
-import { aliasOf } from "./names.js";
-import { scaffoldFilesOf } from "./scaffold.js";
+import { aliasOf } from "../domain/names.js";
+import { CheckError, checkImports } from "../services/check.js";
+import { clientFileOf } from "../services/client.js";
+import { domainFileOf } from "../services/domain.js";
+import { entitiesFileOf } from "../services/entities.js";
+import { scaffoldFilesOf } from "../services/scaffold.js";
 /**
  * `sincpro-client generate <contract.json> --out <dir> [--domain <name>] [--base <path>]` — what an
  * application's `make client` runs, once per bounded context, over the client contract
  * sincpro_framework exported (`export-client-contract`):
  *
- * - `domain.ts`: the DTOs, only types;
- * - `client.ts`: every operation as data, and `clientOf(transport)`;
+ * - `domain.ts`: the DTOs, only types — and the domain events with `DomainEvent`, their union,
+ *   when the contract was exported with them (`export-client-contract --events`);
+ * - `client.ts`: every operation (and event) as data, and `clientOf(transport)`;
  * - `entities.ts`: an `entity<T, C>()` per model a screen can list;
  * - `contract.json`: the snapshot they were written from, for `metasOf`.
  *

package/dist/codegen/index.d.ts

@@ -3,10 +3,10 @@
  * sincpro_framework exports (PRD_01 phase B). A build step that runs in Node — nothing in
  * the runtime imports it (`make doctor`), and the package's root entry does not re-export it. `sincpro-client generate` (`cli.ts`) is the same, from a terminal.
  */
-export { CheckError, checkImports, type Place, placeOf, type Violation, violationOf, } from "./check.js";
-export { clientFileOf } from "./client.js";
-export { domainFileOf } from "./domain.js";
-export { entitiesFileOf } from "./entities.js";
-export type { Bindings, Metamodel, Operation, RestBinding, Schema, } from "./metamodel.js";
-export type { GenerateOptions } from "./rest.js";
-export { scaffoldFilesOf, type ScaffoldOptions, } from "./scaffold.js";
+export type { Bindings, Metamodel, Operation, RestBinding, Schema, } from "./domain/metamodel.js";
+export { CheckError, checkImports, type Place, placeOf, type Violation, violationOf, } from "./services/check.js";
+export { clientFileOf } from "./services/client.js";
+export { domainFileOf } from "./services/domain.js";
+export { entitiesFileOf } from "./services/entities.js";
+export type { GenerateOptions } from "./services/rest.js";
+export { scaffoldFilesOf, type ScaffoldOptions, } from "./services/scaffold.js";

package/dist/codegen/index.js

@@ -1,10 +1,5 @@
-/**
- * The generator: a bounded context's DTOs, client and entities out of the client contract
- * sincpro_framework exports (PRD_01 phase B). A build step that runs in Node — nothing in
- * the runtime imports it (`make doctor`), and the package's root entry does not re-export it. `sincpro-client generate` (`cli.ts`) is the same, from a terminal.
- */
-export { CheckError, checkImports, placeOf, violationOf, } from "./check.js";
-export { clientFileOf } from "./client.js";
-export { domainFileOf } from "./domain.js";
-export { entitiesFileOf } from "./entities.js";
-export { scaffoldFilesOf, } from "./scaffold.js";
+export { CheckError, checkImports, placeOf, violationOf, } from "./services/check.js";
+export { clientFileOf } from "./services/client.js";
+export { domainFileOf } from "./services/domain.js";
+export { entitiesFileOf } from "./services/entities.js";
+export { scaffoldFilesOf, } from "./services/scaffold.js";

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

@@ -1,4 +1,4 @@
-import type { Metamodel } from "./metamodel.js";
+import type { Metamodel } from "../domain/metamodel.js";
 import { type GenerateOptions } from "./rest.js";
 /**
  * The TypeScript of the client of `metamodel`, as the text of one file next to its `domain.ts`.
@@ -8,6 +8,8 @@ import { type GenerateOptions } from "./rest.js";
  * 2. Per operation REST reaches, how a transport calls it (`callOf`): a page, a record, a write
  *    — or none, said in the client's own doc.
  * 3. The routes of the writes, read once (`writeRoute`).
+ * 4. When the contract carries them, every domain event as data, by its type's name: its wire
+ *    name, and whether the bounded context records it or handles it.
  * Final: `clientOf(transport)`, a method per operation reached, named by `methodOf`; two with
  *    one name are refused, naming both.
  */

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

@@ -1,4 +1,4 @@
-import { aliasOf, answerOf, claimed, deprecationOf, docOf, DOMAIN_MODULE, FRAMEWORK, headerOf, identifierOf, localOf, methodOf, recordLiteral, sorted, } from "./names.js";
+import { aliasOf, answerOf, claimed, deprecationOf, docOf, DOMAIN_MODULE, FRAMEWORK, headerOf, identifierOf, localOf, methodOf, recordLiteral, sorted, } from "../domain/names.js";
 import { ownerOf, restOf, WRITES, } from "./rest.js";
 /**
  * The client of a bounded context as TypeScript: every operation as data, and a method for each
@@ -123,6 +123,8 @@ function methodSourceOf(local, answer, method, call, rest, doc) {
  * 2. Per operation REST reaches, how a transport calls it (`callOf`): a page, a record, a write
  *    — or none, said in the client's own doc.
  * 3. The routes of the writes, read once (`writeRoute`).
+ * 4. When the contract carries them, every domain event as data, by its type's name: its wire
+ *    name, and whether the bounded context records it or handles it.
  * Final: `clientOf(transport)`, a method per operation reached, named by `methodOf`; two with
  *    one name are refused, naming both.
  */
@@ -181,6 +183,7 @@ export function clientFileOf(metamodel, options = {}) {
         "",
         `import type * as dto from "${DOMAIN_MODULE}";`,
     ].join("\n");
+    const events = sorted(metamodel.events ?? {}).map(([name, event]) => `  ${identifierOf(event.title)}: { name: ${JSON.stringify(name)}, recorded: ${event.recorded}, handled: ${event.handled} },`);
     const client = [
         "/**",
         ` * «${aliasOf(metamodel)}» over a transport: a method for each operation REST reaches as a`,
@@ -195,6 +198,11 @@ export function clientFileOf(metamodel, options = {}) {
         headerOf("The client", metamodel),
         imports,
         `/** Every operation of «${aliasOf(metamodel)}», as data: what it is, and how each wire reaches it. */\nexport const operations = {\n${data.join("\n")}\n} as const;`,
+        ...(events.length === 0
+            ? []
+            : [
+                `/** Every domain event of «${aliasOf(metamodel)}» in the contract, as data: its wire name, and whether it records or handles it. */\nexport const events = {\n${events.join("\n")}\n} as const;`,
+            ]),
         ...(routes.length === 0 ? [] : [`const routes = {\n${routes.join("\n")}\n};`]),
         `${client}\nexport function clientOf(transport: Transport) {\n  return bindable(transport, (transport) => ({\n${methods.join("\n")}\n  }));\n}`,
     ].join("\n\n")}\n`;

package/dist/codegen/services/domain.d.ts

@@ -0,0 +1,20 @@
+import type { Metamodel } from "../domain/metamodel.js";
+/**
+ * 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`) — 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, operations and events, each sorted by name; two of them with one TypeScript
+ *    name are refused, naming both.
+ */
+export declare function domainFileOf(metamodel: Metamodel): string;

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