@sincpro/client-framework 0.2.0 → 0.4.0

package/AGENTS.md

@@ -8,24 +8,30 @@ 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/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          |
+| 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            |
 
 ## Hard rules (the build enforces them — `make doctor`)
 
@@ -33,7 +39,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`.
 
@@ -48,16 +54,28 @@ 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.
@@ -71,7 +89,17 @@ it says what this package is responsible for and what it is not. This file is ho
   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.
+
+- **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,
+  so it lives in `src/common/`. How a value is shown to a person, typed in an input, or kept in
+  SQLite or IndexedDB is the platform's — @sincpro/web-framework's or @sincpro/mobile's.
+- **A decimal never becomes a `number`.** It travels as text and is computed with `Decimal` or
+  `Money` (exact, on `BigInt`); `Number(...)` or `parseFloat` on an amount is the float the
+  backend sends text to avoid. And a day is never a `Date`: a `Date` is an instant.
+- **The in-memory server copies by the wire's rules** (`valuesOf` → `readValues`): what it receives
+  and answers is what a real server would — a `Money` as `{ amount, currency }`, a `Date` as text.
 
 ## Before you hand it back
 

package/MANIFESTO.md

@@ -25,28 +25,37 @@ 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`.
-7. **The generator.** From a service's client contract to each domain's types, client and
+   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
+   text, a money with its currency, a day that is never an instant, bytes tagged, ids as UUID v7 —
+   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.
-8. **Testing.** An in-memory transport, tracer and reporter, so a use case is proven in Node with
+9. **Testing.** An in-memory transport, tracer and reporter, so a use case is proven in Node with
    nothing else.
 
 ## What it is not
@@ -55,7 +64,8 @@ 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. For the
@@ -72,14 +82,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,
@@ -95,8 +107,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
         ▲
@@ -115,8 +127,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,44 +5,252 @@ 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,
 });
-await project.closeIssue.execute(input); // project/closeIssue → project/preview, project/send
+
+// 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)
+});
+
+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
+```
+
+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:
@@ -59,18 +267,85 @@ Nothing is installed or shipped unless it is imported, and without a tracer or a
 case runs the same — nothing traces, nothing reports. In a test, `memoryTracer()` and
 `memoryReporter()` (`@sincpro/client-framework/testing`).
 
+## Values on the wire
+
+The backend writes every message with one set of rules, and every client reads and writes them
+the same — so they live here, not in each platform:
+
+| Value       | Travels as                                 | Here                                             |
+| ----------- | ------------------------------------------ | ------------------------------------------------ |
+| a decimal   | text, every digit: `"10.50"`               | `Decimal` — exact, on `BigInt`; rounds half up   |
+| a money     | `{ "amount": "10.50", "currency": "BOB" }` | `Money` — never adds two currencies              |
+| a day       | `"2026-10-02"`, never converted            | `isDay`, `dayOf(instant, zone)` for «today»      |
+| an instant  | ISO text: `"2026-10-02T14:30:00Z"`         | `wallTimeOf` / `instantOf` on the company's zone |
+| an id       | a UUID v7 as 32 hex                        | `newEntityId`, `isEntityId`, `momentOf`          |
+| bytes       | `{ "$bytes": "<base64>" }`                 | `valuesOf` / `readValues`                        |
+| the context | only what travels: text, numbers, lists    | `plainCodec`, `travelling`                       |
+
+```ts
+import { Money, pack, unpack, valuesOf } from "@sincpro/client-framework";
+
+const line = new Money("19.90", "BOB").times("3"); // 59.70 BOB, exact
+const total = Money.total([line, delivery], "BOB").rounded(); // to the currency's decimals
+valuesOf({ total, at: new Date() }); // { total: { amount, currency }, at: "…Z" }
+const answer = unpack(text, Money); // a typed read when asked for — never imposed
+```
+
+Not restrictive, like the backend: reading keeps every key it finds, a typed read is asked for
+(`rebuilt(values, Money)`), any currency code is read, and an application adds its own decimals
+(`Money.decimals["USDT"] = 6`). What JSON cannot write (`NaN`, a function, a cycle) is refused at
+once, naming where. Showing a value to a person — `Intl.NumberFormat`, a date picker — is each
+platform's, never this package's.
+
 ## Where 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

@@ -6,7 +6,7 @@ import type { Tracer } from "../observability/ports.js";
  *
  *     // a browser (@sincpro/web-framework/telemetry does this), Node, React Native…
  *     const tracer = openTelemetryTracer(provider.getTracer("forge-web"));
- *     const runtime = createRuntime({ tracer });
+ *     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

package/dist/adapters/opentelemetry.js

@@ -5,7 +5,7 @@ import { isSpanContextValid, ROOT_CONTEXT, SpanKind, SpanStatusCode, trace, Trac
  *
  *     // a browser (@sincpro/web-framework/telemetry does this), Node, React Native…
  *     const tracer = openTelemetryTracer(provider.getTracer("forge-web"));
- *     const runtime = createRuntime({ tracer });
+ *     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

package/dist/adapters/sentry.d.ts

@@ -17,11 +17,11 @@ export type ExceptionClient = {
  *
  *     // @sincpro/web-framework/errors builds the browser's client with GlitchTip's DSN
  *     const reporter = sentryReporter(client);
- *     const runtime = createRuntime({ reporter });
+ *     configureProcess({ reporter });
  *
  * Context: it imports nothing — it takes the client the platform made (with its DSN, release
  * and data rules), so it costs no dependency and works on every platform. What is reported is
- * already decided by the runtime (`outcomeOf`: only `failed`); this only says where it happened.
+ * already decided by the process (`outcomeOf`: only `failed`); this only says where it happened.
  * The context goes as a context, not as tags: a tag is indexed and searched, and an execution's
  * values are not the place for that.
  */