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

package/src/effective-operation.ts

@@ -1,10 +1,4 @@
-/**
- * The operation model after every declaration and convention has been resolved.
- *
- * The scanner produces evidence. This module turns that evidence into the one table
- * boot, check, explain and protocol projections consume. It is deliberately pure: no
- * container, filesystem, migration or handler construction is involved.
- */
+/** The operation model after every declaration and convention has been resolved. */
 import { lowerFirst, type SchemaView } from '@fougere/schema';
 import { statementDrift } from './boot/statement-drift.js';
 import { computeBindingPlan, type BindingPlan } from './wire/binding.js';
@@ -232,7 +226,7 @@ export function resolveEffectiveOperations(
           resolutionDiagnostics,
         )) continue;
 
-        // A fact is judged by the entity it names. This used to be patched into the
+        // A fact is validated by the entity it names. This used to be patched into the
         // facade after resolution, leaving check/explain with a different input.
         let input = contract.input;
         if (!input) {
@@ -326,9 +320,9 @@ export function resolveEffectiveOperations(
 function groupedCollectors(collectors: readonly CollectorEntry[]): Map<string, CollectorEntry[]> {
   const grouped = new Map<string, CollectorEntry[]>();
   for (const collector of collectors) {
-    const held = grouped.get(collector.typeName) ?? [];
-    held.push(collector);
-    grouped.set(collector.typeName, held);
+    const sameName = grouped.get(collector.typeName) ?? [];
+    sameName.push(collector);
+    grouped.set(collector.typeName, sameName);
   }
   return grouped;
 }
@@ -359,9 +353,9 @@ function normalizeBinding(
   // Array order is never allowed to become semantic authority.
   const byName = new Map<string, Binding[]>();
   for (const binding of contract.binding) {
-    const held = byName.get(binding.name) ?? [];
-    held.push(binding);
-    byName.set(binding.name, held);
+    const sameName = byName.get(binding.name) ?? [];
+    sameName.push(binding);
+    byName.set(binding.name, sameName);
   }
   const expected = new Set(params.map((param) => param.name));
   const invalid = params.filter((param) => (byName.get(param.name)?.length ?? 0) !== 1);
@@ -403,14 +397,14 @@ function validateProvenance(
   const ambiguousInput = diagnostics.some((diagnostic) =>
     diagnostic.code === 'input-contract-ambiguous'
     && diagnostic.subject === `${handler.ctor.name}.${name}`);
-  const body = parameters.filter((parameter) => parameter.binding.source.kind === 'body');
+  const fromInput = parameters.filter((parameter) => parameter.binding.source.kind === 'input');
   const inferredBody = new Set<EffectiveParameter>();
 
   if (!explicitBinding && !ambiguousInput && contract.input) {
-    if (body.length === 1) {
-      inferredBody.add(body[0]!);
-    } else if (body.length > 1) {
-      const matches = body.filter((parameter) =>
+    if (fromInput.length === 1) {
+      inferredBody.add(fromInput[0]!);
+    } else if (fromInput.length > 1) {
+      const matches = fromInput.filter((parameter) =>
         schemaMatches(contract.input!, contract.signature?.params[parameter.position]?.type));
       if (matches.length > 1) {
         diagnostics.push({
@@ -419,7 +413,7 @@ function validateProvenance(
           filePath: handler.filePath,
           frond: frond.name,
           subject: `${handler.ctor.name}.${name}`,
-          message: `Cannot resolve which parameter of ${handler.ctor.name}.${name} receives the body: `
+          message: `Cannot resolve which parameter of ${handler.ctor.name}.${name} receives the input: `
             + `${matches.map((parameter) => `${parameter.name}: ${parameter.type ?? 'unknown'}`).join('; ')} `
             + 'all match the resolved input contract. Declare an explicit binding plan.',
         });
@@ -430,9 +424,9 @@ function validateProvenance(
   }
 
   // A type written with an inline object literal names nothing a collector can register
-  // under, so the parameter IS the body. Only a NAMED type can be the wrong-frond
+  // under, so the parameter IS the input. Only a NAMED type can be the wrong-frond
   // substitution the refusal below exists for.
-  for (const parameter of body) {
+  for (const parameter of fromInput) {
     if (structural(contract.signature?.params[parameter.position]?.type)) inferredBody.add(parameter);
   }
 
@@ -455,7 +449,7 @@ function validateProvenance(
       }
       continue;
     }
-    if (source.kind !== 'body' || explicitBinding || ambiguousInput) continue;
+    if (source.kind !== 'input' || explicitBinding || ambiguousInput) continue;
 
     const typeName = lowerFirst(contract.signature?.params[parameter.position]?.type.name ?? '');
     const elsewhere = fronds.flatMap((candidate) => candidate === frond
@@ -463,12 +457,12 @@ function validateProvenance(
       : candidate.collectors.filter((collector) => collector.typeName === typeName));
     if (elsewhere.length > 0) {
       // verify() supplies the more complete topology diagnostic; do not also call this
-      // an unknown body.
+      // an unknown input.
       continue;
     }
 
-    // An inferred body must be backed by exactly one resolved interpretation. With one
-    // body, the input itself is sufficient evidence; with several, exactly one type may
+    // An inferred input must be backed by exactly one resolved interpretation. With one
+    // input, the value itself is sufficient evidence; with several, exactly one type may
     // match. Explicit plans are authoritative because they state every provenance.
     const recognized = explicitBinding || inferredBody.has(parameter);
     if (recognized) continue;
@@ -596,30 +590,7 @@ function uniqueDiagnostics(diagnostics: readonly ScanDiagnostic[]): ScanDiagnost
   });
 }
 
-/**
- * The contract of every operation a handler serves — the three producers, merged once.
- *
- * This lived inline in `buildFacade`, which made the façade the only thing that could
- * answer "what is this op's contract, really?". Anything else asking — a checker, a
- * client generator, a descriptor — had to redo the merge, and a second opinion that
- * drifts reports nothing wrong while looking at the wrong thing.
- *
- * The order is a claim about authority, not a convenience:
- *
- *   1. a prefab DECLARES what it built (`Crud(E).__ops`) — runtime, so it survives a
- *      scan that resolved nothing;
- *   2. the scan DERIVES from source — a method written in this very file is the
- *      author's own word and beats everything; a method it merely READ on a base
- *      class is a guess about someone else's code, and yields to that code's own
- *      declaration;
- *   3. `frond.config.ts` STATES — the most explicit statement, made by whoever
- *      assembles the app, and the only answer for an op inherited from an installed
- *      base class the workspace-only scan cannot see. Merged per key, so stating a
- *      `binding` alone does not erase an `input` the scan found.
- *
- * Pure: no container, no instance, no disk. The binding plan is resolved here, so
- * nothing downstream ever meets an AST.
- */
+/** The contract of every operation a handler serves — the three producers, merged once. */
 export function resolveContracts(
   handler: Pick<HandlerEntry, 'ctor' | 'operations'>,
   overrides: FrondDescriptor['operationsOverrides'],

package/src/emit.ts

@@ -1,61 +1,13 @@
-/**
- * Announcing a fact — the half of the topology `remotes:` never covered.
- *
- * Every other call in Fougere names **one** recipient: `remotes` names one address per
- * frond, `Facade<T>` resolves one door. `Emit<T>` names a **subject** instead, and the
- * number of readers is not the emitter's business.
- *
- * ```ts
- * constructor(private published: Emit<PostPublished>) {}
- * await this.published({ id, title });          // I say it happened. I do not know who cares.
- *
- * async reindex(fact: Fact<PostPublished>) {}   // any handler, any frond. Nothing to register.
- * ```
- *
- * **It is a resolver, not a channel.** A bus moves messages — it has a queue, an envelope
- * format, a delivery semantic. This has none of that: it answers *who*, then hands over to
- * the call path that already exists. It is `resolve` returning N things instead of one.
- * That is also why temporal decoupling stays out of reach: a resolver holds nothing. The
- * day at-least-once is wanted, a real channel goes UNDER this, in the transport — the
- * dispatch line becomes a publish and a consumer calls the same door on the far side.
- */
+/** Announcing a fact — the half of the topology `remotes:` never covered. */
 import { lowerFirst } from '@fougere/schema';
 
-/**
- * What an emitter injects. Resolved by type, like `Storage<Post>` and `Facade<T>`.
- *
- * The returned promise settles when the fact has been **dispatched**, never when it has
- * been handled: a subscriber's failure is its own. The `EventBus` this replaces did
- * `await Promise.all(handlers)` and handed their rejections back, which made a publication
- * hostage to its own indexer.
- */
+/** What an emitter injects. */
 export type Emit<T> = (fact: T) => Promise<void>;
 
-/**
- * What a subscriber accepts — and what it PROMISES about itself.
- *
- * Not merely "I subscribe". Push is the strict mode and pull is a special case of it: an
- * op written for push is correct when called directly, the reverse is false. So this
- * wrapper commits the operation to three things its author must honour, because no type
- * can check them:
- *
- * 1. **replayable** — delivery is at-least-once the day a broker sits underneath;
- * 2. **no reader for its return** — nobody receives what it hands back;
- * 3. **owner of its failures** — they reach a log, never the emitter.
- *
- * It is the identity at runtime. The scan reads the written name, which is the whole
- * mechanism: `binding.ts` sees `Fact<X>` and binds the parameter as a fact instead of
- * letting it fall through to "everything else — body".
- */
+/** What a subscriber accepts — and what it PROMISES about itself. */
 export type Fact<T> = T;
 
-/**
- * The container key of an emission — THE one place that spells the format.
- *
- * Its dual is right below, because the boot reads the fact back out of a handler's `deps`
- * to know which emissions to register. A key and the way to undo it belong together: the
- * pair that is split is the pair that drifts.
- */
+/** The container key of an emission — THE one place that spells the format. */
 export function emitKeyOf(fact: string): string {
   return `${lowerFirst(fact)}Emit`;
 }
@@ -69,17 +21,7 @@ export function factOfEmitKey(key: string): string | undefined {
     : undefined;
 }
 
-/**
- * What a set of handlers ANNOUNCES — `Emit<T>` read back out of their dependencies.
- *
- * Two readers, which is exactly why it is a function and not a line: the boot registers one
- * emission value per name, and the identity card publishes the same set. Spelled twice they
- * would drift the day an emission stops being a constructor dependency.
- *
- * The dual — what a handler ACCEPTS — is not here, because it is not read the same way: a
- * `Fact<T>` parameter is a fact about one operation, and `computeBindingPlan` has already
- * written it into the plan (`app.listensTo()`).
- */
+/** What a set of handlers ANNOUNCES — `Emit<T>` read back out of their dependencies. */
 export function factsAnnouncedBy(handlers: readonly { deps: readonly string[] }[]): string[] {
   return [...new Set(
     handlers

package/src/entry/facade.ts

@@ -0,0 +1,44 @@
+import { Call } from '../wire/call.js';
+import type { PartialInvocation } from '../wire/Invocation.js';
+import { RouteAddress } from '../wire/RouteAddress.js';
+import type { DispatchPort } from '../dispatch/DispatchPort.js';
+
+type Operation = (...args: any[]) => unknown;
+
+/** Facade for a contract whose operation names are only known at discovery. */
+export function dynamicOperations(operation: (name: string) => Operation): Record<string, Operation> {
+  const isOperationName = (name: string | symbol): name is string =>
+    typeof name === 'string'
+    && name !== 'then'
+    && name !== 'toJSON'
+    && !Object.hasOwn(Object.prototype, name);
+
+  return new Proxy({}, {
+    get: (_target, name) => (isOperationName(name) ? operation(name) : undefined),
+    has: (_target, name) => isOperationName(name),
+    getOwnPropertyDescriptor: (_target, name) => (isOperationName(name)
+      ? { value: operation(name), writable: false, enumerable: true, configurable: true }
+      : undefined),
+  });
+}
+
+/** Turns facade method calls into canonical dispatches. */
+export function facadeOperations(
+  dispatcher: DispatchPort,
+  entity: string,
+  operationNames?: Iterable<string>,
+  surface?: string,
+): Record<string, Operation> {
+  const operation = (name: string): Operation => (invocation) => dispatcher.dispatch(new Call(
+    new RouteAddress({
+      entity,
+      operation: name,
+      ...(surface !== undefined ? { surface } : {}),
+    }),
+    invocation,
+  ));
+
+  return operationNames
+    ? Object.fromEntries([...operationNames].map((name) => [name, operation(name)]))
+    : dynamicOperations(operation);
+}

package/src/entry/transport.ts

@@ -0,0 +1,16 @@
+import { Call } from '../wire/call.js';
+import { RouteAddress } from '../wire/RouteAddress.js';
+import type { DispatchPort } from '../dispatch/DispatchPort.js';
+import type { Transport } from '../wire/call.js';
+
+/** Adapts the historical transport signature to the canonical dispatch port. */
+export function createTransportEntry(dispatcher: DispatchPort, surface?: string): Transport {
+  return (legacy, invocation) => dispatcher.dispatch(new Call(
+    new RouteAddress({
+      entity: legacy.entity,
+      operation: legacy.op,
+      ...(surface !== undefined ? { surface } : {}),
+    }),
+    invocation,
+  ));
+}

package/src/frond-config.ts

@@ -5,45 +5,11 @@ import type { BindingPlan } from './wire/binding.js';
 
 // ── Types ────────────────────────────────────────
 
-/**
- * Per-operation override. Config takes precedence over conventions (isReadOp, facade lookup).
- *
- * Two families of keys, and they act at different depths:
- *
- * - **Resolution** (`kind`, `handler`, `method`) — intent and implementation, resolved
- *   once into core's `EffectiveOperation`; every local or remote door consumes it.
- * - **Projection** (`graphql`) — protocol vocabulary, read only by that adapter.
- * - **Contract** (`input`, `output`, `binding`) — what the op IS. Read by the façade,
- *   and this is the third producer of an {@link OperationContract}: a prefab DECLARES its
- *   ops (`Crud.__ops`), the scan DERIVES them from source, config STATES them outright.
- *   The façade cannot tell the three apart.
- *
- * Stating a contract here makes the scan optional rather than load-bearing. Two cases it
- * answers that nothing else does:
- * - a method inherited from an **installed** base class — the scan resolves nothing there
- *   (workspace-only heritage) and says nothing, so the op silently misses the façade;
- * - an operation inherited from a declaration unavailable to the project's type checker.
- *
- * Config wins over both other producers — it is the most explicit statement, made by
- * whoever assembles the app. Precedence: CLI > frond config > fougere config > scan >
- * conventions.
- */
+/** Per-operation override. */
 export interface OperationOverride {
-  /**
-   * Force operation kind, over the naming convention (`isReadOp`).
-   *
-   * The convention reads the NAME, which is a weak signal — an app naming its reads in
-   * domain terms (`ofBook`, `roots`, `bySlug`) matches no prefix and every one of them is
-   * published as a mutation and a POST. This is the only place that fixes it.
-   */
+  /** Force operation kind, over the naming convention (`isReadOp`). */
   kind?: 'query' | 'command';
-  /**
-   * The GraphQL root field this op answers to. Defaults to the method name.
-   *
-   * A GraphQL root is flat, so two handlers naming a method `ofBook` claim one field and
-   * the build is refused, naming both. Nothing is renamed for you: the root vocabulary is
-   * the app's, and a derived name would move the day a distant frond gained an entity.
-   */
+  /** The GraphQL root field this op answers to. */
   graphql?: string;
   /**
    * Handler class to delegate to (overrides the default `{Entity}Handler` lookup).
@@ -52,22 +18,12 @@ export interface OperationOverride {
   handler?: EntityConstructor;
   /** Method name on `handler` (defaults to the operation name). */
   method?: string;
-  /**
-   * CASL ability check (e.g. 'archive Post'). **Declared, not implemented** — no
-   * reader interprets it today, in any adapter. Kept as the named slot for the
-   * question rather than silently dropped, but do not rely on it: a config that
-   * states a policy is not enforced anywhere.
-   *
-   * Wiring it means adopting a rules engine, which is precisely what the design
-   * turns down: an identity-dependent right is judged INSIDE the operation
-   * (`publish` reads `post.authorId !== user.id`), and a door-dependent one is a
-   * surface. Neither needs a second vocabulary evaluated by a second engine.
-   */
+  /** CASL ability check (e.g. */
   policy?: string;
 
   // ── The contract itself — see the note above ──
 
-  /** What judges the input. The view carries its own mode (`partial()` → patch). */
+  /** What validates the input. The view carries its own mode (`partial()` → patch). */
   input?: SchemaView;
   /**
    * Where each argument is read from — states what the scan would otherwise derive
@@ -82,18 +38,7 @@ export interface OperationOverride {
 export interface FrondConfig {
   /** Class names exposed as the frond's public contract (all surfaces). */
   expose?: string[];
-  /**
-   * The entities this frond may read ACROSS sources, by name.
-   *
-   * It is not a permission checked after the fact: the list IS the environment a
-   * cross-source query runs in — a source holding none of these is never opened, so
-   * its tables do not exist in that connection. `facadeFor` excludes an entity with no
-   * door on purpose ("it would publish the auth tables to anyone who asks"), and a SQL
-   * door at app scope would hand them over; this is what keeps it shut.
-   *
-   * Declaring it is what makes `Reads` injectable here. A frond that declares none
-   * asks for none, and nothing is attached on its behalf.
-   */
+  /** The entities this frond may read ACROSS sources, by name. */
   reads?: string[];
   /** Per-surface entity lists. Overrides default deduction for each named surface. */
   surfaces?: Record<string, string[]>;
@@ -105,15 +50,7 @@ export interface FrondConfig {
 
 // ── Helper ───────────────────────────────────────
 
-/**
- * Define a frond configuration (typed identity helper).
- *
- * ```ts
- * // fronds/auth/frond.config.ts
- * import { defineFrond } from '@fougere/core'
- * export default defineFrond({ expose: ['User', 'AuthHandler'] })
- * ```
- */
+/** Define a frond configuration (typed identity helper). */
 export function defineFrond(config: FrondConfig): FrondConfig {
   return config;
 }

package/src/identity-keys.ts

@@ -1,14 +1,4 @@
-/**
- * Making keys and issuing grants — the half of identity that runs at a DEPLOYMENT.
- *
- * It sits on the Node entry because it is the CLI speaking: `fougere keys` generates a
- * pair, `fougere grant` binds a name to one, and both happen once, on a machine with a
- * filesystem. Neither is reachable from a request path, so nothing here is on any hot
- * path and `generateKeyPairSync` — the one gesture WebCrypto could not replace without
- * changing what a key IS — never has to leave `node:crypto`.
- *
- * The verifying half is elsewhere (`identity.ts`) because it runs per call, everywhere.
- */
+/** Making keys and issuing grants — the half of identity that runs at a DEPLOYMENT. */
 import { createPrivateKey, createPublicKey, generateKeyPairSync, sign } from 'node:crypto';
 import { b64url } from './crypto/encoding.js';
 
@@ -22,11 +12,8 @@ export function generateKeyPair(): { privateKey: string; publicKey: string } {
 }
 
 /**
- * Bind a name to a public key, signed by the root — the whole of what a receiver
- * needs to recognize a frond it has never seen.
- *
- * `ttlDays` bounds the damage of a leaked frond key without a revocation list:
- * re-issuing is a deployment, which is the same gesture that leaked it.
+ * Bind a name to a public key, signed by the root — the whole of what a receiver needs to
+ * recognize a frond it has never seen.
  */
 export function issueGrant(
   rootPrivateKey: string,

package/src/identity.ts

@@ -1,35 +1,4 @@
-/**
- * Who is calling — the proof, not the claim.
- *
- * `InvocationContext.state` is what a caller SAYS about itself, and a split receiver
- * used to believe it: identity read straight off the wire, so a reader could post
- * `{ state: { user: { role: 'admin' } } }` and be one. This module is what turns that
- * sack into something a receiver establishes instead of accepts.
- *
- * Two signatures, one public key to distribute:
- *
- *   GRANT      the root says "this key is `blog`"   — issued once, at deployment
- *   ENVELOPE   `blog` says "here is my whole call"   — signed per call
- *
- * The envelope binds the CALL and not only its state: address, params, query, a digest
- * of the body. Signing the state alone proved WHO without proving WHAT, so anyone on the
- * wire could replay a captured envelope against another operation for as long as it
- * stayed valid — `post.list` re-sent as `post.delete`, same signature, still good.
- *
- * A receiver holds the root's public key and nothing else: it validates any frond it
- * has never seen, which is what a per-caller list could not do. The private root key
- * signs grants and never leaves the machine that issued them.
- *
- * Ed25519 and a JWS-shaped grant rather than X.509: node can PARSE a certificate but
- * not ISSUE one, so a real chain would mean openssl or a library. The grant says the
- * same thing — a name bound to a public key, signed by the root — with no dependency.
- *
- * The Ed25519 itself comes through `#crypto`, which has two realizations: `node:crypto`
- * everywhere, WebCrypto under `workerd`. Everything here is therefore async — WebCrypto
- * has no synchronous form — and a key is parsed ONCE, into a `Signer` or a `Verifier`,
- * never per call. Making the keys and issuing grants happen at a deployment and live in
- * `identity-keys.ts`, on the Node entry.
- */
+/** Who is calling — the proof, not the claim. */
 import { crypto } from '#crypto';
 import type { PublicJwk, Signer, Verifier } from './crypto/port.js';
 import { b64url, unb64url, bytesOf, textOf, unb64 } from './crypto/encoding.js';
@@ -50,13 +19,13 @@ export interface FrondIdentity {
   grant: string;
 }
 
-/** The body's fingerprint. Absence and explicit null are different signed calls. */
-async function digestOf(body: unknown): Promise<string> {
+/** The input's fingerprint. Absence and explicit null are different signed calls. */
+async function digestOf(input: unknown): Promise<string> {
   // The tag is outside the caller value, so no user object can collide with it. JSON's
   // own omission rule still applies inside `value`, matching what crosses the wire.
-  const canonical = body === undefined
+  const canonical = input === undefined
     ? { kind: 'undefined' }
-    : { kind: 'value', value: body };
+    : { kind: 'value', value: input };
   return b64url(await crypto.sha256(bytesOf(JSON.stringify(canonical))));
 }
 
@@ -67,7 +36,7 @@ async function boundTo(call: SignedCall) {
     op: call.op,
     params: call.params ?? {},
     query: call.query ?? {},
-    body: await digestOf(call.body),
+    input: await digestOf(call.input),
   };
 }
 
@@ -85,11 +54,7 @@ async function signJws(header: object, payload: object, signer: Signer): Promise
   return `${signingInput}.${b64url(await signer.sign(bytesOf(signingInput)))}`;
 }
 
-/**
- * The payload, once the signature holds. Throws rather than returning a falsy value:
- * every caller here is deciding whether to admit a call, and an unverified payload
- * must never be reachable by forgetting a check.
- */
+/** The payload, once the signature holds. */
 async function verifyJws(token: string, verifier: Verifier, what: string): Promise<Record<string, unknown>> {
   const parts = token.split('.');
   if (parts.length !== 3) throw new Error(`Malformed ${what}`);
@@ -111,13 +76,7 @@ function headerOf(token: string): Record<string, unknown> {
   return JSON.parse(textOf(unb64url(encodedHeader))) as Record<string, unknown>;
 }
 
-/**
- * Sign one call, whole: who is asking, what is asked, and on whose behalf.
- *
- * The private key is parsed on every call here, which is the convenience form. A process
- * that signs in a request path builds its signer once — `identityFromEnv` does exactly
- * that, and `sign` on the value it returns holds the parsed key.
- */
+/** Sign one call, whole. */
 export async function signEnvelope(identity: FrondIdentity, call: SignedCall): Promise<string> {
   return sealWith(await crypto.signerOf(identity.privateKey), identity.grant, call);
 }
@@ -133,11 +92,7 @@ async function sealWith(signer: Signer, grant: string, call: SignedCall): Promis
   );
 }
 
-/**
- * Establish the caller, or throw. Order matters: the grant is checked against the ROOT
- * first, and only the key it carries verifies the envelope — reading the envelope's own
- * claim of who it is before that would be believing the thing under examination.
- */
+/** Establish the caller, or throw. */
 export async function verifyEnvelope(token: string, rootPublicKey: string, presented: SignedCall): Promise<VerifiedCall> {
   return openWith(await crypto.verifierOf(rootPublicKey), token, presented);
 }
@@ -173,13 +128,7 @@ async function openWith(root: Verifier, token: string, presented: SignedCall): P
 
 /** The two halves a boot needs, and the environment they come from. */
 export interface CallIdentity {
-  /**
-   * Signs an outgoing call, whole. Absent when this process holds no key — it only answers.
-   *
-   * A promise because WebCrypto has no synchronous form. On Node the work stays
-   * synchronous inside and only the answer is wrapped: measured at 14.28 µs awaited
-   * against 14.30 µs called directly, while WebCrypto on the same curve costs 22.72.
-   */
+  /** Signs an outgoing call, whole. */
   sign?: (call: SignedCall) => Promise<string>;
   /** Establishes an incoming caller, against the call that actually arrived. */
   verify?: (identity: string, presented: SignedCall) => Promise<VerifiedCall>;
@@ -187,29 +136,12 @@ export interface CallIdentity {
   requireIdentity: boolean;
 }
 
-/**
- * A PEM, however the deployment chose to carry it.
- *
- * A PEM is multi-line and an environment variable that spans lines survives poorly —
- * docker-compose, systemd and CI secret stores each mangle it differently — so
- * `fougere keys` prints base64. Both forms are read here rather than one being decreed:
- * a human pasting a real PEM is not making a mistake.
- */
+/** A PEM, however the deployment chose to carry it. */
 function pemOf(value: string): string {
   return value.trimStart().startsWith('-----') ? value : textOf(unb64(value));
 }
 
-/**
- * What the deployment injected, read once at boot.
- *
- * Three variables, no config key: a private key never belongs in a committed file, and
- * `fougere keys` prints exactly these. A process may hold either half or both — a frond
- * that only answers has no key, one that only calls trusts no root, one in the middle
- * does both.
- *
- * Trusting a root IS asking to refuse: there is no separate flag, because a deployment
- * that names an authority and then accepts unsigned calls has said two things at once.
- */
+/** What the deployment injected, read once at boot. */
 export async function identityFromEnv(env: Record<string, string | undefined> = envOfProcess()): Promise<CallIdentity> {
   const root = env.FOUGERE_ROOT_KEY ? pemOf(env.FOUGERE_ROOT_KEY) : undefined;
   const privateKey = env.FOUGERE_KEY ? pemOf(env.FOUGERE_KEY) : undefined;

package/src/imports.ts

@@ -1,27 +1,4 @@
-/**
- * A frond reaching into another one by FILE PATH.
- *
- * `verify()` next door answers the same question — does this app survive a split? — from
- * the MODEL: what a constructor asks for, what a parameter is typed. This one can only be
- * answered from the source text, so it reads files and lives apart rather than making
- * `verify` lose the sentence that says it reads none.
- *
- * ```ts
- * import User from '../../user/entities/User.js';   // these two folders are neighbours
- * import User from '@fronds/user/entities/User';    // I depend on the frond named user
- * ```
- *
- * Both resolve today, and that is exactly the trap: a frond declared in `remotes:` is
- * still scanned, its code is still on this disk, so the relative form keeps working right
- * up to the day the folder is not there — an extraction into its own repository, an image
- * that copies one frond. Then it fails at build time, with a message about a file path
- * that says nothing about the model.
- *
- * So a relative path across a boundary is not a bug. It is a **colocation constraint that
- * nothing declares**: real, load-bearing, and invisible to the scan, to the identity card
- * and to `remotes:`. The named form states the same dependency in terms the model can
- * read — and it is the form `fougere sync` writes, so it survives the move.
- */
+/** A frond reaching into another one by FILE PATH. */
 import type ts from '@typescript/typescript6';
 import { readdir, readFile } from 'node:fs/promises';
 import { join, resolve, dirname, relative, isAbsolute } from 'node:path';
@@ -71,13 +48,7 @@ async function sourcesUnder(dir: string): Promise<string[]> {
   return out;
 }
 
-/**
- * Every relative import that resolves outside its own frond.
- *
- * `preProcessFile` rather than a regex or a full parse: it is TypeScript's own scanner for
- * exactly this question, so `// import x from '../../other'` in a comment is not a finding
- * and a specifier split across lines still is.
- */
+/** Every relative import that resolves outside its own frond. */
 export async function crossFrondImports(
   fronds: readonly Pick<FrondDescriptor, 'name' | 'source'>[],
 ): Promise<CrossFrondImport[]> {