@sincpro/client-framework 0.5.0 → 1.0.0

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

@@ -26,7 +26,11 @@ export type Schema = {
         type?: string;
         relation?: string | null;
         identity?: string;
+        /** A to-many whose records are other aggregates: listed and searched, never edited as lines. */
+        reference?: boolean;
     };
+    /** An answer that is bytes as they are produced (an export): the media types it may be. */
+    "x-sincpro-streamed"?: readonly string[];
 };
 export type Operation = {
     /** What it is for its entity: `search`, `get`, `edit`, `command`… */
@@ -49,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;
@@ -76,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
@@ -7,17 +7,20 @@ import { ownerOf, restOf, WRITES, } from "./rest.js";
  *
  * Context: a method only writes down the route the contract published and hands the call to the
  * transport, which keeps the rules — the `Idempotency-Key`, the `Problem`, the model's version.
- * A GET is a page (`list`), one record (`one`), or — a Query of the context's own, `GET /me` —
- * a read of its answer as it came (`readRoute`, over a transport that has `read`). A GET's
+ * A GET is a page (`list`), one record (`one`), a file (`export`: `downloadRoute`, its bytes as
+ * they arrive), or — a Query of the context's own, `GET /me` — a read of its answer as it came
+ * (`readRoute`, over a transport that has `read`). A GET's
  * keys in its path are required parameters; every other field is an optional one.
  */
 /** A search's fields a page asks with, not the screen: the criteria, and its cursor inside it. */
 const PAGED = new Set(["criteria", "cursor"]);
+/** An export's fields its method takes apart: the criteria and the format. */
+const EXPORTED = new Set(["criteria", "cursor", "format"]);
 /** A GET's parameters: the path's keys, and the rest of its input but what a page asks with. */
-function askedOf(operation, rest, paged) {
+function askedOf(operation, rest, paged, apart = PAGED) {
     const path = [...rest.fields].sort();
     const query = Object.keys(operation.input.properties ?? {})
-        .filter((one) => !path.includes(one) && !(paged && PAGED.has(one)))
+        .filter((one) => !path.includes(one) && !(paged && apart.has(one)))
         .sort();
     return { path, query };
 }
@@ -29,6 +32,9 @@ function callOf(metamodel, operation, rest) {
     const owner = ownerOf(metamodel, operation);
     if (operation.role === "search" && owner !== undefined && owner in metamodel.models)
         return { kind: "list", entity: owner, ...askedOf(operation, rest, true) };
+    // An export answers bytes, never JSON: it is downloaded.
+    if (operation.role === "export" && owner !== undefined && owner in metamodel.models)
+        return { kind: "download", entity: owner, ...askedOf(operation, rest, true, EXPORTED) };
     const field = owner === undefined ? undefined : operation.targets[owner];
     const record = rest.fields.length === 1 && rest.fields[0] === field;
     if (operation.role === "get" && owner !== undefined && field !== undefined && record)
@@ -78,6 +84,15 @@ function methodSourceOf(local, answer, method, call, rest, doc) {
         const signature = params.signature === "" ? "" : `, ${params.signature}`;
         return `${doc}    ${method}: (criteria: Criteria<${entity}>${signature}) =>\n      transport.list<${entity}>(${params.route(rest.path)}, criteria),`;
     }
+    if (call.kind === "download") {
+        const entity = `dto.${identifierOf(call.entity)}`;
+        const params = paramsOf(call);
+        // The path's keys are required, so they come first: a required parameter never follows an
+        // optional one.
+        const keys = params.signature === "" ? "" : `${params.signature.replace("params?:", "params:")}, `;
+        const given = params.signature === "" ? "" : ", params";
+        return `${doc}    ${method}: (${keys}criteria?: Criteria<${entity}>, format?: ExportFormat) =>\n      downloadRoute(transport, exportRoute(${JSON.stringify(rest.path)}, criteria, format${given})),`;
+    }
     if (call.kind === "read") {
         const params = paramsOf(call);
         return `${doc}    ${method}: (${params.signature}) =>\n      readRoute<dto.${answer}>(transport, ${params.route(rest.path)}),`;
@@ -108,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.
  */
@@ -122,6 +139,7 @@ export function clientFileOf(metamodel, options = {}) {
     let paged = false;
     let reads = false;
     let sends = false;
+    let downloads = false;
     for (const [identity, operation] of operations) {
         const local = localOf(metamodel, identity);
         const rest = restOf(metamodel, identity, options);
@@ -135,6 +153,10 @@ export function clientFileOf(metamodel, options = {}) {
         claim(method, `operation ${identity}`);
         const doc = docOf([operation.description, deprecationOf(metamodel, operation)], "    ");
         methods.push(methodSourceOf(local, answerOf(metamodel, identity), method, call, rest, doc));
+        if (call.kind === "download") {
+            downloads = true;
+            paged = true;
+        }
         if (call.kind === "list" || call.kind === "read") {
             paged ||= call.kind === "list";
             reads ||= call.kind === "read";
@@ -147,6 +169,7 @@ export function clientFileOf(metamodel, options = {}) {
     }
     const core = [
         "bindable",
+        ...(downloads ? ["downloadRoute", "type ExportFormat", "exportRoute"] : []),
         ...(lists ? ["listRoute"] : []),
         ...(sends ? ["pathFor"] : []),
         ...(reads ? ["readRoute"] : []),
@@ -160,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`,
@@ -174,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
@@ -20,7 +27,11 @@ const DEFINITIONS = "#/$defs/";
 /** A shared definition a package of the stack already types: imported, never written again. */
 const IMPORTED = {
     Criteria: { name: "Criteria", from: "@sincpro/criteria" },
+    Download: { name: "Download", from: "@sincpro/client-framework" },
+    EntityCollection: { name: "EntityCollection", from: "@sincpro/client-framework" },
 };
+/** A relation that holds several records: a reading answers it as a page of them. */
+const TO_MANY = new Set(["one2many", "many2many"]);
 /** The field types whose value is the record itself, not a key that names it. */
 const RELATIONAL = new Set(["many2one", "one2many", "many2many", "embedded"]);
 /** A related record: in an answer only when the read expands it. */
@@ -42,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))
@@ -56,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) {
@@ -82,6 +102,26 @@ 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: 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"];
+    return held?.type === "array" ? held.items : undefined;
+}
+/**
+ * A property's TypeScript. A to-many inside a record is an `EntityCollection` of its records —
+ * a page with its count and cursor, as the read answers it — never an array, which would say the
+ * page is all there is.
+ */
+function propertyTypeOf(property, scope, depth, record) {
+    const records = record ? heldRecords(property) : undefined;
+    if (records === undefined)
+        return typeOf(property, scope, depth, record);
+    scope.imports.add("EntityCollection");
+    return `EntityCollection<${typeOf(records, scope, depth, record)}>`;
+}
 function objectOf(schema, scope, depth, record) {
     const properties = sorted(schema.properties ?? {});
     if (properties.length === 0) {
@@ -95,7 +135,7 @@ function objectOf(schema, scope, depth, record) {
     const lines = properties.map(([name, property]) => {
         const doc = docOf([property.description, keyNote(property)], pad);
         const mark = optional(name, property, schema, record) ? "?" : "";
-        return `${doc}${pad}${keyOf(name)}${mark}: ${typeOf(property, scope, depth + 1, record)};`;
+        return `${doc}${pad}${keyOf(name)}${mark}: ${propertyTypeOf(property, scope, depth + 1, record)};`;
     });
     return `{\n${lines.join("\n")}\n${"  ".repeat(depth)}}`;
 }
@@ -133,6 +173,13 @@ function typeOf(schema, scope, depth, record) {
                 : objectOf(schema, scope, depth, record);
     }
 }
+/** What a streamed answer is on the client — an export's bytes (`Download`) —, else nothing. */
+function streamed(output, scope) {
+    if (output["x-sincpro-streamed"] === undefined)
+        return undefined;
+    scope.imports.add("Download");
+    return "Download";
+}
 /** What the server says of an operation: its words, then what it is, for whom, on which field. */
 function operationDoc(metamodel, local, operation) {
     const runsOn = sorted(operation.targets).map(([entity, field]) => `\`${entity}\` in \`${field}\``);
@@ -145,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]) => {
@@ -172,21 +235,51 @@ export function domainFileOf(metamodel) {
         const local = localOf(metamodel, identity);
         const named = answerOf(metamodel, identity);
         claim(local, `operation ${identity}`);
-        const answer = operation.output === null ? "unknown" : typeOf(operation.output, scope, 0, false);
+        const answer = operation.output === null
+            ? "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) {
@@ -199,9 +292,14 @@ export function domainFileOf(metamodel) {
         claim(identifierOf(name), `definition ${name}`);
         return written.get(name);
     });
-    const imports = [...scope.imports].sort().map((name) => {
+    // One line per package, its names sorted.
+    const byPackage = new Map();
+    for (const name of [...scope.imports].sort()) {
         const imported = IMPORTED[name];
-        return `import type { ${imported.name} } from "${imported.from}";`;
-    });
-    return `${[headerOf("The DTOs", metamodel), ...(imports.length === 0 ? [] : [imports.join("\n")]), ...models, ...shared, ...operations].join("\n\n")}\n`;
+        byPackage.set(imported.from, [...(byPackage.get(imported.from) ?? []), imported.name]);
+    }
+    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, ...sentModels, ...shared, ...operations, ...events].join("\n\n")}\n`;
 }

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

@@ -1,11 +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}`.
+ * 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) {
@@ -61,10 +61,18 @@ function entitySourceOf(metamodel, model, domain, options, claim) {
     const missing = [];
     const routes = [`  list: ${JSON.stringify(list.found.rest.path)},`];
     const one = oneOf(reads("get", isGet), "get");
+    const edit = oneOf(reads("edit", isWrite), "edit");
     if (one !== undefined && "found" in one) {
         const field = one.found.operation.targets[model];
+        // sincpro_framework's `Get` answers the caller's own draft only when asked (`draft`), and an
+        // entity edited through `Edit` keeps its drafts there: its record is read with them, or a
+        // draft kept on one visit never comes back on the next.
+        const drafts = edit !== undefined &&
+            "found" in edit &&
+            one.found.operation.input.properties?.["draft"]?.type === "boolean";
+        const path = `${recordPath(one.found.rest, field)}${drafts ? "?draft=true" : ""}`;
         if (field !== undefined && one.found.rest.fields.length === 1)
-            routes.push(`  one: ${JSON.stringify(recordPath(one.found.rest, field))},`);
+            routes.push(`  one: ${JSON.stringify(path)},`);
         else
             missing.push(`one: \`${one.found.local}\` is at ${one.found.rest.path}`);
     }
@@ -82,6 +90,26 @@ 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)
+            missing.push(`export: ${exported.missing}`);
+        else
+            routes.push(`  export: ${JSON.stringify(exported.found.rest.path)},`);
+    }
     const commands = reached.filter((one) => one.operation.role === "command" &&
         isWrite(one.rest.method) &&
         one.operation.entities.includes(model));
@@ -127,7 +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}`.
+ * 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.
  *