@johnhenry/graceholder 0.0.0-stage → 0.1.0

package/src/key.js

@@ -0,0 +1,30 @@
+// Key string (scheme gh1) -> hash -> local stream. FROZEN at 1.0.0 (docs/design.md 2.2).
+import { xxh64 } from "./xxh64.js";
+import { Stream } from "./rng.js";
+
+export const KEY_SCHEME = "gh1";
+const SEP = "\x1f";
+const SCOPES = new Set(["e", "l", "p", "a"]);
+const encoder = new TextEncoder();
+
+const clean = (v) => String(v).replaceAll(SEP, "�");
+
+/**
+ * @param {{ seed: string|number, scope: "e"|"l"|"p"|"a", typeName: string, entityKey: string,
+ *           fieldName: string, subKeys?: Array<string|number> }} p
+ */
+export function keyString(p) {
+  if (!SCOPES.has(p.scope)) throw new RangeError(`unknown key scope ${JSON.stringify(p.scope)}`);
+  const parts = [KEY_SCHEME, p.seed, p.scope, p.typeName, p.entityKey, p.fieldName, ...(p.subKeys ?? [])];
+  return parts.map(clean).join(SEP);
+}
+
+/** @returns {bigint} XXH64 (seed 0) of the UTF-8 key string */
+export function hashKey(p) {
+  return xxh64(encoder.encode(keyString(p)), 0n);
+}
+
+/** @returns {Stream} the SplitMix64 stream for this key */
+export function keyStream(p) {
+  return new Stream(hashKey(p));
+}

package/src/learn.js

@@ -0,0 +1,397 @@
+// specFromSamples: learn a side-car spec from real responses (docs/design.md section 18).
+// Pure and deterministic: the same query, samples and options give the same spec. It reads formats
+// and statistics, never free text: see the privacy rules in section 18.2.
+import { Kind, isEnumType } from "graphql";
+import { GraceholderError } from "./errors.js";
+import { infer } from "./infer.js";
+import { anchorMs as parseAnchor, DEFAULT_ANCHOR } from "./anchor.js";
+import { compileSpec } from "./spec.js";
+import { PAGING_ARGS } from "./args.js";
+
+const DAY_MS = 86400000;
+const YEAR_DAYS = 365.25;
+const bad = (msg, path) => new GraceholderError("bad-samples", msg, path === undefined ? undefined : { path });
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const r3 = (x) => Math.round(x * 1000) / 1000;
+const byText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+/** Generators whose value is the identity of the entity or computed from the graph: never learned. */
+const KEEP = new Set(["id.key", "id.int", "count.of", "order.subtotal", "order.tax", "order.total"]);
+/** Generators that stand for personal data: enum-like or not, their values are never copied. */
+const PERSONAL = new Set(["person.first", "person.last", "person.full", "person.username", "person.phone", "person.bio"]);
+/** Generators that stand for free text: a learned length range replaces them. */
+const TEXTISH = new Set(["word", "words", "sentence", "sentences", "paragraph", "lorem", "title", "person.bio", "text"]);
+/** Coherent date generators and the window of days before the anchor they can produce. */
+const COHERENT_DAYS = {
+  "time.created": [30, 1500], "time.updated": [0, 1500], "time.published": [0, 1500],
+  "time.birthday": [18 * YEAR_DAYS, 90 * YEAR_DAYS + 364],
+};
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const EMAIL = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+const URL_RE = /^https?:\/\/[^\s]+$/i;
+const IMAGE_URL = /\.(?:png|jpe?g|gif|webp|svg|avif)(?:\?[^\s]*)?$/i;
+const IPV4 = /^(?:25[0-5]|2[0-4]\d|1?\d?\d)(?:\.(?:25[0-5]|2[0-4]\d|1?\d?\d)){3}$/;
+const ISO_DATETIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?$/;
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+/** Response key -> merged field nodes of one selection list, looking through fragments. */
+function collectFields(selections, fragments, out = new Map()) {
+  for (const sel of selections) {
+    if (sel.kind === Kind.FIELD) {
+      const name = sel.name.value;
+      if (name.startsWith("__")) continue;
+      const key = sel.alias?.value ?? name;
+      const entry = out.get(key) ?? { key, name, selections: [], hasSelection: false };
+      if (sel.selectionSet) {
+        entry.hasSelection = true;
+        entry.selections.push(...sel.selectionSet.selections);
+      }
+      out.set(key, entry);
+    } else if (sel.kind === Kind.INLINE_FRAGMENT) {
+      collectFields(sel.selectionSet.selections, fragments, out);
+    } else if (sel.kind === Kind.FRAGMENT_SPREAD) {
+      collectFields(fragments.get(sel.name.value).selectionSet.selections, fragments, out);
+    }
+  }
+  return out;
+}
+
+function normalizeSamples(samples, rootKeys) {
+  const list = Array.isArray(samples) ? samples : [samples];
+  if (list.length === 0) throw bad("specFromSamples needs at least one sample response");
+  return list.map((s, i) => {
+    if (!isObject(s)) throw bad(`sample ${i} must be an object (a response's data, or { data })`);
+    if (Object.hasOwn(s, "data") && !rootKeys.has("data")) {
+      if (!isObject(s.data)) throw bad(`sample ${i} has no data${s.errors ? " (it has errors)" : ""}`);
+      return s.data;
+    }
+    return s;
+  });
+}
+
+class Acc {
+  constructor(path, info) {
+    this.path = path;
+    this.info = info;
+    this.present = 0; // parent instances that had the key
+    this.nulls = 0;
+    this.sizes = []; // list lengths, one per instance holding a list
+    this.values = []; // non-null scalar values, flattened across instances and list elements
+    this.sawList = false;
+    this.sawSingle = false;
+    this.opaque = false; // an object where a scalar was selected (a JSON scalar)
+  }
+}
+
+function walkSamples(ctx, selections, parentPath, instances) {
+  for (const f of collectFields(selections, ctx.fragments).values()) {
+    const path = parentPath ? `${parentPath}.${f.name}` : f.name;
+    let acc = ctx.accs.get(path);
+    if (!acc) {
+      acc = new Acc(path, ctx.byPath.get(path));
+      ctx.accs.set(path, acc);
+    }
+    const children = [];
+    for (const inst of instances) {
+      if (!Object.hasOwn(inst, f.key)) continue;
+      const v = inst[f.key];
+      acc.present++;
+      if (v === null) {
+        acc.nulls++;
+        continue;
+      }
+      if (Array.isArray(v)) {
+        acc.sawList = true;
+        acc.sizes.push(v.length);
+        for (const e of v) {
+          if (e === null) continue;
+          if (f.hasSelection) {
+            if (!isObject(e)) throw bad(`${path}: the query selects sub-fields, but a list element is ${typeof e}`, path);
+            children.push(e);
+          } else if (isObject(e) || Array.isArray(e)) acc.opaque = true;
+          else acc.values.push(e);
+        }
+      } else {
+        acc.sawSingle = true;
+        if (f.hasSelection) {
+          if (!isObject(v)) throw bad(`${path}: the query selects sub-fields, but the sample has ${typeof v}`, path);
+          children.push(v);
+        } else if (isObject(v)) acc.opaque = true;
+        else acc.values.push(v);
+      }
+    }
+    if (f.hasSelection && children.length) walkSamples(ctx, f.selections, path, children);
+  }
+}
+
+// --- value learning ----------------------------------------------------------------------------
+
+const decimalsOf = (v) => {
+  const t = String(v);
+  if (/e/i.test(t)) return 6;
+  const i = t.indexOf(".");
+  return Math.min(8, i < 0 ? 0 : t.length - i - 1);
+};
+
+/** Pattern (docs/design.md 18.3) for same-length ASCII strings, or null when they do not share a format. */
+export function shapePattern(values) {
+  const len = values[0].length;
+  if (len === 0 || len > 64 || values.some((v) => v.length !== len)) return null;
+  if (values.some((v) => !/^[\x21-\x7e]+$/.test(v))) return null;
+  const distinct = new Set(values).size;
+  const cls = (c) => (/[0-9]/.test(c) ? "d" : /[a-z]/.test(c) ? "l" : /[A-Z]/.test(c) ? "u" : "o");
+  const slots = [];
+  for (let i = 0; i < len; i++) {
+    const chars = new Set(values.map((v) => v[i]));
+    const classes = new Set([...chars].map(cls));
+    if (chars.size === 1) {
+      const c = [...chars][0];
+      slots.push({ kind: cls(c) === "o" ? "lit" : "const", c, cls: cls(c) });
+    } else if (classes.size === 1) {
+      const k = [...classes][0];
+      if (k === "o") return null; // different punctuation in one place: not a format
+      slots.push({ kind: "class", cls: k });
+    } else if (classes.has("o")) {
+      return null;
+    } else {
+      slots.push({ kind: "class", cls: "x" }); // letters and digits mixed
+    }
+  }
+  // a constant alphabetic prefix of up to 5 letters, followed by a digit or a separator, is part of the format
+  let prefix = 0;
+  if (distinct >= 2) {
+    while (prefix < len && slots[prefix].kind === "const" && /[A-Za-z]/.test(slots[prefix].c)) prefix++;
+    const next = slots[prefix];
+    if (prefix > 5 || prefix === len || !(next.cls === "d" || next.cls === "o")) prefix = 0;
+  }
+  const hasDigit = values.some((v) => /[0-9]/.test(v));
+  const hasLiteral = slots.some((s) => s.kind === "lit");
+  const allUpper = len >= 2 && values.every((v) => /^[A-Z]+$/.test(v));
+  if (!(hasDigit || hasLiteral || allUpper)) return null;
+  if (distinct === 1 && !hasDigit) return null;
+  const escape = (c) => (/[#?A*\\]/.test(c) ? `\\${c}` : c);
+  return slots
+    .map((s, i) => {
+      if (s.kind === "lit") return escape(s.c);
+      if (s.kind === "const" && i < prefix) return escape(s.c);
+      const k = s.cls;
+      return k === "d" ? "#" : k === "l" ? "?" : k === "u" ? "A" : "*";
+    })
+    .join("");
+}
+
+function learnValues(ctx, acc) {
+  const { path, info } = acc;
+  const values = acc.values;
+  const note = (kind, message) => ctx.notes.push({ path, kind, message });
+  if (info.ovSrc?.gen === "directive") return note("skipped", "a directive on the field already sets its generator"), null;
+  if (info.derive !== undefined) return note("kept-heuristic", "derived fields follow their source"), null;
+  const heur = info.gen;
+  if (KEEP.has(heur)) return note("kept-heuristic", `${heur} supplies identifiers and aggregates; the entity graph keeps them consistent`), null;
+  const named = info.schema?.named;
+  if (values.every((v) => typeof v === "boolean")) {
+    return { gen: { name: "bool", args: { p: r3(values.filter(Boolean).length / values.length) } } };
+  }
+  if (values.every((v) => typeof v === "number" && Number.isFinite(v))) return learnNumbers(values, named?.name, note);
+  if (values.every((v) => typeof v === "string")) return learnStrings(ctx, acc, values, heur, note);
+  return note("skipped", "values of mixed types"), null;
+}
+
+function learnNumbers(values, declared, note) {
+  let min = values[0];
+  let max = values[0];
+  for (const v of values) {
+    if (v < min) min = v;
+    if (v > max) max = v;
+  }
+  const integral = declared === "Int" ? true : declared === "Float" ? false : values.every(Number.isInteger);
+  if (integral) {
+    if (!Number.isSafeInteger(min) || !Number.isSafeInteger(max)) return note("skipped", "integers outside the safe range"), null;
+    return { gen: { name: "int", args: { min, max } } };
+  }
+  return { gen: { name: "float", args: { min, max, decimals: Math.max(...values.map(decimalsOf)) } } };
+}
+
+function learnStrings(ctx, acc, values, heur, note) {
+  const named = acc.info.schema?.named;
+  const counts = new Map();
+  for (const v of values) counts.set(v, (counts.get(v) ?? 0) + 1);
+  const n = values.length;
+  const d = counts.size;
+
+  // a schema enum: the values are public, only their frequencies come from the data
+  if (named && isEnumType(named)) {
+    const allowed = new Set(named.getValues().map((v) => v.name));
+    const stray = values.find((v) => !allowed.has(v));
+    if (stray !== undefined) throw bad(`${acc.path}: ${JSON.stringify(stray)} is not a value of the enum ${named.name}`, acc.path);
+    return { pick: weighted(counts) };
+  }
+
+  if (values.every((v) => UUID.test(v))) return { gen: "id.uuid" };
+  if (values.every((v) => EMAIL.test(v))) return { gen: "person.email" };
+  if (values.every((v) => URL_RE.test(v))) return { gen: values.every((v) => IMAGE_URL.test(v)) ? "imageUrl" : "url" };
+  if (values.every((v) => IPV4.test(v))) return { gen: "ip" };
+  const dates = learnDates(ctx, values, heur, note);
+  if (dates !== undefined) return dates;
+
+  const constantCase = values.every((v) => /^[A-Z][A-Z_]+$/.test(v));
+  const enumLike = values.every((v) => v.length <= 40) && ((d <= ctx.maxEnum && n >= 2 * d) || (constantCase && d <= 24));
+  if (enumLike && ctx.allows(acc.path)) {
+    if (PERSONAL.has(heur)) return note("withheld", `${heur} stands for personal data; its values are never copied`), null;
+    return { pick: weighted(counts) };
+  }
+  const hasDigit = values.some((v) => /[0-9]/.test(v));
+  if (enumLike && !hasDigit) {
+    return note("withheld", `${d} distinct value(s) look like an enumeration; pass allowValues to copy them`), null;
+  }
+
+  const len = values[0].length;
+  if (len >= 8 && values.every((v) => v.length === len && /^[0-9a-f]+$/.test(v)) && values.some((v) => /[a-f]/.test(v)) && values.some((v) => /[0-9]/.test(v))) {
+    return { gen: { name: "hex", args: { length: len } } };
+  }
+  if (values.every((v) => /^[0-9]+$/.test(v))) {
+    if (values.every((v) => v.length === len)) return { pattern: "#".repeat(len) };
+    const nums = values.map(Number);
+    if (nums.every(Number.isSafeInteger)) return { gen: { name: "id.int", args: { min: Math.min(...nums), max: Math.max(...nums), string: true } } };
+  }
+  const shape = shapePattern(values);
+  if (shape !== null) return { pattern: shape };
+
+  if (TEXTISH.has(heur)) {
+    let min = Infinity;
+    let max = 0;
+    for (const v of values) {
+      if (v.length < min) min = v.length;
+      if (v.length > max) max = v.length;
+    }
+    return { gen: { name: "text", args: { min, max } } };
+  }
+  return note("kept-heuristic", `free text is never copied; the ${heur} heuristic stays`), null;
+}
+
+/** Counts as `{ value, weight }` objects (most common first), or plain values when all are equally common. */
+function weighted(counts) {
+  const entries = [...counts].sort((a, b) => b[1] - a[1] || byText(a[0], b[0]));
+  if (entries.every(([, c]) => c === entries[0][1])) return entries.map(([v]) => v).sort(byText);
+  return entries.map(([value, weight]) => ({ value, weight }));
+}
+
+/** ISO date-times and dates as a datetime range relative to the anchor; undefined when the values are not dates. */
+function learnDates(ctx, values, heur, note) {
+  let dateOnly = true;
+  const times = [];
+  for (const v of values) {
+    const dt = ISO_DATETIME.exec(v);
+    if (dt) {
+      dateOnly = false;
+      times.push(Date.parse(dt[1] ? v : `${v}Z`));
+    } else if (ISO_DATE.test(v)) {
+      times.push(Date.parse(v));
+    } else return undefined;
+  }
+  if (times.some((t) => !Number.isFinite(t))) return undefined;
+  let lo = times[0];
+  let hi = times[0];
+  for (const t of times) {
+    if (t < lo) lo = t;
+    if (t > hi) hi = t;
+  }
+  const minDaysAgo = Math.floor((ctx.anchorMs - hi) / DAY_MS);
+  const maxDaysAgo = Math.ceil((ctx.anchorMs - lo) / DAY_MS);
+  const window = COHERENT_DAYS[heur];
+  if (window && minDaysAgo >= window[0] && maxDaysAgo <= window[1]) {
+    return note("kept-heuristic", `${heur} keeps dates coherent with the entity's other dates and already covers this range`), null;
+  }
+  const args = { minDaysAgo, maxDaysAgo };
+  if (dateOnly) args.format = "date";
+  return { gen: { name: "datetime", args } };
+}
+
+// --- emission ----------------------------------------------------------------------------------
+
+/**
+ * Like {@link specFromSamples}, but also returns the notes explaining what was withheld or kept.
+ * @param {string|import("graphql").DocumentNode} query
+ * @param {any} samples one response or an array of responses (`data` objects or `{ data }`)
+ * @param {{ schema?: any, allowValues?: boolean|string[], maxEnum?: number, anchorDate?: string|Date, operationName?: string, variables?: Record<string, unknown> }} [opts]
+ * @returns {{ spec: Record<string, any>, notes: { path: string, kind: string, message: string }[] }}
+ */
+export function analyzeSamples(query, samples, opts = {}) {
+  const { allowValues = false, maxEnum = 12 } = opts;
+  if (typeof allowValues !== "boolean" && !(Array.isArray(allowValues) && allowValues.every((p) => typeof p === "string"))) {
+    throw new GraceholderError("bad-options", "allowValues must be a boolean or an array of field paths");
+  }
+  if (!Number.isInteger(maxEnum) || maxEnum < 1) throw new GraceholderError("bad-options", "maxEnum must be a positive integer");
+  const anchorMs = parseAnchor(opts.anchorDate ?? DEFAULT_ANCHOR);
+  const inferred = infer(query, { operationName: opts.operationName, variables: opts.variables, schema: opts.schema });
+  const fragments = new Map(inferred.document.definitions.filter((d) => d.kind === Kind.FRAGMENT_DEFINITION).map((d) => [d.name.value, d]));
+  const op = /** @type {import("graphql").OperationDefinitionNode} */ (inferred.document.definitions.find((d) => d.kind === Kind.OPERATION_DEFINITION));
+  const rootKeys = new Set(collectFields(op.selectionSet.selections, fragments).keys());
+  const instances = normalizeSamples(samples, rootKeys);
+
+  const ctx = {
+    fragments, byPath: inferred.byPath, accs: new Map(), notes: /** @type {{ path: string, kind: string, message: string }[]} */ ([]), anchorMs, maxEnum,
+    allows: (path) => allowValues === true || (Array.isArray(allowValues) && allowValues.includes(path)),
+  };
+  walkSamples(ctx, op.selectionSet.selections, "", instances);
+
+  const spec = {};
+  for (const acc of ctx.accs.values()) {
+    const { info, path } = acc;
+    if (!info || info.synthetic) continue;
+    const entry = {};
+    const fromDirective = (prop) => info.ovSrc?.[prop] === "directive";
+    const sch = info.schemaSourced ? info.schema : null;
+    if (acc.sawList && acc.sawSingle) throw bad(`${path}: the samples have a list in some responses and a single value in others`, path);
+    if (sch) {
+      if (acc.sawList && !sch.list && !info.connection) throw bad(`${path}: a sample has a list, but the schema declares ${String(sch.def.type)}`, path);
+      if (acc.sawSingle && sch.list) throw bad(`${path}: a sample has a single value, but the schema declares ${String(sch.def.type)}`, path);
+      if (acc.nulls > 0 && sch.nonNull) throw bad(`${path}: a sample has null, but the schema declares ${String(sch.def.type)}`, path);
+    } else if (!info.connection && (acc.sawList || acc.sawSingle) && acc.sawList !== info.list && !fromDirective("list")) {
+      entry[acc.sawList ? "list" : "one"] = true;
+    }
+    if (acc.sawList && !info.connection) {
+      const paged = [...info.args.keys()].some((a) => PAGING_ARGS.has(a) || a === "skip" || a === "take");
+      if (paged) ctx.notes.push({ path, kind: "skipped", message: "a paged list: the page size comes from the query, not the collection" });
+      else if (!fromDirective("count")) {
+        const min = Math.min(...acc.sizes);
+        const max = Math.max(...acc.sizes);
+        entry.count = min === max ? min : [min, max];
+      }
+    }
+    if (info.connection) {
+      const totals = ctx.accs.get(`${path}.totalCount`)?.values.filter((v) => Number.isInteger(v) && v >= 0) ?? [];
+      if (totals.length && !fromDirective("count")) {
+        const min = Math.min(...totals);
+        const max = Math.max(...totals);
+        entry.count = min === max ? min : [min, max];
+      } else if (!totals.length) ctx.notes.push({ path, kind: "skipped", message: "a connection without totalCount: its size is unknown" });
+    }
+    if (acc.nulls > 0 && acc.present > 0 && !fromDirective("nullRate")) {
+      entry.nullRate = acc.nulls === acc.present ? 1 : Math.max(0.001, r3(acc.nulls / acc.present));
+    }
+    if (info.kind === "scalar" && acc.values.length > 0 && !acc.opaque) {
+      const learned = learnValues(ctx, acc);
+      if (learned) Object.assign(entry, learned);
+    }
+    if (Object.keys(entry).length) spec[path] = entry;
+  }
+  compileSpec(spec); // what we hand back must be a valid spec
+  return { spec, notes: ctx.notes };
+}
+
+/**
+ * Infer a side-car spec from real responses to a query.
+ *
+ * Learns list sizes (`count`), null rates (`nullRate`), integer and float ranges, boolean ratios,
+ * date ranges, string lengths and ID/code formats (`pattern`). Free text is never copied: enum-like
+ * value sets only appear in the spec when `allowValues` permits (or when the schema declares the enum).
+ * @param {string|import("graphql").DocumentNode} query
+ * @param {any} samples one response or an array of responses (`data` objects or `{ data }`)
+ * @param {{ schema?: any, allowValues?: boolean|string[], maxEnum?: number, anchorDate?: string|Date, operationName?: string, variables?: Record<string, unknown> }} [opts]
+ * @returns {Record<string, any>} a plain spec object, ready to commit
+ */
+export function specFromSamples(query, samples, opts = {}) {
+  return analyzeSamples(query, samples, opts).spec;
+}

package/src/naming.js

@@ -0,0 +1,74 @@
+// Name tokenising, singularising and type-name derivation (docs/design.md 4.2). FROZEN at 1.0.0.
+
+/** Split a field or type name into lowercase words. */
+export function tokenize(name) {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((t) => t.toLowerCase());
+}
+
+const IRREGULAR = new Map([
+  ["people", "person"], ["men", "man"], ["women", "woman"], ["children", "child"], ["mice", "mouse"],
+  ["feet", "foot"], ["teeth", "tooth"], ["geese", "goose"], ["analyses", "analysis"], ["indices", "index"],
+  ["criteria", "criterion"], ["knives", "knife"], ["wives", "wife"], ["leaves", "leaf"], ["lives", "life"],
+  ["shelves", "shelf"], ["wolves", "wolf"], ["data", "data"],
+  // -ie words that the generic ies->y rule would turn into -y
+  ["movies", "movie"], ["cookies", "cookie"], ["pies", "pie"], ["ties", "tie"], ["lies", "lie"],
+  ["zombies", "zombie"], ["selfies", "selfie"], ["rookies", "rookie"], ["calories", "calorie"],
+  ["species", "species"], ["series", "series"],
+]);
+
+/** Singularise one lowercase word. Rules in order, first match wins. */
+export function singularize(word) {
+  const irregular = IRREGULAR.get(word);
+  if (irregular !== undefined) return irregular;
+  if (/[^aeiou]ies$/.test(word)) return word.slice(0, -3) + "y";
+  if (/(ss|x|ch|sh)es$/.test(word)) return word.slice(0, -2);
+  if (/(ss|us|is)$/.test(word)) return word;
+  if (word.endsWith("s")) return word.slice(0, -1);
+  return word;
+}
+
+export const pascal = (tokens) => tokens.map((t) => t[0].toUpperCase() + t.slice(1)).join("");
+
+/** Names a derived object type may not take (N5). */
+const RESERVED = new Set(["Int", "Float", "String", "Boolean", "ID", "DateTime", "Query", "Mutation", "Subscription"]);
+
+/** N3 + N5: singularise the last word of the field name, PascalCase, avoid collisions. */
+export function typeNameFor(fieldName) {
+  const tokens = tokenize(fieldName);
+  if (tokens.length === 0) return "Object";
+  tokens[tokens.length - 1] = singularize(tokens[tokens.length - 1]);
+  let name = pascal(tokens);
+  if (/^[0-9]/.test(name)) name = "T" + name;
+  return RESERVED.has(name) ? name + "Type" : name;
+}
+
+const KINDS = [
+  ["person", ["user", "person", "customer", "author", "member", "employee", "contact", "account", "profile", "owner", "student", "patient", "driver", "guest", "reviewer", "commenter", "friend", "follower", "manager", "admin"]],
+  ["org", ["company", "organization", "org", "team", "brand", "vendor", "store", "shop", "employer"]],
+  ["product", ["product", "item", "sku", "listing"]],
+  ["post", ["post", "article", "comment", "message", "review", "note", "story"]],
+  ["order", ["order", "invoice", "cart", "payment", "receipt"]],
+];
+
+/** Persona kind of a type name (docs/design.md 6.1): first kind with a matching token wins. */
+export function personaKind(typeName) {
+  const tokens = tokenize(typeName);
+  for (const [kind, words] of KINDS) if (tokens.some((t) => words.includes(t))) return kind;
+  return "generic";
+}
+
+const PLURALS = new Map([["person", "people"], ["man", "men"], ["woman", "women"], ["child", "children"], ["mouse", "mice"], ["foot", "feet"], ["tooth", "teeth"], ["goose", "geese"]]);
+
+/** Plural of one lowercase word (used to name a collection that is counted but not selected). */
+export function pluralize(word) {
+  const irregular = PLURALS.get(word);
+  if (irregular) return irregular;
+  if (/[^aeiou]y$/.test(word)) return word.slice(0, -1) + "ies";
+  if (/(s|x|z|ch|sh)$/.test(word)) return word + "es";
+  return word + "s";
+}

package/src/pack-registry.js

@@ -0,0 +1,59 @@
+// Vocabulary packs (docs/design.md section 17). A pack is plain data plus functions:
+//   { name, version, vocab, types?, generators(V, base), rules?(ctx), inherit?(typeName) }
+// Packs live in separate modules (`@johnhenry/graceholder/packs/<name>`) so an application only
+// ships the ones it imports. `registerPack` makes a pack addressable by name in `options.packs`.
+import { GraceholderError } from "./errors.js";
+
+const NAME = /^[a-z][a-z0-9-]*$/;
+/** name -> pack object, for packs registered with registerPack */
+const REGISTERED = new Map();
+/** name -> the one pack object that has used this name (registered or passed directly) */
+const SEEN = new Map();
+
+const bad = (msg, hint) => new GraceholderError("bad-pack", msg, hint ? { hint } : undefined);
+
+function validate(pack) {
+  if (pack === null || typeof pack !== "object") throw bad("a pack must be an object");
+  if (typeof pack.name !== "string" || !NAME.test(pack.name)) throw bad(`pack name must match ${NAME}, got ${JSON.stringify(pack.name)}`);
+  if (typeof pack.generators !== "function") throw bad(`pack ${pack.name}: generators must be a function (V, base) => ({ name: (ctx) => value })`);
+  if (pack.rules !== undefined && typeof pack.rules !== "function") throw bad(`pack ${pack.name}: rules must be a function`);
+  if (pack.inherit !== undefined && typeof pack.inherit !== "function") throw bad(`pack ${pack.name}: inherit must be a function`);
+  const seen = SEEN.get(pack.name);
+  if (seen && seen !== pack) throw bad(`a different pack named ${JSON.stringify(pack.name)} is already in use`, "pack names are global; pick another name");
+  SEEN.set(pack.name, pack);
+}
+
+/** Register a pack so `options.packs` can name it. Registering the same pack twice is fine. */
+export function registerPack(pack) {
+  validate(pack);
+  REGISTERED.set(pack.name, pack);
+  return pack;
+}
+
+/** Names of the registered packs. */
+export function registeredPacks() {
+  return [...REGISTERED.keys()];
+}
+
+/**
+ * Resolve `options.packs` (names and/or pack objects) to pack objects, in order, without duplicates.
+ * @returns {any[]}
+ */
+export function resolvePacks(list) {
+  if (list === undefined) return [];
+  if (!Array.isArray(list)) throw new GraceholderError("bad-options", "packs must be an array of pack names or pack objects");
+  const out = [];
+  for (const item of list) {
+    let pack = item;
+    if (typeof item === "string") {
+      pack = REGISTERED.get(item);
+      if (!pack) {
+        throw new GraceholderError("unknown-pack", `unknown pack ${JSON.stringify(item)}`, {
+          hint: `registered: ${registeredPacks().join(", ") || "(none)"}. Import it from "@johnhenry/graceholder/packs/${item}" and pass the object, or call registerPack()`,
+        });
+      }
+    } else validate(item);
+    if (!out.includes(pack)) out.push(pack);
+  }
+  return out;
+}

package/src/packs/PROVENANCE.md

@@ -0,0 +1,26 @@
+# Pack vocabulary provenance
+
+Everything in `geo.js`, `commerce.js`, `finance.js` and `health.js` was written by hand for this
+project and is contributed under the repository's MIT licence. No file was copied from, or generated
+from, a third-party dataset (in particular not from faker, whose data files are not used).
+
+- **geo.** City, region, country, time zone, postal-code and area-code facts are public, uncopyrightable
+  facts typed in by hand; coordinates are approximate city centres rounded to 0.01 degree and are
+  placeholders, not for navigation. Time zones are IANA names. Phone templates use each country's calling
+  code; the US and Canada use the fictional `555-01xx` block, the United Kingdom the Ofcom drama ranges
+  (`020 7946 0xxx`, `0161 496 0xxx`, ...) and Australia the ACMA `5550 xxxx` block. Paris uses `01 99 00 xx xx`, which is believed to be France's reserved fiction range but was not checked against a source.
+  Other countries' templates are well-formed but not guaranteed unassigned. Cities are real, so use them
+  as place names only.
+- **commerce.** Categories, product nouns and adjectives are ordinary English words. Brand names are
+  invented; any resemblance to a trademark is coincidental.
+- **finance.** Currency codes, names, symbols and minor units follow ISO 4217. IBAN lengths and layouts
+  follow ISO 13616 / the SWIFT IBAN registry; the check digits are computed (ISO 7064 mod 97-10) and
+  verified in tests against published example IBANs. Card number prefixes (4, 51-55, 34/37) and the Luhn
+  check are the public conventions; the ABA 3-7-1 weights are the published routing-number checksum.
+  Merchants are invented.
+- **health.** Every condition and medication name is invented and obviously whimsical; none is a real
+  diagnosis or drug. Specialty names are ordinary category words. Nothing is medical information. A test
+  rejects a deny list of real diagnoses and drug-name endings.
+
+All tables are order-frozen (values are chosen by index), so any edit, reorder or append is an output
+change. `test/packs.test.js` asserts a SHA-256 checksum of every table.

package/src/packs/commerce.d.ts

@@ -0,0 +1,4 @@
+import type { Pack } from "../index.js";
+/** The commerce pack. Import from "@johnhenry/graceholder/packs/commerce". */
+export declare const commerce: Pack;
+export default commerce;