@fougere/core 0.4.0-alpha.0 → 0.5.0-alpha.0

package/dist/wire/drift.d.ts

@@ -0,0 +1,55 @@
+import { type Change } from '@fougere/schema';
+import type { IdentityCard } from './call.js';
+/**
+ * What separates the copy a consumer holds from what the producer actually serves.
+ *
+ * It lives beside `IdentityCard` and not in `@fougere/testing` for the reason the card
+ * itself does: the subject is the card, and a second reader arrived — the dev panel, which
+ * must not drag a 426 KB faker in to compare two of them.
+ */
+export interface CardDrift {
+    frond: string;
+    /** A door the consumer calls that the producer no longer serves. */
+    missingDoors: string[];
+    /** An operation the consumer calls that the door no longer has. */
+    missingOps: {
+        door: string;
+        ops: string[];
+    }[];
+    /** A shape that moved under a door the consumer still calls. */
+    shapes: {
+        door: string;
+        changes: Change[];
+    }[];
+    /** A fact the consumer subscribes to whose shape moved, or that is gone. */
+    facts: {
+        fact: string;
+        changes: Change[] | 'gone';
+    }[];
+}
+/**
+ * What a consumer's synced copy no longer matches in what the producer serves.
+ *
+ * The gap TypeScript cannot see, and the only place the gradient genuinely lies: the code
+ * is identical in-process and split, but one side may have aged. `fougere sync` wrote the
+ * consumer's copy three weeks ago, the producer moved on, and it still compiles —
+ * production is where that is found today. This is what Pact sells; the material was
+ * already here, in `rpc.discover` and in `Card.diff`.
+ *
+ * Read in ONE direction on purpose: what the consumer holds, checked against what is
+ * served. A producer serving MORE than the consumer knows is not drift — it is a producer
+ * that moved forward without breaking anyone, which is the whole point of the order the
+ * repo already states (re-sync the readers, then deploy the sender).
+ */
+export declare function driftOf(mine: IdentityCard, theirs: IdentityCard, frond: string): CardDrift;
+/** Whether anything at all separates the two cards. */
+export declare function agrees(drift: CardDrift): boolean;
+/**
+ * The drift, in the words a deploy needs.
+ *
+ * A fact says the order out loud, because the repo already states it as a rule and
+ * nothing enforced it: a fact is judged strictly, so a reader that has not been re-synced
+ * refuses what the sender now announces.
+ */
+export declare function explain(drift: CardDrift): string[];
+//# sourceMappingURL=drift.d.ts.map

package/dist/wire/drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift.d.ts","sourceRoot":"","sources":["../../src/wire/drift.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,MAAM,EAAyB,MAAM,iBAAiB,CAAC;AAC3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mEAAmE;IACnE,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAC9C,gEAAgE;IAChE,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAC9C,4EAA4E;IAC5E,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAAA;KAAE,EAAE,CAAC;CACvD;AAuBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAgC1F;AAED,uDAAuD;AACvD,wBAAgB,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAKhD;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,EAAE,CAYlD"}

package/dist/wire/drift.js

@@ -0,0 +1,121 @@
+import { Card } from '@fougere/schema';
+/** Every door of a card, by name. */
+function doorsOf(card, frond) {
+    const found = new Map();
+    for (const one of card.fronds) {
+        if (one.name !== frond)
+            continue;
+        for (const door of one.doors) {
+            found.set(door.name, { ops: new Set(door.ops.map((op) => op.name)), schema: door.schema });
+        }
+    }
+    return found;
+}
+function factsOf(card, frond) {
+    const found = new Map();
+    for (const one of card.fronds) {
+        if (one.name !== frond)
+            continue;
+        for (const fact of one.facts ?? [])
+            found.set(fact.name, fact.schema);
+    }
+    return found;
+}
+/**
+ * What a consumer's synced copy no longer matches in what the producer serves.
+ *
+ * The gap TypeScript cannot see, and the only place the gradient genuinely lies: the code
+ * is identical in-process and split, but one side may have aged. `fougere sync` wrote the
+ * consumer's copy three weeks ago, the producer moved on, and it still compiles —
+ * production is where that is found today. This is what Pact sells; the material was
+ * already here, in `rpc.discover` and in `Card.diff`.
+ *
+ * Read in ONE direction on purpose: what the consumer holds, checked against what is
+ * served. A producer serving MORE than the consumer knows is not drift — it is a producer
+ * that moved forward without breaking anyone, which is the whole point of the order the
+ * repo already states (re-sync the readers, then deploy the sender).
+ */
+export function driftOf(mine, theirs, frond) {
+    const held = doorsOf(mine, frond);
+    const served = doorsOf(theirs, frond);
+    const drift = { frond, missingDoors: [], missingOps: [], shapes: [], facts: [] };
+    for (const [name, door] of held) {
+        const there = served.get(name);
+        if (!there) {
+            drift.missingDoors.push(name);
+            continue;
+        }
+        const missing = [...door.ops].filter((op) => !there.ops.has(op));
+        if (missing.length > 0)
+            drift.missingOps.push({ door: name, ops: missing.sort() });
+        if (door.schema && there.schema) {
+            // `Card.diff` never guesses a rename — a field gone plus a field appeared lands in
+            // `ambiguous`, and only a declaration settles it. Here nobody can declare one, so
+            // the pair is reported as it is and a human reads it.
+            const moved = Card.fromDescriptor(door.schema).diff(Card.fromDescriptor(there.schema));
+            if (moved.changes.length > 0)
+                drift.shapes.push({ door: name, changes: moved.changes });
+        }
+    }
+    const heldFacts = factsOf(mine, frond);
+    const servedFacts = factsOf(theirs, frond);
+    for (const [name, shape] of heldFacts) {
+        if (!servedFacts.has(name)) {
+            drift.facts.push({ fact: name, changes: 'gone' });
+            continue;
+        }
+        const there = servedFacts.get(name);
+        if (!shape || !there)
+            continue;
+        const moved = Card.fromDescriptor(shape).diff(Card.fromDescriptor(there));
+        if (moved.changes.length > 0)
+            drift.facts.push({ fact: name, changes: moved.changes });
+    }
+    return drift;
+}
+/** Whether anything at all separates the two cards. */
+export function agrees(drift) {
+    return drift.missingDoors.length === 0
+        && drift.missingOps.length === 0
+        && drift.shapes.length === 0
+        && drift.facts.length === 0;
+}
+/**
+ * The drift, in the words a deploy needs.
+ *
+ * A fact says the order out loud, because the repo already states it as a rule and
+ * nothing enforced it: a fact is judged strictly, so a reader that has not been re-synced
+ * refuses what the sender now announces.
+ */
+export function explain(drift) {
+    const lines = [];
+    for (const door of drift.missingDoors)
+        lines.push(`${drift.frond}.${door} — you call it, it is not served`);
+    for (const { door, ops } of drift.missingOps)
+        lines.push(`${drift.frond}.${door} — gone: ${ops.join(', ')}`);
+    for (const { door, changes } of drift.shapes) {
+        for (const change of changes)
+            lines.push(`${drift.frond}.${door} — ${describe(change)}`);
+    }
+    for (const { fact, changes } of drift.facts) {
+        if (changes === 'gone') {
+            lines.push(`${fact} — you subscribe to it, it is no longer announced`);
+            continue;
+        }
+        for (const change of changes)
+            lines.push(`${fact} — ${describe(change)} → re-sync and deploy the readers, THEN the sender`);
+    }
+    return lines;
+}
+function describe(change) {
+    switch (change.kind) {
+        case 'added': return `+ ${change.field}${change.required ? ' (required)' : ''}`;
+        case 'removed': return `- ${change.field}`;
+        case 'renamed': return `${change.from} → ${change.to}`;
+        case 'retyped': return `${change.field}: ${[...change.from].join('|')} → ${[...change.to].join('|')}`;
+        case 'reshaped': return `${change.field}: its bounds moved`;
+        case 'required': return `${change.field}: ${change.from ? 'no longer' : 'now'} required`;
+        case 'restated': return `${change.field}: its ${change.axis} moved`;
+    }
+}
+//# sourceMappingURL=drift.js.map

package/dist/wire/drift.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift.js","sourceRoot":"","sources":["../../src/wire/drift.ts"],"names":[],"mappings":"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"}

package/dist/wire/middleware.d.ts

@@ -18,7 +18,7 @@ export interface OperationContext {
     /** Extensible bag — middlewares deposit data here (user, permissions, etc.). */
     state: Record<string, unknown>;
     /** Transport-agnostic invocation context (params, query, body, state). */
-    invocation?: import('./invocation.js').InvocationContext;
+    invocation?: import('../contract/Invocation.js').InvocationContext;
 }
 export type AppNext = () => Promise<unknown>;
 export type AppMiddleware = (ctx: OperationContext, next: AppNext) => Promise<unknown>;

package/dist/wire/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/wire/middleware.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,0EAA0E;IAC1E,UAAU,CAAC,EAAE,OAAO,iBAAiB,EAAE,iBAAiB,CAAC;CAC1D;AAED,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;AAC7C,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,gBAAgB,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAIvF;;GAEG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,aAAa,EAAE,EAC5B,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,OAAO,CAAC,CASlB"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/wire/middleware.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,0EAA0E;IAC1E,UAAU,CAAC,EAAE,OAAO,2BAA2B,EAAE,iBAAiB,CAAC;CACpE;AAED,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;AAC7C,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,gBAAgB,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAIvF;;GAEG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,aAAa,EAAE,EAC5B,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,OAAO,CAAC,CASlB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fougere/core",
-  "version": "0.4.0-alpha.0",
+  "version": "0.5.0-alpha.0",
   "description": "The core — scan, call contract, façades, remote stand-ins.",
   "keywords": [
     "fougere",
@@ -56,8 +56,8 @@
   "dependencies": {
     "@typescript/typescript6": "^6.0.2",
     "dequal": "^2.0.3",
-    "@fougere/container": "0.4.0-alpha.0",
-    "@fougere/schema": "0.4.0-alpha.0"
+    "@fougere/container": "0.5.0-alpha.0",
+    "@fougere/schema": "0.5.0-alpha.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"

package/src/boot/Emissions.ts

@@ -3,7 +3,7 @@ import type { Container } from '@fougere/container';
 import { validationErrorsOf } from '../wire/errors.js';
 import { emitKeyOf, factsAnnouncedBy } from '../emit.js';
 import { ambient } from '#ambient';
-import { EMPTY_INVOCATION } from '../wire/invocation.js';
+import { EMPTY_INVOCATION } from '../contract/Invocation.js';
 import type { Logger } from '../builtins/logger.js';
 import type { Fronds } from '../scan/Fronds.js';
 import type { OperationsMap } from '../wire/operation.js';

package/src/boot/HandlerFacade.ts

@@ -8,7 +8,7 @@ import { repositoryKeyOf } from '../prefab/repository.js';
 import { targetOf } from '../prefab/prefab.js';
 import type { OperationContract, OperationsMap } from '../wire/operation.js';
 import type { EffectiveOperation, EffectiveOperationsMap } from '../effective-operation.js';
-import type { InvocationContext } from '../wire/invocation.js';
+import type { InvocationContext } from '../contract/Invocation.js';
 import type { Emissions } from './Emissions.js';
 import type { Logger } from '../builtins/logger.js';
 import type { EntityEntry, HandlerEntry, PresenterEntry } from '../scan/frond.js';

package/src/boot/binding.ts

@@ -7,7 +7,7 @@
  * load-bearing, since the fall-through would otherwise hand it the caller's body.
  */
 import type { ParsedParam } from '../scan/handler-parser.js';
-import type { InvocationContext } from '../wire/invocation.js';
+import type { InvocationContext } from '../contract/Invocation.js';
 import { lowerFirst } from '@fougere/schema';
 
 // ── Types ─────────────────────────────────────

package/src/boot/bootstrap.ts

@@ -1,6 +1,7 @@
 import type { Container } from '@fougere/container';
 import { lowerFirst, type SchemaView } from '@fougere/schema';
 import type { EntityEntry, HandlerEntry, PresenterEntry } from '../scan/frond.js';
+import { hostedBy } from './hosted.js';
 import type { AuthRuntime } from './auth.js';
 import type { CreateAppOptions, App } from './types.js';
 import type { AppMiddleware } from '../wire/middleware.js';
@@ -106,11 +107,11 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
   container.register('Config', Config, { lifetime: 'singleton' });
   log.debug('builtins registered (Logger, Config)');
 
-  // The scan is HANDED IN. Producing it reads a disk, consuming it does not — which is
-  // the whole reason this file names no builtin and a Worker can run what it builds.
-  // `scanProject` (`@fougere/core/node`) is one producer; a module a build wrote is another.
+  // What this app hosts is HANDED IN — stated, scanned, or both (`hostedBy`). Producing
+  // it may read a disk; consuming it never does, which is the whole reason this file names
+  // no builtin and a Worker can run what it builds.
   const scanStart = performance.now();
-  const { fronds, diagnostics } = await (typeof options.scan === 'function' ? options.scan() : options.scan);
+  const { fronds, diagnostics } = await hostedBy(options);
   const operationModel = resolveEffectiveOperations(fronds, {
     diagnostics,
     remotes: options.remotes,
@@ -786,6 +787,10 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
     // What this app publishes, straight from fougere.config.ts — the doors read it,
     // so an undeclared adapter serves nothing whatever a host mounted.
     adapters: options.adapters ?? {},
+    // Where a call goes, as DECLARED. Kept because a reader needs it beside what the
+    // runtime OBSERVED — `rpc.topology` calls a frond remote because it answered, never
+    // because a key said so, and the two disagree exactly when something is misconfigured.
+    remotes: Object.freeze({ ...(options.remotes ?? {}) }),
     dispatch: (call) => dispatcher.dispatch(call),
     local: localDispatcher,
     resolve,
@@ -814,6 +819,9 @@ export async function createApp(options: CreateAppOptions): Promise<App> {
       ));
     },
     extensions: () => appLifecycle.names(),
+    observe(observer) {
+      return dispatchLifecycle.add(observer);
+    },
     use(...args: [AppMiddleware] | [string, AppMiddleware]): void {
       if (typeof args[0] === 'string') {
         const [entity, mw] = args as [string, AppMiddleware];

package/src/boot/hosted.ts

@@ -0,0 +1,77 @@
+/**
+ * What this app hosts — what it STATED, or what a scan FOUND.
+ *
+ * The PRESENCE of the key is the decision, the way `remotes:` states a topology: an app
+ * that passes `fronds:` is saying "do not scan", and one that passes `scan:` is handing
+ * over what a scanner read. There is no mode to configure because there is no third
+ * behaviour to name.
+ *
+ * Both may arrive, and then they MERGE — but only where a scan costs nothing at runtime.
+ * Under Nuxt the scan is a build artifact, so an app may state the frond it wants to own
+ * and leave the rest to what the build found. Anywhere the scan would run at START, half a
+ * statement buys nothing the whole one does: the disk is read either way.
+ *
+ * Merging is per frond NAME and per member. A stated frond wins outright on the members it
+ * names — stating `entities: [Post]` where a scan found `[Post, Author]` yields `[Post]`,
+ * because the point of stating is to decide. Empty is what "I named none" looks like, and
+ * `frond()` builds every member, so an empty one is filled rather than enforced.
+ */
+import type { FrondDescriptor, ScanResult } from '../scan/frond.js';
+import { Fronds } from '../scan/Fronds.js';
+
+/** Where an app's fronds come from — either, or both. */
+export interface HostedSources {
+  /** What the app states. No disk was read, so no diagnostic can come from it. */
+  fronds?: readonly FrondDescriptor[];
+  /** What a scanner found, and what it could not do. */
+  scan?: ScanResult | (() => Promise<ScanResult> | ScanResult);
+}
+
+/** The members a stated frond takes from a scan when it named none of its own. */
+type Fillable = 'providers' | 'entities' | 'handlers' | 'presenters' | 'collectors' | 'seeds';
+
+/** A stated frond, completed by what a scan found under the same name. */
+function completed(stated: FrondDescriptor, found: FrondDescriptor | undefined): FrondDescriptor {
+  if (!found) return stated;
+
+  // Written out rather than looped: a loop over the key union asks TypeScript to prove
+  // `found[k]` fits `stated[k]` for every k at once, which it cannot — and the cast that
+  // silences it would also silence a member added to the descriptor and forgotten here.
+  const fill = <K extends Fillable>(member: K): FrondDescriptor[K] =>
+    (stated[member].length === 0 ? found[member] : stated[member]);
+
+  return {
+    ...found,
+    ...stated,
+    providers: fill('providers'),
+    entities: fill('entities'),
+    handlers: fill('handlers'),
+    presenters: fill('presenters'),
+    collectors: fill('collectors'),
+    seeds: fill('seeds'),
+  };
+}
+
+/** What the app hosts, and what the scan — if it ran — could not do. */
+export async function hostedBy(sources: HostedSources): Promise<ScanResult> {
+  const scanned = sources.scan
+    ? await (typeof sources.scan === 'function' ? sources.scan() : sources.scan)
+    : undefined;
+
+  if (!sources.fronds) {
+    if (!scanned) {
+      throw new Error(
+        'createApp needs `fronds:` (what this app states) or `scan:` (what a scanner found). '
+        + 'Neither was given, so nothing is hosted.',
+      );
+    }
+
+    return scanned;
+  }
+
+  const found = scanned?.fronds ?? [];
+  const stated = sources.fronds.map((f) => completed(f, found.find((s) => s.name === f.name)));
+  const unstated = found.filter((f) => !sources.fronds!.some((s) => s.name === f.name));
+
+  return { fronds: Fronds.scanned([...stated, ...unstated]), diagnostics: scanned?.diagnostics ?? [] };
+}

package/src/boot/ownership.ts

@@ -1,4 +1,4 @@
-import { lowerFirst, type EntityConstructor } from '@fougere/schema';
+import { lowerFirst } from '@fougere/schema';
 import type { FrondDescriptor, ProviderEntry } from '../scan/frond.js';
 import { targetOf } from '../prefab/prefab.js';
 import { ownedBy, repositoryKeyOf } from '../prefab/repository.js';
@@ -135,6 +135,3 @@ function entityOfOrmKey(dep: string): string | undefined {
   const entity = lowerFirst(dep.slice(0, -'Orm'.length));
   return ormKeyOf(entity) === dep ? entity : undefined;
 }
-
-/** Placeholder so the module's imports stay honest if a caller wants the entity list. */
-export type { EntityConstructor };

package/src/boot/remote.ts

@@ -11,7 +11,7 @@
 import type { FrondCall, Transport } from '../wire/call.js';
 import { assertIdentityCard, RPC_ENTITY } from '../wire/call.js';
 import { runMiddlewares, type AppMiddleware, type OperationContext } from '../wire/middleware.js';
-import { EMPTY_INVOCATION, type InvocationContext } from '../wire/invocation.js';
+import { EMPTY_INVOCATION, type InvocationContext } from '../contract/Invocation.js';
 import { FougereError, ErrorCode } from '../wire/errors.js';
 import { Card, type SchemaView, type SchemaDescriptor } from '@fougere/schema';
 import { DynamicFacade } from '../entry/DynamicFacade.js';

package/src/boot/statement-drift.ts

@@ -0,0 +1,60 @@
+/**
+ * Where a STATED contract and the signature it is about have stopped agreeing.
+ *
+ * `frond.config.ts` states an operation's contract and wins over the scan — that order is
+ * deliberate, and it is the only answer for a method inherited from an installed base class
+ * the workspace scan cannot see. But winning silently is how a statement made about
+ * `publish(id: string)` keeps applying after the parameter was renamed to `postId`: the
+ * façade binds what the config said, the method receives `undefined`, and nothing anywhere
+ * says the two disagree.
+ *
+ * So this compares, and only where BOTH exist — a statement about a signature the scan
+ * never read is not drift, it is the case config was built for. It is a `warning` and not
+ * a refusal: the statement is still the author's word, and a boot that ran yesterday must
+ * not stop running because a parameter moved. What it must not do is stay quiet.
+ */
+import type { FrondDescriptor, HandlerEntry, ScanDiagnostic } from '../scan/frond.js';
+import type { BindingPlan } from './binding.js';
+import type { ParsedMethod } from '../scan/handler-parser.js';
+
+/** The parameters a stated binding names, against the ones the method declares. */
+function namesDisagreeing(stated: BindingPlan, signature: ParsedMethod): string[] {
+  const declared = new Set(signature.params.map((p: { name: string }) => p.name));
+
+  return stated.map((b) => b.name).filter((name) => !declared.has(name));
+}
+
+/**
+ * What a frond's stated contracts no longer match.
+ *
+ * Read by `resolveEffectiveOperations`, so the same answer reaches `fougere check` and a
+ * boot — one comparison, two readers, no second opinion to drift on its own.
+ */
+export function statementDrift(frond: FrondDescriptor, handler: HandlerEntry): ScanDiagnostic[] {
+  const found: ScanDiagnostic[] = [];
+
+  for (const [name, override] of Object.entries(frond.operationsOverrides ?? {})) {
+    if (!override.binding) continue;
+
+    // The scan's own reading of this method. Absent means config is stating what nothing
+    // read — an installed base class, a handler outside the workspace — which is legal.
+    const signature = handler.operations.get(name)?.signature;
+    if (!signature) continue;
+
+    const orphans = namesDisagreeing(override.binding, signature);
+    if (orphans.length === 0) continue;
+
+    found.push({
+      severity: 'warning',
+      code: 'stated-binding-drifted',
+      filePath: handler.filePath,
+      frond: frond.name,
+      subject: `${handler.ctor.name}.${name}`,
+      message: `frond.config.ts binds ${orphans.map((o) => `\`${o}\``).join(', ')} on `
+        + `${handler.ctor.name}.${name}, which declares (${signature.params.map((p: { name: string }) => p.name).join(', ')}). `
+        + `The statement wins, so those parameters receive nothing.`,
+    });
+  }
+
+  return found;
+}

package/src/boot/types.ts

@@ -7,7 +7,7 @@
  */
 import type { Container } from '@fougere/container';
 import type { Fronds } from '../scan/Fronds.js';
-import type { ScanResult } from '../scan/frond.js';
+import type { FrondDescriptor, ScanResult } from '../scan/frond.js';
 import type { SchemaView } from '@fougere/schema';
 import type { OrmFactory } from '../orm.js';
 import type { AppMiddleware } from '../wire/middleware.js';
@@ -55,7 +55,16 @@ export interface CreateAppOptions {
    * apart, and that is the point: it names no builtin, so a runtime without `node:fs`
    * runs it. `root` and `fronds` used to live here — both were arguments to the scan.
    */
-  scan: ScanResult | (() => Promise<ScanResult> | ScanResult);
+  scan?: ScanResult | (() => Promise<ScanResult> | ScanResult);
+  /**
+   * What this app STATES it hosts — `frond('blog', { entities: [Post] })`.
+   *
+   * Passing this and not `scan:` is how an app says "do not scan": nothing reads a disk,
+   * nothing loads `typescript`, and what was not named does not exist. Passing both fills
+   * the members left unnamed from what the scan found — the app's word wins, the way
+   * `frond.config.ts` wins over the scan one level down.
+   */
+  fronds?: readonly FrondDescriptor[];
   /**
    * Remote fronds — label → address. What each remote hosts is discovered
    * at the first miss (rpc.discover), never declared here.
@@ -140,6 +149,8 @@ export interface App extends DispatchPort {
    * the answer is still "not here".
    */
   adapters: Record<string, boolean | undefined>;
+  /** Where a call goes, as the config declared it — frond name to address. */
+  remotes: Readonly<Record<string, string>>;
   /** Discovered fronds metadata. */
   fronds: Fronds;
   /** Resolve from root container (shortcut). */
@@ -253,6 +264,8 @@ export interface App extends DispatchPort {
    */
   serveRpc(op: string, answer: RpcAnswer): void;
   /** Register a global app middleware (runs on every operation). */
+  /** Watch every dispatch transition; the returned function unsubscribes. */
+  observe(observer: DispatchObserver): () => void;
   use(middleware: AppMiddleware): void;
   /** Register an app middleware scoped to a specific entity. */
   use(entity: string, middleware: AppMiddleware): void;

package/src/contract/CallLog.ts

@@ -0,0 +1,55 @@
+import type { DispatchEvent } from '../dispatch/DispatchEvent.js';
+
+/**
+ * What crosses the door: the address, the route it took, and the verdict.
+ *
+ * It lives here rather than beside its producer for the reason `TopologyReport` does: it
+ * crosses a process boundary, so a reader that never installed `@fougere/calls` — the CLI
+ * — needs its shape, and putting it there is what produces a hand-copied duplicate.
+ *
+ * Never the body. Same rule the topology report states — a remote destination is named,
+ * not disclosed — and it holds here for the same reason: this answer leaves the process.
+ */
+export interface CallRecord {
+  /** Monotonic, and the whole cursor protocol: a reader asks for what is above its own. */
+  seq: number;
+  frond?: string;
+  entity: string;
+  operation: string;
+  surface?: string;
+  /** Known at `resolved`, so absent on a call that never found a route. */
+  route?: NonNullable<DispatchEvent['routeKind']>;
+  /**
+   * The traceparent the invocation carried, when one did.
+   *
+   * One panel reads one process, so this is what lets two of them be sewn: the process
+   * that sent and the process that executed share it, and the gap between their two
+   * durations IS the cost of the wire rather than a deduction.
+   */
+  trace?: string;
+  /**
+   * The peer that established this call, when one did.
+   *
+   * A hosted frond serves several consumers, so its own ring mixes them: this is what
+   * separates them. Absent on a call nobody signed — a loopback dev boot has no identity.
+   */
+  caller?: string;
+  startedAt: number;
+  /** Known at `settled`. */
+  ms?: number;
+  verdict: 'running' | 'ok' | 'failed';
+  refusal?: { code?: string; message: string };
+}
+
+/**
+ * One page of the ring.
+ *
+ * `dropped` is what the ring could not keep — an absence is named rather than left to
+ * look like a quiet period.
+ */
+export interface CallPage {
+  calls: CallRecord[];
+  cursor: number;
+  inFlight: number;
+  dropped: number;
+}

package/src/contract.ts

@@ -9,7 +9,7 @@
  * is allowed in — measured, it imports no node builtin either.
  */
 import { lowerFirst } from '@fougere/schema';
-import { canonicalInvocation, type InvocationContext } from './wire/invocation.js';
+import { canonicalInvocation, type InvocationContext } from './contract/Invocation.js';
 import type { FrondCall } from './wire/call.js';
 
 export { FougereError, ErrorCode, validationErrorsOf } from './wire/errors.js';
@@ -17,14 +17,23 @@ export { FougereError, ErrorCode, validationErrorsOf } from './wire/errors.js';
 // core's boot — reaching it through the main entry dragged the scanner into a bundle.
 export { toPublicError } from './wire/http-error.js';
 export type { FougereErrorOptions } from './wire/errors.js';
-export { canonicalInvocation, EMPTY_INVOCATION } from './wire/invocation.js';
-export type { InvocationContext } from './wire/invocation.js';
+export { canonicalInvocation, EMPTY_INVOCATION } from './contract/Invocation.js';
+export type { InvocationContext } from './contract/Invocation.js';
 export { Invocation } from './contract/Invocation.js';
 export type { InvocationInput } from './contract/Invocation.js';
 export { Call } from './contract/Call.js';
 export { RouteAddress } from './contract/RouteAddress.js';
 export type { RouteAddressInput } from './contract/RouteAddress.js';
 export type { FrondCall, Transport, SignedCall } from './wire/call.js';
+export { MAX_BODY_BYTES } from './wire/call.js';
+// The reserved entity, VALUE and not type: a consumer that wants to leave it alone — a
+// call log ignoring its own reader — has to be able to name it.
+export { RPC_ENTITY } from './wire/call.js';
+export type { CallPage, CallRecord } from './contract/CallLog.js';
+// The comparison of two cards, which a consumer runs about a producer — browser-safe on
+// purpose: a panel showing the drift holds only the two cards, never the app.
+export { driftOf, agrees, explain } from './wire/drift.js';
+export type { CardDrift } from './wire/drift.js';
 
 /**
  * What `rpc.discover` answers. It belongs here and not to the runtime: the

package/src/dispatch/DispatchLifecycle.ts

@@ -2,10 +2,30 @@ import type { DispatchEvent, DispatchObserver } from './DispatchEvent.js';
 
 /** Publishes dispatch transitions without participating in dispatch decisions. */
 export class DispatchLifecycle {
+  private readonly observers: DispatchObserver[];
+
   constructor(
-    private readonly observers: readonly DispatchObserver[] = [],
+    observers: readonly DispatchObserver[] = [],
     private readonly diagnose: (error: unknown, event: DispatchEvent) => void = () => {},
-  ) {}
+  ) {
+    this.observers = [...observers];
+  }
+
+  /**
+   * Subscribe after the dispatcher was built, and get the unsubscription back.
+   *
+   * The list used to be settled at construction, so only the caller of `createApp` could
+   * observe — an extension, which runs in `up(app)`, could not. `app.use` already adds a
+   * middleware this late; this is its dual, and the pair is *participate* / *watch*.
+   */
+  add(observer: DispatchObserver): () => void {
+    this.observers.push(observer);
+
+    return () => {
+      const at = this.observers.indexOf(observer);
+      if (at !== -1) this.observers.splice(at, 1);
+    };
+  }
 
   publish(event: DispatchEvent): void {
     for (const observer of this.observers) {

package/src/dispatch/InFlight.ts

@@ -10,10 +10,6 @@ export class InFlight {
     return this.running;
   }
 
-  get open(): boolean {
-    return this.accepting;
-  }
-
   enter(entity: string, operation: string): () => void {
     if (!this.accepting) {
       throw new FougereError({