@sincpro/client-framework 0.1.0 → 0.3.0

package/AGENTS.md

@@ -8,23 +8,29 @@ it says what this package is responsible for and what it is not. This file is ho
 - **Read the manifesto.** A piece that serves nothing there does not go in; a piece it forbids
   does not either. If you think it should, change the manifesto first and say why.
 - **Look at the backend.** This package mirrors sincpro_framework (`~/dev/sincpro_framework`):
-  `Feature`, `ApplicationService`, the context, the span per use case. When in doubt about a
+  the bounded context and its dependencies, `Feature`, `ApplicationService`, the context and its
+  store, the process, the span per use case. When in doubt about a
   word or a behaviour, read how the backend does it, not memory.
+- **Use the shared words.** [`docs/UBIQUITOUS_LANGUAGE.md`](docs/UBIQUITOUS_LANGUAGE.md) is the
+  vocabulary of every Sincpro framework. A new word, or a word that changes, goes there in the
+  same pull request; a word in its «do not use» table never enters code or docs.
 - **Look at who uses it.** @sincpro/web-framework (`~/dev/sincpro_web_framework`) and
   @sincpro/mobile (`~/dev/mobile/sincpro_mobile`). A piece only one of them needs, and that
   needs a platform, belongs there.
 
 ## Where things go
 
-| Folder               | What                                                                                    |
-| -------------------- | --------------------------------------------------------------------------------------- |
-| `src/client/`        | The seam with a server: `Transport`, REST, memory, `entity()`, the client contract, ids |
-| `src/model/`         | Model definitions: `defineMeta`, from a JSON Schema, the store of known ones            |
-| `src/services/`      | `Feature`, `ApplicationService`, the runtime, the execution and what binds to 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/testing/`       | `memoryTracer`, `memoryReporter` — the ports in memory, for tests                       |
-| `tests/`             | vitest in Node; `tests/support/` holds the fake domains and forge's real contracts      |
+| Folder               | What                                                                                        |
+| -------------------- | ------------------------------------------------------------------------------------------- |
+| `src/client/`        | The seam with a server: `Transport`, REST, memory, `entity()`, the client contract, ids     |
+| `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          |
 
 ## Hard rules (the build enforces them — `make doctor`)
 
@@ -32,7 +38,7 @@ it says what this package is responsible for and what it is not. This file is ho
   no `document`, `window`, `localStorage`, `navigator`. What a platform must give, it gives
   through a port.
 - **Node only in the generator.** `node:` imports, `process` and `Buffer` live in `src/codegen/`
-  and nowhere else; nothing in the runtime imports `codegen/`.
+  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`.
 
@@ -47,24 +53,42 @@ 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, `this.deps`,
-  `this.context` and `this.features` are that run's — bound to its execution. So a Feature keeps
-  nothing of a request on `this`, and declares no `#private` fields (they refuse the view); use
-  TypeScript's `private`.
-- **A span is named by the key, not the class** (`bindServices(runtime, "project", { sendIssue })`
-  → `project/sendIssue`; an ApplicationService's Features by their keys too): a production build
-  renames classes. Only an unbound Feature falls back to its class name.
-- **The trace reaches the wire through `deps`.** 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 outside `deps` and closed over sends no trace.
+- **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
+  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
+  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`.
+- **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.
+- **The process is read on every call, never at import.** `project` is defined when its module
+  loads, before `main` runs `configureProcess`; nothing may capture the tracer, the reporter or the
+  store at definition time. `configureProcess` replaces everything at once — a test calls it in
+  `beforeEach` and starts with an empty context.
+- **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 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
   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`).
+- **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
-  `RuntimeOptions.outcomeOf`, never by catching in a Feature.
+  `ProcessOptions.outcomeOf`, never by catching in a Feature.
 
 ## Before you hand it back
 

package/MANIFESTO.md

@@ -25,22 +25,27 @@ server-side render, in a script and in a test, unchanged.**
 
 ## What it is responsible for
 
-1. **Use cases.** `Feature` is one use case, with its dependencies injected; `ApplicationService`
-   is a Feature that also executes the Features of its own domain — never another
-   ApplicationService. All of a client's logic lives in them.
+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 `<domain>/<Feature>` like the backend's; the unexpected reported with its trace id;
-   what the server already explained (a validation, a conflict) not reported. The platform plugs
-   the implementation — OpenTelemetry, GlitchTip, a queue on the phone, memory in a test.
-4. **Context.** The levels a call sees — the application, its domain, the call itself — and what
-   travels to the server with it (`traceparent`, `sincpro-context`). Carried by each call, never
-   kept in a global: two calls at once never mix their parents.
-5. **Domains and the application.** A bounded context is declared once — its client, its use
-   cases, what they depend on — and an application is the set of domains it loads. Domains never
-   import each other; they talk by reference.
+   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.
+   The platform plugs the implementation — OpenTelemetry, GlitchTip, a queue on the phone, memory
+   in a test — once, for the process (`configureProcess`).
+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
    typed commands and answers, the service's client contract, model definitions read once from
    the server, client-side ids (UUID v7) and the server's `Problem`.
@@ -55,11 +60,15 @@ server-side render, in a script and in a test, unchanged.**
   the web and to @sincpro/mobile on a phone.
 - **Not a shell, a router or a window manager.** Where things open is the platform's.
 - **Not a cache or a state manager.** Holding server state for screens is the platform's job,
-  with the libraries that do it best.
+  with the libraries that do it best. The context is not one either: a handful of values every
+  use case runs with — the tenant, the company — kept wherever the platform says.
 - **Not offline storage.** SQLite on a phone or IndexedDB in a point of sale are platform
   adapters.
-- **Not a telemetry or error-tracking SDK.** It defines the ports and calls them; it bundles no
-  vendor.
+- **Not a telemetry or error-tracking SDK.** It defines the ports and calls them. For the
+  common vendors it offers optional adapters (`./opentelemetry`, `./sentry`) that wrap what the
+  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.
@@ -69,14 +78,16 @@ server-side render, in a script and in a test, unchanged.**
 1. **Platform-neutral, or it does not go in.** It runs on Node, in a browser and on React Native.
    What it needs from a platform it asks through a port, never by reaching for it. The build
    enforces it.
-2. **The backend's words.** Feature, ApplicationService, domain, context, 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 executing its Feature. A helper
-   that wraps one skips the trace and the report — that is how an incident ends up with nothing
-   to look at.
+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.
 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.
+   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,
@@ -92,8 +103,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
-        │   Feature · ApplicationService · interceptors · context per call
-        │   Domain · application · Tracer and ErrorReporter ports
+        │   UseBoundedContext · Feature · ApplicationService · interceptors
+        │   the process · the context · Tracer, ErrorReporter and ContextStore ports
         │   Transport · entity() · client contract · model definitions · ids
         │   the generator · in-memory doubles for tests
         ▲
@@ -112,8 +123,14 @@ where they already ran without the DOM. `Feature` and `ApplicationService` came
 ports for tracing and error reporting are in, with the trace and the context written on every
 request a use case sends.
 
-**Next:** the domains and the application. The plan is written in @sincpro/web-framework
-(`docs/prd/PRD_02_marco-de-trabajo.md`, in Spanish like the rest of Sincpro's design records).
+**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.
 
 ## How we decide
 

package/README.md

@@ -5,60 +5,317 @@ every platform.** Write a use case once — a `Feature`, or an `ApplicationServi
 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 domains.
+its bounded contexts.
 
-> **Status: 0.x, the first cut.** The API may still change before 1.0. In: the client, the
-> generator, `Feature` and `ApplicationService` with their interceptors, and the ports for tracing
-> and error reporting. Read the [manifesto](MANIFESTO.md) for what this package is responsible
-> for, what it is not and where it is going.
+> **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.
 
-## A use case, traced and reported by default
+## 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
+  }
+  class ErrorReporter {
+    <<port>>
+    +report(error, about)
+  }
+  class Transport {
+    <<port>>
+    +list(route, criteria)
+    +one(route)
+    +send(method, route, body)
+  }
+  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
+```
 
 ```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;
+}
+
+export function registerDependencies(bc: UseBoundedContext<ProjectDependencies>) {
+  bc.addDependency("client", clientOf(transport));
+  bc.addDependency("session", session);
+  return bc;
+}
+```
+
+```ts
+// domains/project/infrastructure/bounded_context.ts
 import {
-  ApplicationService,
-  bindServices,
-  createRuntime,
-  Feature,
+  ApplicationService as BaseApplicationService,
+  Feature as BaseFeature,
+  UseBoundedContext,
 } from "@sincpro/client-framework";
 
-class SendIssue extends Feature<{ project: ProjectClient }> {
-  execute(input: dto.CommandSendIssue) {
-    return this.deps.project.sendIssue(input); // carries this run's traceparent
+import type { ProjectFeatures } from "../services";
+
+export class Feature extends BaseFeature<ProjectDependencies> {}
+export class ApplicationService extends BaseApplicationService<
+  ProjectDependencies,
+  ProjectFeatures
+> {}
+
+export function configProjectBoundedContext(name: string) {
+  return registerDependencies(new UseBoundedContext<ProjectDependencies>(name));
+}
+```
+
+```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 CloseIssue extends ApplicationService<{ preview: PreviewClose; send: SendIssue }> {
-  async execute(input: CloseIssueInput) {
-    const preview = await this.features.preview.execute(input); // a child span
-    if (preview.warnings.length > 0) return { blocked: preview };
-    return this.features.send.execute({ ...input, message: "closed" }); // another child
+// 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);
   }
 }
 
-const runtime = createRuntime({ tracer, reporter, context: () => ({ tenant_id: "acme" }) });
-const project = bindServices(runtime, "project", {
-  closeIssue: new CloseIssue({ preview: new PreviewClose(deps), send: new SendIssue(deps) }),
+// domains/project/services/index.ts
+export const features = { Issues, Notices };
+export const applicationServices = { CloseAndNotify };
+export type ProjectFeatures = typeof features;
+```
+
+```ts
+// domains/project/index.ts
+export const project = configProjectBoundedContext("project").register({
+  features,
+  applicationServices,
+});
+
+// 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
+```
+
+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)
+```
+
+`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.
+
+## The process: tracing, errors and the context
+
+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:
+
+```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)
 });
-await project.closeIssue.execute(input); // project/closeIssue → project/preview, project/send
+
+processContext.set({ tenant_id: "acme" }); // every use case runs with it and sends it
+project.context.set({ warehouse_id: 4 }); // only what «project» runs
+```
+
+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
 ```
 
-`tracer` and `reporter` are the platform's: OpenTelemetry and GlitchTip in a browser, a queue on
-a phone, `memoryTracer()` and `memoryReporter()` (`@sincpro/client-framework/testing`) in a test.
-A use case that was never bound runs too, with nothing tracing.
+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.
+
+`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:
+
+```ts
+import { openTelemetryTracer } from "@sincpro/client-framework/opentelemetry"; // peer: @opentelemetry/api
+import { sentryReporter } from "@sincpro/client-framework/sentry"; // no dependency
+
+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)
+```
+
+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`).
 
 ## Where it sits
 
-```text
-@sincpro/criteria           the contract with the server
-        ▲
-@sincpro/client-framework   use cases · interceptors · context · ports · domains · the client
-        ▲
-@sincpro/web-framework      the web          @sincpro/mobile      a phone
+```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
 ```
 
 No React, no DOM, no platform: what a platform must provide — how a span is exported, where an
-error is reported — it plugs through a port.
+error is reported, where the context lives — it plugs through a port.
+
+## On each platform
+
+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:
+
+```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
+```
+
+`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.
+
+The services are the same everywhere; each platform plugs its own technology behind the same
+three ports, in its `main`:
+
+| 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` |
+
+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.
 
 ## Development
 

package/dist/adapters/opentelemetry.d.ts

@@ -0,0 +1,21 @@
+import { type Tracer as OtelTracer } from "@opentelemetry/api";
+import type { Tracer } from "../observability/ports.js";
+/**
+ * The `Tracer` port over OpenTelemetry's API: every use case a span of whatever provider the
+ * platform registered.
+ *
+ *     // a browser (@sincpro/web-framework/telemetry does this), Node, React Native…
+ *     const tracer = openTelemetryTracer(provider.getTracer("forge-web"));
+ *     configureProcess({ tracer });
+ *
+ * Context: only `@opentelemetry/api`, which runs the same on every platform — the provider, its
+ * exporter and where it sends are the platform's (the browser's OTLP over fetch, a phone's
+ * queue, a server's SDK). An optional entry with an optional peer: an application that does not
+ * import it installs nothing and ships nothing.
+ *
+ * The parent is given, never read from OpenTelemetry's context: a run carries its own execution
+ * (`Execution`), so two use cases at once never take each other's span, and no context manager
+ * (Zone.js) is needed. A span nothing records (a sampler said no, no provider registered)
+ * answers no ids — so no `traceparent` claims a trace that does not exist.
+ */
+export declare function openTelemetryTracer(tracer: OtelTracer): Tracer;