@fougere/core 0.9.0-alpha.1 → 0.9.3-alpha.0

package/dist/wire/errors.js

@@ -1,4 +1,8 @@
-/** The error vocabulary — what a refusal IS, independently of who hears it. */
+/**
+ * The error vocabulary — what a refusal IS, independently of who hears it.
+ *
+ * Documented: [errors](https://fougere.dev/docs/business/errors).
+ */
 // ── ErrorCode ──────────────────────────────────
 /** Semantic error codes — transport-agnostic. Each bridge maps them to its own format. */
 export var ErrorCode;

package/dist/wire/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/wire/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/wire/errors.ts"],"names":[],"mappings":"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"}

package/dist/wire/signature.d.ts

@@ -1,4 +1,3 @@
-/** A method's signature, as a contract is built from it — the shape, never the reading. */
 /** A type reference — primitives, entities, arrays, generics. */
 export interface TypeRef {
     /** Raw type text as written in source (e.g. 'Pagination<Post>'). */
@@ -24,7 +23,7 @@ export interface Param {
     type: TypeRef;
     optional?: boolean;
 }
-/** A method signature. */
+/** A method's signature, as a contract is built from it — the shape, never the reading. */
 export interface Signature {
     name: string;
     params: Param[];

package/dist/wire/signature.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../src/wire/signature.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,iEAAiE;AACjE,MAAM,WAAW,OAAO;IACtB,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,oCAAoC;AACpC,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,0BAA0B;AAC1B,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}
+{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../src/wire/signature.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,WAAW,OAAO;IACtB,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,oCAAoC;AACpC,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,2FAA2F;AAC3F,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fougere/core",
-  "version": "0.9.0-alpha.1",
+  "version": "0.9.3-alpha.0",
   "description": "The core — scan, call contract, façades, remote stand-ins.",
   "keywords": [
     "fougere",
@@ -61,12 +61,12 @@
   "dependencies": {
     "@typescript/typescript6": "^6.0.2",
     "dequal": "^2.0.3",
-    "@fougere/container": "0.9.0-alpha.1",
-    "@fougere/schema": "0.9.0-alpha.1"
+    "@fougere/container": "0.9.3-alpha.0",
+    "@fougere/schema": "0.9.3-alpha.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "@fougere/compiler": "0.9.0-alpha.1"
+    "@fougere/compiler": "0.9.3-alpha.0"
   },
   "publishConfig": {
     "access": "public"

package/src/boot/AppLifecycle.ts

@@ -1,7 +1,11 @@
 import type { App } from './types.js';
 import type { FrondDescriptor } from '../descriptor/frond.js';
 
-/** One process-level extension and its reversible lifecycle. */
+/**
+ * One process-level extension and its reversible lifecycle.
+ *
+ * Documented: [lifecycle](https://fougere.dev/docs/infra/lifecycle).
+ */
 export interface Extension {
   name: string;
   /**

package/src/boot/apply.ts

@@ -9,7 +9,11 @@ export interface ConfigApplication {
   pending: string[];
 }
 
-/** What a (re-)read config changes in a process that is already running. */
+/**
+ * What a (re-)read config changes in a process that is already running.
+ *
+ * Documented: [lifecycle](https://fougere.dev/docs/infra/lifecycle).
+ */
 export function applyConfig(next: FougereConfig, inForce?: FougereConfig): ConfigApplication {
   const applied: string[] = [];
   const pending: string[] = [];

package/src/boot/declared.ts

@@ -0,0 +1,88 @@
+/**
+ * What an app says about its NEIGHBOURS — the dual of the identity card, which says what it IS.
+ *
+ * Documented: [observability](https://fougere.dev/docs/infra/observability).
+ */
+import type { FrondDescriptor } from '../descriptor/frond.js';
+import { facadeKeyOf, type DeclaredEdge, type DeclaredFrond, type DeclaredTopology } from '../wire/call.js';
+
+interface Declaring {
+  fronds: readonly FrondDescriptor[];
+  remotes: Readonly<Record<string, string>>;
+}
+
+/** Read from the config and the scan, never from a call, so nothing has to answer for it. */
+export function declaredTopologyOf({ fronds, remotes }: Declaring): DeclaredTopology {
+  const hosted = fronds.filter((frond) => !frond.brought);
+
+  return { fronds: placements(hosted, remotes), edges: crossings(hosted) };
+}
+
+function placements(hosted: readonly FrondDescriptor[], remotes: Readonly<Record<string, string>>): DeclaredFrond[] {
+  const here = hosted
+    .filter((frond) => !remotes[frond.name])
+    .map((frond) => ({ frond: frond.name, placement: 'local' as const }));
+
+  const elsewhere = Object.entries(remotes)
+    .map(([frond, address]) => ({ frond, placement: 'remote' as const, at: hostOf(address) }));
+
+  return [...here, ...elsewhere];
+}
+
+/**
+ * Which frond serves each address — indexed FORWARD, so a dependency is recognized by what
+ * answers it and never by its spelling. A surface is left out: its key carries a `:`, and no
+ * dependency can name one.
+ */
+export function servedBy(fronds: readonly FrondDescriptor[]): Map<string, string> {
+  const index = new Map<string, string>();
+  for (const frond of fronds) {
+    if (frond.brought) continue;
+    for (const handler of frond.handlers) {
+      if (handler.surface) continue;
+      index.set(facadeKeyOf(handler.address), frond.name);
+    }
+  }
+
+  return index;
+}
+
+/**
+ * The fronds one class reaches through a façade — the only sanctioned crossing.
+ *
+ * An address no scanned frond serves is left out rather than guessed: naming the frond behind it
+ * means reading its card, and a card is a DISCOVERY, which belongs to the other half of the
+ * report. This answers what the CODE declares, and never more.
+ */
+export function reachedBy(deps: readonly string[], from: string, index: Map<string, string>): string[] {
+  const reached = deps
+    .map((dependency) => index.get(dependency))
+    .filter((frond): frond is string => frond !== undefined && frond !== from);
+
+  return [...new Set(reached)];
+}
+
+function crossings(hosted: readonly FrondDescriptor[]): DeclaredEdge[] {
+  const index = servedBy(hosted);
+  const found = new Map<string, DeclaredEdge>();
+
+  for (const frond of hosted) {
+    for (const handler of frond.handlers) {
+      for (const to of reachedBy(handler.deps, frond.name, index)) {
+        found.set(`${frond.name} ${to}`, { from: frond.name, to });
+      }
+    }
+  }
+
+  return [...found.values()];
+}
+
+function hostOf(address: string): string {
+  try {
+    const url = new URL(address);
+
+    return `${url.protocol}//${url.host}`;
+  } catch {
+    return address;
+  }
+}

package/src/boot/install.ts

@@ -6,7 +6,7 @@ import type { Dispatcher } from '../dispatch/Dispatcher.js';
 import type { RouteRegistry } from '../dispatch/RouteRegistry.js';
 import type { Emissions } from './Emissions.js';
 import type { EffectiveOperationsMap, EffectiveOperationModel } from '../effective-operation.js';
-import { nameOf } from '../descriptor/frond.js';
+import { nameOf, type ProviderEntry } from '../descriptor/frond.js';
 import type { EntityEntry, FrondDescriptor, HandlerEntry } from '../descriptor/frond.js';
 import type { OperationsMap } from '../wire/operation.js';
 import type { AppMiddleware } from '../wire/middleware.js';
@@ -14,9 +14,9 @@ import type { CreateAppOptions } from './types.js';
 import { registerFrames } from './together.js';
 import { HandlerFacade } from '../dispatch/HandlerFacade.js';
 import { targetOf } from '../prefab/prefab.js';
-import { ownersOf, refuseStorageInUserCode, refuseCrudOnOwned } from './ownership.js';
+import { ownersOf, refuseSharedName, refuseStorageInUserCode, refuseCrudOnOwned } from './ownership.js';
 import { StorageGuard } from '../dispatch/StorageGuard.js';
-import { portBindings } from './ports.js';
+import { portBindings, seamChains, wrapping, SEAMS } from './ports.js';
 import { facadeKeyOf, contractsKeyOf } from '../wire/call.js';
 import { inheritsCrud, subjectOf } from '../prefab/crud.js';
 import { repositoryKeyOf } from '../prefab/repository.js';
@@ -117,6 +117,7 @@ export async function installFrond(frond: FrondDescriptor, assembly: Assembly):
 
   // 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.
+  refuseSharedName(frond);
   const owners = ownersOf(frond.providers);
   refuseStorageInUserCode(frond, owners, (entity) => entityByName.has(entity));
   refuseCrudOnOwned(frond, owners);
@@ -124,11 +125,22 @@ export async function installFrond(frond: FrondDescriptor, assembly: Assembly):
   for (const provider of frond.providers) {
     scope.register(nameOf(provider), provider.ctor, { deps: provider.deps });
   }
+  // What this frond puts in front of one of the framework's own ports. Its own, like every
+  // provider — a link goes where its frond goes, which is what a frond behind `remotes:`
+  // takes with it.
+  const seams = seamChains(frond.providers, options.ports);
+  for (const [seam, links] of seams) {
+    boundPorts.add(seam);
+    frondLog.debug(`seam ${seam} → ${links.map((one) => one.ctor.name).join(' → ')} → the realization`);
+  }
   // …and again under the port each one extends, so `private payment: Payment`
   // reaches the realization instead of the base class it is declared against.
   // Registered AFTER the loop above so a port key always wins over the base's
   // own registration — same precedence as a declared repository over its default.
   for (const [port, chain] of portBindings(frond.providers, (n) => scope.has(n), options.ports)) {
+    // A seam is bound where its realization is BUILT, not under a container key — nothing
+    // resolves `Storage`, and `<Entity>Storage` is what a handler asks for.
+    if (SEAMS.has(port)) continue;
     // Registered from the INSIDE OUT, each wrapper asking for the one it stands in front
     // of: the container resolves a dep by NAME, so wrapping is a substituted key and
     // needs nothing of the container itself. The outermost answers under the port.
@@ -168,8 +180,12 @@ export async function installFrond(frond: FrondDescriptor, assembly: Assembly):
         ? baseStorage.output(outputSchema)
         : baseStorage;
 
+      // The declared chain first, then the guard OUTSIDE it: the guard hands on the value
+      // it parsed, so a wrapper reads what the entity says a row is rather than what
+      // arrived. Same order the client door has held since `StorageGuard` existed.
+      const linked = wrapping('Storage', seams.get('Storage') ?? [], scoped, (dep) => scope.resolve(dep));
       // Storage is a way out like the client surface — see `StorageGuard`.
-      const guarded = new StorageGuard(entity.entityClass.getFields(), entity.name).guard(scoped);
+      const guarded = new StorageGuard(entity.entityClass.getFields(), entity.name).guard(linked);
       scope.registerValue(key, guarded);
 
       // The default repository IS the guarded port — it already answers every gesture a

package/src/boot/ownership.ts

@@ -5,6 +5,27 @@ import { targetOf } from '../prefab/prefab.js';
 import { ownedBy, repositoryKeyOf } from '../prefab/repository.js';
 import { entityOfStorageKey } from '../storage/port.js';
 
+/** One name, one file: two providers under one key and the second silently replaces the first. */
+export function refuseSharedName(frond: FrondDescriptor): void {
+  const declared = new Map<string, string>();
+
+  for (const provider of frond.providers) {
+    const name = nameOf(provider);
+    const first = declared.get(name);
+    if (first !== undefined) {
+      throw new Error(
+        `[provider] two files declare ${name}:\n`
+        + `    ${first}\n`
+        + `    ${provider.filePath}\n`
+        + `  A frond registers both under one key, so the second replaces the first and whoever `
+        + `asks for ${name} is handed whichever was scanned last.\n`
+        + '  Rename one of the two.',
+      );
+    }
+    declared.set(name, provider.filePath);
+  }
+}
+
 /** Who owns an entity's storage. */
 export function ownersOf(providers: readonly ProviderEntry[]): Map<string, string> {
   const owners = new Map<string, string>();

package/src/boot/ports.ts

@@ -1,5 +1,68 @@
 import { nameOf, type ProviderEntry } from '../descriptor/frond.js';
 
+/**
+ * The framework's own ports — a class core exports that a user class may stand in front of.
+ *
+ * They differ from a port in one way, and it decides everything else: their realization is
+ * HANDED IN rather than scanned (`storageFactory` builds one per entity), so a class that
+ * extends one can only be a wrapper.
+ *
+ * The scope is the FROND, like every other provider, and there is no key that widens it: a
+ * link that must be everywhere is a frond that is everywhere, which `Extension.fronds`
+ * already answers — `@fougere/calls` brings one into every app that installs it. A
+ * process-wide key would break the gradient, since a frond moved behind `remotes:` would
+ * silently leave the reach of a link its own code never mentioned.
+ *
+ * Documented: [ports](https://fougere.dev/docs/business/ports).
+ */
+export const SEAMS = new Set(['Storage']);
+
+/**
+ * What stands in front of each seam, outermost first — the same reading `portBindings`
+ * does, with no realization to find.
+ */
+export function seamChains(
+  providers: ProviderEntry[],
+  chosen: Record<string, string | readonly string[]> | undefined,
+): 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}).`,
+      );
+    }
+    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]));
+
+  return bound;
+}
+
+/** Put the declared chain in front of an instance the framework holds, and hand back the outermost. */
+export function wrapping<T extends object>(
+  seam: string,
+  links: readonly ProviderEntry[],
+  inner: T,
+  resolve: (name: string) => unknown,
+): T {
+  let current = inner;
+  // From the INSIDE out, so each link is handed the one it stands in front of — the same
+  // order `install.ts` registers a port's chain in, for the same reason.
+  for (const link of [...links].reverse()) {
+    const made = link.ctor as unknown as new (...args: unknown[]) => T;
+    current = new made(...link.deps.map((dep) => (dep === seam ? current : resolve(dep))));
+  }
+
+  return current;
+}
+
 /**
  * A port is a class something already answers under, and what answers it may be a CHAIN:
  * the realization, wrapped by whoever stands in front of it.

package/src/boot/remote.ts

@@ -1,4 +1,8 @@
-/** Remote façade — what resolve() falls back to. */
+/**
+ * Remote façade — what resolve() falls back to.
+ *
+ * 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';

package/src/boot/seed.ts

@@ -61,7 +61,11 @@ interface SeedDoor {
   write(item: unknown): Promise<unknown>;
 }
 
-/** Plant a set of seeds, in the order given. */
+/**
+ * Plant a set of seeds, in the order given.
+ *
+ * Documented: [seeds](https://fougere.dev/docs/business/seeds).
+ */
 export async function runSeeds(
   app: App,
   seeds: SeedEntry[],

package/src/boot/together.ts

@@ -1,4 +1,8 @@
-/** Building a frame — what a handler asking for `Together<[…]>` receives. */
+/**
+ * Building a frame — what a handler asking for `Together<[…]>` receives.
+ *
+ * Documented: [together](https://fougere.dev/docs/business/together).
+ */
 import { ambient } from '#ambient';
 import { upperFirst, lowerFirst, type SchemaView } from '@fougere/schema';
 import type { Container } from '@fougere/container';

package/src/boot/types.ts

@@ -137,9 +137,9 @@ export interface App extends DispatchPort {
   extensions(): string[];
   /** Declare one `rpc` op — what the app says about ITSELF, beside the card. */
   serveRpc(operationName: string, answer: RpcAnswer): void;
-  /** Register a global app middleware (runs on every operation). */
   /** Watch every dispatch transition; the returned function unsubscribes. */
   observe(observer: DispatchObserver): () => void;
+  /** Register a global app middleware (runs on every operation). */
   use(middleware: AppMiddleware): void;
   /** Register an app middleware scoped to a specific entity. */
   use(entity: string, middleware: AppMiddleware): void;

package/src/builtin/logger.ts

@@ -13,11 +13,9 @@ export interface LogRecord {
   at: number;
 }
 
+/** Where a line goes once it is written — `@fougere/log` ships one, `observability` another. */
 export type LogSink = (record: LogRecord) => void;
 
-/** Who else takes this process's log lines, beside the console. */
-const sinks: LogSink[] = [];
-
 /**
  * Where one boot's lines wait, and where they go once they can.
  *
@@ -66,15 +64,6 @@ export class Carry {
   }
 }
 
-/** Take every line this process logs. Returns the way to withdraw. */
-export function onLog(next: LogSink): () => void {
-  sinks.push(next);
-  return () => {
-    const at = sinks.indexOf(next);
-    if (at >= 0) sinks.splice(at, 1);
-  };
-}
-
 const LEVELS: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
 
 /** The level, held ONCE for the process and CONSULTED at every emission. */
@@ -176,14 +165,6 @@ export class Logger {
       level: level as LogRecord['level'], name: this.name, message: msg, args, at: Date.now(),
     };
 
-    // Beside the console, never instead of it: a forwarded line is an addition, and a
-    // sink that throws must not cost the operator the line they were reading.
-    for (const take of sinks) {
-      try {
-        take(record);
-      } catch { /* forwarding never breaks logging */ }
-    }
-
     this.carry?.push(record);
 
     // The console ALWAYS, whoever else took the line. Skipping it once a destination

package/src/config-loader.ts

@@ -21,7 +21,6 @@ export interface FougereConfig {
   logLevel?: LogLevel;
   /** Remote fronds — frondName → base URL. */
   remotes?: Record<string, string>;
-  /** Which realization answers which port — port class name → implementation class name. */
   /** What answers a port — a name, or the chain from the outside in. */
   ports?: Record<string, string | readonly string[]>;
   /** Auth declaration — picks a provider package and forwards options to it. */

package/src/contract.ts

@@ -30,7 +30,10 @@ export { driftOf, agrees, explain } from './wire/drift.js';
 export type { CardDrift } from './wire/drift.js';
 
 /** What `rpc.discover` answers. */
-export type { IdentityCard, CardOp, TopologyReport, FrondPlacement, Edge } from './wire/call.js';
+export type {
+  IdentityCard, CardOp, TopologyReport, FrondPlacement, Edge,
+  DeclaredTopology, DeclaredFrond, DeclaredEdge,
+} from './wire/call.js';
 export { assertIdentityCard } from './wire/call.js';
 
 /** The key a class name is filed under — 'Post' → 'post'. */

package/src/descriptor/frond.ts

@@ -1,4 +1,8 @@
-/** What a frond is made of — one interface per convention directory. */
+/**
+ * What a frond is made of — one interface per convention directory.
+ *
+ * Documented: [the Frond](https://fougere.dev/docs/concepts/frond).
+ */
 import type { SchemaView } from '@fougere/schema';
 import type { Param, OperationContract, OperationsMap } from '../wire/operation.js';
 import type { PresenterViews } from '../prefab/presenter.js';

package/src/effective-operation.ts

@@ -1,6 +1,7 @@
 /** The operation model after every declaration and convention has been resolved. */
 import { lowerFirst, type SchemaView } from '@fougere/schema';
 import { statementDrift } from './boot/statement-drift.js';
+import { reachedBy, servedBy } from './boot/declared.js';
 import { computeBindingPlan, type BindingPlan } from './wire/binding.js';
 import { targetOf } from './prefab/prefab.js';
 import type { CollectorEntry, FrondDescriptor, HandlerEntry } from './descriptor/frond.js';
@@ -69,6 +70,23 @@ export interface EffectiveOperation extends OperationContract {
     runtime: 'local' | 'remote';
     remote?: string;
   };
+  /**
+   * What running this op reaches, and how much of that crosses a process.
+   *
+   * `placement` says where the op ANSWERS; this says where it GOES. The pair is what every
+   * number a process hard-codes is really a function of — how often a trace is sampled, where
+   * a latency histogram's bounds should sit, what a load threshold may assume. An op that
+   * answers here and hops twice is not the same subject as one that answers here and hops none.
+   *
+   * Read from the handler, never from the op: a dependency is declared on the constructor, so
+   * the crossing belongs to the CLASS. Every op of one handler reaches the same fronds, and
+   * saying otherwise would dress a structural fact as a precise effect.
+   */
+  reach: {
+    fronds: { frond: string; runtime: 'local' | 'remote' }[];
+    /** How many of them are a process away — zero when everything it reaches runs here. */
+    hops: number;
+  };
   exposure: {
     surfaces: string[];
     adapters: string[];
@@ -80,6 +98,26 @@ export interface EffectiveOperation extends OperationContract {
 
 export type EffectiveOperationsMap = Map<string, EffectiveOperation>;
 
+/**
+ * Where an op's work goes: the fronds its handler reaches, and how many are a process away.
+ *
+ * A frond this app never scanned is not among them. The report can say a call LEFT — that is
+ * `placement` — but naming what is on the far side of an address means reading its card, and a
+ * card is a discovery rather than a declaration.
+ */
+function reachOf(
+  deps: readonly string[],
+  from: string,
+  index: Map<string, string>,
+  remotes: Record<string, string>,
+): EffectiveOperation['reach'] {
+  const fronds = reachedBy(deps, from, index)
+    .sort()
+    .map((frond) => ({ frond, runtime: (remotes[frond] ? 'remote' : 'local') as 'local' | 'remote' }));
+
+  return { fronds, hops: fronds.filter((one) => one.runtime === 'remote').length };
+}
+
 /** The absence rules every door normalises to before the handler is invoked. */
 export const EFFECTIVE_OPERATION_SEMANTICS = Object.freeze({
   optional: 'undefined' as const,
@@ -131,6 +169,8 @@ export function resolveEffectiveOperations(
   const schemas = new Map(
     fronds.flatMap((frond) => frond.entities.map((entity) => [entity.name, entity.entityClass] as const)),
   );
+  /** Every address a frond answers, so a dependency naming one is read as the crossing it is. */
+  const served = servedBy(fronds);
 
   // Input ambiguity is produced where schemas are available (the scanner), but it is a
   // resolution failure. Lift it into the same refusal table as kind/binding/topology.
@@ -285,6 +325,7 @@ export function resolveEffectiveOperations(
             runtime: remote ? 'remote' : 'local',
             ...(remote ? { remote } : {}),
           },
+          reach: reachOf(handler.deps, frond.name, served, options.remotes ?? {}),
           exposure: {
             surfaces: servedSurfaces(frond, handler).map((surface) => surface ?? 'default'),
             adapters: exposedAdapters(handler, options.adapters),

package/src/identity.ts

@@ -1,4 +1,8 @@
-/** Who is calling — the proof, not the claim. */
+/**
+ * Who is calling — the proof, not the claim.
+ *
+ * Documented: [identity](https://fougere.dev/docs/infra/identity).
+ */
 import { crypto } from '#crypto';
 import type { PublicJwk, Signer, Verifier } from './crypto/port.js';
 import { b64url, unb64url, bytesOf, textOf, unb64 } from './crypto/encoding.js';

package/src/index.ts

@@ -48,6 +48,9 @@ export type { Declared, FrondDeclaration, DeclaredSubject } from './declare.js';
 // only by tests through a deep path — a consumer comparing its own card to a producer's
 // had to dispatch a call to ask a question about itself.
 export { identityCardOf } from './boot/card.js';
+// Its dual: what the app declares about its NEIGHBOURS. Read by `rpc.topology`, by
+// `@fougere/calls` and by `fougere graph`, which each held their own half of it.
+export { declaredTopologyOf } from './boot/declared.js';
 export type { Facade } from './wire/call.js';
 export type {
   FrondCall,
@@ -57,21 +60,25 @@ export type {
   TopologyReport,
   FrondPlacement,
   Edge,
+  DeclaredTopology,
+  DeclaredFrond,
+  DeclaredEdge,
 } from './contract.js';
 export { type Emit, type Fact, type Pipe } from './wire/emit.js';
 export { callValueOf } from './contract.js';
 export { toHttpError } from './wire/http-error.js';
 export { toPublicError } from './contract.js';
 export { loggerMiddleware } from './wire/loggerMiddleware.js';
-export { Carry, Logger, setLogLevel, logLevel, envLevel, onLog, formatted } from './builtin/logger.js';
+export { Carry, Logger, setLogLevel, logLevel, envLevel, formatted } from './builtin/logger.js';
 export type { LogRecord, Rendered, LogSink } from './builtin/logger.js';
 // The fact a boot announces. Its destinations are `@fougere/log`'s; the line is core's.
 export { default as LogLine, CARRIES_LINE, LOG_LINE } from './builtin/LogLine.js';
 // What a re-read config changes in a running process — and what it cannot.
 export { applyConfig } from './boot/apply.js';
 export { Config } from './builtin/config.js';
-export type { Storage, StorageFactory, ListOptions, ListResult, Together } from './storage/port.js';
-export { togetherKeyOf } from './storage/port.js';
+export type { StorageFactory, ListOptions, ListResult, Together } from './storage/port.js';
+// A VALUE as well as a type: it is what a wrapper extends, which is the whole of declaring one.
+export { Storage, togetherKeyOf } from './storage/port.js';
 export type { Constraint, Source, SourceConfig, SourceView } from './source.js';
 export { Sources } from './source.js';
 export { storageOver } from './storage/store.js';

package/src/prefab/collector.ts

@@ -1,4 +1,8 @@
-/** Collector(Type) — resolves one handler input parameter from the invocation context. */
+/**
+ * Collector(Type) — resolves one handler input parameter from the invocation context.
+ *
+ * Documented: [collectors](https://fougere.dev/docs/business/collectors).
+ */
 
 import { upperFirst } from '@fougere/schema';