@sincpro/client-framework 0.6.0 → 1.1.0

package/AGENTS.md

@@ -20,18 +20,23 @@ it says what this package is responsible for and what it is not. This file is ho
 
 ## Where things go
 
-| Folder               | What                                                                                          |
-| -------------------- | --------------------------------------------------------------------------------------------- |
-| `src/common/`        | The values of the wire: ids, a day and an instant, `Decimal`, `Money`, `valuesOf` / `rebuilt` |
-| `src/client/`        | The seam with a server: `Transport`, REST, memory, `entity()`, the client contract            |
-| `src/model/`         | Model definitions: `defineMeta`, from a JSON Schema, the store of known ones                  |
-| `src/services/`      | `UseBoundedContext`, `Feature`, `ApplicationService`, the process, the execution              |
-| `src/context/`       | The `ContextStore` port, `memoryContexts`, and `Context` — one level of it                    |
-| `src/observability/` | The ports a platform plugs: `Tracer`, `ErrorReporter`                                         |
-| `src/codegen/`       | The generator and its CLI (`sincpro-client generate`) — the only place Node is allowed        |
-| `src/adapters/`      | Optional entries over a vendor (`./opentelemetry`, `./sentry`): the only place one is named   |
-| `src/testing/`       | `memoryTracer`, `memoryReporter` — the ports in memory, for tests                             |
-| `tests/`             | vitest in Node; `tests/support/` holds the fake domains and forge's real contracts            |
+Each module is laid out as sincpro_framework's are: `domain/` (ports, types and rules),
+`adapters/` (implementations of the ports), `services/` (what uses them), `infrastructure/`
+(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 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`)
 
@@ -42,6 +47,11 @@ it says what this package is responsible for and what it is not. This file is ho
   and nowhere else; nothing an application runs imports `codegen/`.
 - **Self-imports, no extensions.** Inside `src/`, import `@sincpro/client-framework/<path>` —
   never a relative path, never `.ts`.
+- **Domain inward.** A `domain/` folder imports only other `domain/` folders: no adapter,
+  service, infrastructure or entrypoint.
+- **Vendors in their entry.** A vendor's SDK is imported only in its optional entry
+  (`observability/adapters/opentelemetry.ts`, `observability/adapters/sentry.ts`,
+  `client/adapters/parquet.ts`), and nothing in `src/` imports one.
 
 ## Conventions
 
@@ -55,17 +65,53 @@ it says what this package is responsible for and what it is not. This file is ho
 ## Known traps
 
 - **A run sees the instance through a view of its own.** Inside a method, each dependency
-  (`this.client`), `this.context` and `this.feature` are that run's — bound to its execution. So a
+  (`this.client`), `this.context` and `this.featureBus` are that run's — bound to its execution. So a
   service declares no `#private` fields (they refuse the view); use TypeScript's `private`.
-- **A service is a singleton of its bounded context.** What a method writes on `this` lands on the
-  instance, shared by the next call, the call beside it and every `with`/`scoped` variant — as in
+- **A service is a singleton of its generation.** What a method writes on `this` lands on the
+  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 is named by the registered name, not the class** (`register({ features: { Issues } })`
-  → `project/Issues.close`, identity `project.Issues.close`): a production build renames classes,
-  never the keys of an object.
-- **The dependencies are typed, not declared.** `BaseFeature<ProjectDependencies>` types
-  `this.client` from an interface, which does not exist at run time; the bounded context answers
-  whatever was added with `addDependency`. A dependency nobody added reads `undefined`.
+- **A span uses stable service metadata, not constructor.name.** `serviceName = "Cancel"` gives
+  `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.
+- **Decorators are optional.** Function registration must work without any decorator
+  transform. Standard and legacy (`experimentalDecorators`) fixtures are compiled explicitly in
+  tests; do not claim Metro (Babel) or web bundler support without testing those configurations.
 - **The trace reaches the wire through the dependencies.** A dependency is bound to the run when it
   is a `Transport` or carries `BIND` (every generated client does, through `bindable`); anything
   else is handed as it is. A client built elsewhere and closed over sends no trace.
@@ -76,20 +122,44 @@ it says what this package is responsible for and what it is not. This file is ho
 - **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`);
+  validating or converting what arrives would be a generated reader, not a class.
+- **Events come only from the contract.** The generator writes event types and `DomainEvent`
+  only when the backend exported its contract with `--events`; a contract without them writes
+  the same bytes as before.
 - **What the generator writes is compared byte for byte** (`tests/support/forge-contract/`, out
   of prettier and eslint). After changing the generator on purpose, run `make codegen-fixtures`
   and read the diff.
-- **A module name the generator writes is built in parts** (`codegen/names.ts`, `FRAMEWORK`): the
+- **A module name the generator writes is built in parts** (`codegen/domain/names.ts`, `FRAMEWORK`): the
   build's `tsc-alias` rewrites this package's specifiers inside strings too.
 - **An adapter wraps what the application built, never builds it.** `openTelemetryTracer` takes
   the app's tracer, `sentryReporter` the app's client: no `register()`, no `Sentry.init()`, no
   endpoint or DSN here, nothing read from the environment. A vendor's SDK is imported only in
-  `src/adapters/`, and nothing else imports an adapter (`make doctor`).
+  its optional entry, and nothing else imports one (`make doctor`).
 - **A span nothing records claims no trace.** OpenTelemetry's API with no provider answers an
   all-zeros span: the adapter gives no ids, so no `traceparent` of zeros reaches the server.
 - **Reported means unexpected.** A `TransportError` the server answered with a 4xx is `refused`,
-  an `AbortError` is `aborted`; neither is reported (`outcomeOf`). Change that with
-  `ProcessOptions.outcomeOf`, never by catching in a Feature.
+  an `AbortError` is `aborted`; neither is reported (`outcomeOf`). A bounded context adds its own
+  with `expectErrors(...)`; a process replaces the rule with `ProcessOptions.outcomeOf`. Never
+  catch in a Feature to hide a failure.
+- **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
+  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
+  default engine; `configureProcess({ logger })` and `configureLogger(...)` take the same
+  `LoggerConfiguration`. The host chooses production explicitly. Never log DTOs, results, full
+  session context or raw errors automatically.
 
 - **Only what is transversal comes here.** A value's wire form (a decimal as text, a day never
   an instant, a money with its currency) is the backend's contract, the same on every platform,

package/MANIFESTO.md

@@ -25,28 +25,34 @@ server-side render, in a script and in a test, unchanged.**
 
 ## What it is responsible for
 
-1. **Services.** A `Feature` is a facade over one part of the domain, each public method a use
-   case; an `ApplicationService` composes the Features of its own bounded context — never another
-   ApplicationService. All of a client's logic lives in them, with their dependencies typed and
-   injected by their bounded context (`this.client`, `this.session`).
-2. **Interception.** Every public method of a use case passes through interceptors, and that is
-   what makes the defaults free: the trace, the error report, the context. The author of a
-   Feature writes none of it.
-3. **Observability, as ports.** `Tracer` and `ErrorReporter` are the contract: one span per use
-   case, named `<bounded context>/<Service>.<method>` like the backend's; the unexpected reported
-   with its trace id; what the server already explained (a validation, a conflict) not reported.
+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 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
+   bounded context declares expected, not reported.
    The platform plugs the implementation — OpenTelemetry, GlitchTip, a queue on the phone, memory
-   in a test — once, for the process (`configureProcess`).
+   in a test — once, for the process (`configureProcess`). Structured logs are tagged by layer
+   (infrastructure, adapter, bounded context, ApplicationService, Feature) and by execution;
+   console filtering never controls another sink's delivery.
 4. **Context.** The levels a call sees — the process, its bounded context, a scope — read once
    where a gesture starts and inherited by everything it runs, and what travels to the server with
    it (`traceparent`, `sincpro-context`). Where the values live is a port (`ContextStore`) each
    platform implements with its own technology; the execution is carried by each call, never kept
    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 once — and used through one light object:
-   `project.Issues.close(input)`. 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
+   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 `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
@@ -54,9 +60,25 @@ server-side render, in a script and in a test, unchanged.**
    and the exact arithmetic a client needs on them (`Decimal`, `Money`). Only the wire form and
    what follows from it: showing a value to a person is each platform's.
 8. **The generator.** From a service's client contract to each domain's types, client and
-   entities — generated, never edited, and as platform-neutral as everything else here.
+   entities — and its domain events when the contract carries them —, generated as types,
+   never edited, and as platform-neutral as everything else here.
 9. **Testing.** An in-memory transport, tracer and reporter, so a use case is proven in Node with
    nothing else.
+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, 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
 
@@ -73,9 +95,13 @@ server-side render, in a script and in a test, unchanged.**
   application built — its provider, its client, with its endpoint and its DSN. It initialises
   nothing and registers nothing global; an application that does not import them installs
   nothing and ships nothing, and without a tracer or a reporter everything runs the same.
-- **Not where business rules live.** The server keeps them; a client reads what it publishes.
-- **Not an event bus**, and not a dispatcher: a use case is executed by calling it, and the
-  interceptors are what make that call traced and reported.
+- **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 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
 
@@ -85,17 +111,18 @@ server-side render, in a script and in a test, unchanged.**
 2. **The backend's words.** Bounded context, Feature, ApplicationService, dependencies, context,
    process, the span name — the same as sincpro_framework, so whoever knows the backend already
    knows the client.
-3. **Nothing escapes the interceptors.** Reusing a use case is calling it through its bounded
-   context. A helper that wraps one skips the trace and the report — that is how an incident ends
-   up with nothing to look at.
+3. **Nothing escapes execution.** Reusing a use case means dispatching its Command through the
+   bounded context or feature bus. Directly constructing and calling a service bypasses its
+   execution context and instrumentation.
 4. **Context travels with the call.** Never in a global stack: clients run many things at once.
 5. **A port where there are two implementations, a class where there is one.** `Transport` has
    REST and memory; `Tracer` has a platform's and a test's; `ContextStore` has the browser's, the
    phone's and memory.
 6. **Generated, never edited.** Applications extend by composition; regenerating never loses
    work.
-7. **The server is the source of truth.** A client reads the model, the preview and the refusal,
-   and never re-implements a rule.
+7. **Authority is explicit.** A generated client reads the server's model and refusal and never
+   authorizes duplicating server rules. A local domain can own local rules; synchronization and
+   conflict policy are separate from command delivery.
 8. **Small, and paid for only when used.** No side effects at import, tree-shakable, and no
    dependency it can avoid.
 9. **Grow by evidence.** Nothing before its second use; every change ships with a test that fails
@@ -107,8 +134,8 @@ server-side render, in a script and in a test, unchanged.**
 @sincpro/criteria           the contract with the server: Criteria, Meta, Page, Problem
         ▲
 @sincpro/client-framework   this package — platform-neutral
-        │   UseBoundedContext · Feature · ApplicationService · interceptors
-        │   the process · the context · Tracer, ErrorReporter and ContextStore ports
+        │   BoundedContext · Command · Feature · ApplicationService · execution
+        │   the process · the context · Tracer, ErrorReporter, Logger and ContextStore ports
         │   Transport · entity() · client contract · model definitions · ids
         │   the generator · in-memory doubles for tests
         ▲
@@ -119,22 +146,58 @@ server-side render, in a script and in a test, unchanged.**
 
 Dependencies point down only. This package knows nothing above it.
 
-## Where it stands
-
-**The first cut is here.** The client and the generator came out of @sincpro/web-framework,
-where they already ran without the DOM. `Feature` and `ApplicationService` came from
-@sincpro/mobile, with each call carrying its own execution instead of a global stack. And the
-ports for tracing and error reporting are in, with the trace and the context written on every
-request a use case sends.
+**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.
 
-**Then the bounded context**, set up as the backend sets one up: a dependency type that types every
-service's `this.client`, `addDependency`, the services registered by name and used as
-`project.Issues.close(input)` and `this.feature.Issues`; the process configured once in `main`
-(`configureProcess`); and the context as a port, so the browser and the phone keep it each with
-their own technology behind the same door.
+## Where it stands
 
-**Next:** @sincpro/mobile on this package, and the screens' side in @sincpro/web-framework — the
-cache of reads, invalidated by the writes a use case sends.
+**The application layer is the backend's.** A bounded context executes class Commands through
+one pipeline — context, span, log lines, outcome, report — with its dependencies injected,
+its ApplicationServices composing Features through `featureBus`, and the backend's error
+handlers: a failure is observed where it happened, then answered or handed on. Screen requests
+and scaffolded applications run through the same pipeline.
+
+**Observability is ports, plugged once.** Tracing, error reporting and logging are ports the
+process configures; the console is the default log engine, OpenTelemetry and Sentry optional
+entries that wrap what the application built. The application layer imports no logger: a
+bounded context has its own, and a run hands `this.logger`, bound to its execution; only the
+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 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/`.
+
+**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