@fougere/core 0.2.0-alpha.2 → 0.4.0-alpha.0

package/src/boot/frame.ts

@@ -0,0 +1,210 @@
+/**
+ * The compensated realization of a frame — what `Together` becomes when its members do
+ * not share an engine.
+ *
+ * A transaction is the engine's own answer and costs nothing to use: the members are
+ * rebuilt over it and the engine gives both the unwind and the isolation. Across engines
+ * there is no such thing, so the unwind is built here: every write through the port is
+ * recorded with the image that preceded it, and a failure replays the inverses in reverse
+ * order.
+ *
+ * **It gives all-or-nothing, never isolation.** Between two writes a reader sees the half,
+ * and nothing here can hide it — that is the whole difference between the two realizations
+ * and the reason the boot says which one it built.
+ *
+ * The port is thirteen known gestures, which is what makes the inverse derivable rather
+ * than declared: a saga asks its author for an `undo` per step because its steps are
+ * arbitrary code. Here they are not.
+ */
+import { FieldGroup, FieldSet, Unique, type Fields } from '@fougere/schema';
+import { dequal } from 'dequal';
+import type { Logger } from '../builtins/logger.js';
+
+/** One write that landed, and how to take it back. */
+export interface Undo {
+  /** What it will undo, in the sentence a failure report needs. */
+  what: string;
+  run(): Promise<void>;
+}
+
+/**
+ * The subset of the port a frame has to watch: every gesture that writes, plus the reads
+ * that take one back.
+ *
+ * Not `StorageGuard`'s `Writer`, which is `create` and `update` — all a judge needs. Undoing
+ * needs more: the deletes, and the reads that fetch the image to put back.
+ */
+interface Undoable {
+  create(input: Record<string, unknown>, ...rest: unknown[]): Promise<Record<string, unknown>>;
+  update(id: string, patch: Record<string, unknown>, ...rest: unknown[]): Promise<Record<string, unknown>>;
+  delete(id: string): Promise<boolean>;
+  findById(id: string, ...rest: unknown[]): Promise<Record<string, unknown> | undefined>;
+  findByKeys(ids: readonly string[], ...rest: unknown[]): Promise<Map<string, Record<string, unknown>>>;
+  upsert?(input: Record<string, unknown>, ...rest: unknown[]): Promise<Record<string, unknown>>;
+  upsertAll?(inputs: readonly Record<string, unknown>[], ...rest: unknown[]): Promise<number>;
+}
+
+const pick = (row: Record<string, unknown>, keys: readonly string[]): Record<string, unknown> =>
+  Object.fromEntries(keys.map((key) => [key, row[key]]));
+
+/**
+ * Whether an upsert's conflict can be something other than the primary key.
+ *
+ * The inverse of an upsert is derivable exactly when the conflict is the primary key: read
+ * the rows by key first, then restore the ones that were there and delete the ones that
+ * were not. `SqlEntityOrm` spells `onConflict(pk)` on SQLite and Postgres, so that holds —
+ * but MySQL's `onDuplicateKeyUpdate` fires on ANY unique constraint, and a row that
+ * conflicts on a unique email while carrying a different key would be restored under a key
+ * the write never touched.
+ *
+ * So the question is asked of the DECLARATION, not of the engine: an entity whose only
+ * unique constraint is its key upserts unambiguously everywhere. This file knows no dialect
+ * and should not learn one.
+ */
+function mayConflictElsewhere(fields: Fields): boolean {
+  const groups = FieldGroup.groupsOf(fields, Unique);
+  if (groups.length > 0) return true;
+  // A sole `unique()` carries a one-member group, which `groupsOf` filters out.
+  return Object.values(fields).some((field) => FieldGroup.on(field, Unique).length > 0);
+}
+
+/** Refused where it is used, naming the group that makes the inverse ambiguous. */
+function refuseAmbiguousUpsert(entity: string, gesture: string): never {
+  throw new Error(
+    `${entity}.${gesture}() cannot be unwound: ${entity} declares a unique constraint besides ` +
+    `its key, so an upsert may overwrite a row this frame never read — and there is no ` +
+    `transaction here to take it back. Put the members in one source, or write ` +
+    `create/update explicitly.`,
+  );
+}
+
+/**
+ * The ORM a member is handed inside a compensated frame: the same port, writing the same
+ * rows, leaving an inverse behind each time.
+ *
+ * `Object.create` for the same reason `StorageGuard` uses it — the ORM keeps every gesture
+ * it had, including the ones this knows nothing about.
+ */
+export function recording<T extends object>(orm: T, entity: string, fields: Fields, journal: Undo[]): T {
+  const base = orm as unknown as Undoable;
+  if (typeof base.create !== 'function' || typeof base.update !== 'function') return orm;
+
+  const key = FieldSet.of(fields).primary;
+  if (!key) {
+    throw new Error(
+      `${entity} declares no primary field, so a write to it cannot be taken back by ` +
+      `identity — and this frame has no transaction to do it instead.`,
+    );
+  }
+
+  const recorded = Object.create(orm) as T & Undoable;
+
+  recorded.create = async function (...args) {
+    const row = await base.create.apply(this, args);
+    const id = String(row[key]);
+    journal.push({ what: `create ${entity}#${id}`, run: () => base.delete.call(this, id).then(() => undefined) });
+    return row;
+  };
+
+  recorded.update = async function (...args) {
+    const [id, patch] = args;
+    const before = await base.findById.call(this, id);
+    const row = await base.update.apply(this, args);
+    if (!before) return row;
+
+    // Compare against what the WRITE produced, not against the patch: a `update: 'now'`
+    // field is stamped by the storage, so the patch is not what the row now holds.
+    const touched = Object.keys(patch);
+    const wrote = pick(row, touched);
+    journal.push({
+      what: `update ${entity}#${id} (${touched.join(', ')})`,
+      run: async () => {
+        const current = await base.findById.call(this, id);
+        if (!current) throw new Error(`${entity}#${id} is gone`);
+        const moved = touched.filter((field) => !dequal(current[field], wrote[field]));
+        if (moved.length > 0) {
+          throw new Error(`${entity}#${id} was changed by someone else since (${moved.join(', ')})`);
+        }
+        await base.update.call(this, id, pick(before, touched));
+      },
+    });
+    return row;
+  };
+
+  recorded.delete = async function (id) {
+    const before = await base.findById.call(this, id);
+    const removed = await base.delete.call(this, id);
+    if (removed && before) {
+      journal.push({ what: `delete ${entity}#${id}`, run: () => base.create.call(this, before).then(() => undefined) });
+    }
+    return removed;
+  };
+
+  // An upsert says neither what it wrote over nor what it inserted, so the frame reads the
+  // keys first: what was there is restored, what was not is deleted. One extra query for
+  // the page, which is the same bargain `update` already makes for one row.
+  const undoUpsert = async function (this: unknown, rows: readonly Record<string, unknown>[]): Promise<Undo> {
+    const ids = rows.map((row) => String(row[key]));
+    const before = await base.findByKeys.call(this, ids);
+    return {
+      what: `upsert ${entity} (${ids.length} row(s))`,
+      run: async () => {
+        for (const id of ids) {
+          const was = before.get(id);
+          if (was) await base.update.call(this, id, was);
+          else await base.delete.call(this, id);
+        }
+      },
+    };
+  };
+
+  if (typeof base.upsert === 'function') {
+    (recorded as unknown as Undoable).upsert = async function (input, ...rest) {
+      if (mayConflictElsewhere(fields)) refuseAmbiguousUpsert(entity, 'upsert');
+      const undo = await undoUpsert.call(this, [input]);
+      const row = await base.upsert!.call(this, input, ...rest);
+      journal.push(undo);
+      return row;
+    };
+  }
+
+  if (typeof base.upsertAll === 'function') {
+    (recorded as unknown as Undoable).upsertAll = async function (inputs, ...rest) {
+      if (mayConflictElsewhere(fields)) refuseAmbiguousUpsert(entity, 'upsertAll');
+      const undo = await undoUpsert.call(this, inputs);
+      const written = await base.upsertAll!.call(this, inputs, ...rest);
+      journal.push(undo);
+      return written;
+    };
+  }
+
+  return recorded;
+}
+
+/**
+ * Replay the inverses, most recent first, and report rather than pretend.
+ *
+ * Every one is attempted even after one fails: stopping at the first would leave writes
+ * standing that could have been taken back. What cannot be undone is named — the caller is
+ * about to tell a user their transfer failed, and "it failed and here is what is still in
+ * the database" is the only honest version of that sentence.
+ */
+export async function unwind(journal: readonly Undo[], cause: unknown, log: Logger): Promise<never> {
+  const stuck: string[] = [];
+  for (const undo of [...journal].reverse()) {
+    try {
+      await undo.run();
+    } catch (failure) {
+      stuck.push(`${undo.what} — ${(failure as Error).message}`);
+      log.error(`frame could not undo ${undo.what}`, failure);
+    }
+  }
+  if (stuck.length === 0) throw cause;
+
+  throw new Error(
+    `The frame failed and ${stuck.length} of ${journal.length} write(s) could not be taken back: ` +
+    `${stuck.join('; ')}. What remains is in the database. Original failure: ` +
+    `${(cause as Error)?.message ?? String(cause)}`,
+    { cause },
+  );
+}

package/src/boot/ownership.ts

@@ -0,0 +1,140 @@
+import { lowerFirst, type EntityConstructor } from '@fougere/schema';
+import type { FrondDescriptor, ProviderEntry } from '../scan/frond.js';
+import { targetOf } from '../prefab/prefab.js';
+import { ownedBy, repositoryKeyOf } from '../prefab/repository.js';
+import { ormKeyOf } from '../orm.js';
+
+/**
+ * Who owns an entity's storage.
+ *
+ * `Repository(Commande, Stock)` states it — an aggregate is the only thing that claims
+ * entities it is not named after, and the arity is what says so. A repository of ONE owns
+ * nothing: a boundary between one thing and nothing is not a boundary, and the judge is
+ * already on that entity's rows.
+ */
+export function ownersOf(providers: readonly ProviderEntry[]): Map<string, string> {
+  const owners = new Map<string, string>();
+  for (const provider of providers) {
+    const owned = ownedBy(provider.ctor);
+    if (owned.length < 2) continue;
+    for (const entity of owned) {
+      const name = lowerFirst((entity as { name: string }).name);
+      const first = owners.get(name);
+      if (first && first !== provider.ctor.name) {
+        // Refused rather than settled, for the reason `ports:` refuses two implementations
+        // and `remotes` two owners of an entity: whichever won would depend on scan order,
+        // and one of the two aggregates would be silently unenforced.
+        throw new Error(
+          `[aggregate] ${first} and ${provider.ctor.name} both own ${name}. `
+          + 'An entity has one owner: merge the two, or take it out of one of them.',
+        );
+      }
+      owners.set(name, provider.ctor.name);
+    }
+  }
+  return owners;
+}
+
+/**
+ * The entities a class was BUILT ON — what a prefab may legitimately be handed the storage
+ * of. Empty for a plain service, which is why one cannot ask for an ORM at all.
+ */
+function builtOn(ctor: unknown): string[] {
+  const owned = ownedBy(ctor);
+  if (owned.length > 0) return owned.map((e) => lowerFirst((e as { name: string }).name));
+  const target = targetOf(ctor) as { name?: string } | undefined;
+  return target?.name ? [lowerFirst(target.name)] : [];
+}
+
+/**
+ * `EntityOrm<E>` is not a word of the user's vocabulary — `<E>Repository` is the one way in.
+ *
+ * A door judges and projects; a HOLDER keeps the storage. So the rule is not about which
+ * directory a file sits in but about which of the two a class is: a handler, a presenter and
+ * a collector may never name an ORM, and a provider may name only the ORM of what its prefab
+ * was built on — which is `Repository` and `Mirror`, without either being named here.
+ *
+ * What it buys beyond one word instead of two: an entity that becomes owned later needs no
+ * call site to move, because none of them ever spelled the storage.
+ *
+ * Refused at boot rather than reported by `verify`, which nothing calls at startup.
+ */
+export function refuseOrmInUserCode(frond: FrondDescriptor, owners: Map<string, string>): void {
+  const doors = [
+    ...frond.handlers.map((h) => ({ ...h, kind: 'handler' })),
+    ...frond.presenters.map((p) => ({ ...p, kind: 'presenter' })),
+    ...frond.collectors.map((c) => ({ ...c, kind: 'collector' })),
+  ];
+  const holders = frond.providers.map((p) => ({ ...p, kind: 'provider' as const }));
+
+  for (const decl of [...doors, ...holders]) {
+    const allowed = decl.kind === 'provider' ? builtOn(decl.ctor) : [];
+    for (const dep of decl.deps) {
+      const entity = entityOfOrmKey(dep);
+      if (!entity) continue;
+
+      const owner = owners.get(entity);
+      if (owner && owner !== decl.ctor.name) {
+        throw new Error(
+          `[aggregate] ${decl.ctor.name} asks for ${dep}, and ${owner} owns ${entity}.\n`
+          + `  Nothing else reaches an owned entity's storage — name the operation on `
+          + `${owner} and ask for it:\n`
+          + `    constructor(private ${entity}: ${owner}) {}\n`
+          + `  ${decl.filePath}`,
+        );
+      }
+      if (allowed.includes(entity)) continue;
+
+      throw new Error(
+        `${decl.ctor.name} asks for ${dep}. Storage is reached through a repository, `
+        + `never through the port:\n`
+        + `    constructor(private ${entity}: ${repositoryKeyOf(entity)}) {}\n`
+        + `  It answers every gesture ${dep} does, whether or not anyone wrote the file — `
+        + `and the day ${entity} belongs to an aggregate, this line does not move.\n`
+        + `  ${decl.filePath}`,
+      );
+    }
+  }
+}
+
+/**
+ * An owned entity has no automatic CRUD — said at boot, not at the first request.
+ *
+ * `HandlerFacade.deps()` asks for `<E>Repository` when a handler inherits the five gestures
+ * and declares no constructor of its own, and an owned entity has no such key. That alone
+ * refuses — but LAZILY, at the first call, on the container's own sentence: measured, the app
+ * booted clean and answered every request with `'LedgerRepository' is not registered`. A
+ * receiver that starts and then rejects everything is found in production, which is the
+ * reason `serve()` checks its address at boot rather than per call.
+ *
+ * Recognized by FORM, like the façade recognizes it: a prototype carrying `list` and
+ * `findById` needs storage of its own, whether `Crud()` put them there or an author did.
+ */
+export function refuseCrudOnOwned(frond: FrondDescriptor, owners: Map<string, string>): void {
+  for (const handler of frond.handlers) {
+    const owner = owners.get(handler.address);
+    if (!owner || handler.deps.length > 0) continue;
+    const proto = (handler.ctor as { prototype?: Record<string, unknown> }).prototype;
+    if (typeof proto?.list !== 'function' || typeof proto?.findById !== 'function') continue;
+
+    throw new Error(
+      `[aggregate] ${handler.ctor.name} takes the five gestures on ${handler.address}, `
+      + `which ${owner} owns.\n`
+      + `  An owned entity has no automatic CRUD: nothing writes it but its owner, so there `
+      + `is no storage to hand this handler.\n`
+      + `  Name the operations on ${owner} and call them:\n`
+      + `    constructor(private ${handler.address}: ${owner}) {}\n`
+      + `  ${handler.filePath}`,
+    );
+  }
+}
+
+/** `'PostOrm'` → `'post'`, and nothing for a key that is not one. */
+function entityOfOrmKey(dep: string): string | undefined {
+  if (!dep.endsWith('Orm') || dep === 'Orm') return undefined;
+  const entity = lowerFirst(dep.slice(0, -'Orm'.length));
+  return ormKeyOf(entity) === dep ? entity : undefined;
+}
+
+/** Placeholder so the module's imports stay honest if a caller wants the entity list. */
+export type { EntityConstructor };

package/src/boot/ports.ts

@@ -0,0 +1,66 @@
+import type { ProviderEntry } from '../scan/frond.js';
+
+/**
+ * A port is a class something already answers under. Nothing declares one — the
+ * prototype chain states it, so `class StripePayment extends Payment` IS the whole
+ * registration, and so is `class MyLogger extends Logger` over a builtin.
+ *
+ * This is the fourth reading of the rule the other three already apply: the type
+ * names the SUBJECT (`EntityOrm<E>`, `Emit<F>`, `Facade<H>`) and the container
+ * holds the realization. Providers were the one case where the type named the
+ * realization instead, so `constructor(private payment: Payment)` resolved to the
+ * base class and a handler got an object whose method did not exist.
+ *
+ * Only the DIRECT base binds. A deeper chain binds each link to its own child, and
+ * a case that wants otherwise states it in `ports:` — which wins over all of this.
+ */
+export function portBindings(
+  providers: ProviderEntry[],
+  answers: (name: string) => boolean,
+  chosen: Record<string, string> | undefined,
+): 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 bound = new Map<string, ProviderEntry>();
+  for (const [port, impls] of candidates) {
+    const named = chosen?.[port];
+    if (named) {
+      const pick = impls.find((i) => i.ctor.name === named);
+      if (!pick) {
+        throw new Error(
+          `[ports] ${port}: '${named}' does not extend it. `
+          + `What does: ${impls.map((i) => i.ctor.name).join(', ')}.`,
+        );
+      }
+      bound.set(port, pick);
+      continue;
+    }
+    if (impls.length > 1) {
+      // 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((i) => i.ctor.name).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}: '${impls[0].ctor.name}' } `
+        + 'in fougere.config.ts.',
+      );
+    }
+    bound.set(port, impls[0]);
+  }
+  return bound;
+}

package/src/boot/remote.ts

@@ -0,0 +1,179 @@
+/**
+ * Remote façade — what resolve() falls back to.
+ *
+ * When a handler isn't hosted locally and remotes are declared, resolve()
+ * returns a façade-shaped stand-in: same call surface as a local facade,
+ * every operation executed through a Transport. Routing is lazy — on the
+ * first miss, each declared remote is asked what it hosts (rpc.discover)
+ * and the answer is cached. A remote that can't be reached stays pending
+ * and is retried on the next miss instead of being cached as absent.
+ */
+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 { EMPTY_INVOCATION, type InvocationContext } from '../wire/invocation.js';
+import { FougereError, ErrorCode } from '../wire/errors.js';
+import { Card, type SchemaView, type SchemaDescriptor } from '@fougere/schema';
+import { DynamicFacade } from '../entry/DynamicFacade.js';
+
+interface Route {
+  frond: string;
+  transport: Transport;
+  /**
+   * The entity's schema, rebuilt from the identity card — the same
+   * `SchemaConstructor` shape `entity({...})` produces, live validation
+   * included. Reconstructed once per entity, at discovery time.
+   *
+   * **Absent when the door stores nothing.** A handler may carry no entity, so the card
+   * publishes it with ops and no shape; there is nothing to rebuild and pretending
+   * otherwise would hand callers an empty schema that validates everything.
+   */
+  schema?: SchemaView;
+}
+
+export interface RemoteRouter {
+  route(entity: string): Promise<Route>;
+}
+
+export function createRemoteRouter(
+  remotes: Record<string, string>,
+  makeTransport: (url: string) => Transport,
+): RemoteRouter {
+  const byEntity = new Map<string, Route>();
+  // The remotes config key is a label for the address — the identity card is
+  // what decides which entities live behind it.
+  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. */
+  const claimedBy = new Map<string, string>();
+
+  const discover = async (): Promise<void> => {
+    // Asking is concurrent; INDEXING is not, and is done in the order `remotes` declares.
+    // Reading the cards inside the race made "which remote won" depend on who answered
+    // first, so the same two remotes could resolve differently between two runs.
+    const cards = await Promise.all(
+      [...pending].map(async ([label, url]) => {
+        const transport = transports.get(url) ?? makeTransport(url);
+        transports.set(url, transport);
+        try {
+          const answer = await transport({ entity: RPC_ENTITY, op: 'discover' }, EMPTY_INVOCATION);
+          // Judged below and not here: this catch means "unreachable, retry", and a
+          // refusal thrown inside it would be swallowed into another silent retry.
+          return { label, url, transport, answer };
+        } catch {
+          // Unreachable — stays pending, retried on the next miss.
+          return undefined;
+        }
+      }),
+    );
+
+    for (const answered of cards) {
+      if (!answered) continue;
+      const { label, url, transport, answer } = answered;
+      pending.delete(label);
+      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
+        // does not exist.
+        for (const door of frond.doors) {
+          const held = claimedBy.get(door.name);
+          /**
+           * Two remotes claiming one name is refused, not silently arbitrated.
+           *
+           * `byEntity` is keyed by the door name alone, so the second claim used to be
+           * dropped with `if (!byEntity.has(...))` — no warning, and the winner was
+           * whichever remote answered first. The local boot already refuses the same
+           * collision (`assertOneOwnerPerKey`) and it refused the OTHER duplicate: in
+           * process the last frond loaded won, here the first discovered did. One
+           * application, two topologies, two different handlers answering — which is
+           * precisely the gradient not holding.
+           *
+           * Refusing is the honest answer while a call names an entity and not a frond.
+           * `FrondCall` already carries an optional `frond`; the day it is required, this
+           * becomes a disambiguation instead of a refusal.
+           */
+          if (held !== undefined && held !== label) {
+            throw new FougereError({
+              code: ErrorCode.INTERNAL_ERROR,
+              message:
+                `Two remotes serve '${door.name}': '${held}' 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,
+            });
+          }
+          claimedBy.set(door.name, label);
+          byEntity.set(door.name, {
+            frond: frond.name,
+            transport,
+            ...(door.schema ? { schema: Card.fromDescriptor(door.schema as SchemaDescriptor).toSchema() } : {}),
+          });
+        }
+      }
+    }
+  };
+
+  return {
+    async route(entity) {
+      if (!byEntity.has(entity) && pending.size > 0) await discover();
+      const hit = byEntity.get(entity);
+      if (hit) return hit;
+      if (pending.size > 0) {
+        throw new FougereError({
+          code: ErrorCode.SERVICE_UNAVAILABLE,
+          message: `No reachable remote hosts '${entity}' — unreachable: ${[...pending.keys()].join(', ')}`,
+          entity,
+        });
+      }
+      throw new FougereError({
+        code: ErrorCode.NOT_FOUND,
+        message: `No declared remote hosts '${entity}'`,
+        entity,
+      });
+    },
+  };
+}
+
+type Facade = Record<string, (invocation?: InvocationContext) => Promise<unknown>>;
+
+/**
+ * Façade-shaped stand-in — the consumer can't tell it from a local facade.
+ *
+ * Every trap answers the same question, and that is the point: the runner asks
+ * `Object.hasOwn(facade, op)` before calling, so a proxy that only trapped `get`
+ * reported *no* operations and every split call came back `Unknown operation` —
+ * `get` said yes, `hasOwn` said no, and the runner believed `hasOwn`.
+ *
+ * The stand-in claims every legal op name because it cannot know better: routing is
+ * lazy on purpose (the card is fetched at the first miss), and the remote is the
+ * authority on its own surface anyway. An op it does not serve comes back as its
+ * NOT_FOUND — judged where it is owned, which is the same answer a local façade gives.
+ *
+ * It runs the app's middlewares, like `HandlerFacade` does, because "the consumer can't
+ * tell it from a local facade" was false of the one thing a consumer installs: measured,
+ * `runMiddlewares` had a single caller, so a frond that moved lost every middleware on
+ * the calling side — no log, no retry, no cache — from a `remotes:` line alone.
+ * The invocation the transport sends is the one the chain leaves behind, so a middleware
+ * can still put something on the wire.
+ */
+export function createRemoteFacade(
+  entity: string,
+  router: RemoteRouter,
+  middlewaresFor: (address: string) => AppMiddleware[],
+): Facade {
+  const opFn = (op: string) => async (invocation: InvocationContext = EMPTY_INVOCATION) => {
+    const { frond, transport } = await router.route(entity);
+    const call: FrondCall = { frond, entity, op };
+    const ctx: OperationContext = {
+      entity, frond, operation: op, args: [], state: invocation.state, invocation,
+    };
+    return runMiddlewares(middlewaresFor(entity), ctx, () =>
+      transport(call, ctx.invocation ?? invocation));
+  };
+
+  return new DynamicFacade(opFn).operations as Facade;
+}