@sincpro/client-framework 0.0.0-stage → 0.2.0

package/AGENTS.md

@@ -0,0 +1,85 @@
+# AGENTS.md — working on @sincpro/client-framework
+
+Rules for any agent (or person) changing this package. Read [`MANIFESTO.md`](MANIFESTO.md) first:
+it says what this package is responsible for and what it is not. This file is how to keep it.
+
+## Before you change anything
+
+- **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
+  word or a behaviour, read how the backend does it, not memory.
+- **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          |
+
+## Hard rules (the build enforces them — `make doctor`)
+
+- **Platform-neutral.** No React, no `react-native`, no web-ui, no composer, no @sincpro/mobile;
+  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/`.
+- **Self-imports, no extensions.** Inside `src/`, import `@sincpro/client-framework/<path>` —
+  never a relative path, never `.ts`.
+
+## Conventions
+
+- Code, comments and docs in English: this package is open source.
+- `Context:` blocks at the top of a file are the design record: why it is the way it is. Keep
+  them true.
+- A change ships with a test in `tests/` that fails without it, run in Node.
+- Public means exported from `src/index.ts`. No side effects at import (`sideEffects: false`).
+- A port (an `interface`) only where there are two implementations; a class or a type otherwise.
+
+## 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.
+- **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.
+
+## Before you hand it back
+
+```bash
+make verify-format   # eslint --fix + prettier + typecheck + doctor
+make test
+make build
+```
+
+Never bump `version` in `package.json` — the release pipeline does. Never commit; a person
+does.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SINCPRO S.R.L
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MANIFESTO.md

@@ -0,0 +1,127 @@
+# Manifesto
+
+> **@sincpro/client-framework is the client side of
+> [sincpro_framework](https://github.com/Sincpro-SRL/sincpro_framework), for every platform:
+> where a client's logic lives, how every use case is traced and reported, how an application is
+> made of domains, and how it talks to a service through a client generated from that service's
+> contract. No React, no DOM, no platform.**
+
+This is the founding statement of the repository: what it is responsible for, what it is not,
+how it is composed and where it is going. Every change is measured against it. If a change needs
+something this page does not say, change this page first, and say why.
+
+## Why it exists
+
+Sincpro builds business software with one backend framework and several clients: the web
+([@sincpro/web-framework](https://github.com/Sincpro-SRL/sincpro_web_framework)), mobile
+([@sincpro/mobile](https://github.com/Sincpro-SRL/sincpro_mobile)), server-side renders, scripts,
+tests. Each one was growing the same core on its own — mobile wrote `Feature` and
+`ApplicationService` with interceptors; the web wrote the transport, the entities and the
+generator from the contract — and a use case written for one could not run on the other.
+
+The backend already answers how a use case is written, traced and reported. This package gives
+every client the same answer, once: **a Feature written here runs in a browser, on a phone, in a
+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.
+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.
+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
+   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
+   nothing else.
+
+## What it is not
+
+- **Not a UI.** No React, no components, no hooks: drawing belongs to @sincpro/web-framework on
+  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.
+- **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
+  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.
+
+## What we believe
+
+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.
+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.
+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.
+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
+   without it.
+
+## How it is composed
+
+```text
+@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
+        │   Transport · entity() · client contract · model definitions · ids
+        │   the generator · in-memory doubles for tests
+        ▲
+@sincpro/web-framework      the web: hooks, components on @sincpro/web-ui, the shell on
+                            @sincpro/web-composer, the browser's tracing and error reporting
+@sincpro/mobile             mobile: the React Native shell, SQLite, its queue, its exporter
+```
+
+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.
+
+**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).
+
+## How we decide
+
+This page is the yardstick. A piece that serves nothing here does not go in. A piece this page
+forbids does not go in either. To change what this page says, change the page first — in the
+open, with the reason.
+
+Open source, under the [MIT license](LICENSE).

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# @sincpro/client-framework
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The client side of [sincpro_framework](https://github.com/Sincpro-SRL/sincpro_framework), for
+every platform.** Write a use case once — a `Feature`, or an `ApplicationService` that composes
+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.
+
+> **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.
+
+## A use case, traced and reported by default
+
+```ts
+import {
+  ApplicationService,
+  bindServices,
+  createRuntime,
+  Feature,
+} 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
+  }
+}
+
+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
+  }
+}
+
+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) }),
+});
+await project.closeIssue.execute(input); // project/closeIssue → project/preview, project/send
+```
+
+`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
+```
+
+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.
+
+## Development
+
+Node 26 (`nvm use`).
+
+```bash
+make init            # pre-commit + dependencies
+make test            # vitest, in Node
+make verify-format   # format + lint + doctor; fails if the tree is left dirty (what CI runs)
+make build           # tsc into dist/
+```
+
+`make doctor` enforces what the type checker cannot: the source imports itself, never a relative
+path; no React, no UI, no browser global; Node only inside the generator. Read
+[`AGENTS.md`](AGENTS.md) before changing anything, and [`CONTRIBUTING.md`](CONTRIBUTING.md)
+before opening a pull request.
+
+## CI/CD
+
+Every workflow in `.github/workflows/` delegates to
+[`Sincpro-SRL/.github`](https://github.com/Sincpro-SRL/.github) and only calls `make` targets:
+checks on every pull request and push to `main`, a release draft on `main`, publication to npm
+when a release is published, and notifications. The version is written by the release pipeline,
+never by hand.
+
+## License
+
+[MIT](LICENSE)

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"));
+ *     const runtime = createRuntime({ 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;

package/dist/adapters/opentelemetry.js

@@ -0,0 +1,68 @@
+import { isSpanContextValid, ROOT_CONTEXT, SpanKind, SpanStatusCode, trace, TraceFlags, } from "@opentelemetry/api";
+/**
+ * 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"));
+ *     const runtime = createRuntime({ 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 function openTelemetryTracer(tracer) {
+    return {
+        start(name, options) {
+            const parent = options.parent;
+            const parentContext = parent !== undefined && parent.traceId !== "" && parent.spanId !== ""
+                ? trace.setSpanContext(ROOT_CONTEXT, {
+                    traceId: parent.traceId,
+                    spanId: parent.spanId,
+                    traceFlags: parent.sampled ? TraceFlags.SAMPLED : TraceFlags.NONE,
+                    isRemote: false,
+                })
+                : ROOT_CONTEXT;
+            const span = tracer.startSpan(name, {
+                kind: SpanKind.INTERNAL,
+                ...(options.attributes ? { attributes: options.attributes } : {}),
+            }, parentContext);
+            const own = span.spanContext();
+            const valid = isSpanContextValid(own);
+            const state = own.traceState?.serialize();
+            return {
+                traceId: valid ? own.traceId : "",
+                spanId: valid ? own.spanId : "",
+                sampled: valid && (own.traceFlags & TraceFlags.SAMPLED) === TraceFlags.SAMPLED,
+                ...(state ? { state } : {}),
+                set: (attributes) => void span.setAttributes(attributes),
+                end: (outcome, error) => close(span, outcome, error),
+            };
+        },
+    };
+}
+/**
+ * How the use case ended, said the way OpenTelemetry reads it: `failed` is an error with its
+ * exception; `refused` and `aborted` are expected answers — said in `sincpro.outcome`, never as
+ * an error, the way the backend leaves a refusal out of its error rate.
+ */
+function close(span, outcome, error) {
+    span.setAttribute("sincpro.outcome", outcome);
+    if (outcome === "failed") {
+        if (error instanceof Error)
+            span.recordException(error);
+        span.setStatus({
+            code: SpanStatusCode.ERROR,
+            ...(error instanceof Error ? { message: error.message } : {}),
+        });
+    }
+    else if (outcome === "ok")
+        span.setStatus({ code: SpanStatusCode.OK });
+    span.end();
+}

package/dist/adapters/sentry.d.ts

@@ -0,0 +1,28 @@
+import type { ErrorReporter } from "../observability/ports.js";
+/**
+ * What this adapter needs of a Sentry-compatible client: its `captureException`. A browser's
+ * `BrowserClient`, Node's, React Native's — and GlitchTip, which speaks Sentry's protocol.
+ */
+export type ExceptionClient = {
+    captureException(error: unknown, hint?: {
+        captureContext?: {
+            tags?: Record<string, string>;
+            contexts?: Record<string, Record<string, unknown>>;
+        };
+    }): unknown;
+};
+/**
+ * The `ErrorReporter` port over a Sentry-compatible client: an unexpected error reported with the
+ * use case it happened in, its trace — the id the backend logged too — and its context.
+ *
+ *     // @sincpro/web-framework/errors builds the browser's client with GlitchTip's DSN
+ *     const reporter = sentryReporter(client);
+ *     const runtime = createRuntime({ 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.
+ * 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.
+ */
+export declare function sentryReporter(client: ExceptionClient): ErrorReporter;

package/dist/adapters/sentry.js

@@ -0,0 +1,36 @@
+/**
+ * The `ErrorReporter` port over a Sentry-compatible client: an unexpected error reported with the
+ * use case it happened in, its trace — the id the backend logged too — and its context.
+ *
+ *     // @sincpro/web-framework/errors builds the browser's client with GlitchTip's DSN
+ *     const reporter = sentryReporter(client);
+ *     const runtime = createRuntime({ 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.
+ * 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.
+ */
+export function sentryReporter(client) {
+    return {
+        report(error, about) {
+            client.captureException(error, {
+                captureContext: {
+                    tags: {
+                        "sincpro.use_case": about.useCase,
+                        ...(about.traceId === "" ? {} : { trace_id: about.traceId }),
+                    },
+                    contexts: {
+                        sincpro: {
+                            use_case: about.useCase,
+                            execution_id: about.executionId,
+                            ...(about.traceId === "" ? {} : { trace_id: about.traceId }),
+                            context: about.context,
+                        },
+                    },
+                },
+            });
+        },
+    };
+}

package/dist/client/contract.d.ts

@@ -0,0 +1,34 @@
+import { type Contract, type Meta } from "@sincpro/criteria";
+/**
+ * A bounded context's client contract, as the application keeps it: the snapshot
+ * `sincpro-web generate` writes (`contract.json`), or the document a service serves
+ * (`GET /client-contract/<context>.json`). Only its models are read here.
+ *
+ * Context: the generated entities are keyed `<domain>:<kind>` (`project:issue`) — the key the
+ * workspace refers to them by and the meta store keeps their definitions under —, so the rule
+ * that turns a model's name into its kind lives once, here, and both the generator and the
+ * preload read it.
+ */
+export type ClientContract = {
+    models: Readonly<Record<string, Contract>>;
+    $defs?: Readonly<Record<string, Contract>>;
+};
+/** `ProjectEvent` → `project_event`: the kind in an entity's key. */
+export declare function kindOf(model: string): string;
+/** The key of a model's entity: `entityKeyOf("project", "ProjectEvent")` → `"project:project_event"`. */
+export declare function entityKeyOf(domain: string, model: string): string;
+/**
+ * The version of every entity of `contract`, by its model's name — what `restTransport`
+ * compares each answer with (`snapshot`) to say when the generated code is behind the server.
+ *
+ *     restTransport({ base: "/v1", snapshot: versionsOf(contract), onVersionDrift: warn })
+ */
+export declare function versionsOf(contract: ClientContract): Record<string, string>;
+/**
+ * The definition of every model of `contract`, by its entity's key — what `FrameworkProvider
+ * metas` preloads, so the first screen draws its labels with no request at all. The transport
+ * still reads the live definition and asks again when an answer says another version.
+ *
+ *     <FrameworkProvider transport={transport} metas={metasOf(contract, "project")}>
+ */
+export declare function metasOf(contract: ClientContract, domain: string): Record<string, Meta>;

package/dist/client/contract.js

@@ -0,0 +1,41 @@
+import { metaFromContract } from "@sincpro/criteria";
+/** `ProjectEvent` → `project_event`: the kind in an entity's key. */
+export function kindOf(model) {
+    return model
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1_$2")
+        .toLowerCase();
+}
+/** The key of a model's entity: `entityKeyOf("project", "ProjectEvent")` → `"project:project_event"`. */
+export function entityKeyOf(domain, model) {
+    return `${domain}:${kindOf(model)}`;
+}
+/**
+ * The version of every entity of `contract`, by its model's name — what `restTransport`
+ * compares each answer with (`snapshot`) to say when the generated code is behind the server.
+ *
+ *     restTransport({ base: "/v1", snapshot: versionsOf(contract), onVersionDrift: warn })
+ */
+export function versionsOf(contract) {
+    return Object.fromEntries(Object.entries(contract.models).flatMap(([name, model]) => {
+        const version = model["x-sincpro"]?.version;
+        return model["x-sincpro"]?.identity != null && typeof version === "string"
+            ? [[name, version]]
+            : [];
+    }));
+}
+/**
+ * The definition of every model of `contract`, by its entity's key — what `FrameworkProvider
+ * metas` preloads, so the first screen draws its labels with no request at all. The transport
+ * still reads the live definition and asks again when an answer says another version.
+ *
+ *     <FrameworkProvider transport={transport} metas={metasOf(contract, "project")}>
+ */
+export function metasOf(contract, domain) {
+    // A related model, or a value a record holds, is pointed at by its name (`#/models/Run`).
+    const related = { ...(contract.$defs ?? {}), ...contract.models };
+    return Object.fromEntries(Object.entries(contract.models)
+        // Only an entity has a key of its own; a value it holds is described inside it.
+        .filter(([, model]) => model["x-sincpro"]?.identity != null)
+        .map(([name, model]) => [entityKeyOf(domain, name), metaFromContract(model, related)]));
+}

package/dist/client/discovery.d.ts

@@ -0,0 +1,47 @@
+import { type Meta } from "@sincpro/criteria";
+/**
+ * The discovery document of a bounded context, as far as this reads it: its paths, each
+ * operation with the entities it belongs to, and the published contract of every model.
+ *
+ * Context: sincpro_framework describes a model once — JSON Schema with `x-sincpro`, under the
+ * document's `components.schemas` — and every read answers only the version of it
+ * (`model_version`). So the definition a list, a form and a select are built from is read here,
+ * once, and asked for again only when an answer says another version.
+ */
+export type DiscoveryDocument = {
+    paths?: Readonly<Record<string, Readonly<Record<string, DiscoveryOperation>>>>;
+    components?: {
+        schemas?: Readonly<Record<string, DocumentSchema>>;
+    };
+};
+export type DiscoveryOperation = {
+    "x-sincpro-entities"?: readonly string[];
+    responses?: Readonly<Record<string, {
+        content?: Readonly<Record<string, {
+            schema?: DocumentSchema;
+        }>>;
+    }>>;
+};
+type DocumentSchema = {
+    $ref?: string;
+    items?: DocumentSchema;
+    anyOf?: readonly DocumentSchema[];
+    properties?: Readonly<Record<string, DocumentSchema>>;
+    "x-sincpro"?: {
+        entity?: string;
+        version?: string;
+    };
+};
+/**
+ * The model a request to `path` answers, by the name of its contract in the document: the
+ * entity the operation says it belongs to, else the one its answer holds.
+ *
+ *     modelAt(published, "/v1/projects/p1", "get")   // "Project"
+ */
+export declare function modelAt(published: DiscoveryDocument, path: string, method: string): string | undefined;
+/** The definition of the model named `name`, read from its contract, and its version. */
+export declare function definitionOf(published: DiscoveryDocument, name: string): {
+    meta: Meta;
+    version: string | null;
+} | undefined;
+export {};