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

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[]> {

package/src/index.ts

@@ -1,16 +1,7 @@
-/**
- * What a consumer writes, and nothing else.
- *
- * `exports` publishes this barrel and `./contract`, so an import that is not here
- * cannot be reached from outside the package at all — which is what makes this file
- * the contract rather than a convenience. The machinery the boot uses to keep its own
- * promises stays inside: container keys, the binding plan, the mixin's runtime
- * accessors, the config merge. Measured on 2026-08-16, none of them had a single
- * importer anywhere in the workspace.
- */
+/** What a consumer writes, and nothing else. */
 export { createApp } from './boot/bootstrap.js';
 export { orderSeeds, runSeeds, seeding } from './boot/seed.js';
-export { AppLifecycle, AppLifecycle as Lifecycle, migrating } from './boot/AppLifecycle.js';
+export { AppLifecycle, migrating } from './boot/AppLifecycle.js';
 export type { Extension } from './boot/AppLifecycle.js';
 export { defineFougere } from './define.js';
 export type { AdapterConfig, FougereConfig } from './config-loader.js';
@@ -24,17 +15,17 @@ export { Presenter } from './prefab/presenter.js';
 export type { PresenterViews } from './prefab/presenter.js';
 export { Collector } from './prefab/collector.js';
 export { Repository, type RepositoryOf, type RepositoryConstructor, type AggregateOf, type AggregateConstructor } from './prefab/repository.js';
-export { Invocation, canonicalInvocation, EMPTY_INVOCATION } from './contract/Invocation.js';
-export type { InvocationContext, 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 { Invocation, canonicalInvocation, EMPTY_INVOCATION } from './wire/Invocation.js';
+export type { InvocationContext, 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 { DispatchLifecycle } from './dispatch/DispatchLifecycle.js';
 export { Dispatcher } from './dispatch/Dispatcher.js';
 // The class and not only its type: an observer RECEIVES these, so a package that folds
 // them — or a test of one — has to be able to make one through the door.
 export { DispatchEvent } from './dispatch/DispatchEvent.js';
-export type { CallPage, CallRecord } from './contract/CallLog.js';
+export type { CallPage, CallRecord } from './wire/CallLog.js';
 export { driftOf, agrees, explain, type CardDrift } from './wire/drift.js';
 export type { DispatchObserver } from './dispatch/DispatchEvent.js';
 export type { DispatchPort } from './dispatch/DispatchPort.js';
@@ -87,15 +78,17 @@ export { callValueOf } from './contract.js';
 export type { CallValue } from './contract.js';
 export { toHttpError, toPublicError } from './wire/http-error.js';
 export { loggerMiddleware } from './wire/loggerMiddleware.js';
-export { Logger, setLogLevel, logLevel, envLevel, onLog } from './builtins/logger.js';
-export type { LogLevel, LogRecord, LogSink } from './builtins/logger.js';
+export { Logger, setLogLevel, logLevel, envLevel, onLog } from './builtin/logger.js';
+export type { LogLevel, LogRecord, LogSink } from './builtin/logger.js';
 // What a re-read config changes in a running process — and what it cannot.
 export { applyConfig, type ConfigApplication } from './boot/apply.js';
-export { Config } from './builtins/config.js';
-export type { Storage, StorageFactory, Source, SourceConfig, SourceView, ListOptions, ListResult, Together } from './storage.js';
-export { Sources, togetherKeyOf, membersOfTogetherKey } from './storage.js';
-export { storageOver } from './rows.js';
-export type { Rows, Row } from './rows.js';
+export { Config } from './builtin/config.js';
+export type { Storage, StorageFactory, ListOptions, ListResult, Together } from './storage.js';
+export { togetherKeyOf, membersOfTogetherKey } from './storage.js';
+export type { Constraint, Source, SourceConfig, SourceView } from './source.js';
+export { Sources } from './source.js';
+export { storageOver } from './store.js';
+export type { Store, Values } from './store.js';
 export type { App, CreateAppOptions } from './boot/types.js';
 export type { ScanResult, ScanDiagnostic } from './scan/result.js';
 export type {

package/src/loader.ts

@@ -1,21 +1,7 @@
-/**
- * How a source file becomes a module — one registry, two readers.
- *
- * The scanner loads fronds and `config-loader` loads a config, and both must use the
- * loader the host installed: a TS file needs jiti under Nuxt and plain `import` under
- * tsx. It lived in `scan/scanner.ts`, so reading a config dragged the scanner, its AST
- * parser and the TypeScript compiler behind it.
- */
+/** How a source file becomes a module — one registry, two readers. */
 import { pathToFileURL } from 'node:url';
 
-/**
- * Module loader — can be swapped (e.g. jiti for TS files in Nuxt context).
- *
- * `fresh` asks for a file that may have changed since it was last read. Every loader
- * caches, so without it a second read of an EDITED file hands back the first one —
- * which is what re-reading a config is for. A loader that cannot honour it may ignore
- * the flag; it then answers with what it already had.
- */
+/** Module loader — can be swapped (e.g. */
 export type ModuleLoader = (
   filePath: string,
   options?: { fresh?: boolean },

package/src/node.ts

@@ -1,14 +1,4 @@
-/**
- * What Fougere does with a filesystem — the half of core that a Worker cannot run.
- *
- * The line is not "build vs runtime": `boot()` and `loadConfig` run in production, on a
- * server, every time. It is whether the thing reaches for a disk. Everything here does,
- * transitively, and nothing on the main entry does — which is what lets a bundler for a
- * runtime without `node:fs` trace the main entry and find no builtin at all.
- *
- * The third entry, `@fougere/core/contract`, answers a different question: what crosses a
- * process boundary. A foreign frond reads it without reading our boot.
- */
+/** What Fougere does with a filesystem — the half of core that a Worker cannot run. */
 export { boot } from './boot/boot.js';
 
 export { scanProject, frondAliases, watchPathsOf } from './scan/scanner.js';
@@ -23,6 +13,7 @@ export { setModuleLoader, getModuleLoader } from './loader.js';
 export { loadConfig, loadCascadedConfig } from './config-loader.js';
 export { defineFrond } from './frond-config.js';
 export { crossFrondImports } from './imports.js';
+export { adaptersOf } from './scan/adapters.js';
 
 // Making a key and binding a name to it happen once, at a deployment, on a machine with
 // a filesystem — the CLI speaking. Verifying happens per call, everywhere, and stays on

package/src/prefab/collector.ts

@@ -1,25 +1,4 @@
-/**
- * Collector(Type) — resolves one handler input parameter from the invocation context.
- *
- * The target is a NAME matched against the parameter's type, never a schema: nothing
- * here nor in the scan reads its fields. So `Ability`, built per call from state, sits
- * beside `User`, loaded from a row.
- *
- * The dual of Presenter only in direction. A presenter's subject is a ROW — it adds
- * computed fields to one, so its target must be an entity. A collector's subject is a
- * PARAMETER.
- *
- * Usage:
- * ```ts
- * export default class UserCollector extends Collector(User) {
- *   constructor(private userStorage: UserStorage) { super(); }
- *
- *   async collect(ctx: InvocationContext) {
- *     return this.userStorage.findById(ctx.state.userId as string);
- *   }
- * }
- * ```
- */
+/** Collector(Type) — resolves one handler input parameter from the invocation context. */
 
 import { upperFirst } from '@fougere/schema';
 

package/src/prefab/crud.ts

@@ -1,48 +1,42 @@
+import { lowerFirst, type EntityConstructor, type SchemaView } from '@fougere/schema';
 import type { Storage, ListOptions, ListResult } from '../storage.js';
 import type { OperationContract } from '../wire/operation.js';
-import type { EntityConstructor, SchemaView } from '@fougere/schema';
+import { targetOf } from './prefab.js';
 
-/** The id of the row an op acts on — a route segment, or a query fallback. */
-const byId = { name: 'id', source: { kind: 'param' as const, name: 'id' }, optional: false };
-const fromBody = { name: 'input', source: { kind: 'body' as const }, optional: false };
+/**
+ * So a class is recognized by what it ANSWERS, since the mixin leaves no other trace.
+ * FR : pour qu'une classe se reconnaisse à ce qu'elle répond, le mixin ne laissant rien d'autre.
+ * `inheritsCrud(class PostHandler extends Crud(Post) {})` → `true`
+ */
+export function inheritsCrud(ctor: unknown): boolean {
+  const proto = (ctor as { prototype?: Record<string, unknown> } | undefined)?.prototype;
+
+  return typeof proto?.list === 'function' && typeof proto?.findById === 'function';
+}
 
 /**
- * The same five, written as the scan would have written them.
- *
- * `binding` says WHERE an argument is read from; it never says of what type, and a
- * GraphQL argument needs the type. So a producer that fills only `binding` leaves
- * `adapter/graphql` with nothing to declare — it drops the op (`registerOperations`,
- * `if (!sig) continue`) and four of the five CRUD ops vanish from the schema while
- * the façade and REST still serve them. Measured on an installed app: 16 handlers,
- * 14 with unresolvable heritage, zero `createX` in the schema.
+ * So storage follows the shape the handler was built on, which may differ from its address.
+ * FR : pour que le stockage suive la forme sur laquelle le handler est bâti.
+ * `subjectOf(class Draft extends Crud(Post) {}, 'draft')` → `'post'`
  */
+export function subjectOf(ctor: unknown, address: string): string {
+  const target = targetOf(ctor);
+
+  return target?.name ? lowerFirst(target.name) : address;
+}
+
+/** The id of the row an op acts on — a route segment, or a query fallback. */
+const byId = { name: 'id', source: { kind: 'param' as const, name: 'id' }, optional: false };
+const fromBody = { name: 'input', source: { kind: 'input' as const }, optional: false };
+
+/** The same five, written as the scan would have written them. */
 const idParam = { name: 'id', type: { raw: 'string', name: 'string' } };
 const inputParam = (entity: string) => ({ name: 'input', type: { raw: `Partial<${entity}>`, name: entity } });
 const returns = (raw: string, name: string, extra?: { array?: boolean; nullable?: boolean }) =>
   ({ raw, name, ...extra });
 
-/**
- * The five ops a Crud handler brings, declared rather than discovered.
- *
- * The mixin built them, so it alone knows their contract in full: what judges
- * their input, where each argument comes from. It says so on the class, at
- * runtime — which is what makes the guarantee independent of the AST scan (an
- * installed app cannot resolve this file, and never needs to).
- */
-/**
- * `output` says the entity, and saying it costs nothing at runtime.
- *
- * The façade already projected onto the entity when nothing else was named, so this
- * changes no result: `outputFieldsFor` reads `contractOutput` and falls back to the
- * entity, and both are the same shape here. What changes is that the sentence now
- * EXISTS — the identity card publishes `output` per op, and a card was measured
- * carrying none at all (2026-08-06, ten ops, zero outputs), which typed every remote
- * return as `unknown` for anyone building on it.
- *
- * It does not close the view: only an explicit `__opOutputs` does (`closed: perOp !==
- * undefined`), so a named view still wins and a presenter's computed fields still ride
- * out. `delete` names none — a boolean is not a shape.
- */
+/** The five ops a Crud handler brings, declared rather than discovered. */
+/** `output` says the entity, and saying it costs nothing at runtime. */
 function crudOps(entity: SchemaView & { partial?: () => SchemaView }): Record<string, OperationContract> {
   const name = (entity as { name?: string }).name ?? 'Entity';
   const input = inputParam(name);
@@ -76,15 +70,7 @@ function crudOps(entity: SchemaView & { partial?: () => SchemaView }): Record<st
   };
 }
 
-/**
- * The mixin's single "trust me" point — the twin of `asSchemaConstructor` in @fougere/schema.
- *
- * The implementation returns whatever the storage hands back; the declaration names the view
- * each op emits at the port. TypeScript cannot connect the two (the view is a runtime
- * argument, the type is a generic), so one assertion states that the mixin honours what it
- * declared — and the façade makes it true, projecting each op's result onto its view
- * (`outputFieldsFor` in `bootstrap.ts`).
- */
+/** The mixin's single "trust me" point — the twin of `asSchemaConstructor` in @fougere/schema. */
 function asCrudConstructor<T, V>(impl: object): CrudConstructor<T, V> {
   return impl as CrudConstructor<T, V>;
 }
@@ -95,12 +81,7 @@ export type CrudOpName = 'list' | 'findById' | 'create' | 'update' | 'delete';
 /** Which view each op speaks — omitted ops speak the entity, the trivial view. */
 export type CrudViews = Partial<Record<CrudOpName, EntityConstructor>>;
 
-/**
- * The view an op emits, fabricated: the one declared for it, the single view when the
- * whole handler declares one, the entity otherwise. `PostCard` is not a hand-written
- * type — `Post.pick(...)` derives it field by field, so an op's return is a projection
- * of the entity exactly like the entity is the projection that keeps everything.
- */
+/** The view an op emits, fabricated. */
 type OutOf<V, K extends CrudOpName, T> =
   // Bracketed on purpose: a naked `V extends …` DISTRIBUTES, and the no-view default
   // is the empty map, whose `keyof` is `never` — distribution would then collapse
@@ -109,17 +90,7 @@ type OutOf<V, K extends CrudOpName, T> =
   : K extends keyof V ? (V[K] extends EntityConstructor ? InstanceType<V[K]> : T)
   : T;
 
-/**
- * The five ops, typed from the entity and its views.
- *
- * Two things the mixin declares but does not own. The **output** is the view the
- * handler names (`Crud(Post, { list: PostCard })`) — fabricated, so a redefinition
- * that returns cards stays assignable. The **trailing parameters** are resolved by
- * type from the container (`delete(id, user?: User)` gets its user from a
- * collector): the mixin cannot know them, they belong to the app, so it declares that
- * a tail exists and that it supplies none — which is what `never` says, and what keeps
- * a judged redefinition assignable.
- */
+/** The five ops, typed from the entity and its views. */
 export interface CrudOps<T, V = {}> {
   storage: Storage<T>;
   list(options?: ListOptions, ...collected: never[]): Promise<ListResult<OutOf<V, 'list', T>>>;
@@ -141,20 +112,7 @@ export interface CrudConstructor<T, V = {}> {
   readonly __ops: Record<string, OperationContract>;
 }
 
-/**
- * Mixin — extends Crud(Entity) to get all 5 typed CRUD methods.
- *
- * The second argument (optional) names the view the ops emit, and comes in two
- * spellings of one idea — a view per op, or one view for all five:
- *
- * Crud(Post)                      → every op emits Post
- * Crud(Post, { list: PostCard })  → list emits cards, the rest emit Post. Declaration
- *                                   only: the handler keeps its full-row storage, so a
- *                                   judge can still read `body`.
- * Crud(Post, PostPublic)          → every op emits PostPublic, and the bootstrap
- *                                   scopes the injected storage via .output(PostPublic) —
- *                                   the whole handler speaks the restricted view.
- */
+/** Mixin — extends Crud(Entity) to get all 5 typed CRUD methods. */
 export function Crud<E extends EntityConstructor, V extends CrudViews | EntityConstructor = {}>(
   entity: E,
   output?: V,
@@ -168,10 +126,13 @@ export function Crud<E extends EntityConstructor, V extends CrudViews | EntityCo
 
   return asCrudConstructor<T, V>(class CrudHandler {
     static __entity = entity;
-    /** Handler-wide view only — a per-op map must NOT scope the storage the judges read. */
+    /** Handler-wide view only — a per-op map must NOT scope the storage the validators read. */
     static __output = wholeHandler ?? entity;
     static __opOutputs = perOp;
-    /** What this prefab handler declares — read by the façade, merged under the author's own methods. */
+    /**
+     * What this prefab handler declares — read by the façade, merged under the author's own
+     * methods.
+     */
     static __ops: Record<string, OperationContract> = crudOps(entity as unknown as SchemaView & { partial?: () => SchemaView });
 
     storage: Storage<T>;

package/src/prefab/mirror.ts

@@ -1,32 +1,10 @@
-import { FieldSet, Lifecycle, type EntityConstructor, type Fields, type ValidationResult } from '@fougere/schema';
+import { Lifecycle, type EntityConstructor, type Fields } from '@fougere/schema';
 import type { Storage } from '../storage.js';
 
-/**
- * A paginated local copy of a source that cannot be queried directly.
- *
- * The shape must contain an `updated()` field used as a high-water mark. Subclasses
- * implement `pull`; `refresh` validates and upserts each returned page.
- *
- * ```ts
- * export default class PartnerCatalog extends Mirror(BookCard) {
- *   constructor(storage: Storage<BookCard>, private catalog: Facade<CatalogHandler>) {
- *     super(storage);
- *   }
- *
- *   async *pull(since?: Date) {
- *     for (let page = 0; page !== null;) {
- *       const body = await fetch(`${api}?page=${page}&since=${since?.toISOString() ?? ''}`);
- *       const { items, next } = await body.json();
- *       yield items.map(toCard);
- *       page = next;
- *     }
- *   }
- * }
- * ```
- */
+/** A paginated local copy of a source that cannot be queried directly. */
 /** What one refresh did — enough to log it, and to decide whether to run again. */
 export interface Refreshed {
-  /** Rows written, counting a replaced row once. */
+  /** Instances written, counting a replaced one once. */
   written: number;
   /** The age the pull was asked to start from — absent on the first ever run. */
   since?: Date;
@@ -84,7 +62,7 @@ export function Mirror<E extends EntityConstructor>(shape: E): MirrorConstructor
       // Preserve the source's page boundaries: one page becomes one upsert.
       for await (const page of this.pull(since)) {
         if (page.length === 0) continue;
-        written += await this.storage.upsertAll(judgePage(shape, page) as Partial<T>[]);
+        written += await this.storage.upsertAll(page);
       }
       return { written, since, ms: Date.now() - started };
     }
@@ -102,21 +80,3 @@ export function ageFieldOf(shape: unknown): string | undefined {
   }
   return undefined;
 }
-
-/** Validate and decode a page, naming a refused row by its declared primary field. */
-function judgePage<T>(shape: unknown, page: Partial<T>[]): Record<string, unknown>[] {
-  const judge = (shape as { validate?: (input: unknown) => ValidationResult<unknown> }).validate;
-  if (typeof judge !== 'function') return page as Record<string, unknown>[];
-
-  const name = (shape as { name?: string }).name ?? 'mirror';
-  const fields = (shape as { getFields?: () => Fields }).getFields?.();
-  const primary = fields ? FieldSet.of(fields).primary : undefined;
-  return page.map((row, index) => {
-    const verdict = judge.call(shape, row);
-    if (verdict.success) return verdict.data as Record<string, unknown>;
-    const key = primary === undefined ? undefined : (row as Record<string, unknown>)[primary];
-    const where = key !== undefined ? `row ${primary} ${JSON.stringify(key)}` : `row ${index} of this page`;
-    const why = verdict.errors.map((e) => `${e.path}: ${e.message}`).join(', ');
-    throw new Error(`${name} mirror refused ${where} — ${why}`);
-  });
-}

package/src/prefab/prefab.ts

@@ -1,20 +1,7 @@
 import type { EntityConstructor } from '@fougere/schema';
 import type { PresenterViews } from './presenter.js';
 
-/**
- * What a prefab class declares about ITSELF, at runtime.
- *
- * `Crud(Post)`, `Presenter(Post)`, `Repository(Post)`, `Collector(User)` and
- * `Mirror(BookCard)` all fabricate a class, and only the fabricator knows what it was
- * built on: the AST scan is workspace-only, so an INSTALLED prefab resolves to nothing
- * and a statement written in source would be lost. Hence a runtime marker — the same
- * reason `__ops` exists.
- *
- * It was three spellings for one statement: `static __entity` on three of the five, a
- * private `Symbol.for('fougere:x_target')` on the other two, and BOTH on `Repository`
- * and `Mirror` — the same class recording its subject twice, under two names, with two
- * readers that could disagree. A mark that answers one question answers it once.
- */
+/** What a prefab class declares about ITSELF, at runtime. */
 interface Prefab {
   /** The shape this class was built on. `Mirror` calls it a shape; it is the same slot. */
   readonly __entity?: EntityConstructor;
@@ -24,13 +11,7 @@ interface Prefab {
   readonly __output?: EntityConstructor;
 }
 
-/**
- * The shape a prefab was built on, or `undefined` when the class is not one.
- *
- * A plain property read: JavaScript walks a constructor's own prototype chain, so a
- * subclass of a prefab answers what its base recorded. Three of the five accessors this
- * replaces walked that chain by hand, and two did not — one question, two mechanisms.
- */
+/** The shape a prefab was built on, or `undefined` when the class is not one. */
 export function targetOf(ctor: unknown): EntityConstructor | undefined {
   return (ctor as Prefab | undefined)?.__entity;
 }

package/src/prefab/presenter.ts

@@ -1,26 +1,4 @@
-/**
- * Presenter(Entity) — enriches an entity's output with computed fields.
- *
- * Each method on the presenter is a computed field resolver:
- * - Receives the entity record as first argument
- * - Can be sync or async
- * - Injected via DI (constructor params resolved by the container)
- *
- * Usage:
- * ```ts
- * export default class PostPresenter extends Presenter(Post) {
- *   constructor(private commentStorage: CommentStorage) { super(); }
- *
- *   excerpt(post: Post) {
- *     return post.body.slice(0, 200);
- *   }
- *
- *   async commentCount(post: Post) {
- *     return this.commentStorage.countFor(post.id);
- *   }
- * }
- * ```
- */
+/** Presenter(Entity) — enriches an entity's output with computed fields. */
 
 import { upperFirst, type EntityConstructor } from '@fougere/schema';
 
@@ -30,19 +8,7 @@ import { upperFirst, type EntityConstructor } from '@fougere/schema';
  */
 export type PresenterViews = Record<string, EntityConstructor | [EntityConstructor]>;
 
-/**
- * `Presenter(Order, { items: [OrderItemView], user: UserCard })` — the second argument names
- * the view each computed field emits, exactly as `Crud(Post, { list: PostCard })` names an
- * op's. What fabricates a field declares its contract, and it declares it **once**: the
- * façade applies the presenter (see `PresenterExecutor`), and every surface reads the same statement
- * instead of guessing.
- *
- * Guessing was the cost of not stating it. The scan can read a scalar off a return type and
- * nothing more, so a field returning an object had no derivable shape: the GraphQL projection
- * fell back to a serialized `String`, and a client asking `items { quantity }` got a schema
- * error on a field REST served whole. Declaring is optional — a scalar field needs nothing,
- * and an undeclared object keeps the old behaviour.
- */
+/** `Presenter(Order, { items. */
 export function Presenter<E extends EntityConstructor>(entity: E, views?: PresenterViews) {
   class PresenterBase {
     static readonly __entity = entity;