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

package/src/effective-operation.ts

@@ -6,6 +6,7 @@
  * container, filesystem, migration or handler construction is involved.
  */
 import { lowerFirst, type SchemaView } from '@fougere/schema';
+import { statementDrift } from './boot/statement-drift.js';
 import type { BindingPlan } from './boot/binding.js';
 import { targetOf } from './prefab/prefab.js';
 import type {
@@ -166,6 +167,9 @@ export function resolveEffectiveOperations(
       const effective = new Map<string, EffectiveOperation>();
       byHandler.set(handler, effective);
       const contracts = resolveContracts(handler, frond.operationsOverrides, collectorNames);
+      // A statement wins over the scan on purpose; saying so out loud is what keeps the
+      // win from hiding a rename. Compared here, where both readings are in hand.
+      resolutionDiagnostics.push(...statementDrift(frond, handler));
 
       for (const [name, rawContract] of contracts) {
         const subject = `${handler.ctor.name}.${name}`;

package/src/index.ts

@@ -31,7 +31,12 @@ export { RouteAddress } from './contract/RouteAddress.js';
 export type { RouteAddressInput } from './contract/RouteAddress.js';
 export { DispatchLifecycle } from './dispatch/DispatchLifecycle.js';
 export { Dispatcher } from './dispatch/Dispatcher.js';
-export type { DispatchEvent, DispatchObserver } from './dispatch/DispatchEvent.js';
+// The class and not only its type: an observer RECEIVES these, so a package that folds
+// them — or a test of one — has to be able to make one through the door.
+export { DispatchEvent } from './dispatch/DispatchEvent.js';
+export type { CallPage, CallRecord } from './contract/CallLog.js';
+export { driftOf, agrees, explain, type CardDrift } from './wire/drift.js';
+export type { DispatchObserver } from './dispatch/DispatchEvent.js';
 export type { DispatchPort } from './dispatch/DispatchPort.js';
 export {
   inferOperationKind,
@@ -62,7 +67,16 @@ export type {
 export type { ModuleLoader } from './loader.js';
 export { FougereError, ErrorCode, validationErrorsOf, type FougereErrorOptions } from './wire/errors.js';
 export type { OperationContext, AppNext, AppMiddleware } from './wire/middleware.js';
-export { createLocalRunner, createAppRunner, assertIdentityCard } from './wire/call.js';
+export { createLocalRunner, createAppRunner, assertIdentityCard, RPC_ENTITY, MAX_BODY_BYTES } from './wire/call.js';
+
+// A frond an app STATES, for a boot that will not scan. No disk, no `typescript` — which
+// is why it sits here and not in `/node`, beside the scanner that reads a project.
+export { frond } from './scan/declare.js';
+export type { FrondDeclaration, Declared, DeclaredSubject } from './scan/declare.js';
+// What this app would answer to `rpc.discover`. Served by the boot, and reached until now
+// only by tests through a deep path — a consumer comparing its own card to a producer's
+// had to dispatch a call to ask a question about itself.
+export { identityCardOf } from './wire/call.js';
 export type {
   FrondCall, Transport, IdentityCard, CardOp, Facade, RpcAnswer,
   TopologyReport, FrondPlacement, Edge,

package/src/node.ts

@@ -16,7 +16,9 @@ export {
   type Conventions, type ConventionsInput, DEFAULT_CONVENTIONS,
   resolveConventions, frondPackage, frondDirsOf, providerDirsOf, watchPathsOf,
 } from './scan/conventions.js';
+export { RUNTIME_PACKAGES } from './scan/bundling.js';
 export { emitScan, type EmitOptions } from './scan/emit.js';
+export { emitStatement } from './scan/statement.js';
 export { setModuleLoader, getModuleLoader } from './loader.js';
 export { loadConfig, loadCascadedConfig } from './config-loader.js';
 export { defineFrond } from './frond-config.js';

package/src/scan/bundling.ts

@@ -0,0 +1,25 @@
+/**
+ * What a Fougere boot loads at RUNTIME, so a bundler must leave it alone.
+ *
+ * Stated once because it was stated twice and the two had already drifted: the Vite plugin
+ * listed `@fougere/schema`, `@fougere/adapter-graphql` and `@fougere/auth-better`, the Next
+ * one did not, and BOTH omitted the two packages `@fougere/app`'s boot actually imports
+ * dynamically — `@fougere/defaults` and `@fougere/transport-http`. A list a bundler reads
+ * has no way to notice it is wrong: nothing fails at build time, the app fails at boot.
+ *
+ * It sits here rather than beside the dynamic imports because both readers are BUILD-TIME
+ * plugins that already depend on core, and neither may pull the boot into a bundler config.
+ */
+export const RUNTIME_PACKAGES: readonly string[] = [
+  '@fougere/app',
+  '@fougere/core',
+  '@fougere/schema',
+  '@fougere/defaults',
+  '@fougere/transport-http',
+  '@fougere/adapter-sql',
+  '@fougere/adapter-graphql',
+  '@fougere/auth-better',
+  'better-sqlite3',
+  'jiti',
+  'typescript',
+];

package/src/scan/declare.ts

@@ -0,0 +1,188 @@
+/**
+ * A frond stated by its author, for an app that will not scan.
+ *
+ * The scan reads the type checker because a signature IS a declaration — and that reading
+ * has to happen while the types still exist, which is build time. An app that wants
+ * neither a build step nor `typescript` at runtime says the same thing here instead, and
+ * `createApp` cannot tell the difference: it consumes a `ScanResult`, never a scanner.
+ *
+ * What it does NOT ask for is the point. Every name the scan derives from a class is
+ * derived here the same way — `PostHandler` answers at `post`, `Post` is stored as `post`
+ * — so a declaration states classes and nothing else. `filePath` is empty because there is
+ * no file to point at, and a diagnostic that would have quoted one says so plainly.
+ *
+ * Measured on `demos/nuxt-blog`: 23 of its 29 operations need no word here at all, because
+ * `Crud.__ops` declares them at runtime. Only the six the author wrote by hand cost
+ * anything, and they cost `frond.config.ts` — where what is not derivable is stated.
+ */
+import { lowerFirst, type SchemaView } from '@fougere/schema';
+import type {
+  CollectorEntry, EntityEntry, FrondDescriptor, HandlerEntry,
+  PresenterEntry, ProviderEntry, SeedEntry,
+} from './frond.js';
+import { DEFAULT_CONVENTIONS } from './conventions.js';
+import { getPresenterFields } from '../prefab/presenter.js';
+
+/** A class, as a declaration hands it over: the constructor itself. */
+type Ctor = new (...args: never[]) => unknown;
+
+/**
+ * What a subject needs beyond its class, when its constructor names a frame or a port.
+ *
+ * `deps` is the one thing no runtime can recover: TypeScript erases the parameter types,
+ * and `registerFrames` reads them to know which frames to build — asking for one IS
+ * declaring it. A handler that takes only its own entity's ORM needs nothing here.
+ */
+export interface DeclaredSubject {
+  ctor: Ctor;
+  deps?: string[];
+}
+
+/** A handler, and the surface it answers on when it is not the default one. */
+export interface DeclaredHandler extends DeclaredSubject {
+  /**
+   * The scan reads this from the directory (`handlers/public/`), so a statement has to
+   * say it: two handlers over one entity collide on their address otherwise, and the
+   * refusal names the same route twice.
+   */
+  surface?: string;
+}
+
+/** A class on its own, or a class with what it asks for. */
+export type Declared = Ctor | DeclaredSubject;
+
+const ctorOf = (d: Declared): Ctor => (typeof d === 'function' ? d : d.ctor);
+
+/**
+ * What a prefab was BUILT ON — `Presenter(Post)` and `Collector(User)` both keep it under
+ * `__entity`, which is the only place it survives: nothing in the FORM of `PostPresenter`
+ * says `Post`. Absent, the class did not come through the prefab, and the refusal says so
+ * rather than yielding a frond whose presenter belongs to no entity.
+ */
+function subjectOf(ctor: Ctor, kind: string): { name: string } {
+  const subject = (ctor as unknown as { __entity?: { name: string } }).__entity;
+  if (!subject?.name) {
+    throw new Error(
+      `${ctor.name} is declared as a ${kind} but does not extend ${kind === 'presenter' ? 'Presenter(Entity)' : 'Collector(Type)'}, `
+      + `so what it is about cannot be read.`,
+    );
+  }
+
+  return subject;
+}
+const depsOf = (d: Declared): string[] => (typeof d === 'function' ? [] : d.deps ?? []);
+
+/** `PostHandler` answers at `post` — the same rule the scan applies to a file it found. */
+function addressOf(className: string): string {
+  const base = className.endsWith('Handler') ? className.slice(0, -7) : className;
+
+  return lowerFirst(base);
+}
+
+/** What a declaration states about one frond. Everything else is derived from the classes. */
+export interface FrondDeclaration {
+  entities?: SchemaView[];
+  handlers?: (Ctor | DeclaredHandler)[];
+  presenters?: (Ctor | DeclaredSubject)[];
+  collectors?: (Ctor | DeclaredSubject)[];
+  providers?: Declared[];
+  seeds?: { entityName: string; data: SeedEntry['data'] }[];
+  /** Per-surface entity lists — the same key `frond.config.ts` states. */
+  surfaces?: Record<string, string[]>;
+  /** The import scope this frond answers under. Defaults to the conventional one. */
+  scope?: string;
+}
+
+/**
+ * State a frond without reading a disk.
+ *
+ * ```ts
+ * createApp({
+ *   scan: { fronds: Fronds.scanned([frond('blog', { entities: [Post], handlers: [PostHandler] })]), diagnostics: [] },
+ * })
+ * ```
+ */
+export function frond(name: string, declared: FrondDeclaration = {}): FrondDescriptor {
+  const scope = declared.scope ?? DEFAULT_CONVENTIONS.scope;
+
+  const entities: EntityEntry[] = (declared.entities ?? []).map((entityClass) => ({
+    name: lowerFirst((entityClass as { name: string }).name),
+    entityClass,
+    filePath: '',
+    exposed: true,
+  }));
+
+  const handlers: HandlerEntry[] = (declared.handlers ?? []).map((h) => {
+    const ctor = ctorOf(h);
+    const surface = typeof h === 'function' ? undefined : h.surface;
+    const address = addressOf(ctor.name);
+
+    return {
+      name: ctor.name,
+      address,
+      ctor,
+      // A handler about no stored row is ordinary — the address is not a promise that an
+      // entity carries it, which is why this is not looked up.
+      entityName: address,
+      operations: new Map(),
+      deps: depsOf(h),
+      filePath: '',
+      exposed: true,
+      ...(surface ? { surface } : {}),
+    };
+  });
+
+  // Read off the class, never restated: `Presenter(Post)` keeps `Post` in `__entity` and a
+  // computed field IS a method, which `getPresenterFields` already reads from the prototype.
+  // Asking for `entityName` and `fields` made a statement copy what the class carries — and
+  // a copy that drifts silently, since nothing compares the two.
+  const presenters: PresenterEntry[] = (declared.presenters ?? []).map((p) => {
+    const ctor = ctorOf(p);
+    const fields = getPresenterFields(ctor);
+
+    return {
+      entityName: lowerFirst(subjectOf(ctor, 'presenter').name),
+      ctor,
+      fields,
+      fieldMeta: fields.map((field) => ({ name: field })),
+      deps: depsOf(p),
+      filePath: '',
+    };
+  });
+
+  // `Collector(User)` keeps `User` the same way — the type a handler names to receive it.
+  const collectors: CollectorEntry[] = (declared.collectors ?? []).map((c) => {
+    const ctor = ctorOf(c);
+
+    return {
+      typeName: subjectOf(ctor, 'collector').name,
+      ctor,
+      deps: depsOf(c),
+      filePath: '',
+    };
+  });
+
+  const providers: ProviderEntry[] = (declared.providers ?? []).map((p) => ({
+    ctor: ctorOf(p),
+    deps: depsOf(p),
+    filePath: '',
+  }));
+
+  const seeds: SeedEntry[] = (declared.seeds ?? []).map((s) => ({
+    entityName: s.entityName,
+    data: s.data,
+    filePath: '',
+  }));
+
+  return {
+    name,
+    source: { path: '', package: `${scope}/${name}` },
+    providers,
+    entities,
+    handlers,
+    presenters,
+    collectors,
+    seeds,
+    ...(declared.surfaces ? { surfaces: declared.surfaces } : {}),
+  };
+}

package/src/scan/handler-parser.ts

@@ -800,7 +800,6 @@ function parseClassMethods(
   const cls = findDefaultClass(source);
   if (!cls) return { methods: [], unresolvedHeritage: unresolved };
 
-  // Parse child class methods
   const childMethods = extractClassMethods(cls, source, skip, checker);
   const childNames = new Set(childMethods.map((m) => m.name));
 

package/src/scan/scanner.ts

@@ -458,7 +458,6 @@ async function toPresenterEntry(filePath: string): Promise<PresenterEntry | null
   const presenterParams = await ctorParamsOf(filePath);
   const deps = presenterParams.map((p) => depKeyOf(p.type));
 
-  // Parse method return types from source
   let fieldMeta: PresenterEntry['fieldMeta'] = [];
   try {
     const parsed = await presenterMethodsOf(filePath);

package/src/scan/statement.ts

@@ -0,0 +1,126 @@
+/**
+ * The scan, written as the STATEMENT an author would have written.
+ *
+ * A scan runs at build and the app runs elsewhere — two runtimes, no shared memory — so
+ * something has to cross. What used to cross was the scan RESULT: every operation's
+ * TypeScript signature re-serialized as JSON, beside the five CRUD ops `Crud.__ops`
+ * declares at runtime anyway. A second writing of what the classes carry, and one that
+ * drifts, since nothing compares the two.
+ *
+ * What crosses here is what `fronds.ts` holds: imports that bring the ORIGINAL classes
+ * back, and `frond()` calls. Everything else `frond()` derives — `Post` is stored as
+ * `post`, `PostHandler` answers at `post`, a computed field IS a method, and
+ * `Presenter(Post)` keeps its subject. Only what TypeScript erases is named: a
+ * constructor's parameter types (`deps`), and the surface a handler answers on, which the
+ * scan read from its directory.
+ *
+ * Measured on demos/nuxt-blog: 102 lines of scan against 31 of statement, and the same app
+ * — same rows, same computed fields, and no `typescript` loaded at boot.
+ */
+import { relative } from 'node:path';
+import type { FrondDescriptor, ScanResult } from './frond.js';
+
+type Live = { name?: string };
+
+/**
+ * A file becomes the specifier the PROJECT already uses for it: `@fronds/blog/…`, the
+ * import scope a handler names its neighbour by, and which the Nuxt module registers as an
+ * alias for every frond it found.
+ *
+ * A relative path would name the same file by a second route, and two routes to one module
+ * are two modules — so `Post` would not equal `Post` and every identity check would fail
+ * quietly. It also puts the file outside what the alias resolves, which is what made Node,
+ * not the bundler, read the frond's `.ts` and answer 500 on `../entities/Post.js`.
+ *
+ * `.js`, because the source is `.ts` and the project spells a TypeScript source that way
+ * everywhere else — the alias resolves through the same rule as a hand-written import.
+ */
+function specifierOf(filePath: string, frond: FrondDescriptor): string {
+  const inside = relative(frond.source.path, filePath).replace(/\.tsx?$/, '.js');
+
+  return `${frond.source.package}/${inside}`;
+}
+
+/** One alias per file, so a class imported twice is one binding and one identity. */
+class Imports {
+  private readonly byPath = new Map<string, string>();
+  private readonly lines: string[] = [];
+
+  default(filePath: string, frond: FrondDescriptor): string {
+    const known = this.byPath.get(filePath);
+    if (known) return known;
+    const alias = `_${this.byPath.size}`;
+    this.lines.push(`import ${alias} from '${specifierOf(filePath, frond)}';`);
+    this.byPath.set(filePath, alias);
+
+    return alias;
+  }
+
+  render(): string {
+    return this.lines.join('\n');
+  }
+}
+
+/** `{ ctor: X, deps: [...] }` when there is something to say, the bare class otherwise. */
+function subject(alias: string, deps: string[], extra = ''): string {
+  const parts = [
+    ...(deps.length ? [`deps: ${JSON.stringify(deps)}`] : []),
+    ...(extra ? [extra] : []),
+  ];
+
+  return parts.length ? `{ ctor: ${alias}, ${parts.join(', ')} }` : alias;
+}
+
+function frondOf(frond: FrondDescriptor, imports: Imports): string {
+  const list = (items: string[]): string => `[${items.join(', ')}]`;
+  const members: string[] = [];
+
+  if (frond.entities.length) {
+    members.push(`entities: ${list(frond.entities.map((e) => imports.default(e.filePath, frond)))}`);
+  }
+  if (frond.handlers.length) {
+    members.push(`handlers: ${list(frond.handlers.map((h) =>
+      subject(imports.default(h.filePath, frond), h.deps, h.surface ? `surface: ${JSON.stringify(h.surface)}` : '')))}`);
+  }
+  if (frond.presenters.length) {
+    members.push(`presenters: ${list(frond.presenters.map((p) => subject(imports.default(p.filePath, frond), p.deps)))}`);
+  }
+  if (frond.collectors.length) {
+    members.push(`collectors: ${list(frond.collectors.map((c) => subject(imports.default(c.filePath, frond), c.deps)))}`);
+  }
+  if (frond.providers.length) {
+    members.push(`providers: ${list(frond.providers.map((p) => subject(imports.default(p.filePath, frond), p.deps)))}`);
+  }
+  // A seed is DATA, not a class — the one member a statement cannot derive from an import.
+  if (frond.seeds.length) {
+    members.push(`seeds: ${JSON.stringify(frond.seeds.map((s) => ({ entityName: s.entityName, data: s.data })))}`);
+  }
+  if (frond.surfaces) members.push(`surfaces: ${JSON.stringify(frond.surfaces)}`);
+
+  const scope = (frond.source.package as string | undefined)?.split('/')[0];
+  if (scope) members.push(`scope: ${JSON.stringify(scope)}`);
+
+  return `  frond(${JSON.stringify(frond.name)}, {\n    ${members.join(',\n    ')},\n  })`;
+}
+
+/** The scan as a list of `frond()` calls — the file an author writes, written for them. */
+// Nothing is written relative to the destination, so where the file SITS is not a
+// parameter — the alias resolves the same from anywhere.
+export function emitStatement(scan: ScanResult): string {
+  const imports = new Imports();
+  const fronds = scan.fronds.map((f) => frondOf(f as FrondDescriptor & { source: Live }, imports));
+
+  return [
+    '// Generated by @fougere/nuxt — what the scan found, as the statement you would write.',
+    '//',
+    '// Classes are IMPORTED, never restated: `frond()` derives every name from them. Write',
+    '// your own `fronds.ts` beside `fougere.config.ts` to state this by hand instead.',
+    "import { frond } from '@fougere/core';",
+    imports.render(),
+    '',
+    'export default [',
+    `${fronds.join(',\n')},`,
+    '];',
+    '',
+  ].join('\n');
+}

package/src/wire/call.ts

@@ -8,7 +8,7 @@
  */
 import { Card, type SchemaDescriptor } from '@fougere/schema';
 import { factsAnnouncedBy } from '../emit.js';
-import type { InvocationContext } from './invocation.js';
+import type { InvocationContext } from '../contract/Invocation.js';
 import { FougereError, ErrorCode } from './errors.js';
 import type { App } from '../boot/types.js';
 import { createTransportEntry } from '../entry/TransportEntry.js';
@@ -27,6 +27,18 @@ export interface FrondCall {
 export type Transport = (call: FrondCall, invocation: InvocationContext) => Promise<unknown>;
 
 /** Reserved namespace — calls the runner answers itself, never a façade. */
+/**
+ * What a receiver accepts before it stops reading a body.
+ *
+ * Stated once because it was stated FOUR times — `transport/http/policy.ts` said so in its
+ * own comment ("spelled in four packages") while three doors kept their own literal, so
+ * raising the cap here used to leave three of them refusing at the old one.
+ *
+ * `@fougere/http` keeps a fourth copy on purpose: it declares no Fougere dependency at all,
+ * and giving a leaf port a dependency on the kernel to share a number is the wrong trade.
+ */
+export const MAX_BODY_BYTES = 1024 * 1024;
+
 export const RPC_ENTITY = 'rpc';
 
 /**

package/src/wire/drift.ts

@@ -0,0 +1,131 @@
+import { Card, type Change, type SchemaDescriptor } 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' }[];
+}
+
+/** Every door of a card, by name. */
+function doorsOf(card: IdentityCard, frond: string): Map<string, { ops: Set<string>; schema?: SchemaDescriptor }> {
+  const found = new Map<string, { ops: Set<string>; schema?: SchemaDescriptor }>();
+  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: IdentityCard, frond: string): Map<string, SchemaDescriptor | undefined> {
+  const found = new Map<string, SchemaDescriptor | undefined>();
+  for (const one of card.fronds) {
+    if (one.name !== frond) continue;
+    for (const fact of one.facts ?? []) found.set(fact.name, fact.schema as SchemaDescriptor | undefined);
+  }
+  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: IdentityCard, theirs: IdentityCard, frond: string): CardDrift {
+  const held = doorsOf(mine, frond);
+  const served = doorsOf(theirs, frond);
+  const drift: CardDrift = { 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: CardDrift): boolean {
+  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: CardDrift): string[] {
+  const lines: string[] = [];
+  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: Change): string {
+  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`;
+  }
+}

package/src/wire/middleware.ts

@@ -20,7 +20,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>;

package/dist/boot/Lifecycle.d.ts

@@ -1,4 +0,0 @@
-/** Compatibility module. Prefer AppLifecycle for the process-level lifecycle. */
-export { AppLifecycle, AppLifecycle as Lifecycle, migrating } from './AppLifecycle.js';
-export type { Extension } from './AppLifecycle.js';
-//# sourceMappingURL=Lifecycle.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"Lifecycle.d.ts","sourceRoot":"","sources":["../../src/boot/Lifecycle.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,OAAO,EAAE,YAAY,EAAE,YAAY,IAAI,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACvF,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/boot/Lifecycle.js

@@ -1,3 +0,0 @@
-/** Compatibility module. Prefer AppLifecycle for the process-level lifecycle. */
-export { AppLifecycle, AppLifecycle as Lifecycle, migrating } from './AppLifecycle.js';
-//# sourceMappingURL=Lifecycle.js.map

package/dist/boot/Lifecycle.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Lifecycle.js","sourceRoot":"","sources":["../../src/boot/Lifecycle.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,OAAO,EAAE,YAAY,EAAE,YAAY,IAAI,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/scan/scan-cache.d.ts

@@ -1,16 +0,0 @@
-export declare function setCacheRoot(dir: string): void;
-/**
- * The parse of a file, or the parse again if the file changed — the one gesture, so a
- * caller never assembles the pieces.
- *
- * It handed out `hashFile` + `getCached` + `setCached` and every caller wrote the same
- * five lines in the same order; the scanner wrote them three times, once inline inside a
- * `try`. Three assemblies of one question, each free to forget the half that stores.
- *
- * `key` and not the path alone: one file is parsed several ways (its constructor, its
- * methods, its methods with heritage resolved) and each reading is its own entry.
- */
-export declare function cachedParse<T>(key: string, filePath: string, parse: () => Promise<T>): Promise<T>;
-/** Write cache to disk if modified. */
-export declare function flushCache(): void;
-//# sourceMappingURL=scan-cache.d.ts.map

package/dist/scan/scan-cache.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"scan-cache.d.ts","sourceRoot":"","sources":["../../src/scan/scan-cache.ts"],"names":[],"mappings":"AAqDA,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAG9C;AA2BD;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAUvG;AAED,uCAAuC;AACvC,wBAAgB,UAAU,IAAI,IAAI,CAOjC"}