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

package/src/scan/statement.ts

@@ -1,22 +1,4 @@
-/**
- * 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 } from '../descriptor/frond.js';
 import type { ScanResult } from './result.js';
@@ -24,17 +6,9 @@ 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

@@ -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);

package/src/store.ts

@@ -0,0 +1,152 @@
+/** The thirteen gestures of {@link Storage}, derived from four. */
+import { applyCreate, applyUpdate, Lifecycle, Role, type SchemaView } from '@fougere/schema';
+import type { Storage, StorageFactory } from './storage.js';
+
+/** One instance, as every realization hands it over. */
+export type Values = Record<string, unknown>;
+
+/** Instances addressed by key — what an adapter supplies, and all of it. */
+export interface Store {
+  get(key: string): Promise<Values | undefined>;
+  has(key: string): Promise<boolean>;
+  set(key: string, values: Values): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  /** Everything it holds. A realization that cannot answer this cheaply says so in its doc. */
+  all(): Promise<Values[]>;
+  /** Handed on as `Storage.client` — the Map, the directory, whatever it is. */
+  readonly client: unknown;
+}
+
+export function storageOver(open: (entity: SchemaView, name: string) => Store): StorageFactory {
+  return (entity: SchemaView, name: string): Storage => {
+    const fields = entity.getFields();
+    const store = open(entity, name);
+    const pk = Object.entries(fields).find(([, field]) => Role.of(field).isPrimary)?.[0] ?? 'id';
+    // `Storage.findById(id: string)` — but a key can hold a number, and a Map keyed on
+    // `1` does not answer `'1'`. SQL never had the question; here the divergence was
+    // silent and only on this storage.
+    const keyOf = (value: unknown) => String(value);
+    // Same contract as SQL: a criterion may name a SET, and an empty set matches nothing.
+    const matches = (values: Record<string, unknown>, criteria: Record<string, unknown>) =>
+      Object.entries(criteria).every(([key, value]) => Array.isArray(value)
+        ? value.some((v) => Object.is(values[key], v))
+        : Object.is(values[key], value));
+
+    // A store holds whole instances and reads them whole, so the scope SQL puts in its
+    // SELECT is applied here on the way out. Same set of gestures either way: everything
+    // that hands back an instance, which leaves `delete` and `upsertAll` alone.
+    const scoped = (selected?: Set<string>): Storage => {
+      const pick = (values: Values): Values => (selected
+        ? Object.fromEntries(Object.entries(values).filter(([key]) => selected.has(key)))
+        : values);
+
+      return {
+        client: store.client,
+        async list(options?: any) {
+          let items = await store.all();
+          if (options?.where) items = items.filter((values) => matches(values, options.where));
+          // Held before the page is cut, and after the filter: `total` answers "how many
+          // match", which is what a paginator divides. Reading `store.size` at the end
+          // answered a different question — everything the store holds, including the ones
+          // the filter exists to keep out of this caller's sight.
+          const matching = items.length;
+          const limit = options?.limit;
+          const offset = options?.page && limit ? (options.page - 1) * limit : options?.offset ?? 0;
+          if (offset > 0) items = items.slice(offset);
+          const hasMore = limit ? items.length > limit : false;
+          if (limit) items = items.slice(0, limit);
+          // The cursor is read before the scope cuts: a view that drops the key still
+          // pages, the way it does over SQL.
+          const endCursor = items.length > 0 ? String((items[items.length - 1] as any)[pk] ?? '') : undefined;
+          const result = items.map(pick) as any;
+          result.hasMore = hasMore;
+          result.endCursor = endCursor;
+          if (options?.count) result.total = matching;
+          return result;
+        },
+        async findById(id: string) {
+          const values = await store.get(keyOf(id));
+          return values && pick(values);
+        },
+        async findBy(criteria: Record<string, unknown>) {
+          const values = (await store.all()).find((held) => matches(held, criteria));
+          return values && pick(values);
+        },
+        async findAllBy(criteria: Record<string, unknown>) {
+          return (await store.all()).filter((values) => matches(values, criteria)).map(pick);
+        },
+        // Same contract as SQL: a map keyed by the primary key, a miss being an absent key.
+        async findByKeys(ids: readonly string[]) {
+          const found = new Map<string, Record<string, unknown>>();
+          for (const id of ids) {
+            const values = await store.get(keyOf(id));
+            if (values) found.set(String(id), pick(values));
+          }
+          return found;
+        },
+        // The dual, same contract as SQL: grouped by the value read off the instance.
+        async findAllByKeys(field: string, keys: readonly string[]) {
+          const grouped = new Map<string, Record<string, unknown>[]>();
+          if (keys.length === 0) return grouped;
+          const wanted = new Set(keys.map(String));
+          for (const values of await store.all()) {
+            const key = String(values[field]);
+            if (!wanted.has(key)) continue;
+            const bucket = grouped.get(key);
+            if (bucket) bucket.push(pick(values)); else grouped.set(key, [pick(values)]);
+          }
+          return grouped;
+        },
+        // Same contract as SQL: the key and the creation stamps survive an overwrite.
+        async upsert(input: Partial<Record<string, unknown>>) {
+          const values = applyCreate(fields, applyUpdate(fields, input));
+          const id = values[pk] as string | undefined;
+          if (id === undefined) throw new Error(`${name}.upsert(): no \`${pk}\` — an upsert needs the key it writes at.`);
+          const previous = await store.get(keyOf(id));
+          if (previous) {
+            for (const [key, field] of Object.entries(fields)) {
+              if (key === pk || Lifecycle.of(field).stampedOnce) values[key] = previous[key];
+            }
+          }
+          await store.set(keyOf(id), values);
+          return pick(values);
+        },
+        async upsertAll(inputs: readonly Partial<Record<string, unknown>>[]) {
+          for (const input of inputs) await this.upsert(input);
+          return inputs.length;
+        },
+        async create(input: Partial<Record<string, unknown>>) {
+          const values = applyCreate(fields, input);
+          const id = values[pk] as string | undefined;
+          // `primary(text())` declares no generator, so nothing fills the hole and the
+          // caller has to. Keying on `undefined` would let the second create overwrite the
+          // first, in silence — the old version hid this by inventing an `id` field the
+          // entity never declared.
+          if (id === undefined) {
+            throw new Error(`${name}.create: '${pk}' is the primary key and nothing supplied it — this entity declares no generator for it.`);
+          }
+          // A create is not an upsert. `Map.set` overwrites, so a second create under the
+          // same key answered "created" while destroying the previous instance — SQL answers a
+          // constraint violation, and a store that loses data silently is worse than one
+          // that fails.
+          if (await store.has(keyOf(id))) {
+            throw new Error(`${name}.create: '${pk}' ${JSON.stringify(id)} already exists.`);
+          }
+          await store.set(keyOf(id), values);
+          return pick(values);
+        },
+        async update(id: string, input: Partial<Record<string, unknown>>) {
+          const existing = await store.get(keyOf(id));
+          if (!existing) throw new Error(`Not found: ${id}`);
+          const updated = { ...existing, ...applyUpdate(fields, input), [pk]: existing[pk] };
+          await store.set(keyOf(id), updated);
+          return pick(updated);
+        },
+        async delete(id: string) { return await store.delete(keyOf(id)); },
+        output(schema: SchemaView) { return scoped(new Set(Object.keys(schema.getFields()))); },
+      };
+    };
+
+    return scoped();
+  };
+}