@fougere/core 0.5.0-alpha.1 → 0.7.0-alpha.0

package/src/config-loader.ts

@@ -1,7 +1,7 @@
 import { resolve } from 'node:path';
 import { existsSync } from 'node:fs';
 import type { AuthConfig } from './boot/auth.js';
-import type { LogLevel } from './builtins/logger.js';
+import type { LogLevel } from './builtin/logger.js';
 import type { ConventionsInput } from './scan/conventions.js';
 import { getModuleLoader } from './loader.js';
 
@@ -10,68 +10,22 @@ import { getModuleLoader } from './loader.js';
 export interface FougereConfig {
   /** Database configuration — the DEFAULT source, the one an entity lands in unnamed. */
   db?: 'sqlite' | { dialect: 'sqlite'; path?: string } | false;
-  /**
-   * The other places rows live — a name, an engine, and the entities it holds.
-   *
-   * A fact about the APP, stated beside `remotes:` because it is the same kind of
-   * statement: `remotes:` says where a CALL goes, this says where a ROW is. Neither
-   * belongs on the entity, which describes itself and not its deployment.
-   *
-   * Only the exception is declared: everything unnamed stays in `db`. Membership is
-   * per ENTITY rather than per frond — two fronds may share a database, and one frond
-   * may hold entities in two — so the entity is the truth and a frond-wide shorthand
-   * waits for a case that needs it.
-   *
-   * A `ref()` across two sources gets no foreign key: two databases share no
-   * constraint. The DDL stops pretending rather than the `ref` being refused.
-   */
+  /** The other places rows live — a name, an engine, and the entities it holds. */
   sources?: Record<string, { dialect?: 'sqlite'; path?: string; entities: string[] }>;
   /**
-   * The names the scan reads instead of deriving them — the import scope, the fronds
-   * directory, the seven convention directories.
-   *
-   * Only what differs is stated. Read BEFORE the fronds are discovered, which is what
-   * lets it name the prefix they are found under: nothing in this file may import
-   * `@fronds/*`, or the name would be needed to read the file that declares it.
+   * The names the scan reads instead of deriving them — the import scope, the fronds directory,
+   * the seven convention directories.
    */
   conventions?: ConventionsInput;
-  /**
-   * How much every logger says. The one key a running app CONSULTS rather than
-   * consumes, so re-reading this file changes it without rebuilding anything.
-   *
-   * `FOUGERE_LOG_LEVEL` still wins — it is how the CLI speaks, and the precedence is
-   * the usual one (CLI over config file).
-   */
+  /** How much every logger says. */
   logLevel?: LogLevel;
   /** Remote fronds — frondName → base URL. */
   remotes?: Record<string, string>;
-  /**
-   * Which realization answers which port — port class name → implementation class name.
-   *
-   * A fact about the APP, stated beside `remotes:` for the same reason `sources:` is:
-   * `remotes:` says where a CALL goes, `sources:` says where a ROW is, this says who
-   * performs an ACTION. None of the three belongs inside the frond, which describes
-   * itself and not its deployment — a `billing` frond naming Stripe would be the one
-   * thing the framework refuses.
-   *
-   * Only the exception is declared. One class extending a port answers it by
-   * convention and this key stays absent; two make the boot refuse until one is named.
-   */
+  /** Which realization answers which port — port class name → implementation class name. */
   ports?: Record<string, string>;
   /** Auth declaration — picks a provider package and forwards options to it. */
   auth?: AuthConfig;
-  /**
-   * Which protocol adapters this app serves.
-   *
-   * A fact about the APP, declared once beside `db`, `remotes` and `auth` — not a
-   * property of whichever host runs it. Before this existed the same decision was
-   * spelled five different ways: Nuxt mounted REST unconditionally, the Web hosts
-   * served it if you happened to create a route file, and Express if you happened to
-   * call a middleware. One decision, five dialects, no canonical place.
-   *
-   * Absent means not served. The call envelope is not listed here: it is the wire the
-   * client primitives use, not a projection an app chooses to publish.
-   */
+  /** Which protocol adapters this app serves. */
   adapters?: AdapterConfig;
 }
 
@@ -105,13 +59,7 @@ async function loadConfigFrom(dir: string, fresh?: boolean): Promise<FougereConf
   return {};
 }
 
-/**
- * Load the root fougere.config.{ts,js,mjs} from the given directory.
- *
- * `fresh` re-reads a file that may have changed since the last load — what a host
- * calls when it decides to reconsider its config, and the only way `applyConfig` has
- * anything new to apply.
- */
+/** Load the root fougere.config.{ts,js,mjs} from the given directory. */
 export async function loadConfig(root: string, options?: { fresh?: boolean }): Promise<FougereConfig> {
   return loadConfigFrom(root, options?.fresh);
 }
@@ -119,10 +67,9 @@ export async function loadConfig(root: string, options?: { fresh?: boolean }): P
 // ── Merging ──────────────────────────────────────
 
 /**
- * Override a config with another, the invariant of every cascade level:
- * scalar keys replace, but `remotes` (the topology) MERGES — an override adds
- * or redirects a frond without erasing the others. Used for workspace→app and
- * for global→CLI alike.
+ * Override a config with another, the invariant of every cascade level: scalar keys replace, but
+ * `remotes` (the topology) MERGES — an override adds or redirects a frond without erasing the
+ * others.
  */
 function mergeGlobal(base: FougereConfig, override: Partial<FougereConfig>): FougereConfig {
   const merged: FougereConfig = { ...base, ...override };
@@ -132,13 +79,7 @@ function mergeGlobal(base: FougereConfig, override: Partial<FougereConfig>): Fou
   return merged;
 }
 
-/**
- * Load config along the workspace→app frontier. The workspace-root config is
- * the base (canonical topology: `remotes`, shared `db`); the app-root config
- * overrides. Same `root` boundary the fronds already cascade along. When both
- * roots resolve to the same dir (single app, no workspace), this is the plain
- * root config — idempotent, no behavior change.
- */
+/** Load config along the workspace→app frontier. */
 export async function loadCascadedConfig(workspaceRoot: string, appRoot: string): Promise<FougereConfig> {
   const base = await loadConfig(workspaceRoot);
   if (resolve(workspaceRoot) === resolve(appRoot)) return base;

package/src/contract.ts

@@ -1,15 +1,9 @@
 /**
- * Contract surface — what a sender needs to speak to a receiver, and
- * nothing that assumes a runtime: the error vocabulary, the invocation
- * shape, the call value, the naming convention.
- *
- * Browser-safe by design: no node builtin may enter this module's import
- * graph. Published as the `@fougere/core/contract` subpath so client
- * bundles never touch the full index (scanner, config loader). `@fougere/schema`
- * is allowed in — measured, it imports no node builtin either.
+ * Contract surface — what a sender needs to speak to a receiver, and nothing that assumes a
+ * runtime: the error vocabulary, the invocation shape, the call value, the naming convention.
  */
 import { lowerFirst } from '@fougere/schema';
-import { canonicalInvocation, type InvocationContext } from './contract/Invocation.js';
+import { canonicalInvocation, type InvocationContext } from './wire/Invocation.js';
 import type { FrondCall } from './wire/call.js';
 
 export { FougereError, ErrorCode, validationErrorsOf } from './wire/errors.js';
@@ -17,45 +11,29 @@ export { FougereError, ErrorCode, validationErrorsOf } from './wire/errors.js';
 // core's boot — reaching it through the main entry dragged the scanner into a bundle.
 export { toPublicError } from './wire/http-error.js';
 export type { FougereErrorOptions } from './wire/errors.js';
-export { canonicalInvocation, EMPTY_INVOCATION } from './contract/Invocation.js';
-export type { InvocationContext } from './contract/Invocation.js';
-export { Invocation } from './contract/Invocation.js';
-export type { InvocationInput } from './contract/Invocation.js';
-export { Call } from './contract/Call.js';
-export { RouteAddress } from './contract/RouteAddress.js';
-export type { RouteAddressInput } from './contract/RouteAddress.js';
+export { canonicalInvocation, EMPTY_INVOCATION } from './wire/Invocation.js';
+export type { InvocationContext } from './wire/Invocation.js';
+export { Invocation } from './wire/Invocation.js';
+export type { PartialInvocation } from './wire/Invocation.js';
+export { Call } from './wire/call.js';
+export { RouteAddress } from './wire/RouteAddress.js';
+export type { RouteAddressInput } from './wire/RouteAddress.js';
 export type { FrondCall, Transport, SignedCall } from './wire/call.js';
 export { MAX_BODY_BYTES } from './wire/call.js';
 // The reserved entity, VALUE and not type: a consumer that wants to leave it alone — a
 // call log ignoring its own reader — has to be able to name it.
 export { RPC_ENTITY } from './wire/call.js';
-export type { CallPage, CallRecord } from './contract/CallLog.js';
+export type { CallPage, CallRecord } from './wire/CallLog.js';
 // The comparison of two cards, which a consumer runs about a producer — browser-safe on
 // purpose: a panel showing the drift holds only the two cards, never the app.
 export { driftOf, agrees, explain } from './wire/drift.js';
 export type { CardDrift } from './wire/drift.js';
 
-/**
- * What `rpc.discover` answers. It belongs here and not to the runtime: the
- * reserved op travels on the same wire as every other call, so a consumer that
- * only sends — a browser bundle, a frond written elsewhere — needs its shape and
- * nothing else. Type-only, so `call.js` never enters the runtime graph.
- *
- * Stated once, on purpose: two private copies of this interface have already gone
- * stale (the CLI's, then the Rust demo's) the day an op stopped being a bare name.
- */
+/** What `rpc.discover` answers. */
 export type { IdentityCard, CardOp, TopologyReport, FrondPlacement, Edge } from './wire/call.js';
 export { assertIdentityCard } from './wire/call.js';
 
-/**
- * The key a class name is filed under — 'Post' → 'post'. Re-exported rather than
- * respelled: a card writes it and a foreign key derives from it, so the convention
- * belongs to the schema, and a second copy here is a second opinion. It travels
- * through this subpath because a consumer of the wire (a browser bundle) may hold no
- * schema dependency of its own — that audience only. Inside the package it is read from
- * `@fougere/schema` directly: routing four modules through here bought nothing and put
- * this file inside a cycle.
- */
+/** The key a class name is filed under — 'Post' → 'post'. */
 export { lowerFirst } from '@fougere/schema';
 
 /** A call, fully fabricated: the designation and its completed invocation. */
@@ -65,10 +43,8 @@ export interface CallValue {
 }
 
 /**
- * Fabricate the call value — one designation, two spellings:
- * `callValueOf(Post, 'list', { query })` (class + verb) or
- * `callValueOf({ entity, op }, input)` (raw, for dynamic bridges).
- * Missing invocation fields complete to the empty invocation.
+ * Fabricate the call value — one designation, two spellings: `callValueOf(Post, 'list', { query
+ * })` (class + verb) or `callValueOf({ entity, op }, input)` (raw, for dynamic bridges).
  */
 export function callValueOf(
   target: { name: string } | FrondCall,

package/src/crypto/encoding.ts

@@ -1,11 +1,4 @@
-/**
- * What both realizations spell identically — bytes in, bytes out, no platform.
- *
- * `Buffer` did all of this and does not exist on a Worker; `atob`/`btoa` exist on both.
- * Nothing here is a policy decision, which is why it sits beside the port rather than
- * inside either half: two copies of a base64url would be two chances to disagree on the
- * padding, and the disagreement would show up as a bad signature.
- */
+/** What both realizations spell identically — bytes in, bytes out, no platform. */
 
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
@@ -45,13 +38,7 @@ export const unb64 = (input: string): Uint8Array => {
   return bytes;
 };
 
-/**
- * The DER a PEM wraps. WebCrypto imports DER and knows nothing about the armour.
- *
- * The label is not checked: a caller asking for a private key and handed a public one
- * fails at `importKey` with a message about the key, which is the truer error than one
- * about a header line.
- */
+/** The DER a PEM wraps. */
 export function derOf(pem: string): Uint8Array {
   const body = pem.replace(/-----(BEGIN|END)[^-]+-----/g, '').replace(/\s+/g, '');
   if (body.length === 0) throw new Error('Not a PEM: no base64 body between the armour');

package/src/crypto/node.ts

@@ -1,10 +1,4 @@
-/**
- * Ed25519 through `node:crypto` — the default realization, and the fast one.
- *
- * `sign`/`verify` are synchronous here and stay synchronous: the promise is put around
- * the answer, never around the work. That is the whole reason this file exists rather
- * than everyone sharing the WebCrypto half.
- */
+/** 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';
 

package/src/crypto/port.ts

@@ -1,20 +1,4 @@
-/**
- * The two Ed25519 gestures a signed call needs, and the one hash that binds it.
- *
- * Node signs 59% faster than WebCrypto on the same curve (measured 2026-08-23: 14.30 µs
- * against 22.72 µs per signature, 34.42 against 41.81 to verify), so this is a PORT with
- * two realizations and not one implementation at the lowest common denominator. `#crypto`
- * resolves to `crypto/node.ts` everywhere except under the `workerd` condition — the
- * bundler picks at build time, and neither half ever appears in the other's output.
- *
- * The shape is async because WebCrypto is. On Node that costs one microtask, which the
- * same measurement puts inside the noise of the signature itself (14.30 sync against
- * 14.28 awaited) — awaiting is free, converting is not.
- *
- * A KEY IS PARSED ONCE. `crypto.subtle.importKey` is async and per-key, so an interface
- * shaped `sign(key, data)` would import on every call; `signerOf(pem)` hands back
- * something that holds the parsed key, and a boot builds it once.
- */
+/** The two Ed25519 gestures a signed call needs, and the one hash that binds it. */
 
 /** A parsed private key. */
 export interface Signer {
@@ -36,7 +20,7 @@ export interface PublicJwk {
 }
 
 export interface CryptoPort {
-  /** SHA-256. What binds a body to an envelope without carrying the body. */
+  /** 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>;

package/src/crypto/webcrypto.ts

@@ -1,15 +1,4 @@
-/**
- * Ed25519 through WebCrypto — what a runtime with no `node:` builtin has.
- *
- * Verified in real workerd with no compatibility flag (2026-08-23): sign, verify, a JWK
- * import, an SPKI import and SHA-256 all answer. `Ed25519` is the algorithm name; the
- * older `NODE-ED25519` spelling is not used, and a runtime that only knows that one will
- * refuse at `importKey` rather than silently signing with something else.
- *
- * The four gestures are declared here rather than pulled from `lib.dom`: this package
- * compiles with `lib: ["ESNext"]` and naming DOM would make every consumer carry a
- * browser's globals to read a server type. What the file needs IS the declaration.
- */
+/** 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';
 

package/src/{scan/declare.ts → declare.ts}

@@ -1,38 +1,16 @@
-/**
- * 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.
- */
+/** A frond stated by its author, for an app that will not scan. */
 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';
+} from './descriptor/frond.js';
+import { DEFAULT_CONVENTIONS } from './scan/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.
- */
+/** What a subject needs beyond its class, when its constructor names a frame or a port. */
 export interface DeclaredSubject {
   ctor: Ctor;
   deps?: string[];
@@ -41,9 +19,9 @@ export interface DeclaredSubject {
 /** 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.
+   * 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;
 }
@@ -55,9 +33,8 @@ 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.
+ * `__entity`, which is the only place it survives: nothing in the FORM of `PostPresenter` says
+ * `Post`.
  */
 function subjectOf(ctor: Ctor, kind: string): { name: string } {
   const subject = (ctor as unknown as { __entity?: { name: string } }).__entity;
@@ -93,15 +70,7 @@ export interface FrondDeclaration {
   scope?: string;
 }
 
-/**
- * State a frond without reading a disk.
- *
- * ```ts
- * createApp({
- *   scan: { fronds: Fronds.scanned([frond('blog', { entities: [Post], handlers: [PostHandler] })]), diagnostics: [] },
- * })
- * ```
- */
+/** State a frond without reading a disk. */
 export function frond(name: string, declared: FrondDeclaration = {}): FrondDescriptor {
   const scope = declared.scope ?? DEFAULT_CONVENTIONS.scope;
 

package/src/define.ts

@@ -1,9 +1,8 @@
 import type { FougereConfig } from './config-loader.js';
 
 /**
- * Identity helper for fougere.config.ts — preserves literal types for autocomplete
- * while validating against FougereConfig. Equivalent to `satisfies FougereConfig`
- * but more explicit and aligned with defineFrond().
+ * Identity helper for fougere.config.ts — preserves literal types for autocomplete while
+ * validating against FougereConfig.
  */
 export function defineFougere<T extends FougereConfig>(config: T): T {
   return config;

package/src/descriptor/Fronds.ts

@@ -0,0 +1,47 @@
+import type { SchemaView } from '@fougere/schema';
+import type { EntityEntry, FrondDescriptor } from './frond.js';
+
+/** What this app hosts, with the questions everyone was asking it by hand. */
+export class Fronds extends Array<FrondDescriptor> {
+  static override get [Symbol.species](): ArrayConstructor {
+    return Array;
+  }
+
+  /** The fronds an app hosts, scanned or stated. The only gate in — `Array.of` is taken. */
+  static hosting(fronds: readonly FrondDescriptor[]): Fronds {
+    const all = new Fronds();
+    all.push(...fronds);
+    return all;
+  }
+
+  /** The frond that hosts an entity — `undefined` when no loaded frond does. */
+  owner(entity: string): FrondDescriptor | undefined {
+    return this.find((frond) => frond.entities.some((e) => e.name === entity));
+  }
+
+  /** The entity of that name, wherever it was declared. */
+  entity(name: string): EntityEntry | undefined {
+    for (const frond of this) {
+      const found = frond.entities.find((e) => e.name === name);
+      if (found) return found;
+    }
+    return undefined;
+  }
+
+  /** Every entity class, by name — across all fronds and never per-frond. */
+  schemas(): Map<string, SchemaView> {
+    return new Map(this.flatMap((frond) => frond.entities.map((e) => [e.name, e.entityClass] as const)));
+  }
+
+  /** Every declared entity, sorted. What is DECLARED, not what answers. */
+  entityNames(): string[] {
+    return this.flatMap((frond) => frond.entities.map((e) => e.name)).sort();
+  }
+
+  /** The names a call may address, sorted — what a NOT_FOUND must print. */
+  servedNames(surface?: string): string[] {
+    return this.flatMap((frond) => frond.handlers
+      .filter((handler) => (handler.surface ?? undefined) === surface)
+      .map((handler) => handler.address)).sort();
+  }
+}

package/src/descriptor/frond.ts

@@ -0,0 +1,145 @@
+/** What a frond is made of — one interface per convention directory. */
+import type { SchemaView } from '@fougere/schema';
+import type { Param, OperationContract, OperationsMap } from '../wire/operation.js';
+import type { PresenterViews } from '../prefab/presenter.js';
+import type { Fronds } from './Fronds.js';
+
+/** A discovered provider — a class under `services/` or `repositories/`, injected by type. */
+export interface ProviderEntry {
+  /** The class constructor (default export of the file). */
+  ctor: new (...args: never[]) => unknown;
+  /** Constructor dependency type names (from AST scan). */
+  deps: string[];
+  /** Absolute file path (for debugging). */
+  filePath: string;
+}
+
+/** A discovered entity (Entity subclass in entities/ dir). */
+export interface EntityEntry {
+  /** Registration key: class name lowercased first char (e.g. 'product'). */
+  name: string;
+  /** The Entity class (has static getFields()). */
+  entityClass: SchemaView;
+  /** Absolute file path (for debugging). */
+  filePath: string;
+  /** Whether this entity is part of the frond's public contract. */
+  exposed?: boolean;
+}
+
+/** A discovered handler (controls what a service exposes). */
+export interface HandlerEntry {
+  /** Registration key (e.g. 'postHandler'). */
+  name: string;
+  /**
+   * The name this handler answers to — its class name minus `Handler`, lowercased (`PostHandler` →
+   * `post`).
+   */
+  address: string;
+  /** The handler class. */
+  ctor: new (...args: never[]) => unknown;
+  /** All operations with full signatures for binding. */
+  operations: OperationsMap;
+  /** Constructor dependency type names (from AST scan). */
+  deps: string[];
+  /** Absolute file path (for debugging). */
+  filePath: string;
+  /** Whether this handler is part of the frond's public contract. */
+  exposed?: boolean;
+  /** Output schema override — when Crud(Entity, Output), restricts storage output. */
+  outputOverride?: SchemaView;
+  /** Surface name — subdirectory in handlers/ (e.g. 'admin', 'public'). */
+  surface?: string;
+}
+
+/** Return type metadata for a presenter computed field. */
+export interface PresenterFieldMeta {
+  name: string;
+  /** Inferred return type name: 'string', 'number', 'boolean', or a class name. */
+  returnType?: string;
+  /** The field emits a LIST per row — `tags(posts: Post[]): string[][]`. */
+  list?: boolean;
+  /** Whether the return is nullable. */
+  nullable?: boolean;
+  /** The declared parameters AFTER the rows. */
+  params?: Param[];
+}
+
+/** A discovered presenter (computed fields for an entity's output). */
+export interface PresenterEntry {
+  /** Entity name this presenter enriches (e.g. 'post' from PostPresenter). */
+  entityName: string;
+  /** The presenter class. */
+  ctor: new (...args: never[]) => unknown;
+  /** Computed field names (method names on prototype). */
+  fields: string[];
+  /** Per-field type metadata (inferred from source via parser). */
+  fieldMeta: PresenterFieldMeta[];
+  /**
+   * The view each computed field emits, when the presenter declares one (`Presenter(Order, {
+   * items: [OrderItemView] })`).
+   */
+  views?: PresenterViews;
+  /** Constructor dependency type names (from AST scan). */
+  deps: string[];
+  /** Absolute file path (for debugging). */
+  filePath: string;
+}
+
+/** 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;
+}
+
+/** A discovered seed file (array of records or async factory). */
+export interface SeedEntry {
+  /** Entity name this seed targets (from filename: Author.seed.ts → 'author'). */
+  entityName: string;
+  /** Raw default export — array or function. Resolved at runtime. */
+  data: Record<string, unknown>[] | SeedFactory;
+  /** Absolute file path (for debugging). */
+  filePath: string;
+}
+
+/** Seed factory — receives a resolver to access handlers cross-frond. */
+export type SeedFactory = (resolve: <T>(name: string) => T) => Promise<Record<string, unknown>[]>;
+
+/** Where a frond lives on disk. */
+export interface FrondSource {
+  /** Absolute path to the frond directory. */
+  path: string;
+  /** The @fronds/{name} package name. Always present. */
+  package: string;
+}
+
+export interface FrondDescriptor {
+  name: string;
+  source: FrondSource;
+  providers: ProviderEntry[];
+  entities: EntityEntry[];
+  handlers: HandlerEntry[];
+  presenters: PresenterEntry[];
+  collectors: CollectorEntry[];
+  seeds: SeedEntry[];
+  /**
+   * Per-surface entity lists from frond.config.ts (e.g. { graphql: ['Post'], rest: ['Post',
+   * 'Author'] }).
+   */
+  surfaces?: Record<string, string[]>;
+  /** Entities this frond may read across sources — see `FrondConfig.reads`. */
+  reads?: string[];
+  /** Per-operation overrides from frond.config.ts. */
+  operationsOverrides?: Record<string, OperationContract & {
+    kind?: 'query' | 'command';
+    /** Class name to resolve from DI (overrides default `{Entity}Handler` lookup). */
+    handlerName?: string;
+    /** Method name on the resolved handler (defaults to op name). */
+    method?: string;
+  }>;
+}