@sincpro/client-framework 0.6.0 → 1.0.0

package/dist/core/services/error-handlers.js

@@ -0,0 +1,21 @@
+/**
+ * The answer of a chain of error handlers to `error`, or what its last handler threw.
+ *
+ *     await handled([toEmpty, logAndRethrow], new IssueNotFound())   ->  toEmpty's answer
+ *
+ * 1. Each handler, first-registered-first, receives what the one before it threw.
+ * Final: the first answer; when every handler threw, the last thrown — the original error when
+ *    there is no handler at all.
+ */
+export async function handled(handlers, error) {
+    let current = error;
+    for (const handler of handlers) {
+        try {
+            return await handler(current);
+        }
+        catch (thrown) {
+            current = thrown;
+        }
+    }
+    throw current;
+}

package/dist/core/services/execution.d.ts

@@ -0,0 +1,35 @@
+import type { Execution } from "../../context/domain/execution.js";
+import type { ContextValues } from "../../context/domain/store.js";
+import type { ErrorHandler } from "../domain/errors.js";
+export interface RuntimeService {
+    execute(command: object): unknown;
+}
+type Layer = "feature" | "application_service";
+export interface ExecutionOptions {
+    readonly boundedContext: string;
+    readonly name: string;
+    readonly layer: Layer;
+    readonly dependencies: ReadonlyMap<string, unknown>;
+    readonly context: () => ContextValues;
+    readonly parent?: Execution;
+    readonly featureBus: (execution: Execution) => object;
+    /** The bounded context's expected errors: they end `refused`, never reported. */
+    readonly expected: (error: unknown) => boolean;
+    /** The bounded context's handlers for this layer: what answers a failure instead of raising it. */
+    readonly handlers: readonly ErrorHandler[];
+}
+/**
+ * One pipeline for every registered Feature and ApplicationService.
+ *
+ * 1. A span `<bounded context>/<serviceName>`, a child of the parent run when there is one, and
+ *    the execution every dependency, `this.logger` and child Feature are bound to.
+ * 2. The service runs, seeing that execution through its own view of the instance.
+ * 3. A failure is observed where it happened: its outcome (expected by the bounded context →
+ *    `refused`, else the process's `outcomeOf`), the span closed with it, its log line and —
+ *    when `failed`, and only once per error along the run — its report.
+ * 4. Then the layer's error handlers answer it, in order; with none, or when the last throws,
+ *    the error reaches the caller.
+ * Final: the service's answer, or its handlers'.
+ */
+export declare function executeService(target: RuntimeService, command: object, options: ExecutionOptions): Promise<unknown>;
+export {};

package/dist/core/services/execution.js

@@ -0,0 +1,137 @@
+import { newEntityId } from "../../common/ids.js";
+import { bindDependency } from "./binding.js";
+import { handled } from "./error-handlers.js";
+import { NO_TRACER, } from "../../observability/domain/tracing.js";
+import { observabilityNow } from "../../observability/infrastructure/registry.js";
+import { executionLogger, logExecution, logHandled, } from "../../observability/services/logging.js";
+import { firstReport } from "../../observability/services/reporting.js";
+const REPORTED_BY_EXECUTION = new WeakMap();
+/** Observability adapters are best-effort; their failures must not replace a business result. */
+function observe(work, fallback) {
+    try {
+        return work();
+    }
+    catch {
+        return fallback;
+    }
+}
+function serviceView(target, options, execution) {
+    const dependencies = new Map();
+    const logger = executionLogger(options.layer, execution);
+    let features;
+    return new Proxy(target, {
+        get(held, property, receiver) {
+            if (property === "context")
+                return execution.context;
+            if (property === "span")
+                return execution.span;
+            if (property === "logger")
+                return logger;
+            if (property === "featureBus" && options.layer === "application_service") {
+                return (features ??= options.featureBus(execution));
+            }
+            if (typeof property === "string" && options.dependencies.has(property)) {
+                if (!dependencies.has(property)) {
+                    dependencies.set(property, bindDependency(options.dependencies.get(property), execution));
+                }
+                return dependencies.get(property);
+            }
+            if (Reflect.has(held, property))
+                return Reflect.get(held, property, receiver);
+            if (typeof property === "string") {
+                throw new Error(`${options.boundedContext}: dependency or member is not registered: ${property}`);
+            }
+            return undefined;
+        },
+        set(held, property, value) {
+            if (property === "context" ||
+                property === "span" ||
+                property === "logger" ||
+                property === "featureBus" ||
+                (typeof property === "string" && options.dependencies.has(property))) {
+                throw new Error(`Execution dependencies and context are read-only: ${String(property)}`);
+            }
+            return Reflect.set(held, property, value);
+        },
+    });
+}
+/**
+ * One pipeline for every registered Feature and ApplicationService.
+ *
+ * 1. A span `<bounded context>/<serviceName>`, a child of the parent run when there is one, and
+ *    the execution every dependency, `this.logger` and child Feature are bound to.
+ * 2. The service runs, seeing that execution through its own view of the instance.
+ * 3. A failure is observed where it happened: its outcome (expected by the bounded context →
+ *    `refused`, else the process's `outcomeOf`), the span closed with it, its log line and —
+ *    when `failed`, and only once per error along the run — its report.
+ * 4. Then the layer's error handlers answer it, in order; with none, or when the last throws,
+ *    the error reaches the caller.
+ * Final: the service's answer, or its handlers'.
+ */
+export async function executeService(target, command, options) {
+    const ports = observabilityNow();
+    const startedAt = Date.now();
+    const useCase = `${options.boundedContext}.${options.name}`;
+    const context = options.parent?.context ?? options.context();
+    const id = newEntityId();
+    const attributes = {
+        "sincpro.use_case": useCase,
+        "sincpro.layer": options.layer,
+        "sincpro.context": options.boundedContext,
+        "sincpro.execution_id": id,
+    };
+    const span = observe(() => ports.tracer.start(`${options.boundedContext}/${options.name}`, {
+        ...(options.parent ? { parent: options.parent.span } : {}),
+        attributes,
+    }), NO_TRACER.start(useCase, {}));
+    const execution = {
+        id,
+        useCase,
+        boundedContext: options.boundedContext,
+        parent: options.parent,
+        span,
+        context,
+    };
+    const reported = options.parent
+        ? (REPORTED_BY_EXECUTION.get(options.parent) ?? new Set())
+        : new Set();
+    REPORTED_BY_EXECUTION.set(execution, reported);
+    logExecution(options.layer, execution);
+    const finish = (error) => {
+        const outcome = error
+            ? observe(() => (options.expected(error.value) ? "refused" : ports.outcomeOf(error.value)), "failed")
+            : "ok";
+        observe(() => span.end(outcome, error?.value), undefined);
+        logExecution(options.layer, execution, {
+            outcome,
+            durationMs: Math.max(0, Date.now() - startedAt),
+        });
+        if (outcome === "failed" && error && ports.reporter && !reported.has(error.value)) {
+            reported.add(error.value);
+            // Mark for reportError outside the call; a different root may report the same Error.
+            firstReport(error.value);
+            observe(() => ports.reporter?.report(error.value, {
+                useCase,
+                traceId: span.traceId,
+                executionId: id,
+                context,
+            }), undefined);
+        }
+    };
+    let answer;
+    try {
+        answer = await Reflect.apply(target.execute, serviceView(target, options, execution), [
+            command,
+        ]);
+    }
+    catch (error) {
+        finish({ value: error });
+        if (options.handlers.length === 0)
+            throw error;
+        const recovered = await handled(options.handlers, error);
+        logHandled(options.layer, { execution });
+        return recovered;
+    }
+    finish();
+    return answer;
+}

package/dist/index.d.ts

@@ -3,45 +3,23 @@
  * 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.
+ * (`sideEffects: false`), so an application pays only for what it uses. Each module is laid out
+ * as sincpro_framework's are — `domain/` (ports and rules), `adapters/` (their implementations),
+ * `services/`, `infrastructure/`, `entrypoint/` — and says what it offers in its own `index.ts`:
  *
- *   common/   the values of the wire, as the backend writes them: ids, a day and an instant,
- *             `Decimal`, `Money`, a to-many as a page of its records (`EntityCollection`), and
- *             how any value is written and read (`valuesOf`, `rebuilt`)
- *   client/   the seam with a server: the transport and its REST and in-memory implementations,
- *             entities with typed commands, the service's client contract
- *   model/    model definitions: written by hand, read from a JSON Schema, kept once known
- *   services/ the bounded context (`UseBoundedContext`), its `Feature` and `ApplicationService`,
- *             the process they run in (`configureProcess`), what each run carries
- *   context/  the context: one door (`Context`) over the store each platform plugs
- *   observability/  the ports a platform plugs: a tracer and an error reporter
+ *   common/         the values of the wire, as the backend writes them
+ *   context/        the context's levels, where they live, what travels, the execution
+ *   observability/  tracing, error reporting and logging: ports, console, loggers
+ *   client/         the seam with a server: transports, entities, the client contract
+ *   model/          model definitions
+ *   core/           Commands, Features, ApplicationServices, BoundedContext, the process
  *
- * The generator is `@sincpro/client-framework/codegen`, and the in-memory tracer and reporter
+ * The generator is `@sincpro/client-framework/codegen`, and the in-memory observability
  * `@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, type ExportFormat, exportRoute, 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 { 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 Decoder, type Download, downloadRoute, type Draft, type Method, type One, readRoute, type SendOptions, type Transport, TransportError, } from "./client/transport.js";
-export { collectionOf, type EntityCollection, type HeldCollection, isCollection, isPartial, relatedCriteria, type RelationKeys, totalOf, } from "./common/collection.js";
-export { Decimal, type DecimalLike } from "./common/decimal.js";
-export { isEntityId, momentOf, newEntityId } from "./common/ids.js";
-export { Money } from "./common/money.js";
-export { BYTES, type JsonValue, pack, readValues, type Rebuild, rebuilt, unpack, valuesOf, } from "./common/serialization.js";
-export { dayOf, installTimeZone, instantOf, isDay, timeZoneNow, wallTimeOf, } from "./common/time.js";
-export { CONTEXT_HEADER, type ContextCodec, plainCodec, travelling, travels, } from "./context/codec.js";
-export { type Context } from "./context/context.js";
-export { type ContextStore, type ContextValues, memoryContexts, } from "./context/store.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 { type BoundedContext, UseBoundedContext, } from "./services/bounded-context.js";
-export { BIND, type Bindable, bindable, bindDependency, bindTransport, type Execution, headersOf, } from "./services/execution.js";
-export { ApplicationService, Feature, type ServiceClasses, type ServiceMethods, type Services, } from "./services/feature.js";
-export { configureProcess, outcomeOf, processContext, type ProcessOptions, } from "./services/process.js";
-export { reportError } from "./services/report.js";
-export { screensTransport } from "./services/screens.js";
+export * from "./client/index.js";
+export * from "./common/index.js";
+export * from "./context/index.js";
+export * from "./core/index.js";
+export * from "./model/index.js";
+export * from "./observability/index.js";

package/dist/index.js

@@ -3,45 +3,23 @@
  * 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.
+ * (`sideEffects: false`), so an application pays only for what it uses. Each module is laid out
+ * as sincpro_framework's are — `domain/` (ports and rules), `adapters/` (their implementations),
+ * `services/`, `infrastructure/`, `entrypoint/` — and says what it offers in its own `index.ts`:
  *
- *   common/   the values of the wire, as the backend writes them: ids, a day and an instant,
- *             `Decimal`, `Money`, a to-many as a page of its records (`EntityCollection`), and
- *             how any value is written and read (`valuesOf`, `rebuilt`)
- *   client/   the seam with a server: the transport and its REST and in-memory implementations,
- *             entities with typed commands, the service's client contract
- *   model/    model definitions: written by hand, read from a JSON Schema, kept once known
- *   services/ the bounded context (`UseBoundedContext`), its `Feature` and `ApplicationService`,
- *             the process they run in (`configureProcess`), what each run carries
- *   context/  the context: one door (`Context`) over the store each platform plugs
- *   observability/  the ports a platform plugs: a tracer and an error reporter
+ *   common/         the values of the wire, as the backend writes them
+ *   context/        the context's levels, where they live, what travels, the execution
+ *   observability/  tracing, error reporting and logging: ports, console, loggers
+ *   client/         the seam with a server: transports, entities, the client contract
+ *   model/          model definitions
+ *   core/           Commands, Features, ApplicationServices, BoundedContext, the process
  *
- * The generator is `@sincpro/client-framework/codegen`, and the in-memory tracer and reporter
+ * The generator is `@sincpro/client-framework/codegen`, and the in-memory observability
  * `@sincpro/client-framework/testing`: neither is part of what an application runs.
  */
-export { entityKeyOf, kindOf, metasOf, versionsOf, } from "./client/contract.js";
-export { bodyFor, entity, exportRoute, listRoute, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, SCOPE_PARAM, scopeOfRef, startingValuesOf, TRAIL_PARAM, WITH_PARAM, writeRoute, } from "./client/entity.js";
-export { memoryTransport, } from "./client/memory.js";
-export { restTransport, urlOf, } from "./client/rest.js";
-export { retryKeys, unanswered, } from "./client/retry.js";
-export { downloadRoute, readRoute, TransportError, } from "./client/transport.js";
-export { collectionOf, isCollection, isPartial, relatedCriteria, totalOf, } from "./common/collection.js";
-export { Decimal } from "./common/decimal.js";
-export { isEntityId, momentOf, newEntityId } from "./common/ids.js";
-export { Money } from "./common/money.js";
-export { BYTES, pack, readValues, rebuilt, unpack, valuesOf, } from "./common/serialization.js";
-export { dayOf, installTimeZone, instantOf, isDay, timeZoneNow, wallTimeOf, } from "./common/time.js";
-export { CONTEXT_HEADER, plainCodec, travelling, travels, } from "./context/codec.js";
-export {} from "./context/context.js";
-export { memoryContexts, } from "./context/store.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 { UseBoundedContext, } from "./services/bounded-context.js";
-export { BIND, bindable, bindDependency, bindTransport, headersOf, } from "./services/execution.js";
-export { ApplicationService, Feature, } from "./services/feature.js";
-export { configureProcess, outcomeOf, processContext, } from "./services/process.js";
-export { reportError } from "./services/report.js";
-export { screensTransport } from "./services/screens.js";
+export * from "./client/index.js";
+export * from "./common/index.js";
+export * from "./context/index.js";
+export * from "./core/index.js";
+export * from "./model/index.js";
+export * from "./observability/index.js";

package/dist/model/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Model definitions: written by hand (`defineMeta`), read from a JSON Schema, kept once known.
+ *
+ *   domain/          `defineMeta`, `field`
+ *   services/        `metaFromSchema`, `completeMeta`
+ *   infrastructure/  `metaStore`: the definitions already known
+ */
+export { defineMeta, field, type FieldOptions, type MetaSpec, type Words, } from "./domain/meta.js";
+export { type MetaStore, metaStore, } from "./infrastructure/metas.js";
+export { completeMeta, type JsonSchema, metaFromSchema, type SchemaComponents, } from "./services/schema.js";

package/dist/model/index.js

@@ -0,0 +1,10 @@
+/**
+ * Model definitions: written by hand (`defineMeta`), read from a JSON Schema, kept once known.
+ *
+ *   domain/          `defineMeta`, `field`
+ *   services/        `metaFromSchema`, `completeMeta`
+ *   infrastructure/  `metaStore`: the definitions already known
+ */
+export { defineMeta, field, } from "./domain/meta.js";
+export { metaStore, } from "./infrastructure/metas.js";
+export { completeMeta, metaFromSchema, } from "./services/schema.js";

package/dist/model/{metas.d.ts → infrastructure/metas.d.ts}

@@ -3,7 +3,7 @@ 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
+ * transport reads (`client/services/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.
  *

package/dist/model/{schema.d.ts → services/schema.d.ts}

@@ -3,7 +3,7 @@ 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`).
+ * Schema with `x-sincpro` — and read by the transport (`metaFromContract`, `client/services/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 —

package/dist/model/{schema.js → services/schema.js}

@@ -1,4 +1,4 @@
-import { field } from "./meta.js";
+import { field } from "../domain/meta.js";
 const UNKNOWN = {
     type: "unknown",
     kind: "scalar",

package/dist/observability/adapters/console.d.ts

@@ -0,0 +1,12 @@
+import type { Logger, LogLayer, LogLevel } from "../domain/logging.js";
+export type ConsoleLoggerOptions = {
+    mode: "development" | "production";
+    /** Development INFO/DEBUG threshold. WARN/ERROR are never hidden by layer/level masks. */
+    level?: LogLevel;
+    layers?: Partial<Record<LogLayer, boolean>>;
+};
+/**
+ * Built-in console engine: silent in production, configurable
+ * development layers, and WARN/ERROR preserved. Other sinks are filtered independently.
+ */
+export declare function consoleLogger(options: ConsoleLoggerOptions): Logger;

package/dist/observability/adapters/console.js

@@ -0,0 +1,35 @@
+const RANK = { debug: 0, info: 1, warn: 2, error: 3 };
+/**
+ * Built-in console engine: silent in production, configurable
+ * development layers, and WARN/ERROR preserved. Other sinks are filtered independently.
+ */
+export function consoleLogger(options) {
+    const mode = options.mode;
+    if (mode !== "development" && mode !== "production") {
+        throw new TypeError("Console logger mode must be development or production");
+    }
+    const level = options.level ?? "debug";
+    if (!Object.hasOwn(RANK, level)) {
+        throw new TypeError("Console logger level must be debug, info, warn or error");
+    }
+    const layers = { ...options.layers };
+    return {
+        log(record) {
+            if (mode === "production")
+                return;
+            if (record.level !== "warn" && record.level !== "error") {
+                if (layers[record.layer] === false || RANK[record.level] < RANK[level])
+                    return;
+            }
+            const prefix = `${record.timestamp} [${record.layer}] ${record.level.toUpperCase()}`;
+            const method = record.level === "debug"
+                ? console.debug
+                : record.level === "warn"
+                    ? console.warn
+                    : record.level === "error"
+                        ? console.error
+                        : console.log;
+            method.call(console, prefix, record.message, record);
+        },
+    };
+}

package/dist/observability/adapters/memory.d.ts

@@ -0,0 +1,41 @@
+import type { ErrorAbout, ErrorReporter } from "../domain/errors.js";
+import type { Logger, LogRecord } from "../domain/logging.js";
+import type { Outcome, Tracer } from "../domain/tracing.js";
+/**
+ * Observability adapters that keep what they were told, so a test reads it back.
+ *
+ *     const tracer = memoryTracer();
+ *     configureProcess({ tracer });
+ *     await project.execute(new CommandCloseIssue("issue-1"));
+ *     tracer.spans.map((one) => one.name);   // ["project/CloseIssue", "project/Store", …]
+ *
+ * Context: a use case is proven in Node with nothing of a platform; these are the platform's
+ * part, held in memory. Not test doubles of this package — real implementations of its ports.
+ */
+/** A span as the memory tracer kept it. */
+export type RecordedSpan = {
+    name: string;
+    traceId: string;
+    spanId: string;
+    /** The span it was opened under, when it was. */
+    parentSpanId: string | undefined;
+    attributes: Record<string, string | number | boolean>;
+    /** How it ended; `undefined` while it is open. */
+    outcome: Outcome | undefined;
+    error: unknown;
+};
+export type MemoryTracer = Tracer & {
+    readonly spans: RecordedSpan[];
+};
+export declare function memoryTracer(): MemoryTracer;
+export type MemoryReporter = ErrorReporter & {
+    readonly reports: {
+        error: unknown;
+        about: ErrorAbout;
+    }[];
+};
+export declare function memoryReporter(): MemoryReporter;
+export type MemoryLogger = Logger & {
+    readonly records: LogRecord[];
+};
+export declare function memoryLogger(): MemoryLogger;

package/dist/observability/adapters/memory.js

@@ -0,0 +1,49 @@
+function hex(bytes) {
+    return Array.from(globalThis.crypto.getRandomValues(new Uint8Array(bytes)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export function memoryTracer() {
+    const spans = [];
+    return {
+        spans,
+        start(name, options) {
+            const recorded = {
+                name,
+                traceId: options.parent?.traceId || hex(16),
+                spanId: hex(8),
+                parentSpanId: options.parent?.spanId || undefined,
+                attributes: { ...options.attributes },
+                outcome: undefined,
+                error: undefined,
+            };
+            spans.push(recorded);
+            return {
+                traceId: recorded.traceId,
+                spanId: recorded.spanId,
+                sampled: true,
+                set: (attributes) => void Object.assign(recorded.attributes, attributes),
+                end: (outcome, error) => {
+                    if (recorded.outcome !== undefined)
+                        return;
+                    recorded.outcome = outcome;
+                    recorded.error = error;
+                },
+            };
+        },
+    };
+}
+export function memoryReporter() {
+    const reports = [];
+    return { reports, report: (error, about) => void reports.push({ error, about }) };
+}
+export function memoryLogger() {
+    const records = [];
+    return {
+        records,
+        log(record) {
+            records.push({
+                ...record,
+                ...(record.attributes ? { attributes: { ...record.attributes } } : {}),
+            });
+        },
+    };
+}

package/dist/{adapters → observability/adapters}/opentelemetry.d.ts

@@ -1,5 +1,5 @@
 import { type Tracer as OtelTracer } from "@opentelemetry/api";
-import type { Tracer } from "../observability/ports.js";
+import type { Tracer } from "../domain/tracing.js";
 /**
  * The `Tracer` port over OpenTelemetry's API: every use case a span of whatever provider the
  * platform registered.

package/dist/{adapters → observability/adapters}/sentry.d.ts

@@ -1,4 +1,4 @@
-import type { ErrorReporter } from "../observability/ports.js";
+import type { ErrorReporter } from "../domain/errors.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.

package/dist/observability/domain/errors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What a platform plugs to report what nobody expected.
+ *
+ * Context: the backend reports each unexpected failure once, with the use case and the trace it
+ * belongs to; GlitchTip, Sentry or memory in a test receive it here. A reporter that fails is
+ * ignored: telling about a failure never becomes a second one.
+ */
+/** What a report says about where the error happened. */
+export type ErrorAbout = {
+    /** `<bounded context>.<Service>`: the use case's identity, as the backend's — or, for what
+     *  failed outside one (`reportError`), where it happened (`view project:issue/acme-3`). */
+    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: the process's context, its bounded context's, its scope's. */
+    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;
+}

package/dist/observability/domain/errors.js

@@ -0,0 +1,8 @@
+/**
+ * What a platform plugs to report what nobody expected.
+ *
+ * Context: the backend reports each unexpected failure once, with the use case and the trace it
+ * belongs to; GlitchTip, Sentry or memory in a test receive it here. A reporter that fails is
+ * ignored: telling about a failure never becomes a second one.
+ */
+export {};

package/dist/observability/domain/logging.d.ts

@@ -0,0 +1,42 @@
+import type { Attributes, Outcome } from "./tracing.js";
+/**
+ * What a platform plugs to receive structured logs: a sink (`Logger`) that owns filtering and
+ * delivery — the console by default, Loki, a phone's queue, memory in a test.
+ *
+ * Context: a line says which layer wrote it, the way sincpro_framework's architecture names
+ * them: the application layer (a bounded context and its ApplicationServices and Features,
+ * through `project.logger` and `this.logger`), its adapters (`loggerAdapter`) and the
+ * infrastructure around them (`logger`). A line written inside a use case carries that
+ * execution's identity; nothing writes a DTO, a response, an error body or the session's
+ * context on its own.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/** The layer a line comes from. */
+export type LogLayer = "infrastructure" | "adapter" | "bounded_context" | "application_service" | "feature";
+/** Structured logging never implicitly includes a DTO, response, error body or session context. */
+export type LogRecord = {
+    readonly timestamp: string;
+    readonly level: LogLevel;
+    readonly layer: LogLayer;
+    readonly message: string;
+    readonly attributes?: Attributes;
+    readonly event?: "execution.started" | "execution.finished" | "error.handled";
+    readonly boundedContext?: string;
+    readonly useCase?: string;
+    readonly executionId?: string;
+    readonly traceId?: string;
+    readonly spanId?: string;
+    readonly outcome?: Outcome;
+    readonly durationMs?: number;
+};
+/** A sink owns filtering and delivery. Logging is best-effort and never awaited by business work. */
+export interface Logger {
+    log(record: LogRecord): void | Promise<void>;
+}
+/** How code writes a line: the logger of a layer, of a bounded context, or of a run. */
+export interface LayerLogger {
+    debug(message: string, attributes?: Attributes): void;
+    info(message: string, attributes?: Attributes): void;
+    warn(message: string, attributes?: Attributes): void;
+    error(message: string, attributes?: Attributes): void;
+}

package/dist/observability/domain/logging.js

@@ -0,0 +1 @@
+export {};