@sincpro/client-framework 0.0.0-stage → 0.1.0

package/dist/codegen/rest.js

@@ -0,0 +1,27 @@
+/** What a transport can send: GET is read by `list` (a page) or `one` (a record) only. */
+export const WRITES = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+export function restOf(metamodel, identity, options) {
+    const binding = metamodel.bindings?.rest?.[identity];
+    if (binding === undefined)
+        return undefined;
+    const base = options.base ?? "";
+    const under = base === "" || binding.path === base || binding.path.startsWith(`${base}/`);
+    if (!under)
+        throw new Error(`${identity} is at ${binding.path}, outside the base ${base}`);
+    return {
+        method: binding.method.toUpperCase(),
+        path: binding.path.slice(base.length) || "/",
+        fields: binding.path_fields,
+    };
+}
+/**
+ * The one entity a read belongs to: its only entity, or — when it concerns several — the one
+ * whose model its answer carries. `undefined` when that still leaves more than one.
+ */
+export function ownerOf(metamodel, operation) {
+    if (operation.entities.length === 1)
+        return operation.entities[0];
+    const answer = JSON.stringify(operation.output ?? {});
+    const carried = operation.entities.filter((one) => one in metamodel.models && answer.includes(`"#/models/${one}"`));
+    return carried.length === 1 ? carried[0] : undefined;
+}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The public entry of @sincpro/client-framework: everything a client of a sincpro_framework
+ * service needs, on any platform.
+ *
+ * Context: one entry, not one per area — the package has no side effects at import
+ * (`sideEffects: false`), so an application pays only for what it uses, and a use case, the
+ * client it calls and the entity it reads come from the same place.
+ *
+ *   client/   the seam with a server: the transport and its REST and in-memory implementations,
+ *             entities with typed commands, the service's client contract, client-side ids
+ *   model/    model definitions: written by hand, read from a JSON Schema, kept once known
+ *   services/ Feature and ApplicationService, the runtime they run in, what each run carries
+ *   observability/  the ports a platform plugs: a tracer and an error reporter
+ *
+ * The generator is `@sincpro/client-framework/codegen`, and the in-memory tracer and reporter
+ * `@sincpro/client-framework/testing`: neither is part of what an application runs.
+ */
+export { type ClientContract, entityKeyOf, kindOf, metasOf, versionsOf, } from "./client/contract.js";
+export { bodyFor, type CommandAnswers, type CommandBodies, type CommandRoute, type Entity, entity, type EntityRef, type EntityRoutes, listRoute, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, SCOPE_PARAM, scopeOfRef, startingValuesOf, type SummaryFields, type SummaryPart, TRAIL_PARAM, WITH_PARAM, type WriteRoute, writeRoute, } from "./client/entity.js";
+export { isEntityId, newEntityId } from "./client/ids.js";
+export { type MemoryOptions, type MemoryTable, memoryTransport, } from "./client/memory.js";
+export { type RestOptions, restTransport, urlOf, type VersionDrift, } from "./client/rest.js";
+export { type RetryKeys, retryKeys, unanswered, } from "./client/retry.js";
+export { type CallOptions, type Draft, type Method, type One, readRoute, type SendOptions, type Transport, TransportError, } from "./client/transport.js";
+export { defineMeta, field, type FieldOptions, type MetaSpec, type Words, } from "./model/meta.js";
+export { type MetaStore, metaStore } from "./model/metas.js";
+export { completeMeta, type JsonSchema, metaFromSchema, type SchemaComponents, } from "./model/schema.js";
+export { type Attributes, type ErrorAbout, type ErrorReporter, NO_TRACER, type Outcome, type Span, type Tracer, } from "./observability/ports.js";
+export { BIND, type Bindable, bindable, bindDependency, bindTransport, type Execution, headersOf, } from "./services/execution.js";
+export { ApplicationService, bindServices, Feature, } from "./services/feature.js";
+export { createRuntime, DETACHED, outcomeOf, type Runtime, type RuntimeOptions, } from "./services/runtime.js";

package/dist/index.js

@@ -0,0 +1,31 @@
+/**
+ * The public entry of @sincpro/client-framework: everything a client of a sincpro_framework
+ * service needs, on any platform.
+ *
+ * Context: one entry, not one per area — the package has no side effects at import
+ * (`sideEffects: false`), so an application pays only for what it uses, and a use case, the
+ * client it calls and the entity it reads come from the same place.
+ *
+ *   client/   the seam with a server: the transport and its REST and in-memory implementations,
+ *             entities with typed commands, the service's client contract, client-side ids
+ *   model/    model definitions: written by hand, read from a JSON Schema, kept once known
+ *   services/ Feature and ApplicationService, the runtime they run in, what each run carries
+ *   observability/  the ports a platform plugs: a tracer and an error reporter
+ *
+ * The generator is `@sincpro/client-framework/codegen`, and the in-memory tracer and reporter
+ * `@sincpro/client-framework/testing`: neither is part of what an application runs.
+ */
+export { entityKeyOf, kindOf, metasOf, versionsOf, } from "./client/contract.js";
+export { bodyFor, entity, listRoute, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, SCOPE_PARAM, scopeOfRef, startingValuesOf, TRAIL_PARAM, WITH_PARAM, writeRoute, } from "./client/entity.js";
+export { isEntityId, newEntityId } from "./client/ids.js";
+export { memoryTransport, } from "./client/memory.js";
+export { restTransport, urlOf, } from "./client/rest.js";
+export { retryKeys, unanswered, } from "./client/retry.js";
+export { readRoute, TransportError, } from "./client/transport.js";
+export { defineMeta, field, } from "./model/meta.js";
+export { metaStore } from "./model/metas.js";
+export { completeMeta, metaFromSchema, } from "./model/schema.js";
+export { NO_TRACER, } from "./observability/ports.js";
+export { BIND, bindable, bindDependency, bindTransport, headersOf, } from "./services/execution.js";
+export { ApplicationService, bindServices, Feature, } from "./services/feature.js";
+export { createRuntime, DETACHED, outcomeOf, } from "./services/runtime.js";

package/dist/model/meta.d.ts

@@ -0,0 +1,121 @@
+import type { Expression, FieldMeta, FieldType, Meta, Operator } from "@sincpro/criteria";
+/**
+ * A model definition written by hand, in the shape sincpro_framework publishes.
+ *
+ * Context: everything in this package reads a `Meta` — the labels, the columns, the controls,
+ * the search box. A service built with sincpro_framework sends one with every answer. A domain
+ * that has none (another backend, rows a screen already holds, a prototype
+ * with no server yet) declares it here, and from then on it is indistinguishable: the same
+ * list, the same record, the same criteria. `describeRows` from `@sincpro/criteria` guesses
+ * one from rows; this one is written on purpose, with the words a person reads.
+ *
+ *     const tickets = defineMeta({
+ *       aggregate: "Ticket", identity: "id", display: "title", search: ["title"],
+ *       name: { es: "Tickets" },
+ *       fields: {
+ *         id: field.text({ readonly: true }),
+ *         title: field.text({ label: { es: "Título" }, required: true }),
+ *         stage: field.choice(["new", "done"], { labels: { new: { es: "Nuevo" } } }),
+ *         opened_at: field.datetime({ label: { es: "Abierto" } }),
+ *       },
+ *     });
+ */
+/** A word in several languages, `{default?, es?, en?, …}`; a bare string is the default. */
+export type Words = string | Readonly<Record<string, string>>;
+export type FieldOptions = {
+    label?: Words;
+    help?: Words;
+    required?: boolean;
+    readonly?: boolean;
+    /** Holds no value sometimes. A nullable field is never sortable: keyset paging over it
+     *  loses the rows that hold NULL, which is why the framework refuses to order by one. */
+    nullable?: boolean;
+    default?: unknown;
+    /** Form hints over the record, as sincpro_framework's `Presentation` publishes them. */
+    readonlyWhen?: Expression;
+    requiredWhen?: Expression;
+    visibleWhen?: Expression;
+};
+/** The field builders: one per type the framework publishes. */
+export declare const field: {
+    text: (options?: FieldOptions) => FieldMeta;
+    integer: (options?: FieldOptions) => FieldMeta;
+    /** A decimal travels as text so no digit is lost (`"10.50"`): pass `exact: true`. */
+    number: (options?: FieldOptions & {
+        exact?: boolean;
+    }) => {
+        exact?: boolean;
+        type: FieldType;
+        nullable: boolean;
+        choices?: unknown[];
+        choice_labels?: Record<string, Record<string, string>>;
+        label?: Record<string, string>;
+        help?: Record<string, string>;
+        groupable?: boolean;
+        aggregates?: string[];
+        computed?: boolean;
+        owner?: string | null;
+        readonly?: boolean;
+        required?: boolean;
+        default?: unknown;
+        readonly_when?: Expression | null;
+        required_when?: Expression | null;
+        visible_when?: Expression | null;
+        sortable: boolean;
+        ops: Operator[];
+        widget?: string;
+        affects?: string[];
+        judged_by?: string[];
+        holds?: Expression | null;
+        computes?: import("@sincpro/criteria").Formula | null;
+        navigable?: boolean;
+        total?: string | null;
+        many?: boolean;
+        relation?: string | null;
+        identified_by?: string | null;
+        parent_field?: string | null;
+        related_field?: string | null;
+        definition?: Meta | null;
+        kind: import("@sincpro/criteria").FieldKind;
+    };
+    boolean: (options?: FieldOptions) => FieldMeta;
+    date: (options?: FieldOptions) => FieldMeta;
+    datetime: (options?: FieldOptions) => FieldMeta;
+    tags: (options?: FieldOptions) => FieldMeta;
+    /** An enum: the values in order, and the word each one is read as. */
+    choice: (values: readonly string[], options?: FieldOptions & {
+        labels?: Readonly<Record<string, Words>>;
+    }) => FieldMeta;
+    /** Points at ONE record of another aggregate, by the scalar key this record holds. */
+    many2one: (relation: string, keys: {
+        identifiedBy: string;
+        definition?: Meta;
+    }, options?: FieldOptions) => FieldMeta;
+    /** The records of another aggregate that point back here, by THEIR key. */
+    one2many: (relation: string, keys: {
+        identifiedBy: string;
+        definition?: Meta;
+    }, options?: FieldOptions) => FieldMeta;
+    many2many: (relation: string, keys: {
+        identifiedBy: string;
+        definition?: Meta;
+    }, options?: FieldOptions) => FieldMeta;
+    /** A value object kept inside the record — an address, a specification. No identity. */
+    embedded: (definition: Meta, options?: FieldOptions & {
+        many?: boolean;
+    }) => FieldMeta;
+};
+export type MetaSpec = {
+    aggregate: string;
+    identity: string;
+    fields: Record<string, FieldMeta>;
+    name?: Words;
+    /** The field shown beside the identity: what a select and a many2one show. */
+    display?: string;
+    /** `"-created_at"`, the way a URL writes it. Without it, the identity ascending. */
+    defaultOrder?: string;
+    /** The text fields a typed text is looked for in — the entity's search template. */
+    search?: readonly string[];
+};
+/** A whole definition, from its fields. See the file header. */
+export declare function defineMeta(spec: MetaSpec): Meta;

package/dist/model/meta.js

@@ -0,0 +1,130 @@
+function hints(options) {
+    return {
+        ...(options.readonlyWhen ? { readonly_when: options.readonlyWhen } : {}),
+        ...(options.requiredWhen ? { required_when: options.requiredWhen } : {}),
+        ...(options.visibleWhen ? { visible_when: options.visibleWhen } : {}),
+    };
+}
+/** The comparisons each type takes — the same table sincpro_framework publishes. */
+const OPS = {
+    text: ["=", "!=", "like", "starts with", "in", "not in"],
+    integer: ["=", "!=", ">", ">=", "<", "<=", "between", "in", "not in"],
+    number: ["=", "!=", ">", ">=", "<", "<=", "between", "in", "not in"],
+    date: ["=", "!=", ">", ">=", "<", "<=", "between"],
+    datetime: ["=", "!=", ">", ">=", "<", "<=", "between"],
+    boolean: ["="],
+    "text[]": ["contains", "not contains", "=", "!="],
+};
+function words(value) {
+    if (value === undefined)
+        return undefined;
+    return typeof value === "string" ? { default: value } : { ...value };
+}
+function scalar(type, options = {}) {
+    const nullable = options.nullable ?? false;
+    const ops = [...(OPS[type] ?? [])];
+    if (nullable && type !== "text[]" && type !== "boolean")
+        ops.push("is null");
+    const listed = type === "text[]";
+    return {
+        type,
+        kind: "scalar",
+        nullable,
+        sortable: !nullable && !listed,
+        groupable: !listed,
+        ops,
+        ...(options.label === undefined ? {} : { label: words(options.label) }),
+        ...(options.help === undefined ? {} : { help: words(options.help) }),
+        ...(options.required === undefined ? {} : { required: options.required }),
+        ...(options.readonly === undefined ? {} : { readonly: options.readonly }),
+        ...(options.default === undefined ? {} : { default: options.default }),
+        ...hints(options),
+    };
+}
+function relational(type, relation, keys, options = {}) {
+    return {
+        type,
+        kind: "relation",
+        nullable: options.nullable ?? type === "many2one",
+        sortable: false,
+        ops: [],
+        many: type !== "many2one",
+        relation,
+        identified_by: keys.identifiedBy,
+        ...(keys.definition === undefined ? {} : { definition: keys.definition }),
+        ...(options.label === undefined ? {} : { label: words(options.label) }),
+        ...(options.help === undefined ? {} : { help: words(options.help) }),
+        ...(options.readonly === undefined ? {} : { readonly: options.readonly }),
+    };
+}
+/** The field builders: one per type the framework publishes. */
+export const field = {
+    text: (options) => scalar("text", options),
+    integer: (options) => scalar("integer", options),
+    /** A decimal travels as text so no digit is lost (`"10.50"`): pass `exact: true`. */
+    number: (options) => ({
+        ...scalar("number", options),
+        ...(options?.exact ? { exact: true } : {}),
+    }),
+    boolean: (options) => scalar("boolean", options),
+    date: (options) => scalar("date", options),
+    datetime: (options) => scalar("datetime", options),
+    tags: (options) => scalar("text[]", options),
+    /** An enum: the values in order, and the word each one is read as. */
+    choice: (values, options = {}) => ({
+        ...scalar("text", options),
+        ops: ["=", "!=", "in", "not in", ...(options.nullable ? ["is null"] : [])],
+        choices: [...values],
+        ...(options.labels === undefined
+            ? {}
+            : {
+                choice_labels: Object.fromEntries(Object.entries(options.labels).map(([value, said]) => [value, words(said) ?? {}])),
+            }),
+    }),
+    /** Points at ONE record of another aggregate, by the scalar key this record holds. */
+    many2one: (relation, keys, options) => relational("many2one", relation, keys, options),
+    /** The records of another aggregate that point back here, by THEIR key. */
+    one2many: (relation, keys, options) => relational("one2many", relation, keys, options),
+    many2many: (relation, keys, options) => relational("many2many", relation, keys, options),
+    /** A value object kept inside the record — an address, a specification. No identity. */
+    embedded: (definition, options = {}) => ({
+        type: "embedded",
+        kind: "embedded",
+        nullable: options.nullable ?? false,
+        sortable: false,
+        ops: [],
+        definition,
+        ...(options.many ? { many: true } : {}),
+        ...(options.label === undefined ? {} : { label: words(options.label) }),
+    }),
+};
+/** The template a typed text fills: `like` over each field, any of them matching. */
+function searchTemplate(fields) {
+    if (fields.length === 0)
+        return null;
+    const like = (name) => ({
+        field: name,
+        operator: "like",
+        value: { $: "param", name: "text" },
+    });
+    const [only] = fields;
+    return {
+        selection: fields.length === 1 && only !== undefined ? like(only) : { any: fields.map(like) },
+    };
+}
+/** A whole definition, from its fields. See the file header. */
+export function defineMeta(spec) {
+    const missing = [spec.identity, spec.display, ...(spec.search ?? [])].filter((name) => name !== undefined && name !== "" && !(name in spec.fields));
+    if (missing.length > 0)
+        throw new Error(`${spec.aggregate}: ${missing.join(", ")} named but not declared`);
+    return {
+        aggregate: spec.aggregate,
+        identity: spec.identity,
+        default_order: spec.defaultOrder ?? spec.identity,
+        fields: spec.fields,
+        get_id: spec.identity,
+        ...(spec.name === undefined ? {} : { name: words(spec.name) }),
+        ...(spec.display === undefined ? {} : { display: spec.display }),
+        search: searchTemplate(spec.search ?? []),
+    };
+}

package/dist/model/metas.d.ts

@@ -0,0 +1,17 @@
+import type { Meta } from "@sincpro/criteria";
+/**
+ * The model definitions already known, by entity key (`"billing:invoice"`).
+ *
+ * Context: sincpro_framework publishes each model once, in the discovery document the
+ * transport reads (`core/discovery`); an answer carries only its version. This keeps the
+ * definitions ACROSS readings, so the second list of the same entity, the record opened from it
+ * and the select that points at it draw their labels before the rows arrive.
+ *
+ * Seeded, it is the preload: definitions written at build time (a snapshot of the server's,
+ * or `defineMeta`) reach the first screen with no request at all.
+ */
+export type MetaStore = {
+    get(key: string): Meta | undefined;
+    set(key: string, meta: Meta): void;
+};
+export declare function metaStore(seed?: Readonly<Record<string, Meta>>): MetaStore;

package/dist/model/metas.js

@@ -0,0 +1,7 @@
+export function metaStore(seed = {}) {
+    const known = new Map(Object.entries(seed));
+    return {
+        get: (key) => known.get(key),
+        set: (key, meta) => void known.set(key, meta),
+    };
+}

package/dist/model/schema.d.ts

@@ -0,0 +1,39 @@
+import type { Meta } from "@sincpro/criteria";
+/**
+ * A model definition read from a JSON Schema — what an OpenAPI document holds.
+ *
+ * Context: a model a READ answers is published by sincpro_framework as its contract — JSON
+ * Schema with `x-sincpro` — and read by the transport (`metaFromContract`, `core/discovery`).
+ * What has no `x-sincpro` is a plain JSON Schema: a COMMAND's body, a value object it carries.
+ *
+ * So this reads such a component schema into a `Meta` — the form of a Command, a value object —
+ * and `completeMeta` fills, from it, what a definition left `unknown`.
+ *
+ *     const spec = metaFromSchema("ProjectSpecification", doc.components.schemas);
+ *     const fixed = completeMeta(project.fields.specification.definition, spec);
+ */
+export type JsonSchema = {
+    type?: string | string[];
+    format?: string;
+    enum?: readonly unknown[];
+    items?: JsonSchema;
+    $ref?: string;
+    anyOf?: readonly JsonSchema[];
+    oneOf?: readonly JsonSchema[];
+    properties?: Readonly<Record<string, JsonSchema>>;
+    required?: readonly string[];
+    title?: string;
+    description?: string;
+    default?: unknown;
+};
+export type SchemaComponents = Readonly<Record<string, JsonSchema>>;
+/** The definition a component schema describes. `identity` empty: a value object has none. */
+export declare function metaFromSchema(name: string, components: SchemaComponents, options?: {
+    identity?: string;
+}): Meta;
+/**
+ * The server's definition, with what it left `unknown` taken from the schema — recursively
+ * into value objects. What the server DID say always wins: its labels, its operators, its
+ * hints. A field the schema does not know is left as the server sent it.
+ */
+export declare function completeMeta(meta: Meta, schema: Meta): Meta;

package/dist/model/schema.js

@@ -0,0 +1,128 @@
+import { field } from "./meta.js";
+const UNKNOWN = {
+    type: "unknown",
+    kind: "scalar",
+    nullable: true,
+    sortable: false,
+    ops: [],
+};
+function nameOfRef(ref) {
+    return ref.slice(ref.lastIndexOf("/") + 1);
+}
+/** `anyOf: [X, {type: "null"}]` is `X`, nullable — how pydantic writes `X | None`. */
+function unwrap(schema) {
+    const options = schema.anyOf ?? schema.oneOf;
+    if (options === undefined)
+        return { schema, nullable: false };
+    const real = options.filter((one) => one.type !== "null");
+    const [only] = real;
+    return real.length === 1 && only !== undefined
+        ? { schema: { ...only, ...pick(schema) }, nullable: real.length < options.length }
+        : { schema, nullable: real.length < options.length };
+}
+/** The words of the outer schema win over the ones of what it wraps. */
+function pick(schema) {
+    return {
+        ...(schema.title === undefined ? {} : { title: schema.title }),
+        ...(schema.description === undefined ? {} : { description: schema.description }),
+        ...(schema.default === undefined ? {} : { default: schema.default }),
+    };
+}
+function fieldFrom(raw, required, components, seen) {
+    const { schema: unwrapped, nullable } = unwrap(raw);
+    const target = unwrapped.$ref !== undefined
+        ? { ...components[nameOfRef(unwrapped.$ref)], ...pick(unwrapped) }
+        : unwrapped;
+    const options = {
+        ...(target.title === undefined ? {} : { label: target.title }),
+        ...(target.description === undefined ? {} : { help: target.description }),
+        ...(target.default === undefined ? {} : { default: target.default }),
+        ...(nullable ? { nullable } : {}),
+        required: required && target.default === undefined && !nullable,
+    };
+    if (unwrapped.$ref !== undefined) {
+        const name = nameOfRef(unwrapped.$ref);
+        if (components[name] === undefined || seen.has(name))
+            return UNKNOWN;
+        if (target.properties === undefined)
+            return target.enum ? field.choice(target.enum.map(String), options) : UNKNOWN;
+        return field.embedded(metaOf(name, target, components, new Set([...seen, name])), options);
+    }
+    if (target.enum)
+        return field.choice(target.enum.map(String), options);
+    const type = Array.isArray(target.type)
+        ? target.type.find((t) => t !== "null")
+        : target.type;
+    switch (type) {
+        case "string":
+            if (target.format === "date")
+                return field.date(options);
+            if (target.format === "date-time")
+                return field.datetime(options);
+            return field.text(options);
+        case "integer":
+            return field.integer(options);
+        case "number":
+            return field.number(options);
+        case "boolean":
+            return field.boolean(options);
+        case "array": {
+            const item = target.items === undefined ? undefined : unwrap(target.items).schema;
+            if (item?.$ref !== undefined) {
+                const inner = fieldFrom(item, false, components, seen);
+                return inner.kind === "embedded" && inner.definition
+                    ? field.embedded(inner.definition, { ...options, many: true })
+                    : field.tags(options);
+            }
+            return item?.type === "string" || item?.enum ? field.tags(options) : UNKNOWN;
+        }
+        default:
+            return UNKNOWN;
+    }
+}
+function metaOf(name, schema, components, seen) {
+    const required = new Set(schema.required ?? []);
+    const fields = Object.fromEntries(Object.entries(schema.properties ?? {}).map(([key, property]) => [
+        key,
+        fieldFrom(property, required.has(key), components, seen),
+    ]));
+    return {
+        aggregate: name,
+        identity: "",
+        default_order: "",
+        fields,
+        ...(schema.title === undefined ? {} : { name: { default: schema.title } }),
+    };
+}
+/** The definition a component schema describes. `identity` empty: a value object has none. */
+export function metaFromSchema(name, components, options = {}) {
+    const schema = components[name];
+    if (schema === undefined)
+        throw new Error(`no schema named ${name}`);
+    const meta = metaOf(name, schema, components, new Set([name]));
+    return options.identity
+        ? { ...meta, identity: options.identity, get_id: options.identity }
+        : meta;
+}
+/**
+ * The server's definition, with what it left `unknown` taken from the schema — recursively
+ * into value objects. What the server DID say always wins: its labels, its operators, its
+ * hints. A field the schema does not know is left as the server sent it.
+ */
+export function completeMeta(meta, schema) {
+    const fields = Object.fromEntries(Object.entries(meta.fields).map(([name, own]) => {
+        const known = schema.fields[name];
+        if (known === undefined)
+            return [name, own];
+        if (own.type === "unknown")
+            return [name, { ...known, ...labelsOf(own) }];
+        if (own.kind === "embedded" && own.definition && known.definition)
+            return [name, { ...own, definition: completeMeta(own.definition, known.definition) }];
+        return [name, own];
+    }));
+    return { ...meta, fields };
+}
+/** A label the server declared is kept over the schema's generated title. */
+function labelsOf(own) {
+    return own.label && Object.keys(own.label).length > 0 ? { label: own.label } : {};
+}

package/dist/observability/ports.d.ts

@@ -0,0 +1,64 @@
+/**
+ * What a platform plugs so every use case is traced and every unexpected error reported.
+ *
+ * Context: sincpro_framework opens one span per use case and reports what nobody expected; a
+ * client has to do the same, and continue the backend's trace. The vendor — OpenTelemetry in a
+ * browser, a queue on a phone, GlitchTip, memory in a test — is the platform's, so this package
+ * defines the contract and calls it, and bundles none. Two implementations at least (a
+ * platform's and a test's) are why these are ports.
+ *
+ * Nothing here may break a use case: a tracer or a reporter that throws is ignored, and the use
+ * case answers as it would have.
+ */
+/** What is said about a span: plain values only, the way OpenTelemetry takes them. */
+export type Attributes = Readonly<Record<string, string | number | boolean>>;
+/**
+ * How a use case ended.
+ *
+ * - `ok`: it answered.
+ * - `refused`: the server said no and explained why — a validation, a conflict, a permission.
+ *   Expected; never reported.
+ * - `aborted`: whoever asked stopped waiting (a screen that closed). Never reported.
+ * - `failed`: anything else — a bug, a server that broke, a server nobody could reach. Reported.
+ */
+export type Outcome = "ok" | "refused" | "aborted" | "failed";
+/** One span: a use case, open while it runs. */
+export interface Span {
+    /** 32 hex — the id the server continues and a person quotes as a support code. Empty when
+     *  nothing traces. */
+    readonly traceId: string;
+    /** 16 hex. Empty when nothing traces. */
+    readonly spanId: string;
+    /** Whether this trace is kept: the server follows the same decision. */
+    readonly sampled: boolean;
+    /** Vendor state that travels beside the trace (`tracestate`), when there is any. */
+    readonly state?: string;
+    /** Says more about the use case while it runs. */
+    set(attributes: Attributes): void;
+    /** Closes it, once. `error` is what it failed or was refused with. */
+    end(outcome: Outcome, error?: unknown): void;
+}
+/** Opens spans. One per platform; `NO_TRACER` when nothing traces. */
+export interface Tracer {
+    start(name: string, options: {
+        parent?: Span;
+        attributes?: Attributes;
+    }): Span;
+}
+/** What a report says about where the error happened. */
+export type ErrorAbout = {
+    /** `<domain>/<Feature>`, the span's name. */
+    useCase: string;
+    /** The trace the error belongs to — the same id the server logged, when it got that far. */
+    traceId: string;
+    /** The execution's own id. */
+    executionId: string;
+    /** What the use case ran with (`Runtime` `context`). */
+    context: Readonly<Record<string, unknown>>;
+};
+/** Reports what nobody expected. One per platform; none when nothing reports. */
+export interface ErrorReporter {
+    report(error: unknown, about: ErrorAbout): void;
+}
+/** Traces nothing: what a use case runs with until a platform plugs a tracer. */
+export declare const NO_TRACER: Tracer;

package/dist/observability/ports.js

@@ -0,0 +1,21 @@
+/**
+ * What a platform plugs so every use case is traced and every unexpected error reported.
+ *
+ * Context: sincpro_framework opens one span per use case and reports what nobody expected; a
+ * client has to do the same, and continue the backend's trace. The vendor — OpenTelemetry in a
+ * browser, a queue on a phone, GlitchTip, memory in a test — is the platform's, so this package
+ * defines the contract and calls it, and bundles none. Two implementations at least (a
+ * platform's and a test's) are why these are ports.
+ *
+ * Nothing here may break a use case: a tracer or a reporter that throws is ignored, and the use
+ * case answers as it would have.
+ */
+const EMPTY_SPAN = {
+    traceId: "",
+    spanId: "",
+    sampled: false,
+    set: () => undefined,
+    end: () => undefined,
+};
+/** Traces nothing: what a use case runs with until a platform plugs a tracer. */
+export const NO_TRACER = { start: () => EMPTY_SPAN };