@fougere/core 0.9.3-alpha.0 → 0.11.0-alpha.0

package/src/entry/facade.ts

@@ -1,5 +1,5 @@
-import { Call } from '../wire/call.js';
-import type { PartialInvocation } from '../wire/Invocation.js';
+import { Call } from '../wire/Call.js';
+
 import { RouteAddress } from '../wire/RouteAddress.js';
 import type { DispatchPort } from '../dispatch/DispatchPort.js';
 

package/src/entry/transport.ts

@@ -1,7 +1,7 @@
-import { Call } from '../wire/call.js';
+import { Call } from '../wire/Call.js';
 import { RouteAddress } from '../wire/RouteAddress.js';
 import type { DispatchPort } from '../dispatch/DispatchPort.js';
-import type { Transport } from '../wire/call.js';
+import type { Transport } from '../wire/Transport.js';
 
 /** Adapts the historical transport signature to the canonical dispatch port. */
 export function createTransportEntry(dispatcher: DispatchPort, surface?: string): Transport {

package/src/index.ts

@@ -2,48 +2,71 @@
 export { createApp } from './boot/bootstrap.js';
 export { orderSeeds, runSeeds, seeding } from './boot/seed.js';
 export { AppLifecycle, migrating } from './boot/AppLifecycle.js';
-export type { Extension } from './boot/AppLifecycle.js';
+export type { Extension } from './boot/Extension.js';
 export { defineFougere } from './define.js';
-export type { FougereConfig, AdapterConfig } from './config-loader.js';
-export type { OperationOverride, FrondConfig } from './frond-config.js';
-export { buildGraph, clusterEntities, suggestSplit, type EntityNode, type DomainCluster } from './graph.js';
-export { Crud } from './prefab/crud.js';
-export type { CrudViews, CrudOps, CrudOpName, CrudConstructor } from './prefab/crud.js';
-export { Mirror } from './prefab/mirror.js';
-export type { Refreshed, MirrorOf, MirrorConstructor } from './prefab/mirror.js';
+export type { AdapterConfig } from './AdapterConfig.js';
+export type { FougereConfig } from './FougereConfig.js';
+export type { AnswerFor } from './AnswerFor.js';
+export type { FougereNames } from './FougereNames.js';
+export type { FougerePorts } from './FougerePorts.js';
+export type { NameOf } from './NameOf.js';
+export type { PortChoice } from './PortChoice.js';
+export type { FrondConfig } from './FrondConfig.js';
+export type { OperationOverride } from './OperationOverride.js';
+export { buildGraph, clusterEntities, suggestSplit, type DomainCluster } from './DomainCluster.js';
+export { type EntityNode } from './EntityNode.js';
+export { Crud } from './prefab/CrudConstructor.js';
+export type { CrudConstructor } from './prefab/CrudConstructor.js';
+export type { CrudOpName } from './prefab/CrudOpName.js';
+export type { CrudOps } from './prefab/CrudOps.js';
+export type { CrudViews } from './prefab/CrudViews.js';
+export { Mirror } from './prefab/MirrorConstructor.js';
+export type { MirrorConstructor } from './prefab/MirrorConstructor.js';
+export type { MirrorOf } from './prefab/MirrorOf.js';
+export type { Refreshed } from './prefab/Refreshed.js';
 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 { type AggregateConstructor } from './prefab/AggregateConstructor.js';
+export { type AggregateOf } from './prefab/AggregateOf.js';
+export { Repository, type RepositoryConstructor } from './prefab/RepositoryConstructor.js';
+export { type RepositoryOf } from './prefab/RepositoryOf.js';
 export { Invocation } from './contract.js';
 export type { InvocationContext } from './contract.js';
+export type { PartialInvocation } from './contract.js';
 export { Call } from './contract.js';
 export { RouteAddress } from './contract.js';
 export { DispatchLifecycle } from './dispatch/DispatchLifecycle.js';
 export { Dispatcher } from './dispatch/Dispatcher.js';
+export { release, type Releasing } from './dispatch/Release.js';
+export { releasing } from './boot/relations.js';
+export { type Dependent } from './dispatch/Dependent.js';
+export { JOURNAL, type Journal } from './dispatch/Journal.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.
+// them — or a test of one — has to be able to make one through the facade.
 export { DispatchEvent } from './dispatch/DispatchEvent.js';
 export type { CallPage, CallRecord } from './contract.js';
 export { driftOf, agrees, explain, type CardDrift } from './contract.js';
-export type {
-  OperationContract,
-  OperationsMap,
-  Param,
-  TypeRef,
-} from './wire/operation.js';
-export { resolveEffectiveOperations } from './effective-operation.js';
-export type { EffectiveOperation } from './effective-operation.js';
+export type { OperationContract } from './wire/OperationContract.js';
+export type { OperationsMap } from './wire/OperationsMap.js';
+export type { Param } from './wire/Param.js';
+export type { TypeRef } from './wire/TypeRef.js';
+export { resolveEffectiveOperations } from './EffectiveOperationModel.js';
+export type { EffectiveOperation } from './EffectiveOperation.js';
 export type { ModuleLoader } from './loader.js';
 export { FougereError, ErrorCode, validationErrorsOf } from './contract.js';
-export type { AppMiddleware, OperationContext, AppNext } from './wire/middleware.js';
+export type { AppMiddleware } from './wire/AppMiddleware.js';
+export type { AppNext } from './wire/AppNext.js';
+export type { OperationContext } from './wire/OperationContext.js';
 export { assertIdentityCard, RPC_ENTITY, MAX_BODY_BYTES } from './contract.js';
 export { createLocalRunner, createAppRunner } from './boot/runner.js';
 
 // A frond an app STATES, for a boot that will not scan. No disk, no `typescript` — which
 // is why it sits here and not in `/node`, beside the scanner that reads a project.
-export { frond } from './declare.js';
-export type { Declared, FrondDeclaration, DeclaredSubject } from './declare.js';
+export { frond } from './FrondDeclaration.js';
+export type { Declared } from './Declared.js';
+export type { DeclaredSubject } from './DeclaredSubject.js';
+export type { FrondDeclaration } from './FrondDeclaration.js';
 // What this app would answer to `rpc.discover`. Served by the boot, and reached until now
 // only by tests through a deep path — a consumer comparing its own card to a producer's
 // had to dispatch a call to ask a question about itself.
@@ -51,7 +74,20 @@ export { identityCardOf } from './boot/card.js';
 // Its dual: what the app declares about its NEIGHBOURS. Read by `rpc.topology`, by
 // `@fougere/calls` and by `fougere graph`, which each held their own half of it.
 export { declaredTopologyOf } from './boot/declared.js';
-export type { Facade } from './wire/call.js';
+// Both halves of what a call can refuse, put together where they are READ — the framework's
+// follows from `kind` and `input`, so only the frond's travels.
+export { refusalsOf, type Refusable } from './wire/refusals.js';
+// The facades as TYPES — empty here, filled by the `.d.ts` the scan writes beside the app.
+export type { Addresses } from './wire/Addresses.js';
+export type { Answer } from './wire/Answer.js';
+export type { AnyHandler } from './wire/AnyHandler.js';
+export type { FacadeName } from './wire/FacadeName.js';
+export type { FougereHandlers } from './wire/FougereHandlers.js';
+export type { FougereOperations } from './wire/FougereOperations.js';
+export type { HandlerOf } from './wire/HandlerOf.js';
+export type { Refused } from './wire/Refused.js';
+export type { Rows } from './wire/Rows.js';
+export type { Facade } from './wire/Facade.js';
 export type {
   FrondCall,
   Transport,
@@ -64,48 +100,61 @@ export type {
   DeclaredFrond,
   DeclaredEdge,
 } from './contract.js';
-export { type Emit, type Fact, type Pipe } from './wire/emit.js';
+export { type Emit } from './wire/Emit.js';
+export { type Fact } from './wire/Fact.js';
+export { type Pipe } from './wire/Pipe.js';
 export { callValueOf } from './contract.js';
 export { toHttpError } from './wire/http-error.js';
 export { toPublicError } from './contract.js';
 export { loggerMiddleware } from './wire/loggerMiddleware.js';
-export { Carry, Logger, setLogLevel, logLevel, envLevel, formatted } from './builtin/logger.js';
-export type { LogRecord, Rendered, LogSink } from './builtin/logger.js';
+export { Carry } from './builtin/Carry.js';
+export { Logger, envLevel, formatted, logLevel, setLogLevel } from './builtin/Logger.js';
+export type { LogRecord } from './builtin/LogRecord.js';
+export type { LogSink } from './builtin/LogSink.js';
+export type { Rendered } from './builtin/Rendered.js';
 // The fact a boot announces. Its destinations are `@fougere/log`'s; the line is core's.
 export { default as LogLine, CARRIES_LINE, LOG_LINE } from './builtin/LogLine.js';
 // What a re-read config changes in a running process — and what it cannot.
 export { applyConfig } from './boot/apply.js';
 export { Config } from './builtin/config.js';
-export type { StorageFactory, ListOptions, ListResult, Together } from './storage/port.js';
+export type { ListOptions } from './storage/ListOptions.js';
+export type { ListResult } from './storage/ListResult.js';
+export type { StorageFactory } from './storage/StorageFactory.js';
+export type { Together } from './storage/Together.js';
 // A VALUE as well as a type: it is what a wrapper extends, which is the whole of declaring one.
-export { Storage, togetherKeyOf } from './storage/port.js';
-export type { Constraint, Source, SourceConfig, SourceView } from './source.js';
-export { Sources } from './source.js';
-export { storageOver } from './storage/store.js';
-export type { Store, Values } from './storage/store.js';
-export type { App, CreateAppOptions } from './boot/types.js';
-export type { ScanResult, ScanDiagnostic } from './scan.js';
-export {
-  type Conventions, type ConventionsInput, DEFAULT_CONVENTIONS,
-  resolveConventions, frondPackage, frondDirsOf, providerDirsOf,
-} from './conventions.js';
-export type {
-  FrondDescriptor,
-  FrondSource,
-  ProviderEntry,
-  EntityEntry,
-  HandlerEntry,
-  SeedEntry,
-  PresenterEntry,
-  PresenterFieldMeta,
-  CollectorEntry,
-} from './descriptor/frond.js';
-export type { AuthConfig, AuthContext, AuthRuntime } from './boot/auth.js';
+export { Storage, togetherKeyOf } from './storage/Storage.js';
+export type { Constraint } from './Constraint.js';
+export type { Source } from './Source.js';
+export type { SourceConfig } from './SourceConfig.js';
+export type { SourceView } from './SourceView.js';
+export { Sources } from './Source.js';
+export { storageOver } from './storage/Store.js';
+export type { Store } from './storage/Store.js';
+export type { Values } from './storage/Values.js';
+export type { App } from './boot/App.js';
+export type { CreateAppOptions } from './boot/CreateAppOptions.js';
+export type { ScanResult } from './scan.js';
+export type { Diagnostic } from './diagnostic.js';
+export { DEFAULT_CONVENTIONS, frondDirsOf, frondPackage, providerDirsOf, resolveConventions, type Conventions } from './Conventions.js';
+export { type ConventionsInput } from './ConventionsInput.js';
+export type { CollectorEntry } from './descriptor/CollectorEntry.js';
+export type { EntityEntry } from './descriptor/EntityEntry.js';
+export type { FrondDescriptor } from './descriptor/FrondDescriptor.js';
+export type { FrondSource } from './descriptor/FrondSource.js';
+export type { HandlerEntry } from './descriptor/HandlerEntry.js';
+export type { PresenterEntry } from './descriptor/PresenterEntry.js';
+export type { PresenterFieldMeta } from './descriptor/PresenterFieldMeta.js';
+export type { ProviderEntry } from './descriptor/ProviderEntry.js';
+export type { SeedEntry } from './descriptor/SeedEntry.js';
+export type { AuthConfig } from './boot/AuthConfig.js';
+export type { AuthContext } from './boot/AuthContext.js';
+export type { AuthRuntime } from './boot/AuthRuntime.js';
 export { Fronds } from './descriptor/Fronds.js';
-export { verify, type Violation } from './verify.js';
+export { verify, type Misplaced } from './verify.js';
 // Same question as verify(), answered from the source text instead of the model.
 // Who is calling, established rather than accepted — the proof beside `state`'s claim.
 // `generateKeyPair` and `issueGrant` are NOT here: they make keys at a deployment and
 // need `node:crypto` for a gesture WebCrypto has no equal of. They sit on `/node`.
-export { signEnvelope, verifyEnvelope, identityFromEnv } from './identity.js';
-export type { FrondIdentity, SignedCall } from './identity.js';
+export { signEnvelope, verifyEnvelope, identityFromEnv } from './CallIdentity.js';
+export type { FrondIdentity } from './FrondIdentity.js';
+export type { SignedCall } from './wire/SignedCall.js';

package/src/node.ts

@@ -1,7 +1,7 @@
 /** What Fougere does with a filesystem, minus the scan — that is `@fougere/compiler`. */
 export { setModuleLoader, getModuleLoader } from './loader.js';
-export { loadConfig, loadCascadedConfig } from './config-loader.js';
-export { defineFrond, loadFrondConfig } from './frond-config.js';
+export { loadConfig, loadCascadedConfig } from './FougereConfig.js';
+export { defineFrond, loadFrondConfig } from './FrondConfig.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/AggregateConstructor.ts

@@ -0,0 +1,9 @@
+import type { AggregateShape } from './AggregateShape.js';
+import { type EntityConstructor } from '@fougere/schema';
+
+export type AggregateConstructor<E extends readonly EntityConstructor[]> =
+  (new (...storages: unknown[]) => AggregateShape<E>) & {
+    readonly __entity: unknown;
+    /** The entities this class owns. Present from two on — an owner of one owns nothing. */
+    readonly __owns: E;
+  };

package/src/prefab/AggregateOf.ts

@@ -0,0 +1,6 @@
+import { type EntityConstructor } from '@fougere/schema';
+import type { Storage } from '../storage/Storage.js';
+
+/** The tuple an aggregate holds — the readable form of {@link AggregateShape}'s member. */
+export type AggregateOf<E extends readonly EntityConstructor[]> =
+  { [K in keyof E]: Storage<InstanceType<E[K]>> };

package/src/prefab/AggregateShape.ts

@@ -0,0 +1,7 @@
+import type { Storage } from '../storage/Storage.js';
+import type { EntityConstructor } from '@fougere/schema';
+
+/** What an aggregate's subclass sees. */
+export declare abstract class AggregateShape<E extends readonly EntityConstructor[]> {
+  protected storages: { [K in keyof E]: Storage<InstanceType<E[K]>> };
+}

package/src/prefab/{crud.ts → CrudConstructor.ts}

@@ -1,7 +1,12 @@
 import { lowerFirst, type EntityConstructor, type SchemaView } from '@fougere/schema';
-import type { Storage, ListOptions, ListResult } from '../storage/port.js';
-import type { OperationContract } from '../wire/operation.js';
+import type { ListOptions } from '../storage/ListOptions.js';
+import type { ListResult } from '../storage/ListResult.js';
+import type { Storage } from '../storage/Storage.js';
+import type { OperationContract } from '../wire/OperationContract.js';
 import { targetOf } from './prefab.js';
+import type { CrudOpName } from './CrudOpName.js';
+import type { CrudViews } from './CrudViews.js';
+import type { CrudOps } from './CrudOps.js';
 
 /**
  * A class is recognized by what it ANSWERS — the mixin leaves no other trace.
@@ -27,11 +32,14 @@ export function subjectOf(ctor: unknown, address: string): string {
 
 /** 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 });
 
@@ -78,12 +86,6 @@ 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. */
 type OutOf<V, K extends CrudOpName, T> =
   // Bracketed on purpose: a naked `V extends …` DISTRIBUTES, and the no-view default
@@ -93,16 +95,6 @@ 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. */
-export interface CrudOps<T, V = {}> {
-  storage: Storage<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 = {}> {
   // `Storage<T>`, not the bare `Storage`: a handler that injects a second storage has to

package/src/prefab/CrudOpName.ts

@@ -0,0 +1,2 @@
+/** The five ops the mixin fabricates. */
+export type CrudOpName = 'list' | 'findById' | 'create' | 'update' | 'delete';

package/src/prefab/CrudOps.ts

@@ -0,0 +1,24 @@
+import type { CrudOpName } from './CrudOpName.js';
+import type { EntityConstructor } from '@fougere/schema';
+import type { ListOptions } from '../storage/ListOptions.js';
+import type { ListResult } from '../storage/ListResult.js';
+import type { Storage } from '../storage/Storage.js';
+
+/** 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
+  // 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. */
+export interface CrudOps<T, V = {}> {
+  storage: Storage<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>;
+}

package/src/prefab/CrudViews.ts

@@ -0,0 +1,5 @@
+import { type EntityConstructor } from '@fougere/schema';
+import type { CrudOpName } from './CrudOpName.js';
+
+/** Which view each op speaks — omitted ops speak the entity, the trivial view. */
+export type CrudViews = Partial<Record<CrudOpName, EntityConstructor>>;

package/src/prefab/MirrorConstructor.ts

@@ -0,0 +1,35 @@
+import type { EntityConstructor } from '@fougere/schema';
+import type { Storage } from '../storage/Storage.js';
+import type { Refreshed } from './Refreshed.js';
+import type { MirrorOf } from './MirrorOf.js';
+
+export interface MirrorConstructor<T> {
+  new (storage: Storage<T>): MirrorOf<T>;
+  readonly __entity: unknown;
+}
+
+export function Mirror<E extends EntityConstructor>(shape: E): MirrorConstructor<InstanceType<E>> {
+  type T = InstanceType<E>;
+
+  abstract class MirrorBase implements MirrorOf<T> {
+    static readonly __entity = shape;
+
+    constructor(public storage: Storage<T>) {}
+
+    abstract pull(since?: Date): AsyncIterable<Partial<T>[]>;
+
+    async refresh(since?: Date): Promise<Refreshed> {
+      const started = Date.now();
+      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.storage.upsertAll(page);
+      }
+
+      return { written, since, ms: Date.now() - started };
+    }
+  }
+
+  return MirrorBase as unknown as MirrorConstructor<T>;
+}

package/src/prefab/MirrorOf.ts

@@ -0,0 +1,19 @@
+import type { Storage } from '../storage/Storage.js';
+import type { Refreshed } from './Refreshed.js';
+
+/**
+ * A paginated local copy of a source that cannot be queried directly.
+ *
+ * Documented: [the base](https://fougere.dev/docs/concepts/the-base).
+ */
+export interface MirrorOf<T> {
+  /** The copy's own storage — where a page lands. */
+  storage: Storage<T>;
+  /** Pages of rows to write. The one thing a mirror's author supplies. */
+  pull(since?: Date): AsyncIterable<Partial<T>[]>;
+  /**
+   * Pull from `since` and write every page. The mark is the CALLER's: only it knows
+   * whether a pass completed, and a pass that throws must not advance it.
+   */
+  refresh(since?: Date): Promise<Refreshed>;
+}

package/src/prefab/Refreshed.ts

@@ -0,0 +1,9 @@
+/** What one refresh did — enough to log it, and to decide whether to run again. */
+export interface Refreshed {
+  /** Instances written, counting a replaced one once. */
+  written: number;
+  /** The age the pull was asked to start from — absent when it asked for everything. */
+  since?: Date;
+  /** How long the whole pass took, pull included. */
+  ms: number;
+}

package/src/prefab/{repository.ts → RepositoryConstructor.ts}

@@ -1,18 +1,11 @@
 import { upperFirst, type EntityConstructor } from '@fougere/schema';
-import type { Storage, ListOptions, ListResult, SelectOption } from '../storage/port.js';
+import type { ListOptions } from '../storage/ListOptions.js';
+import type { ListResult } from '../storage/ListResult.js';
+import type { SelectOption } from '../storage/SelectOption.js';
+import type { Storage } from '../storage/Storage.js';
 import type { SchemaView } from '@fougere/schema';
-
-/**
- * Repository(…entities) — who owns an entity's storage, and where its questions are named.
- *
- * Documented: [repositories](https://fougere.dev/docs/business/repositories).
- */
-
-/**
- * The shape a repository of ONE entity has — the port itself, plus whatever the subclass names on
- * top.
- */
-export type RepositoryOf<T> = Storage<T>;
+import type { AggregateOf } from './AggregateOf.js';
+import type { AggregateConstructor } from './AggregateConstructor.js';
 
 /** The single-entity form: the port, plus whatever the subclass names. */
 export interface RepositoryConstructor<T> {
@@ -25,21 +18,12 @@ declare abstract class AggregateShape<E extends readonly EntityConstructor[]> {
   protected storages: { [K in keyof E]: Storage<InstanceType<E[K]>> };
 }
 
-/** The tuple an aggregate holds — the readable form of {@link AggregateShape}'s member. */
-export type AggregateOf<E extends readonly EntityConstructor[]> =
-  { [K in keyof E]: Storage<InstanceType<E[K]>> };
-
-export type AggregateConstructor<E extends readonly EntityConstructor[]> =
-  (new (...storages: unknown[]) => AggregateShape<E>) & {
-    readonly __entity: unknown;
-    /** The entities this class owns. Present from two on — an owner of one owns nothing. */
-    readonly __owns: E;
-  };
-
 export function Repository<E extends EntityConstructor>(entity: E): RepositoryConstructor<InstanceType<E>>;
+
 export function Repository<E extends readonly [EntityConstructor, EntityConstructor, ...EntityConstructor[]]>(
   ...entities: E
 ): AggregateConstructor<E>;
+
 export function Repository(...entities: EntityConstructor[]): unknown {
   return entities.length === 1 ? one(entities[0]) : many(entities);
 }

package/src/prefab/RepositoryOf.ts

@@ -0,0 +1,7 @@
+import type { Storage } from '../storage/Storage.js';
+
+/**
+ * The shape a repository of ONE entity has — the port itself, plus whatever the subclass names on
+ * top.
+ */
+export type RepositoryOf<T> = Storage<T>;

package/src/scan.ts

@@ -1,29 +1,9 @@
 import type { Fronds } from './descriptor/Fronds.js';
-
-/** Something the scan could NOT do — recorded instead of swallowed. */
-export interface ScanDiagnostic {
-  /**
-   * `blocking` — the app now serves less than its source declares, and no caller can know it: a
-   * handler that failed to parse contributes zero operations.
-   */
-  severity: 'blocking' | 'warning';
-  /** Stable rule name — `handler-parse-failed`, `directory-unreadable`. */
-  code: string;
-  /** Absolute path of what could not be read. */
-  filePath: string;
-  /** The frond it belongs to, when the scan got far enough to know. */
-  frond?: string;
-  /** The declaration the diagnostic is about — e.g. `PostHandler.publish`. */
-  subject?: string;
-  /** What could not be done, and what it costs. One sentence, for a human. */
-  message: string;
-  /** The underlying failure, kept whole. */
-  cause?: unknown;
-}
+import type { Diagnostic } from './diagnostic.js';
 
 /** Result of scanning a project directory. */
 export interface ScanResult {
   fronds: Fronds;
-  /** What the scan could not do. Empty is a claim, not a default — see {@link ScanDiagnostic}. */
-  diagnostics: ScanDiagnostic[];
+  /** What the scan could not do. Empty is a claim, not a default — see {@link Diagnostic}. */
+  diagnostics: Diagnostic[];
 }

package/src/storage/{criterion.ts → Comparison.ts}

@@ -1,5 +1,5 @@
-/** What a read may ask about one field, and how a storage tells the two forms apart. */
 import { type Field, Shapes } from '@fougere/schema';
+import type { ComparisonName } from './ComparisonName.js';
 
 /**
  * The comparisons a criterion may name.
@@ -23,8 +23,6 @@ export interface Comparison {
 
 export const COMPARISONS = ['gte', 'lte', 'gt', 'lt', 'ne', 'between', 'contains', 'notIn', 'isNull'] as const;
 
-export type ComparisonName = (typeof COMPARISONS)[number];
-
 /**
  * Is this criterion a comparison, or a value that happens to be an object?
  *

package/src/storage/ComparisonName.ts

@@ -0,0 +1,3 @@
+export const COMPARISONS = ['gte', 'lte', 'gt', 'lt', 'ne', 'between', 'contains', 'notIn', 'isNull'] as const;
+
+export type ComparisonName = (typeof COMPARISONS)[number];

package/src/storage/ListOptions.ts

@@ -0,0 +1,29 @@
+/** 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.
+   */
+  where?: Record<string, unknown>;
+}

package/src/storage/ListResult.ts

@@ -0,0 +1,9 @@
+/** 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;
+}

package/src/storage/SelectOption.ts

@@ -0,0 +1,6 @@
+import { type SchemaView } from '@fougere/schema';
+
+/** Select option — restrict returned fields to those of a SchemaView. */
+export interface SelectOption {
+  select?: SchemaView;
+}