@fougere/core 0.5.0-alpha.1 → 0.7.0-alpha.0

package/src/scan/scanner.ts

@@ -1,27 +1,28 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { existsSync, type Dirent } from 'node:fs';
 import { join, dirname, basename, resolve as resolvePath } from 'node:path';
-import type { FrondDescriptor, ProviderEntry, EntityEntry, HandlerEntry, PresenterEntry, CollectorEntry, SeedEntry, ScanResult, ScanDiagnostic } from './frond.js';
+import type { FrondDescriptor, ProviderEntry, EntityEntry, HandlerEntry, PresenterEntry, CollectorEntry, SeedEntry } from '../descriptor/frond.js';
+import type { ScanResult, ScanDiagnostic } from './result.js';
 import { ANONYMOUS_SCHEMA_NAME, type SchemaView } from '@fougere/schema';
 import type { OperationContract, OperationsMap } from '../wire/operation.js';
 import { cardinalityOf } from '../wire/operation.js';
-import { computeBindingPlan } from '../boot/binding.js';
+import { computeBindingPlan } from '../wire/binding.js';
 import {
   parseAllHandlerMethods,
   parsePresenterMethods,
   parseConstructorParams,
   resetTypePrograms,
   seedTypeProgram,
-  type ParsedType,
 } from './handler-parser.js';
+import type { TypeRef } from '../wire/signature.js';
 import { loadFrondConfig } from '../frond-config.js';
 import { emitKeyOf } from '../emit.js';
 import { getPresenterFields } from '../prefab/presenter.js';
-import { ormKeyOf, togetherKeyOf } from '../orm.js';
+import { storageKeyOf, togetherKeyOf } from '../storage.js';
 import { targetOf, viewsOf, outputOf } from '../prefab/prefab.js';
 import { ownedBy, repositoryKeyOf } from '../prefab/repository.js';
 import { lowerFirst } from '@fougere/schema';
-import { Fronds } from './Fronds.js';
+import { Fronds } from '../descriptor/Fronds.js';
 import { getModuleLoader } from '../loader.js';
 import {
   type Conventions, type ConventionsInput,
@@ -30,13 +31,7 @@ import {
 
 // FS
 
-/**
- * What this scan run could not do. Reset by {@link scanProject}, which owns a run.
- *
- * Module-scoped like the loader and the cache root above: the scanner already has a
- * notion of "the current run". Three sites record — measured — so a per-run object
- * would carry twenty methods to spare one line of reset.
- */
+/** What this scan run could not do. */
 let diagnostics: ScanDiagnostic[] = [];
 
 function record(d: ScanDiagnostic): void {
@@ -44,10 +39,8 @@ function record(d: ScanDiagnostic): void {
 }
 
 /**
- * An absent convention directory is the ordinary case — a frond without
- * `presenters/` is not a defect. Anything else (permissions, an I/O error, a path
- * that is not a directory) means the scan did not look, and answering `[]` says
- * it did. One `catch` used to conflate the two.
+ * An absent convention directory is the ordinary case — a frond without `presenters/` is not a
+ * defect.
  */
 async function readEntries(path: string): Promise<Dirent[]> {
   try {
@@ -114,13 +107,7 @@ function findWorkspaceRoot(from: string): string {
   return resolvePath(from); // fallback: use project root itself
 }
 
-/**
- * Strip the 'Handler' suffix → the name the handler answers to. 'PostHandler' → 'post'.
- *
- * Nothing here checks that an entity carries the result, and nothing should: a handler
- * about no stored row is ordinary. The old name of this function — `toEntityName` — is
- * what let "one façade per entity" be repeated until it read as a rule.
- */
+/** Strip the 'Handler' suffix → the name the handler answers to. */
 function toAddress(className: string): string {
   const base = className.endsWith('Handler') ? className.slice(0, -7) : className;
   return lowerFirst(base);
@@ -129,20 +116,10 @@ function toAddress(className: string): string {
 // Scan
 
 /**
- * The container key a constructor parameter asks for — derived from its TYPE, not from
- * how the type was spelled.
- *
- * `deps` used to be `p.type.name`, so the key WAS the alias's name: `type ListOrm =
- * EntityOrm<List>` resolved only because someone had spelled it exactly like the
- * registration key (`ListOrm`), while `type ListRepo = EntityOrm<List>` — the same type —
- * typechecked and died at boot on `'ListRepo' is not registered`. And `EntityOrm<List>`
- * written out in full asked for `'EntityOrm'`, which nothing registers.
- *
- * `EntityOrm<X>` names X's storage, so that is the key. The generic argument was already
- * parsed (`ParsedType.generics`) and thrown away. Anything else keeps its own name: a
- * plain service IS designated by its class name.
+ * The container key a constructor parameter asks for — derived from its TYPE, not from how the
+ * type was spelled.
  */
-function depKeyOf(type: ParsedType): string {
+function depKeyOf(type: TypeRef): string {
   // `Facade<PostHandler>` — the second port, read exactly like the first. The type names
   // what arrives: not the handler (its methods take positional arguments and it is never
   // injected), but the door built in front of it. Same key whether that door is the local
@@ -165,32 +142,25 @@ function depKeyOf(type: ParsedType): string {
   // `RepositoryOf<Post>` — what an author writes when no repository file exists. The dual
   // of the line below: one names the port, the other the holder, and both resolve to a key
   // rather than to a class the author would have to invent.
-  const held = type.name === 'RepositoryOf' ? type.generics?.[0]?.name : undefined;
-  if (held) return repositoryKeyOf(held);
+  const subject = type.name === 'RepositoryOf' ? type.generics?.[0]?.name : undefined;
+  if (subject) return repositoryKeyOf(subject);
 
-  const target = type.name === 'EntityOrm' ? type.generics?.[0]?.name : undefined;
+  // The GENERIC names the subject, so a prefix does not change the key — `MeiliStorage<Card>`
+  // is `Card`'s storage. A class named `FileStorage` is untouched: it carries no generic.
+  const target = type.name.endsWith('Storage') && type.generics?.length === 1
+    ? type.generics[0]?.name
+    : undefined;
   if (!target) return type.name;
 
-  return ormKeyOf(target);
+  return storageKeyOf(target);
 }
 
-/**
- * `'[Account, Ledger]'` → `['Account', 'Ledger']`.
- *
- * The tuple was chosen over the variadic form the parser reads more cleanly, because the
- * variadic one costs arities-with-defaults and a `never` filter on the TypeScript side
- * while the tuple maps to `[EntityOrm<Account>, EntityOrm<Ledger>]` in one line. The
- * parser does not get to decide alone; this split is what that choice costs.
- */
+/** `'[Account, Ledger]'` → `['Account', 'Ledger']`. */
 function tupleMembers(raw: string): string[] {
   return raw.replace(/^\[|\]$/g, '').split(',').map((member) => member.trim()).filter(Boolean);
 }
 
-/**
- * These readings are semantic: an unchanged file can mean something different after an
- * imported alias changes. The parser's TypeScript Program is the cache for one scan; a
- * cache keyed only by this file's bytes would be unsound.
- */
+/** These readings are semantic. */
 const ctorParamsOf = (filePath: string) =>
   parseConstructorParams(filePath);
 
@@ -216,9 +186,9 @@ async function toProvider(filePath: string): Promise<ProviderEntry> {
   const owned = ownedBy(ctor);
   const target = targetOf(ctor);
   if (owned.length > 1 && deps.length === 0) {
-    deps.push(...owned.map((entity) => ormKeyOf(lowerFirst((entity as { name: string }).name))));
+    deps.push(...owned.map((entity) => storageKeyOf(lowerFirst((entity as { name: string }).name))));
   } else if (target && deps.length === 0) {
-    deps.push(ormKeyOf(lowerFirst((target as { name: string }).name)));
+    deps.push(storageKeyOf(lowerFirst((target as { name: string }).name)));
   }
 
   // No `name` beside `ctor`: a provider registers under `ctor.name`, which is what
@@ -243,10 +213,10 @@ async function toEntityEntry(filePath: string): Promise<EntityEntry | null> {
 }
 
 /**
- * Resolve a ParsedType to a runtime schema if available in module exports.
+ * Resolve a TypeRef to a runtime schema if available in module exports.
  * Handles arrays, generics (uses base name), and simple references.
  */
-function resolveSchema(type: ParsedType, moduleExports: Record<string, unknown>): SchemaView | undefined {
+function resolveSchema(type: TypeRef, moduleExports: Record<string, unknown>): SchemaView | undefined {
   // An array's element type IS `type.name` — the arity rides beside it, so nothing has
   // to be unwrapped here.
   // For generics like Pagination<Post>, also check inner types
@@ -271,12 +241,7 @@ function resolveSchema(type: ParsedType, moduleExports: Record<string, unknown>)
   return undefined;
 }
 
-/**
- * Parse ALL method signatures for unified binding.
- *
- * Resolves schemas for all params (not just the first) and stores
- * full signatures for the binding algorithm.
- */
+/** Parse ALL method signatures for unified binding. */
 async function inferOperations(
   filePath: string,
   handlerName: string,
@@ -307,15 +272,8 @@ async function inferOperations(
   }
 
   /**
-   * A base class the parse could not open — an installed package, typically, whose
-   * source is not in the workspace. Its operations are missing from this façade, and
-   * the scan cannot tell whether there were any.
-   *
-   * A warning, not a refusal: an installed base class with no operation is perfectly
-   * ordinary, and the boot has no way to decide between the two. So it names the
-   * clause and stops there. Stating the contract in `frond.config.ts` is the answer
-   * — the third producer, which creates an op neither other producer found — and it
-   * silences this by making the op exist.
+   * A base class the parse could not open — an installed package, typically, whose source is not
+   * in the workspace.
    */
   for (const base of parsed.unresolvedHeritage) {
     record({
@@ -341,10 +299,10 @@ async function inferOperations(
     // caller supplies through the body are candidates: a schema-typed collector, fact or
     // context parameter is not input merely because it names an entity. The old loop
     // ignored provenance and assigned the first schema it met, so swapping two parameters
-    // silently changed the contract the façade used to judge the request body.
+    // silently changed the contract the façade used to validate the request body.
     const binding = computeBindingPlan(method.params, collectorTypeNames);
     const candidates = method.params.flatMap((param, index) => {
-      if (binding[index]?.source.kind !== 'body') return [];
+      if (binding[index]?.source.kind !== 'input') return [];
       const schema = resolveSchema(param.type, moduleExports);
       return schema ? [{ param, schema }] : [];
     });
@@ -521,13 +479,7 @@ async function scanFrond(frondPath: string, name: string, source: FrondDescripto
     entities: entitiesDir, handlers: handlersDir,
     presenters: presentersDir, collectors: collectorsDir, seeds: seedsDir,
   } = conventions.dirs;
-  /**
-   * A convention directory, read by whoever knows the shape it holds.
-   *
-   * The same three lines were written six times — list, read in parallel, drop what the
-   * reader refused — which is what made `handlers/` quietly special: it grew a second
-   * pass for its surfaces and nothing else could.
-   */
+  /** A convention directory, read by whoever knows the shape it holds. */
   const collect = async <T extends object>(
     dir: string,
     read: (filePath: string) => Promise<T | null>,
@@ -614,15 +566,7 @@ async function scanFrond(frondPath: string, name: string, source: FrondDescripto
   };
 }
 
-/**
- * The frond's name — the directory, unless its `package.json` renames it. One rule for a
- * frond under `fronds/` and for the root frond alike, so the root needs no second spelling.
- *
- * Carrying the convention is what makes a frond; the key never marked anything and
- * nothing read it. It earns its keep as the one thing the directory cannot say: that
- * `fronds/blog-v2/` serves the frond still called `blog` — so a rename on disk does not
- * rename the entity keys, the `@fronds/*` import or a `remotes:` entry.
- */
+/** The frond's name — the directory, unless its `package.json` renames it. */
 async function frondNameOf(frondPath: string, dirName: string): Promise<string> {
   try {
     const pkg = JSON.parse(await readFile(join(frondPath, 'package.json'), 'utf8')) as {
@@ -636,15 +580,8 @@ async function frondNameOf(frondPath: string, dirName: string): Promise<string>
 }
 
 /**
- * A frond is a directory carrying the convention, and the project root is one such
- * directory — so a single-domain app writes `entities/` next to `app/` and never names
- * anything. `fronds/` is not the definition, it is where the OTHERS live: the root frond
- * stays put when a second domain appears, which is what makes flattening free instead of
- * a deferred move.
- *
- * `entities/` is the test, not "any convention directory". `services/` and `repositories/`
- * are ordinary top-level names in projects that never heard of Fougere, and a domain
- * without a single entity is not a domain.
+ * A frond is a directory carrying the convention, and the project root is one such directory — so
+ * a single-domain app writes `entities/` next to `app/` and never names anything.
  */
 async function rootFrondOf(root: string, workspaceRoot: string, conventions: Conventions): Promise<FrondDescriptor | null> {
   if ((await files(join(root, conventions.dirs.entities))).length === 0) return null;
@@ -652,21 +589,7 @@ async function rootFrondOf(root: string, workspaceRoot: string, conventions: Con
   return scanFrond(root, name, { path: root, package: frondPackage(name, conventions) }, conventions, workspaceRoot);
 }
 
-/**
- * `@fronds/<name>` → the directory it names, for every frond of a project.
- *
- * The framework states this convention — `FrondSource.package` has always spelled it, and
- * `fougere sync` writes it into a consumer's tsconfig — and until now its own reader could
- * not resolve it. The Nuxt module registered a Vite alias, so a `.vue` page could import
- * `@fronds/blog/entities/Post`, while the SCAN loaded sources through a bare jiti: a frond
- * naming its neighbour got `Cannot find module '@fronds/user/entities/User.js'`. So the one
- * form that survives a split was the one form that did not run.
- *
- * Hand it to the module loader — `createJiti(url, { alias: await frondAliases(root) })` —
- * and the named form resolves everywhere the framework reads. A directory listing and a
- * `package.json` read, no parsing: it is deliberately callable BEFORE the loader exists,
- * which is what makes the chicken-and-egg go away.
- */
+/** `@fronds/<name>` → the directory it names, for every frond of a project. */
 export async function frondAliases(root: string, conventions: Conventions = DEFAULT_CONVENTIONS): Promise<Record<string, string>> {
   const frondsDir = join(root, conventions.fronds);
   const aliases: Record<string, string> = {};
@@ -680,17 +603,7 @@ export async function frondAliases(root: string, conventions: Conventions = DEFA
     aliases[frondPackage(await frondNameOf(path, dir), conventions)] = resolvePath(path);
   }
 
-  /**
-   * A SYNCED frond answers to the same name.
-   *
-   * `fougere sync` writes `.fougere/remotes/<name>/` and registers it in `remotes.json`,
-   * which the Nuxt module already reads to alias `@fronds/<name>`. Doing it here too is
-   * what makes the convention mean ONE thing: a consumer writes `@fronds/blog/entities/Post`
-   * and never learns whether that frond is on this disk or was fetched from a card.
-   *
-   * A local frond wins a name collision — its source is the truth, a synced copy is a
-   * mirror of somebody else's.
-   */
+  /** A SYNCED frond answers to the same name. */
   try {
     const registry = JSON.parse(
       await readFile(join(root, '.fougere', 'remotes.json'), 'utf8'),
@@ -751,23 +664,12 @@ export async function scanProject(
 
   // The app's own domain first, then the ones it took in.
   const all = rootFrond ? [rootFrond, ...under] : under;
-  const fronds = Fronds.scanned(filter ? all.filter((f) => filter.includes(f.name)) : all);
+  const fronds = Fronds.hosting(filter ? all.filter((f) => filter.includes(f.name)) : all);
 
   return { fronds, diagnostics };
 }
 
-/**
- * What changes when a frond's domain changes — the paths a dev loop watches.
- *
- * It lives beside the scan rather than beside the conventions it reads, because it turns
- * names into DISK paths: `join` is `node:path`, and `conventions.ts` is reached from
- * `index` through `frond()`, which an edge bundle imports. Measured — esbuild refused the
- * Worker with `Could not resolve "node:path"`.
- *
- * The root frond IS the scan root, so watching its path would match every write in the
- * project: `.nuxt/`, `node_modules/`, the build output. Its convention directories are
- * the frond, and they are what a scan re-reads.
- */
+/** What changes when a frond's domain changes — the paths a dev loop watches. */
 export function watchPathsOf(
   frond: { source: { path: string } },
   scanRoot: string,

package/src/scan/statement.ts

@@ -1,39 +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 type { FrondDescriptor, ScanResult } from './frond.js';
+import type { FrondDescriptor } from '../descriptor/frond.js';
+import type { ScanResult } from './result.js';
 
 type Live = { name?: string };
 
 /**
- * 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');

package/src/source.ts

@@ -0,0 +1,44 @@
+import { Registry, type SchemaView } from '@fougere/schema';
+import type { StorageFactory } from './storage.js';
+
+/** A place rows live, whatever realizes it. */
+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. */
+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

@@ -0,0 +1,141 @@
+import { upperFirst, lowerFirst, type SchemaView } from '@fougere/schema';
+
+/** Options for list queries — pagination, sorting, counting. */
+export interface ListOptions {
+  /** Number of records to return. */
+  limit?: number;
+
+  /** Offset-based: skip N records. */
+  offset?: number;
+
+  /** Page-based: 1-indexed page number (requires limit). */
+  page?: number;
+
+  /** Cursor-based: fetch records after this ID. */
+  after?: string;
+
+  /** Field name to order by. */
+  orderBy?: string;
+
+  /** Sort direction (default: 'asc'). */
+  order?: 'asc' | 'desc';
+
+  /** If true, also returns total count (for pagination UIs). */
+  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.
+   */
+  where?: Record<string, unknown>;
+}
+
+/** Result of list() — extends Array so it's backward compatible. */
+export interface ListResult<T> extends Array<T> {
+  /** Total number of matching records (only set when count: true). */
+  total?: number;
+  /** Cursor of the last item (for cursor-based pagination). */
+  endCursor?: string;
+  /** Whether more records exist after endCursor. */
+  hasMore?: boolean;
+}
+
+/** The keys `list()` answers to. */
+const LIST_OPTION_KEYS = [
+  'limit', 'offset', 'page', 'after', 'orderBy', 'order', 'count', 'where', 'select',
+] as const;
+
+/** Refuse an option the port does not answer to, naming it and what was expected. */
+export function assertListOptions(options: object | undefined, entity: string): void {
+  if (!options) return;
+  const legal = new Set<string>(LIST_OPTION_KEYS);
+  const strangers = Object.keys(options).filter((key) => !legal.has(key));
+  if (strangers.length === 0) return;
+  throw new Error(
+    `${entity}.list(): unknown option ${strangers.map((s) => `\`${s}\``).join(', ')}. ` +
+    `Known options are ${LIST_OPTION_KEYS.join(', ')} — to filter, pass \`where: { ${strangers[0]}: … }\`.`,
+  );
+}
+
+/** Select option — restrict returned fields to those of a SchemaView. */
+export interface SelectOption {
+  select?: SchemaView;
+}
+
+/** Per-entity storage — scoped CRUD operations on a single entity type. */
+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*.
+   */
+  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.
+   */
+  findByKeys(ids: readonly string[], options?: SelectOption): Promise<Map<string, T>>;
+  /** 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. */
+  upsert(input: Partial<T>, options?: SelectOption): Promise<T>;
+  /** 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. */
+  readonly client: unknown;
+}
+
+/**
+ * Factory that creates a Storage for a given entity.
+ * Called by bootstrap for every scanned entity.
+ */
+export type StorageFactory = (entity: SchemaView, name: string) => Storage;
+
+/** 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. */
+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));
+
+  return storageKeyOf(entity) === key && known(entity) ? entity : undefined;
+}
+
+/** 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. */
+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>;
+}
+
+/**
+ * The container key of a frame — `[['Account', 'Ledger'], ['RateMirror']]` →
+ * 'Account+Ledger|RateMirrorTogether'.
+ */
+export function togetherKeyOf(entities: readonly string[], providers: readonly string[] = []): string {
+  const named = entities.map(upperFirst).join(SEPARATOR);
+  return `${named}${providers.length ? KINDS + providers.map(upperFirst).join(SEPARATOR) : ''}${FRAME}`;
+}
+
+const FRAME = 'Together';
+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. */
+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);
+  const split = (list: string) => list.split(SEPARATOR).filter(Boolean);
+  return { entities: split(entities!), providers: split(providers) };
+}