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

package/src/boot/ports.ts

@@ -1,4 +1,7 @@
-import { nameOf, type ProviderEntry } from '../descriptor/frond.js';
+import { nameOf } from '../descriptor/FrondDescriptor.js';
+import { type ProviderEntry } from '../descriptor/ProviderEntry.js';
+import { basesOf } from '../descriptor/bases.js';
+import type { Diagnostic } from '../diagnostic.js';
 
 /**
  * The framework's own ports — a class core exports that a user class may stand in front of.
@@ -24,23 +27,29 @@ export const SEAMS = new Set(['Storage']);
 export function seamChains(
   providers: ProviderEntry[],
   chosen: Record<string, string | readonly string[]> | undefined,
+  refused: Diagnostic[],
 ): Map<string, ProviderEntry[]> {
   const wrappers = new Map<string, ProviderEntry[]>();
   for (const provider of providers) {
     const seam = (Object.getPrototypeOf(provider.ctor) as { name?: string } | null)?.name;
     if (!seam || !SEAMS.has(seam)) continue;
     if (!provider.deps.includes(seam)) {
-      throw new Error(
-        `[ports] ${nameOf(provider)} extends ${seam}, and a seam's realization is handed in `
-        + `rather than declared — so a class extending one can only stand IN FRONT of it, `
-        + `which it says by asking for it: constructor(private inner: ${seam}).`,
-      );
+      refused.push({
+        severity: 'blocking',
+        code: 'seam-not-wrapped',
+        filePath: provider.filePath,
+        subject: nameOf(provider),
+        message: `${nameOf(provider)} extends ${seam}, and a seam's realization is handed in rather `
+          + 'than declared — so a class extending one can only stand IN FRONT of it, which it says '
+          + `by asking for it: constructor(private inner: ${seam}).`,
+      });
+      continue;
     }
     wrappers.set(seam, [...(wrappers.get(seam) ?? []), provider]);
   }
 
   const bound = new Map<string, ProviderEntry[]>();
-  for (const [seam, all] of wrappers) bound.set(seam, chain(seam, [], all, chosen?.[seam]));
+  for (const [seam, all] of wrappers) bound.set(seam, chain(seam, [], all, chosen?.[seam], refused));
 
   return bound;
 }
@@ -77,22 +86,9 @@ export function portBindings(
   providers: ProviderEntry[],
   answers: (name: string) => boolean,
   chosen: Record<string, string | readonly string[]> | undefined,
+  refused: Diagnostic[],
 ): Map<string, ProviderEntry[]> {
-  // port class name → the classes that extend it, in scan order.
-  const candidates = new Map<string, ProviderEntry[]>();
-  for (const provider of providers) {
-    const base = Object.getPrototypeOf(provider.ctor) as { name?: string } | null;
-    const port = base?.name;
-    // ONE condition: something already answers under that name. Providers are
-    // registered into this scope just above, and the builtins sit in its parent, so
-    // this covers a neighbour service and `Logger` alike — a framework class is a
-    // port like any other, which is what makes a default overridable.
-    //
-    // It is also what excludes a prefab: a repository extends the class
-    // `Repository(Post)` returned (`RepositoryBase`), and no key is ever that name.
-    if (!port || !answers(port)) continue;
-    candidates.set(port, [...(candidates.get(port) ?? []), provider]);
-  }
+  const candidates = basesOf(providers, answers);
 
   const bound = new Map<string, ProviderEntry[]>();
   for (const [port, all] of candidates) {
@@ -102,7 +98,7 @@ export function portBindings(
     const impls = all.filter((one) => !wraps(one));
     const stated = chosen?.[port];
 
-    bound.set(port, chain(port, impls, wrappers, stated));
+    bound.set(port, chain(port, impls, wrappers, stated, refused));
   }
 
   return bound;
@@ -113,6 +109,7 @@ function chain(
   impls: ProviderEntry[],
   wrappers: ProviderEntry[],
   stated: string | readonly string[] | undefined,
+  refused: Diagnostic[],
 ): ProviderEntry[] {
   // The whole chain, outside in — a string is a chain of one, and the last name is what
   // actually answers. What a deployment wraps its realization with is the same kind of
@@ -121,16 +118,21 @@ function chain(
     const order = typeof stated === 'string' ? [stated] : stated;
     const all = [...wrappers, ...impls];
 
-    return order.map((name) => {
+    return order.flatMap((name) => {
       const pick = all.find((one) => nameOf(one) === name);
       if (!pick) {
-        throw new Error(
-          `[ports] ${port}: '${name}' does not extend it. `
-          + `What does: ${all.map(nameOf).join(', ')}.`,
-        );
+        refused.push({
+          severity: 'blocking',
+          code: 'port-not-extended',
+          filePath: all[0]?.filePath ?? 'fougere.config.ts',
+          subject: `ports: { ${port}: '${name}' }`,
+          message: `${port}: '${name}' does not extend it. What does: ${all.map(nameOf).join(', ')}.`,
+        });
+
+        return [];
       }
 
-      return pick;
+      return [pick];
     });
   }
 
@@ -138,22 +140,31 @@ function chain(
     // Refusing rather than keeping one, for the reason `remotes` refuses two owners
     // of an entity: whichever won would depend on scan order, and the handler would
     // charge the wrong provider without a word.
-    throw new Error(
-      `[ports] ${impls.map(nameOf).join(' and ')} both extend ${port}, `
-      + 'and nothing says which one answers it. Which realization a deployment uses is '
-      + `not a fact about the code — state it: ports: { ${port}: '${nameOf(impls[0]!)}' } `
-      + 'in fougere.config.ts.',
-    );
+    refused.push({
+      severity: 'blocking',
+      code: 'port-implemented-twice',
+      filePath: impls[0]!.filePath,
+      subject: port,
+      message: `${impls.map(nameOf).join(' and ')} both extend ${port}, and nothing says which one `
+        + 'answers it. Which realization a deployment uses is not a fact about the code — state it: '
+        + `ports: { ${port}: '${nameOf(impls[0]!)}' } in fougere.config.ts.`,
+    });
+
+    return [...wrappers, ...impls];
   }
 
   if (wrappers.length > 1) {
     // Same refusal one layer out: two wrappers are an ORDER, and scan order is not one.
-    throw new Error(
-      `[ports] ${wrappers.map(nameOf).join(' and ')} both wrap ${port}, `
-      + 'and nothing says which stands in front. State the chain, outside in: '
-      + `ports: { ${port}: [${[...wrappers, ...impls].map((one) => `'${nameOf(one)}'`).join(', ')}] } `
-      + 'in fougere.config.ts.',
-    );
+    refused.push({
+      severity: 'blocking',
+      code: 'port-wrapped-twice',
+      filePath: wrappers[0]!.filePath,
+      subject: port,
+      message: `${wrappers.map(nameOf).join(' and ')} both wrap ${port}, and nothing says which `
+        + 'stands in front. State the chain, outside in: '
+        + `ports: { ${port}: [${[...wrappers, ...impls].map((one) => `'${nameOf(one)}'`).join(', ')}] } `
+        + 'in fougere.config.ts.',
+    });
   }
 
   return [...wrappers, ...impls];

package/src/boot/relations.ts

@@ -0,0 +1,172 @@
+/** Who holds a `ref()`: the source it lives in, this process, or nobody. */
+import { lowerFirst, Role, Shapes, type SchemaView } from '@fougere/schema';
+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';
+
+/**
+ * Does a foreign key hold this reference? Both sides in ONE source that keeps relations — two
+ * databases share no constraint, and a frond behind `remotes:` registers no storage here at
+ * all. So the PAIR decides, never the engine.
+ *
+ * And the pair is not enough: an engine's cascade does not pass through the guard, so a hop it
+ * owns above a hop it does not would take rows out with nothing left to release THEIR rows. One
+ * unkeyed hop anywhere below and the guard takes the whole tree — the engine's own cascade then
+ * finds nothing left to do, since the guard walks deepest first and the row goes last.
+ */
+function keyed(namer: string, target: string, hosting: Hosting, seen = new Set<string>()): boolean {
+  const pair = hosting.hostedHere(namer)
+    && hosting.hostedHere(target)
+    && hosting.sourceOf(namer) === hosting.sourceOf(target)
+    && hosting.enforces(hosting.sourceOf(namer), 'relation');
+  if (!pair || seen.has(namer)) return pair;
+  seen.add(namer);
+
+  return referencesTo(namer, hosting).every(({ entity }) => keyed(entity, namer, hosting, seen));
+}
+
+/** Every field of every entity that names `target` — read over the whole app, both ways need it. */
+function referencesTo(target: string, hosting: Hosting): { entity: string; field: string; role: Role }[] {
+  const found: { entity: string; field: string; role: Role }[] = [];
+
+  for (const [entity, schema] of hosting.entities()) {
+    for (const [field, declared] of Object.entries(schema.getFields())) {
+      const role = Role.of(declared);
+      if (role.isReference && role.target?.name && lowerFirst(role.target.name) === target) {
+        found.push({ entity, field, role });
+      }
+    }
+  }
+
+  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.
+ *
+ * Documented: [entities](https://fougere.dev/docs/schema/entities).
+ */
+export function heldBy(entity: SchemaView, name: string, hosting: Hosting): RelationCheck[] {
+  const checks: RelationCheck[] = [];
+
+  for (const [field, declared] of Object.entries(entity.getFields())) {
+    const role = Role.of(declared);
+    if (!role.isReference || !role.target?.name) continue;
+
+    const target = lowerFirst(role.target.name);
+    if (keyed(name, target, hosting)) continue;
+
+    checks.push({
+      field,
+      target,
+      missing: async (keys) => {
+        const storage = hosting.storageOf(target) as ByKeys | undefined;
+        // 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) ?? [];
+        const found = await storage.findByKeys(keys.map(String));
+
+        return keys.filter((key) => !found.has(String(key)));
+      },
+    });
+  }
+
+  return checks;
+}
+
+/**
+ * The rows that name this entity's, and what becomes of them — the dual of `heldBy`.
+ *
+ * Read over EVERY entity of the app, because a namer is declared wherever its own frond is,
+ * and the target learns of it from nowhere else. What a key already holds is left out: the
+ * engine answers it at the rows, inside the delete's own transaction.
+ *
+ * Documented: [entities](https://fougere.dev/docs/schema/entities).
+ */
+export function dependentsOf(target: string, hosting: Hosting): Dependent[] {
+  return referencesTo(target, hosting)
+    .filter(({ entity }) => !keyed(entity, target, hosting))
+    .map(({ entity, field, role }) => ({ entity, field, onDelete: role.onDelete ?? 'restrict' }));
+}
+
+/**
+ * `set null` on a field that may not hold one — refused where the FIELD is, not in `ref()`.
+ *
+ * `optional()` wraps a `ref()` and is applied after it, so only the field the entity ended up
+ * declaring knows whether null is admitted. Asked here rather than at the target, because the
+ * declaration is the namer's and so is the fix.
+ */
+export function refuseUnwritableNull(entity: SchemaView, name: string, filePath: string): Diagnostic[] {
+  const refused: Diagnostic[] = [];
+
+  for (const [field, declared] of Object.entries(entity.getFields())) {
+    if (Role.of(declared).onDelete !== 'set null' || Shapes.isNullable(declared.shape)) continue;
+    refused.push({
+      severity: 'blocking',
+      code: 'on-delete-null-refused',
+      filePath,
+      subject: `${name}.${field}`,
+      message: `${name}.${field} states onDelete 'set null', and the field admits no null — so the `
+        + 'row could neither be emptied nor kept. Wrap it in `optional()`, or state `cascade` '
+        + 'to take the row out with its target.',
+    });
+  }
+
+  return refused;
+}
+
+/** The checks nothing in this process can answer — asked once every frond has registered. */
+export function unheldAmong(checks: readonly RelationCheck[], hosting: Hosting): string[] {
+  return checks
+    .filter((check) => hosting.storageOf(check.target) === undefined)
+    .map((check) => `${check.field} → ${check.target}`);
+}
+
+/**
+ * What a release asks the boot, built once per app — the same `Hosting` the guard reads.
+ *
+ * `dependentsOf` is answered per call rather than cached: a frond installed after this one
+ * brings rows that name an entity already registered, and a table taken at boot would miss
+ * exactly the crossings this exists for.
+ */
+export function releasing(hosting: Hosting): Releasing {
+  return {
+    dependentsOf: (entity) => dependentsOf(entity, hosting),
+    rowsOf: (entity) => hosting.storageOf(entity) as Rows | undefined,
+    schemaOf: (entity) => hosting.entities().get(entity),
+    peers: () => hosting.peers(),
+    journal: (entity) => hosting.journal(entity),
+  };
+}
+
+/**
+ * A release this process can START and cannot FINISH.
+ *
+ * Read from what is HERE and never asked of anyone: an entity states `cascade` or `set null`,
+ * and nothing registered a journal — both facts are local, so the line is too. The same shape
+ * as `unique declared, and the source does not enforce it`, one rung up: what is declared, and
+ * what this process cannot keep.
+ *
+ * Silent when a key holds every hop: the engine carries those out in one statement, and there
+ * is no half-done state for anybody to finish.
+ */
+export function unfinishable(hosting: Hosting): string[] {
+  if (hosting.journal('') !== undefined) return [];
+
+  const found: string[] = [];
+  for (const [entity] of hosting.entities()) {
+    for (const dependent of dependentsOf(entity, hosting)) {
+      if (dependent.onDelete === 'restrict') continue;
+      found.push(`${dependent.entity}.${dependent.field} → ${entity} (${dependent.onDelete})`);
+    }
+  }
+
+  return found;
+}

package/src/boot/remote.ts

@@ -3,11 +3,16 @@
  *
  * Documented: [the gradient](https://fougere.dev/docs/infra/gradient).
  */
-import type { FrondCall, Transport } from '../wire/call.js';
-import { assertIdentityCard, RPC_ENTITY } from '../wire/call.js';
-import { runMiddlewares, type AppMiddleware, type OperationContext } from '../wire/middleware.js';
-import { type InvocationContext, Invocation } from '../wire/Invocation.js';
-import { FougereError, ErrorCode } from '../wire/errors.js';
+import type { FrondCall } from '../wire/FrondCall.js';
+import type { Transport } from '../wire/Transport.js';
+import { RPC_ENTITY } from '../wire/RpcAnswer.js';
+import { assertIdentityCard } from '../wire/card/IdentityCard.js';
+import { runMiddlewares, type AppMiddleware } from '../wire/AppMiddleware.js';
+import { type OperationContext } from '../wire/OperationContext.js';
+import { Invocation } from '../wire/Invocation.js';
+import { type InvocationContext } from '../wire/InvocationContext.js';
+import { ErrorCode } from '../wire/ErrorCode.js';
+import { FougereError } from '../wire/FougereError.js';
 import { Card, type SchemaView, type SchemaDescriptor } from '@fougere/schema';
 import { dynamicOperations } from '../entry/facade.js';
 
@@ -35,7 +40,7 @@ export function createRemoteRouter(
   const pending = new Map(Object.entries(remotes));
   const transports = new Map<string, Transport>();
 
-  /** Which remote label claimed a door name — so a second claim can name the first. */
+  /** Which remote label claimed a facade name — so a second claim can name the first. */
   const claimedBy = new Map<string, string>();
 
   const discover = async (): Promise<void> => {
@@ -65,28 +70,28 @@ export function createRemoteRouter(
       const card = assertIdentityCard(answer, `Remote '${label}' (${url})`);
 
       for (const frond of card.fronds) {
-        // Doors only. A fact is not routable — nobody calls it, it arrives — so
-        // adding one here would answer a call with a transport to a door that
+        // Facades only. A fact is not routable — nobody calls it, it arrives — so
+        // adding one here would answer a call with a transport to a facade that
         // does not exist.
-        for (const door of frond.doors) {
-          const first = claimedBy.get(door.name);
+        for (const facade of frond.facades) {
+          const first = claimedBy.get(facade.name);
           /** Two remotes claiming one name is refused, not silently arbitrated. */
           if (first !== undefined && first !== label) {
             throw new FougereError({
               code: ErrorCode.INTERNAL_ERROR,
               message:
-                `Two remotes serve '${door.name}': '${first}' and '${label}'.\n`
+                `[claim] Two remotes serve '${facade.name}': '${first}' and '${label}'.\n`
                 + `  A call names an entity, not a frond, so nothing could choose between them.\n`
                 + `  - Keep one of the two out of \`remotes:\`, or\n`
                 + `  - expose one of them under a different entity name.`,
-              entity: door.name,
+              entity: facade.name,
             });
           }
-          claimedBy.set(door.name, label);
-          byEntity.set(door.name, {
+          claimedBy.set(facade.name, label);
+          byEntity.set(facade.name, {
             frond: frond.name,
             transport,
-            ...(door.schema ? { schema: Card.fromDescriptor(door.schema as SchemaDescriptor).toSchema() } : {}),
+            ...(facade.schema ? { schema: Card.fromDescriptor(facade.schema as SchemaDescriptor).toSchema() } : {}),
           });
         }
       }
@@ -101,13 +106,15 @@ export function createRemoteRouter(
       if (pending.size > 0) {
         throw new FougereError({
           code: ErrorCode.SERVICE_UNAVAILABLE,
-          message: `No reachable remote hosts '${entity}' — unreachable: ${[...pending.keys()].join(', ')}`,
+          message: `No reachable remote hosts '${entity}' — unreachable: ${[...pending.keys()].join(', ')}.\n`
+          + '  Named in `remotes:`, and did not answer.',
           entity,
         });
       }
       throw new FougereError({
         code: ErrorCode.NOT_FOUND,
-        message: `No declared remote hosts '${entity}'`,
+        message: `No declared remote hosts '${entity}'.\n`
+          + '  Nothing here serves it either — add its frond to `fronds:`/`scan:`, or name the frond that does in `remotes:`.',
         entity,
       });
     },

package/src/boot/runner.ts

@@ -1,6 +1,6 @@
 /** A Transport built from an app — the two ways a call enters this process. */
-import type { App } from './types.js';
-import type { Transport } from '../wire/call.js';
+import type { App } from './App.js';
+import type { Transport } from '../wire/Transport.js';
 import { createTransportEntry } from '../entry/transport.js';
 
 /** Build the local runner — the reference realization of Transport. */

package/src/boot/seed.ts

@@ -1,8 +1,10 @@
 import { Role } from '@fougere/schema';
-import { facadeKeyOf } from '../wire/call.js';
-import type { FrondDescriptor, SeedEntry, SeedFactory } from '../descriptor/frond.js';
-import type { App } from './types.js';
-import type { Extension } from './AppLifecycle.js';
+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';
+import type { App } from './App.js';
+import type { Extension } from './Extension.js';
 
 /** What the ordering satisfied, and what no order can. */
 export interface SeedOrder {
@@ -56,7 +58,7 @@ export function orderSeeds(fronds: FrondDescriptor[]): SeedOrder {
 }
 
 /** Where a seed writes, and what it may skip — resolved per entity. */
-interface SeedDoor {
+interface SeedFacade {
   list(): Promise<unknown[]>;
   write(item: unknown): Promise<unknown>;
 }
@@ -75,13 +77,13 @@ export async function runSeeds(
     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 door = doorFor(app, seed.entityName);
-    if (!door) {
+    const facade = facadeFor(app, seed.entityName);
+    if (!facade) {
       report(`  ${seed.entityName}: no handler façade nor storage — skipping seed`);
       continue;
     }
 
-    const existing = await door.list();
+    const existing = await facade.list();
     if (existing.length > 0) {
       report(`  ${seed.entityName}: skipped (${existing.length} exist)`);
       continue;
@@ -91,7 +93,7 @@ export async function runSeeds(
     // key is exactly what a seed gets wrong.
     for (const item of data) {
       try {
-        await door.write(item);
+        await facade.write(item);
       } catch (cause) {
         throw new Error(
           `Seed '${seed.entityName}' failed on ${JSON.stringify(item)}: ${(cause as Error)?.message ?? cause}`,
@@ -104,7 +106,7 @@ export async function runSeeds(
 }
 
 /** A seed is not a client. */
-function doorFor(app: App, entityName: string): SeedDoor | undefined {
+function facadeFor(app: App, entityName: string): SeedFacade | undefined {
   let handler: Record<string, Function> | undefined;
   try { handler = app.resolve<Record<string, Function>>(facadeKeyOf(entityName)); } catch {}
 

package/src/boot/statement-drift.ts

@@ -1,8 +1,9 @@
 /** Where a STATED contract and the signature it is about have stopped agreeing. */
-import type { FrondDescriptor, HandlerEntry } from '../descriptor/frond.js';
-import type { ScanDiagnostic } from '../scan.js';
+import type { FrondDescriptor } from '../descriptor/FrondDescriptor.js';
+import type { HandlerEntry } from '../descriptor/HandlerEntry.js';
+import type { Diagnostic } from '../diagnostic.js';
 import type { BindingPlan } from '../wire/binding.js';
-import type { Signature } from '../wire/signature.js';
+import type { Signature } from '../wire/Signature.js';
 
 /** The parameters a binding plan names, against the ones the method declares. */
 function namesDisagreeing(plan: BindingPlan, signature: Signature): string[] {
@@ -12,8 +13,8 @@ function namesDisagreeing(plan: BindingPlan, signature: Signature): string[] {
 }
 
 /** What a frond's stated contracts no longer match. */
-export function statementDrift(frond: FrondDescriptor, handler: HandlerEntry): ScanDiagnostic[] {
-  const found: ScanDiagnostic[] = [];
+export function statementDrift(frond: FrondDescriptor, handler: HandlerEntry): Diagnostic[] {
+  const found: Diagnostic[] = [];
 
   for (const [name, override] of Object.entries(frond.operationsOverrides ?? {})) {
     if (!override.binding) continue;