@sincpro/client-framework 1.0.0 → 1.1.0

package/AGENTS.md

@@ -25,17 +25,18 @@ Each module is laid out as sincpro_framework's are: `domain/` (ports, types and
 (the process's state and technical support) and `entrypoint/` (the doors a caller uses). A
 module has only the layers it needs, and says what it offers in its own `index.ts`.
 
-| Folder               | What                                                                                           |
-| -------------------- | ---------------------------------------------------------------------------------------------- |
-| `src/common/`        | The values of the wire: ids, a day and an instant, `Decimal`, `Money`, `valuesOf` / `rebuilt`  |
-| `src/context/`       | `ContextStore`, codec, `Execution` (domain); memory and plain codec; `Context`; the process's  |
-| `src/observability/` | Tracer/ErrorReporter/Logger ports; console, memory, OpenTelemetry, Sentry; loggers, reporting  |
-| `src/client/`        | `Transport`, `entity()`, the contract (domain); REST, memory, Parquet; discovery, propagation  |
-| `src/model/`         | Model definitions: `defineMeta`, from a JSON Schema, the store of known ones                   |
-| `src/core/`          | DTOs, bus, Feature/ApplicationService, error handlers; pipeline; `BoundedContext`; the process |
-| `src/codegen/`       | The generator and its CLI (`sincpro-client generate`) — the only place Node is allowed         |
-| `src/testing/`       | The public entry of the in-memory observability adapters                                       |
-| `tests/`             | vitest in Node, one folder per module; `tests/support/` holds fakes and forge's contracts      |
+| Folder               | What                                                                                            |
+| -------------------- | ----------------------------------------------------------------------------------------------- |
+| `src/common/`        | The values of the wire: ids, a day and an instant, `Decimal`, `Money`, `valuesOf` / `rebuilt`   |
+| `src/context/`       | `ContextStore`, codec, `Execution` (domain); memory and plain codec; `Context`; the process's   |
+| `src/observability/` | Tracer/ErrorReporter/Logger ports; console, memory, OpenTelemetry, Sentry; loggers, reporting   |
+| `src/client/`        | `Transport`, `entity()`, the contract (domain); REST, memory, Parquet; discovery, propagation   |
+| `src/model/`         | Model definitions: `defineMeta`, from a JSON Schema, the store of known ones                    |
+| `src/core/`          | DTOs and events, bus, services, handlers, extension points; pipeline; `BoundedContext`; process |
+| `src/event_driven/`  | `Envelope`, `EventQueue`/`Subscribes` ports; `syncQueue`; `Publisher`, `Subscriber`             |
+| `src/codegen/`       | The generator and its CLI (`sincpro-client generate`) — the only place Node is allowed          |
+| `src/testing/`       | The public entry of the in-memory observability adapters                                        |
+| `tests/`             | vitest in Node, one folder per module; `tests/support/` holds fakes and forge's contracts       |
 
 ## Hard rules (the build enforces them — `make doctor`)
 
@@ -70,7 +71,41 @@ module has only the layers it needs, and says what it offers in its own `index.t
   instance, shared by the next call, the call beside it and every `scoped` variant — as in
   sincpro_framework. What belongs to one request goes in its arguments or its context.
 - **A span uses stable service metadata, not constructor.name.** `serviceName = "Cancel"` gives
-  `project/Cancel`, identity `project.Cancel`. Commands route by exact constructor identity.
+  `project/Cancel`, identity `project.Cancel`. Commands and events route by exact constructor
+  identity. An event declares `static eventName` (its wire name) for the same reason; `name` is
+  reserved for it.
+- **A replacement names what it replaces.** `feature(dto, { replaces: Service })` is refused
+  unless `Service` is registered now for `dto`; its spans carry `sincpro.replaces`. A service
+  meant to be subclassed declares `static readonly serviceName: string = "…"`, or the literal
+  type stops a subclass from renaming itself.
+- **How events are carried is here; where they are kept is the platform's.** One subscriber
+  per bounded context; a `Subscriber` executes an event in each. `storedQueue` holds the rules —
+  store first, deliver in order, retry what may succeed, set aside what never will, never run a
+  context twice — over an `EventStore` the platform plugs (SQLite, IndexedDB, memory). A store
+  only keeps records; it never decides.
+- **A circuit belongs where the dependency is.** `CircuitBreaker` (in the process's memory, the
+  backend's semantics: `COUNTED_KINDS`, half-open with one probe) guards a transport
+  (`guardedTransport`) or an adapter; its `CircuitOpen` declares `unavailable` and a wait, so
+  nothing else needs to know a circuit exists.
+- **Delivery is at least once.** A stored event may run twice in a context after a crash; a
+  subscriber keys its effect by `this.execution.causationId` (the envelope's id). `maxAttempts`
+  sets aside what keeps failing. One process drains a store. `execution` is reserved.
+- **A failure says its kind, whatever the wire.** `failureOf` reads a declared `failureKind`, the
+  `Problem` (the same over REST, JSON-RPC and gRPC), then a REST status. A transport of another
+  wire, or another backend's adapter, declares the kind with `kindOfGrpcCode` /
+  `kindOfJsonRpcCode` / `kindOfHttpStatus` — never a table of its own. Retrying, setting aside,
+  reporting and the outcome all follow from it.
+- **A run can be cancelled.** `execute(…, { signal })`: it ends `aborted` at once, its Features
+  inherit the signal, `this.signal` reads it, and a bound transport sends it with every request.
+  `signal` is reserved, like `context` and `logger`.
+- **No variable named `process`.** `make doctor` reads `process.` as Node outside `codegen/`.
+- **A run belongs to a flow.** `correlationId` is shared by every run and event of one flow;
+  `causationId` names what directly caused it. A dependency carrying `BIND` (the `Publisher`)
+  is bound to the run, so what it publishes joins that flow with nothing passed by hand.
+- **The pipeline is closed for modification, open for extension.** Change the flow in
+  `executeService` only for every run; what one application needs goes through an interceptor
+  (control, inside the run, keeps the class), a listener (observation, never changes the
+  answer, its failure ignored) or `extend`.
 - **Dependency declarations do not register anything.** Service bases declare typed attributes
   from a shared dependency interface. Only `addDependency` supplies runtime values; a missing
   dependency fails explicitly.
@@ -87,6 +122,12 @@ module has only the layers it needs, and says what it offers in its own `index.t
 - **A store's `load` may answer a new object each time** (one that parses JSON does): `Context`
   keeps one object per `version`, so a screen can hand `values` to `useSyncExternalStore`. A store
   that changes without moving the version is a broken store.
+- **The generated client never names a wire.** A method is `transport.call(operations.X, input,
+options)`: no route, no verb, no RPC method. The contract's bindings (`rest`, `rpc`, `grpc`,
+  `mcp`) are data in `operations`; an `OperationTransport` adapter reads the one of its wire
+  (`restOperations`, `jsonRpcOperations`, a platform's gRPC) and throws `OperationNotPublished`
+  for the rest. A run binds an `OperationTransport` as it binds a `Transport`: headers and signal.
+  The REST `Transport` stays for `restOperations` and for screens (`entity()`, pages, drafts).
 - **What is generated is types, never classes.** A generated DTO is the remote contract: a
   class extending `Command` could be registered on the local bus, which is what keeps a remote
   operation and a local use case apart. Runtime knowledge goes in data (`operations`, `events`);

package/MANIFESTO.md

@@ -28,8 +28,11 @@ server-side render, in a script and in a test, unchanged.**
 1. **Services.** A `Feature` executes a registered Command through `execute(dto)`;
    an `ApplicationService` composes its context's Features through `featureBus`, never another
    ApplicationService. Dependencies are typed attributes supplied by the bounded context.
-2. **Execution.** Every command enters one internal execution pipeline. Context, tracing,
-   outcomes and error reporting are supplied there, not handwritten by each service.
+2. **Execution.** Every Command and event enters one execution pipeline, defined here: context,
+   chain, span, log lines, outcome, report, error handlers — not handwritten by each service. An
+   application changes it from outside through its extension points, as the backend's
+   `bus_pipeline`: interceptors control a run (look, veto, adjust, answer); listeners hear it
+   start, answer or fail, and never change it; an extension wires a component in one place.
 3. **Observability, as ports.** `Tracer`, `ErrorReporter` and `Logger` are the contracts: one span per use
    case, named `<bounded context>/<serviceName>`; the unexpected reported
    with its trace id; what the server already explained (a validation, a conflict), or what a
@@ -47,7 +50,9 @@ server-side render, in a script and in a test, unchanged.**
    Features and ApplicationServices, registered for class DTOs — and called as
    `project.execute(new Command(...))`. The bounded context is the bus. An application is the set
    of bounded contexts it loads; they never import each other's insides.
-6. **The client.** The `Transport` port and its implementations (REST, memory), `entity()` with
+6. **The client.** The `OperationTransport` port — an operation called by who it is, over any
+   wire — with its REST and JSON-RPC adapters (a platform adds gRPC or its own); the `Transport`
+   port and its implementations (REST, memory), `entity()` with
    typed commands and answers, the service's client contract, model definitions read once from
    the server and the server's `Problem`.
 7. **The values of the wire.** How every value travels, as the backend writes it — a decimal as
@@ -62,9 +67,18 @@ server-side render, in a script and in a test, unchanged.**
 10. **The command core (`./core`).** The single model matching the backend's application
     abstractions: class DTOs and Responses, a bounded context that is a bus, Features and
     ApplicationServices registered for DTO classes, attribute-injected dependencies and a
-    feature bus for composition, and the backend's error handlers — global, feature and
-    application service — with the errors a bounded context expects. The internal engine uses
+    feature bus for composition, domain events executed by their subscribers, replacements,
+    and the backend's error handlers — global, feature and application service — with the
+    errors a bounded context expects. The internal engine uses
     the injected process ports. Remote clients and mapping remain distinct.
+11. **Event-driven, as ports (`event_driven`).** How every platform publishes domain events and
+    subscribes to them the same way: the envelope that travels beside an event (its flow and
+    its cause), the `EventQueue` and `Subscribes` ports, a `Publisher` a Feature holds, a
+    `Subscriber` over the bounded contexts that hear, the queue that delivers in the call, and
+    the stored queue's rules over an `EventStore` the platform plugs. The guidelines, the rules
+    and the contracts are here; where events are kept is the platform's.
+12. **Resilience.** What a failure is (`failureOf`, the backend's kinds on every wire) and the
+    backend's circuit breaker, guarding any transport or adapter.
 
 ## What it is not
 
@@ -84,8 +98,10 @@ server-side render, in a script and in a test, unchanged.**
 - **Not where application-specific business rules live.** The package supplies execution
   abstractions; a registered use case may delegate to a server or use a local domain. A remote
   adapter does not authorize reimplementing the server's rules.
-- **Not an event delivery system.** The command dispatcher in `./core` executes use cases.
-  An event contract does not supply a publisher, queue, outbox, broker or synchronization engine.
+- **Not a durable event delivery system.** It defines how events are published, carried and
+  executed — the ports, the envelope, the in-call queue — so web and mobile do it alike; storing
+  them, retrying, a dead-letter queue, waiting for a connection, other tabs, a broker are the
+  platform's adapters behind `EventQueue`.
 
 ## What we believe
 
@@ -130,6 +146,14 @@ server-side render, in a script and in a test, unchanged.**
 
 Dependencies point down only. This package knows nothing above it.
 
+**What goes where.** client-framework + web-framework is to a web application what
+sincpro_framework is to a backend; client-framework + @sincpro/mobile, the same for a phone. A
+piece web and mobile can both use, and that needs no platform, comes here — as a port, its rules
+and a memory adapter. A piece only one platform needs, or that needs a platform's technology, is
+that platform's — an adapter of a port. An application's business is the application's. Nothing
+is replicated: what differs by nature (a phone's SQLite domain, a browser's entity screens) stays
+different, and the platforms meet here only through the ports.
+
 ## Where it stands
 
 **The application layer is the backend's.** A bounded context executes class Commands through
@@ -145,16 +169,35 @@ bounded context has its own, and a run hands `this.logger`, bound to its executi
 infrastructure and the adapters have a predefined one.
 
 **The client and the generator read the backend's contract.** Types per model, operation and —
-when the contract is exported with them — domain event; a client per wire REST reaches; the
-entities screens use. What is generated is types, never classes: the remote contract describes
-the wire and never reaches the local bus.
+when the contract is exported with them — domain event; a client whose methods call each
+operation by who it is, over the `OperationTransport` the application injects — REST, JSON-RPC,
+a platform's gRPC —; the entities screens use. What is generated is types, never classes, and
+never names a wire: the contract's bindings are data, read by the adapter of each wire.
 
 **Each module is laid out as the backend's.** `domain/`, `adapters/`, `services/`,
 `infrastructure/`, `entrypoint/`, only those a module needs; `domain/` depends only on `domain/`.
 
-**Next:** web and mobile adopt it in their own releases; generated readers that validate and
-convert what arrives, when a use needs them; durable delivery, designed apart from
-instrumentation.
+**The pipeline is the core's, and open.** The flow of a run is defined once; interceptors,
+listeners and extensions change or hear it from outside, without touching a service.
+
+**Events travel the same way on every platform.** A Feature publishes through a `Publisher`;
+a `Subscriber` executes the event in every bounded context that hears it, in the same flow
+(`correlationId`, caused by the run that published it). In the call (`syncQueue`), or stored
+first and delivered by the backend's store-and-forward rules (`storedQueue`) over the
+`EventStore` each platform plugs — a SQLite table, IndexedDB, memory.
+
+**A failure means the same thing everywhere.** `failureOf` reads any error — whatever the wire,
+whatever backend — in the backend's kinds and next steps; retrying, setting aside, reporting and
+a screen's answer follow from it. A run can be cancelled, and its requests with it. The
+backend's circuit breaker guards any transport.
+
+**Consumers have a guide.** The `sincpro-client-framework` skill says, for an application and for
+a platform's framework, what goes where and how each thing is done.
+
+**Next:** web and mobile adopt it in their own releases — mobile's SQLite `EventStore` and gRPC or
+JSON-RPC wire, web's in-memory or IndexedDB store and its hooks —, declaring this package as a
+peer dependency; events from the server live, with the backend's server-sent events; generated
+readers that validate and convert what arrives, when a use needs them.
 
 ## How we decide
 

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)
@@ -103,6 +105,164 @@ without a decorator transform, call them: `sales.feature(CommandTotal)(Total)`.
 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) { … }
+}
+printing.feature(CommandPrint, { replaces: Print })(PrintOnBixolon);
+printing.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 executed as a Command is: by the Feature or
+ApplicationService registered for its class, its subscriber 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) { … }
+}
+
+shop.feature(OrderPaid)(ThankCustomer);
+await shop.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 subscriber per bounded context.** Another context that hears the event registers its
+  own; a `Subscriber` executes it in each.
+- An ApplicationService can subscribe too, and compose Features — of Commands or of events —
+  through `featureBus`. `execute(event)` answers whatever the subscriber returns (`unknown`).
+
+### Publishing and subscribing
+
+```ts
+import { Publisher, Subscriber, syncQueue } from "@sincpro/client-framework";
+
+const subscriber = new Subscriber(mail, stock); // every bounded context that hears
+const queue = syncQueue(subscriber); // in the call, in memory — or a platform's
+shop.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` and in `stock` — `context.execute(event, envelope)` —, so their runs
+continue the same flow; one that fails does not stop the others.
+
+What is defined here, and what each platform plugs behind the ports:
+
+| Piece                     | Here                                                           | The platform's                         |
+| ------------------------- | -------------------------------------------------------------- | -------------------------------------- |
+| `DomainEvent`, subscriber | the class, its `eventName`, its execution                      | —                                      |
+| `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(...contexts)`, `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(sales, stock, printing),
+  ready: (stored) => connectivity.online || !needsNetwork(stored.envelope.name),
+  onSettled: (stored) => activity.show(stored.envelope.name, stored.state),
+});
+shop.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 in every
+  bounded context that 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. A subscriber that must not act twice keys what it does by the
+  envelope's id, `this.execution.causationId` in its run.
+- **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
+shop.interceptor(CommandPay)(async (command, next, run) => {
+  if (!credit.allows(command.customer_id)) throw new NoCredit();
+  return next(command);
+});
+shop.interceptor()((executable, next, run) => next(executable)); // every class
+
+// observation: never changes the answer
+shop.onStart((started) => activity.running(started.execution.useCase));
+shop.onCompletion((done) => activity.succeeded(done.execution.useCase), CommandPay);
+shop.onFailure((failed) => activity.failed(failed.execution?.useCase, failed.outcome));
+
+// composition: a module or plugin wires its pieces in one place
+shop.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
@@ -126,18 +286,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 = sales.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:
@@ -229,17 +452,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 +525,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,
@@ -341,7 +618,8 @@ Each module is laid out as sincpro_framework's are, and says what it offers in i
 
 ```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 +631,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
   codegen/         the generator and its CLI — the only place Node is allowed
   testing/         memoryTracer, memoryReporter, memoryLogger
 ```
@@ -397,8 +682,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