@sincpro/client-framework 1.0.0 → 1.2.0

package/README.md

@@ -7,6 +7,8 @@ the same way, and a typed client generated from a service's contract. No React,
 platform storage: what a platform must give, it gives through a port.
 
 - [A bounded context](#a-bounded-context)
+- [Domain events](#domain-events)
+- [Extending the pipeline](#extending-the-pipeline)
 - [Errors](#errors)
 - [Observability](#observability)
 - [Context](#context)
@@ -63,12 +65,12 @@ class Quote extends ApplicationService<CommandQuote, ResponseTotal> {
   }
 }
 
-const sales = new BoundedContext<{ unitPrice: number }>("sales");
-sales.addDependency("unitPrice", 10);
-sales.feature(CommandTotal)(Total);
-sales.appService(CommandQuote)(Quote);
+const salesBoundedContext = new BoundedContext<{ unitPrice: number }>("sales");
+salesBoundedContext.addDependency("unitPrice", 10);
+salesBoundedContext.feature(CommandTotal)(Total);
+salesBoundedContext.appService(CommandQuote)(Quote);
 
-const answer = await sales.execute(new CommandQuote(3)); // ResponseTotal — total 30
+const answer = await salesBoundedContext.execute(new CommandQuote(3)); // ResponseTotal — total 30
 ```
 
 A Command names, by its type, the Response it answers: `execute` infers it, with no second
@@ -94,15 +96,240 @@ only). A Response may be a class, a plain object, a page, a primitive or `void`.
 ### Decorators, when the project has them
 
 ```ts
-@sales.feature(CommandTotal)
+@salesBoundedContext.feature(CommandTotal)
 class Total extends Feature<CommandTotal, ResponseTotal> { … }
 ```
 
 The same functions work as standard decorators and as legacy ones (`experimentalDecorators`);
-without a decorator transform, call them: `sales.feature(CommandTotal)(Total)`. No DI library
+without a decorator transform, call them: `salesBoundedContext.feature(CommandTotal)(Total)`. No DI library
 and no `reflect-metadata`. The tests compile both decorator forms with TypeScript; a bundler's
 transform (Vite, Metro/Babel) is each application's to configure and test.
 
+### Replacing a service
+
+An application takes the place of a service a module registered, as the backend's `replaces=`:
+
+```ts
+class PrintOnBixolon extends Print {
+  static override readonly serviceName = "PrintOnBixolon";
+  override execute(command: CommandPrint) { … }
+}
+printingBoundedContext.feature(CommandPrint, { replaces: Print })(PrintOnBixolon);
+printingBoundedContext.handlerOf(CommandPrint); // PrintOnBixolon
+```
+
+`replaces` names the service registered now for that class, or the registration is refused. The
+next call answers with the new one; its spans say which it replaced (`sincpro.replaces`). A
+service meant to be replaced by a subclass widens its name — `static readonly serviceName:
+string = "Print"` —, or TypeScript keeps the literal and the subclass cannot rename itself. A
+dependency is replaced the same way: `addDependency(name, next, { replaces: previous })`.
+
+## Domain events
+
+A fact that already happened — `OrderPaid` — is heard in one of two ways:
+
+| What hears it                                                                                 | When                                                                                       |
+| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| **A use case of the event**: a Feature or ApplicationService whose input _is_ the event       | the use case exists because of the event, and nothing else calls it                        |
+| **An `EventSubscriber`**: an entrypoint that reads the event and executes Commands on the bus | the event starts use cases that have their own Command — a screen or a cron calls them too |
+
+A subscriber is not a use case — it is a door, as a cron or a screen is: it decides nothing. Work
+of several steps is an ApplicationService (the workflow) that the subscriber executes, never
+logic in the subscriber.
+
+### A use case of the event
+
+The event is executed as a Command is: by the Feature or ApplicationService registered for its
+class in this bounded context, through the same pipeline (span, log lines, error handlers,
+report):
+
+```ts
+class OrderPaid extends DomainEvent {
+  static readonly eventName = "shop.order.v1.paid"; // its wire name, as the backend's `name`
+  constructor(readonly order_id: string) {
+    super();
+  }
+}
+
+class ThankCustomer extends Feature<OrderPaid, void> {
+  static readonly serviceName = "ThankCustomer";
+  async execute(event: OrderPaid) { … }
+}
+
+shopBoundedContext.feature(OrderPaid)(ThankCustomer);
+await shopBoundedContext.execute(new OrderPaid("o-1")); // span shop/ThankCustomer, sincpro.event = its name
+```
+
+- **`eventName` is declared**, as `serviceName` is: a minifier renames classes. `event.name`
+  reads it; `name` is reserved, and a subclass cannot make it a field.
+- **One use case per event in a bounded context.** Another context that hears the event
+  registers its own; the queue's `Subscriber` executes it in each.
+- An ApplicationService can take the event too, and compose Features — of Commands or of events
+  — through `featureBus`. `execute(event)` answers whatever its use case returns (`unknown`).
+
+### An `EventSubscriber`: the entrypoint that hears an event
+
+```ts
+// entrypoints/queue/logged-successfully.subscriber.ts — reads the event, executes the Command
+export class LoggedSuccessfully extends EventSubscriber<OdooLoggedIn> {
+  static readonly subscriberName = "LoggedSuccessfully";
+  declare readonly ticketsBoundedContext: BoundedContext<TicketsDependencies>;
+
+  async handle(event: OdooLoggedIn) {
+    await this.ticketsBoundedContext.execute(new CommandStartDay(event.uid)); // an ApplicationService
+  }
+}
+
+// entrypoints/queue/index.ts — who hears what, and what they call
+export const ticketsSubscriptions = new Subscriptions<TicketsEntrypoints>(
+  "tickets-subscriptions",
+);
+ticketsSubscriptions.addDependency("ticketsBoundedContext", ticketsBoundedContext);
+ticketsSubscriptions.subscribe(OdooLoggedIn)(LoggedSuccessfully);
+```
+
+- **Each delivery is a run of its own**, `tickets-subscriptions/LoggedSuccessfully` in the layer
+  `entrypoint`: its span, its log lines, `this.logger`, `this.execution`. It continues the
+  envelope's flow, and the use cases it executes are its children.
+- **A bounded context it was given is bound to it** (`BIND`), as a transport is: what it executes
+  runs under the subscriber's span, in the same flow, caused by it, cancelled with it — and still
+  with its own dependencies, context, interceptors and handlers. A Feature that calls another
+  bounded context injected into it gets the same.
+- **One subscriber per event in a `Subscriptions`**; a second is refused, a replacement names the
+  one it replaces (`subscribe(Event, { replaces: Old })`). Several reactions to one event are one
+  ApplicationService, or subscribers of different registries.
+- **It is not a use case**: interceptors and listeners see the use cases it calls, not it. A
+  failure is reported once along the flow, where it happened, with the outcome its bounded
+  context gave it (`expectErrors` holds).
+- **Its name is its identity** in spans, logs and the stored queue's record of who already
+  heard an event, so it differs from every bounded context's (`<context>-subscriptions`).
+
+### Publishing and subscribing
+
+```ts
+import { Publisher, Subscriber, syncQueue } from "@sincpro/client-framework";
+
+// the queue's door: every bounded context with a use case of the event, every Subscriptions
+const subscriber = new Subscriber(
+  mailBoundedContext,
+  stockBoundedContext,
+  ticketsSubscriptions,
+);
+const queue = syncQueue(subscriber); // in the call, in memory — or a platform's
+shopBoundedContext.addDependency("publisher", new Publisher(queue));
+
+class Pay extends Feature<CommandPay, string> {
+  declare readonly publisher: Publisher;
+  async execute(command: CommandPay) {
+    await this.publisher.publish(new OrderPaid(command.order_id)); // its Envelope
+    return command.order_id;
+  }
+}
+```
+
+The `Publisher` is bound to the run that holds it, so the event joins that run's flow: its
+envelope carries the run's `correlationId` and names the run as its cause. The `Subscriber`
+executes it in `mail`, in `stock` and in `tickets-subscriptions` — `execute(event, envelope)`
+—, so their runs continue the same flow; one that fails does not stop the others. Two of them
+never share a name.
+
+What is defined here, and what each platform plugs behind the ports:
+
+| Piece             | Here                                                           | The platform's                         |
+| ----------------- | -------------------------------------------------------------- | -------------------------------------- |
+| `DomainEvent`     | the class, its `eventName`, its execution                      | —                                      |
+| `EventSubscriber` | the entrypoint, its run, `Subscriptions`                       | —                                      |
+| `Envelope`        | `name`, `id`, `correlationId`, `causationId`, `publishedAt`    | storing it beside the event            |
+| `EventQueue` port | `syncQueue` (in the call); `storedQueue` (store, then deliver) | a broker's queue, `BroadcastChannel`   |
+| `EventStore` port | `memoryEventStore()`                                           | mobile: a SQLite table; web: IndexedDB |
+| `Subscribes` port | `Subscriber(...hearing)`, `eventTypeOf(name)`                  | —                                      |
+
+### Stored events: one way to carry them, any store
+
+```ts
+const queue = storedQueue({
+  store: sqliteEventStore(db), // the platform's EventStore; memoryEventStore() in a tab or a test
+  subscriber: new Subscriber(
+    salesBoundedContext,
+    stockBoundedContext,
+    printingBoundedContext,
+  ),
+  ready: (stored) => connectivity.online || !needsNetwork(stored.envelope.name),
+  onSettled: (stored) => activity.show(stored.envelope.name, stored.state),
+});
+shopBoundedContext.addDependency("publisher", new Publisher(queue));
+connectivity.onBack(() => queue.drain()); // and on coming back to the foreground
+```
+
+`publish` returns once the event is stored. Then the queue delivers what waits, one at a time,
+in the order stored — the backend's store-and-forward, over whatever store the platform plugs:
+
+- It is rebuilt as its class — `static fromJSON` when it has one — and executed by everyone who
+  hears it and does not have it yet: a retry never runs one twice.
+- A failure a retry may fix (`failureOf`: unavailable, no answer, a conflict…) is tried again
+  after the backoff or the wait it asks for, and what follows waits, so the order holds.
+- A failure every attempt would repeat (`PERMANENT_KINDS`: a refusal, invalid, not found) sets
+  it aside — the dead-letter queue — and never holds back what follows.
+- One that is not `ready` (no connection, no session) waits while the rest go on.
+- After `maxAttempts` (10) a failure a retry might still fix is set aside too: a bug of the
+  process (`internal`) never holds the line forever.
+
+The port only keeps records — `add`, `next(skip)`, `save` — so a SQLite table, IndexedDB or
+memory carry events the same way, with the same rules.
+
+Three things a platform keeps in mind:
+
+- **At least once.** A process that stops after a context executed an event and before the store
+  saved it runs it there again. What must not act twice keys what it does by the envelope's id —
+  `this.execution.causationId` in a use case of the event, or in an `EventSubscriber`, which hands
+  it to the Command it executes — or by what the event names (the entity's own id).
+- **One drainer per store.** Two tabs over one IndexedDB claim it first (the Web Locks API).
+- **Values come back as JSON.** An event that carries a `Money`, a `Decimal` or a date declares
+  `static fromJSON` to read them back as such.
+
+The events a remote service publishes arrive as generated types (`DomainEvent` in
+`generated/domain.ts`, a union narrowed by `name`); a local event is a class, like a local
+Command.
+
+## Extending the pipeline
+
+The flow of a run is the core's — context, chain, span, log lines, outcome, report, handlers —,
+and an application changes or hears it from outside, as the backend's `bus_pipeline`:
+
+```ts
+// control: around the service — look, veto (throw), adjust (same class), or answer
+shopBoundedContext.interceptor(CommandPay)(async (command, next, run) => {
+  if (!credit.allows(command.customer_id)) throw new NoCredit();
+  return next(command);
+});
+shopBoundedContext.interceptor()((executable, next, run) => next(executable)); // every class
+
+// observation: never changes the answer
+shopBoundedContext.onStart((started) => activity.running(started.execution.useCase));
+shopBoundedContext.onCompletion(
+  (done) => activity.succeeded(done.execution.useCase),
+  CommandPay,
+);
+shopBoundedContext.onFailure((failed) =>
+  activity.failed(failed.execution?.useCase, failed.outcome),
+);
+
+// composition: a module or plugin wires its pieces in one place
+shopBoundedContext.extend(auditing);
+```
+
+- **Interceptors** run inside the run, outermost first in the order registered: a veto is the
+  use case's failure — observed, answered by the error handlers. What an interceptor passes on
+  keeps its class (the bus routes by class); `run` gives it the use case, the execution and its
+  logger. `withoutInterceptor(fn)` stops one; registered later, it wraps from the next call.
+- **Listeners** hear each run start and each service that answered, filtered by class when
+  named; a failure is heard once, when it escapes the call after every handler, from where it
+  first failed. One that throws is ignored. Each `on…` answers how to stop.
+  `processListeners.onStart / onCompletion / onFailure` hear every bounded context at once — a
+  progress bar, a toast —, after each one's own.
+- **`extend(fn)`** is `fn(context)`, said as composition; `fresh()` copies everything an
+  extension registered.
+
 ## Errors
 
 As the backend's, a bounded context has three chains of error handlers, run
@@ -110,14 +337,14 @@ first-registered-first. A handler returns the answer, or throws to hand the erro
 one's throw reaches the caller:
 
 ```ts
-sales.addFeatureErrorHandler((error) => {
+salesBoundedContext.addFeatureErrorHandler((error) => {
   if (error instanceof PriceNotFound) return new ResponseTotal(0); // the answer
   throw error; // the next handler, or the caller
 });
-sales.addAppServiceErrorHandler(toBusinessError);
-sales.addGlobalErrorHandler(toProblem); // what reaches sales.execute or a scope
+salesBoundedContext.addAppServiceErrorHandler(toBusinessError);
+salesBoundedContext.addGlobalErrorHandler(toProblem); // what reaches salesBoundedContext.execute or a scope
 
-sales.expectErrors(QuoteExpired); // the business answering: `refused`, never reported
+salesBoundedContext.expectErrors(QuoteExpired); // the business answering: `refused`, never reported
 ```
 
 A failure is observed where it happened, before any handler runs: its span closes with its
@@ -126,18 +353,81 @@ the answer, not whether the failure is seen; an answered one adds an `error.hand
 feature handler answers wherever the Feature ran, inside an ApplicationService too; the global
 chain wraps only `execute` and `scoped(...).execute`.
 
-How an error ended a use case:
+### What kind of failure it is
+
+`failureOf(error)` says what any error is, in the backend's words (`FailureKind`, `NextStep`
+from @sincpro/criteria), whatever raised it:
+
+```ts
+const failure = failureOf(error);
+failure.kind; // "conflict", "unavailable", "domain", "unknown_outcome"…
+failure.nextStep; // "refresh_and_retry", "retry_later", "authenticate", "do_not_retry"…
+failure.retryable; // may sending it again succeed
+failure.retryAfter; // seconds to wait first
+failure.permanent; // every attempt fails the same way: set it aside
+failure.fault; // the system's problem: reported
+failure.aborted; // whoever asked stopped waiting
+```
+
+It reads, in order: an `AbortError`; what the error declares (`failureKind`, `reason`,
+`retryAfter` — on itself or as a static of its class, as the backend's errors do); the `Problem`
+the server sent, the same over REST, JSON-RPC and gRPC; a REST status. Not every wire is REST: a
+JSON-RPC or gRPC transport — or another backend's adapter, such as Odoo's — makes errors that
+declare their kind, with the backend's own tables:
+
+```ts
+class RpcError extends Error {
+  constructor(
+    readonly code: number,
+    message: string,
+  ) {
+    super(message);
+  }
+  get failureKind() {
+    return kindOfJsonRpcCode(this.code); // kindOfGrpcCode, kindOfHttpStatus
+  }
+}
+```
+
+How an error ended a use case follows from it (`outcomeOf`):
 
-| Outcome   | When                                                                         | Reported |
-| --------- | ---------------------------------------------------------------------------- | -------- |
-| `ok`      | it answered                                                                  | —        |
-| `refused` | the server answered a 4xx (`TransportError`), or the class is `expectErrors` | no       |
-| `aborted` | whoever asked stopped waiting (`AbortError`)                                 | no       |
-| `failed`  | anything else: a bug, a 5xx, a server nobody reached                         | yes      |
+| Outcome   | When                                                                       | Reported |
+| --------- | -------------------------------------------------------------------------- | -------- |
+| `ok`      | it answered                                                                | —        |
+| `refused` | the caller's answer: a 4xx, a declared kind (`domain`…), or `expectErrors` | no       |
+| `aborted` | whoever asked stopped waiting: an `AbortError`, a cancelled run            | no       |
+| `failed`  | a fault: a bug, a 5xx, a server nobody reached                             | yes      |
 
 `configureProcess({ outcomeOf })` replaces the process-wide rule. `reportError(error, where)`
 reports what fails outside a use case — a view, a worker —, with the same rule.
 
+### Cancelling a run
+
+```ts
+const screen = new AbortController();
+const answer = salesBoundedContext.execute(new CommandQuote(3), { signal: screen.signal });
+screen.abort(); // the run ends `aborted` at once; nothing is reported
+```
+
+Its Features inherit the signal, a service reads it as `this.signal`, and every request its bound
+transport or generated client sends is cancelled with it — with nothing passed by hand.
+
+### A circuit breaker
+
+```ts
+const odoo = new CircuitBreaker("odoo", { failures: 5, openFor: 30_000 });
+const transport = guardedTransport(rpcTransport, odoo); // every call through the circuit
+await odoo.call(() => printer.print(receipt)); // or one call; odoo.wrap(fn) for a function
+```
+
+The backend's `CircuitBreaker`, in this process's memory. After `failures` counted failures in a
+row — the dependency did not answer (`unavailable`, `unknown_outcome`, `exhausted`, `internal`) —
+it opens: calls fail at once with `CircuitOpen`, `unavailable` with the time left as its
+`retryAfter`, so `failureOf`, a stored queue (which waits that long) and a screen already know
+what to do. After `openFor`, one call tries: an answer closes it, a counted failure opens it
+again. A refusal is an answer and never counts. Put it where the dependency is — the transport, an
+adapter —, not in each Feature.
+
 ## Observability
 
 The platform plugs the implementations once, at startup; nothing breaks without them:
@@ -176,21 +466,21 @@ import { logger, loggerAdapter } from "@sincpro/client-framework";
 
 logger.info("Database opened"); // infrastructure — the global logger
 loggerAdapter.warn("Printer is slow", { ms: 900 }); // an adapter
-sales.logger.info("Catalog preloaded"); // a bounded context, outside a use case
+salesBoundedContext.logger.info("Catalog preloaded"); // a bounded context, outside a use case
 this.logger.info("Totalling"); // inside a Feature or ApplicationService
 ```
 
-| Logger                    | Layer                 | Each line carries                              |
-| ------------------------- | --------------------- | ---------------------------------------------- |
-| `logger`                  | `infrastructure`      | —                                              |
-| `loggerAdapter`           | `adapter`             | the run, when injected as a dependency         |
-| `sales.logger`            | `bounded_context`     | its bounded context                            |
-| `this.logger`, Feature    | `feature`             | bounded context, use case, execution and trace |
-| `this.logger`, AppService | `application_service` | the same                                       |
+| Logger                       | Layer                 | Each line carries                              |
+| ---------------------------- | --------------------- | ---------------------------------------------- |
+| `logger`                     | `infrastructure`      | —                                              |
+| `loggerAdapter`              | `adapter`             | the run, when injected as a dependency         |
+| `salesBoundedContext.logger` | `bounded_context`     | its bounded context                            |
+| `this.logger`, Feature       | `feature`             | bounded context, use case, execution and trace |
+| `this.logger`, AppService    | `application_service` | the same                                       |
 
 `this.logger` keeps its run across awaits and concurrent calls, without a global stack. An
 adapter that imports `loggerAdapter` at module level writes without the run; inject it
-(`sales.addDependency("log", loggerAdapter)`) or pass `this.logger` when a line must carry it.
+(`salesBoundedContext.addDependency("log", loggerAdapter)`) or pass `this.logger` when a line must carry it.
 
 One configuration, two doors — `configureProcess({ logger })` replaces every process port,
 `configureLogger(...)` only logging (an in-app debug switch):
@@ -218,8 +508,8 @@ snapshot, and what travels goes to the server in `sincpro-context`.
 
 ```ts
 processContext.set({ tenant_id: "acme" });
-sales.context.set({ warehouse_id: 4 });
-await sales.scoped({ company_id: 2 }).execute(new CommandQuote(1));
+salesBoundedContext.context.set({ warehouse_id: 4 });
+await salesBoundedContext.scoped({ company_id: 2 }).execute(new CommandQuote(1));
 ```
 
 Where the values live is a port (`ContextStore`): synchronous reads, a version per change and an
@@ -229,17 +519,67 @@ its own. `values` is the same object until it changes, so a screen can hand it t
 
 ## Talking to a server
 
-| Piece                          | What it does                                                                          |
-| ------------------------------ | ------------------------------------------------------------------------------------- |
-| `restTransport({ base })`      | REST over `fetch`: `Idempotency-Key`, the server's `Problem`, model versions, Parquet |
-| `memoryTransport(tables)`      | the same contract in memory, copying by the wire's rules — for tests and demos        |
-| `entity(key, routes)`          | a model's routes and Commands, typed — what a generated `entities.ts` declares        |
-| `retryKeys()`                  | one `Idempotency-Key` per gesture, kept while a retry may repeat it                   |
-| `screensTransport(transport)`  | screen reads and writes run as use cases of `screens`: traced and reported            |
-| `parquetDecoder` (`./parquet`) | large pages read as Parquet through the same transport                                |
+A remote service is reached through a port. The generated client never names a wire: it says
+which operation, with what input, and the adapter the application injects decides how it
+travels.
+
+```ts
+import { clientOf } from "./generated/client";
+
+// pick the wire; the client, the Features and the tests stay the same
+const forge = clientOf(restOperations(restTransport({ base: "/v1", headers: session })));
+// or clientOf(jsonRpcOperations({ endpoint: "/rpc", headers: session }))
+// or clientOf(grpcOperations(channel)) — a platform's adapter, the same port
+
+await forge.sendIssue({ issue_id: "acme-3", message: "hola" }); // ResponseSendIssue
+```
+
+| Piece                             | What it does                                                                          |
+| --------------------------------- | ------------------------------------------------------------------------------------- |
+| `OperationTransport` port         | `call(operation, input, options)`: an operation by who it is, over any wire           |
+| `restOperations(transport)`       | over REST: the path from the input's fields, a Query's query, a Command's body        |
+| `jsonRpcOperations({ endpoint })` | over JSON-RPC 2.0: one `POST`, the operation's method, its input as named params      |
+| `restTransport({ base })`         | REST over `fetch`: `Idempotency-Key`, the server's `Problem`, model versions, Parquet |
+| `memoryTransport(tables)`         | the same REST contract in memory, copying by the wire's rules — for tests and demos   |
+| `entity(key, routes)`             | a model's routes and Commands, typed — what a generated `entities.ts` declares        |
+| `retryKeys()`                     | one `Idempotency-Key` per gesture, kept while a retry may repeat it                   |
+| `guardedTransport(t, breaker)`    | every call of a transport through a circuit breaker                                   |
+| `screensTransport(transport)`     | screen reads and writes run as use cases of `screens`: traced and reported            |
+| `parquetDecoder` (`./parquet`)    | large pages read as Parquet through the same transport                                |
+
+Inside a Feature, inject the generated client as it is: the run binds it, so every call carries
+its trace (`traceparent`), its context (`sincpro-context`) and its signal — as headers over HTTP,
+as metadata where a platform's adapter puts them. `screensTransport` and `entity()` stay on the
+REST `Transport`: they are how a screen reads pages of an entity, with its model and its drafts.
+
+### Writing an adapter for another wire
+
+An adapter is one function: read the operation's binding for its wire, send the input, answer the
+answer, and fail with errors `failureOf` reads.
+
+```ts
+function grpcOperations(channel: Channel): OperationTransport {
+  return {
+    async call(operation, input, options) {
+      const method = operation.grpc?.method;
+      if (!method) throw new OperationNotPublished(operation.identity, "gRPC");
+      try {
+        return await channel.unary(method, input, {
+          metadata: options?.headers, // traceparent, sincpro-context
+          signal: options?.signal,
+        });
+      } catch (error) {
+        const code = (error as { code: number }).code;
+        throw Object.assign(error as Error, { failureKind: kindOfGrpcCode(code) });
+      }
+    },
+  };
+}
+```
 
-Inside a Feature, inject the transport or the generated client as they are — the run already
-observes them. `screensTransport` is for what a screen asks directly, outside any Feature.
+Every operation in `operations` carries its identity and each wire's binding (`rest`, `rpc`,
+`grpc`, `mcp`); an operation the adapter's wire does not publish is `OperationNotPublished`
+(`not_found`), never guessed.
 
 ## Generated code
 
@@ -252,14 +592,18 @@ sincpro-client check --root src
 
 `generate` writes, from the contract the backend exports — never edited, written again whole:
 
-| File          | What                                                                                       |
-| ------------- | ------------------------------------------------------------------------------------------ |
-| `domain.ts`   | a type per model, per `<Name>Input`, per operation's input and answer, per domain event    |
-| `client.ts`   | `clientOf(transport)`: a method per operation REST reaches; `operations` and `events` data |
-| `entities.ts` | each entity's list, record, edit, export, Commands and history, for screens                |
+| File          | What                                                                                          |
+| ------------- | --------------------------------------------------------------------------------------------- |
+| `domain.ts`   | a type per model, per `<Name>Input`, per operation's input and answer, per domain event       |
+| `client.ts`   | `clientOf(operations)`: a method per operation, over any wire; `operations` and `events` data |
+| `entities.ts` | each entity's list, record, edit, export, Commands and history, for screens                   |
 
-`scaffold` writes, once, the application's own files: its dependencies, its service bases and
-`registerServices`. `check` enforces the application's layers and bounded-context boundaries.
+Each method takes the operation's input and answers its answer, as `domain.ts` types them — a
+search answers its `Response…` with its records and cursor, as the backend's callers get it, on
+every wire. `scaffold` writes, once, the application's own files: its dependencies (the client
+over the `operations` the application exports — `--operations <module>` —), its service bases
+and `registerServices`. `check` enforces the application's layers and bounded-context
+boundaries.
 
 **Domain events, on demand.** A backend leaves its events out of the contract unless it is
 exported with `--events`. Then each event is a type as it is received — every field present,
@@ -335,13 +679,52 @@ never a `Date`. `valuesOf`/`pack` write; `readValues` reads tagged values back;
 use a reader given explicitly. Cycles, functions and non-finite numbers are refused. How a value
 is shown, typed or stored is the platform's.
 
+## An application's layout
+
+An application is laid out as a sincpro_framework service is — the entrypoints call the bus, the
+bus runs the use cases, the use cases use the adapters:
+
+```text
+src/
+  entrypoints/main.ts(x)               configureProcess, the stored queue and its Subscriber
+  domains/
+    common/infrastructure/operations.ts  export const operations — the wire every client uses
+    <bounded context>/
+      generated/                       sincpro-client generate — never edited
+      domain/                          local Commands, Responses, DomainEvents, value rules
+      adapters/                        repositories, printers, other systems
+      services/                        the use cases, one folder per aggregate or entity
+        <aggregate>/                     sale_order/: its Features and ApplicationServices
+          confirm-quotation.feature.ts
+          <entity of the aggregate>/     payments/: a related entity with use cases of its own
+            register-payment.feature.ts
+            reconcile-payments.app-service.ts
+        index.ts                         registerServices: each Command with its service
+      infrastructure/                  dependencies.ts, bounded_context.ts (service bases)
+      entrypoints/                     the doors: they translate, they decide nothing
+        queue/                           EventSubscribers: event → Command → bus; index.ts: Subscriptions
+        cron/                            the platform's scheduler: tick → Command → bus
+      index.ts                         export const <context>BoundedContext — ready to execute
+```
+
+- **Services by aggregate.** A simple entity is one folder with its Features (a CRUD). When an
+  aggregate holds related entities with use cases of their own — the payments of a sale order —,
+  they get a folder inside it, and its Features and ApplicationServices live there, grouped by
+  what they are about.
+- **Entrypoints translate.** A subscriber, a cron and a screen build a Command and execute it;
+  a workflow of several use cases is an ApplicationService they execute. `sincpro-client check`
+  refuses a service that imports an entrypoint.
+- **A bounded context is named for what it is**: `salesBoundedContext`, never `sales` (an
+  entity?) or `ctx` — `context` is already the run's (`this.context`).
+
 ## Package layout
 
 Each module is laid out as sincpro_framework's are, and says what it offers in its `index.ts`:
 
 ```text
 src/
-  common/          the values of the wire
+  common/          the values of the wire, and what kind of failure an error is
+  circuit_breaker/ CircuitBreaker, CircuitOpen
   context/
     domain/          ContextStore and ContextCodec ports, what travels, Execution
     adapters/        memoryContexts, plainCodec
@@ -353,15 +736,22 @@ src/
     infrastructure/  the ports this process runs with
     services/        logger, loggerAdapter, reportError, outcomeOf
   client/
-    domain/          Transport, TransportError, entity(), the client contract
-    adapters/        rest, memory, parquet (optional entry)
-    services/        discovery, retry keys, propagation of trace and context
+    domain/          OperationTransport, RemoteOperation, Transport, TransportError, entity(),
+                     the client contract
+    adapters/        restOperations, jsonRpcOperations, rest, memory, parquet (optional entry)
+    services/        discovery, retry keys, propagation of trace, context and signal,
+                     guardedTransport
   model/           defineMeta, metaFromSchema, metaStore
   core/
-    domain/          Command, Response, Feature, ApplicationService, FeatureBus, ErrorHandler
-    services/        the execution pipeline, dependency binding, the handler chain
+    domain/          Command, DomainEvent, Response, Feature, ApplicationService, FeatureBus,
+                     ErrorHandler, the pipeline's extension points
+    services/        the execution pipeline, interceptors, dependency binding, the handler chain
     entrypoint/      BoundedContext, screensTransport
-    infrastructure/  configureProcess, configureLogger
+    infrastructure/  configureProcess, configureLogger, processListeners
+  event_driven/
+    domain/          Envelope, the EventQueue, Subscribes and EventStore ports
+    adapters/        syncQueue, storedQueue, memoryEventStore
+    entrypoint/      Publisher, Subscriber (the queue's door), Subscriptions, EventSubscriber
   codegen/         the generator and its CLI — the only place Node is allowed
   testing/         memoryTracer, memoryReporter, memoryLogger
 ```
@@ -397,8 +787,19 @@ The runtime uses `fetch`, `AbortSignal`, `URL`, `crypto.getRandomValues`, `Proxy
 
 Read [`MANIFESTO.md`](MANIFESTO.md) (what this package is and is not), [`AGENTS.md`](AGENTS.md)
 (how to change it), [`CONTRIBUTING.md`](CONTRIBUTING.md),
-[`docs/UBIQUITOUS_LANGUAGE.md`](docs/UBIQUITOUS_LANGUAGE.md) and
-[`docs/MOBILE.md`](docs/MOBILE.md). Versions are written by the release pipeline.
+[`docs/UBIQUITOUS_LANGUAGE.md`](docs/UBIQUITOUS_LANGUAGE.md),
+[`docs/WEB.md`](docs/WEB.md) and [`docs/MOBILE.md`](docs/MOBILE.md). Versions are written by the release pipeline.
+
+## For consumers: the skill
+
+[`.claude/skills/sincpro-client-framework/SKILL.md`](.claude/skills/sincpro-client-framework/SKILL.md)
+is the guide for whoever builds on this package — an application, @sincpro/web-framework,
+@sincpro/mobile — and for the agents that help them: the rule for what goes here, in a platform's
+framework or in an application; the vocabulary; how an application is laid out; how to start the
+process, reach the services over any wire, write a use case, decide what a screen does with a
+failure, publish and subscribe to events, extend the pipeline, write a platform's adapter for each
+port, and test; and the mistakes to avoid. It follows the format of sincpro_framework's skills, so
+the shared knowledge base can carry it beside them.
 
 ## License
 

package/dist/circuit_breaker/domain/circuit.d.ts

@@ -0,0 +1,29 @@
+import type { FailureKind } from "@sincpro/criteria";
+/**
+ * Where a circuit stands — for a health screen or a test; a call never needs it.
+ *
+ * - `closed`: calls go through.
+ * - `open`: calls fail at once (`CircuitOpen`) until its time passes.
+ * - `half_open`: its time passed; one call goes through to try, the others still fail at once.
+ */
+export type CircuitState = "closed" | "open" | "half_open";
+/**
+ * The kinds a circuit counts by default — the backend's `COUNTED`: the dependency did not answer,
+ * may not have, asked to be left alone, or failed in a way nobody declared. Every other kind is
+ * an answer: a refusal is the dependency working.
+ */
+export declare const COUNTED_KINDS: ReadonlySet<FailureKind>;
+/** Whether a failure says the dependency is not answering — not what it answered. */
+export declare function countedByDefault(error: unknown): boolean;
+/**
+ * The dependency a circuit guards failed too often: the call was not made. It declares itself
+ * `unavailable` with its wait, so a retry, a stored queue and a screen already know what to do.
+ */
+export declare class CircuitOpen extends Error {
+    readonly circuit: string;
+    static readonly failureKind = "unavailable";
+    readonly reason = "CIRCUIT_OPEN";
+    /** Seconds to wait before trying again — one at least. */
+    readonly retryAfter: number;
+    constructor(circuit: string, retryAfterSeconds: number);
+}