@sincpro/client-framework 1.0.0 → 1.2.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; queues; `Publisher`, `Subscriber`, `Subscriptions` |
+| `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,58 @@ 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 use case of an
+  event per bounded context, one `EventSubscriber` per event per `Subscriptions`; 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 one who heard it twice — over an
+  `EventStore` the platform plugs (SQLite, IndexedDB, memory). A store only keeps records; it
+  never decides.
+- **A subscriber is an entrypoint, not a use case.** An `EventSubscriber` reads the event and
+  executes Commands on a bounded context it was given, as a cron does on a tick; what to decide,
+  and a workflow of several use cases, is a Feature or an ApplicationService it executes. Its run
+  is layer `entrypoint`: no interceptor wraps it, no listener hears it, no error handler answers
+  it. An event may instead be the input of a use case (`feature(Event)(Service)`) when the use
+  case exists because of it. A `Subscriptions` is named apart from every bounded context: the
+  queue keeps who heard an event by name, and `Subscriber` refuses two of one name.
+- **A bounded context injected into a run is bound to it** (`BIND`): what it executes is a child
+  of the caller — span, flow, cause, signal, one report — with its own dependencies, context and
+  handlers. A failure keeps the outcome where it first failed, so a caller does not report what
+  the callee expected.
+- **A bounded context is named for what it is.** `salesBoundedContext`, never `sales` (an
+  entity?) and never `ctx` or `bc`: `context` is already the run's. The scaffold writes it so.
+- **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 after a crash. A use case of the
+  event keys its effect by `this.execution.causationId` (the envelope's id); an `EventSubscriber`
+  finds the same id in its own run and hands it in the Command it executes — the use case's
+  `causationId` is the subscriber's run —, or the effect is keyed by the entity the event names.
+  `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 +139,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`);
@@ -112,7 +170,7 @@ module has only the layers it needs, and says what it offers in its own `index.t
 - **An error handler answers; it does not observe.** The failure is recorded where it happened —
   span, log line, report — before the layer's handlers run, as in sincpro_framework. A handler
   returns the answer or throws to the next; the global chain wraps only `execute` and `scoped`.
-- **The application layer imports no logger.** A bounded context has `project.logger`; a run
+- **The application layer imports no logger.** A bounded context has `projectBoundedContext.logger`; a run
   hands `this.logger`, bound to its execution. Only `logger` (infrastructure, the global one) and
   `loggerAdapter` are predefined; injected as a dependency they bind to the run (`BIND`), imported
   at module level they do not. No logger is predefined for an application layer. Console is the

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
@@ -45,9 +48,11 @@ server-side render, in a script and in a test, unchanged.**
    in a global stack: two calls at once never mix their parents.
 5. **Bounded contexts.** Set up like the backend's — its dependencies (`addDependency`), its
    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
+   `projectBoundedContext.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,20 @@ 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 as the input of a use case, 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, the
+    `EventSubscriber` — the entrypoint that hears an event and calls use cases, as a cron does on
+    a tick — and its `Subscriptions`, a `Subscriber` over everyone who hears, 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 +100,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 +148,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 +171,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