@fougere/core 0.6.0-alpha.0 → 0.8.0-alpha.0

package/src/scan/statement.ts

@@ -1,40 +1,14 @@
-/**
- * The scan, written as the STATEMENT an author would have written.
- *
- * A scan runs at build and the app runs elsewhere — two runtimes, no shared memory — so
- * something has to cross. What used to cross was the scan RESULT: every operation's
- * TypeScript signature re-serialized as JSON, beside the five CRUD ops `Crud.__ops`
- * declares at runtime anyway. A second writing of what the classes carry, and one that
- * drifts, since nothing compares the two.
- *
- * What crosses here is what `fronds.ts` holds: imports that bring the ORIGINAL classes
- * back, and `frond()` calls. Everything else `frond()` derives — `Post` is stored as
- * `post`, `PostHandler` answers at `post`, a computed field IS a method, and
- * `Presenter(Post)` keeps its subject. Only what TypeScript erases is named: a
- * constructor's parameter types (`deps`), and the surface a handler answers on, which the
- * scan read from its directory.
- *
- * Measured on demos/nuxt-blog: 102 lines of scan against 31 of statement, and the same app
- * — same rows, same computed fields, and no `typescript` loaded at boot.
- */
+/** The scan, written as the STATEMENT an author would have written. */
 import { relative } from 'node:path';
+import { nameOf } from '../descriptor/frond.js';
 import type { FrondDescriptor } from '../descriptor/frond.js';
 import type { ScanResult } from './result.js';
-
-type Live = { name?: string };
+import { type Aliases, type Live, operationsOf } from './contract.js';
 
 /**
- * A file becomes the specifier the PROJECT already uses for it: `@fronds/blog/…`, the
- * import scope a handler names its neighbour by, and which the Nuxt module registers as an
- * alias for every frond it found.
- *
- * A relative path would name the same file by a second route, and two routes to one module
- * are two modules — so `Post` would not equal `Post` and every identity check would fail
- * quietly. It also puts the file outside what the alias resolves, which is what made Node,
- * not the bundler, read the frond's `.ts` and answer 500 on `../entities/Post.js`.
- *
- * `.js`, because the source is `.ts` and the project spells a TypeScript source that way
- * everywhere else — the alias resolves through the same rule as a hand-written import.
+ * A file becomes the specifier the PROJECT already uses for it: `@fronds/blog/…`, the import scope
+ * a handler names its neighbour by, and which the Nuxt module registers as an alias for every
+ * frond it found.
  */
 function specifierOf(filePath: string, frond: FrondDescriptor): string {
   const inside = relative(frond.source.path, filePath).replace(/\.tsx?$/, '.js');
@@ -43,30 +17,66 @@ function specifierOf(filePath: string, frond: FrondDescriptor): string {
 }
 
 /** One alias per file, so a class imported twice is one binding and one identity. */
-class Imports {
+class Imports implements Aliases {
   private readonly byPath = new Map<string, string>();
+  private readonly byValue = new Map<Live, string>();
+  private readonly byClassName = new Map<string, Live>();
   private readonly lines: string[] = [];
+  /** The frond a file belongs to — a named import needs the specifier its default got. */
+  private frondOfFile = new Map<string, FrondDescriptor>();
 
-  default(filePath: string, frond: FrondDescriptor): string {
+  default(filePath: string, frond: FrondDescriptor, value?: Live): string {
+    this.frondOfFile.set(filePath, frond);
     const known = this.byPath.get(filePath);
-    if (known) return known;
+    if (known) {
+      if (value) this.remember(value, known);
+
+      return known;
+    }
     const alias = `_${this.byPath.size}`;
     this.lines.push(`import ${alias} from '${specifierOf(filePath, frond)}';`);
     this.byPath.set(filePath, alias);
+    if (value) this.remember(value, alias);
+
+    return alias;
+  }
+
+  /** A view a handler declares beside itself — `PostPublic` is exported by name. */
+  named(value: Live, filePath: string, name: string): string {
+    const known = this.byValue.get(value);
+    if (known) return known;
+    const frond = this.frondOfFile.get(filePath);
+    if (!frond) {
+      throw new Error(
+        `A statement cannot be written: ${name} lives in ${filePath}, which no frond imported first.`,
+      );
+    }
+    const alias = `_${this.byPath.size}_${name}`;
+    this.lines.push(`import { ${name} as ${alias} } from '${specifierOf(filePath, frond)}';`);
+    this.remember(value, alias);
 
     return alias;
   }
 
+  aliasOf(value: Live): string | undefined { return this.byValue.get(value); }
+  classNamed(name: string): Live | undefined { return this.byClassName.get(name); }
+
+  private remember(value: Live, alias: string): void {
+    this.byValue.set(value, alias);
+    const name = (value as { name?: string }).name;
+    if (name) this.byClassName.set(name, value);
+  }
+
   render(): string {
     return this.lines.join('\n');
   }
 }
 
 /** `{ ctor: X, deps: [...] }` when there is something to say, the bare class otherwise. */
-function subject(alias: string, deps: string[], extra = ''): string {
+function subject(alias: string, deps: string[], ...extra: string[]): string {
   const parts = [
     ...(deps.length ? [`deps: ${JSON.stringify(deps)}`] : []),
-    ...(extra ? [extra] : []),
+    ...extra.filter(Boolean),
   ];
 
   return parts.length ? `{ ctor: ${alias}, ${parts.join(', ')} }` : alias;
@@ -76,12 +86,21 @@ function frondOf(frond: FrondDescriptor, imports: Imports): string {
   const list = (items: string[]): string => `[${items.join(', ')}]`;
   const members: string[] = [];
 
+  // Entities first, and by VALUE: an operation names its input and output as schemas, and
+  // the one a `Partial<X>` derives from is found here rather than imported a second time.
   if (frond.entities.length) {
-    members.push(`entities: ${list(frond.entities.map((e) => imports.default(e.filePath, frond)))}`);
+    members.push(`entities: ${list(frond.entities.map((e) =>
+      imports.default(e.filePath, frond, e.entityClass as Live)))}`);
   }
   if (frond.handlers.length) {
-    members.push(`handlers: ${list(frond.handlers.map((h) =>
-      subject(imports.default(h.filePath, frond), h.deps, h.surface ? `surface: ${JSON.stringify(h.surface)}` : '')))}`);
+    members.push(`handlers: ${list(frond.handlers.map((h) => subject(
+      imports.default(h.filePath, frond, h.ctor as Live),
+      h.deps,
+      h.surface ? `surface: ${JSON.stringify(h.surface)}` : '',
+      // What the scan read from source, and what no class carries at runtime. Without it
+      // a host that boots from this statement serves a prefab's five ops and nothing else.
+      h.operations.size ? `operations: ${operationsOf(h.operations, h.filePath, imports, '      ')}` : '',
+    )))}`);
   }
   if (frond.presenters.length) {
     members.push(`presenters: ${list(frond.presenters.map((p) => subject(imports.default(p.filePath, frond), p.deps)))}`);
@@ -90,13 +109,26 @@ function frondOf(frond: FrondDescriptor, imports: Imports): string {
     members.push(`collectors: ${list(frond.collectors.map((c) => subject(imports.default(c.filePath, frond), c.deps)))}`);
   }
   if (frond.providers.length) {
-    members.push(`providers: ${list(frond.providers.map((p) => subject(imports.default(p.filePath, frond), p.deps)))}`);
+    members.push(`providers: ${list(frond.providers.map((p) => subject(
+      imports.default(p.filePath, frond, p.ctor as Live),
+      p.deps,
+      // The container key, and a bundler is free to rewrite the class's own name — it did,
+      // and a handler asking for `Communes` met a provider registered as `_Communes`.
+      `name: ${JSON.stringify(nameOf(p))}`,
+    )))}`);
   }
   // A seed is DATA, not a class — the one member a statement cannot derive from an import.
   if (frond.seeds.length) {
     members.push(`seeds: ${JSON.stringify(frond.seeds.map((s) => ({ entityName: s.entityName, data: s.data })))}`);
   }
   if (frond.surfaces) members.push(`surfaces: ${JSON.stringify(frond.surfaces)}`);
+  // What `frond.config.ts` states — read BY the scan, so a host that boots from a written
+  // statement never sees the file. It is the only answer for the kind of an op whose name
+  // leads with no known verb, and the only one for a method inherited from a base class
+  // the workspace scan cannot see.
+  if (frond.operationsOverrides && Object.keys(frond.operationsOverrides).length) {
+    members.push(`operationsOverrides: ${JSON.stringify(frond.operationsOverrides)}`);
+  }
 
   const scope = (frond.source.package as string | undefined)?.split('/')[0];
   if (scope) members.push(`scope: ${JSON.stringify(scope)}`);

package/src/source.ts

@@ -0,0 +1,63 @@
+import { Registry, Role, type SchemaView } from '@fougere/schema';
+import type { StorageFactory } from './storage.js';
+
+/** A promise the judge at the door cannot keep, because it is about rows it never sees. */
+export type Constraint = 'unique';
+
+/** Whether an entity asks for one, anywhere but on its key. */
+export function declares(schema: SchemaView, constraint: Constraint): boolean {
+  if (constraint !== 'unique') return false;
+  if ((schema.getUnique() ?? []).length > 0) return true;
+
+  return Object.values(schema.getFields()).some((field) => Role.of(field).isUnique);
+}
+
+/** A place rows live, whatever realizes it. */
+export interface Source {
+  storageFactory: StorageFactory;
+  /**
+   * Bring the shape of what lives here up to date, and say what it could not bring.
+   *
+   * A pass is additive by design and leaves what already exists alone — which is a
+   * promise worth keeping and a silence worth breaking: what it declined to change is
+   * still a difference, and a boot is where a reader can act on it.
+   */
+  migrate?(view: SourceView): Promise<void | string>;
+  /** Run `fn` as ONE unit of work, with a factory bound to it. */
+  transacted?<R>(fn: (factory: StorageFactory) => Promise<R>): Promise<R>;
+  /** What it refuses at the rows themselves. Absent leaves the judge alone with it. */
+  enforces?: readonly Constraint[];
+  close?(): Promise<void>;
+  /** What distinguishes it when a query is reported. */
+  name?: string;
+}
+
+/** The app as ONE source sees it. */
+export interface SourceView {
+  fronds: readonly { readonly name: string; readonly entities: readonly { readonly name: string }[] }[];
+  /** The auth provider's own entities, when they ride with this source. */
+  auth?: unknown;
+  elsewhere: readonly string[];
+}
+
+/** What a config file can carry about a source — values, never a live driver. */
+export interface SourceConfig {
+  /** The adapter that realizes it. Absent means the conventional one. */
+  source?: string;
+  /** The entities whose rows live here. Absent on the default source: it holds the rest. */
+  entities?: string[];
+  [key: string]: unknown;
+}
+
+/** Which adapter answers a source name — one per process, no subject to hold. */
+class SourceRegistry extends Registry<(conf: SourceConfig) => Source> {
+  /** The source this name stands for, built from the config entry that named it. */
+  open(name: string, conf: SourceConfig, path?: string): Source {
+    return this.resolve(name, path)(conf);
+  }
+}
+
+export const Sources = new SourceRegistry(
+  'source',
+  'import the adapter that answers it, or call Sources.register(name, build)',
+);

package/src/storage.ts

@@ -24,9 +24,8 @@ export interface ListOptions {
   count?: boolean;
 
   /**
-   * Equality criteria, field by field — `{ orderId: '…' }`. Named rather than spread
-   * across the options so an unknown key stays ignored instead of silently becoming a
-   * filter. `listBy(criteria)` is the same thing said as an intention.
+   * Equality criteria, field by field — `{ orderId: '…' }`. Named rather than spread across the
+   * options so an unknown key stays ignored instead of silently becoming a filter.
    */
   where?: Record<string, unknown>;
 }
@@ -41,12 +40,7 @@ export interface ListResult<T> extends Array<T> {
   hasMore?: boolean;
 }
 
-/**
- * The keys `list()` answers to. Anything else is a mistake, and saying so is the point:
- * the façade refuses an unknown key in a CLIENT's input (`Unknown field`) — this applies the
- * same rule to the framework's own arguments. `list({ orderId })` used to be accepted and
- * the filter dropped, so a one-to-many relation quietly returned the whole table.
- */
+/** The keys `list()` answers to. */
 const LIST_OPTION_KEYS = [
   'limit', 'offset', 'page', 'after', 'orderBy', 'order', 'count', 'where', 'select',
 ] as const;
@@ -73,83 +67,27 @@ export interface Storage<T = Record<string, unknown>> {
   list(options?: ListOptions & SelectOption): Promise<ListResult<T>>;
   findById(id: string, options?: SelectOption): Promise<T | undefined>;
   /**
-   * Read by criteria — `findBy({ email })` for the one, `findAllBy({ orderId })` for the
-   * many, which is what a one-to-many relation *is*.
-   *
-   * Both existed on the SQL implementation from the start and neither was declared here.
-   * A port that hides what it offers is a port nobody can use: `auth-better` cast its way
-   * in (`storage as StorageWithFindBy`), a presenter that needed the lines of an order read the
-   * whole table instead, and the GraphQL relation resolver passed criteria to `list()`
-   * — which drops what it does not know.
+   * Read by criteria — `findBy({ email })` for the one, `findAllBy({ orderId })` for the many,
+   * which is what a one-to-many relation *is*.
    */
   findBy(criteria: Partial<T> | Record<string, unknown>, options?: SelectOption): Promise<T | undefined>;
   findAllBy(criteria: Partial<T> | Record<string, unknown>, options?: SelectOption): Promise<T[]>;
   /**
-   * Read a SET of rows by their key, in one go — the gesture every other one was
-   * being bent into.
-   *
-   * `findAllBy` compares with `=`, so a list of ids could not be passed to it; the
-   * only way to read N rows was `list()` then filter in memory, which is what 14 of
-   * 14 handlers of a real app measured on 2026-08-14 were doing. It is invisible on
-   * SQLite and it is the whole table the day the rows are not local.
-   *
-   * It answers a MAP, because the caller holds keys and not positions: a page zips
-   * against it by `get(row.authorId)`, a miss is the absence of a key, and a repeated
-   * key is one entry. The list form this replaced promised that zip and could not
-   * keep it — dropping a miss shifts every later position — so each caller rebuilt
-   * the very index the implementation had just thrown away.
+   * Read a SET of rows by their key, in one go — the gesture every other one was being bent into.
    */
   findByKeys(ids: readonly string[], options?: SelectOption): Promise<Map<string, T>>;
-  /**
-   * Its dual: the rows that point AT each of these keys, grouped by the one they point at.
-   *
-   * `findByKeys` answers the side a row designates — one each, at most. This answers the
-   * side that designates the row — several each, and a key with none is simply absent.
-   * Together they are both directions of a relation, each in one query.
-   *
-   * Written because the page-shaped gesture only covered one of them: a presenter holding
-   * its page and wanting "the items of these lists" had no vocabulary for it and read the
-   * whole table instead, measured on a real app. `field` names the foreign key on THIS
-   * entity, the one carrying the value.
-   */
+  /** The dual of `findByKeys`: many rows per key, not one. */
   findAllByKeys(field: string, keys: readonly string[], options?: SelectOption): Promise<Map<string, T[]>>;
   create(input: Partial<T>, options?: SelectOption): Promise<T>;
-  /**
-   * Write the row, or make the existing one look like this — one statement.
-   *
-   * What an import needs and the port did not have: `create` throws on the second run,
-   * so re-reading a source meant deleting first. Measured pulling an API twice.
-   *
-   * The key and the creation stamps survive an overwrite — a row keeps the moment it
-   * appeared. An engine with no upsert clause refuses by name rather than emulating
-   * one with a read in front, which would promise an atomicity it has not got.
-   */
+  /** Write the row, or make the existing one look like this — one statement. */
   upsert(input: Partial<T>, options?: SelectOption): Promise<T>;
-  /**
-   * A whole page in one statement — what an import writes through.
-   *
-   * Row by row, 500 rows were 500 statements (measured); the shape of an import is a
-   * page, so the write is one too. Answers how many rows were written rather than the
-   * rows: `create` hands back the complete row because a caller acts on it, and an
-   * import acts on none of them — re-reading a page for a symmetry nobody uses would
-   * double the work.
-   */
+  /** A whole page in one statement — what an import writes through. */
   upsertAll(inputs: readonly Partial<T>[], options?: SelectOption): Promise<number>;
   update(id: string, input: Partial<T>, options?: SelectOption): Promise<T>;
   delete(id: string): Promise<boolean>;
   /** Returns a scoped storage that restricts all read results to the fields of the given schema. */
   output(schema: SchemaView): Storage<T>;
-  /**
-   * What this storage wraps — the Kysely instance for the SQL one, something else elsewhere.
-   *
-   * Every judge sits on the storage's own methods, so a statement issued here meets none of
-   * them: a value the entity refuses lands in the table without a word. It is the port's
-   * own escape hatch rather than a handle on the side, so it keeps the scope the container
-   * gave you — `productStorage.client` reaches the products, not the whole database.
-   *
-   * `unknown` on purpose: the client belongs to the implementation, and narrowing it is
-   * the caller saying out loud which one they are standing on.
-   */
+  /** What this storage wraps — the Kysely instance for the SQL one, something else elsewhere. */
   readonly client: unknown;
 }
 
@@ -159,118 +97,12 @@ export interface Storage<T = Record<string, unknown>> {
  */
 export type StorageFactory = (entity: SchemaView, name: string) => Storage;
 
-/**
- * A place rows live, whatever realizes it.
- *
- * `StorageFactory` plus its lifecycle, which is why it lives beside it. Three of the four
- * gestures are optional and ABSENCE IS THE ANSWER: no `transacted` and a frame compensates
- * instead of transacting (`boot/together.ts`), no `migrate` and there is no shape to bring
- * up to date. What a source is MADE OF is not here — `adapter/sql` states `dialect`, `db`
- * and `sink` on its own `SqlSource`, reached by narrowing, the rule {@link Storage.client}
- * already obeys one level down.
- */
-export interface Source {
-  storageFactory: StorageFactory;
-  /** Bring the shape of what lives here up to date. */
-  migrate?(view: SourceView): Promise<void>;
-  /** Run `fn` as ONE unit of work, with a factory bound to it. */
-  transacted?<R>(fn: (factory: StorageFactory) => Promise<R>): Promise<R>;
-  close?(): Promise<void>;
-  /** What distinguishes it when a query is reported. */
-  name?: string;
-}
-
-/**
- * The app as ONE source sees it: what lives there, and the NAMES of what does not.
- *
- * The second half is what lets a DDL stop lying. A batch holding every entity cannot tell
- * a cross-source target from a typo, so a `ref()` falls back to a derived table name and
- * the constraint is emitted against a table that may not exist. `elsewhere` says which
- * misses are legitimate — and a target in neither list is a mistake, out loud.
- */
-export interface SourceView {
-  fronds: readonly { readonly name: string; readonly entities: readonly { readonly name: string }[] }[];
-  /** The auth provider's own entities, when they ride with this source. */
-  auth?: unknown;
-  elsewhere: readonly string[];
-}
-
-/**
- * What a config file can carry about a source — values, never a live driver.
- *
- * `source` names the ADAPTER, and everything else belongs to the adapter it named:
- * `adapter/sql` reads `dialect`, a file one reads `path`. That is the shape
- * `EntityAdapters` already has — addressed by adapter, and what sits below is the
- * adapter's own. Which is why the level `schema` owns is not repeated here.
- */
-export interface SourceConfig {
-  /** The adapter that realizes it. Absent means the conventional one. */
-  source?: string;
-  /** The entities whose rows live here. Absent on the default source: it holds the rest. */
-  entities?: string[];
-  [key: string]: unknown;
-}
-
-/**
- * Which adapter answers a source name — one per process, no subject to hold.
- *
- * The shape `Generators` already has, and the refusal `resolveStorage` already made: only
- * `sqlite` could be resolved from its name, because it was the one driver `defaults`
- * depended on. That refusal had no owner — it lived in the package that happened to import
- * the driver — so a second adapter had nowhere to say it exists. Here it does, and an
- * unknown name is refused naming what this process answers.
- *
- * Registered at IMPORT by each adapter, so nothing central lists them.
- */
-export class Sources {
-  private static readonly registry = new Map<string, (conf: SourceConfig) => Source>();
-
-  static register(name: string, build: (conf: SourceConfig) => Source): void {
-    this.registry.set(name, build);
-  }
-
-  /** The source this name stands for, refused by name when nothing does. */
-  static resolve(name: string, conf: SourceConfig): Source {
-    const build = this.registry.get(name);
-    if (build) return build(conf);
-
-    throw new Error(
-      `Unknown source '${name}' — import the adapter that answers it, or register one with `
-      + `Sources.register('${name}', build). This process answers `
-      + `${[...this.registry.keys()].join(', ') || 'nothing yet'}.`,
-    );
-  }
-
-  /** Whether a name is answered, for a caller that must not throw to find out. */
-  static answers(name: string): boolean {
-    return this.registry.has(name);
-  }
-
-  /** What this process answers — what a refusal elsewhere prints. */
-  static answered(): string[] {
-    return [...this.registry.keys()];
-  }
-}
-
-/**
- * Container key of an entity's storage — 'reading' → 'ReadingStorage'.
- *
- * The twin of {@link repositoryKeyOf} and of `facadeKeyOf`: the key of a thing
- * lives with the thing. This one was spelled by hand in four places in
- * `bootstrap.ts` and a fifth in `scanner.ts` — where the SCAN derives what a
- * constructor asks for. Two readers of one convention, neither of them naming it,
- * so a rename would have moved one and left the other resolving to nothing.
- */
+/** Container key of an entity's storage — 'reading' → 'ReadingStorage'. */
 export function storageKeyOf(entity: string): string {
   return `${upperFirst(entity)}${HELD}`;
 }
 
-/**
- * The entity behind a storage key, or `undefined` when the key is not one.
- *
- * The dual of the line above, for the reason `membersOfTogetherKey` is. `known` is what the
- * suffix alone cannot answer: `FileStorage` is an ordinary class name.
- */
+/** The entity behind a storage key, or `undefined` when the key is not one. */
 export function entityOfStorageKey(key: string, known: (entity: string) => boolean): string | undefined {
   if (key.length <= HELD.length || !key.endsWith(HELD)) return undefined;
   const entity = lowerFirst(key.slice(0, -HELD.length));
@@ -281,47 +113,7 @@ export function entityOfStorageKey(key: string, known: (entity: string) => boole
 /** What a holder keeps, said in the key it is registered under. */
 const HELD = 'Storage';
 
-/**
- * `Together<[Account, Ledger]>` — writes that stand or fall as one.
- *
- * `Storage` is the port whose every gesture is ONE statement, and one statement is
- * atomic in every engine. This is the port whose unit is a BLOCK: what the callback did
- * happens entirely, or not at all. Nothing else separates them — the arity of the unit
- * of work is the whole distinction, which is why this lives here and not in a file of
- * its own.
- *
- * ```ts
- * constructor(private together: Together<[Account, Ledger]>) {}
- *
- * await this.together.run(async ([accounts, ledger]) => {
- *   await accounts.update(from, { balance: b - amount });
- *   await ledger.create({ from, to, amount });
- * });
- * ```
- *
- * **The second list is providers**, rebuilt inside the frame so that what THEY write is
- * covered too — a `Mirror` writes its pages through `Storage<T>`, so naming it puts
- * them under the same unwind, with no locator and no second injection path:
- *
- * ```ts
- * constructor(private together: Together<[RateCard, Ledger], [RateMirror]>) {}
- *
- * await this.together.run(async ([rates, ledger], [mirror]) => { await mirror.refresh(); });
- * ```
- *
- * Two lists rather than one, because in a signature an entity and a provider are both
- * written as a class name and their instance types do not separate them — the type would
- * have to guess, by looking for methods or for a brand, and both answers are worse than
- * saying it. They are two different facts anyway: what the unwind covers, and what is
- * rebuilt to make that true.
- *
- * **All or nothing is the promise; isolation is not.** On one engine the members are
- * rebuilt over a transaction and the engine gives both. Across engines a transaction
- * cannot exist, so the frame keeps the before-image of each write and replays the
- * inverse in reverse order — the unwind holds, the isolation does not, and a reader
- * between two writes sees the half. The boot says which of the two it built rather
- * than letting the author assume the stronger one.
- */
+/** `Together<[Account, Ledger]>` — writes that stand or fall as one. */
 export interface Together<E extends readonly unknown[], P extends readonly unknown[] = []> {
   run<R>(fn: (entities: { [K in keyof E]: Storage<E[K]> }, providers: P) => Promise<R>): Promise<R>;
 }
@@ -329,12 +121,6 @@ export interface Together<E extends readonly unknown[], P extends readonly unkno
 /**
  * The container key of a frame — `[['Account', 'Ledger'], ['RateMirror']]` →
  * 'Account+Ledger|RateMirrorTogether'.
- *
- * The DECLARED order, not a sorted one. The tuples are what the callback destructures, so
- * reordering here would hand `[ledger, accounts]` to a signature that says the opposite —
- * the type and the runtime disagreeing about the same line. Two orders of one frame are
- * therefore two keys and two registrations; they cost nothing, a frame holding no state
- * between runs.
  */
 export function togetherKeyOf(entities: readonly string[], providers: readonly string[] = []): string {
   const named = entities.map(upperFirst).join(SEPARATOR);
@@ -346,13 +132,7 @@ const SEPARATOR = '+';
 /** Separates the two lists — what the unwind covers, and what is rebuilt to make it true. */
 const KINDS = '|';
 
-/**
- * The members behind a frame key, or `undefined` when the key is not one.
- *
- * The dual of the line above, and here for the reason `factOfEmitKey` is: the boot reads
- * the key back out of a handler's `deps` to know which frames to build. A key and the way
- * to undo it belong together — the pair that is split is the pair that drifts.
- */
+/** The members behind a frame key, or `undefined` when the key is not one. */
 export function membersOfTogetherKey(key: string): { entities: string[]; providers: string[] } | undefined {
   if (key.length <= FRAME.length || !key.endsWith(FRAME)) return undefined;
   const [entities, providers = ''] = key.slice(0, -FRAME.length).split(KINDS);