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

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/together.ts

@@ -11,6 +11,8 @@ import { type StorageFactory } from '../storage/StorageFactory.js';
 import type { Logger } from '../builtin/Logger.js';
 import type { ProviderEntry } from '../descriptor/ProviderEntry.js';
 import { StorageGuard } from '../dispatch/StorageGuard.js';
+import { heldBy, releasing } from './relations.js';
+import type { Hosting } from './Hosting.js';
 import { recording, unwind, type Undo } from './frame.js';
 import type { Diagnostic } from '../diagnostic.js';
 
@@ -26,6 +28,8 @@ export interface FrameWorld {
   /** Whether that source hands one out — asked before the frame is built, not at the call. */
   transacts?: (source: string) => boolean;
   transacted?: <R>(source: string, fn: (storageFactory: StorageFactory) => Promise<R>) => Promise<R>;
+  /** What a member's references ask before a write — the answer its frond's own storage gets. */
+  hosting: Hosting;
   log: Logger;
 }
 
@@ -180,7 +184,7 @@ export function registerFrames(
 
     const sources = new Set(members.entities.map((member) => world.sourceOf?.(member.name) ?? 'db'));
     const validator = (storage: Storage, name: string, schema: SchemaView) =>
-      new StorageGuard(schema.getFields(), name).guard(storage);
+      new StorageGuard(schema.getFields(), name, {}, heldBy(schema, name, world.hosting), releasing(world.hosting)).guard(storage);
 
     // One engine and a way into it: the engine gives the unwind AND the isolation. The
     // question goes to the source these members live in — a composition answering for the

package/src/contract.ts

@@ -18,6 +18,7 @@ export type { Comparison } from './storage/Comparison.js';
 export { toPublicError } from './wire/http-error.js';
 export { Invocation } from './wire/Invocation.js';
 export type { InvocationContext } from './wire/InvocationContext.js';
+export type { PartialInvocation } from './wire/PartialInvocation.js';
 export { Call } from './wire/Call.js';
 export { RouteAddress } from './wire/RouteAddress.js';
 export type { FrondCall } from './wire/FrondCall.js';

package/src/dispatch/Dependent.ts

@@ -0,0 +1,19 @@
+import type { OnDelete } from '@fougere/schema';
+
+/**
+ * A `ref()` read from the TARGET's side: rows that name it, and what becomes of them.
+ *
+ * The dual of `RelationCheck`, which reads the same declaration from the child's side to judge
+ * a write. Only what no foreign key holds reaches here — a key answers at the rows, inside the
+ * delete's own transaction, and nothing in this process would see it happen.
+ *
+ * Documented: [entities](https://fougere.dev/docs/schema/entities).
+ */
+export interface Dependent {
+  /** The entity whose rows name the target — `post`. */
+  entity: string;
+  /** The field carrying the key — `authorId`. */
+  field: string;
+  /** Unstated is `restrict`: what a foreign key does when nothing is said. */
+  onDelete: OnDelete;
+}

package/src/dispatch/Dispatcher.ts

@@ -7,6 +7,7 @@ import type { RoutePolicy } from './RoutePolicy.js';
 import { RouteRegistry } from './RouteRegistry.js';
 import { routeNotFound, servedOperations } from './routeNotFound.js';
 import type { InFlight } from './InFlight.js';
+import type { Journal } from './Journal.js';
 
 /** Resolves and executes every call through the same transverse lifecycle. */
 export class Dispatcher implements DispatchPort {
@@ -15,22 +16,57 @@ export class Dispatcher implements DispatchPort {
     private readonly inFlight: InFlight,
     private readonly lifecycle = new DispatchLifecycle(),
     private readonly policy?: RoutePolicy,
+    private readonly journalOf?: () => Journal | undefined,
   ) {}
 
+  /** The route that answers this address, or the refusal naming what is served instead. */
+  private async routeFor(call: Call): Promise<Route> {
+    const known = this.routes.find(call.address);
+    const resolved = known ?? await this.routes.resolve(call.address);
+    const route = resolved && (!this.policy || this.policy.accepts(resolved)) ? resolved : undefined;
+    if (!route) {
+      throw this.policy?.notFound?.(call, this.routes.routes())
+        ?? routeNotFound(call, servedOperations(call, this.routes.routes(), this.policy));
+    }
+
+    return route;
+  }
+
+  /**
+   * A kept call publishes no dispatch event and enters no flight: it has not been answered,
+   * and counting it here would report one call spanning the days until its hour.
+   *
+   * Its address is resolved all the same. What is kept is made hours later, by then against
+   * whatever the app still serves — so an address nothing answers is refused to the caller who
+   * can still fix it, rather than to a beat nobody is watching.
+   */
+  private async keep(call: Call, runAt: number): Promise<undefined> {
+    await this.routeFor(call);
+
+    const journal = this.journalOf?.();
+    if (!journal) {
+      throw new Error(
+        `${call.address.toString()} asks to run at ${new Date(runAt).toISOString()}, and nothing keeps it.`
+        + ' Install a package answering Journal — @fougere/workflow.',
+      );
+    }
+
+    await journal.keep(call, runAt);
+
+    return undefined;
+  }
+
   async dispatch(call: Call): Promise<unknown> {
+    const { runAt } = call.invocation;
+    if (runAt !== undefined) return this.keep(call, runAt);
+
     let route: Route | undefined;
     let release: (() => void) | undefined;
     this.lifecycle.publish(DispatchEvent.received(call));
 
     try {
       release = this.inFlight.enter(call.address.entity, call.address.operation);
-      const known = this.routes.find(call.address);
-      const resolved = known ?? await this.routes.resolve(call.address);
-      route = resolved && (!this.policy || this.policy.accepts(resolved)) ? resolved : undefined;
-      if (!route) {
-        throw this.policy?.notFound?.(call, this.routes.routes())
-          ?? routeNotFound(call, servedOperations(call, this.routes.routes(), this.policy));
-      }
+      route = await this.routeFor(call);
 
       this.lifecycle.publish(DispatchEvent.resolved(call, route.kind));
       const result = await route.execute(call);

package/src/dispatch/Journal.ts

@@ -0,0 +1,26 @@
+import type { Call } from '../wire/Call.js';
+
+/**
+ * What writes a release down while it happens, when a package provides one.
+ *
+ * Core does the same hops in the same order either way — children before their parent, so an
+ * interruption leaves fewer children and never an orphan. What a journal adds is that somebody
+ * can finish what a stopped process started: the row says a release began, and a sweep redoes
+ * it. Redoing is safe because every hop already is — a row taken out twice is taken out once.
+ *
+ * What writes a release down writes none of its own: the boot leaves out the entities of the
+ * fronds an extension BROUGHT, so keeping the row that says a release began does not begin one.
+ * Read from what was brought rather than written down, the way `CARRIES_LINE` is.
+ *
+ * Documented: [entities](https://fougere.dev/docs/schema/entities).
+ */
+export interface Journal {
+  /** Hold this call until `runAt`, so a sweep dispatches it then and nobody waits for it now. */
+  keep(call: Call, runAt: number): Promise<void>;
+  /** Take this release on, or say another process is already driving it. */
+  open(entity: string, key: string): Promise<'taken' | 'busy'>;
+  close(entity: string, key: string): Promise<void>;
+}
+
+/** The container key a package registers its journal under. */
+export const JOURNAL = 'Journal';

package/src/dispatch/RelationCheck.ts

@@ -0,0 +1,21 @@
+/**
+ * A `ref()` whose target the source does not hold, so the guard reads it before the write.
+ *
+ * The pair decides, never the engine: SQL keeps a foreign key over rows it can see, and a
+ * target in another source gets a column and nothing else. The boot builds one of these for
+ * each reference that falls outside its own source, and none for the rest — a co-located
+ * relation costs nothing here, because the key already refuses the same row.
+ *
+ * Documented: [entities](https://fougere.dev/docs/schema/entities).
+ */
+export interface RelationCheck {
+  /** The field carrying the key — `authorId`. */
+  field: string;
+  /** What it points at, as the boot files it — `user`. */
+  target: string;
+  /**
+   * Which of these keys no row answers. Takes a set so a page costs one read, and so the
+   * single-row case is the same call with one member.
+   */
+  missing(keys: readonly unknown[]): Promise<readonly unknown[]>;
+}

package/src/dispatch/Release.ts

@@ -0,0 +1,156 @@
+/** What a delete does to the rows that name it, when no foreign key does it instead. */
+import { FieldSet, type SchemaView } from '@fougere/schema';
+import type { Dependent } from './Dependent.js';
+import type { Journal } from './Journal.js';
+import { ErrorCode } from '../wire/ErrorCode.js';
+import { FougereError } from '../wire/FougereError.js';
+
+/** The gestures a release reaches a dependent's rows through. */
+export interface Rows {
+  findAllByKeys(field: string, keys: readonly string[]): Promise<Map<string, Record<string, unknown>[]>>;
+  update(id: string, patch: Record<string, unknown>): Promise<unknown>;
+  delete(id: string): Promise<boolean>;
+}
+
+/** What the guard hands a release: who depends on an entity, and how to reach their rows. */
+export interface Releasing {
+  dependentsOf(entity: string): readonly Dependent[];
+  rowsOf(entity: string): Rows | undefined;
+  schemaOf(entity: string): SchemaView | undefined;
+  /** Written down while it happens, when a package provides one — absent is the plain walk. */
+  journal(entity: string): Journal | undefined;
+  /** Every declared remote — each one walks its own tree, and is alone able to. */
+  peers(): readonly { release(entity: string, key: unknown, visited: readonly string[]): Promise<void> }[];
+}
+
+/**
+ * The rows that name a key, taken out or emptied, deepest FIRST.
+ *
+ * Order is the whole guarantee: a child never outlives its parent, so an interruption leaves
+ * fewer children and never an orphan. That is what lets a release cross a process without a
+ * two-phase commit — and why nothing here needs to be undone, only finished.
+ *
+ * A row already visited is not visited again, which is what ends a cycle: `Category.parentId`
+ * pointing at its own entity walks down and stops when a key repeats.
+ *
+ * Documented: [entities](https://fougere.dev/docs/schema/entities).
+ */
+export async function release(
+  entity: string,
+  key: unknown,
+  world: Releasing,
+  visited: readonly string[] = [],
+  row?: () => Promise<unknown>,
+): Promise<void> {
+  const mark = `${entity}#${String(key)}`;
+  // Already on the trail means SOMEONE upstream is asking every process about this row, so
+  // asking again would be the bounce two processes declaring each other would never end. The
+  // local walk still runs: being asked is exactly the point, and only this process can do it.
+  const asked = visited.includes(mark);
+  const trail = asked ? visited : [...visited, mark];
+
+  // Written down before the first hop, so a process that stops mid-way leaves a row saying so.
+  // Absent, the hops are the same and nothing finishes them.
+  const journal = world.journal(entity);
+  if (journal && await journal.open(entity, String(key)) === 'busy') return;
+
+  // Every declared remote, and every one of them: a frond behind `remotes:` may have no sources
+  // here, so this process cannot see that its rows name ours — only that process can.
+  if (!asked) for (const peer of world.peers()) await peer.release(entity, key, trail);
+
+  try {
+    await walk(entity, [key], world, new Set([mark]), trail);
+  } catch (refusal) {
+    // A refusal is an outcome, not an interruption: the framework decided, and redoing it
+    // would only decide again — a run kept open for one would be swept forever. Anything
+    // else stopped us mid-tree, and THAT is what a run is for.
+    if (refusal instanceof FougereError) await journal?.close(entity, String(key));
+    throw refusal;
+  }
+
+  // The row itself, LAST — handed in by whoever owns the gesture, so a run covers the whole
+  // thing rather than stopping one statement short of it. Whatever the row answers, the
+  // release did its part: what depends on this one is dealt with, and nothing is left to redo.
+  try {
+    await row?.();
+  } finally {
+    await journal?.close(entity, String(key));
+  }
+}
+
+async function walk(
+  entity: string,
+  keys: readonly unknown[],
+  world: Releasing,
+  seen: Set<string>,
+  trail: readonly string[],
+): Promise<void> {
+  const dependents = world.dependentsOf(entity);
+  // Every refusal of this level BEFORE any of its rows move: two fields of one entity are two
+  // dependents, and declaration order would otherwise let a cascade beside a `restrict` win.
+  // Depth needs no such pass — a level acts only once the level below it came back.
+  for (const dependent of dependents.filter((one) => one.onDelete === 'restrict')) {
+    const rows = world.rowsOf(dependent.entity);
+    if (!rows) continue;
+    const found = [...(await rows.findAllByKeys(dependent.field, keys.map(String))).values()].flat();
+    if (found.length === 0) continue;
+
+    throw new FougereError({
+      code: ErrorCode.CONFLICT,
+      message: `${dependent.entity}.${dependent.field} holds ${found.length} row(s) naming this one, `
+        + `and states onDelete 'restrict' — take them out first, or declare what should happen.`,
+      entity,
+      operation: 'delete',
+    });
+  }
+
+  for (const dependent of dependents.filter((one) => one.onDelete !== 'restrict')) {
+    const rows = world.rowsOf(dependent.entity);
+    // Nothing here holds those rows. The process that does answers the same two readings core
+    // serves everywhere, so the ask crosses and the work happens on ITS side of the wire —
+    // which is what keeps the declaration identical whatever the topology.
+    // Nothing here holds those rows: every declared remote is asked about THIS level, and the
+    // one that holds them walks its own tree from there. The trail grows by one mark per level,
+    // so a deeper ask is never mistaken for the bounce of a shallower one.
+    if (!rows) {
+      for (const key of keys) {
+        // A level already on the trail is one somebody is asking every process about, so
+        // asking again is the bounce — the same reason `release` reads it before crossing.
+        if (trail.includes(`${entity}#${String(key)}`)) continue;
+        for (const peer of world.peers()) await peer.release(entity, key, trail);
+      }
+      continue;
+    }
+
+    const naming = await rows.findAllByKeys(dependent.field, keys.map(String));
+    const found = [...naming.values()].flat();
+    if (found.length === 0) continue;
+
+    if (dependent.onDelete === 'set null') {
+      const primary = keyOf(world, dependent.entity);
+      for (const row of found) await rows.update(String(row[primary]), { [dependent.field]: null });
+      continue;
+    }
+
+    const primary = keyOf(world, dependent.entity);
+    const below = found.map((row) => row[primary]).filter((id) => !taken(seen, dependent.entity, id));
+    // Deepest first: what names THESE rows goes before they do, all the way down.
+    await walk(dependent.entity, below, world, seen, trail);
+    for (const id of below) await rows.delete(String(id));
+  }
+}
+
+/** True once, and remembers — a key already on the path is what ends a cycle. */
+function taken(seen: Set<string>, entity: string, key: unknown): boolean {
+  const mark = `${entity}#${String(key)}`;
+  if (seen.has(mark)) return true;
+  seen.add(mark);
+
+  return false;
+}
+
+function keyOf(world: Releasing, entity: string): string {
+  const schema = world.schemaOf(entity);
+
+  return (schema && FieldSet.of(schema.getFields()).primary) ?? 'id';
+}

package/src/dispatch/StorageGuard.ts

@@ -4,6 +4,8 @@ import { assertListOptions } from '../storage/Storage.js';
 import { ErrorCode } from '../wire/ErrorCode.js';
 import { FougereError } from '../wire/FougereError.js';
 import type { GuardReport } from './GuardReport.js';
+import type { RelationCheck } from './RelationCheck.js';
+import { release, type Releasing } from './Release.js';
 
 /** The gestures this guard grafts onto. */
 interface Writer {
@@ -11,6 +13,7 @@ interface Writer {
   update(...args: [unknown, Record<string, unknown>, ...unknown[]]): Promise<unknown>;
   upsert?(...args: [Record<string, unknown>, ...unknown[]]): Promise<unknown>;
   upsertAll?(...args: [readonly Record<string, unknown>[], ...unknown[]]): Promise<unknown>;
+  delete?(id: string): Promise<boolean>;
   list?(...args: unknown[]): unknown;
 }
 
@@ -23,6 +26,8 @@ export class StorageGuard {
     private readonly fields: Fields,
     private readonly entity: string,
     private readonly report: GuardReport = {},
+    private readonly relations: readonly RelationCheck[] = [],
+    private readonly releasing?: Releasing,
   ) {}
 
   guard<T extends object>(storage: T): T {
@@ -32,13 +37,29 @@ export class StorageGuard {
     const validation = this;
     const guarded = Object.create(storage) as T & Writer;
 
+    const remove = writer.delete;
+    if (typeof remove === 'function' && validation.releasing) {
+      // What names this row goes first, and this row last: an interruption then leaves fewer
+      // children rather than an orphan. A key holds the rest, at the rows, in one statement.
+      guarded.delete = async function (id) {
+        let gone = false;
+        await release(validation.entity, id, validation.releasing!, [], async () => {
+          gone = await remove.call(this, id);
+        });
+
+        return gone;
+      };
+    }
+
     guarded.create = async function (...args) {
       args[0] = validation.validated(args[0], 'create');
+      await validation.targetsOf([args[0]], 'create');
       return writer.create.apply(this, args);
     };
 
     guarded.update = async function (...args) {
       args[1] = validation.validated(args[1], 'update');
+      await validation.targetsOf([args[1]], 'update');
       return writer.update.apply(this, args);
     };
 
@@ -46,6 +67,7 @@ export class StorageGuard {
     if (typeof upsert === 'function') {
       guarded.upsert = async function (...args) {
         args[0] = validation.validated(args[0], 'upsert');
+        await validation.targetsOf([args[0]], 'upsert');
         return upsert.apply(this, args);
       };
     }
@@ -56,6 +78,9 @@ export class StorageGuard {
       // the caller asked for as one, and the refusal is readable from the input alone.
       guarded.upsertAll = async function (...args) {
         args[0] = args[0].map((row, index) => validation.validated(row, 'upsertAll', index));
+        // The keys of the whole page in one read per relation, for the reason above: a page
+        // refused on its fourth row has already written three.
+        await validation.targetsOf(args[0], 'upsertAll');
         return upsertAll.apply(this, args);
       };
     }
@@ -202,6 +227,43 @@ export class StorageGuard {
 
     return parsed as T;
   }
+
+  /**
+   * The rows a `ref()` points at, read before the write lands.
+   *
+   * Only the references the boot could not leave to a foreign key reach here — a target in
+   * the same source is already refused by the key, at the rows, which this cannot be: the
+   * target may be deleted between the read and the write. It catches what a key catches in
+   * practice, which is a key that was never right: a row copied from another environment,
+   * an author deleted months ago, an id from a test.
+   *
+   * A patch that does not carry the field says nothing about it, so it is skipped rather
+   * than read as `null`.
+   */
+  private async targetsOf(rows: readonly Record<string, unknown>[], operation: string): Promise<void> {
+    if (this.relations.length === 0) return;
+
+    const refused = await Promise.all(this.relations.map(async (relation) => {
+      const keys = [...new Set(
+        rows.map((row) => row[relation.field]).filter((key) => key !== undefined && key !== null),
+      )];
+      if (keys.length === 0) return [];
+      const missing = await relation.missing(keys);
+
+      return missing.map((key) => `${relation.field} ${JSON.stringify(key)} — no ${relation.target} holds it`);
+    }));
+
+    const errors = refused.flat();
+    if (errors.length === 0) return;
+
+    throw new FougereError({
+      code: ErrorCode.VALIDATION_FAILED,
+      message: `Refused on the way out — ${errors.join(', ')}`,
+      entity: this.entity,
+      operation,
+      details: errors,
+    });
+  }
 }
 
 const unwrap = (one: { value: unknown } | { error: string }): unknown =>

package/src/index.ts

@@ -33,10 +33,15 @@ export { Repository, type RepositoryConstructor } from './prefab/RepositoryConst
 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 facade.
 export { DispatchEvent } from './dispatch/DispatchEvent.js';

package/src/wire/Emit.ts

@@ -1,4 +1,7 @@
 import { lowerFirst } from '@fougere/schema';
+import { computeBindingPlan } from './binding.js';
+import type { OperationContract } from './OperationContract.js';
+import type { OperationsMap } from './OperationsMap.js';
 
 /**
  * What an emitter injects. PARTIAL, because announcing is what REALIZES the fact's
@@ -52,6 +55,26 @@ export function factsAwaitedBy(handlers: readonly { deps: readonly string[] }[])
   return factsIn(handlers, factOfAwaitKey);
 }
 
+/**
+ * What a set of handlers LISTENS to — the dual of what it announces, and the half no
+ * dependency spells: accepting a `Fact<T>` IS the subscription, so it is read from the
+ * binding plan, where `Emissions` reads it too.
+ */
+export function factsListenedTo(handlers: readonly { operations: OperationsMap }[]): string[] {
+  const taken = (contract: OperationContract): string[] => {
+    const plan = contract.binding
+      ?? (contract.signature ? computeBindingPlan(contract.signature.params, NO_COLLECTOR) : []);
+
+    return plan.flatMap((bound) =>
+      bound.source.kind === 'fact' || bound.source.kind === 'pipe' ? [bound.source.factName] : []);
+  };
+
+  return [...new Set(handlers.flatMap((handler) => [...handler.operations.values()].flatMap(taken)))];
+}
+
+/** `Fact` and `Pipe` name themselves, and the plan reads them before it reads a collector. */
+const NO_COLLECTOR = new Set<string>();
+
 function factsIn(
   handlers: readonly { deps: readonly string[] }[],
   behindKey: (key: string) => string | undefined,