@fougere/core 0.8.3-alpha.0 → 0.9.0-alpha.0

package/src/dispatch/StorageGuard.ts

@@ -1,6 +1,6 @@
-import { Boundary, FieldSet, FieldValueValidator, InputRefusal, type Fields } from '@fougere/schema';
-import { COMPARISONS, comparisonOf, unknownIn } from '../criterion.js';
-import { assertListOptions } from '../storage.js';
+import { FieldSet, FieldValueValidator, InputRefusal, type Fields } from '@fougere/schema';
+import { COMPARISONS, comparisonOf, unknownIn } from '../storage/criterion.js';
+import { assertListOptions } from '../storage/port.js';
 import { ErrorCode, FougereError } from '../wire/errors.js';
 
 /** The gestures this guard grafts onto. */
@@ -70,7 +70,7 @@ export class StorageGuard {
     if (typeof list === 'function') {
       guarded.list = async function (...args: unknown[]) {
         const options = args[0] as { where?: Record<string, unknown> } | undefined;
-        assertListOptions(options, validation.entity);
+        assertListOptions(options, validation.entity, Object.keys(validation.fields));
         if (options?.where) args[0] = { ...options, where: validation.criteria(options.where) };
 
         return list.apply(this, args);
@@ -169,11 +169,7 @@ export class StorageGuard {
   /** One value against one field — validated, then decoded the way the wire hands it. */
   private value(field: Fields[string], asked: unknown): { value: unknown } | { error: string } {
     if (asked === null || asked === undefined) return { value: asked };
-    const checked = FieldValueValidator.of(field).validate(asked);
-    if ('error' in checked) return checked;
-    if (checked.value === null) return { value: null };
-
-    return Boundary.of(field).decode(checked.value);
+    return FieldValueValidator.of(field).parse(asked);
   }
 
   private validated<T>(value: T, operation: string, index?: number): T {
@@ -195,18 +191,9 @@ export class StorageGuard {
         parsed[key] = item;
         continue;
       }
-      const checked = FieldValueValidator.of(field).validate(item);
-      if ('error' in checked) {
-        errors.push(`${where}${key}: ${checked.error}`);
-        continue;
-      }
-      if (checked.value === null) {
-        parsed[key] = null;
-        continue;
-      }
-      const decoded = Boundary.of(field).decode(checked.value);
-      if ('error' in decoded) errors.push(`${where}${key}: ${decoded.error}`);
-      else parsed[key] = decoded.value;
+      const value = FieldValueValidator.of(field).parse(item);
+      if ('error' in value) errors.push(`${where}${key}: ${value.error}`);
+      else parsed[key] = value.value;
     }
 
     if (errors.length > 0) {

package/src/dispatch/presenterArguments.ts

@@ -1,24 +1,36 @@
-import { computeBindingPlan } from '../wire/binding.js';
+import { computeBindingPlan, type BindingPlan } from '../wire/binding.js';
 import type { InvocationContext } from '../wire/Invocation.js';
 import type { PresenterEntry } from '../descriptor/frond.js';
 import type { ArgumentResolver } from './ArgumentResolver.js';
 import type { PresenterArgs } from './PresenterExecutor.js';
 
+/**
+ * Where each computed field's extra arguments come from — read off the declaration, so a
+ * field that takes only the page is absent and asks for nothing.
+ */
+export function presenterPlans(
+  meta: PresenterEntry,
+  collectorTypes: Set<string>,
+): Map<string, BindingPlan> {
+  const plans = new Map<string, BindingPlan>();
+  for (const field of meta.fieldMeta) {
+    if (!field.params?.length) continue;
+    plans.set(field.name, computeBindingPlan(field.params, collectorTypes));
+  }
+
+  return plans;
+}
+
 /** The invocation-dependent arguments of every computed presenter field. */
 export async function presenterArguments(
-  meta: PresenterEntry,
+  plans: Map<string, BindingPlan>,
   invocation: InvocationContext,
   resolver: ArgumentResolver,
-  collectorTypes: Set<string>,
 ): Promise<PresenterArgs> {
   const argumentsByField: PresenterArgs = {};
 
-  for (const field of meta.fieldMeta) {
-    if (!field.params?.length) continue;
-    argumentsByField[field.name] = await resolver.resolve(
-      computeBindingPlan(field.params, collectorTypes),
-      invocation,
-    );
+  for (const [field, plan] of plans) {
+    argumentsByField[field] = await resolver.resolve(plan, invocation);
   }
 
   return argumentsByField;

package/src/dispatch/validateInput.ts

@@ -1,4 +1,4 @@
-import { InputValidator, type SchemaView } from '@fougere/schema';
+import { InputValidator, dotted, type SchemaView } from '@fougere/schema';
 import type { InvocationContext } from '../wire/Invocation.js';
 import { ErrorCode, FougereError } from '../wire/errors.js';
 
@@ -17,7 +17,7 @@ export function validateInput(
   if (!result.success) {
     throw new FougereError({
       code: ErrorCode.VALIDATION_FAILED,
-      message: result.errors.map((error) => `${error.path}: ${error.message}`).join(', '),
+      message: result.errors.map((error) => `${dotted(error.path)}: ${error.message}`).join(', '),
       details: result.errors,
       entity,
       operation,

package/src/effective-operation.ts

@@ -4,7 +4,8 @@ import { statementDrift } from './boot/statement-drift.js';
 import { computeBindingPlan, type BindingPlan } from './wire/binding.js';
 import { targetOf } from './prefab/prefab.js';
 import type { CollectorEntry, FrondDescriptor, HandlerEntry } from './descriptor/frond.js';
-import type { ScanDiagnostic } from './scan/result.js';
+import { servedSurfaces } from './descriptor/surface.js';
+import type { ScanDiagnostic } from './scan.js';
 import { verify } from './verify.js';
 import {
   inferOperationKind,
@@ -228,13 +229,19 @@ export function resolveEffectiveOperations(
 
         // A fact is validated by the entity it names. This used to be patched into the
         // facade after resolution, leaving check/explain with a different input.
-        let input = contract.input;
-        if (!input) {
-          const fact = contract.binding.find((binding) => binding.source.kind === 'fact');
-          if (fact?.source.kind === 'fact') input = schemas.get(fact.source.factName);
-        }
-
-        const output = effectiveOutput(frond, handler, name, contract);
+        const announced = contract.binding.find((binding) =>
+          binding.source.kind === 'fact' || binding.source.kind === 'pipe');
+        const fact = announced?.source.kind === 'fact' || announced?.source.kind === 'pipe'
+          ? schemas.get(announced.source.factName)
+          : undefined;
+        const input = contract.input ?? fact;
+
+        // An op that FINISHES a fact answers the fact, so its answer is the fact's shape:
+        // derived here, where its input already is. Left to the ordinary projection it
+        // came back stripped — measured, the subscriber got a value with no `id`.
+        const output = announced?.source.kind === 'pipe' && fact
+          ? { schema: fact, closed: false }
+          : effectiveOutput(frond, handler, name, contract);
         const className = handler.ctor.name.endsWith('Handler')
           ? handler.ctor.name.slice(0, -'Handler'.length)
           : handler.ctor.name;
@@ -279,7 +286,7 @@ export function resolveEffectiveOperations(
             ...(remote ? { remote } : {}),
           },
           exposure: {
-            surfaces: surfacesOf(frond, handler),
+            surfaces: servedSurfaces(frond, handler).map((surface) => surface ?? 'default'),
             adapters: exposedAdapters(handler, options.adapters),
           },
           outputClosed: output.closed,
@@ -557,18 +564,6 @@ function effectiveOutput(
   return { ...(entity ? { schema: entity.entityClass } : {}), closed: false };
 }
 
-function surfacesOf(frond: FrondDescriptor, handler: HandlerEntry): string[] {
-  if (handler.surface) return [handler.surface];
-  const surfaces = ['default'];
-  for (const [surface, addresses] of Object.entries(frond.surfaces ?? {})) {
-    const dedicated = frond.handlers.some((candidate) =>
-      candidate.address === handler.address && candidate.surface === surface);
-    if (!dedicated && addresses.some((address) =>
-      address.toLowerCase() === handler.address.toLowerCase())) surfaces.push(surface);
-  }
-  return [surfaces[0]!, ...surfaces.slice(1).sort()];
-}
-
 function exposedAdapters(
   handler: HandlerEntry,
   adapters: Record<string, boolean | undefined> | undefined,

package/src/frond-config.ts

@@ -11,6 +11,12 @@ export interface OperationOverride {
   kind?: 'query' | 'command';
   /** The GraphQL root field this op answers to. */
   graphql?: string;
+  /**
+   * Where this op answers over REST — the dual of `graphql:`, and the frond's to say for
+   * the same reason: how an operation is CALLED belongs beside it, not in whatever host
+   * mounts the router. The prefix stays the host's: naming is the frond's, mounting is not.
+   */
+  rest?: { method?: string; path?: string; status?: number };
   /**
    * Handler class to delegate to (overrides the default `{Entity}Handler` lookup).
    * Class name is used to resolve from DI. E.g. `ArchiveHandler` → `app.resolve('ArchiveHandler')`.
@@ -44,6 +50,20 @@ export interface FrondConfig {
   surfaces?: Record<string, string[]>;
   /** Interface → implementation bindings for DI (e.g. { Database: 'SqliteDatabase' }). */
   bindings?: Record<string, string>;
+  /**
+   * The ops that FINISH a fact, in the order they run — by class name, keyed by fact.
+   *
+   * Declared by the frond that OWNS the fact, because ordering is a decision about the
+   * fact itself and it has one owner. Without it two links refuse: nothing would say which
+   * ran first, and scan order is not an answer.
+   */
+  pipes?: Record<string, string[]>;
+  /**
+   * How far a middleware reaches, by class name. A middleware answers for its own frond
+   * without being named here; `'app'` is the exception, and it is stated by the frond
+   * that decides for the others.
+   */
+  middlewares?: Record<string, 'frond' | 'app'>;
   /** Per-operation overrides. Key = operation name (method name on a handler). */
   operations?: Record<string, OperationOverride>;
 }

package/src/index.ts

@@ -4,93 +4,84 @@ export { orderSeeds, runSeeds, seeding } from './boot/seed.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';
-export type { FrondConfig, OperationOverride } from './frond-config.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 { CrudOps, CrudOpName, CrudViews, CrudConstructor } from './prefab/crud.js';
+export type { CrudViews, CrudOps, CrudOpName, CrudConstructor } from './prefab/crud.js';
 export { Mirror } from './prefab/mirror.js';
-export type { MirrorOf, MirrorConstructor, Refreshed } from './prefab/mirror.js';
+export type { Refreshed, MirrorOf, MirrorConstructor } from './prefab/mirror.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 { 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 { Invocation } from './contract.js';
+export type { InvocationContext } 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';
 // 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 './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';
-export {
-  inferOperationKind,
-  resolveIsReadOp,
-  resolveOperationKind,
-} from './wire/operation.js';
-export { resolveContracts } from './effective-operation.js';
+export type { CallPage, CallRecord } from './contract.js';
+export { driftOf, agrees, explain, type CardDrift } from './contract.js';
 export type {
   OperationContract,
-  OperationKind,
-  OperationKindInference,
   OperationsMap,
   Param,
   TypeRef,
 } from './wire/operation.js';
-export {
-  EFFECTIVE_OPERATION_SEMANTICS,
-  EffectiveOperationModel,
-  resolveEffectiveOperations,
-} from './effective-operation.js';
-export type {
-  EffectiveCollector,
-  EffectiveOperation,
-  EffectiveOperationOptions,
-  EffectiveOperationsMap,
-  EffectiveParameter,
-} from './effective-operation.js';
+export { resolveEffectiveOperations } from './effective-operation.js';
+export type { EffectiveOperation } from './effective-operation.js';
 export type { ModuleLoader } from './loader.js';
-export { FougereError, ErrorCode, validationErrorsOf, type FougereErrorOptions } from './wire/errors.js';
-export type { OperationContext, AppNext, AppMiddleware } from './wire/middleware.js';
-export { assertIdentityCard, RPC_ENTITY, MAX_BODY_BYTES } from './wire/call.js';
+export { FougereError, ErrorCode, validationErrorsOf } from './contract.js';
+export type { AppMiddleware, OperationContext, AppNext } from './wire/middleware.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 { FrondDeclaration, Declared, DeclaredSubject } from './declare.js';
+export type { Declared, FrondDeclaration, DeclaredSubject } from './declare.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.
 export { identityCardOf } from './boot/card.js';
+export type { Facade } from './wire/call.js';
 export type {
-  FrondCall, Transport, IdentityCard, CardOp, Facade, RpcAnswer,
-  TopologyReport, FrondPlacement, Edge,
-} from './wire/call.js';
-export { type Emit, type Fact } from './emit.js';
+  FrondCall,
+  Transport,
+  IdentityCard,
+  CardOp,
+  TopologyReport,
+  FrondPlacement,
+  Edge,
+} from './contract.js';
+export { type Emit, type Fact, type Pipe } from './wire/emit.js';
 export { callValueOf } from './contract.js';
-export type { CallValue } from './contract.js';
-export { toHttpError, toPublicError } from './wire/http-error.js';
+export { toHttpError } from './wire/http-error.js';
+export { toPublicError } from './contract.js';
 export { loggerMiddleware } from './wire/loggerMiddleware.js';
-export { Logger, setLogLevel, logLevel, envLevel, onLog } from './builtin/logger.js';
-export type { LogLevel, LogRecord, LogSink } from './builtin/logger.js';
+export { Carry, Logger, setLogLevel, logLevel, envLevel, onLog, formatted } from './builtin/logger.js';
+export type { LogRecord, Rendered, LogSink } from './builtin/logger.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, type ConfigApplication } from './boot/apply.js';
+export { applyConfig } from './boot/apply.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 { Storage, StorageFactory, ListOptions, ListResult, Together } from './storage/port.js';
+export { togetherKeyOf } from './storage/port.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 { 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/result.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,
@@ -98,20 +89,16 @@ export type {
   EntityEntry,
   HandlerEntry,
   SeedEntry,
-  SeedFactory,
   PresenterEntry,
   PresenterFieldMeta,
   CollectorEntry,
 } from './descriptor/frond.js';
 export type { AuthConfig, AuthContext, AuthRuntime } from './boot/auth.js';
 export { Fronds } from './descriptor/Fronds.js';
-export { verify, assertSplittable, type Violation } from './verify.js';
+export { verify, type Violation } from './verify.js';
 // Same question as verify(), answered from the source text instead of the model.
-export type { CrossFrondImport } from './imports.js';
-export type { HandlerDeclaration } from './declarations.js';
-export type { OutsideConvention } from './placement.js';
 // 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, VerifiedCall, CallIdentity, SignedCall } from './identity.js';
+export type { FrondIdentity, SignedCall } from './identity.js';

package/src/node.ts

@@ -1,21 +1,7 @@
-/** 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';
-export {
-  type Conventions, type ConventionsInput, DEFAULT_CONVENTIONS,
-  resolveConventions, frondPackage, frondDirsOf, providerDirsOf,
-} from './scan/conventions.js';
-export { RUNTIME_PACKAGES } from './scan/bundling.js';
-export { emitScan, type EmitOptions } from './scan/emit.js';
-export { emitStatement } from './scan/statement.js';
+/** 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 } from './frond-config.js';
-export { crossFrondImports } from './imports.js';
-export { handlerDeclarations } from './declarations.js';
-export { outsideConventions } from './placement.js';
-export { adaptersOf } from './scan/adapters.js';
+export { defineFrond, loadFrondConfig } from './frond-config.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/crud.ts

@@ -1,5 +1,5 @@
 import { lowerFirst, type EntityConstructor, type SchemaView } from '@fougere/schema';
-import type { Storage, ListOptions, ListResult } from '../storage.js';
+import type { Storage, ListOptions, ListResult } from '../storage/port.js';
 import type { OperationContract } from '../wire/operation.js';
 import { targetOf } from './prefab.js';
 

package/src/prefab/mirror.ts

@@ -1,26 +1,27 @@
-import { Lifecycle, type EntityConstructor, type Fields } from '@fougere/schema';
-import type { Storage } from '../storage.js';
+import type { EntityConstructor } from '@fougere/schema';
+import type { Storage } from '../storage/port.js';
 
-/** 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 {
   /** Instances written, counting a replaced one once. */
   written: number;
-  /** The age the pull was asked to start from — absent on the first ever run. */
+  /** 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;
 }
 
+/** A paginated local copy of a source that cannot be queried directly. */
 export interface MirrorOf<T> {
-  /** The copy's own storage — where a page lands, and where its age is read. */
+  /** 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>[]>;
-  /** 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>;
+  /**
+   * 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>;
 }
 
 export interface MirrorConstructor<T> {
@@ -31,16 +32,6 @@ export interface MirrorConstructor<T> {
 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;
 
@@ -48,35 +39,18 @@ export function Mirror<E extends EntityConstructor>(shape: E): MirrorConstructor
 
     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.storage.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> {
+    async refresh(since?: Date): 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.storage.upsertAll(page);
       }
+
       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;
-}

package/src/prefab/repository.ts

@@ -1,5 +1,5 @@
 import { upperFirst, type EntityConstructor } from '@fougere/schema';
-import type { Storage, ListOptions, ListResult, SelectOption } from '../storage.js';
+import type { Storage, ListOptions, ListResult, SelectOption } from '../storage/port.js';
 import type { SchemaView } from '@fougere/schema';
 
 /** Repository(…entities) — who owns an entity's storage, and where its questions are named. */

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

@@ -1,4 +1,4 @@
-import type { Fronds } from '../descriptor/Fronds.js';
+import type { Fronds } from './descriptor/Fronds.js';
 
 /** Result of scanning a project directory. */
 /** Something the scan could NOT do — recorded instead of swallowed. */

package/src/source.ts

@@ -1,5 +1,5 @@
 import { Registry, Role, type SchemaView } from '@fougere/schema';
-import type { StorageFactory } from './storage.js';
+import type { StorageFactory } from './storage/port.js';
 
 /** A promise the judge at the door cannot keep, because it is about rows it never sees. */
 export type Constraint = 'unique';

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

@@ -35,8 +35,8 @@ export type ComparisonName = (typeof COMPARISONS)[number];
  */
 export function comparisonOf(field: Field | undefined, asked: unknown): Comparison | undefined {
   if (asked === null || typeof asked !== 'object' || Array.isArray(asked)) return undefined;
-  // `Shapes.of` answers with `null` already taken out — `optional(json())` is an object.
-  if (!field || Shapes.of(field.shape).base?.type === 'object') return undefined;
+  // The type is read off the base, so `optional(json())` still answers `object`.
+  if (!field || Shapes.typeOf(field.shape) === 'object') return undefined;
 
   return asked as Comparison;
 }

package/src/{storage.ts → storage/port.ts}

@@ -45,15 +45,30 @@ 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 {
+/**
+ * Refuse an option the port does not answer to, and an order by a field the entity does not
+ * declare — an unhonoured `orderBy` returns the page in whatever order the engine chose.
+ */
+export function assertListOptions(
+  options: object | undefined,
+  entity: string,
+  declared: readonly 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;
+  if (strangers.length > 0) {
+    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]}: … }\`.`,
+    );
+  }
+
+  const { orderBy } = options as ListOptions;
+  if (orderBy === undefined || declared.includes(orderBy)) 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]}: … }\`.`,
+    `${entity}.list(): unknown orderBy \`${orderBy}\`. ${entity} declares ${declared.join(', ')}.`,
   );
 }