@earendil-works/chord 1.5.0 → 1.5.1

package/dist/registries/record.js

@@ -0,0 +1,283 @@
+// A registry on a host (slice 8 §1): its provider (replaced or removed by a reload, slice 7b §3), its contributions in table order (`contribution.ts`), the table
+// and its lazy composition (marked when the table changes, composed when read or followed, in the batch's
+// deliveries), the reports of conflicts and failures (once per episode) and of contributions nobody serves, and the
+// values its readers follow by version.
+import { ChordError } from "../data/index.js";
+import { invalid } from "../data/internal.js";
+import { handedOut } from "../state/internal.js";
+import { RegistryValueSource } from "./value.js";
+const NEVER = { good: undefined, failure: undefined };
+/**
+ * Checks a registry provider as a setup served it (declaration policy: plugin code is bundled without type checks):
+ * `compose` is a function.
+ */
+export function checkProvider(name, provider) {
+    if (typeof provider?.compose !== "function")
+        throw new Error(`registry ${name}: compose is a function`);
+}
+/** One registry of a host. */
+export class RegistryRecord {
+    name;
+    #batch;
+    #report;
+    #provider;
+    /** The contributions of live contributors, sorted by plugin, then type (a facet's first). */
+    #contributions = [];
+    /** The last table composed, kept so an unchanged table composes nothing. */
+    #table;
+    #dirty = true;
+    #composition = NEVER;
+    /** Set while its table is built and composed: a read then is a cycle of registries. */
+    #composing = false;
+    /** The conflicts the last good composition reported, by key: a conflict is reported once per episode. */
+    #conflicts = new Set();
+    /** The values readers follow, by version; made by the first reader of a version. */
+    #values = new Map();
+    /** The host's clock of unbound waits: a value of it waited for while it has none is on it. */
+    clock;
+    /** The contributing plugins `registry_undeclared` named last (joined); `undefined` since a provider served it. */
+    #undeclared;
+    constructor(name, batch, report, clock) {
+        this.name = name;
+        this.#batch = batch;
+        this.#report = report;
+        this.clock = clock;
+    }
+    /** The newest registry version its contributions were built against; `undefined` without contributions. */
+    get newestContribution() {
+        if (this.#contributions.length === 0)
+            return undefined;
+        return Math.max(...this.#contributions.map(({ version }) => version));
+    }
+    /** The provider's version; `undefined` while none serves it. */
+    get providedVersion() {
+        return this.#provider?.version;
+    }
+    /** The value readers of `version` follow. */
+    value(version) {
+        let value = this.#values.get(version);
+        if (value === undefined) {
+            value = new RegistryValueSource(this, version, this.#batch);
+            this.#values.set(version, value);
+        }
+        return value;
+    }
+    /**
+     * Serves the registry with `provider` at `version` (the defining plugin's facet, checked by `checkProvider` when
+     * its setup ran), replacing the provider a reload changed, inside a batch: the table composes again (lazily).
+     */
+    serve(version, provider) {
+        this.#provider = { version, provider };
+        this.#table = undefined;
+        this.#invalidate();
+    }
+    /**
+     * A reload removed the defining plugin, inside a batch: no provider serves it; its readers' values fail
+     * `unavailable/undeclared` (a reader parked on it waits `not_served`), its contributions stay in the table.
+     */
+    unserve() {
+        this.#provider = undefined;
+        this.#table = undefined;
+        this.#composition = NEVER;
+        this.#invalidate();
+    }
+    /** The first composition of a served registry, at `load`'s publication or a reload's commit, inside its batch. */
+    composeServed() {
+        if (this.#provider === undefined)
+            return;
+        this.start();
+    }
+    /**
+     * After a publication's batch, or a batch where an object's contributions entered: with contributions and no
+     * provider, reports `registry_undeclared` naming the contributing plugins, unless the same ones were reported since
+     * a provider last served it.
+     */
+    reportUndeclared() {
+        if (this.#provider !== undefined) {
+            this.#undeclared = undefined;
+            return;
+        }
+        if (this.#contributions.length === 0)
+            return;
+        const plugins = [...new Set(this.#contributions.map(({ contributor }) => contributor.plugin))];
+        const key = plugins.join("\u0000");
+        if (key === this.#undeclared)
+            return;
+        this.#undeclared = key;
+        this.#report({ kind: "registry_undeclared", registry: this.name, plugins });
+    }
+    /** Adds a live contributor's contribution, inside a batch: the table changes. */
+    add(contribution) {
+        const at = this.#contributions.findIndex((other) => compareContributors(contribution, other) < 0);
+        // A new list per change (contributors come and go rarely): a composition keeps the one it was built from.
+        this.#contributions = this.#contributions.toSpliced(at < 0 ? this.#contributions.length : at, 0, contribution);
+        contribution.follow();
+        this.#invalidate();
+    }
+    /** Removes an ending contributor's contribution, inside a batch: the table changes. */
+    remove(contribution) {
+        const at = this.#contributions.indexOf(contribution);
+        if (at < 0)
+            return;
+        this.#contributions = this.#contributions.toSpliced(at, 1);
+        contribution.unfollow();
+        this.#invalidate();
+    }
+    /** A followed contribution changed, inside a batch: the table is marked, composed when read or followed. */
+    contributionChanged() {
+        this.#invalidate();
+    }
+    /**
+     * The current composition, composed now when the table changed: the value, or `compose`'s failure with the last
+     * good one; `unavailable/undeclared` while no provider serves it. A read while it composes is a cycle.
+     */
+    start() {
+        if (this.#composing)
+            throw invalid("cycle", `registry ${this.name} is read while it composes`);
+        if (this.#provider === undefined) {
+            const error = new ChordError({
+                code: "unavailable",
+                reason: "undeclared",
+                message: `registry ${this.name}: no plugin serves it here`,
+            });
+            return { kind: "failed", error, last: undefined };
+        }
+        if (this.#dirty)
+            this.#recompose(this.#provider);
+        const { good, failure } = this.#composition;
+        if (failure !== undefined)
+            return { kind: "failed", error: failure.error, last: good };
+        // A composition without a failure has a value.
+        return { kind: "value", value: good.value };
+    }
+    /** The contributions the current good composition was built from; `undefined` while there is none. */
+    get composedFrom() {
+        return this.#composition.good?.from;
+    }
+    /**
+     * Whether every contribution of `from` (what a composition, or a mapping of it, was built from) is still in the
+     * table (decision 5: one that left may have closed the native its entry held).
+     */
+    inTable(from) {
+        const current = this.#contributions;
+        return from === current || from.every((each) => current.includes(each));
+    }
+    /** The adapter mapping the composed value back for readers of `version`; `undefined` when there is none. */
+    valueAdapter(version) {
+        return this.#provider?.provider.accepts?.[version]?.value;
+    }
+    /** Runs an adapter of the provider as a pure compute, counted. */
+    adapt(adapter) {
+        this.#batch.count("chord.registry.adapts");
+        return this.#batch.compute(adapter);
+    }
+    /** Reports a contribution left out (`contribution_failed`, `contribution_refused`; the caller keeps the episode). */
+    reportContribution(error) {
+        this.#report(error);
+    }
+    /** Reports a throw of `compose` or of a value adapter (`registry_failed`; the caller keeps the episode). */
+    failed(error) {
+        this.#report({ kind: "registry_failed", registry: this.name, error: handedOut(error) });
+    }
+    /**
+     * The host closed: the contributions stop following their sources, the values end (a value kept by a reader still
+     * reads the last composition).
+     */
+    close() {
+        for (const contribution of this.#contributions)
+            contribution.unfollow();
+        this.#contributions = [];
+        this.#table = undefined;
+        this.#dirty = false;
+        for (const value of this.#values.values())
+            value.close();
+        this.#values.clear();
+    }
+    /**
+     * The table changed: every version's value is marked and listed (each lists itself once per batch); while it is
+     * not composed since an earlier change, only listed (its dependents are marked already).
+     */
+    #invalidate() {
+        if (this.#dirty) {
+            for (const value of this.#values.values())
+                value.relisted();
+            return;
+        }
+        this.#dirty = true;
+        for (const value of this.#values.values())
+            value.recomposed();
+    }
+    /**
+     * Builds the table and composes it, unless it is the last one composed, entry for entry (`compose` is pure). A
+     * throw is a failure episode: reported once, the last good composition kept while every contribution it was built
+     * from is still in the table (decision 5: one whose contributor ended may hold a closed native); conflicts are
+     * reported once per episode, as their message and plugins.
+     */
+    #recompose({ version, provider }) {
+        this.#dirty = false;
+        this.#composing = true;
+        try {
+            const table = this.#build(version, provider);
+            if (table === this.#table && this.#composition !== NEVER)
+                return;
+            this.#table = table;
+            const conflicts = new Map();
+            const context = {
+                report: (conflict) => conflicts.set(`${conflict.message}\u0000${conflict.plugins.join("\u0000")}`, conflict),
+            };
+            let value;
+            try {
+                this.#batch.count("chord.registry.composes");
+                value = this.#batch.compute(() => provider.compose(table, context));
+            }
+            catch (error) {
+                if (this.#composition.failure === undefined)
+                    this.failed(error);
+                const { good } = this.#composition;
+                this.#composition = {
+                    good: good !== undefined && this.inTable(good.from) ? good : undefined,
+                    failure: { error },
+                };
+                return;
+            }
+            this.#composition = { good: { value, from: this.#contributions }, failure: undefined };
+            for (const [key, conflict] of conflicts) {
+                if (this.#conflicts.has(key))
+                    continue;
+                this.#report({ kind: "registry_conflict", registry: this.name, ...conflict });
+            }
+            this.#conflicts = new Set(conflicts.keys());
+        }
+        finally {
+            this.#composing = false;
+        }
+    }
+    /** The table of the live contributions now; the last one itself when every entry is the same object. */
+    #build(version, provider) {
+        const previous = this.#table;
+        const table = [];
+        let same = previous !== undefined;
+        for (const contribution of this.#contributions) {
+            const entry = contribution.entry(version, provider);
+            if (entry === undefined)
+                continue;
+            if (same && previous[table.length] !== entry)
+                same = false;
+            table.push(entry);
+        }
+        return same && previous.length === table.length ? previous : table;
+    }
+}
+/** Table order: by plugin name, then type, a facet (no type) first; code point order, never load order. */
+function compareContributors(a, b) {
+    const left = a.contributor;
+    const right = b.contributor;
+    if (left.plugin !== right.plugin)
+        return left.plugin < right.plugin ? -1 : 1;
+    const leftType = left.type ?? "";
+    const rightType = right.type ?? "";
+    if (leftType === rightType)
+        return 0;
+    return leftType < rightType ? -1 : 1;
+}
+//# sourceMappingURL=record.js.map

package/dist/registries/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../src/registries/record.ts"],"names":[],"mappings":"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","sourcesContent":["// A registry on a host (slice 8 §1): its provider (replaced or removed by a reload, slice 7b §3), its contributions in table order (`contribution.ts`), the table\n// and its lazy composition (marked when the table changes, composed when read or followed, in the batch's\n// deliveries), the reports of conflicts and failures (once per episode) and of contributions nobody serves, and the\n// values its readers follow by version.\n\nimport { ChordError } from \"../data/index.ts\";\nimport { invalid } from \"../data/internal.ts\";\nimport type { UnboundClock } from \"../host/unbound-clock.ts\";\nimport { type Batch, handedOut, type NativeStart } from \"../state/internal.ts\";\nimport type { RegistryContribution } from \"./contribution.ts\";\nimport type { ComposeContext, RegistryConflict, RegistryEntry, RegistryProvider, RegistryTable } from \"./registry.ts\";\nimport { RegistryValueSource } from \"./value.ts\";\n\n/** What a registry reports to its host's `onError`, by kind; each once per episode. */\nexport type RegistryError =\n\t/** `compose` reported a conflict it resolved. */\n\t| {\n\t\t\treadonly kind: \"registry_conflict\";\n\t\t\treadonly registry: string;\n\t\t\treadonly message: string;\n\t\t\treadonly plugins: readonly string[];\n\t  }\n\t/** `compose` (or an older version's `value` adapter) threw: the last good composition stays. */\n\t| { readonly kind: \"registry_failed\"; readonly registry: string; readonly error: unknown }\n\t/** A watchable contribution failed or ended, or its `contribution` adapter threw: it is left out until it heals. */\n\t| {\n\t\t\treadonly kind: \"contribution_failed\";\n\t\t\treadonly registry: string;\n\t\t\treadonly plugin: string;\n\t\t\treadonly type?: string;\n\t\t\treadonly error: unknown;\n\t  }\n\t/** A contribution of a version the provider does not accept (newer, or older without an adapter) is left out. */\n\t| {\n\t\t\treadonly kind: \"contribution_refused\";\n\t\t\treadonly registry: string;\n\t\t\treadonly plugin: string;\n\t\t\treadonly type?: string;\n\t\t\treadonly version: number;\n\t  }\n\t/**\n\t * At a publication, or when a host-lifetime object's contributions enter, the registry has contributions and no\n\t * plugin here serves it (`unavailable/undeclared` for its readers): its contributing plugins in table order; again\n\t * only once they change.\n\t */\n\t| { readonly kind: \"registry_undeclared\"; readonly registry: string; readonly plugins: readonly string[] };\n\n/** The provider as served: the defining plugin's version, `compose` and adapters. */\ntype Provider = { readonly version: number; readonly provider: RegistryProvider<unknown, unknown> };\n\n/**\n * Where a composition stands: never composed, its last good value (with the contributions it was built from), and its\n * failure while `compose` throws.\n */\ntype Composition = {\n\treadonly good: { readonly value: unknown; readonly from: readonly RegistryContribution[] } | undefined;\n\treadonly failure: { readonly error: unknown } | undefined;\n};\n\nconst NEVER: Composition = { good: undefined, failure: undefined };\n\n/**\n * Checks a registry provider as a setup served it (declaration policy: plugin code is bundled without type checks):\n * `compose` is a function.\n */\nexport function checkProvider(name: string, provider: RegistryProvider<unknown, unknown>): void {\n\tif (typeof provider?.compose !== \"function\") throw new Error(`registry ${name}: compose is a function`);\n}\n\n/** One registry of a host. */\nexport class RegistryRecord {\n\treadonly name: string;\n\treadonly #batch: Batch;\n\treadonly #report: (error: RegistryError) => void;\n\t#provider: Provider | undefined;\n\t/** The contributions of live contributors, sorted by plugin, then type (a facet's first). */\n\t#contributions: readonly RegistryContribution[] = [];\n\t/** The last table composed, kept so an unchanged table composes nothing. */\n\t#table: RegistryTable<unknown> | undefined;\n\t#dirty = true;\n\t#composition: Composition = NEVER;\n\t/** Set while its table is built and composed: a read then is a cycle of registries. */\n\t#composing = false;\n\t/** The conflicts the last good composition reported, by key: a conflict is reported once per episode. */\n\t#conflicts = new Set<string>();\n\t/** The values readers follow, by version; made by the first reader of a version. */\n\treadonly #values = new Map<number, RegistryValueSource>();\n\t/** The host's clock of unbound waits: a value of it waited for while it has none is on it. */\n\treadonly clock: UnboundClock;\n\t/** The contributing plugins `registry_undeclared` named last (joined); `undefined` since a provider served it. */\n\t#undeclared: string | undefined;\n\n\tconstructor(name: string, batch: Batch, report: (error: RegistryError) => void, clock: UnboundClock) {\n\t\tthis.name = name;\n\t\tthis.#batch = batch;\n\t\tthis.#report = report;\n\t\tthis.clock = clock;\n\t}\n\n\t/** The newest registry version its contributions were built against; `undefined` without contributions. */\n\tget newestContribution(): number | undefined {\n\t\tif (this.#contributions.length === 0) return undefined;\n\t\treturn Math.max(...this.#contributions.map(({ version }) => version));\n\t}\n\n\t/** The provider's version; `undefined` while none serves it. */\n\tget providedVersion(): number | undefined {\n\t\treturn this.#provider?.version;\n\t}\n\n\t/** The value readers of `version` follow. */\n\tvalue(version: number): RegistryValueSource {\n\t\tlet value = this.#values.get(version);\n\t\tif (value === undefined) {\n\t\t\tvalue = new RegistryValueSource(this, version, this.#batch);\n\t\t\tthis.#values.set(version, value);\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Serves the registry with `provider` at `version` (the defining plugin's facet, checked by `checkProvider` when\n\t * its setup ran), replacing the provider a reload changed, inside a batch: the table composes again (lazily).\n\t */\n\tserve(version: number, provider: RegistryProvider<unknown, unknown>): void {\n\t\tthis.#provider = { version, provider };\n\t\tthis.#table = undefined;\n\t\tthis.#invalidate();\n\t}\n\n\t/**\n\t * A reload removed the defining plugin, inside a batch: no provider serves it; its readers' values fail\n\t * `unavailable/undeclared` (a reader parked on it waits `not_served`), its contributions stay in the table.\n\t */\n\tunserve(): void {\n\t\tthis.#provider = undefined;\n\t\tthis.#table = undefined;\n\t\tthis.#composition = NEVER;\n\t\tthis.#invalidate();\n\t}\n\n\t/** The first composition of a served registry, at `load`'s publication or a reload's commit, inside its batch. */\n\tcomposeServed(): void {\n\t\tif (this.#provider === undefined) return;\n\t\tthis.start();\n\t}\n\n\t/**\n\t * After a publication's batch, or a batch where an object's contributions entered: with contributions and no\n\t * provider, reports `registry_undeclared` naming the contributing plugins, unless the same ones were reported since\n\t * a provider last served it.\n\t */\n\treportUndeclared(): void {\n\t\tif (this.#provider !== undefined) {\n\t\t\tthis.#undeclared = undefined;\n\t\t\treturn;\n\t\t}\n\t\tif (this.#contributions.length === 0) return;\n\t\tconst plugins = [...new Set(this.#contributions.map(({ contributor }) => contributor.plugin))];\n\t\tconst key = plugins.join(\"\\u0000\");\n\t\tif (key === this.#undeclared) return;\n\t\tthis.#undeclared = key;\n\t\tthis.#report({ kind: \"registry_undeclared\", registry: this.name, plugins });\n\t}\n\n\t/** Adds a live contributor's contribution, inside a batch: the table changes. */\n\tadd(contribution: RegistryContribution): void {\n\t\tconst at = this.#contributions.findIndex((other) => compareContributors(contribution, other) < 0);\n\t\t// A new list per change (contributors come and go rarely): a composition keeps the one it was built from.\n\t\tthis.#contributions = this.#contributions.toSpliced(at < 0 ? this.#contributions.length : at, 0, contribution);\n\t\tcontribution.follow();\n\t\tthis.#invalidate();\n\t}\n\n\t/** Removes an ending contributor's contribution, inside a batch: the table changes. */\n\tremove(contribution: RegistryContribution): void {\n\t\tconst at = this.#contributions.indexOf(contribution);\n\t\tif (at < 0) return;\n\t\tthis.#contributions = this.#contributions.toSpliced(at, 1);\n\t\tcontribution.unfollow();\n\t\tthis.#invalidate();\n\t}\n\n\t/** A followed contribution changed, inside a batch: the table is marked, composed when read or followed. */\n\tcontributionChanged(): void {\n\t\tthis.#invalidate();\n\t}\n\n\t/**\n\t * The current composition, composed now when the table changed: the value, or `compose`'s failure with the last\n\t * good one; `unavailable/undeclared` while no provider serves it. A read while it composes is a cycle.\n\t */\n\tstart(): NativeStart<unknown> {\n\t\tif (this.#composing) throw invalid(\"cycle\", `registry ${this.name} is read while it composes`);\n\t\tif (this.#provider === undefined) {\n\t\t\tconst error = new ChordError({\n\t\t\t\tcode: \"unavailable\",\n\t\t\t\treason: \"undeclared\",\n\t\t\t\tmessage: `registry ${this.name}: no plugin serves it here`,\n\t\t\t});\n\t\t\treturn { kind: \"failed\", error, last: undefined };\n\t\t}\n\t\tif (this.#dirty) this.#recompose(this.#provider);\n\t\tconst { good, failure } = this.#composition;\n\t\tif (failure !== undefined) return { kind: \"failed\", error: failure.error, last: good };\n\t\t// A composition without a failure has a value.\n\t\treturn { kind: \"value\", value: good!.value };\n\t}\n\n\t/** The contributions the current good composition was built from; `undefined` while there is none. */\n\tget composedFrom(): readonly RegistryContribution[] | undefined {\n\t\treturn this.#composition.good?.from;\n\t}\n\n\t/**\n\t * Whether every contribution of `from` (what a composition, or a mapping of it, was built from) is still in the\n\t * table (decision 5: one that left may have closed the native its entry held).\n\t */\n\tinTable(from: readonly RegistryContribution[]): boolean {\n\t\tconst current = this.#contributions;\n\t\treturn from === current || from.every((each) => current.includes(each));\n\t}\n\n\t/** The adapter mapping the composed value back for readers of `version`; `undefined` when there is none. */\n\tvalueAdapter(version: number): ((current: never) => unknown) | undefined {\n\t\treturn this.#provider?.provider.accepts?.[version]?.value;\n\t}\n\n\t/** Runs an adapter of the provider as a pure compute, counted. */\n\tadapt<T>(adapter: () => T): T {\n\t\tthis.#batch.count(\"chord.registry.adapts\");\n\t\treturn this.#batch.compute(adapter);\n\t}\n\n\t/** Reports a contribution left out (`contribution_failed`, `contribution_refused`; the caller keeps the episode). */\n\treportContribution(error: RegistryError): void {\n\t\tthis.#report(error);\n\t}\n\n\t/** Reports a throw of `compose` or of a value adapter (`registry_failed`; the caller keeps the episode). */\n\tfailed(error: unknown): void {\n\t\tthis.#report({ kind: \"registry_failed\", registry: this.name, error: handedOut(error) });\n\t}\n\n\t/**\n\t * The host closed: the contributions stop following their sources, the values end (a value kept by a reader still\n\t * reads the last composition).\n\t */\n\tclose(): void {\n\t\tfor (const contribution of this.#contributions) contribution.unfollow();\n\t\tthis.#contributions = [];\n\t\tthis.#table = undefined;\n\t\tthis.#dirty = false;\n\t\tfor (const value of this.#values.values()) value.close();\n\t\tthis.#values.clear();\n\t}\n\n\t/**\n\t * The table changed: every version's value is marked and listed (each lists itself once per batch); while it is\n\t * not composed since an earlier change, only listed (its dependents are marked already).\n\t */\n\t#invalidate(): void {\n\t\tif (this.#dirty) {\n\t\t\tfor (const value of this.#values.values()) value.relisted();\n\t\t\treturn;\n\t\t}\n\t\tthis.#dirty = true;\n\t\tfor (const value of this.#values.values()) value.recomposed();\n\t}\n\n\t/**\n\t * Builds the table and composes it, unless it is the last one composed, entry for entry (`compose` is pure). A\n\t * throw is a failure episode: reported once, the last good composition kept while every contribution it was built\n\t * from is still in the table (decision 5: one whose contributor ended may hold a closed native); conflicts are\n\t * reported once per episode, as their message and plugins.\n\t */\n\t#recompose({ version, provider }: Provider): void {\n\t\tthis.#dirty = false;\n\t\tthis.#composing = true;\n\t\ttry {\n\t\t\tconst table = this.#build(version, provider);\n\t\t\tif (table === this.#table && this.#composition !== NEVER) return;\n\t\t\tthis.#table = table;\n\t\t\tconst conflicts = new Map<string, RegistryConflict>();\n\t\t\tconst context: ComposeContext = {\n\t\t\t\treport: (conflict) =>\n\t\t\t\t\tconflicts.set(`${conflict.message}\\u0000${conflict.plugins.join(\"\\u0000\")}`, conflict),\n\t\t\t};\n\t\t\tlet value: unknown;\n\t\t\ttry {\n\t\t\t\tthis.#batch.count(\"chord.registry.composes\");\n\t\t\t\tvalue = this.#batch.compute(() => provider.compose(table, context));\n\t\t\t} catch (error) {\n\t\t\t\tif (this.#composition.failure === undefined) this.failed(error);\n\t\t\t\tconst { good } = this.#composition;\n\t\t\t\tthis.#composition = {\n\t\t\t\t\tgood: good !== undefined && this.inTable(good.from) ? good : undefined,\n\t\t\t\t\tfailure: { error },\n\t\t\t\t};\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tthis.#composition = { good: { value, from: this.#contributions }, failure: undefined };\n\t\t\tfor (const [key, conflict] of conflicts) {\n\t\t\t\tif (this.#conflicts.has(key)) continue;\n\t\t\t\tthis.#report({ kind: \"registry_conflict\", registry: this.name, ...conflict });\n\t\t\t}\n\t\t\tthis.#conflicts = new Set(conflicts.keys());\n\t\t} finally {\n\t\t\tthis.#composing = false;\n\t\t}\n\t}\n\n\t/** The table of the live contributions now; the last one itself when every entry is the same object. */\n\t#build(version: number, provider: RegistryProvider<unknown, unknown>): RegistryTable<unknown> {\n\t\tconst previous = this.#table;\n\t\tconst table: RegistryEntry<unknown>[] = [];\n\t\tlet same = previous !== undefined;\n\t\tfor (const contribution of this.#contributions) {\n\t\t\tconst entry = contribution.entry(version, provider);\n\t\t\tif (entry === undefined) continue;\n\t\t\tif (same && previous![table.length] !== entry) same = false;\n\t\t\ttable.push(entry);\n\t\t}\n\t\treturn same && previous!.length === table.length ? previous! : table;\n\t}\n}\n\n/** Table order: by plugin name, then type, a facet (no type) first; code point order, never load order. */\nfunction compareContributors(a: RegistryContribution, b: RegistryContribution): number {\n\tconst left = a.contributor;\n\tconst right = b.contributor;\n\tif (left.plugin !== right.plugin) return left.plugin < right.plugin ? -1 : 1;\n\tconst leftType = left.type ?? \"\";\n\tconst rightType = right.type ?? \"\";\n\tif (leftType === rightType) return 0;\n\treturn leftType < rightType ? -1 : 1;\n}\n"]}

package/dist/registries/registry.d.ts

@@ -0,0 +1,74 @@
+import type { Context } from "../context/index.ts";
+import type { NativeObservation, NativeObserver } from "../state/index.ts";
+import type { NativeWatchable, Watchable } from "../watch.ts";
+/**
+ * A registry token: its name (as type names, `[a-z0-9@/._~-]`), the version the bundling plugin was built against, the
+ * contribution type `C` and the composed value type `V`. Shared: every contributor and reader bundles its own copy.
+ */
+export type Registry<C, V> = {
+    readonly kind: "registry";
+    readonly name: string;
+    readonly version: number;
+    /** Type only: `C` in, `V` out. */
+    readonly "~types"?: (contribution: C) => V;
+};
+/** One contribution in a registry's table: its plugin, its object type for an object contributor, its version. */
+export type RegistryEntry<C> = {
+    readonly plugin: string;
+    /** The contributing object's type; absent for a facet. */
+    readonly type?: string;
+    /** The registry version its contributor was built against (an older one adapted to `C`). */
+    readonly version: number;
+    readonly value: C;
+};
+/** A registry's table: one entry per live contributor, sorted by plugin name, then type (a facet's first). */
+export type RegistryTable<C> = readonly RegistryEntry<C>[];
+/** A conflict `compose` resolved with its fallback: reported as `registry_conflict`, once per conflict episode. */
+export type RegistryConflict = {
+    readonly message: string;
+    readonly plugins: readonly string[];
+};
+/** What `compose` gets besides the table. */
+export type ComposeContext = {
+    /** Reports a conflict `compose` resolved (the first by plugin name wins, for example). */
+    report(conflict: RegistryConflict): void;
+};
+/**
+ * Adapters of older versions, by version, the provider's code: `contribution` maps an older contribution to `C` (once
+ * per contribution value), `value` maps the composed value back for a reader of that version (once per composition).
+ * A plugin annotates the old contribution's type (`(old: HttpV1) => upgrade(old)`).
+ */
+export type RegistryAccepts<C, V> = {
+    readonly [version: number]: {
+        readonly contribution?: (old: never) => C;
+        readonly value?: (current: V) => unknown;
+    };
+};
+/** What the defining plugin's facet serves a registry with (`host.serve(R, provider)`). */
+export type RegistryProvider<C, V> = {
+    /**
+     * Composes the table: pure and synchronous, always a value (a fallback built in), conflicts reported. Runs when the
+     * table changed and someone reads or follows the value; a throw is the owner's bug (`registry_failed`, the last
+     * good composition stays).
+     */
+    readonly compose: (table: RegistryTable<C>, context: ComposeContext) => V;
+    readonly accepts?: RegistryAccepts<C, V>;
+};
+/** What a contributor contributes: a plain value, or a Chord watchable of one (followed: its change recomposes). */
+export type Contribution<C> = C | Watchable<C> | NativeWatchable<C>;
+/**
+ * A registry's composed value as a reader of one version sees it (`self.registry`, `host.registry`): a native
+ * watchable; `.value` is the last good composition (a later throwing `compose` keeps it), a watch gets each new one.
+ */
+export interface RegistryValue<V> extends NativeWatchable<V> {
+    /**
+     * A synchronous observer of its compositions (as Durable's `observeXXX`): `advance` runs inside the batch that
+     * composed, so it only records; an attached observer counts as watching, so the composition runs for it.
+     */
+    observe(observer: NativeObserver<V>, context: Context): NativeObservation<V>;
+}
+/** Declares a registry token: `name` and the `version` this plugin is built against. */
+export declare function defineRegistry<C, V>(name: string, options: {
+    readonly version: number;
+}): Registry<C, V>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registries/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/registries/registry.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,EAAE,CAAC,IAAI;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC;CAC3C,CAAC;AAEF,kHAAkH;AAClH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CAClB,CAAC;AAEF,8GAA8G;AAC9G,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,SAAS,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;AAE3D,mHAAmH;AACnH,MAAM,MAAM,gBAAgB,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAEjG,6CAA6C;AAC7C,MAAM,MAAM,cAAc,GAAG;IAC5B,0FAA0F;IAC1F,MAAM,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACzC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,EAAE,CAAC,IAAI;IACnC,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG;QAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,CAAC,CAAC;QAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC;KACzC,CAAC;CACF,CAAC;AAEF,2FAA2F;AAC3F,MAAM,MAAM,gBAAgB,CAAC,CAAC,EAAE,CAAC,IAAI;IACpC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,KAAK,CAAC,CAAC;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CACzC,CAAC;AAEF,oHAAoH;AACpH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;AAEpE;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,CAAE,SAAQ,eAAe,CAAC,CAAC,CAAC;IAC3D;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC;CAC7E;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAMxG"}

package/dist/registries/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/registries/registry.ts"],"names":[],"mappings":"AAAA,oHAAoH;AACpH,wHAAwH;AACxH,qCAAqC;AAGrC,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AA4ElD,wFAAwF;AACxF,MAAM,UAAU,cAAc,CAAO,IAAY,EAAE,OAAqC;IACvF,SAAS,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAC5B,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAC5B,2DAA2D;IAC3D,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,uCAAuC,CAAC,CAAC;IACnH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC5C,CAAC","sourcesContent":["// Registry tokens (design §17, slice 8 D1): `defineRegistry`, shared by every plugin as a contract is (identity and\n// types only), and what the defining plugin's facet serves it with (`compose`, `accepts`); the table `compose` gets and\n// the composed value readers follow.\n\nimport type { Context } from \"../context/index.ts\";\nimport { checkName } from \"../contracts/names.ts\";\nimport type { NativeObservation, NativeObserver } from \"../state/index.ts\";\nimport type { NativeWatchable, Watchable } from \"../watch.ts\";\n\n/**\n * A registry token: its name (as type names, `[a-z0-9@/._~-]`), the version the bundling plugin was built against, the\n * contribution type `C` and the composed value type `V`. Shared: every contributor and reader bundles its own copy.\n */\nexport type Registry<C, V> = {\n\treadonly kind: \"registry\";\n\treadonly name: string;\n\treadonly version: number;\n\t/** Type only: `C` in, `V` out. */\n\treadonly \"~types\"?: (contribution: C) => V;\n};\n\n/** One contribution in a registry's table: its plugin, its object type for an object contributor, its version. */\nexport type RegistryEntry<C> = {\n\treadonly plugin: string;\n\t/** The contributing object's type; absent for a facet. */\n\treadonly type?: string;\n\t/** The registry version its contributor was built against (an older one adapted to `C`). */\n\treadonly version: number;\n\treadonly value: C;\n};\n\n/** A registry's table: one entry per live contributor, sorted by plugin name, then type (a facet's first). */\nexport type RegistryTable<C> = readonly RegistryEntry<C>[];\n\n/** A conflict `compose` resolved with its fallback: reported as `registry_conflict`, once per conflict episode. */\nexport type RegistryConflict = { readonly message: string; readonly plugins: readonly string[] };\n\n/** What `compose` gets besides the table. */\nexport type ComposeContext = {\n\t/** Reports a conflict `compose` resolved (the first by plugin name wins, for example). */\n\treport(conflict: RegistryConflict): void;\n};\n\n/**\n * Adapters of older versions, by version, the provider's code: `contribution` maps an older contribution to `C` (once\n * per contribution value), `value` maps the composed value back for a reader of that version (once per composition).\n * A plugin annotates the old contribution's type (`(old: HttpV1) => upgrade(old)`).\n */\nexport type RegistryAccepts<C, V> = {\n\treadonly [version: number]: {\n\t\treadonly contribution?: (old: never) => C;\n\t\treadonly value?: (current: V) => unknown;\n\t};\n};\n\n/** What the defining plugin's facet serves a registry with (`host.serve(R, provider)`). */\nexport type RegistryProvider<C, V> = {\n\t/**\n\t * Composes the table: pure and synchronous, always a value (a fallback built in), conflicts reported. Runs when the\n\t * table changed and someone reads or follows the value; a throw is the owner's bug (`registry_failed`, the last\n\t * good composition stays).\n\t */\n\treadonly compose: (table: RegistryTable<C>, context: ComposeContext) => V;\n\treadonly accepts?: RegistryAccepts<C, V>;\n};\n\n/** What a contributor contributes: a plain value, or a Chord watchable of one (followed: its change recomposes). */\nexport type Contribution<C> = C | Watchable<C> | NativeWatchable<C>;\n\n/**\n * A registry's composed value as a reader of one version sees it (`self.registry`, `host.registry`): a native\n * watchable; `.value` is the last good composition (a later throwing `compose` keeps it), a watch gets each new one.\n */\nexport interface RegistryValue<V> extends NativeWatchable<V> {\n\t/**\n\t * A synchronous observer of its compositions (as Durable's `observeXXX`): `advance` runs inside the batch that\n\t * composed, so it only records; an attached observer counts as watching, so the composition runs for it.\n\t */\n\tobserve(observer: NativeObserver<V>, context: Context): NativeObservation<V>;\n}\n\n/** Declares a registry token: `name` and the `version` this plugin is built against. */\nexport function defineRegistry<C, V>(name: string, options: { readonly version: number }): Registry<C, V> {\n\tcheckName(name, \"registry\");\n\tconst { version } = options;\n\t// Declaration policy: JavaScript callers reach this check.\n\tif (!Number.isSafeInteger(version) || version < 1) throw new Error(`${name}.version: expected a positive integer`);\n\treturn { kind: \"registry\", name, version };\n}\n"]}

package/dist/registries/value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value.d.ts","sourceRoot":"","sources":["../../src/registries/value.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,UAAU,EAAgB,MAAM,kBAAkB,CAAC;AAE5D,OAAO,EAAE,KAAK,KAAK,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEpF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,6GAA6G;AAC7G,MAAM,WAAW,cAAc;IAC9B,sEAAsE;IACtE,eAAe,IAAI,IAAI,CAAC;IACxB,sFAAsF;IACtF,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CAChC;AAiCD,yDAAyD;AACzD,qBAAa,mBAAoB,SAAQ,cAAc,CAAC,OAAO,CAAC;;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAczB,YAAY,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAKhE;IAED,sGAAsG;IACtG,IAAI,KAAK,IAAI,OAAO,CAKnB;IAED;;;OAGG;IACM,KAAK,IAAI,WAAW,CAAC,OAAO,CAAC,CAMrC;IAED,4GAA4G;IACnG,OAAO,IAAI,OAAO,CAI1B;IAED,mFAAmF;IACnF,IAAa,OAAO,IAAI,OAAO,CAE9B;IAED,kHAAkH;IAClH,IAAI,IAAI,MAAM,IAAI,CAOjB;IAED;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,IAAI,CAWvC;IAED,kHAAkH;IAClH,UAAU,IAAI,IAAI,CAEjB;IAED;;;;OAIG;IACH,QAAQ,IAAI,IAAI,CAEf;IAED,gHAAgH;IAChH,KAAK,IAAI,IAAI,CAmBZ;IAED,8FAA8F;IAC9F,UAAmB,UAAU,IAAI,IAAI,CAEpC;CA4ED"}

package/dist/registries/value.js

@@ -0,0 +1,224 @@
+// Registry values (slice 8 §1 "Reading", S2, S3): a registry's composed value as the readers of one version see it, a
+// native source. The provider's version reads the composition itself; an older one reads it mapped back with
+// `accepts[old].value`, once per composition, kept only while someone reads or follows it; a version the provider
+// cannot serve fails `contract_mismatch`. Its readers (attempts that declared it) keep the mapping; its waiters
+// (attempts parked on it, a waiting `host.registry`) are woken at every change of whether it is usable, and of its
+// failure while it is not (dependency model §9); waited for while it is not, it is on the host's `UnboundClock`.
+import { ChordError, isChordError } from "../data/index.js";
+import { asChordError } from "../data/internal.js";
+import { FollowedSource } from "../state/internal.js";
+const USABLE = { kind: "usable" };
+/** Whether two failures say the same: the same error, or ChordErrors alike (a version mismatch is made per read). */
+function sameError(a, b) {
+    if (a === b)
+        return true;
+    return isChordError(a) && isChordError(b) && a.code === b.code && a.reason === b.reason && a.message === b.message;
+}
+/** One version's view of a registry's composed value. */
+export class RegistryValueSource extends FollowedSource {
+    name;
+    version;
+    #registered;
+    /** Its readers, each a token of its own (one object may read twice), until released. */
+    #readers = new Set();
+    /** Its waiters, each a token of its own, until released. */
+    #waiters = new Set();
+    /**
+     * What its waiters were last told: usable (a value, or a failure with a last good one), or the error it has none
+     * for; a change wakes them.
+     */
+    #told;
+    #mapped;
+    #mapFailure;
+    constructor(record, version, batch) {
+        super(batch);
+        this.name = record.name;
+        this.version = version;
+        this.#registered = { kind: "open", record };
+    }
+    /** The composition (or its mapping) at its last good value; throws the failure when there is none. */
+    get value() {
+        const start = this.start();
+        if (start.kind === "value")
+            return start.value;
+        if (start.last === undefined)
+            throw start.error;
+        return start.last.value;
+    }
+    /**
+     * Its composition (mapped for an older version), composed now if its table changed; a change of whether it is
+     * usable, or of its failure while it is not, wakes its waiters.
+     */
+    start() {
+        const registered = this.#registered;
+        if (registered.kind === "closed")
+            return registered.last;
+        const start = this.#start(registered.record);
+        if (this.#waiters.size > 0)
+            this.#tell(start, registered.record);
+        return start;
+    }
+    /** Its composition (or mapping) now; throws while it is failed, though `.value` keeps the last good one. */
+    current() {
+        const start = this.start();
+        if (start.kind === "failed")
+            throw start.error;
+        return start.value;
+    }
+    /** Followed while someone watches or observes it, and while waiters wait on it. */
+    get watched() {
+        return super.watched || this.#waiters.size > 0;
+    }
+    /** Registers a reader (an attempt that declared it) until the returned release: its mapping is kept meanwhile. */
+    read() {
+        const token = {};
+        this.#readers.add(token);
+        return () => {
+            this.#readers.delete(token);
+            if (this.#readers.size === 0 && !super.watched)
+                this.#dropMapping();
+        };
+    }
+    /**
+     * Registers `waiter` (a parked attempt's object, a waiting `host.registry`) until the returned release: it is told
+     * of every change of whether this value is usable (inside the batch that made it: it only records).
+     */
+    wait(waiter) {
+        const token = { waiter };
+        if (this.#waiters.size === 0)
+            this.#told = undefined;
+        this.#waiters.add(token);
+        return () => {
+            this.#waiters.delete(token);
+            if (this.#waiters.size > 0)
+                return;
+            this.#told = undefined;
+            const registered = this.#registered;
+            if (registered.kind === "open")
+                registered.record.clock.stop(this);
+        };
+    }
+    /** The registry's table changed (inside a batch): its dependents are marked, its followers get the next frame. */
+    recomposed() {
+        this.changed();
+    }
+    /**
+     * The registry's table changed again while not composed since (inside a batch): its dependents are marked already
+     * (none read it meanwhile, or it would be composed); its followers get the next frame. Marking stops here, so a
+     * cycle of registries through their values ends.
+     */
+    relisted() {
+        this.list();
+    }
+    /** The host closed: its watches and observers end, its readers and mapping go; it keeps its last start only. */
+    close() {
+        const registered = this.#registered;
+        let last;
+        try {
+            last = this.start();
+        }
+        catch (error) {
+            last = { kind: "failed", error, last: undefined };
+        }
+        // After the last start, which a waiter put on the clock again.
+        if (registered.kind === "open")
+            registered.record.clock.stop(this);
+        this.#registered = { kind: "closed", last };
+        this.#readers.clear();
+        const waiters = [...this.#waiters];
+        this.#waiters.clear();
+        const error = new ChordError({ code: "released", reason: "closed", message: `registry ${this.name}: closed` });
+        for (const { waiter } of waiters)
+            waiter.closed(error);
+        this.#told = undefined;
+        this.#dropMapping();
+        this.end();
+    }
+    /** Nobody follows it: without readers, its mapping goes (computed again on the next read). */
+    unfollowed() {
+        if (this.#readers.size === 0)
+            this.#dropMapping();
+    }
+    /**
+     * Wakes the waiters when `start` says something else than they were told (by usability, then by the error); while
+     * it is not usable, the wait is on its host's clock (`record.clock`).
+     */
+    #tell(start, record) {
+        const told = this.#told;
+        if (start.kind === "value" || start.last !== undefined) {
+            if (told?.kind === "usable")
+                return;
+            this.#told = USABLE;
+            record.clock.stop(this);
+        }
+        else {
+            if (told?.kind === "failed" && sameError(told.error, start.error))
+                return;
+            this.#told = { kind: "failed", error: start.error };
+            const label = `registry ${this.name}`;
+            const error = asChordError(start.error, label);
+            if (told?.kind === "failed")
+                record.clock.failed(this, error);
+            else
+                record.clock.start(this, label, error);
+        }
+        // The first start of a wait wakes nobody: the waiter reads it itself.
+        if (told === undefined)
+            return;
+        for (const { waiter } of this.#waiters)
+            waiter.dependencyMoved();
+    }
+    #dropMapping() {
+        this.#mapped = undefined;
+        this.#mapFailure = undefined;
+    }
+    #start(record) {
+        const provided = record.providedVersion;
+        if (provided === undefined || provided === this.version)
+            return record.start();
+        const map = provided > this.version ? record.valueAdapter(this.version) : undefined;
+        if (map === undefined) {
+            const message = `registry ${this.name}: version ${this.version} is not served here (version ${provided} is)`;
+            return { kind: "failed", error: new ChordError({ code: "contract_mismatch", message }), last: undefined };
+        }
+        return this.#mappedStart(record, record.start(), map);
+    }
+    /**
+     * The composition `current` mapped back with `map`, once per composition; a throwing mapping fails this version
+     * only (reported once per episode), keeping its last good mapping; a composition mapped before heals it.
+     */
+    #mappedStart(record, current, map) {
+        if (current.kind === "failed" && current.last === undefined)
+            return current;
+        const from = current.kind === "value" ? current.value : current.last.value;
+        // `undefined` is a composition too: the records, not their fields, say whether there is one.
+        // A mapping built from a contribution that left is no last good value any more (decision 5).
+        if (this.#mapped?.contributions !== undefined && !record.inTable(this.#mapped.contributions)) {
+            this.#mapped = undefined;
+        }
+        const mapped = this.#mapped;
+        const failure = this.#mapFailure;
+        if (mapped !== undefined && mapped.from === from && mapped.map === map) {
+            this.#mapFailure = undefined;
+        }
+        else if (failure === undefined || failure.from !== from || failure.map !== map) {
+            try {
+                const value = record.adapt(() => map(from));
+                this.#mapped = { from, map, value, contributions: record.composedFrom };
+                this.#mapFailure = undefined;
+            }
+            catch (error) {
+                if (failure === undefined)
+                    record.failed(error);
+                this.#mapFailure = { from, map, error };
+            }
+        }
+        const last = this.#mapped === undefined ? undefined : { value: this.#mapped.value };
+        if (this.#mapFailure !== undefined)
+            return { kind: "failed", error: this.#mapFailure.error, last };
+        if (current.kind === "failed")
+            return { kind: "failed", error: current.error, last };
+        return { kind: "value", value: last.value };
+    }
+}
+//# sourceMappingURL=value.js.map