@fougere/core 0.6.0-alpha.0 → 0.7.0-alpha.0

package/src/verify.ts

@@ -5,24 +5,11 @@ import { storageKeyOf } from './storage.js';
 import { presenterKeyOf } from './prefab/presenter.js';
 import { collectorKeyOf } from './prefab/collector.js';
 
-/**
- * What a rule found in an app.
- *
- * `message` is the sentence the rule replaces — the prose a human used to have
- * to remember. `Known issues` says "Keep collectors in the consuming frond";
- * this is that sentence, told about a specific handler, by something that runs.
- */
+/** What a rule found in an app. */
 export interface Violation {
   /** Rule name, stable — 'cross-frond-dependency'. */
   rule: string;
-  /**
-   * What it costs, decided by the rule that raises it — never by whoever renders it.
-   *
-   * The two rules here are not the same animal: a cross-frond dependency resolves
-   * today and stops resolving the day the other frond answers over the wire, while a
-   * collector declared elsewhere is already wrong in one process. A reader holding a
-   * table of rule names would be a second opinion on a fact the rule already has.
-   */
+  /** What it costs, decided by the rule that raises it — never by whoever renders it. */
   severity: 'blocking' | 'warning';
   /** The frond the subject lives in. */
   frond: string;
@@ -30,15 +17,7 @@ export interface Violation {
   subject: string;
   /** Where to go and look. */
   filePath: string;
-  /**
-   * What the subject reaches for, and where it actually lives.
-   *
-   * `frond` above is the CONSUMER; the target used to exist only inside the
-   * sentence. A reader that has to parse prose to learn which frond a violation
-   * points at is a second opinion on a fact the checker already held — so the
-   * boot can ask "does this violation target a frond named in `remotes:`?" by
-   * reading a field.
-   */
+  /** What the subject reaches for, and where it actually lives. */
   dependsOn: { key: string; frond: string; kind: string };
   /** What breaks, and what the caller gets instead. */
   message: string;
@@ -48,20 +27,16 @@ export interface Violation {
 type Registration = { frond: string; kind: string };
 
 /**
- * The container keys a frond registers in its own scope, keyed as a handler's
- * `deps` spell them — DI resolves by type name, so both sides are PascalCase.
- *
- * Every key comes from the function that states it, never from a derivation
- * respelled here: a second reader that spells one differently finds nothing and
- * reports nothing wrong, which is the failure mode a checker must not have.
+ * The container keys a frond registers in its own scope, keyed as a handler's `deps` spell them —
+ * DI resolves by type name, so both sides are PascalCase.
  */
 function registrationsOf(frond: FrondDescriptor): Map<string, Registration> {
   const out = new Map<string, Registration>();
   const put = (key: string, kind: string) => out.set(key, { frond: frond.name, kind });
 
-  for (const p of frond.providers) put(p.ctor.name, 'provider');
-  for (const p of frond.presenters) put(presenterKeyOf(p.entityName), 'presenter');
-  for (const c of frond.collectors) put(collectorKeyOf(c.typeName), 'collector');
+  for (const provider of frond.providers) put(provider.ctor.name, 'provider');
+  for (const presenter of frond.presenters) put(presenterKeyOf(presenter.entityName), 'presenter');
+  for (const collector of frond.collectors) put(collectorKeyOf(collector.typeName), 'collector');
   for (const e of frond.entities) {
     put(storageKeyOf(e.name), 'storage');
     put(repositoryKeyOf(e.name), 'repository');
@@ -69,11 +44,7 @@ function registrationsOf(frond: FrondDescriptor): Map<string, Registration> {
   return out;
 }
 
-/**
- * Everything in a frond that is constructed by DI, so carries `deps`.
- * Handlers, presenters and collectors are all built from a constructor whose
- * argument types the scan read; each one can therefore reach across.
- */
+/** Everything in a frond that is constructed by DI, so carries `deps`. */
 function injectablesOf(frond: FrondDescriptor) {
   return [
     ...frond.handlers.map((h) => ({ name: h.ctor.name, deps: h.deps, filePath: h.filePath })),
@@ -83,20 +54,8 @@ function injectablesOf(frond: FrondDescriptor) {
 }
 
 /**
- * Does this app survive being split?
- *
- * A frond runs in-process or in its own process behind JSON-RPC with identical
- * user code — that is the whole claim. What the claim does not say is that
- * *every* app survives the move: a dependency that crosses a frond boundary
- * resolves today because both scopes live in one container, and resolves to
- * nothing the day the other frond answers over the wire.
- *
- * The question only exists where a module boundary is meant to become a process
- * boundary later. Where every inter-module call is already remote there is
- * nothing to check, and where no exit is planned there is nothing to check
- * either. Here it means something, and until now it had no answer.
- *
- * Pure over `app.fronds`: no mount, no process, no file. Call it from a test.
+ * Does this app survive being split? A frond runs in-process or in its own process behind JSON-RPC
+ * with identical user code — that is the whole claim.
  */
 export function verify(app: { fronds: readonly FrondDescriptor[] }): Violation[] {
   const index = new Map<string, Registration>();
@@ -109,7 +68,7 @@ export function verify(app: { fronds: readonly FrondDescriptor[] }): Violation[]
   // they need their own index and their own rule.
   const collectorFronds = new Map<string, string>();
   for (const frond of app.fronds) {
-    for (const c of frond.collectors) collectorFronds.set(c.typeName, frond.name);
+    for (const collector of frond.collectors) collectorFronds.set(collector.typeName, frond.name);
   }
 
   const violations: Violation[] = [];
@@ -144,8 +103,8 @@ export function verify(app: { fronds: readonly FrondDescriptor[] }): Violation[]
 
     // Rule 2 — an operation parameter that wanted a collector this frond has not
     // got. The preliminary binding convention can only see this frond's collector
-    // set, so it produces body evidence. EffectiveOperation refuses that evidence
-    // before boot: another frond's collector proves the provenance is not a body.
+    // set, so it produces input evidence. EffectiveOperation refuses that evidence
+    // before boot: another frond's collector proves the provenance is not an input.
     const own = new Set(frond.collectors.map((c) => c.typeName));
     for (const handler of frond.handlers) {
       for (const [opName, op] of handler.operations) {
@@ -156,7 +115,7 @@ export function verify(app: { fronds: readonly FrondDescriptor[] }): Violation[]
           const wanted = lowerFirst(param.type.name);
           if (own.has(wanted)) continue;
           const elsewhere = collectorFronds.get(wanted);
-          // No collector anywhere for that type may be an ordinary body parameter.
+          // No collector anywhere for that type may be an ordinary input parameter.
           // Only a collector that exists in the wrong place makes that interpretation
           // provably false.
           if (!elsewhere) continue;
@@ -170,7 +129,7 @@ export function verify(app: { fronds: readonly FrondDescriptor[] }): Violation[]
             message:
               `'${param.name}' is typed ${param.type.name}, and the collector that produces one ` +
               `is declared in frond '${elsewhere}'. A binding plan only sees its own frond's ` +
-              `collectors, so the preliminary body interpretation is invalid. Fougere refuses ` +
+              `collectors, so the preliminary input interpretation is invalid. Fougere refuses ` +
               `the operation before it can receive what the caller sent. ` +
               `Move the collector into '${frond.name}'.`,
           });

package/src/wire/CallLog.ts

@@ -0,0 +1,30 @@
+import type { RouteKind } from './RouteAddress.js';
+
+/** What crosses the door. */
+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?: RouteKind;
+  /** The traceparent the invocation carried, when one did. */
+  trace?: string;
+  /** The peer that established this call, when one did. */
+  caller?: string;
+  startedAt: number;
+  /** Known at `settled`. */
+  ms?: number;
+  verdict: 'running' | 'ok' | 'failed';
+  refusal?: { code?: string; message: string };
+}
+
+/** One page of the ring. */
+export interface CallPage {
+  calls: CallRecord[];
+  cursor: number;
+  inFlight: number;
+  dropped: number;
+}

package/src/{contract → wire}/Invocation.ts

@@ -1,15 +1,16 @@
 export interface InvocationContext {
   params: Record<string, unknown>;
   query: Record<string, unknown>;
-  body: unknown;
+  input: unknown;
   state: Record<string, unknown>;
   trace?: string;
   identity?: string;
   caller?: string;
 }
 
-export type InvocationInput = Partial<InvocationContext>;
+export type PartialInvocation = Partial<InvocationContext>;
 
+/** Freezes plain data deeply, and leaves a class instance alone — a `Date` is not a record. */
 function canonicalValue(value: unknown): unknown {
   if (value === null || value === undefined || typeof value !== 'object') return value;
   if (Array.isArray(value)) return Object.freeze(value.map(canonicalValue));
@@ -19,6 +20,7 @@ function canonicalValue(value: unknown): unknown {
   return canonicalRecord(value);
 }
 
+/** Drops the keys set to `undefined`, so an input and its JSON round-trip agree. */
 function canonicalRecord(value: unknown): Record<string, unknown> {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return Object.freeze({});
 
@@ -33,33 +35,37 @@ function canonicalRecord(value: unknown): Record<string, unknown> {
 export class Invocation implements InvocationContext {
   readonly params: Record<string, unknown>;
   readonly query: Record<string, unknown>;
-  readonly body: unknown;
+  readonly input: unknown;
   readonly state: Record<string, unknown>;
   readonly trace?: string;
   readonly identity?: string;
   readonly caller?: string;
 
-  private constructor(input: InvocationInput) {
-    this.params = canonicalRecord(input.params);
-    this.query = canonicalRecord(input.query);
-    this.body = canonicalValue(input.body);
+  /** Gives every entry and every transport the same seven-member value, frozen. */
+  private constructor(context: PartialInvocation) {
+    this.params = canonicalRecord(context.params);
+    this.query = canonicalRecord(context.query);
+    this.input = canonicalValue(context.input);
     // State is host-owned and may still be enriched by existing middlewares. Moving it
     // to immutable lifecycle context is a separate migration.
-    this.state = input.state ?? {};
-    if (input.trace !== undefined) this.trace = input.trace;
-    if (input.identity !== undefined) this.identity = input.identity;
-    if (input.caller !== undefined) this.caller = input.caller;
+    this.state = context.state ?? {};
+    if (context.trace !== undefined) this.trace = context.trace;
+    if (context.identity !== undefined) this.identity = context.identity;
+    if (context.caller !== undefined) this.caller = context.caller;
     Object.freeze(this);
   }
 
-  static from(input?: InvocationInput): Invocation {
-    return input instanceof Invocation ? input : new Invocation(input ?? {});
+  /** Takes a raw object or an invocation, so a caller never has to know which it holds. */
+  static from(context?: PartialInvocation): Invocation {
+    return context instanceof Invocation ? context : new Invocation(context ?? {});
   }
 
-  withBody(body: unknown): Invocation {
-    return new Invocation({ ...this, body });
+  /** Replaces the input — how the façade hands on the value it parsed. */
+  withInput(input: unknown): Invocation {
+    return new Invocation({ ...this, input });
   }
 
+  /** Replaces the host-owned state, which a middleware enriches before the handler runs. */
   withState(state: Record<string, unknown>): Invocation {
     return new Invocation({ ...this, state });
   }
@@ -67,6 +73,7 @@ export class Invocation implements InvocationContext {
 
 export const EMPTY_INVOCATION = Invocation.from();
 
-export function canonicalInvocation(input?: InvocationInput): Invocation {
-  return Invocation.from(input);
+/** Names the same gesture as `Invocation.from` for callers that read better this way. */
+export function canonicalInvocation(context?: PartialInvocation): Invocation {
+  return Invocation.from(context);
 }

package/src/{contract → wire}/RouteAddress.ts

@@ -7,11 +7,13 @@ export interface RouteAddressInput {
   surface?: string;
 }
 
+/** Refuses an empty segment, so no address can be built that nothing can serve. */
 function required(value: string, name: string): string {
   if (value.trim().length === 0) throw new TypeError(`Route ${name} cannot be empty`);
   return value;
 }
 
+/** Applies the same refusal to a segment that may be absent, but not blank. */
 function optional(value: string | undefined, name: string): string | undefined {
   return value === undefined ? undefined : required(value, name);
 }
@@ -22,6 +24,7 @@ export class RouteAddress {
   readonly operation: string;
   readonly surface?: string;
 
+  /** Names one callable operation, and freezes it so a registry key cannot drift. */
   constructor(input: RouteAddressInput) {
     this.entity = required(input.entity, 'entity');
     this.operation = required(input.operation, 'operation');
@@ -29,19 +32,23 @@ export class RouteAddress {
     Object.freeze(this);
   }
 
+  /** Serializes the three segments so a route can be looked up in a `Map`. */
   key(): string {
     return JSON.stringify([this.surface ?? null, this.entity, this.operation]);
   }
 
+  /** Compares two addresses by their key, so `surface` counts as much as the operation. */
   equals(other: RouteAddress): boolean {
     return this.key() === other.key();
   }
 
+  /** Writes the address the way a log and an error message name it. */
   toString(): string {
     const audience = this.surface ? `${this.surface}/` : '';
     return `${audience}${this.entity}.${this.operation}`;
   }
 
+  /** Sends the address over the wire without `surface: undefined` riding along. */
   toJSON(): RouteAddressInput {
     return {
       entity: this.entity,

package/src/wire/binding.ts

@@ -1,10 +1,6 @@
 /**
- * Where each parameter of an operation gets its value — decided once at boot from the
- * parsed signature, replayed per call by `resolveArgs`.
- *
- * The branches are ORDERED and each states why it sits where it does; the list used to
- * be repeated here too, and it had already lost `Fact` — the one whose position is
- * load-bearing, since the fall-through would otherwise hand it the caller's body.
+ * Where each parameter of an operation gets its value — decided once at boot from the parsed
+ * signature, replayed per call by `resolveArgs`.
  */
 import type { Param } from './signature.js';
 import { lowerFirst } from '@fougere/schema';
@@ -13,17 +9,10 @@ import { lowerFirst } from '@fougere/schema';
 
 type ParamSource =
   | { kind: 'collector'; typeName: string }
-  /**
-   * `Fact<PostPublished>` — something that happened, not something a caller typed.
-   *
-   * It resolves from the body exactly like `body` does, and that is deliberate: an
-   * emission and a direct call ARE the same call, so a subscriber cannot tell them apart
-   * and does not need to. The branch exists so the PLAN says what this parameter is —
-   * that sentence is what makes the subscriber index readable without reparsing types.
-   */
+  /** `Fact<PostPublished>` — something that happened, not something a caller typed. */
   | { kind: 'fact'; factName: string }
   | { kind: 'param'; name: string; coerce?: 'number' | 'boolean' }
-  | { kind: 'body' }
+  | { kind: 'input' }
   | { kind: 'context' }
   /** The whole query bag, for an op whose argument IS the options (list). */
   | { kind: 'query' };
@@ -48,12 +37,7 @@ function coercionFor(typeName: string): 'number' | 'boolean' | undefined {
 
 // ── Compute ───────────────────────────────────
 
-/**
- * Build a BindingPlan from parsed method params.
- *
- * @param params - Parsed parameter list from AST
- * @param collectorTypeNames - Registration keys of the types a Collector answers for
- */
+/** Build a BindingPlan from parsed method params. */
 export function computeBindingPlan(
   params: Param[],
   collectorTypeNames: Set<string>,
@@ -62,11 +46,11 @@ export function computeBindingPlan(
     const typeName = param.type.name;
     // `lowerFirst`, never `toLowerCase()`: the collector set is keyed the way the
     // scan spells it, and the two agree on one word only — `AuthorUser` looked up as
-    // `authoruser` missed `authorUser` and fell through to branch 4, the request body.
+    // `authoruser` missed `authorUser` and fell through to branch 4, the request input.
     const typeKey = lowerFirst(typeName);
 
     // 0. Fact — `Fact<X>` names itself, so nothing has to be known in advance. It comes
-    //    FIRST because branch 4 would otherwise hand it the caller's body under the name
+    //    FIRST because branch 4 would otherwise hand it the caller's input under the name
     //    of something that happened.
     const factOf = param.type.name === 'Fact' ? param.type.generics?.[0]?.name : undefined;
     if (factOf) {
@@ -108,10 +92,10 @@ export function computeBindingPlan(
       };
     }
 
-    // 4. Everything else — body
+    // 4. Everything else — input
     return {
       name: param.name,
-      source: { kind: 'body' as const },
+      source: { kind: 'input' as const },
       optional: param.optional ?? false,
     };
   });

package/src/wire/call.ts

@@ -1,16 +1,22 @@
-/**
- * Call contract — a frond call is a value.
- *
- * (frond, entity, op, invocation) → result, or a thrown FougereError.
- * A transport is a function that executes this call elsewhere; the local
- * runner below is the reference realization. Transports move the value,
- * they never reshape it.
- */
+/** Call contract — a frond call is a value. */
 import { Card, type SchemaDescriptor } from '@fougere/schema';
 import { factsAnnouncedBy } from '../emit.js';
-import type { InvocationContext } from '../contract/Invocation.js';
+import { Invocation, type InvocationContext, type PartialInvocation } from './Invocation.js';
+import type { RouteAddress } from './RouteAddress.js';
 import { FougereError, ErrorCode } from './errors.js';
 
+/** One normalized request, frozen: where it goes and what the caller supplied. */
+export class Call {
+  readonly address: RouteAddress;
+  readonly invocation: Invocation;
+
+  constructor(address: RouteAddress, invocation?: PartialInvocation) {
+    this.address = address;
+    this.invocation = Invocation.from(invocation);
+    Object.freeze(this);
+  }
+}
+
 /** Target of a call — which façade operation, wherever it lives. */
 export interface FrondCall {
   /** Frond name, when the caller knows it. Routing hint only. */
@@ -25,49 +31,27 @@ 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.
- */
+/** What a receiver accepts before it stops reading an input. */
 export const MAX_BODY_BYTES = 1024 * 1024;
 
 export const RPC_ENTITY = 'rpc';
 
-/**
- * What an `rpc` op answers — the door for what the app says about ITSELF, never about a row.
- *
- * `discover` is core's own, registered like any other (`bootstrap.ts`): a package declares
- * its reading beside it, and an app that installed none serves none.
- */
+/** What an `rpc` op answers — the door for what the app says about ITSELF, never about a row. */
 export type RpcAnswer = (invocation: InvocationContext, surface?: string) => unknown;
 
-/**
- * Everything a caller's envelope covers — the call as the sender meant it.
- *
- * Here and not beside the signing code because it is a CONTRACT: the sender binds it,
- * the receiver re-presents what arrived, and a frond written in another language reads
- * this shape without reading our crypto. `body` is bound by digest (arbitrary, possibly
- * large), the rest by value — which is what keeps a canonical-JSON dependency out.
- */
+/** Everything a caller's envelope covers — the call as the sender meant it. */
 export interface SignedCall {
   entity: string;
   op: string;
   params?: Record<string, unknown>;
   query?: Record<string, unknown>;
-  body?: unknown;
+  input?: unknown;
   state?: Record<string, unknown>;
 }
 
 /**
- * One operation, as a stranger meets it — its name, what it is for, what it takes
- * and whether it reads or writes. Everything here already existed on the contract;
- * it just never left the process.
+ * One operation, as a stranger meets it — its name, what it is for, what it takes and whether it
+ * reads or writes.
  */
 export interface CardOp {
   name: string;
@@ -79,57 +63,21 @@ export interface CardOp {
   output?: SchemaDescriptor;
   /** `query` reads, `command` writes — the same call REST turns into GET vs POST. */
   kind: 'query' | 'command';
-  /**
-   * How much `output` describes: one row, maybe one, many, a page, or nothing shaped.
-   * `output` alone is the shape of a ROW, so a consumer generating a signature from
-   * this card would otherwise have to guess — and `list` returning a page rather than
-   * an array is exactly the guess it would get wrong.
-   */
+  /** How much `output` describes. */
   cardinality?: 'one' | 'maybe' | 'many' | 'page' | 'none';
 }
 
-/**
- * What an app hosts — the wire projection of its scanned fronds.
- *
- * Two lists per frond, and they are duals: **what you may call**, and **what you will
- * receive**. A door is entered from outside; a fact leaves on its own.
- *
- * `doors` was called `entities` and the name lied: an entry is an ADDRESS, and the shape
- * behind it is optional (`facadeKeyOf` builds its key from a handler's name, which need not
- * be an entity's). The lie cost something real — `fougere sync` demanded a descriptor on
- * every entry and refused whole cards over a health check.
- */
+/** What an app hosts — the wire projection of its scanned fronds. */
 export interface IdentityCard {
   fronds: {
     name: string;
     doors: {
       name: string;
       ops: CardOp[];
-      /**
-       * The shape stored under this name — **absent when nothing is**. A handler may
-       * carry no entity (`bootstrap`: *pointing at nothing is legal*), and a door with
-       * no rows behind it is ordinary: a health check, a computation, a search across
-       * several shapes. A reader that needs the shape must say what it does without one.
-       */
+      /** The shape stored under this name — **absent when nothing is**. */
       schema?: SchemaDescriptor;
     }[];
-    /**
-     * The facts this frond ANNOUNCES — one entry per `Emit<T>` its handlers inject.
-     *
-     * They carry no operation, which is why they cannot ride in `doors`: the rule there is
-     * *hosting means answering*, and an entity with no façade is excluded on purpose (it
-     * would publish the auth tables to anyone who asks). A fact is the opposite case —
-     * someone WROTE that it leaves, so publishing its shape is honouring a statement, not
-     * leaking one.
-     *
-     * Without this, a fact stopped at the repository boundary: `remotes:` gives the
-     * location, colocation gives the contract, and across two repositories there is no
-     * colocation. The subscriber had to hand-copy the emitter's declaration.
-     *
-     * `schema` is absent when the announced type is not a declared entity — legal (nothing
-     * requires a fact to be one) and worth saying rather than hiding: the name travels, the
-     * shape does not, and a consumer can see exactly that.
-     */
+    /** The facts this frond ANNOUNCES — one entry per `Emit<T>` its handlers inject. */
     facts: { name: string; schema?: SchemaDescriptor }[];
   }[];
 }
@@ -150,17 +98,7 @@ export interface Edge {
   errors: number;
 }
 
-/**
- * The shape of the system as ONE process discovered it — the answer to `rpc.topology`.
- *
- * Here and not in the package that produces it, for the reason `SignedCall` is here: it
- * crosses a process boundary, so a reader consumes it without depending on the producer.
- * `@fougere/observability` fills it; a panel reads it; neither imports the other.
- *
- * Nothing in it is declared — a frond is `local` because this process scanned it, `remote`
- * because it answered a call nobody here hosts. `remotes:` states an intent, and the two
- * disagree exactly when something is misconfigured.
- */
+/** The shape of the system as ONE process discovered it — the answer to `rpc.topology`. */
 export interface TopologyReport {
   /** When this process started counting — an edge count is read against it. */
   since: number;
@@ -170,18 +108,7 @@ export interface TopologyReport {
   edges: Edge[];
 }
 
-/**
- * The shape a card must have to be walked — `fronds`, and each frond's `doors`.
- *
- * A card crosses a process boundary, so it is judged like anything else that does.
- * The check lives beside the type because two readers walk it: the boot indexes a
- * remote's doors, and `fougere sync` writes classes from them. `TypeError:
- * card.fronds is not iterable` was what a malformed card produced at the boot,
- * naming neither the remote nor the address.
- *
- * The descriptor behind a door is NOT checked here — `Card.toSchema` refuses it, and
- * only where one is consumed.
- */
+/** The shape a card must have to be walked — `fronds`, and each frond's `doors`. */
 export function assertIdentityCard(value: unknown, source: string): IdentityCard {
   const card = value as IdentityCard | undefined;
   const fronds = Array.isArray(card?.fronds) ? card.fronds : undefined;
@@ -205,49 +132,19 @@ function cardRefusal(source: string, what: string): FougereError {
 
 /** A façade as the runtime holds it: op names to functions, nothing typed about them. */
 
-/**
- * The door built in front of a handler — the framework's second port, after `Storage`.
- *
- * `Facade<PostHandler>` is what a neighbouring frond injects. It names what ARRIVES
- * rather than what is written: never the handler (nobody injects it, and its methods take
- * positional arguments), but the door, whose every op takes the invocation and whose
- * implementation is the local façade or a doublure. A signature therefore says nothing
- * about where the other frond runs, which is the whole point.
- *
- * `keyof T` is the right set by construction, not by approximation: the scan skips
- * `private` and `protected` (`handler-parser.ts`) because "TypeScript already has the
- * word for it", so a handler's public methods ARE its operations — and `keyof` excludes
- * the rest for the same reason.
- */
+/** The door built in front of a handler — the framework's second port, after `Storage`. */
 export type Facade<T> = {
   [K in keyof T]: T[K] extends (...args: never[]) => infer R
     ? (invocation?: InvocationContext) => R
     : never;
 };
 
-/**
- * The container key of a façade — THE one place that spells the format.
- *
- * A surface is a named audience, and it is a key: `handlers/public/PostHandler.ts`
- * registers `public:postHandler` next to the default `postHandler`. The default
- * surface is the empty key, so callers that know nothing about surfaces keep
- * designating exactly what they designated before.
- *
- * Nobody outside this package builds this string: adapters ask `app.facadeFor()`,
- * which is why an adapter can stay structurally typed and core-free.
- */
+/** The container key of a façade — THE one place that spells the format. */
 export function facadeKeyOf(entityName: string, surface?: string): string {
   return surface ? `${surface}:${entityName}Handler` : `${entityName}Handler`;
 }
 
-/**
- * Where the contracts behind a façade live — the dual of `facadeKeyOf`.
- *
- * The façade answers calls; it does not say what it answers. That sentence used
- * to be true only inside `buildFacade`, so anything asking the app what it hosts
- * got bare names. A door and its terms are registered together, under the same
- * audience.
- */
+/** Where the contracts behind a façade live — the dual of `facadeKeyOf`. */
 export function contractsKeyOf(entityName: string, surface?: string): string {
   return `${facadeKeyOf(entityName, surface)}:contracts`;
 }