@fougere/core 0.2.0-alpha.2 → 0.4.0-alpha.0

package/src/orm.ts

@@ -0,0 +1,252 @@
+import { upperFirst, type SchemaView } from '@fougere/schema';
+
+/** Options for list queries — pagination, sorting, counting. */
+export interface ListOptions {
+  /** Number of records to return. */
+  limit?: number;
+
+  /** Offset-based: skip N records. */
+  offset?: number;
+
+  /** Page-based: 1-indexed page number (requires limit). */
+  page?: number;
+
+  /** Cursor-based: fetch records after this ID. */
+  after?: string;
+
+  /** Field name to order by. */
+  orderBy?: string;
+
+  /** Sort direction (default: 'asc'). */
+  order?: 'asc' | 'desc';
+
+  /** If true, also returns total count (for pagination UIs). */
+  count?: boolean;
+
+  /**
+   * Equality criteria, field by field — `{ orderId: '…' }`. Named rather than spread
+   * across the options so an unknown key stays ignored instead of silently becoming a
+   * filter. `listBy(criteria)` is the same thing said as an intention.
+   */
+  where?: Record<string, unknown>;
+}
+
+/** Result of list() — extends Array so it's backward compatible. */
+export interface ListResult<T> extends Array<T> {
+  /** Total number of matching records (only set when count: true). */
+  total?: number;
+  /** Cursor of the last item (for cursor-based pagination). */
+  endCursor?: string;
+  /** Whether more records exist after endCursor. */
+  hasMore?: boolean;
+}
+
+/**
+ * The keys `list()` answers to. Anything else is a mistake, and saying so is the point:
+ * the façade refuses an unknown key in a CLIENT's input (`Unknown field`) — this applies the
+ * same rule to the framework's own arguments. `list({ orderId })` used to be accepted and
+ * the filter dropped, so a one-to-many relation quietly returned the whole table.
+ */
+const LIST_OPTION_KEYS = [
+  'limit', 'offset', 'page', 'after', 'orderBy', 'order', 'count', 'where', 'select',
+] as const;
+
+/** Refuse an option the port does not answer to, naming it and what was expected. */
+export function assertListOptions(options: object | undefined, entity: string): void {
+  if (!options) return;
+  const legal = new Set<string>(LIST_OPTION_KEYS);
+  const strangers = Object.keys(options).filter((key) => !legal.has(key));
+  if (strangers.length === 0) return;
+  throw new Error(
+    `${entity}.list(): unknown option ${strangers.map((s) => `\`${s}\``).join(', ')}. ` +
+    `Known options are ${LIST_OPTION_KEYS.join(', ')} — to filter, pass \`where: { ${strangers[0]}: … }\`.`,
+  );
+}
+
+/** Select option — restrict returned fields to those of a SchemaView. */
+export interface SelectOption {
+  select?: SchemaView;
+}
+
+/** Per-entity ORM — scoped CRUD operations on a single entity type. */
+export interface EntityOrm<T = Record<string, unknown>> {
+  list(options?: ListOptions & SelectOption): Promise<ListResult<T>>;
+  findById(id: string, options?: SelectOption): Promise<T | undefined>;
+  /**
+   * Read by criteria — `findBy({ email })` for the one, `findAllBy({ orderId })` for the
+   * many, which is what a one-to-many relation *is*.
+   *
+   * Both existed on the SQL implementation from the start and neither was declared here.
+   * A port that hides what it offers is a port nobody can use: `auth-better` cast its way
+   * in (`orm as OrmWithFindBy`), a presenter that needed the lines of an order read the
+   * whole table instead, and the GraphQL relation resolver passed criteria to `list()`
+   * — which drops what it does not know.
+   */
+  findBy(criteria: Partial<T> | Record<string, unknown>, options?: SelectOption): Promise<T | undefined>;
+  findAllBy(criteria: Partial<T> | Record<string, unknown>, options?: SelectOption): Promise<T[]>;
+  /**
+   * Read a SET of rows by their key, in one go — the gesture every other one was
+   * being bent into.
+   *
+   * `findAllBy` compares with `=`, so a list of ids could not be passed to it; the
+   * only way to read N rows was `list()` then filter in memory, which is what 14 of
+   * 14 handlers of a real app measured on 2026-08-14 were doing. It is invisible on
+   * SQLite and it is the whole table the day the rows are not local.
+   *
+   * It answers a MAP, because the caller holds keys and not positions: a page zips
+   * against it by `get(row.authorId)`, a miss is the absence of a key, and a repeated
+   * key is one entry. The list form this replaced promised that zip and could not
+   * keep it — dropping a miss shifts every later position — so each caller rebuilt
+   * the very index the implementation had just thrown away.
+   */
+  findByKeys(ids: readonly string[], options?: SelectOption): Promise<Map<string, T>>;
+  /**
+   * Its dual: the rows that point AT each of these keys, grouped by the one they point at.
+   *
+   * `findByKeys` answers the side a row designates — one each, at most. This answers the
+   * side that designates the row — several each, and a key with none is simply absent.
+   * Together they are both directions of a relation, each in one query.
+   *
+   * Written because the page-shaped gesture only covered one of them: a presenter holding
+   * its page and wanting "the items of these lists" had no vocabulary for it and read the
+   * whole table instead, measured on a real app. `field` names the foreign key on THIS
+   * entity, the one carrying the value.
+   */
+  findAllByKeys(field: string, keys: readonly string[], options?: SelectOption): Promise<Map<string, T[]>>;
+  create(input: Partial<T>, options?: SelectOption): Promise<T>;
+  /**
+   * Write the row, or make the existing one look like this — one statement.
+   *
+   * What an import needs and the port did not have: `create` throws on the second run,
+   * so re-reading a source meant deleting first. Measured pulling an API twice.
+   *
+   * The key and the creation stamps survive an overwrite — a row keeps the moment it
+   * appeared. An engine with no upsert clause refuses by name rather than emulating
+   * one with a read in front, which would promise an atomicity it has not got.
+   */
+  upsert(input: Partial<T>, options?: SelectOption): Promise<T>;
+  /**
+   * A whole page in one statement — what an import writes through.
+   *
+   * Row by row, 500 rows were 500 statements (measured); the shape of an import is a
+   * page, so the write is one too. Answers how many rows were written rather than the
+   * rows: `create` hands back the complete row because a caller acts on it, and an
+   * import acts on none of them — re-reading a page for a symmetry nobody uses would
+   * double the work.
+   */
+  upsertAll(inputs: readonly Partial<T>[], options?: SelectOption): Promise<number>;
+  update(id: string, input: Partial<T>, options?: SelectOption): Promise<T>;
+  delete(id: string): Promise<boolean>;
+  /** Returns a scoped ORM that restricts all read results to the fields of the given schema. */
+  output(schema: SchemaView): EntityOrm<T>;
+  /**
+   * What this ORM wraps — the Kysely instance for the SQL one, something else elsewhere.
+   *
+   * Every judge sits on the ORM's own methods, so a statement issued here meets none of
+   * them: a value the entity refuses lands in the table without a word. It is the port's
+   * own escape hatch rather than a handle on the side, so it keeps the scope the container
+   * gave you — `productOrm.client` reaches the products, not the whole database.
+   *
+   * `unknown` on purpose: the client belongs to the implementation, and narrowing it is
+   * the caller saying out loud which one they are standing on.
+   */
+  readonly client: unknown;
+}
+
+/**
+ * Factory that creates an EntityOrm for a given entity.
+ * Called by bootstrap for every scanned entity.
+ */
+export type OrmFactory = (entity: SchemaView, name: string) => EntityOrm;
+
+/**
+ * Container key of an entity's storage — 'reading' → 'ReadingOrm'.
+ *
+ * The twin of {@link repositoryKeyOf} and of `facadeKeyOf`: the key of a thing
+ * lives with the thing. This one was spelled by hand in four places in
+ * `bootstrap.ts` and a fifth in `scanner.ts` — where the SCAN derives what a
+ * constructor asks for. Two readers of one convention, neither of them naming it,
+ * so a rename would have moved one and left the other resolving to nothing.
+ */
+export function ormKeyOf(entity: string): string {
+  return `${upperFirst(entity)}Orm`;
+}
+
+/**
+ * `Together<[Account, Ledger]>` — writes that stand or fall as one.
+ *
+ * `EntityOrm` is the port whose every gesture is ONE statement, and one statement is
+ * atomic in every engine. This is the port whose unit is a BLOCK: what the callback did
+ * happens entirely, or not at all. Nothing else separates them — the arity of the unit
+ * of work is the whole distinction, which is why this lives here and not in a file of
+ * its own.
+ *
+ * ```ts
+ * constructor(private together: Together<[Account, Ledger]>) {}
+ *
+ * await this.together.run(async ([accounts, ledger]) => {
+ *   await accounts.update(from, { balance: b - amount });
+ *   await ledger.create({ from, to, amount });
+ * });
+ * ```
+ *
+ * **The second list is providers**, rebuilt inside the frame so that what THEY write is
+ * covered too — a `Mirror` writes its pages through `EntityOrm<T>`, so naming it puts
+ * them under the same unwind, with no locator and no second injection path:
+ *
+ * ```ts
+ * constructor(private together: Together<[RateCard, Ledger], [RateMirror]>) {}
+ *
+ * await this.together.run(async ([rates, ledger], [mirror]) => { await mirror.refresh(); });
+ * ```
+ *
+ * Two lists rather than one, because in a signature an entity and a provider are both
+ * written as a class name and their instance types do not separate them — the type would
+ * have to guess, by looking for methods or for a brand, and both answers are worse than
+ * saying it. They are two different facts anyway: what the unwind covers, and what is
+ * rebuilt to make that true.
+ *
+ * **All or nothing is the promise; isolation is not.** On one engine the members are
+ * rebuilt over a transaction and the engine gives both. Across engines a transaction
+ * cannot exist, so the frame keeps the before-image of each write and replays the
+ * inverse in reverse order — the unwind holds, the isolation does not, and a reader
+ * between two writes sees the half. The boot says which of the two it built rather
+ * than letting the author assume the stronger one.
+ */
+export interface Together<E extends readonly unknown[], P extends readonly unknown[] = []> {
+  run<R>(fn: (entities: { [K in keyof E]: EntityOrm<E[K]> }, providers: P) => Promise<R>): Promise<R>;
+}
+
+/**
+ * The container key of a frame — `[['Account', 'Ledger'], ['RateMirror']]` →
+ * 'Account+Ledger|RateMirrorTogether'.
+ *
+ * The DECLARED order, not a sorted one. The tuples are what the callback destructures, so
+ * reordering here would hand `[ledger, accounts]` to a signature that says the opposite —
+ * the type and the runtime disagreeing about the same line. Two orders of one frame are
+ * therefore two keys and two registrations; they cost nothing, a frame holding no state
+ * between runs.
+ */
+export function togetherKeyOf(entities: readonly string[], providers: readonly string[] = []): string {
+  const named = entities.map(upperFirst).join(SEPARATOR);
+  return `${named}${providers.length ? KINDS + providers.map(upperFirst).join(SEPARATOR) : ''}${FRAME}`;
+}
+
+const FRAME = 'Together';
+const SEPARATOR = '+';
+/** Separates the two lists — what the unwind covers, and what is rebuilt to make it true. */
+const KINDS = '|';
+
+/**
+ * The members behind a frame key, or `undefined` when the key is not one.
+ *
+ * The dual of the line above, and here for the reason `factOfEmitKey` is: the boot reads
+ * the key back out of a handler's `deps` to know which frames to build. A key and the way
+ * to undo it belong together — the pair that is split is the pair that drifts.
+ */
+export function membersOfTogetherKey(key: string): { entities: string[]; providers: string[] } | undefined {
+  if (key.length <= FRAME.length || !key.endsWith(FRAME)) return undefined;
+  const [entities, providers = ''] = key.slice(0, -FRAME.length).split(KINDS);
+  const split = (list: string) => list.split(SEPARATOR).filter(Boolean);
+  return { entities: split(entities!), providers: split(providers) };
+}

package/src/prefab/collector.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 userOrm: UserOrm) { super(); }
+ *
+ *   async collect(ctx: InvocationContext) {
+ *     return this.userOrm.findById(ctx.state.userId as string);
+ *   }
+ * }
+ * ```
+ */
+
+import { upperFirst } from '@fougere/schema';
+
+export function Collector<T extends abstract new (...args: any[]) => any>(target: T) {
+  class CollectorBase {
+    static readonly __entity = target;
+  }
+  return CollectorBase;
+}
+
+/** Container key of a collector — 'user' → 'UserCollector', 'ability' → 'AbilityCollector'. */
+export function collectorKeyOf(type: string): string {
+  return `${upperFirst(type)}Collector`;
+}

package/src/prefab/crud.ts

@@ -0,0 +1,188 @@
+import type { EntityOrm, ListOptions, ListResult } from '../orm.js';
+import type { OperationContract } from '../wire/operation.js';
+import type { EntityConstructor, SchemaView } from '@fougere/schema';
+
+/** 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 };
+
+/**
+ * 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.
+ */
+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.
+ */
+function crudOps(entity: SchemaView & { partial?: () => SchemaView }): Record<string, OperationContract> {
+  const name = (entity as { name?: string }).name ?? 'Entity';
+  const input = inputParam(name);
+  return {
+    list: {
+      output: entity, cardinality: 'page',
+      binding: [{ name: 'options', source: { kind: 'query' }, optional: true }],
+      signature: {
+        name: 'list', returnType: returns(`ListResult<${name}>`, 'ListResult'),
+        params: [{ name: 'options', type: { raw: 'ListOptions', name: 'ListOptions' }, optional: true }],
+      },
+    },
+    findById: {
+      output: entity, cardinality: 'maybe', binding: [byId],
+      signature: { name: 'findById', returnType: returns(`${name} | undefined`, name, { nullable: true }), params: [idParam] },
+    },
+    create: {
+      input: entity, output: entity, cardinality: 'one', binding: [fromBody],
+      signature: { name: 'create', returnType: returns(name, name), params: [input] },
+    },
+    // The patch view carries its own mode: an absent field is untouched, an
+    // immutable one re-supplied is refused.
+    update: {
+      input: entity.partial?.(), output: entity, cardinality: 'one', binding: [byId, fromBody],
+      signature: { name: 'update', returnType: returns(name, name), params: [idParam, input] },
+    },
+    delete: {
+      cardinality: 'none', binding: [byId],
+      signature: { name: 'delete', returnType: returns('boolean', 'boolean'), params: [idParam] },
+    },
+  };
+}
+
+/**
+ * The mixin's single "trust me" point — the twin of `asSchemaConstructor` in @fougere/schema.
+ *
+ * The implementation returns whatever the ORM 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`).
+ */
+function asCrudConstructor<T, V>(impl: object): CrudConstructor<T, V> {
+  return impl as CrudConstructor<T, V>;
+}
+
+/** The five ops the mixin fabricates. */
+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.
+ */
+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
+  // every op's output to `never` instead of falling through to the entity.
+  [V] extends [EntityConstructor] ? InstanceType<V & EntityConstructor>
+  : 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.
+ */
+export interface CrudOps<T, V = {}> {
+  orm: EntityOrm<T>;
+  list(options?: ListOptions, ...collected: never[]): Promise<ListResult<OutOf<V, 'list', T>>>;
+  findById(id: string, ...collected: never[]): Promise<OutOf<V, 'findById', T> | undefined>;
+  create(input: Partial<T>, ...collected: never[]): Promise<OutOf<V, 'create', T>>;
+  update(id: string, input: Partial<T>, ...collected: never[]): Promise<OutOf<V, 'update', T>>;
+  delete(id: string, ...collected: never[]): Promise<boolean>;
+}
+
+/** The prefab handler class — its ops, plus the statics the bootstrap and adapters read. */
+export interface CrudConstructor<T, V = {}> {
+  // `EntityOrm<T>`, not the bare `EntityOrm`: a handler that injects a second ORM has to
+  // spell its own constructor, and `super(orm)` with the ORM the container hands it —
+  // typed on the entity, as the `orm` property below already says — was refused.
+  new (orm: EntityOrm<T>): CrudOps<T, V>;
+  readonly __entity: unknown;
+  readonly __output: unknown;
+  readonly __opOutputs?: CrudViews;
+  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 ORM, so a
+ *                                   judge can still read `body`.
+ * Crud(Post, PostPublic)          → every op emits PostPublic, and the bootstrap
+ *                                   scopes the injected ORM via .output(PostPublic) —
+ *                                   the whole handler speaks the restricted view.
+ */
+export function Crud<E extends EntityConstructor, V extends CrudViews | EntityConstructor = {}>(
+  entity: E,
+  output?: V,
+): CrudConstructor<InstanceType<E>, V> {
+  // The entity() factory class IS the data type — no Infer needed.
+  type T = InstanceType<E>;
+
+  // A view is a class (it carries fields) ; a map of views is a plain object.
+  const perOp = typeof output === 'object' && output !== null ? (output as CrudViews) : undefined;
+  const wholeHandler = typeof output === 'function' ? (output as EntityConstructor) : undefined;
+
+  return asCrudConstructor<T, V>(class CrudHandler {
+    static __entity = entity;
+    /** Handler-wide view only — a per-op map must NOT scope the ORM the judges 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. */
+    static __ops: Record<string, OperationContract> = crudOps(entity as unknown as SchemaView & { partial?: () => SchemaView });
+
+    orm: EntityOrm<T>;
+    constructor(orm: EntityOrm) {
+      this.orm = orm as EntityOrm<T>;
+    }
+
+    async list(options?: ListOptions): Promise<ListResult<T>> { return this.orm.list(options) as Promise<ListResult<T>>; }
+    async findById(id: string): Promise<T | undefined> { return this.orm.findById(id); }
+    async create(input: Partial<T>): Promise<T> { return this.orm.create(input); }
+    async update(id: string, input: Partial<T>): Promise<T> { return this.orm.update(id, input); }
+    async delete(id: string): Promise<boolean> { return this.orm.delete(id); }
+  });
+}

package/src/prefab/mirror.ts

@@ -0,0 +1,122 @@
+import { FieldSet, Lifecycle, type EntityConstructor, type Fields, type ValidationResult } from '@fougere/schema';
+import type { EntityOrm } from '../orm.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(orm: EntityOrm<BookCard>, private catalog: Facade<CatalogHandler>) {
+ *     super(orm);
+ *   }
+ *
+ *   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;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+/** 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. */
+  written: number;
+  /** The age the pull was asked to start from — absent on the first ever run. */
+  since?: Date;
+  /** How long the whole pass took, pull included. */
+  ms: number;
+}
+
+export interface MirrorOf<T> {
+  /** The copy's own storage — where a page lands, and where its age is read. */
+  orm: EntityOrm<T>;
+  /** Pages of rows to write. The one thing a mirror's author supplies. */
+  pull(since?: Date): AsyncIterable<Partial<T>[]>;
+  /** Run one pass: read the high-water mark, pull from there, write each page. */
+  refresh(): Promise<Refreshed>;
+  /** When the freshest row here was written — `undefined` while the copy is empty. */
+  freshness(): Promise<Date | undefined>;
+}
+
+export interface MirrorConstructor<T> {
+  new (orm: EntityOrm<T>): MirrorOf<T>;
+  readonly __entity: unknown;
+}
+
+export function Mirror<E extends EntityConstructor>(shape: E): MirrorConstructor<InstanceType<E>> {
+  type T = InstanceType<E>;
+
+  // Refuse an undated copy before it can be used as if it held live rows.
+  const declared = ageFieldOf(shape);
+  if (declared === undefined) {
+    throw new Error(
+      `Mirror(${(shape as { name?: string }).name ?? '?'}): the shape carries no \`updated()\` field — ` +
+      `a copy has to be able to say when it was pulled, and \`refresh\` reads its high-water mark from it.`,
+    );
+  }
+  const age: string = declared;
+
+  abstract class MirrorBase implements MirrorOf<T> {
+    static readonly __entity = shape;
+
+    constructor(public orm: EntityOrm<T>) {}
+
+    abstract pull(since?: Date): AsyncIterable<Partial<T>[]>;
+
+    /** The freshest persisted stamp; no process-local freshness state is kept. */
+    async freshness(): Promise<Date | undefined> {
+      const [newest] = await this.orm.list({ orderBy: age, order: 'desc', limit: 1 });
+      const value = (newest as Record<string, unknown> | undefined)?.[age];
+      return value instanceof Date ? value : undefined;
+    }
+
+    async refresh(): Promise<Refreshed> {
+      const started = Date.now();
+      const since = await this.freshness();
+      let written = 0;
+      // 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.orm.upsertAll(judgePage(shape, page) as Partial<T>[]);
+      }
+      return { written, since, ms: Date.now() - started };
+    }
+  }
+
+  return MirrorBase as unknown as MirrorConstructor<T>;
+}
+
+/** The field whose lifecycle stamps every update. */
+export function ageFieldOf(shape: unknown): string | undefined {
+  const fields = (shape as { getFields?: () => Fields }).getFields?.();
+  if (!fields) return undefined;
+  for (const [name, field] of Object.entries(fields)) {
+    if (Lifecycle.of(field).stampedOnUpdate) return name;
+  }
+  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

@@ -0,0 +1,46 @@
+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.
+ */
+interface Prefab {
+  /** The shape this class was built on. `Mirror` calls it a shape; it is the same slot. */
+  readonly __entity?: EntityConstructor;
+  /** The view each computed field emits — `Presenter(Order, { items: [OrderItemView] })`. */
+  readonly __views?: PresenterViews;
+  /** The view the whole handler speaks — `Crud(Post, PostPublic)`. Same slot, one level up. */
+  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.
+ */
+export function targetOf(ctor: unknown): EntityConstructor | undefined {
+  return (ctor as Prefab | undefined)?.__entity;
+}
+
+/** The views a prefab declares, same rule. */
+export function viewsOf(ctor: unknown): PresenterViews | undefined {
+  return (ctor as Prefab | undefined)?.__views;
+}
+
+/** The handler-wide view a prefab declares, same rule. */
+export function outputOf(ctor: unknown): EntityConstructor | undefined {
+  return (ctor as Prefab | undefined)?.__output;
+}