@sincpro/client-framework 0.6.0 → 1.1.0

package/README.md

@@ -1,425 +1,700 @@
 # @sincpro/client-framework
 
-**The client side of [sincpro_framework](https://github.com/Sincpro-SRL/sincpro_framework), for
-every platform.** Write a use case once — a `Feature`, or an `ApplicationService` that composes
-Features — and run it in a browser, on a phone, in a server-side render, in a script or in a test.
-Every use case is traced and every unexpected error reported, continuing the backend's trace,
-without its author writing either. A service's client contract becomes typed code for each of
-its bounded contexts.
-
-> **Status: 0.x.** The API may still change before 1.0. In: the client, the generator, the
-> bounded context with its `Feature` and `ApplicationService`, the process (tracing, error
-> reporting, the context) and its ports. Read the [manifesto](MANIFESTO.md) for what this package
-> is responsible for, what it is not and where it is going, and the
-> [ubiquitous language](docs/UBIQUITOUS_LANGUAGE.md) every Sincpro framework shares.
-
-## What it gives, at a glance
-
-```mermaid
-classDiagram
-  direction LR
-  class UseBoundedContext {
-    +name
-    +context : Context
-    +addDependency(name, value)
-    +register(features, applicationServices) BoundedContext
-  }
-  class BoundedContext {
-    +Issues : the methods of Issues
-    +CloseAndNotify : the methods of CloseAndNotify
-    +context : Context
-    +with(dependencies) BoundedContext
-    +scoped(context) BoundedContext
-  }
-  class Feature {
-    #client, session : each dependency
-    #context : what this run executes with
-  }
-  class ApplicationService {
-    #feature : Issues, Notices
-  }
-  class Context {
-    +values
-    +get(name)
-    +set(values)
-    +clear(names)
-    +watch(listener)
-  }
-  class ContextStore {
-    <<port>>
-    +load(key)
-    +save(key, values)
-    +delete(key)
-    +version(key)
-    +watch(key, listener)
-  }
-  class Tracer {
-    <<port>>
-    +start(name, parent, attributes) Span
+The client side of [sincpro_framework](https://github.com/Sincpro-SRL/sincpro_framework), for
+the web, React Native, scripts and tests: the same application layer as the backend —
+Commands, Features, ApplicationServices and a bounded context that is their bus —, observed
+the same way, and a typed client generated from a service's contract. No React, no DOM, no
+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)
+- [Talking to a server](#talking-to-a-server)
+- [Generated code](#generated-code)
+- [Values on the wire](#values-on-the-wire)
+- [Package layout](#package-layout)
+- [Development](#development)
+
+## A bounded context
+
+```ts
+import {
+  ApplicationService,
+  BoundedContext,
+  Command,
+  Feature,
+  Response,
+} from "@sincpro/client-framework";
+
+class ResponseTotal extends Response {
+  constructor(readonly total: number) {
+    super();
   }
-  class ErrorReporter {
-    <<port>>
-    +report(error, about)
+}
+
+class CommandTotal extends Command<ResponseTotal> {
+  constructor(readonly quantity: number) {
+    super();
   }
-  class Transport {
-    <<port>>
-    +list(route, criteria)
-    +one(route)
-    +send(method, route, body)
+}
+
+class CommandQuote extends Command<ResponseTotal> {
+  constructor(readonly quantity: number) {
+    super();
   }
-  UseBoundedContext --> BoundedContext : register
-  BoundedContext o-- Feature : each by its name
-  Feature <|-- ApplicationService
-  BoundedContext --> Context : its level
-  Context --> ContextStore : kept in
-  BoundedContext ..> Tracer : a span per use case
-  BoundedContext ..> ErrorReporter : what nobody expected
-  Feature ..> Transport : through its generated client
-```
+}
 
-`configureProcess({ tracer, reporter, context })` plugs the ports once; `processContext` is the
-process's level of the context. Beside them: the generated client (`sincpro-client generate`),
-`entity()`, model definitions (`defineMeta`, `metaFromSchema`) and client-side ids.
-
-## A bounded context, set up like the backend's
-
-Each bounded context of an application has the layout sincpro_framework gives a service: what its
-services can count on, its bases, its services, and the one object the rest of the application
-uses it through.
-
-```mermaid
-flowchart LR
-  subgraph py["sincpro_framework · Python"]
-    direction TB
-    pd["infrastructure/dependencies.py<br/>DependencyContextType · add_dependency"]
-    pf["infrastructure/framework.py<br/>Feature · ApplicationService · UseFramework"]
-    ps["services/<br/>@bus.feature · @bus.app_service"]
-    pi["__init__.py<br/>the bounded context"]
-    pd --> pf --> ps --> pi
-  end
-  subgraph ts["@sincpro/client-framework · TypeScript"]
-    direction TB
-    td["infrastructure/dependencies.ts<br/>ProjectDependencies · addDependency"]
-    tf["infrastructure/bounded_context.ts<br/>Feature · ApplicationService · UseBoundedContext"]
-    tsv["services/<br/>features · applicationServices"]
-    ti["index.ts<br/>export const project"]
-    td --> tf --> tsv --> ti
-  end
-  ti --> users["a screen · another bounded context · a test<br/>project.Issues.close(input)"]
-  pi -. "the client contract" .-> td
-```
+class Total extends Feature<CommandTotal, ResponseTotal> {
+  static readonly serviceName = "Total";
+  declare readonly unitPrice: number; // a dependency, typed
 
-```ts
-// domains/project/infrastructure/dependencies.ts — what the services can count on
-export interface ProjectDependencies {
-  client: ProjectClient; // generated from the service's contract
-  session: Session;
+  execute(command: CommandTotal): ResponseTotal {
+    this.logger.info("Totalling", { quantity: command.quantity });
+    return new ResponseTotal(command.quantity * this.unitPrice);
+  }
 }
 
-export function registerDependencies(bc: UseBoundedContext<ProjectDependencies>) {
-  bc.addDependency("client", clientOf(transport));
-  bc.addDependency("session", session);
-  return bc;
+class Quote extends ApplicationService<CommandQuote, ResponseTotal> {
+  static readonly serviceName = "Quote";
+
+  execute(command: CommandQuote): Promise<ResponseTotal> {
+    return this.featureBus.execute(new CommandTotal(command.quantity));
+  }
 }
+
+const sales = new BoundedContext<{ unitPrice: number }>("sales");
+sales.addDependency("unitPrice", 10);
+sales.feature(CommandTotal)(Total);
+sales.appService(CommandQuote)(Quote);
+
+const answer = await sales.execute(new CommandQuote(3)); // ResponseTotal — total 30
 ```
 
+A Command names, by its type, the Response it answers: `execute` infers it, with no second
+argument (the backend's `bus(dto, ResponseType)` is accepted too, and checked in TypeScript
+only). A Response may be a class, a plain object, a page, a primitive or `void`.
+
+- **One Command, one service.** A Command class is registered once, across both layers, and
+  dispatched by its exact constructor. `serviceName` names the service in spans and logs —
+  stable, where a minifier renames classes.
+- **Dependencies are attributes.** `addDependency` supplies them; a service declares their types
+  (`declare readonly client: …`), usually once on a base class per bounded context, as
+  `sincpro-client scaffold` writes it. Declaring registers nothing; reading a missing one fails.
+  A replacement names what it replaces: `addDependency(name, next, { replaces: previous })`.
+- **A service is a singleton of its generation.** What belongs to one request goes in the
+  Command or the context, never on `this`. Use TypeScript `private`, not `#private`: a run sees
+  the instance through a view of its own.
+- **Generations.** The first call (or `buildRootBus()`) builds one; what is registered later
+  answers from the next call, and a running call keeps its own. `fresh()` copies the
+  registrations; `scoped({ company_id: 2 })` runs with more context and the same instances.
+- **Composition.** An ApplicationService runs its context's Features through `this.featureBus`,
+  as children of its own execution; never another ApplicationService.
+
+### Decorators, when the project has them
+
 ```ts
-// domains/project/infrastructure/bounded_context.ts
-import {
-  ApplicationService as BaseApplicationService,
-  Feature as BaseFeature,
-  UseBoundedContext,
-} from "@sincpro/client-framework";
+@sales.feature(CommandTotal)
+class Total extends Feature<CommandTotal, ResponseTotal> { … }
+```
 
-import type { ProjectFeatures } from "../services";
+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
+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.
 
-export class Feature extends BaseFeature<ProjectDependencies> {}
-export class ApplicationService extends BaseApplicationService<
-  ProjectDependencies,
-  ProjectFeatures
-> {}
+### Replacing a service
 
-export function configProjectBoundedContext(name: string) {
-  return registerDependencies(new UseBoundedContext<ProjectDependencies>(name));
+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
-// domains/project/services/issues.ts — a Feature is a facade: one part of the domain
-export class Issues extends Feature {
-  close(input: dto.CommandCloseIssue) {
-    this.session.require(); // each dependency is a typed property
-    return this.client.closeIssue(input); // carries this run's traceparent
+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();
   }
 }
 
-// domains/project/services/close_and_notify.ts — composes the Features of its bounded context
-export class CloseAndNotify extends ApplicationService {
-  async execute(input: dto.CommandCloseIssue) {
-    await this.feature.Issues.close(input); // a child span, the same trace
-    return this.feature.Notices.tell(input);
+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
 
-// domains/project/services/index.ts
-export const features = { Issues, Notices };
-export const applicationServices = { CloseAndNotify };
-export type ProjectFeatures = typeof features;
+```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
-// domains/project/index.ts
-export const project = configProjectBoundedContext("project").register({
-  features,
-  applicationServices,
+// 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
 
-// anywhere: a screen, a script, a test
-await project.Issues.close(input); // span project/Issues.close
-await project.CloseAndNotify.execute(input); // project/CloseAndNotify → its Features under it
+// 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);
 ```
 
-The generator writes this skeleton for you, once, from the service's contract — and never touches
-a file that is already there, because from then on it is yours:
+- **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.
 
-```bash
-sincpro-client generate project.contract.json --out src/domains/project/generated --domain project
-sincpro-client scaffold project.contract.json --out src/domains/project   # dependencies, bases, services, index
+## Errors
+
+As the backend's, a bounded context has three chains of error handlers, run
+first-registered-first. A handler returns the answer, or throws to hand the error on; the last
+one's throw reaches the caller:
+
+```ts
+sales.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
+
+sales.expectErrors(QuoteExpired); // the business answering: `refused`, never reported
 ```
 
-And the layers stay layers: `sincpro-client check` resolves every import of the application with
-its own TypeScript and `tsconfig` (aliases included) and fails when a bounded context reaches into
-another's insides, a service imports React or web-ui, `common` imports a bounded context, or the
-entrypoints skip a bounded context's `index.ts` — put it in `make doctor`:
+A failure is observed where it happened, before any handler runs: its span closes with its
+outcome, its log line is written and, when unexpected, it is reported once. A handler decides
+the answer, not whether the failure is seen; an answered one adds an `error.handled` line. A
+feature handler answers wherever the Feature ran, inside an ApplicationService too; the global
+chain wraps only `execute` and `scoped(...).execute`.
 
-```bash
-sincpro-client check --root src
+### 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
 ```
 
-Every public method is a use case: a span named as the backend names its own
-(`project/Issues.close`, identity `project.Issues.close`), and a report when it fails in a way
-nobody expected. One gesture is one trace, from the click to the database:
-
-```mermaid
-sequenceDiagram
-  participant caller as Caller<br/>(a screen, a test)
-  participant app as project.CloseAndNotify<br/>(ApplicationService)
-  participant feature as this.feature.Issues<br/>(Feature)
-  participant client as this.client<br/>(generated, bound to the run)
-  participant process as Process<br/>(Tracer · ErrorReporter)
-  participant server as sincpro_framework
-
-  caller->>app: execute(input)
-  app->>process: span project/CloseAndNotify — the context read once
-  app->>feature: close(input)
-  feature->>process: child span project/Issues.close
-  feature->>client: closeIssue(input)
-  client->>server: POST /issues/{issue_id}/close · traceparent · sincpro-context
-  server-->>client: ResponseCloseIssue — or a Problem
-  client-->>caller: the answer, through each run
-  Note over process: each run ends ok · refused (shown, never reported) · aborted · failed (reported once, with its trace id)
+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
+  }
+}
 ```
 
-`project` holds references only — each service is made once, the first time it is
-asked for — and it is never frozen: `project.with({ client: fake })` and
-`project.scoped({ company_id: 2 })` derive a variant that shares everything else.
+How an error ended a use case follows from it (`outcomeOf`):
 
-## The process: tracing, errors and the context
+| 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      |
 
-What every bounded context runs with is set once, where the application starts — the way the
-backend's process is. All of it is optional:
+`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.
 
-```ts
-// entrypoints/main.ts
-configureProcess({
-  tracer, // the platform's Tracer
-  reporter, // the platform's ErrorReporter
-  context: memoryContexts(), // where the context lives (this is the default)
-});
+### Cancelling a run
 
-processContext.set({ tenant_id: "acme" }); // every use case runs with it and sends it
-project.context.set({ warehouse_id: 4 }); // only what «project» runs
+```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
 ```
 
-What a screen reads and writes is a use case too when it goes through `screensTransport(transport)`:
-each request is `screens/EntityReads.list`, `…/EntityWrites.send` — traced, with the context on
-it, and reported when it failed.
-
-A service reads it as `this.context` — the process's values, under them its bounded context's,
-under them a scope's, read once where the gesture started — and every request it sends carries
-it in `sincpro-context`. A screen hears it change with `processContext.watch(…)`.
-
-```mermaid
-flowchart LR
-  p["processContext<br/>tenant_id · company_id"]
-  b["project.context<br/>warehouse_id"]
-  s["project.scoped({ company_id: 2 })<br/>one window"]
-  e["this.context<br/>read once where the gesture starts"]
-  c["this.context of each Feature it runs<br/>the same values"]
-  h["sincpro-context<br/>on every request"]
-  store[("ContextStore<br/>the platform's")]
-  p --> e
-  b --> e
-  s --> e
-  e --> c
-  e --> h
-  c --> h
-  p -.-> store
-  b -.-> store
+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 context lives in a `ContextStore`, the port each platform implements with its own technology:
-memory by default, `sessionStorage` or the screens' own store in a browser, MMKV on a phone,
-`AsyncLocalStorage` in a server that renders. The services never know which.
+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
 
-`tracer` and `reporter` are injected by the application — this package initialises nothing.
-Any object that fulfils the port works; for the common vendors there are optional adapters that
-wrap what the application built:
+The platform plugs the implementations once, at startup; nothing breaks without them:
 
 ```ts
-import { openTelemetryTracer } from "@sincpro/client-framework/opentelemetry"; // peer: @opentelemetry/api
-import { sentryReporter } from "@sincpro/client-framework/sentry"; // no dependency
+import { configureProcess, memoryContexts } from "@sincpro/client-framework";
+import { openTelemetryTracer } from "@sincpro/client-framework/opentelemetry";
+import { sentryReporter } from "@sincpro/client-framework/sentry";
 
-const tracer = openTelemetryTracer(provider.getTracer("my-app")); // the app's provider and exporter
-const reporter = sentryReporter(client); // the app's Sentry-compatible client (GlitchTip too)
+configureProcess({
+  tracer: openTelemetryTracer(provider.getTracer("forge-web")), // the app's provider
+  reporter: sentryReporter(client), // the app's Sentry or GlitchTip client
+  logger: { mode: production ? "production" : "development" },
+  context: memoryContexts(),
+});
 ```
 
-What fails outside a use case — a screen that broke while drawing, a subscriber, a worker — goes to
-the same reporter with `reportError(error, where)`: once (an error a use case already reported is
-not sent again), with the process's context.
+Every execution opens a span `<bounded context>/<serviceName>`; an ApplicationService's Features
+are its children, on the same trace. A dependency that is a `Transport` or a generated client is
+bound to the run, so each request carries `traceparent` (and `tracestate`) and
+`sincpro-context` — the backend continues the trace. A tracer, reporter or logger that fails is
+ignored: telling about a use case never changes its answer.
 
-Nothing is installed or shipped unless it is imported, and without a tracer or a reporter every use
-case runs the same — nothing traces, nothing reports. In a test, `memoryTracer()` and
-`memoryReporter()` (`@sincpro/client-framework/testing`).
+The vendor entries wrap what the application built — they initialize nothing, read no
+environment and register nothing global. There is no context manager: the trace reaches the
+wire through the transport. On the web, leave the backend's origin out of OpenTelemetry's
+automatic `fetch` instrumentation (`ignoreUrls`), or it writes a `traceparent` of a trace of its
+own over this one.
 
-## Values on the wire
+### Logging
 
-The backend writes every message with one set of rules, and every client reads and writes them
-the same — so they live here, not in each platform:
-
-| Value        | Travels as                                 | Here                                               |
-| ------------ | ------------------------------------------ | -------------------------------------------------- |
-| a decimal    | text, every digit: `"10.50"`               | `Decimal` — exact, on `BigInt`; rounds half up     |
-| a money      | `{ "amount": "10.50", "currency": "BOB" }` | `Money` — never adds two currencies                |
-| a day        | `"2026-10-02"`, never converted            | `isDay`, `dayOf(instant, zone)` for «today»        |
-| an instant   | ISO text: `"2026-10-02T14:30:00Z"`         | `wallTimeOf` / `instantOf` on the company's zone   |
-| an id        | a UUID v7 as 32 hex                        | `newEntityId`, `isEntityId`, `momentOf`            |
-| bytes        | `{ "$bytes": "<base64>" }`                 | `valuesOf` / `readValues`                          |
-| the context  | only what travels: text, numbers, lists    | `plainCodec`, `travelling`                         |
-| a to-many    | `{ "items": […], "count": {…}, "cursor" }` | `EntityCollection<T>`, `collectionOf`, `isPartial` |
-| an export    | Parquet, Arrow or JSON Lines, streamed     | `downloadRoute`, `exportRoute`, `Download`         |
-| a large page | Parquet, when the search says so           | `restTransport({ decoders: [parquetDecoder] })`    |
+The application layer imports no logger. Two are predefined, for the code around the use cases:
 
 ```ts
-import { Money, pack, unpack, valuesOf } from "@sincpro/client-framework";
+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
+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                                       |
+
+`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.
+
+One configuration, two doors — `configureProcess({ logger })` replaces every process port,
+`configureLogger(...)` only logging (an in-app debug switch):
+
+```ts
+configureLogger({ mode: "development", level: "info", layers: { adapter: false } }); // the console
+configureLogger({ mode: "production" }); // the console, silent
+configureLogger({ engine: combineLoggers(consoleLogger({ mode }), lokiLogger) }); // other sinks
+configureLogger({ engine: false }); // no logs
+```
 
-const line = new Money("19.90", "BOB").times("3"); // 59.70 BOB, exact
-const total = Money.total([line, delivery], "BOB").rounded(); // to the currency's decimals
-valuesOf({ total, at: new Date() }); // { total: { amount, currency }, at: "…Z" }
-const answer = unpack(text, Money); // a typed read when asked for — never imposed
+The console is the default engine. In production it is silent; in development it prints
+everything, and `level` and `layers` hide only INFO/DEBUG. A supplied `engine` owns its own
+policy, and each sink of `combineLoggers` keeps its own — the console's silence never silences
+another. Every execution writes `execution.started` (DEBUG) and `execution.finished` with its
+outcome and duration (INFO, WARN when refused, ERROR when failed). No line carries a DTO, a
+result, an error body or the session's context unless the author writes it. Delivery, buffering
+and credentials (Loki, a phone's queue) are the platform's.
+
+## Context
+
+The values every use case runs with — the tenant, the company —, in levels: the process's, the
+bounded context's, a scope's. A root execution reads them once; its Features inherit that
+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));
 ```
 
-Not restrictive, like the backend: reading keeps every key it finds, a typed read is asked for
-(`rebuilt(values, Money)`), any currency code is read, and an application adds its own decimals
-(`Money.decimals["USDT"] = 6`). What JSON cannot write (`NaN`, a function, a cycle) is refused at
-once, naming where. Showing a value to a person — `Intl.NumberFormat`, a date picker — is each
-platform's, never this package's.
+Where the values live is a port (`ContextStore`): synchronous reads, a version per change and an
+optional `watch`. `memoryContexts()` is the default; a browser, a phone or a server render plugs
+its own. `values` is the same object until it changes, so a screen can hand it to React's
+`useSyncExternalStore`.
 
-A relation that holds several records — the invoices of a customer — comes as a page of them,
-never an array: forty records, «at least 1000», and the cursor to go on. Read it with
-`collectionOf` (an array from a hand-written domain reads the same) — a `HeldCollection`, edited
-the way a string is: `append`, `extend`, `remove`, `replace` answer a new one. Say «1000+» when
-`count.exact` is false, and ask for the rest as a list of the related entity
-(`relatedCriteria(meta.fields.invoices, customer)`). A part of the record — the lines of an
-invoice — is written back only whole: the backend refuses a page of it.
+## Talking to a server
 
-A search asked for millions of records answers Parquet instead of JSON to a client that reads it.
-Give the transport the decoder — an optional entry over `hyparquet` — and nothing above it
-changes: the same page, each value as the JSON wire writes it.
+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 { restTransport } from "@sincpro/client-framework";
-import { parquetDecoder } from "@sincpro/client-framework/parquet";
+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.
 
-const transport = restTransport({ base: "/v1", decoders: [parquetDecoder] });
+```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) });
+      }
+    },
+  };
+}
 ```
 
-## Where it sits
-
-```mermaid
-flowchart TB
-  backend["sincpro_framework<br/>the service: its bounded contexts, Commands, the client contract"]
-  criteria["@sincpro/criteria<br/>Criteria · Meta · Page · Problem"]
-  cf["@sincpro/client-framework<br/>bounded contexts · services · process · context · ports · the client · the generator"]
-  web["@sincpro/web-framework<br/>hooks · screens · the browser's tracer and reporter"]
-  mobile["@sincpro/mobile<br/>React Native · SQLite · its queue"]
-  rest["a script · a server-side render · a test"]
-  web --> cf
-  mobile --> cf
-  rest --> cf
-  cf --> criteria
-  backend -. "client contract → sincpro-client generate" .-> cf
-  cf -- "HTTP · traceparent · sincpro-context" --> backend
+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
+
+```bash
+python -m sincpro_framework.entrypoints export-client-contract app.http:gateways contracts [--events]
+sincpro-client generate contracts/project.contract.json --out src/domains/project/generated --domain project
+sincpro-client scaffold contracts/project.contract.json --out src/domains/project
+sincpro-client check --root src
 ```
 
-No React, no DOM, no platform: what a platform must provide — how a span is exported, where an
-error is reported, where the context lives — it plugs through a port.
+`generate` writes, from the contract the backend exports — never edited, written again whole:
 
-## On each platform
+| 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                   |
 
-This package asks the platform for little: `fetch`, `AbortSignal`, `URL` / `URLSearchParams`,
-`crypto.getRandomValues` (client-side ids, retry keys), `Proxy` / `WeakMap`. Browsers and Node 26
-have them all. **React Native** (Hermes) needs two polyfills, installed once where the app
-starts, before anything imports this package:
+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,
+`name` its wire name as a literal — and `DomainEvent`, their union, narrows by `name`:
 
 ```ts
-import "react-native-get-random-values"; // or expo-crypto's getRandomValues polyfill
-import "react-native-url-polyfill/auto"; // RN's own URL resolves relative paths poorly
+import type * as remote from "./generated/domain";
+
+function subjectOf(event: remote.DomainEvent): string {
+  switch (event.name) {
+    case "project.issue.v1.closed":
+      return event.issue_id; // remote.IssueClosed
+    // …
+  }
+}
 ```
 
-`memoryTransport` copies with `structuredClone` where the engine has it and a JSON round trip
-where it does not. The OpenTelemetry adapter takes `@opentelemetry/api` from 1.9, the version
-`@sincpro/mobile` runs.
+`events` in `client.ts` says, per event, its wire name and whether the bounded context records it
+(its aggregates' own) or handles it (a Feature subscribes).
 
-The services are the same everywhere; each platform plugs its own technology behind the same
-three ports, in its `main`:
+### Types, not classes
 
-| Port            | Browser (@sincpro/web-framework)                | Phone (@sincpro/mobile)                    | Test              |
-| --------------- | ----------------------------------------------- | ------------------------------------------ | ----------------- |
-| `Tracer`        | OpenTelemetry + OTLP/HTTP (`./telemetry`)       | OpenTelemetry with its queue and exporter  | `memoryTracer`    |
-| `ErrorReporter` | GlitchTip / Sentry browser client (`./errors`)  | Sentry React Native client                 | `memoryReporter`  |
-| `ContextStore`  | memory, `sessionStorage`, or the screens' store | MMKV, or memory hydrated from AsyncStorage | `memoryContexts`  |
-| `Transport`     | `restTransport` over `fetch`                    | `restTransport`, or SQLite offline         | `memoryTransport` |
+What is generated is the remote service's contract and an adapter over it, so it is written as
+types; the application's own Commands are classes, written by hand.
 
-How @sincpro/mobile adopts all of this — what maps to what, the MMKV store, the order to move
-in — is [`docs/MOBILE.md`](docs/MOBILE.md).
+- **The wire is JSON, and a type says it exactly.** A decimal is text, a day is text, a page is
+  `{ items, count, cursor }`. A class around that JSON would claim more than it holds unless
+  every field had a reader; a type claims nothing it does not hold.
+- **The local bus routes by class, and the remote contract must not reach it.** 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. A remote call happens inside
+  a local Feature, through the injected client.
+- **Events read best as a union.** A stream of facts — a queue, a history page — is narrowed by
+  `name`, with no registry of constructors to rebuild each one.
+- **Nothing runs.** `domain.ts` adds no byte to a bundle and no side effect; a contract of three
+  hundred models costs nothing at runtime.
 
-A store's reads are synchronous — a use case reads its context where a gesture starts and never
-waits for it — so an asynchronous storage is held in memory and written through.
+A local class takes the contract's shape and stays checked against it:
 
-## Development
+```ts
+import type * as remote from "../generated/domain";
+
+class CommandCancelIssue
+  extends Command<ResponseCancelIssue>
+  implements remote.CommandCancelIssue
+{
+  constructor(readonly issue_id: string) {
+    super();
+  }
+}
+```
 
-Node 26 (`nvm use`).
+The generated name and the local one may be the same — the backend's —, so the generated ones
+are imported under their own (`remote`). Validating and converting what arrives (a decimal into
+`Decimal`) is a reader's job, not a class's: generated readers are the next step, when a use
+needs them.
 
-```bash
-make init            # pre-commit + dependencies
-make test            # vitest, in Node
-make verify-format   # format + lint + doctor; fails if the tree is left dirty (what CI runs)
-make build           # tsc into dist/
+## Values on the wire
+
+| Value      | Travels as                             | API                                            |
+| ---------- | -------------------------------------- | ---------------------------------------------- |
+| Decimal    | exact text, `"10.50"`                  | `Decimal`                                      |
+| Money      | `{ amount: "10.50", currency: "BOB" }` | `Money`                                        |
+| Day        | `"2026-10-02"`, never an instant       | `isDay`, `dayOf`                               |
+| Instant    | ISO text                               | `wallTimeOf`, `instantOf`                      |
+| ID         | UUID v7 as 32 hex                      | `newEntityId`, `isEntityId`, `momentOf`        |
+| Bytes      | `{ "$bytes": "<base64>" }`             | `valuesOf`, `readValues`                       |
+| Collection | items, count and cursor                | `collectionOf`, `isPartial`, `relatedCriteria` |
+| Export     | Parquet, Arrow or JSON Lines           | `downloadRoute`, `exportRoute`                 |
+
+`Decimal` and `Money` compute exactly, on `BigInt`; a decimal never becomes a `number` and a day
+never a `Date`. `valuesOf`/`pack` write; `readValues` reads tagged values back; `rebuilt`/`unpack`
+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.
+
+## 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, and what kind of failure an error is
+  circuit_breaker/ CircuitBreaker, CircuitOpen
+  context/
+    domain/          ContextStore and ContextCodec ports, what travels, Execution
+    adapters/        memoryContexts, plainCodec
+    entrypoint/      Context: one door over a level
+    infrastructure/  the process's store and processContext
+  observability/
+    domain/          Tracer, ErrorReporter, Logger ports
+    adapters/        console (default), memory, opentelemetry and sentry (optional entries)
+    infrastructure/  the ports this process runs with
+    services/        logger, loggerAdapter, reportError, outcomeOf
+  client/
+    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, 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, 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
 ```
 
-`make doctor` enforces what the type checker cannot: the source imports itself, never a relative
-path; no React, no UI, no browser global; Node only inside the generator. Read
-[`AGENTS.md`](AGENTS.md) before changing anything, and [`CONTRIBUTING.md`](CONTRIBUTING.md)
-before opening a pull request.
+| Entry                                                   | What                                        |
+| ------------------------------------------------------- | ------------------------------------------- |
+| `@sincpro/client-framework`                             | everything an application runs              |
+| `@sincpro/client-framework/core`                        | the application layer alone                 |
+| `@sincpro/client-framework/testing`                     | the observability ports in memory           |
+| `@sincpro/client-framework/codegen`                     | the generator, as functions                 |
+| `./console`, `./opentelemetry`, `./sentry`, `./parquet` | optional entries; a vendor's SDK only there |
+
+## Development
 
-## CI/CD
+Node 26 (`nvm use`):
+
+```bash
+make init
+make typecheck
+make test
+make verify-format      # eslint --fix + prettier + typecheck + doctor; fails on a dirty tree
+make build
+make codegen-fixtures   # after changing the generator on purpose; read the diff
+```
 
-Every workflow in `.github/workflows/` delegates to
-[`Sincpro-SRL/.github`](https://github.com/Sincpro-SRL/.github) and only calls `make` targets:
-checks on every pull request and push to `main`, a release draft on `main`, publication to npm
-when a release is published, and notifications. The version is written by the release pipeline,
-never by hand.
+`make doctor` enforces what the compiler does not: self-imports, no platform (React, DOM, Node
+outside `codegen/`), a vendor's SDK only in its optional entry, and `domain/` importing only
+`domain/`. Tests run in Node, one folder per module; `tests/support/forge-contract/` holds real
+contracts and what the generator writes from them, compared byte for byte.
+
+The runtime uses `fetch`, `AbortSignal`, `URL`, `crypto.getRandomValues`, `Proxy`, `WeakMap` and
+`BigInt`; React Native must provide URL and random values before ids or transports are used.
+
+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),
+[`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