@sincpro/client-framework 0.5.0 → 1.0.0

package/AGENTS.md

@@ -20,18 +20,22 @@ 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, 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      |
 
 ## Hard rules (the build enforces them — `make doctor`)
 
@@ -42,6 +46,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 +64,19 @@ 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 route by exact constructor identity.
+- **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 +87,38 @@ 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.
+- **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,27 +25,28 @@ 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 enters one internal execution pipeline. Context, tracing,
+   outcomes and error reporting are supplied there, not handwritten by each service.
+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.
+   Features and ApplicationServices, registered for class DTOs — and called as
+   `project.execute(new Command(...))`. The bounded context is the bus. An application is the set
+   of bounded contexts it loads; they never import each other's insides.
 6. **The client.** The `Transport` port and its implementations (REST, memory), `entity()` with
    typed commands and answers, the service's client contract, model definitions read once from
    the server and the server's `Problem`.
@@ -54,9 +55,16 @@ 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, 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.
 
 ## What it is not
 
@@ -73,9 +81,11 @@ 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 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.
 
 ## What we believe
 
@@ -85,17 +95,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 +118,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
         ▲
@@ -121,20 +132,29 @@ 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.
-
-**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.
-
-**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 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.
+
+**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.
 
 ## How we decide