@fougere/core 0.12.2-alpha.0 → 0.12.5-alpha.0

package/src/boot/install.ts

@@ -1,5 +1,6 @@
 /** Putting one frond into the app being built: its scope, what it serves, what it takes. */
 import type { Container } from '@fougere/container';
+import type { StateShape } from '../wire/StateShape.js';
 import type { ProviderEntry } from '../descriptor/ProviderEntry.js';
 import type { PresenterEntry } from '../descriptor/PresenterEntry.js';
 import { lowerFirst, type Fields, type SchemaView } from '@fougere/schema';
@@ -85,6 +86,8 @@ export interface Assembly {
   seamsOf: Map<string, Map<string, ProviderEntry[]>>;
   log: Logger;
   options: CreateAppOptions;
+  /** What a call's `state` may hold, read off every extension this process mounts. */
+  state: StateShape;
 }
 
 /**
@@ -424,6 +427,7 @@ function buildFacadeInto(
     presenter: presenterMap.get(handler.address),
     presenterScope: scope,
     middlewares: () => getMiddlewares(handler.address),
+    state: assembly.state,
   });
 
   // Emissions use the same contracts and execution path as direct calls, and the terms sit
@@ -457,90 +461,51 @@ function buildFacadeInto(
   ));
 }
 
-export async function installFrond(frond: FrondDescriptor, assembly: Assembly): Promise<void> {
-  const {
-    container, routeRegistry, emissions, dispatcher, localDispatcher, effectiveByKey,
-    boundPorts, refused, operationModel, entityByName, frondOf, contractsOf, getMiddlewares, use,
-    log, options,
-  } = assembly;
-
-  // Declared remote: keep the scanned metadata (bridges route with it),
-  // register nothing locally — resolve() falls through to the remote façade.
-  if (options.remotes && frond.name in options.remotes) {
-    log.child(frond.name).info('declared remote — not hosted locally');
-    // Its facades answer elsewhere, but what they LISTEN to was read here.
-    for (const handler of frond.handlers) {
-      const key = facadeKeyOf(handler.address, handler.surface);
-      const operations = operationModel.forHandler(handler);
-      effectiveByKey.set(key, operations);
-      emissions.note(contractsOf(operations), key);
-
-    }
-
-    return;
+/** Its facades answer elsewhere, but what they LISTEN to is read here, and the bridges route with it. */
+function noteRemoteFrond(frond: FrondDescriptor, { operationModel, effectiveByKey, emissions, contractsOf, log }: Assembly): void {
+  log.child(frond.name).info('declared remote — not hosted locally');
+  for (const handler of frond.handlers) {
+    const key = facadeKeyOf(handler.address, handler.surface);
+    const operations = operationModel.forHandler(handler);
+    effectiveByKey.set(key, operations);
+    emissions.note(contractsOf(operations), key);
   }
-  // A child hangs off its parent, so everything the parent registered answers here too and
-  // nothing else has to know: `ScopeContainer.resolve` already walks up. The boot installs
-  // parents first, which is what makes the key below resolvable.
-  const above = frond.extends ? container.resolve<Container>(`frond:${frond.extends}`) : container;
-  const scope = above.createScope();
-  const frondLog = log.child(frond.name);
-  // The frond's own voice, a child of the APP logger and never of `log` — which is the
-  // boot's, so a service's line would have claimed `boot:` long after the boot was over.
-  scope.registerValue('Logger', container.resolve<Logger>('Logger').child(frond.name));
-
-  // `reads:` is what makes a cross-source reader exist here, and the list IS its
-  // environment — a source holding none of these is never opened. Registered under
-  // the type's own name, which is the key `depKeyOf` already derives for a plain
-  // parameter: `constructor(private reads: Reads)` and nothing else to say.
-  // Declaring `reads:` with nothing to build the reader is a boot that ignores a
-  // clause: the handler asking for `Reads` then dies at its first call, on a
-  // container message that names neither the clause nor what is missing.
-  await registerReads(frond, scope, entityByName, options.sourcesFactory, frondLog);
+}
 
-  // Who owns what, and the rule that makes owning mean something. Before anything is
-  // registered, so a bad line is named by this refusal rather than by the container's.
+/**
+ * Who owns what, and the rule that makes owning mean something — refused before anything is
+ * registered, so a bad line is named here rather than by the container.
+ */
+function ownershipOf(frond: FrondDescriptor, { entityByName, refused }: Assembly): Map<string, string> {
   sharedNames(frond, refused);
   refuseArityDrift(frond, refused);
   const owners = ownersOf(frond.providers, frond.name, refused);
   storageInUserCode(frond, owners, (entity) => entityByName.has(entity), refused);
   crudOnOwned(frond, owners, refused);
 
-  const declared = registerProviders(frond, scope, options.ports, boundPorts, refused, frondLog);
-  // An ancestor's links stand OUTSIDE this frond's own, the order `wrapping` reads — and
-  // like a middleware, a link cannot be inherited through a container key, since a seam has
-  // none: its realization is built rather than resolved.
-  const seams = inheritedSeams(frond, assembly.seamsOf, declared);
-  assembly.seamsOf.set(frond.name, seams);
+  return owners;
+}
 
-  // Register Storage for each entity — PascalCase type name (e.g. 'PostStorage')
-  // When a handler declares Crud(Entity, Output), scope the storage via .output(Output)
-  registerStorages(frond, assembly, scope, seams, owners, frondLog);
+/** A frame is read from the same `deps` every port is: asking for one IS declaring it. */
+function registerFramesOf(frond: FrondDescriptor, assembly: Assembly, scope: Container, frondLog: Logger): void {
+  const { entityByName, frondOf, options, hosting, refused } = assembly;
+  const wanted = [...frond.handlers, ...frond.providers, ...frond.presenters, ...frond.collectors]
+    .flatMap((declared) => declared.deps.map((key) => ({ key, filePath: declared.filePath })));
+
+  registerFrames(scope, wanted, frond.providers, {
+    entityByName,
+    frondOf,
+    hostedHere: (name) => !(options.remotes && name in options.remotes),
+    storageFactory: options.storageFactory,
+    sourceOf: options.sourceOf,
+    transacts: options.transacts,
+    transacted: options.transacted,
+    hosting,
+    log: frondLog,
+  }, refused);
+}
 
-  // Frames, after the ORMs and before anything that may ask for one. A frame is read
-  // from the same `deps` every other port is read from — asking for it IS declaring it,
-  // so nothing is registered for a frame nobody wants.
-  registerFrames(
-    scope,
-    [...frond.handlers, ...frond.providers, ...frond.presenters, ...frond.collectors]
-      .flatMap((d) => d.deps.map((key) => ({ key, filePath: d.filePath }))),
-    frond.providers,
-    {
-      entityByName,
-      frondOf,
-      hostedHere: (name) => !(options.remotes && name in options.remotes),
-      storageFactory: options.storageFactory,
-      sourceOf: options.sourceOf,
-      transacts: options.transacts,
-      transacted: options.transacted,
-      hosting: assembly.hosting,
-      log: frondLog,
-    },
-    refused,
-  );
-
-  // Register presenters in scope — PascalCase type name (e.g. 'PostPresenter')
-  const presenterMap = new Map(frond.presenters.map((p) => [p.entityName, p]));
+function registerPresenters(frond: FrondDescriptor, scope: Container, frondLog: Logger): Map<string, PresenterEntry> {
   for (const presenter of frond.presenters) {
     scope.register(presenterKeyOf(presenter.entityName), presenter.ctor, { deps: presenter.deps });
   }
@@ -548,104 +513,117 @@ export async function installFrond(frond: FrondDescriptor, assembly: Assembly):
     frondLog.debug(`${frond.presenters.length} presenter(s): ${frond.presenters.map((p) => p.entityName).join(', ')}`);
   }
 
-  // Register collectors in scope — PascalCase type name (e.g. 'UserCollector')
-  const collectorTypeNames = new Set(frond.collectors.map((c) => c.typeName));
+  return new Map(frond.presenters.map((presenter) => [presenter.entityName, presenter]));
+}
+
+function registerCollectors(frond: FrondDescriptor, scope: Container, frondLog: Logger): Set<string> {
   for (const collector of frond.collectors) {
-    const key = collectorKeyOf(collector.typeName);
-    scope.register(key, collector.ctor, { deps: collector.deps });
+    scope.register(collectorKeyOf(collector.typeName), collector.ctor, { deps: collector.deps });
   }
   if (frond.collectors.length > 0) {
     frondLog.debug(`${frond.collectors.length} collector(s): ${frond.collectors.map((c) => c.typeName).join(', ')}`);
   }
 
-  // Register middlewares in scope, then take them on. Resolved per call and never here:
-  // a middleware asking for something request-scoped would otherwise be handed the one
-  // instance the boot built — the same reason `getMiddlewares` is read at call time.
-  registerMiddlewares(frond, scope, assembly, frondLog);
-
-  // Build handler facades → registered in ROOT container (public contract)
-  const defaultHandlers = frond.handlers.filter((h) => !h.surface);
-  const surfaceHandlers = frond.handlers.filter((h) => h.surface);
-  const defaultHandlerMap = new Map(defaultHandlers.map((h) => [h.address, h]));
+  return new Set(frond.collectors.map((collector) => collector.typeName));
+}
 
-  const building: Building = { frond, assembly, scope, collectorTypeNames, presenterMap, frondLog };
-  const buildFacade = (
-    entity: EntityEntry | undefined,
-    handler: HandlerEntry,
-    targetScope: Container,
-    facadeKey: string,
-  ) => buildFacadeInto(building, entity, handler, targetScope, facadeKey);
-
-  // A presenter is about an entity — computed fields sit on a shape — so this walks
-  // entities. Exposing the instance lazily; the bridge resolves it on first access.
-  exposePresenters(frond, presenterMap, container, scope);
+function sayFacade(building: Building, facadeKey: string, entity: EntityEntry | undefined): void {
+  const operations = Object.keys(building.assembly.container.resolve(facadeKey) as object).join(', ');
+  building.frondLog.debug(`${facadeKey} [${operations}]`
+    + (entity ? '' : ' — no entity of that name: no storage, no projection, no presenter'));
+}
 
-  // A facade is about a handler, so this walks HANDLERS. It walked entities before,
-  // which made an entity a precondition for being callable at all: a handler naming
-  // none was scanned, then never built, and nothing said so.
-  for (const handler of defaultHandlers) {
-    // Two ways to know the subject, and the explicit one wins: `Crud(Item)` names the
-    // entity it was built on, whatever the handler is called. Otherwise the handler's
-    // own name is the only thing pointing at one — and pointing at nothing is legal.
-    //
-    // By NAME, not by identity: the scanner loads an entity through its own loader and
-    // the handler imports it through the runtime's, so the same class arrives as two
-    // objects. `===` compares module instances, which is not the question being asked.
+/**
+ * A facade is about a handler, so this walks HANDLERS — pointing at no entity is legal. The
+ * subject is `Crud(Item)`'s when it names one, the handler's own name otherwise, compared by
+ * NAME: the scanner and the runtime load one class as two objects.
+ */
+function buildDefaultFacades(building: Building, handlers: readonly HandlerEntry[]): void {
+  for (const handler of handlers) {
     const crudTarget = targetOf(handler.ctor);
     const subject = crudTarget?.name ? lowerFirst(crudTarget.name) : handler.address;
-    const entity = frond.entities.find((e) => e.name === subject);
+    const entity = building.frond.entities.find((e) => e.name === subject);
     const facadeKey = facadeKeyOf(handler.address);
-    buildFacade(entity, handler, scope, facadeKey);
-    frondLog.debug(`${facadeKey} [${Object.keys(container.resolve(facadeKey) as object).join(', ')}]`
-      + (entity ? '' : ' — no entity of that name: no storage, no projection, no presenter'));
+    buildFacadeInto(building, entity, handler, building.scope, facadeKey);
+    sayFacade(building, facadeKey, entity);
   }
+}
 
-  // The dual, and it stays: a shape that declares no operation answers nothing. Said
-  // once per entity rather than deduced from a silence.
-  for (const entity of frond.entities) {
-    if (!defaultHandlerMap.has(entity.name)) {
-      frondLog.debug(`${entity.name} — entity only, no handler: exposes nothing`);
-    }
+/** A shape that declares no operation answers nothing — said once per entity rather than deduced from a silence. */
+function sayUnhandledEntities(building: Building, handlers: readonly HandlerEntry[]): void {
+  const handled = new Set(handlers.map((handler) => handler.address));
+  for (const entity of building.frond.entities) {
+    if (!handled.has(entity.name)) building.frondLog.debug(`${entity.name} — entity only, no handler: exposes nothing`);
   }
+}
 
-  // Surface handlers — create sub-scope per surface handler with scoped storage
-  //
-  // Pointing at nothing is legal HERE TOO. This loop used to `continue` when no entity
-  // carried the handler's name, so `handlers/public/SearchHandler.ts` with no `Search`
-  // entity got no facade at all and no line saying why — while the very same handler at
-  // the default surface is built and logged. One rule, both surfaces.
-  for (const handler of surfaceHandlers) {
-    const entity = frond.entities.find((e) => e.name === handler.address);
-    const surfaceScope = scope.createScope();
-
-    // Register scoped storage if output override differs from entity — under the REPOSITORY
-    // key, which is what a Crud handler asks for, and under the port's own for a holder
-    // that legitimately names it. Registering only the latter left a named surface with
-    // no facade at all once the façade stopped spelling the storage.
-    if (entity) registerSurfaceStorage(entity, handler, surfaceScope, assembly, frondLog);
+/**
+ * One sub-scope per surface handler, holding the storage its view scopes — under the REPOSITORY
+ * key a Crud handler asks for. Pointing at no entity is legal here too: one rule, both surfaces.
+ */
+function buildSurfaceFacades(building: Building, handlers: readonly HandlerEntry[]): void {
+  for (const handler of handlers) {
+    const entity = building.frond.entities.find((e) => e.name === handler.address);
+    const surfaceScope = building.scope.createScope();
+    if (entity) registerSurfaceStorage(entity, handler, surfaceScope, building.assembly, building.frondLog);
 
     const facadeKey = facadeKeyOf(handler.address, handler.surface);
-    buildFacade(entity, handler, surfaceScope, facadeKey);
-    frondLog.debug(`${facadeKey} [${Object.keys(container.resolve(facadeKey) as object).join(', ')}]`
-      + (entity ? '' : ' — no entity of that name: no storage, no projection, no presenter'));
+    buildFacadeInto(building, entity, handler, surfaceScope, facadeKey);
+    sayFacade(building, facadeKey, entity);
   }
+}
 
-  // A named surface is closed, so what it contains is a fact worth stating.
-  // Saying it at boot is the difference between a rule and a rule you can
-  // check: an entity you meant to serve and never wrote a handler for is
-  // absent HERE, in one line, instead of being discovered missing later.
-  const surfaceNames = [...new Set(surfaceHandlers.map((h) => h.surface as string))].sort();
+/** A named surface is closed, so what it serves — and what it leaves out — is said at boot, in one line. */
+function sayWhatSurfacesServe(frond: FrondDescriptor, handlers: readonly HandlerEntry[], frondLog: Logger): void {
+  const surfaceNames = [...new Set(handlers.map((h) => h.surface as string))].sort();
   for (const surfaceName of surfaceNames) {
-    const served = surfaceHandlers
-      .filter((h) => h.surface === surfaceName)
-      .map((h) => h.address)
-      .sort();
+    const served = handlers.filter((h) => h.surface === surfaceName).map((h) => h.address).sort();
     const absent = frond.entities.map((e) => e.name).filter((n) => !served.includes(n));
     frondLog.info(
       `surface '${surfaceName}' — ${served.length} entit${served.length === 1 ? 'y' : 'ies'}: ${served.join(', ')}` +
       (absent.length > 0 ? ` (not served: ${absent.join(', ')})` : ''),
     );
   }
+}
+
+export async function installFrond(frond: FrondDescriptor, assembly: Assembly): Promise<void> {
+  const { container, entityByName, options, log } = assembly;
+
+  if (options.remotes && frond.name in options.remotes) {
+    noteRemoteFrond(frond, assembly);
+
+    return;
+  }
+
+  // A child hangs off its parent, so what the parent registered answers here too — parents are installed first.
+  const above = frond.extends ? container.resolve<Container>(`frond:${frond.extends}`) : container;
+  const scope = above.createScope();
+  const frondLog = log.child(frond.name);
+  // A child of the APP logger, never of the boot's, whose `boot:` would outlive the boot.
+  scope.registerValue('Logger', container.resolve<Logger>('Logger').child(frond.name));
+
+  await registerReads(frond, scope, entityByName, options.sourcesFactory, frondLog);
+  const owners = ownershipOf(frond, assembly);
+
+  const declared = registerProviders(frond, scope, options.ports, assembly.boundPorts, assembly.refused, frondLog);
+  // An ancestor's links stand OUTSIDE this frond's own; a seam has no container key to inherit through.
+  const seams = inheritedSeams(frond, assembly.seamsOf, declared);
+  assembly.seamsOf.set(frond.name, seams);
+  registerStorages(frond, assembly, scope, seams, owners, frondLog);
+  registerFramesOf(frond, assembly, scope, frondLog);
+
+  const presenterMap = registerPresenters(frond, scope, frondLog);
+  const collectorTypeNames = registerCollectors(frond, scope, frondLog);
+  registerMiddlewares(frond, scope, assembly, frondLog);
+  exposePresenters(frond, presenterMap, container, scope);
+
+  const building: Building = { frond, assembly, scope, collectorTypeNames, presenterMap, frondLog };
+  const defaultHandlers = frond.handlers.filter((h) => !h.surface);
+  const surfaceHandlers = frond.handlers.filter((h) => h.surface);
+  buildDefaultFacades(building, defaultHandlers);
+  sayUnhandledEntities(building, defaultHandlers);
+  buildSurfaceFacades(building, surfaceHandlers);
+  sayWhatSurfacesServe(frond, surfaceHandlers, frondLog);
 
   container.registerValue(`frond:${frond.name}`, scope);
   frondLog.info(`registered — ${frond.entities.length} entities, ${frond.handlers.length} handlers, ${frond.seeds.length} seeds`);

package/src/boot/nesting.ts

@@ -6,6 +6,7 @@
  * Documented: [fronds](https://fougere.dev/docs/infra/fronds).
  */
 import type { Diagnostic } from '../diagnostic.js';
+import { isFrondDescriptor } from '../descriptor/FrondDescriptor.js';
 import type { FrondDescriptor } from '../descriptor/FrondDescriptor.js';
 import { Fronds } from '../descriptor/Fronds.js';
 import { statesModule, type FrondsStated } from '../FrondsStated.js';
@@ -102,7 +103,7 @@ export function nestingOf(
     if (frond === undefined) continue;
 
     const placed = stated[parent];
-    const address = typeof placed === 'string' ? placed : placed?.remote;
+    const address = typeof placed === 'string' ? placed : isFrondDescriptor(placed) ? undefined : placed?.remote;
     if (address !== undefined || (remotes && parent in remotes)) {
       refused.push({
         severity: 'blocking',

package/src/boot/relations.ts

@@ -4,7 +4,7 @@ import type { Dependent } from '../dispatch/Dependent.js';
 import type { RelationCheck } from '../dispatch/RelationCheck.js';
 import type { Hosting } from './Hosting.js';
 import type { Diagnostic } from '../diagnostic.js';
-import type { Releasing, Rows } from '../dispatch/Release.js';
+import type { Releasing } from '../dispatch/Release.js';
 import type { EntityEntry } from '../descriptor/EntityEntry.js';
 
 /**
@@ -44,11 +44,6 @@ function referencesTo(target: string, hosting: Hosting): { entity: string; field
   return found;
 }
 
-/** What a target's storage has to answer for a key set to be judged in one read. */
-interface ByKeys {
-  findByKeys(keys: readonly string[]): Promise<Map<string, unknown>>;
-}
-
 /**
  * The references a foreign key cannot hold, each as a read the guard makes before the write.
  *
@@ -68,7 +63,7 @@ export function heldBy(entity: SchemaView, name: string, hosting: Hosting): Rela
       field,
       target,
       missing: async (keys) => {
-        const storage = hosting.storageOf(target) as ByKeys | undefined;
+        const storage = hosting.storageOf(target);
         // Nothing here holds those rows — the process that does answers the same reading,
         // so the question crosses rather than being given up on.
         if (!storage) return hosting.peerOf(target)?.missing(target, keys) ?? [];
@@ -176,7 +171,7 @@ export function unheldAmong(checks: readonly RelationCheck[], hosting: Hosting):
 export function releasing(hosting: Hosting): Releasing {
   return {
     dependentsOf: (entity) => dependentsOf(entity, hosting),
-    rowsOf: (entity) => hosting.storageOf(entity) as Rows | undefined,
+    rowsOf: (entity) => hosting.storageOf(entity),
     schemaOf: (entity) => hosting.entities().get(entity),
     peers: () => hosting.peers(),
     journal: (entity) => hosting.journal(entity),

package/src/boot/remote.ts

@@ -4,6 +4,7 @@
  * Documented: [the gradient](https://fougere.dev/docs/infra/gradient).
  */
 import type { FrondCall } from '../wire/FrondCall.js';
+import type { StateShape } from '../wire/StateShape.js';
 import type { Transport } from '../wire/Transport.js';
 import { RPC_ENTITY } from '../wire/RpcAnswer.js';
 import { assertIdentityCard } from '../wire/card/IdentityCard.js';
@@ -103,15 +104,19 @@ export function createRemoteFacade(
   entity: string,
   router: RemoteRouter,
   middlewaresFor: (address: string) => AppMiddleware[],
+  shape: StateShape,
 ): Facade {
-  const opFn = (op: string) => async (invocation: InvocationContext = Invocation.empty) => {
+  const opFn = (op: string) => async (received: InvocationContext = Invocation.empty) => {
     const { frond, transport, schema } = await router.route(entity);
     const call: FrondCall = { frond, entity, op };
+    const state = received.crossed ? { ...received.state } : shape.judge(received.state, entity, op);
+    const invocation = { ...received, state };
+    const entered = { ...state };
     const ctx: OperationContext = {
-      entity, frond, operation: op, args: [], state: invocation.state, invocation,
+      entity, frond, operation: op, args: [], state, invocation,
     };
     const answer = await runMiddlewares(middlewaresFor(entity), ctx, () =>
-      transport(call, ctx.invocation ?? invocation));
+      transport(call, { ...(ctx.invocation ?? invocation), state: shape.judge(ctx.state, entity, op, entered) }));
 
     // The schema the card carried, put to work: a row crosses as data and comes back through
     // the same codecs a local facade applies, so a placement does not decide what a caller

package/src/boot/seed.ts

@@ -1,5 +1,5 @@
+import { pageOf } from '../wire/Page.js';
 import { Role } from '@fougere/schema';
-import { facadeKeyOf } from '../wire/Facade.js';
 import type { FrondDescriptor } from '../descriptor/FrondDescriptor.js';
 import type { SeedEntry } from '../descriptor/SeedEntry.js';
 import type { SeedFactory } from '../descriptor/SeedFactory.js';
@@ -64,14 +64,9 @@ function whatEachWaitsFor(
   }));
 }
 
-/** Where a seed writes, and what it may skip — resolved per entity. */
-interface SeedFacade {
-  list(): Promise<unknown[]>;
-  write(item: unknown): Promise<unknown>;
-}
-
 /**
- * Plant a set of seeds, in the order given.
+ * Plant a set of seeds, in the order given — by the storage, as a handler writes: a seed is the
+ * frond's own code, not a client.
  *
  * Documented: [seeds](https://fougere.dev/docs/business/seeds).
  */
@@ -81,26 +76,26 @@ export async function runSeeds(
   report: (message: string) => void = () => {},
 ): Promise<void> {
   for (const seed of seeds) {
-    const resolve = <T>(name: string) => app.resolve<T>(name + 'Handler');
-    const data = typeof seed.data === 'function' ? await (seed.data as SeedFactory)(resolve) : seed.data;
-
-    const facade = facadeFor(app, seed.entityName);
-    if (!facade) {
-      report(`  ${seed.entityName}: no handler façade nor storage — skipping seed`);
+    const storage = app.storageFor(seed.entityName);
+    if (!storage) {
+      report(`  ${seed.entityName}: no storage in this process — skipping seed`);
       continue;
     }
 
-    const existing = await facade.list();
+    const existing = pageOf(await storage.list()).items;
     if (existing.length > 0) {
       report(`  ${seed.entityName}: skipped (${existing.length} exist)`);
       continue;
     }
 
+    const resolve = <T>(name: string) => app.resolve<T>(name + 'Handler');
+    const data = typeof seed.data === 'function' ? await (seed.data as SeedFactory)(resolve) : seed.data;
+
     // The driver's error alone names neither the entity nor the row — and a foreign
     // key is exactly what a seed gets wrong.
     for (const item of data) {
       try {
-        await facade.write(item);
+        await storage.create(item);
       } catch (cause) {
         throw new Error(
           `Seed '${seed.entityName}' failed on ${JSON.stringify(item)}: ${(cause as Error)?.message ?? cause}`,
@@ -112,28 +107,6 @@ export async function runSeeds(
   }
 }
 
-/** A seed is not a client. */
-function facadeFor(app: App, entityName: string): SeedFacade | undefined {
-  let handler: Record<string, Function> | undefined;
-  try { handler = app.resolve<Record<string, Function>>(facadeKeyOf(entityName)); } catch {}
-
-  const list = handler?.list;
-  const create = handler?.create;
-  if (typeof list === 'function' && typeof create === 'function') {
-    return {
-      list: () => list.call(handler) as Promise<unknown[]>,
-      write: (item) => create.call(handler, { params: {}, query: {}, input: item, state: {} }),
-    };
-  }
-
-  const storage = app.storageFor(entityName) as
-    | { list: () => Promise<unknown[]>; create: (input: unknown) => Promise<unknown> }
-    | undefined;
-  if (!storage) return undefined;
-
-  return { list: () => storage.list(), write: (item) => storage.create(item) };
-}
-
 /**
  * The framework's own ascent for rows, named — so a host can REPLACE it rather than take over the
  * whole post-boot to get its own.

package/src/descriptor/ExtensionEntry.ts

@@ -1,3 +1,5 @@
+import type { Field } from '@fougere/schema';
+
 /**
  * An extension this frond declares — what rises and falls with the process, written beside the
  * code it instruments.
@@ -10,6 +12,19 @@ export interface ExtensionEntry {
   /** Its own `name`, or the file's — the ascent REPLACES a name already declared. */
   name: string;
   /** The value handed to the ascent, the same shape `CreateAppOptions.extensions` takes. */
-  extension: { name?: string; up?: (app: never) => void | Promise<void>; down?: (app: never) => void | Promise<void> };
+  extension: {
+    name?: string;
+    state?: Readonly<Record<string, Field>>;
+    up?: (app: never) => void | Promise<void>;
+    down?: (app: never) => void | Promise<void>;
+  };
   filePath: string;
 }
+
+/** Recognized by its FORM: a value stating `up`, `down`, or the `state` members it declares. */
+export function isExtension(value: unknown): value is ExtensionEntry['extension'] {
+  const shape = value as { up?: unknown; down?: unknown; state?: unknown } | null;
+
+  return typeof shape?.up === 'function' || typeof shape?.down === 'function'
+    || (typeof shape?.state === 'object' && shape.state !== null);
+}

package/src/descriptor/FrondDescriptor.ts

@@ -63,3 +63,10 @@ export interface FrondDescriptor {
     rest?: { method?: string; path?: string; status?: number };
   }>;
 }
+
+/** Recognized by its FORM, like everything a config holds: a name and the lists every frond carries. */
+export function isFrondDescriptor(value: unknown): value is FrondDescriptor {
+  const shape = value as Partial<Record<keyof FrondDescriptor, unknown>> | null;
+
+  return typeof shape?.name === 'string' && Array.isArray(shape.entities) && Array.isArray(shape.handlers);
+}

package/src/descriptor/Fronds.ts

@@ -41,6 +41,16 @@ export class Fronds extends Array<FrondDescriptor> {
     return this.flatMap((frond) => frond.entities.map((e) => e.name)).sort();
   }
 
+  /**
+   * Whether a named surface serves an entity, as its owning frond declared it — `undefined` when
+   * that frond declares no such surface, and a facade registered there answers as it is.
+   */
+  admits(surface: string, entity: string): boolean | undefined {
+    const declared = this.owner(entity)?.surfaces?.[surface];
+
+    return declared?.some((name) => name.toLowerCase() === entity.toLowerCase());
+  }
+
   /** The names a call may address, sorted — what a NOT_FOUND must print. */
   servedNames(surface?: string): string[] {
     return this.flatMap((frond) => frond.handlers

package/src/descriptor/index.ts

@@ -23,6 +23,7 @@ export { type TypeRef } from '../wire/TypeRef.js';
 export { computeBindingPlan, type BindingPlan } from '../wire/binding.js';
 export type { Signature } from '../wire/Signature.js';
 export { awaitKeyOf, emitKeyOf } from '../wire/Emit.js';
+export { addressOf } from '../wire/Facade.js';
 export { storageKeyOf } from '../storage/Storage.js';
 export { getPresenterFields } from '../prefab/presenter.js';
 export { targetOf, viewsOf, outputOf } from '../prefab/prefab.js';

package/src/dispatch/ArgumentResolver.ts

@@ -1,6 +1,7 @@
 import type { InvocationContext } from '../wire/InvocationContext.js';
 import type { BindingPlan } from '../wire/binding.js';
 import type { CollectorLookup } from './CollectorLookup.js';
+import { collectedAs } from '../prefab/collector.js';
 
 /** Resolves an operation's declared binding plan against one invocation. */
 export class ArgumentResolver {
@@ -13,7 +14,7 @@ export class ArgumentResolver {
       switch (binding.source.kind) {
         case 'collector': {
           const collector = this.collectors?.(binding.source.typeName);
-          args.push(collector ? await collector.collect(ctx) : undefined);
+          args.push(collector ? collectedAs(collector, await collector.collect(ctx)) : undefined);
           break;
         }
         case 'context': {

package/src/dispatch/Facade.ts

@@ -3,6 +3,7 @@ import { type AppMiddleware } from '../wire/AppMiddleware.js';
 import type { EffectiveOperationsMap } from '../EffectiveOperationsMap.js';
 import type { HandlerEntry } from '../descriptor/HandlerEntry.js';
 import type { PresenterEntry } from '../descriptor/PresenterEntry.js';
+import type { StateShape } from '../wire/StateShape.js';
 
 /** What boot resolved around one handler, beyond the handler and the scope it resolves in. */
 export interface Facade {
@@ -22,4 +23,6 @@ export interface Facade {
   presenterScope: Container;
   /** The middlewares that apply to this address, read at call time and never at boot. */
   middlewares: () => AppMiddleware[];
+  /** What a call's `state` may hold in this process. */
+  state: StateShape;
 }