@fougere/core 0.9.2-alpha.0 → 0.10.0-alpha.0

package/src/boot/runner.ts

@@ -1,6 +1,6 @@
 /** A Transport built from an app — the two ways a call enters this process. */
-import type { App } from './types.js';
-import type { Transport } from '../wire/call.js';
+import type { App } from './App.js';
+import type { Transport } from '../wire/Transport.js';
 import { createTransportEntry } from '../entry/transport.js';
 
 /** Build the local runner — the reference realization of Transport. */

package/src/boot/seed.ts

@@ -1,8 +1,10 @@
 import { Role } from '@fougere/schema';
-import { facadeKeyOf } from '../wire/call.js';
-import type { FrondDescriptor, SeedEntry, SeedFactory } from '../descriptor/frond.js';
-import type { App } from './types.js';
-import type { Extension } from './AppLifecycle.js';
+import { facadeKeyOf } from '../wire/Facade.js';
+import type { FrondDescriptor } from '../descriptor/FrondDescriptor.js';
+import type { SeedEntry } from '../descriptor/SeedEntry.js';
+import type { SeedFactory } from '../descriptor/SeedFactory.js';
+import type { App } from './App.js';
+import type { Extension } from './Extension.js';
 
 /** What the ordering satisfied, and what no order can. */
 export interface SeedOrder {
@@ -56,7 +58,7 @@ export function orderSeeds(fronds: FrondDescriptor[]): SeedOrder {
 }
 
 /** Where a seed writes, and what it may skip — resolved per entity. */
-interface SeedDoor {
+interface SeedFacade {
   list(): Promise<unknown[]>;
   write(item: unknown): Promise<unknown>;
 }
@@ -75,13 +77,13 @@ export async function runSeeds(
     const resolve = <T>(name: string) => app.resolve<T>(name + 'Handler');
     const data = typeof seed.data === 'function' ? await (seed.data as SeedFactory)(resolve) : seed.data;
 
-    const door = doorFor(app, seed.entityName);
-    if (!door) {
+    const facade = facadeFor(app, seed.entityName);
+    if (!facade) {
       report(`  ${seed.entityName}: no handler façade nor storage — skipping seed`);
       continue;
     }
 
-    const existing = await door.list();
+    const existing = await facade.list();
     if (existing.length > 0) {
       report(`  ${seed.entityName}: skipped (${existing.length} exist)`);
       continue;
@@ -91,7 +93,7 @@ export async function runSeeds(
     // key is exactly what a seed gets wrong.
     for (const item of data) {
       try {
-        await door.write(item);
+        await facade.write(item);
       } catch (cause) {
         throw new Error(
           `Seed '${seed.entityName}' failed on ${JSON.stringify(item)}: ${(cause as Error)?.message ?? cause}`,
@@ -104,7 +106,7 @@ export async function runSeeds(
 }
 
 /** A seed is not a client. */
-function doorFor(app: App, entityName: string): SeedDoor | undefined {
+function facadeFor(app: App, entityName: string): SeedFacade | undefined {
   let handler: Record<string, Function> | undefined;
   try { handler = app.resolve<Record<string, Function>>(facadeKeyOf(entityName)); } catch {}
 

package/src/boot/statement-drift.ts

@@ -1,8 +1,9 @@
 /** Where a STATED contract and the signature it is about have stopped agreeing. */
-import type { FrondDescriptor, HandlerEntry } from '../descriptor/frond.js';
-import type { ScanDiagnostic } from '../scan.js';
+import type { FrondDescriptor } from '../descriptor/FrondDescriptor.js';
+import type { HandlerEntry } from '../descriptor/HandlerEntry.js';
+import type { Diagnostic } from '../diagnostic.js';
 import type { BindingPlan } from '../wire/binding.js';
-import type { Signature } from '../wire/signature.js';
+import type { Signature } from '../wire/Signature.js';
 
 /** The parameters a binding plan names, against the ones the method declares. */
 function namesDisagreeing(plan: BindingPlan, signature: Signature): string[] {
@@ -12,8 +13,8 @@ function namesDisagreeing(plan: BindingPlan, signature: Signature): string[] {
 }
 
 /** What a frond's stated contracts no longer match. */
-export function statementDrift(frond: FrondDescriptor, handler: HandlerEntry): ScanDiagnostic[] {
-  const found: ScanDiagnostic[] = [];
+export function statementDrift(frond: FrondDescriptor, handler: HandlerEntry): Diagnostic[] {
+  const found: Diagnostic[] = [];
 
   for (const [name, override] of Object.entries(frond.operationsOverrides ?? {})) {
     if (!override.binding) continue;

package/src/boot/together.ts

@@ -6,11 +6,13 @@
 import { ambient } from '#ambient';
 import { upperFirst, lowerFirst, type SchemaView } from '@fougere/schema';
 import type { Container } from '@fougere/container';
-import { membersOfTogetherKey, storageKeyOf, entityOfStorageKey, type Storage, type StorageFactory } from '../storage/port.js';
-import type { Logger } from '../builtin/logger.js';
-import type { ProviderEntry } from '../descriptor/frond.js';
+import { entityOfStorageKey, membersOfTogetherKey, storageKeyOf, type Storage } from '../storage/Storage.js';
+import { type StorageFactory } from '../storage/StorageFactory.js';
+import type { Logger } from '../builtin/Logger.js';
+import type { ProviderEntry } from '../descriptor/ProviderEntry.js';
 import { StorageGuard } from '../dispatch/StorageGuard.js';
 import { recording, unwind, type Undo } from './frame.js';
+import type { Diagnostic } from '../diagnostic.js';
 
 /** Everything the boot knows that a frame needs, gathered once for every frond. */
 export interface FrameWorld {
@@ -33,61 +35,87 @@ interface Members {
   providers: ProviderEntry[];
 }
 
-/** Each declared name, resolved to what it designates. */
-function resolve(names: { entities: string[]; providers: string[] }, declared: readonly ProviderEntry[], world: FrameWorld): Members {
-  const entities = names.entities.map((member) => {
+/** Each declared name, resolved to what it designates — or nothing, and why. */
+function resolve(
+  names: { entities: string[]; providers: string[] },
+  declared: readonly ProviderEntry[],
+  world: FrameWorld,
+  asked: Asked,
+  refused: Diagnostic[],
+): Members | undefined {
+  const before = refused.length;
+
+  const entities = names.entities.flatMap((member) => {
     const name = lowerFirst(member);
     const schema = world.entityByName.get(name);
     if (!schema) {
-      throw new Error(
-        `Together<[…${member}…]>: no entity named '${member}' is scanned in this app. ` +
-        `The first list names entities; a class of this frond goes in the second.`,
-      );
+      refused.push({
+        ...asked,
+        code: 'together-entity-unknown',
+        message: `Together<[…${member}…]>: no entity named '${member}' is scanned in this app. `
+          + 'The first list names entities; a class of this frond goes in the second.',
+      });
+
+      return [];
     }
-    return { name, schema };
+
+    return [{ name, schema }];
   });
 
-  const providers = names.providers.map((member) => {
+  const providers = names.providers.flatMap((member) => {
     const entry = declared.find((provider) => provider.ctor.name === member);
     if (!entry) {
-      throw new Error(
-        `Together<[…], [… ${member} …]>: this frond declares no class named '${member}'. ` +
-        `The second list names providers to rebuild inside the frame — a service, a mirror, ` +
-        `a repository — so that what they write is covered by the unwind.`,
-      );
+      refused.push({
+        ...asked,
+        code: 'together-provider-unknown',
+        message: `Together<[…], [… ${member} …]>: this frond declares no class named '${member}'. `
+          + 'The second list names providers to rebuild inside the frame — a service, a mirror, '
+          + 'a repository — so that what they write is covered by the unwind.',
+      });
+
+      return [];
     }
-    return entry;
+
+    return [entry];
   });
 
-  return { entities, providers };
+  return refused.length === before ? { entities, providers } : undefined;
 }
 
+/** Who asked for the frame, and where they wrote it — the same three fields every refusal here carries. */
+type Asked = { severity: 'blocking'; filePath: string; subject: string };
+
 /** A member that cannot write here at all — its frond is hosted elsewhere. */
-function refuseRemote(members: Members, world: FrameWorld, key: string): void {
+function remoteMembers(members: Members, world: FrameWorld, asked: Asked, refused: Diagnostic[]): void {
   for (const member of members.entities) {
     const frond = world.frondOf.get(member.name);
     if (frond && !world.hostedHere(frond)) {
-      throw new Error(
-        `Together<[…]> (${key}): '${member.name}' belongs to frond '${frond}', which this ` +
-        `process declares in remotes: — it registers no storage here, so its writes cannot be ` +
-        `part of a frame. Host the frond here, or split the work and join the halves with a fact.`,
-      );
+      refused.push({
+        ...asked,
+        code: 'together-member-remote',
+        message: `'${member.name}' belongs to frond '${frond}', which this process declares in `
+          + 'remotes: — it registers no storage here, so its writes cannot be part of a frame. '
+          + 'Host the frond here, or split the work and join the halves with a fact.',
+      });
     }
   }
 }
 
 /** A provider member writing an entity the frame does not name. */
-function refuseUncoveredWrites(members: Members, key: string, world: FrameWorld): void {
+function uncoveredWrites(members: Members, world: FrameWorld, asked: Asked, refused: Diagnostic[]): void {
   const covered = new Set(members.entities.map((member) => member.name));
   for (const provider of members.providers) {
     for (const dep of provider.deps) {
       const entity = entityOfStorageKey(dep, (name) => world.entityByName.has(name));
       if (!entity || covered.has(entity)) continue;
-      throw new Error(
-        `Together<[…]> (${key}): ${provider.ctor.name} writes ${entity}, which is not in the ` +
-        `frame's entity list — its writes would escape the unwind. Add it: ` +
-        `Together<[…, ${upperFirst(entity)}], [… ${provider.ctor.name} …]>.`,
-      );
+      refused.push({
+        ...asked,
+        filePath: provider.filePath,
+        code: 'together-write-uncovered',
+        message: `${provider.ctor.name} writes ${entity}, which is not in the frame's entity list `
+          + `— its writes would escape the unwind. Add it: `
+          + `Together<[…, ${upperFirst(entity)}], [… ${provider.ctor.name} …]>.`,
+      });
     }
   }
 }
@@ -121,22 +149,34 @@ async function inScope<R>(
 /** Register one frame per key a handler or provider of this frond asked for. */
 export function registerFrames(
   scope: Container,
-  keys: Iterable<string>,
+  wanted: Iterable<{ key: string; filePath: string }>,
   providers: readonly ProviderEntry[],
   world: FrameWorld,
+  refused: Diagnostic[],
 ): void {
   let registered = 0;
-  for (const key of new Set(keys)) {
+  const seen = new Set<string>();
+  for (const { key, filePath } of wanted) {
+    if (seen.has(key)) continue;
+    seen.add(key);
     const names = membersOfTogetherKey(key);
     if (!names) continue;
     registered += 1;
+    const asked = { severity: 'blocking', filePath, subject: key } as const;
     if (!world.storageFactory) {
-      throw new Error(`Together<[${names.entities.join(', ')}]> needs storage, and this boot declares none.`);
+      refused.push({
+        ...asked,
+        code: 'together-needs-storage',
+        message: `Together<[${names.entities.join(', ')}]> needs storage, and this boot declares none.`,
+      });
+      continue;
     }
 
-    const members = resolve(names, providers, world);
-    refuseRemote(members, world, key);
-    refuseUncoveredWrites(members, key, world);
+    const members = resolve(names, providers, world, asked, refused);
+    // Nothing left to build a frame out of, and the refusals above already say what is missing.
+    if (!members) continue;
+    remoteMembers(members, world, asked, refused);
+    uncoveredWrites(members, world, asked, refused);
 
     const sources = new Set(members.entities.map((member) => world.sourceOf?.(member.name) ?? 'db'));
     const validator = (storage: Storage, name: string, schema: SchemaView) =>

package/src/builtin/Carry.ts

@@ -0,0 +1,49 @@
+import type { LogRecord } from './LogRecord.js';
+
+/**
+ * Where one boot's lines wait, and where they go once they can.
+ *
+ * PER BOOT and never per process: two apps in one process each have their own
+ * destinations, and a slot shared between them sent the second app's lines to the first
+ * app's facade — measured on `demos/observability`, where only the first of three printed.
+ *
+ * A boot writes most of what a process ever logs, and it writes it before any emission is
+ * registered, so the lines that say what an app is made of are the ones a destination
+ * would miss. Bounded: a boot that never finishes must not grow, and what is dropped is
+ * the OLDEST since the lines explaining a refusal are the last.
+ */
+export class Carry {
+  private held: LogRecord[] = [];
+  private take?: (line: LogRecord) => void;
+
+  static readonly MAX = 500;
+
+  /** Take it now, or keep it for whoever arrives. */
+  push(record: LogRecord): void {
+    if (this.take) {
+      try {
+        this.take(record);
+      } catch { /* announcing never breaks logging, for the same reason a sink does not */ }
+      return;
+    }
+    this.held.push(record);
+    if (this.held.length > Carry.MAX) this.held.shift();
+  }
+
+  /** Hand what is held over, and everything after it. */
+  to(take: (line: LogRecord) => void): () => void {
+    this.take = take;
+    for (const line of this.held.splice(0)) take(line);
+
+    return () => { this.take = undefined; };
+  }
+
+  /**
+   * Forget what is still held — a boot that refused, or an app that declares no
+   * destination. Nothing is printed: the console had every one of these lines when it was
+   * written, and the hold exists only to hand them on later.
+   */
+  forget(): void {
+    this.held.length = 0;
+  }
+}

package/src/builtin/LogLevel.ts

@@ -0,0 +1 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';

package/src/builtin/LogRecord.ts

@@ -0,0 +1,12 @@
+import type { LogLevel } from './LogLevel.js';
+
+/** One line, before it was formatted for a terminal. */
+export interface LogRecord {
+  level: Exclude<LogLevel, 'silent'>;
+  /** The logger's own name — 'boot:app', 'boot:app:catalog'. */
+  name: string;
+  message: string;
+  args: unknown[];
+  /** Epoch milliseconds. */
+  at: number;
+}

package/src/builtin/LogSink.ts

@@ -0,0 +1,4 @@
+import type { LogRecord } from './LogRecord.js';
+
+/** Where a line goes once it is written — `@fougere/log` ships one, `observability` another. */
+export type LogSink = (record: LogRecord) => void;

package/src/builtin/{logger.ts → Logger.ts}

@@ -1,68 +1,8 @@
-/** Fougere Logger — structured, colored, multi-runtime. */
-
-export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
-
-/** One line, before it was formatted for a terminal. */
-export interface LogRecord {
-  level: Exclude<LogLevel, 'silent'>;
-  /** The logger's own name — 'boot:app', 'boot:app:catalog'. */
-  name: string;
-  message: string;
-  args: unknown[];
-  /** Epoch milliseconds. */
-  at: number;
-}
-
-/** Where a line goes once it is written — `@fougere/log` ships one, `observability` another. */
-export type LogSink = (record: LogRecord) => void;
-
-/**
- * Where one boot's lines wait, and where they go once they can.
- *
- * PER BOOT and never per process: two apps in one process each have their own
- * destinations, and a slot shared between them sent the second app's lines to the first
- * app's door — measured on `demos/observability`, where only the first of three printed.
- *
- * A boot writes most of what a process ever logs, and it writes it before any emission is
- * registered, so the lines that say what an app is made of are the ones a destination
- * would miss. Bounded: a boot that never finishes must not grow, and what is dropped is
- * the OLDEST since the lines explaining a refusal are the last.
- */
-export class Carry {
-  private held: LogRecord[] = [];
-  private take?: (line: LogRecord) => void;
-
-  static readonly MAX = 500;
-
-  /** Take it now, or keep it for whoever arrives. */
-  push(record: LogRecord): void {
-    if (this.take) {
-      try {
-        this.take(record);
-      } catch { /* announcing never breaks logging, for the same reason a sink does not */ }
-      return;
-    }
-    this.held.push(record);
-    if (this.held.length > Carry.MAX) this.held.shift();
-  }
-
-  /** Hand what is held over, and everything after it. */
-  to(take: (line: LogRecord) => void): () => void {
-    this.take = take;
-    for (const line of this.held.splice(0)) take(line);
-
-    return () => { this.take = undefined; };
-  }
-
-  /**
-   * Forget what is still held — a boot that refused, or an app that declares no
-   * destination. Nothing is printed: the console had every one of these lines when it was
-   * written, and the hold exists only to hand them on later.
-   */
-  forget(): void {
-    this.held.length = 0;
-  }
-}
+import type { LogLevel } from './LogLevel.js';
+import type { LogRecord } from './LogRecord.js';
+import type { Carry } from './Carry.js';
+import type { LoggerOptions } from './LoggerOptions.js';
+import type { Rendered } from './Rendered.js';
 
 const LEVELS: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
 
@@ -125,19 +65,6 @@ function stamp(at: number | Date): string {
   return `${h}:${m}:${s}.${ms}`;
 }
 
-export interface LoggerOptions {
-  /** Logger name / prefix. */
-  name?: string;
-  /**
-   * Where its lines go — one boot's, so two apps in a process do not share a door. A
-   * logger without one writes to the console and nowhere else, which is what the boot's
-   * first lines do and what an app declaring no destination does forever.
-   */
-  carry?: Carry;
-  /** Force color on/off. Auto-detected by default. */
-  color?: boolean;
-}
-
 export class Logger {
   private name: string;
   private color: boolean;
@@ -176,26 +103,6 @@ export class Logger {
   }
 }
 
-/**
- * One line, ready for a terminal — the console arguments and which method takes them.
- *
- * Here rather than inside the class because the boot is not the only writer: a destination
- * that prints (`@fougere/log`) hands its own record to the same formatting, so the two
- * outputs cannot drift.
- *
- * One console method per level: `debug` and `info` both went to `console.log`, so nothing
- * downstream — a terminal filter, a collector — could tell them apart.
- */
-export interface Rendered {
-  level: Exclude<LogLevel, 'silent'>;
-  name: string;
-  message: string;
-  /** Absent on most lines: a message usually carries its own detail. */
-  args?: unknown[] | null;
-  /** Epoch milliseconds from a logger, a `Date` from an entity that stamped it. */
-  at: number | Date;
-}
-
 export function formatted(
   record: Rendered,
   color = supportsColor(),

package/src/builtin/LoggerOptions.ts

@@ -0,0 +1,14 @@
+import type { Carry } from './Carry.js';
+
+export interface LoggerOptions {
+  /** Logger name / prefix. */
+  name?: string;
+  /**
+   * Where its lines go — one boot's, so two apps in a process do not share a facade. A
+   * logger without one writes to the console and nowhere else, which is what the boot's
+   * first lines do and what an app declaring no destination does forever.
+   */
+  carry?: Carry;
+  /** Force color on/off. Auto-detected by default. */
+  color?: boolean;
+}

package/src/builtin/Rendered.ts

@@ -0,0 +1,21 @@
+import type { LogLevel } from './LogLevel.js';
+
+/**
+ * One line, ready for a terminal — the console arguments and which method takes them.
+ *
+ * Here rather than inside the class because the boot is not the only writer: a destination
+ * that prints (`@fougere/log`) hands its own record to the same formatting, so the two
+ * outputs cannot drift.
+ *
+ * One console method per level: `debug` and `info` both went to `console.log`, so nothing
+ * downstream — a terminal filter, a collector — could tell them apart.
+ */
+export interface Rendered {
+  level: Exclude<LogLevel, 'silent'>;
+  name: string;
+  message: string;
+  /** Absent on most lines: a message usually carries its own detail. */
+  args?: unknown[] | null;
+  /** Epoch milliseconds from a logger, a `Date` from an entity that stamped it. */
+  at: number | Date;
+}

package/src/contract.ts

@@ -3,35 +3,57 @@
  * runtime: the error vocabulary, the invocation shape, the call value, the naming convention.
  */
 import { lowerFirst } from '@fougere/schema';
-import { Invocation, type InvocationContext } from './wire/Invocation.js';
-import type { FrondCall } from './wire/call.js';
+import { Invocation } from './wire/Invocation.js';
+import { type InvocationContext } from './wire/InvocationContext.js';
+import type { FrondCall } from './wire/FrondCall.js';
 
-export { FougereError, ErrorCode, validationErrorsOf } from './wire/errors.js';
+export { ErrorCode } from './wire/ErrorCode.js';
+export { FougereError, validationErrorsOf } from './wire/FougereError.js';
 // What a read may ask about one field. Here rather than on the main entry because an
 // adapter reads it to compile a query, and an adapter carries no boot.
-export { comparisonOf, comparisonsIn } from './storage/criterion.js';
-export type { Comparison } from './storage/criterion.js';
+export { comparisonOf, comparisonsIn } from './storage/Comparison.js';
+export type { Comparison } from './storage/Comparison.js';
 // A receiver turns a refusal into what may cross a process boundary, and it is not
 // core's boot — reaching it through the main entry dragged the scanner into a bundle.
 export { toPublicError } from './wire/http-error.js';
 export { Invocation } from './wire/Invocation.js';
-export type { InvocationContext } from './wire/Invocation.js';
-export { Call } from './wire/call.js';
+export type { InvocationContext } from './wire/InvocationContext.js';
+export { Call } from './wire/Call.js';
 export { RouteAddress } from './wire/RouteAddress.js';
-export type { FrondCall, Transport, SignedCall } from './wire/call.js';
-export { MAX_BODY_BYTES } from './wire/call.js';
+export type { FrondCall } from './wire/FrondCall.js';
+export type { SignedCall } from './wire/SignedCall.js';
+export type { Transport } from './wire/Transport.js';
+export { MAX_BODY_BYTES } from './wire/SignedCall.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 './wire/CallLog.js';
+export { RPC_ENTITY } from './wire/RpcAnswer.js';
+export type { CallPage } from './wire/CallPage.js';
+export type { CallRecord } from './wire/CallRecord.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. */
-export type { IdentityCard, CardOp, TopologyReport, FrondPlacement, Edge } from './wire/call.js';
-export { assertIdentityCard } from './wire/call.js';
+export { refusalsOf, type Refusable } from './wire/refusals.js';
+export type { Addresses } from './wire/Addresses.js';
+export type { Answer } from './wire/Answer.js';
+export type { AnyHandler } from './wire/AnyHandler.js';
+export type { FacadeName } from './wire/FacadeName.js';
+export type { FougereHandlers } from './wire/FougereHandlers.js';
+export type { FougereOperations } from './wire/FougereOperations.js';
+export type { HandlerOf } from './wire/HandlerOf.js';
+export type { Refused } from './wire/Refused.js';
+export type { Rows } from './wire/Rows.js';
+export type { CardOp } from './wire/card/CardOp.js';
+export type { IdentityCard } from './wire/card/IdentityCard.js';
+export type { DeclaredEdge } from './wire/topology/DeclaredEdge.js';
+export type { DeclaredFrond } from './wire/topology/DeclaredFrond.js';
+export type { DeclaredTopology } from './wire/topology/DeclaredTopology.js';
+export type { Edge } from './wire/topology/Edge.js';
+export type { FrondPlacement } from './wire/topology/FrondPlacement.js';
+export type { TopologyReport } from './wire/topology/TopologyReport.js';
+export { assertIdentityCard } from './wire/card/IdentityCard.js';
 
 /** The key a class name is filed under — 'Post' → 'post'. */
 export { lowerFirst } from '@fougere/schema';

package/src/crypto/CryptoPort.ts

@@ -0,0 +1,12 @@
+import type { Signer } from './Signer.js';
+import type { Verifier } from './Verifier.js';
+import type { PublicJwk } from './PublicJwk.js';
+
+export interface CryptoPort {
+  /** SHA-256. What binds an input to an envelope without carrying the input. */
+  sha256(data: Uint8Array): Promise<Uint8Array>;
+  /** From a PKCS#8 PEM — what `fougere keys` writes. */
+  signerOf(privateKeyPem: string): Promise<Signer>;
+  /** From an SPKI PEM (the root's) or a JWK (the one a grant embeds). */
+  verifierOf(key: string | PublicJwk): Promise<Verifier>;
+}

package/src/crypto/PublicJwk.ts

@@ -0,0 +1,7 @@
+/** A public key as a grant carries it — `{ kty: 'OKP', crv: 'Ed25519', x }`. */
+export interface PublicJwk {
+  kty: string;
+  crv?: string;
+  x?: string;
+  [key: string]: unknown;
+}

package/src/crypto/Signer.ts

@@ -0,0 +1,4 @@
+/** A parsed private key. */
+export interface Signer {
+  sign(data: Uint8Array): Promise<Uint8Array>;
+}

package/src/crypto/Verifier.ts

@@ -0,0 +1,5 @@
+/** A parsed public key. */
+export interface Verifier {
+  /** False, never a throw: a bad signature is an answer, not a failure. */
+  verify(data: Uint8Array, signature: Uint8Array): Promise<boolean>;
+}

package/src/crypto/node.ts

@@ -1,6 +1,9 @@
 /** Ed25519 through `node:crypto` — the default realization, and the fast one. */
 import { createHash, createPrivateKey, createPublicKey, sign, verify } from 'node:crypto';
-import type { CryptoPort, PublicJwk, Signer, Verifier } from './port.js';
+import type { CryptoPort } from './CryptoPort.js';
+import type { PublicJwk } from './PublicJwk.js';
+import type { Signer } from './Signer.js';
+import type { Verifier } from './Verifier.js';
 
 export const crypto: CryptoPort = {
   async sha256(data) {

package/src/crypto/webcrypto.ts

@@ -1,6 +1,9 @@
 /** Ed25519 through WebCrypto — what a runtime with no `node:` builtin has. */
 import { derOf } from './encoding.js';
-import type { CryptoPort, PublicJwk, Signer, Verifier } from './port.js';
+import type { CryptoPort } from './CryptoPort.js';
+import type { PublicJwk } from './PublicJwk.js';
+import type { Signer } from './Signer.js';
+import type { Verifier } from './Verifier.js';
 
 interface WebSubtle {
   digest(algorithm: string, data: Uint8Array): Promise<ArrayBuffer>;

package/src/define.ts

@@ -1,4 +1,4 @@
-import type { FougereConfig } from './config-loader.js';
+import type { FougereConfig } from './FougereConfig.js';
 
 /**
  * Identity helper for fougere.config.ts — preserves literal types for autocomplete while

package/src/descriptor/CollectorEntry.ts

@@ -0,0 +1,11 @@
+/** A discovered collector (resolves handler input params from invocation context). */
+export interface CollectorEntry {
+  /** Registration key of the TYPE this collector resolves — 'user', 'ability'. */
+  typeName: string;
+  /** The collector class. */
+  ctor: new (...args: never[]) => unknown;
+  /** Constructor dependency type names (from AST scan). */
+  deps: string[];
+  /** Absolute file path (for debugging). */
+  filePath: string;
+}