@sincpro/client-framework 0.5.0 → 1.0.0

package/dist/codegen/{scaffold.d.ts → services/scaffold.d.ts}

@@ -1,4 +1,4 @@
-import type { Metamodel } from "./metamodel.js";
+import type { Metamodel } from "../domain/metamodel.js";
 /**
  * A bounded context's skeleton, written ONCE beside what is generated — the files that are the
  * application's from then on:
@@ -7,7 +7,7 @@ import type { Metamodel } from "./metamodel.js";
  *       generated/                         `sincpro-client generate` — regenerated, never edited
  *       infrastructure/dependencies.ts     what the services can count on: the generated client
  *       infrastructure/bounded_context.ts  its Feature and ApplicationService, and how it is made
- *       services/index.ts                  the services, by the name each is reached by
+ *       services/index.ts                  registers command classes and their services
  *       index.ts                           `export const project` — ready to use
  *
  * Context: the layout sincpro_framework gives a service (`dependencies.py`, `framework.py`,

package/dist/codegen/{scaffold.js → services/scaffold.js}

@@ -1,9 +1,8 @@
-import { aliasOf, FRAMEWORK } from "./names.js";
+import { aliasOf, FRAMEWORK } from "../domain/names.js";
 /** Names the skeleton's `index.ts` cannot give its constant. */
 const TAKEN = new Set([
     "transport",
-    "features",
-    "applicationServices",
+    "registerServices",
     ..."break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield let static implements interface package private protected public await".split(" "),
 ]);
 /** `sales-orders` → `SalesOrders`. */
@@ -31,7 +30,8 @@ export function scaffoldFilesOf(metamodel, options = {}) {
     const dependencies = [
         HEADER(`What the services of «${alias}» can count on`),
         "",
-        `import type { Transport, UseBoundedContext } from "${FRAMEWORK}";`,
+        `import type { Transport } from "${FRAMEWORK}";`,
+        `import type { BoundedContext } from "${at(FRAMEWORK, "core")}";`,
         ...(client ? ["", `import { clientOf } from "${at("..", "generated", "client")}";`] : []),
         "",
         `/** What every service of «${alias}» finds on \`this\`${client ? ": `this.client`, the service's operations" : ""}. */`,
@@ -44,7 +44,7 @@ export function scaffoldFilesOf(metamodel, options = {}) {
         "}",
         "",
         "export function registerDependencies(",
-        `  bc: UseBoundedContext<${Dependencies}>,`,
+        `  bc: BoundedContext<${Dependencies}>,`,
         `  ${client ? "transport" : "_transport"}: Transport,`,
         ") {",
         ...(client ? [`  bc.addDependency("client", clientOf(transport));`] : []),
@@ -58,45 +58,42 @@ export function scaffoldFilesOf(metamodel, options = {}) {
         "import {",
         "  ApplicationService as BaseApplicationService,",
         "  Feature as BaseFeature,",
-        "  type Transport,",
-        "  UseBoundedContext,",
-        `} from "${FRAMEWORK}";`,
+        "  BoundedContext,",
+        "  type Command,",
+        `} from "${at(FRAMEWORK, "core")}";`,
+        `import type { Transport } from "${FRAMEWORK}";`,
         "",
-        `import type { ${Name}Features } from "${at("..", "services")}";`,
         `import { type ${Dependencies}, registerDependencies } from "${at(".", "dependencies")}";`,
         "",
         `/** A Feature of «${alias}»: its dependencies typed on \`this\`, and \`this.context\`. */`,
-        `export class Feature extends BaseFeature<${Dependencies}> {}`,
+        "export abstract class Feature<C extends Command<R>, R> extends BaseFeature<C, R> {",
+        ...(client ? [`  declare readonly client: ${Dependencies}["client"];`] : []),
+        "}",
         "",
-        `/** An ApplicationService of «${alias}»: the same, and \`this.feature.<Name>\` for each Feature. */`,
-        "export class ApplicationService extends BaseApplicationService<",
-        `  ${Dependencies},`,
-        `  ${Name}Features`,
-        "> {}",
+        `/** An ApplicationService of «${alias}»: the same, and \`this.featureBus.execute(dto)\`. */`,
+        "export abstract class ApplicationService<C extends Command<R>, R> extends BaseApplicationService<C, R> {",
+        ...(client ? [`  declare readonly client: ${Dependencies}["client"];`] : []),
+        "}",
         "",
         `export function config${Name}BoundedContext(name: string, transport: Transport) {`,
-        `  return registerDependencies(new UseBoundedContext<${Dependencies}>(name), transport);`,
+        `  return registerDependencies(new BoundedContext<${Dependencies}>(name), transport);`,
         "}",
         "",
     ].join("\n");
     const services = [
         HEADER(`What «${alias}» offers`),
         "",
-        "/**",
-        ` * Each service by the name it is reached by — \`${name}.Issues.close(…)\`. A Feature groups the`,
-        " * operations of one part of the domain; an ApplicationService composes the Features:",
-        " *",
-        " *     // services/issues.ts",
-        ` *     export class Issues extends Feature {`,
-        " *       close(input: dto.CommandCloseIssue) {",
-        " *         return this.client.closeIssue(input);",
-        " *       }",
-        " *     }",
-        " */",
-        "export const features = {};",
-        "export const applicationServices = {};",
+        `import type { BoundedContext } from "${at(FRAMEWORK, "core")}";`,
+        `import type { ${Dependencies} } from "${at("..", "infrastructure", "dependencies")}";`,
         "",
-        `export type ${Name}Features = typeof features;`,
+        "/** Register local Command classes with their Features and ApplicationServices.",
+        " * Generated DTO types are remote contracts, not runtime command constructors: import",
+        ` * them under their own name — \`import type * as remote from "${at("..", "generated", "domain")}"\` —`,
+        " * and let a local Command implement one (`implements remote.CommandCancelIssue`).",
+        " * Register with context.feature(CommandClass)(FeatureClass) or",
+        " * context.appService(CommandClass)(ApplicationServiceClass).",
+        " */",
+        `export function registerServices(_context: BoundedContext<${Dependencies}>): void {}`,
         "",
     ].join("\n");
     const index = [
@@ -105,13 +102,11 @@ export function scaffoldFilesOf(metamodel, options = {}) {
         `import { transport } from "${transport}";`,
         "",
         `import { config${Name}BoundedContext } from "${at(".", "infrastructure", "bounded_context")}";`,
-        `import { applicationServices, features } from "${at(".", "services")}";`,
+        `import { registerServices } from "${at(".", "services")}";`,
         "",
-        `/** «${alias}»: \`${name}.<Service>.<method>(…)\` — from a screen, a test, another bounded context. */`,
-        `export const ${name} = config${Name}BoundedContext(${JSON.stringify(alias)}, transport).register({`,
-        "  features,",
-        "  applicationServices,",
-        "});",
+        `/** «${alias}»: \`${name}.execute(new Command(...))\`. */`,
+        `export const ${name} = config${Name}BoundedContext(${JSON.stringify(alias)}, transport);`,
+        `registerServices(${name});`,
         "",
     ].join("\n");
     return {

package/dist/common/collection.d.ts

@@ -0,0 +1,110 @@
+import type { AnyRecord, Count, Criteria } from "@sincpro/criteria";
+/**
+ * A to-many as a reading answers it — sincpro_framework's `EntityCollection`: the records, how
+ * many there are, and the cursor to go on inside this parent. Never a bare list, which would
+ * say the page is all there is.
+ *
+ *     customer.invoices   ->  { items: [i1, …, i40], count: { value: 1000, exact: false }, cursor: "eyJ…" }
+ *
+ * Context: a customer may have a million invoices, and the read brings forty of them with
+ * «at least a thousand» — the backend counts up to a cap (`RELATION_COUNT_CAP`) because an exact
+ * total reads every child. A screen that counted `items` showed forty and called it the total;
+ * one that iterated an array never knew there was more. The same type on every platform, so the
+ * web, the phone and a script read a relation the same way.
+ *
+ * `count` is `null` when the read asked for none (`CountMode.NONE`): the cursor alone says there
+ * is more. A collection is written back only whole — the backend refuses a page of it, because
+ * written back it would remove what it did not bring.
+ */
+export type EntityCollection<T> = {
+    readonly items: readonly T[];
+    readonly count?: Count | null;
+    readonly cursor?: string | null;
+};
+/**
+ * A collection with every part said — what `collectionOf` answers —, edited the way a string or
+ * a date is: `append`, `extend`, `remove` and `replace` answer a new collection and never change
+ * this one, as sincpro_framework's `EntityCollection` does.
+ *
+ *     const lines = collectionOf(invoice.lines);
+ *     const next = lines.append(newLine).remove(oldLine.id);   // lines is as it was
+ *
+ * An edit keeps what the collection says: a page stays a page (its cursor; a floor stays a
+ * floor), an exact count moves with what was added or removed. `remove` and `replace` of a record
+ * it does not hold throw, as Python's `list.remove` does. Written as JSON it is the wire's shape:
+ * `{ items, count, cursor }`.
+ */
+export declare class HeldCollection<T> implements EntityCollection<T> {
+    #private;
+    readonly items: readonly T[];
+    readonly count: Count | null;
+    readonly cursor: string | null;
+    constructor(items: readonly T[], count?: Count | null, cursor?: string | null, identity?: string);
+    /** How many records are held — this page, never the total (`count` is that). */
+    get length(): number;
+    /** Whether it holds less than there is (`isPartial`). */
+    get partial(): boolean;
+    [Symbol.iterator](): Iterator<T>;
+    /** A new collection with `records` at the end. */
+    append(...records: T[]): HeldCollection<T>;
+    /** A new collection with every one of `records` at the end, in order. */
+    extend(records: Iterable<T>): HeldCollection<T>;
+    /** A new collection without these records — each named by itself or by its identity. */
+    remove(...records: unknown[]): HeldCollection<T>;
+    /** A new collection where each of `records` takes the place of the held one with its identity. */
+    replace(...records: T[]): HeldCollection<T>;
+    toJSON(): EntityCollection<T>;
+}
+/** Whether `value` is a collection as a reading answers one (`{items, …}`). */
+export declare function isCollection(value: unknown): value is EntityCollection<unknown>;
+/**
+ * Whatever a relation arrived as, as a collection with every part said.
+ *
+ *     collectionOf({ items: [a, b], count: { value: 30, exact: true }, cursor: "x" })
+ *       -> the same, `cursor` and `count` said
+ *     collectionOf([a, b])        -> { items: [a, b], count: { value: 2, exact: true }, cursor: null }
+ *     collectionOf(undefined)     -> { items: [], count: { value: 0, exact: true }, cursor: null }
+ *
+ * An array — a domain written by hand, a record built in memory — holds all there is. `identity`
+ * is the field `remove` and `replace` match records by (the model's `identity`, `"id"`).
+ */
+export declare function collectionOf<T>(value: EntityCollection<T> | readonly T[] | null | undefined, identity?: string): HeldCollection<T>;
+/**
+ * Whether the collection holds less than there is — sincpro_framework's `is_partial`, the same
+ * rule: a cursor says there is more; no count claims nothing; a floor, or a count above what it
+ * holds, says there is more.
+ *
+ *     isPartial({ items: [a], cursor: "x" })                          -> true
+ *     isPartial({ items: [a], count: { value: 1000, exact: false } }) -> true
+ *     isPartial({ items: [a, b], count: { value: 2, exact: true } })  -> false
+ *     isPartial({ items: [a] })                                       -> false
+ */
+export declare function isPartial(collection: EntityCollection<unknown>): boolean;
+/**
+ * How many there are, as well as the collection knows: its count, or — when the read asked for
+ * none — what it holds, exact only when nothing says there is more.
+ *
+ *     totalOf({ items: [a, b], count: { value: 1000, exact: false } })  -> { value: 1000, exact: false }
+ *     totalOf({ items: [a, b], cursor: "x" })                           -> { value: 2, exact: false }
+ */
+export declare function totalOf(collection: EntityCollection<unknown>): Count;
+/** How a relation ties two records, as a model's definition says it (`FieldMeta`). */
+export type RelationKeys = {
+    identified_by?: string | null;
+    parent_field?: string | null;
+    related_field?: string | null;
+};
+/**
+ * The question «the related records of this one», over the related entity — sincpro_framework's
+ * `References.criteria()`: what pages a relation past what its record brought, searches it and
+ * orders it, a list like any other. `criteria` narrows it; it never widens it.
+ *
+ *     relatedCriteria(meta.fields.invoices, customer, "id")
+ *       -> { selection: { field: "customer_id", operator: "=", value: customer.id } }
+ *     relatedCriteria(field, customer, "id", { order: [{ field: "issued_on", descending: true }] })
+ *
+ * The two fields the definition names (`parent_field`, `related_field`) are read when it names
+ * them — a relation by a business key —; `identified_by` against the record's own key otherwise.
+ * A relation whose definition says neither cannot be asked, and says so.
+ */
+export declare function relatedCriteria<T extends AnyRecord>(keys: RelationKeys, record: AnyRecord, identity?: string, criteria?: Criteria<T>): Criteria<T>;

package/dist/common/collection.js

@@ -0,0 +1,169 @@
+/**
+ * A collection with every part said — what `collectionOf` answers —, edited the way a string or
+ * a date is: `append`, `extend`, `remove` and `replace` answer a new collection and never change
+ * this one, as sincpro_framework's `EntityCollection` does.
+ *
+ *     const lines = collectionOf(invoice.lines);
+ *     const next = lines.append(newLine).remove(oldLine.id);   // lines is as it was
+ *
+ * An edit keeps what the collection says: a page stays a page (its cursor; a floor stays a
+ * floor), an exact count moves with what was added or removed. `remove` and `replace` of a record
+ * it does not hold throw, as Python's `list.remove` does. Written as JSON it is the wire's shape:
+ * `{ items, count, cursor }`.
+ */
+export class HeldCollection {
+    items;
+    count;
+    cursor;
+    /** The field each record's identity is in — what `remove` and `replace` match by. */
+    #identity;
+    constructor(items, count = null, cursor = null, identity = "id") {
+        this.items = Object.freeze([...items]);
+        this.count = count;
+        this.cursor = cursor;
+        this.#identity = identity;
+        Object.freeze(this);
+    }
+    /** How many records are held — this page, never the total (`count` is that). */
+    get length() {
+        return this.items.length;
+    }
+    /** Whether it holds less than there is (`isPartial`). */
+    get partial() {
+        return isPartial(this);
+    }
+    [Symbol.iterator]() {
+        return this.items[Symbol.iterator]();
+    }
+    /** A new collection with `records` at the end. */
+    append(...records) {
+        return this.#edited([...this.items, ...records], records.length);
+    }
+    /** A new collection with every one of `records` at the end, in order. */
+    extend(records) {
+        return this.append(...records);
+    }
+    /** A new collection without these records — each named by itself or by its identity. */
+    remove(...records) {
+        const unwanted = new Set(records.map((one) => this.#keyOf(one)));
+        const held = new Set(this.items.map((one) => this.#keyOf(one)));
+        const missing = [...unwanted].filter((key) => !held.has(key));
+        if (missing.length > 0)
+            throw new Error(`not in the collection: ${missing.join(", ")}`);
+        return this.#edited(this.items.filter((one) => !unwanted.has(this.#keyOf(one))), -unwanted.size);
+    }
+    /** A new collection where each of `records` takes the place of the held one with its identity. */
+    replace(...records) {
+        const byKey = new Map(records.map((one) => [this.#keyOf(one), one]));
+        const held = new Set(this.items.map((one) => this.#keyOf(one)));
+        const missing = [...byKey.keys()].filter((key) => !held.has(key));
+        if (missing.length > 0)
+            throw new Error(`not in the collection: ${missing.join(", ")} — append adds a record`);
+        return this.#edited(this.items.map((one) => byKey.get(this.#keyOf(one)) ?? one), 0);
+    }
+    toJSON() {
+        return { items: this.items, count: this.count, cursor: this.cursor };
+    }
+    #keyOf(record) {
+        if (typeof record !== "object" || record === null)
+            return record;
+        const key = record[this.#identity];
+        // A record not stored yet has no identity: it is itself, never every other new one too.
+        return key === undefined || key === null || key === "" ? record : key;
+    }
+    #edited(items, moved) {
+        const count = this.count !== null && this.count.exact
+            ? { value: Math.max(this.count.value + moved, 0), exact: true }
+            : this.count;
+        return new HeldCollection(items, count, this.cursor, this.#identity);
+    }
+}
+/** Whether `value` is a collection as a reading answers one (`{items, …}`). */
+export function isCollection(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    if (!("items" in value))
+        return false;
+    const items = value.items;
+    // A page whose records did not come (`items: null`) is still a page: its count says so.
+    return Array.isArray(items) || items === null || items === undefined;
+}
+/**
+ * Whatever a relation arrived as, as a collection with every part said.
+ *
+ *     collectionOf({ items: [a, b], count: { value: 30, exact: true }, cursor: "x" })
+ *       -> the same, `cursor` and `count` said
+ *     collectionOf([a, b])        -> { items: [a, b], count: { value: 2, exact: true }, cursor: null }
+ *     collectionOf(undefined)     -> { items: [], count: { value: 0, exact: true }, cursor: null }
+ *
+ * An array — a domain written by hand, a record built in memory — holds all there is. `identity`
+ * is the field `remove` and `replace` match records by (the model's `identity`, `"id"`).
+ */
+export function collectionOf(value, identity = "id") {
+    if (value instanceof HeldCollection && identity === "id")
+        return value;
+    if (Array.isArray(value))
+        return new HeldCollection(value, { value: value.length, exact: true }, null, identity);
+    if (isCollection(value)) {
+        const page = value;
+        return new HeldCollection(page.items ?? [], page.count ?? null, page.cursor ?? null, identity);
+    }
+    return new HeldCollection([], { value: 0, exact: true }, null, identity);
+}
+/**
+ * Whether the collection holds less than there is — sincpro_framework's `is_partial`, the same
+ * rule: a cursor says there is more; no count claims nothing; a floor, or a count above what it
+ * holds, says there is more.
+ *
+ *     isPartial({ items: [a], cursor: "x" })                          -> true
+ *     isPartial({ items: [a], count: { value: 1000, exact: false } }) -> true
+ *     isPartial({ items: [a, b], count: { value: 2, exact: true } })  -> false
+ *     isPartial({ items: [a] })                                       -> false
+ */
+export function isPartial(collection) {
+    if (collection.cursor != null)
+        return true;
+    const count = collection.count;
+    if (count == null)
+        return false;
+    return !count.exact || count.value > (collection.items ?? []).length;
+}
+/**
+ * How many there are, as well as the collection knows: its count, or — when the read asked for
+ * none — what it holds, exact only when nothing says there is more.
+ *
+ *     totalOf({ items: [a, b], count: { value: 1000, exact: false } })  -> { value: 1000, exact: false }
+ *     totalOf({ items: [a, b], cursor: "x" })                           -> { value: 2, exact: false }
+ */
+export function totalOf(collection) {
+    return (collection.count ?? {
+        value: (collection.items ?? []).length,
+        exact: collection.cursor == null,
+    });
+}
+/**
+ * The question «the related records of this one», over the related entity — sincpro_framework's
+ * `References.criteria()`: what pages a relation past what its record brought, searches it and
+ * orders it, a list like any other. `criteria` narrows it; it never widens it.
+ *
+ *     relatedCriteria(meta.fields.invoices, customer, "id")
+ *       -> { selection: { field: "customer_id", operator: "=", value: customer.id } }
+ *     relatedCriteria(field, customer, "id", { order: [{ field: "issued_on", descending: true }] })
+ *
+ * The two fields the definition names (`parent_field`, `related_field`) are read when it names
+ * them — a relation by a business key —; `identified_by` against the record's own key otherwise.
+ * A relation whose definition says neither cannot be asked, and says so.
+ */
+export function relatedCriteria(keys, record, identity = "id", criteria = {}) {
+    const there = keys.related_field ?? keys.identified_by;
+    const here = keys.related_field != null ? (keys.parent_field ?? identity) : identity;
+    if (there == null || there === "")
+        throw new Error("this relation's definition names no key to ask it by (identified_by, related_field)");
+    const mine = { field: there, operator: "=", value: record[here] };
+    return {
+        ...criteria,
+        selection: (criteria.selection === undefined
+            ? mine
+            : { all: [criteria.selection, mine] }),
+    };
+}

package/dist/common/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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, and how any value is written and read.
+ */
+export { collectionOf, type EntityCollection, type HeldCollection, isCollection, isPartial, relatedCriteria, type RelationKeys, totalOf, } from "./collection.js";
+export { Decimal, type DecimalLike } from "./decimal.js";
+export { isEntityId, momentOf, newEntityId } from "./ids.js";
+export { Money } from "./money.js";
+export { BYTES, type JsonValue, pack, readValues, type Rebuild, rebuilt, unpack, valuesOf, } from "./serialization.js";
+export { dayOf, installTimeZone, instantOf, isDay, timeZoneNow, wallTimeOf, } from "./time.js";

package/dist/common/index.js

@@ -0,0 +1,10 @@
+/**
+ * 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, and how any value is written and read.
+ */
+export { collectionOf, isCollection, isPartial, relatedCriteria, totalOf, } from "./collection.js";
+export { Decimal } from "./decimal.js";
+export { isEntityId, momentOf, newEntityId } from "./ids.js";
+export { Money } from "./money.js";
+export { BYTES, pack, readValues, rebuilt, unpack, valuesOf, } from "./serialization.js";
+export { dayOf, installTimeZone, instantOf, isDay, timeZoneNow, wallTimeOf, } from "./time.js";

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

@@ -0,0 +1,6 @@
+import type { ContextStore } from "../domain/store.js";
+/**
+ * The context in this process's memory: the default, on every platform. A test gets a fresh one
+ * from `configureProcess()`.
+ */
+export declare function memoryContexts(): ContextStore;

package/dist/context/adapters/memory.js

@@ -0,0 +1,34 @@
+/**
+ * The context in this process's memory: the default, on every platform. A test gets a fresh one
+ * from `configureProcess()`.
+ */
+export function memoryContexts() {
+    const held = new Map();
+    const versions = new Map();
+    const listeners = new Map();
+    const changed = (key) => {
+        versions.set(key, (versions.get(key) ?? 0) + 1);
+        for (const listener of [...(listeners.get(key) ?? [])])
+            listener();
+    };
+    return {
+        load: (key) => held.get(key),
+        save(key, values) {
+            // A copy: whoever handed the values may keep changing their object.
+            held.set(key, { ...values });
+            changed(key);
+        },
+        delete(key) {
+            if (!held.delete(key))
+                return;
+            changed(key);
+        },
+        version: (key) => versions.get(key) ?? 0,
+        watch(key, listener) {
+            const own = listeners.get(key) ?? new Set();
+            listeners.set(key, own);
+            own.add(listener);
+            return () => void own.delete(listener);
+        },
+    };
+}

package/dist/context/adapters/plain-codec.d.ts

@@ -0,0 +1,3 @@
+import { type ContextCodec } from "../domain/codec.js";
+/** The codec for anything outside the codebase: only the values that travel, as JSON. */
+export declare const plainCodec: ContextCodec;

package/dist/context/adapters/plain-codec.js

@@ -0,0 +1,16 @@
+import { travelling, } from "../domain/codec.js";
+/** The codec for anything outside the codebase: only the values that travel, as JSON. */
+export const plainCodec = {
+    dumps: (values) => JSON.stringify(travelling(values)),
+    loads(text) {
+        try {
+            const found = JSON.parse(text);
+            return found !== null && typeof found === "object" && !Array.isArray(found)
+                ? found
+                : {};
+        }
+        catch {
+            return {};
+        }
+    },
+};

package/dist/context/{codec.d.ts → domain/codec.d.ts}

@@ -23,4 +23,3 @@ export interface ContextCodec {
 export declare function travels(value: unknown): boolean;
 /** The values of `context` that travel; the rest stays in this process. */
 export declare function travelling(context: ContextValues): ContextValues;
-export declare const plainCodec: ContextCodec;

package/dist/context/{codec.js → domain/codec.js}

@@ -28,17 +28,3 @@ export function travels(value) {
 export function travelling(context) {
     return Object.fromEntries(Object.entries(context).filter(([, value]) => travels(value)));
 }
-export const plainCodec = {
-    dumps: (values) => JSON.stringify(travelling(values)),
-    loads(text) {
-        try {
-            const found = JSON.parse(text);
-            return found !== null && typeof found === "object" && !Array.isArray(found)
-                ? found
-                : {};
-        }
-        catch {
-            return {};
-        }
-    },
-};

package/dist/context/domain/execution.d.ts

@@ -0,0 +1,33 @@
+import type { Span } from "../../observability/domain/tracing.js";
+/**
+ * One run of a use case: its span, what it runs with, and who ran it.
+ *
+ * Context: sincpro_framework keeps the running use case in a context variable; a browser has
+ * nothing like it that survives an `await` (AsyncContext is a proposal, Zone.js patches the
+ * world), and a global stack mixes the parents of two use cases running at once — which a
+ * screen with several windows does all the time. So an execution is a value, handed to what
+ * the use case calls: the Features its `featureBus` runs, and its dependencies (`BIND`).
+ */
+export type Execution = {
+    /** UUID v7, as 32 hex: this run. */
+    readonly id: string;
+    /** `<bounded context>.<Service>` — the use case's identity, as the backend names its own. */
+    readonly useCase: string;
+    /** The bounded context the use case belongs to. */
+    readonly boundedContext: string;
+    /** The run that executed this one: an ApplicationService, for its Features. */
+    readonly parent: Execution | undefined;
+    readonly span: Span;
+    /** What it runs with, read once where the gesture started and inherited by every child. */
+    readonly context: Readonly<Record<string, unknown>>;
+};
+/**
+ * A dependency that has something to say about the execution it is used in: given that
+ * execution, it answers itself bound to it. The transport, every generated client and the
+ * predefined loggers are; any other dependency of a bounded context is handed as it is.
+ */
+export declare const BIND: unique symbol;
+export type Bindable<T> = {
+    [BIND]: (execution: Execution) => T;
+};
+export declare function isBindable<T>(value: T): value is T & Bindable<T>;

package/dist/context/domain/execution.js

@@ -0,0 +1,11 @@
+/**
+ * A dependency that has something to say about the execution it is used in: given that
+ * execution, it answers itself bound to it. The transport, every generated client and the
+ * predefined loggers are; any other dependency of a bounded context is handed as it is.
+ */
+export const BIND = Symbol.for("sincpro.client-framework.bind");
+export function isBindable(value) {
+    return (value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        typeof value[BIND] === "function");
+}

package/dist/context/{store.d.ts → domain/store.d.ts}

@@ -44,8 +44,3 @@ export interface ContextStore {
      */
     watch?(key: string, listener: () => void): () => void;
 }
-/**
- * The context in this process's memory: the default, on every platform. A test gets a fresh one
- * from `configureProcess()`.
- */
-export declare function memoryContexts(): ContextStore;

package/dist/context/{store.js → domain/store.js}

@@ -23,37 +23,4 @@
  * Reads are synchronous on purpose: a use case reads its context where a gesture starts, and an
  * asynchronous store would make every use case wait for it.
  */
-/**
- * The context in this process's memory: the default, on every platform. A test gets a fresh one
- * from `configureProcess()`.
- */
-export function memoryContexts() {
-    const held = new Map();
-    const versions = new Map();
-    const listeners = new Map();
-    const changed = (key) => {
-        versions.set(key, (versions.get(key) ?? 0) + 1);
-        for (const listener of [...(listeners.get(key) ?? [])])
-            listener();
-    };
-    return {
-        load: (key) => held.get(key),
-        save(key, values) {
-            // A copy: whoever handed the values may keep changing their object.
-            held.set(key, { ...values });
-            changed(key);
-        },
-        delete(key) {
-            if (!held.delete(key))
-                return;
-            changed(key);
-        },
-        version: (key) => versions.get(key) ?? 0,
-        watch(key, listener) {
-            const own = listeners.get(key) ?? new Set();
-            listeners.set(key, own);
-            own.add(listener);
-            return () => void own.delete(listener);
-        },
-    };
-}
+export {};

package/dist/context/{context.d.ts → entrypoint/context.d.ts}

@@ -1,4 +1,4 @@
-import type { ContextStore, ContextValues } from "./store.js";
+import type { ContextStore, ContextValues } from "../domain/store.js";
 /**
  * One level of the context: the process's (`processContext`) or a bounded context's
  * (`project.context`), read and written the same way on every platform.

package/dist/context/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The context: the levels a call sees (the process, its bounded context, a scope), where they
+ * live (`ContextStore`, a port each platform implements), what travels with a request, and the
+ * execution a run carries.
+ *
+ *   domain/          the ports and rules: `ContextStore`, `ContextCodec`, what travels, `Execution`
+ *   adapters/        the implementations this package gives: memory, the plain codec
+ *   entrypoint/      `Context`: one door over a level
+ *   infrastructure/  the process's store and its level (`processContext`)
+ */
+export { memoryContexts } from "./adapters/memory.js";
+export { plainCodec } from "./adapters/plain-codec.js";
+export { CONTEXT_HEADER, type ContextCodec, travelling, travels, } from "./domain/codec.js";
+export { BIND, type Bindable, type Execution, } from "./domain/execution.js";
+export type { ContextStore, ContextValues, } from "./domain/store.js";
+export type { Context } from "./entrypoint/context.js";
+export { processContext } from "./infrastructure/process.js";