@fougere/core 0.2.0-alpha.2 → 0.4.0-alpha.0

package/README.md

@@ -5,7 +5,8 @@ strictly locally; `createAppRunner` follows the topology (local façades, remote
 stand-ins). Transports move the value — they never reshape it.
 
 The façade judges the input, projects the output, and exposes only what a contract
-declares.
+declares. It also canonicalizes optional input before binding: omission is `undefined`,
+JSON may omit its property, and an explicit `null` is never rewritten.
 
 Node-free surface, for the browser: the `@fougere/core/contract` subpath.
 
@@ -18,4 +19,4 @@ pnpm add @fougere/core
 
 Part of [Fougere](https://github.com/chok/fougere) — one schema, a gradient from
 monolith to distributed, the same user code.
-Reference documentation: [the site](https://chok.github.io/fougere/) (en/fr).
+Reference documentation: [the site](https://fougere.dev/) (en/fr).

package/dist/boot/AppLifecycle.d.ts

@@ -0,0 +1,18 @@
+import type { App } from './types.js';
+/** One process-level extension and its reversible lifecycle. */
+export interface Extension {
+    name: string;
+    up?(app: App): void | Promise<void>;
+    down?(app: App): void | Promise<void>;
+}
+/** Runs application extensions up in order and down in reverse order. */
+export declare class AppLifecycle {
+    private readonly members;
+    add(...extensions: readonly (Extension | undefined)[]): this;
+    names(): string[];
+    up(app: App): Promise<void>;
+    down(app: App): Promise<void>;
+}
+/** The replaceable migration slot of the application lifecycle. */
+export declare function migrating(migrate?: Extension['up']): Extension;
+//# sourceMappingURL=AppLifecycle.d.ts.map

package/dist/boot/AppLifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppLifecycle.d.ts","sourceRoot":"","sources":["../../src/boot/AppLifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEtC,gEAAgE;AAChE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,yEAAyE;AACzE,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAE3C,GAAG,CAAC,GAAG,UAAU,EAAE,SAAS,CAAC,SAAS,GAAG,SAAS,CAAC,EAAE,GAAG,IAAI;IAU5D,KAAK,IAAI,MAAM,EAAE;IAIX,EAAE,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3B,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;CAapC;AAED,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,SAAS,CAE9D"}

package/dist/boot/AppLifecycle.js

@@ -0,0 +1,42 @@
+/** Runs application extensions up in order and down in reverse order. */
+export class AppLifecycle {
+    members = [];
+    add(...extensions) {
+        for (const extension of extensions) {
+            if (!extension)
+                continue;
+            const at = this.members.findIndex((held) => held.name === extension.name);
+            if (at === -1)
+                this.members.push(extension);
+            else
+                this.members[at] = extension;
+        }
+        return this;
+    }
+    names() {
+        return this.members.map((extension) => extension.name);
+    }
+    async up(app) {
+        for (const extension of this.members)
+            await extension.up?.(app);
+    }
+    async down(app) {
+        const refused = [];
+        for (const extension of [...this.members].reverse()) {
+            try {
+                await extension.down?.(app);
+            }
+            catch (error) {
+                refused.push(error);
+            }
+        }
+        if (refused.length > 0) {
+            throw new AggregateError(refused, `${refused.length} extension(s) refused to release`);
+        }
+    }
+}
+/** The replaceable migration slot of the application lifecycle. */
+export function migrating(migrate) {
+    return migrate ? { name: 'migrate', up: migrate } : { name: 'migrate' };
+}
+//# sourceMappingURL=AppLifecycle.js.map

package/dist/boot/AppLifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppLifecycle.js","sourceRoot":"","sources":["../../src/boot/AppLifecycle.ts"],"names":[],"mappings":"AASA,yEAAyE;AACzE,MAAM,OAAO,YAAY;IACN,OAAO,GAAgB,EAAE,CAAC;IAE3C,GAAG,CAAC,GAAG,UAA8C;QACnD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,IAAI,CAAC,SAAS;gBAAE,SAAS;YACzB,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,IAAI,CAAC,CAAC;YAC1E,IAAI,EAAE,KAAK,CAAC,CAAC;gBAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;;gBACvC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;QACpC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,EAAE,CAAC,GAAQ;QACf,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,SAAS,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;IAClE,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAQ;QACjB,MAAM,OAAO,GAAc,EAAE,CAAC;QAC9B,KAAK,MAAM,SAAS,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;YACpD,IAAI,CAAC;gBACH,MAAM,SAAS,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;YAC9B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,cAAc,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,kCAAkC,CAAC,CAAC;QACzF,CAAC;IACH,CAAC;CACF;AAED,mEAAmE;AACnE,MAAM,UAAU,SAAS,CAAC,OAAyB;IACjD,OAAO,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC1E,CAAC"}

package/dist/boot/Emissions.d.ts

@@ -0,0 +1,126 @@
+import { type SchemaView } from '@fougere/schema';
+import type { Container } from '@fougere/container';
+import type { Logger } from '../builtins/logger.js';
+import type { Fronds } from '../scan/Fronds.js';
+import type { OperationsMap } from '../wire/operation.js';
+/** Carries an announced fact out of this process — see `CreateAppOptions.onEmit`. */
+type Carrier = (fact: string, payload: unknown) => void | Promise<void>;
+/**
+ * Emissions — the only place in Fougere where an initiator names a SUBJECT.
+ *
+ * It was eight closures over four collections in the middle of the boot, which is a
+ * class that had not been named: the announced set, the subscriber index, the chain
+ * carried in async context, and the shapes a fact is judged against.
+ *
+ * **It is a resolver, not a channel.** It answers *who*, then hands over to the door
+ * that already exists — so a subscriber keeps its judge, its binding and its
+ * middlewares, and nothing here is durable.
+ */
+export declare class Emissions {
+    private readonly shapes;
+    private readonly container;
+    private readonly log;
+    private readonly carry?;
+    /** Who listens to what. Filled as each door's contracts are resolved. */
+    private readonly subscribers;
+    /**
+     * What is announced here, read from the DEPS and not from the subscribers: a handler
+     * declaring `Emit<PostPublished>` must resolve it whether or not anybody listens, and
+     * announcing to nobody is legal.
+     */
+    private readonly announced;
+    constructor(fronds: Fronds, shapes: Map<string, SchemaView>, container: Container, log: Logger, carry?: Carrier | undefined);
+    /**
+     * Who listens to what — read from the PLAN, where `{ kind: 'fact' }` is a sentence
+     * `computeBindingPlan` already wrote, so nothing re-derives what a parameter is.
+     *
+     * It is called for a frond hosted here AND for one declared remote. A remote frond is
+     * still scanned — only its hosting is elsewhere — so its subscriptions are known, and
+     * its door resolves to a doublure. That is the whole reason an emission crosses a
+     * process without a line of transport code: the emitter learned the signature locally
+     * and calls the same key. Noting only the hosted ones left the index EMPTY under a
+     * split, and a fact announced to a remote listener reached nobody, in silence.
+     */
+    note(contracts: OperationsMap, door: string): void;
+    /** The shape a fact is judged by, when the fact is a declared entity. */
+    shapeOf(fact: string): SchemaView | undefined;
+    /** The facts this process has a listener for — what a carrier subscribes to on its behalf. */
+    listensTo(): string[];
+    /**
+     * Register one emission value per fact — announced here, or merely listened to.
+     *
+     * A process that only subscribes still needs the value, because `deliver` is what a
+     * carrier calls and it goes through the same door. Called once every door has been
+     * built, so the two sets are complete.
+     */
+    register(): void;
+    /**
+     * Announcing. Dispatch, never delivery — the emitter is handed back the moment every
+     * subscriber has been HANDED the fact, not when any of them is done.
+     *
+     * The `EventBus` this replaces did `await Promise.all(handlers)` and passed their
+     * rejections up, which made a publication hostage to its own indexer.
+     */
+    private announce;
+    /**
+     * Receiving. **The opposite rule, deliberately**: this one waits, and it tells.
+     *
+     * `deliver` is what a CARRIER calls, and a carrier's whole job is to know whether the
+     * fact landed — at-least-once is retrying what failed, so a delivery that cannot report
+     * makes durability impossible to build on top. It used to be the announcement itself:
+     * it resolved before any subscriber had run and swallowed every failure into a log, so a
+     * queue calling it could only ever ack blindly.
+     *
+     * That is not a contradiction of "dispatch is not delivery". That rule protects the
+     * EMITTER, which must not become hostage to a subscriber; a carrier is not the emitter,
+     * it is precisely the party whose business this is.
+     *
+     * What it still does not do is HOLD anything. A fact refused here is refused, and the
+     * carrier decides whether it comes back — which is the whole of Fougere's position on
+     * durability: the channel goes underneath, it is not reimplemented here.
+     */
+    deliver(fact: string, payload: unknown): Promise<void>;
+    /**
+     * The announcement realizes the fact's own `lifecycle.create` — a `created()` stamped,
+     * an id generated, a default applied.
+     *
+     * `applyCreate` (`schema/src/axis/lifecycle/apply.ts`) is where the split is realized:
+     * the judge never fills a hole, the STORAGE does, at the point of persistence. A fact has no storage, so nobody did — the judge declared an
+     * absent `created()` legal and omitted it, and a subscriber received a value missing a
+     * field its own type promises. Announcing is a fact's point of persistence.
+     *
+     * Announcing only, never `deliver`: a fact that arrives from elsewhere was stamped by
+     * its sender, and stamping it again would give one fact a different identity in every
+     * process that relayed it.
+     *
+     * **A typed emitter cannot reach this yet.** `Emit<T>` names the ROW type, where a
+     * `created()` field is present and required, so `announce({ id, title })` is a compile
+     * error and the author writes `at: new Date()` anyway. So this runs for a payload built
+     * outside the type — a bridge, a replay, a test — and is inert for everyone else.
+     */
+    private stamped;
+    /**
+     * Hand the fact to every listener in THIS process, and give back one promise each.
+     *
+     * The call goes THROUGH the door, so a subscriber meets the same judge, the same binding
+     * and the same middlewares as any caller. Nothing new answers for correctness — that is
+     * the dividend of a subscriber being an ordinary op rather than a special kind.
+     *
+     * It returns the promises rather than settling them, because the two callers want
+     * opposite things and only one of them is wrong to wait.
+     */
+    private handToListeners;
+    /**
+     * A subscriber refusing the SHAPE, said in one line instead of dumped as an error.
+     *
+     * This is the one refusal nobody else will ever see. A door hands its 400 back to the
+     * caller who can fix it; a fact is dispatched, not delivered, so the sender learns
+     * nothing and the log is the whole of the evidence. The most likely cause is also the
+     * one a stack trace hides worst — this process's copy is older than the sender's — so
+     * the line names the fields and the remedy, and hedges because a genuinely bad payload
+     * produces the same refusal.
+     */
+    private describeRefusal;
+}
+export {};
+//# sourceMappingURL=Emissions.d.ts.map

package/dist/boot/Emissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Emissions.d.ts","sourceRoot":"","sources":["../../src/boot/Emissions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAKpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAQ1D,qFAAqF;AACrF,KAAK,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAExE;;;;;;;;;;GAUG;AACH,qBAAa,SAAS;IAalB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IAfzB,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiC;IAE7D;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;gBAGtC,MAAM,EAAE,MAAM,EACG,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAC/B,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,MAAM,EACX,KAAK,CAAC,EAAE,OAAO,YAAA;IAKlC;;;;;;;;;;OAUG;IACH,IAAI,CAAC,SAAS,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAWlD,yEAAyE;IACzE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI7C,8FAA8F;IAC9F,SAAS,IAAI,MAAM,EAAE;IAIrB;;;;;;OAMG;IACH,QAAQ,IAAI,IAAI;IAShB;;;;;;OAMG;YACW,QAAQ;IAuCtB;;;;;;;;;;;;;;;;OAgBG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB5D;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,OAAO;IAOf;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;IA8BvB;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;CAMxB"}

package/dist/boot/Emissions.js

@@ -0,0 +1,233 @@
+import { applyCreate } from '@fougere/schema';
+import { validationErrorsOf } from '../wire/errors.js';
+import { emitKeyOf, factsAnnouncedBy } from '../emit.js';
+import { ambient } from '#ambient';
+import { EMPTY_INVOCATION } from '../wire/invocation.js';
+/**
+ * Emissions — the only place in Fougere where an initiator names a SUBJECT.
+ *
+ * It was eight closures over four collections in the middle of the boot, which is a
+ * class that had not been named: the announced set, the subscriber index, the chain
+ * carried in async context, and the shapes a fact is judged against.
+ *
+ * **It is a resolver, not a channel.** It answers *who*, then hands over to the door
+ * that already exists — so a subscriber keeps its judge, its binding and its
+ * middlewares, and nothing here is durable.
+ */
+export class Emissions {
+    shapes;
+    container;
+    log;
+    carry;
+    /** Who listens to what. Filled as each door's contracts are resolved. */
+    subscribers = new Map();
+    /**
+     * What is announced here, read from the DEPS and not from the subscribers: a handler
+     * declaring `Emit<PostPublished>` must resolve it whether or not anybody listens, and
+     * announcing to nobody is legal.
+     */
+    announced;
+    constructor(fronds, shapes, container, log, carry) {
+        this.shapes = shapes;
+        this.container = container;
+        this.log = log;
+        this.carry = carry;
+        this.announced = new Set(fronds.flatMap((frond) => factsAnnouncedBy(frond.handlers)));
+    }
+    /**
+     * Who listens to what — read from the PLAN, where `{ kind: 'fact' }` is a sentence
+     * `computeBindingPlan` already wrote, so nothing re-derives what a parameter is.
+     *
+     * It is called for a frond hosted here AND for one declared remote. A remote frond is
+     * still scanned — only its hosting is elsewhere — so its subscriptions are known, and
+     * its door resolves to a doublure. That is the whole reason an emission crosses a
+     * process without a line of transport code: the emitter learned the signature locally
+     * and calls the same key. Noting only the hosted ones left the index EMPTY under a
+     * split, and a fact announced to a remote listener reached nobody, in silence.
+     */
+    note(contracts, door) {
+        for (const [op, contract] of contracts) {
+            for (const bound of contract.binding ?? []) {
+                if (bound.source.kind !== 'fact')
+                    continue;
+                const listeners = this.subscribers.get(bound.source.factName) ?? [];
+                listeners.push({ door, op });
+                this.subscribers.set(bound.source.factName, listeners);
+            }
+        }
+    }
+    /** The shape a fact is judged by, when the fact is a declared entity. */
+    shapeOf(fact) {
+        return this.shapes.get(fact);
+    }
+    /** The facts this process has a listener for — what a carrier subscribes to on its behalf. */
+    listensTo() {
+        return [...this.subscribers.keys()];
+    }
+    /**
+     * Register one emission value per fact — announced here, or merely listened to.
+     *
+     * A process that only subscribes still needs the value, because `deliver` is what a
+     * carrier calls and it goes through the same door. Called once every door has been
+     * built, so the two sets are complete.
+     */
+    register() {
+        for (const fact of new Set([...this.announced, ...this.subscribers.keys()])) {
+            this.container.registerValue(emitKeyOf(fact), (raw) => this.announce(fact, raw));
+        }
+        if (ambient.degraded && this.subscribers.size > 0) {
+            this.log.warn('no async context on this runtime — an emission ring is not detected');
+        }
+    }
+    /**
+     * Announcing. Dispatch, never delivery — the emitter is handed back the moment every
+     * subscriber has been HANDED the fact, not when any of them is done.
+     *
+     * The `EventBus` this replaces did `await Promise.all(handlers)` and passed their
+     * rejections up, which made a publication hostage to its own indexer.
+     */
+    async announce(fact, raw) {
+        /**
+         * A fact announced inside a frame that then rolls back is a lie, and nothing can take
+         * it back: announcing is DISPATCH — every subscriber has been handed the fact and the
+         * carrier has already put it on the wire — while the frame's writes are still
+         * provisional.
+         *
+         * Refused rather than deferred to the commit. Deferring would make `Emit<T>` behave
+         * differently depending on where it is called from, which is the hidden runtime the
+         * doctrine refuses; and it opens a window between the commit and the announcement whose
+         * only remedy is an outbox — a table, therefore durability, the one thing Fougere says
+         * it does not hold.
+         *
+         * A fact designates something that HAS happened. `run` returning is when that becomes
+         * true, so that is where the announcement belongs.
+         */
+        await ambient.beforeAnnounce(fact);
+        const payload = this.stamped(fact, raw);
+        /**
+         * Whoever is not in this process — and it is the ONLY way to reach them.
+         *
+         * The local dispatch finds its listeners by having READ their code, so it stops at
+         * the repository boundary: another team's Frond is not on this disk, and the
+         * emission reaches nobody. A carrier hands the fact to a name instead, and the far
+         * side subscribes to that same name from ITS own code. Neither reads the other.
+         *
+         * `deliver` deliberately does NOT come here: a hub that resolved this value to hand
+         * on an incoming reading echoed it straight back to the whole fleet.
+         */
+        const carried = this.carry?.(fact, payload);
+        if (carried)
+            void Promise.resolve(carried).catch((cause) => this.log.error(`${fact} — carrier refused it`, cause));
+        for (const { door, op, done } of this.handToListeners(fact, payload)) {
+            void done.catch((cause) => this.log.error(`${fact} → ${door}.${op}`, this.describeRefusal(fact, cause) ?? cause));
+        }
+    }
+    /**
+     * Receiving. **The opposite rule, deliberately**: this one waits, and it tells.
+     *
+     * `deliver` is what a CARRIER calls, and a carrier's whole job is to know whether the
+     * fact landed — at-least-once is retrying what failed, so a delivery that cannot report
+     * makes durability impossible to build on top. It used to be the announcement itself:
+     * it resolved before any subscriber had run and swallowed every failure into a log, so a
+     * queue calling it could only ever ack blindly.
+     *
+     * That is not a contradiction of "dispatch is not delivery". That rule protects the
+     * EMITTER, which must not become hostage to a subscriber; a carrier is not the emitter,
+     * it is precisely the party whose business this is.
+     *
+     * What it still does not do is HOLD anything. A fact refused here is refused, and the
+     * carrier decides whether it comes back — which is the whole of Fougere's position on
+     * durability: the channel goes underneath, it is not reimplemented here.
+     */
+    async deliver(fact, payload) {
+        const handed = this.handToListeners(fact, payload);
+        const settled = await Promise.allSettled(handed.map((h) => h.done));
+        const refused = settled.flatMap((result, i) => result.status === 'rejected' ? [{ ...handed[i], reason: result.reason }] : []);
+        for (const { door, op, reason } of refused) {
+            this.log.error(`${fact} → ${door}.${op}`, this.describeRefusal(fact, reason) ?? reason);
+        }
+        if (refused.length > 0) {
+            throw new AggregateError(refused.map((r) => r.reason), `${fact} — ${refused.length} of ${handed.length} listener(s) refused it`
+                + ` (${refused.map((r) => `${r.door}.${r.op}`).join(', ')}).`
+                + ` Nothing here holds it: the carrier decides whether it comes back.`);
+        }
+    }
+    /**
+     * The announcement realizes the fact's own `lifecycle.create` — a `created()` stamped,
+     * an id generated, a default applied.
+     *
+     * `applyCreate` (`schema/src/axis/lifecycle/apply.ts`) is where the split is realized:
+     * the judge never fills a hole, the STORAGE does, at the point of persistence. A fact has no storage, so nobody did — the judge declared an
+     * absent `created()` legal and omitted it, and a subscriber received a value missing a
+     * field its own type promises. Announcing is a fact's point of persistence.
+     *
+     * Announcing only, never `deliver`: a fact that arrives from elsewhere was stamped by
+     * its sender, and stamping it again would give one fact a different identity in every
+     * process that relayed it.
+     *
+     * **A typed emitter cannot reach this yet.** `Emit<T>` names the ROW type, where a
+     * `created()` field is present and required, so `announce({ id, title })` is a compile
+     * error and the author writes `at: new Date()` anyway. So this runs for a payload built
+     * outside the type — a bridge, a replay, a test — and is inert for everyone else.
+     */
+    stamped(fact, raw) {
+        const shape = this.shapes.get(fact);
+        return shape && raw !== null && typeof raw === 'object' && !Array.isArray(raw)
+            ? applyCreate(shape.getFields(), raw)
+            : raw;
+    }
+    /**
+     * Hand the fact to every listener in THIS process, and give back one promise each.
+     *
+     * The call goes THROUGH the door, so a subscriber meets the same judge, the same binding
+     * and the same middlewares as any caller. Nothing new answers for correctness — that is
+     * the dividend of a subscriber being an ordinary op rather than a special kind.
+     *
+     * It returns the promises rather than settling them, because the two callers want
+     * opposite things and only one of them is wrong to wait.
+     */
+    handToListeners(fact, payload) {
+        const walked = ambient.currentChain();
+        if (walked.includes(fact)) {
+            throw new Error(`Emission cycle: ${[...walked, fact].join(' → ')}.\n`
+                + `  A fact cannot cause itself. One of the subscribers above announces a fact that leads back here.`);
+        }
+        const listeners = this.subscribers.get(fact) ?? [];
+        if (listeners.length === 0) {
+            this.log.debug(`${fact} — nobody listens in this process`);
+            return [];
+        }
+        return listeners.map(({ door, op }) => ({
+            door,
+            op,
+            done: ambient.enterChain(fact, async () => {
+                let facade;
+                try {
+                    facade = this.container.resolve(door);
+                }
+                catch (cause) {
+                    throw new Error(`${fact} → ${door} could not be reached`, { cause });
+                }
+                return facade[op]({ ...EMPTY_INVOCATION, body: payload });
+            }),
+        }));
+    }
+    /**
+     * A subscriber refusing the SHAPE, said in one line instead of dumped as an error.
+     *
+     * This is the one refusal nobody else will ever see. A door hands its 400 back to the
+     * caller who can fix it; a fact is dispatched, not delivered, so the sender learns
+     * nothing and the log is the whole of the evidence. The most likely cause is also the
+     * one a stack trace hides worst — this process's copy is older than the sender's — so
+     * the line names the fields and the remedy, and hedges because a genuinely bad payload
+     * produces the same refusal.
+     */
+    describeRefusal(fact, cause) {
+        const refusals = validationErrorsOf(cause);
+        if (!refusals?.length)
+            return undefined;
+        return `refused the shape — ${refusals.map((d) => `${d.path}: ${d.message}`).join(', ')}.`
+            + ` If '${fact}' gained a field, this copy is older than the sender's: re-run \`fougere sync\`.`;
+    }
+}
+//# sourceMappingURL=Emissions.js.map

package/dist/boot/Emissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Emissions.js","sourceRoot":"","sources":["../../src/boot/Emissions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAmB,MAAM,iBAAiB,CAAC;AAE/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAczD;;;;;;;;;;GAUG;AACH,MAAM,OAAO,SAAS;IAaD;IACA;IACA;IACA;IAfnB,yEAAyE;IACxD,WAAW,GAAG,IAAI,GAAG,EAAsB,CAAC;IAE7D;;;;OAIG;IACc,SAAS,CAAc;IAExC,YACE,MAAc,EACG,MAA+B,EAC/B,SAAoB,EACpB,GAAW,EACX,KAAe;QAHf,WAAM,GAAN,MAAM,CAAyB;QAC/B,cAAS,GAAT,SAAS,CAAW;QACpB,QAAG,GAAH,GAAG,CAAQ;QACX,UAAK,GAAL,KAAK,CAAU;QAEhC,IAAI,CAAC,SAAS,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,gBAAgB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACxF,CAAC;IAED;;;;;;;;;;OAUG;IACH,IAAI,CAAC,SAAwB,EAAE,IAAY;QACzC,KAAK,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC,IAAI,SAAS,EAAE,CAAC;YACvC,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;gBAC3C,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,MAAM;oBAAE,SAAS;gBAC3C,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;gBACpE,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;gBAC7B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;YACzD,CAAC;QACH,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,OAAO,CAAC,IAAY;QAClB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,8FAA8F;IAC9F,SAAS;QACP,OAAO,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;IACtC,CAAC;IAED;;;;;;OAMG;IACH,QAAQ;QACN,KAAK,MAAM,IAAI,IAAI,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;YAC5E,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,GAAY,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;QAC5F,CAAC;QACD,IAAI,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YAClD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,qEAAqE,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACK,KAAK,CAAC,QAAQ,CAAC,IAAY,EAAE,GAAY;QAC/C;;;;;;;;;;;;;;WAcG;QACH,MAAM,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QAEnC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAExC;;;;;;;;;;WAUG;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC5C,IAAI,OAAO;YAAE,KAAK,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,uBAAuB,EAAE,KAAK,CAAC,CAAC,CAAC;QAEnH,KAAK,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;YACrE,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,MAAM,IAAI,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC;QACpH,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,OAAgB;QAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACnD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAEpE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAC5C,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAiB,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC5F,KAAK,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;YAC3C,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,MAAM,IAAI,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,CAAC;QAC1F,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,cAAc,CACtB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,EAC5B,GAAG,IAAI,MAAM,OAAO,CAAC,MAAM,OAAO,MAAM,CAAC,MAAM,yBAAyB;kBACtE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;kBAC3D,oEAAoE,CACvE,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACK,OAAO,CAAC,IAAY,EAAE,GAAY;QACxC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpC,OAAO,KAAK,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YAC5E,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,GAA8B,CAAC;YAChE,CAAC,CAAC,GAAG,CAAC;IACV,CAAC;IAED;;;;;;;;;OASG;IACK,eAAe,CAAC,IAAY,EAAE,OAAgB;QACpD,MAAM,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;QACtC,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,mBAAmB,CAAC,GAAG,MAAM,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK;kBACnD,mGAAmG,CACtG,CAAC;QACJ,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACnD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,mCAAmC,CAAC,CAAC;YAC3D,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;YACtC,IAAI;YACJ,EAAE;YACF,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE;gBACxC,IAAI,MAAgC,CAAC;gBACrC,IAAI,CAAC;oBACH,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAA2B,IAAI,CAAC,CAAC;gBAClE,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,MAAM,IAAI,uBAAuB,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;gBACvE,CAAC;gBACD,OAAO,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,gBAAgB,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;YAC5D,CAAC,CAAC;SACH,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;;;;;;;;OASG;IACK,eAAe,CAAC,IAAY,EAAE,KAAc;QAClD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,CAAC,QAAQ,EAAE,MAAM;YAAE,OAAO,SAAS,CAAC;QACxC,OAAO,uBAAuB,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;cACtF,QAAQ,IAAI,kFAAkF,CAAC;IACrG,CAAC;CACF"}

package/dist/boot/HandlerFacade.d.ts

@@ -0,0 +1,72 @@
+import type { Container } from '@fougere/container';
+import type { AppMiddleware } from '../wire/middleware.js';
+import type { OperationsMap } from '../wire/operation.js';
+import type { EffectiveOperationsMap } from '../effective-operation.js';
+import type { Emissions } from './Emissions.js';
+import type { Logger } from '../builtins/logger.js';
+import type { EntityEntry, HandlerEntry, PresenterEntry } from '../scan/frond.js';
+/** What this door is about: a handler, the entity behind it when there is one, and where it resolves. */
+export interface Doorway {
+    handler: HandlerEntry;
+    /** Handlers in the owning frond, used to realize a resolved implementation override. */
+    handlers: readonly HandlerEntry[];
+    /** The canonical operation table resolved before boot performs any side effect. */
+    operations: EffectiveOperationsMap;
+    /** The subject — absent is ordinary: a health check owns no row. */
+    entity: EntityEntry | undefined;
+    /** The scope the handler and its collectors resolve in — a surface gets its own. */
+    scope: Container;
+    /** The container key this door answers under. */
+    key: string;
+}
+/** What the frond and the boot supply to every door alike. */
+export interface Wiring {
+    /** The frond this door belongs to — travels on every OperationContext. */
+    frond: string;
+    /** The frond's own scope — where presenters live, whatever sub-scope the door uses. */
+    frondScope: Container;
+    log: Logger;
+    /** Entity names this frond has a collector for. */
+    collectors: Set<string>;
+    presenters: Map<string, PresenterEntry>;
+    /** The middlewares that apply to an address, read at call time and never at boot. */
+    middlewaresFor: (address: string) => AppMiddleware[];
+    emissions: Emissions;
+}
+/** Adapts one handler door to executable operations. */
+export declare class HandlerFacade {
+    private readonly door;
+    private readonly wiring;
+    /** Rich operation facts shared with check, explain and adapters. */
+    readonly effectiveOperations: EffectiveOperationsMap;
+    /** Contracts served by this door. */
+    readonly contracts: OperationsMap;
+    /** The callable surface: op name → the function a caller reaches. */
+    readonly ops: Record<string, Function>;
+    private readonly cachedViews;
+    private instance;
+    private readonly implementationKeys;
+    private readonly implementationInstances;
+    private readonly inputValidator;
+    private readonly argumentResolver;
+    private readonly presenterArguments;
+    constructor(door: Doorway, wiring: Wiring);
+    /** Storage follows the Crud subject, which may differ from the door address. */
+    private subjectOf;
+    private inheritsCrud;
+    private get handlerKey();
+    private depsOf;
+    /** A custom Crud constructor must explicitly receive its repository. */
+    private refuseCrudWithoutRepository;
+    /** Resolve and cache the output view declared for one operation. */
+    private viewOf;
+    private collectorResolver;
+    /** The handler itself, resolved on first call — never at boot. */
+    private resolvedHandler;
+    private isBaseImplementation;
+    /** The exact handler entry the pure model selected; no name-only retry or fallback. */
+    private implementationHandler;
+    private resolvedImplementation;
+    private wrap;
+}
+//# sourceMappingURL=HandlerFacade.d.ts.map

package/dist/boot/HandlerFacade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HandlerFacade.d.ts","sourceRoot":"","sources":["../../src/boot/HandlerFacade.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAM3D,OAAO,KAAK,EAAqB,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,KAAK,EAAsB,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAE5F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AASlF,yGAAyG;AACzG,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,YAAY,CAAC;IACtB,wFAAwF;IACxF,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAClC,mFAAmF;IACnF,UAAU,EAAE,sBAAsB,CAAC;IACnC,oEAAoE;IACpE,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,oFAAoF;IACpF,KAAK,EAAE,SAAS,CAAC;IACjB,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,8DAA8D;AAC9D,MAAM,WAAW,MAAM;IACrB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,uFAAuF;IACvF,UAAU,EAAE,SAAS,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACxC,qFAAqF;IACrF,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,aAAa,EAAE,CAAC;IACrD,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,wDAAwD;AACxD,qBAAa,aAAa;IAmBZ,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAW,OAAO,CAAC,QAAQ,CAAC,MAAM;IAlBnE,oEAAoE;IACpE,QAAQ,CAAC,mBAAmB,EAAE,sBAAsB,CAAC;IACrD,qCAAqC;IACrC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAElC,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAM;IAE5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiC;IAC7D,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA6B;IAChE,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAA0B;IAClE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwB;IACvD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAE/B;IACF,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA4B;gBAElC,IAAI,EAAE,OAAO,EAAmB,MAAM,EAAE,MAAM;IAwC3E,gFAAgF;IAChF,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,YAAY;IAKpB,OAAO,KAAK,UAAU,GAErB;IAED,OAAO,CAAC,MAAM;IAMd,wEAAwE;IACxE,OAAO,CAAC,2BAA2B;IAWnC,oEAAoE;IACpE,OAAO,CAAC,MAAM;IAcd,OAAO,CAAC,iBAAiB,CAGvB;IAEF,kEAAkE;IAClE,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,oBAAoB;IAM5B,uFAAuF;IACvF,OAAO,CAAC,qBAAqB;IAe7B,OAAO,CAAC,sBAAsB;IAiB9B,OAAO,CAAC,IAAI;CA+Bb"}