@johnhenry/graceholder 0.0.0-stage → 0.1.0

package/src/vocab/PROVENANCE.md

@@ -0,0 +1,12 @@
+# Vocabulary provenance
+
+`en.js` is hand-written for this project. Names (including a few accented ones that exercise ASCII folding) are common given names and surnames of
+mixed origin; none is a list copied from a third-party dataset. Places are real, generic
+town names with state/province, ISO-style code and a three-character postal prefix; they
+are not addresses. Lorem words are the classical public-domain ipsum list. Domains use the
+reserved `example.*` names. Everything here is contributed under the repository's MIT
+licence and is original or public domain.
+
+The tables are order-frozen: values are selected by index, so any edit, reorder or
+append is an output change (see docs/design.md sections 7.1 and 11). `test/vocab.test.js`
+asserts a SHA-256 checksum of every table.

package/src/vocab/en.js

@@ -0,0 +1,106 @@
+// Vendored "en" vocabulary. FROZEN at 1.0.0: tables are indexed by position, so
+// any edit, reorder or append changes generated output (docs/design.md 7.1, 11).
+// All content is original or public domain; see PROVENANCE.md.
+
+const freeze = (o) => {
+  if (o !== null && typeof o === "object") for (const v of Object.values(o)) freeze(v);
+  return Object.freeze(o);
+};
+
+export const en = freeze({
+  firstNames: [
+    "Ada", "Alan", "Amara", "Andre", "Anika", "Arjun", "Beatrix", "Bruno", "Camila", "Carlos",
+    "Chiara", "Dana", "Darius", "Elena", "Emeka", "Farah", "Felix", "Fiona", "Gabriel", "Grace",
+    "Hana", "Hector", "Ines", "Isaac", "Jamal", "Jasmine", "Joaquin", "Julia", "Kai", "Keiko",
+    "Lena", "Leo", "Linnea", "Lucas", "Maya", "Mateo", "Mei", "Miles", "Nadia", "Noah",
+    "Olga", "Omar", "Priya", "Quentin", "Rafael", "Rosa", "Sana", "Samuel", "Tessa", "Theo",
+    "Uma", "Victor", "Wanda", "Wei", "Xavier", "Yara", "Yusuf", "Zara", "Zoe", "Ibrahim",
+    "Harriet", "Ngozi", "Tomas", "Sofia",
+    "Jos\u00e9", "Zo\u00eb", "S\u00f8ren", "Ren\u00e9e", "\u00c5sa", "Chlo\u00e9",
+  ],
+  lastNames: [
+    "Abbott", "Adeyemi", "Alvarez", "Andersson", "Bauer", "Bennett", "Brooks", "Castillo", "Chen", "Cohen",
+    "Dalton", "Dubois", "Eriksen", "Fischer", "Flores", "Garcia", "Gupta", "Hansen", "Haruna", "Hughes",
+    "Ibarra", "Jensen", "Kapoor", "Keller", "Kim", "Larsen", "Lopez", "Marsh", "Mbeki", "Moreau",
+    "Nakamura", "Novak", "Okafor", "Olsen", "Ortega", "Patel", "Petrov", "Quinn", "Ramos", "Reyes",
+    "Rossi", "Saito", "Santos", "Schmidt", "Silva", "Singh", "Tanaka", "Torres", "Underwood", "Vega",
+    "Wagner", "Whitfield", "Wright", "Xu", "Yamamoto", "Young", "Zhang", "Ziegler", "Hartley", "Lindqvist",
+    "Okonkwo", "Marchetti", "Delacroix", "Barnes",
+    "M\u00fcller", "\u00c7elik", "N\u00fa\u00f1ez", "\u00d8stergaard", "B\u00e9ranger", "\u0141ukasik",
+  ],
+  emailDomains: ["example.com", "example.org", "example.net", "mail.example.com", "inbox.example.org"],
+  tlds: ["com", "org", "net", "io", "dev"],
+  places: [
+    { city: "Springfield", state: "Illinois", code: "IL", country: "United States", zip: "627" },
+    { city: "Riverton", state: "Wyoming", code: "WY", country: "United States", zip: "825" },
+    { city: "Lakeside", state: "California", code: "CA", country: "United States", zip: "920" },
+    { city: "Fairview", state: "Oregon", code: "OR", country: "United States", zip: "970" },
+    { city: "Georgetown", state: "Texas", code: "TX", country: "United States", zip: "786" },
+    { city: "Clinton", state: "Iowa", code: "IA", country: "United States", zip: "527" },
+    { city: "Madison", state: "Wisconsin", code: "WI", country: "United States", zip: "537" },
+    { city: "Franklin", state: "Tennessee", code: "TN", country: "United States", zip: "370" },
+    { city: "Salem", state: "Massachusetts", code: "MA", country: "United States", zip: "019" },
+    { city: "Bristol", state: "Connecticut", code: "CT", country: "United States", zip: "060" },
+    { city: "Oxford", state: "Ohio", code: "OH", country: "United States", zip: "450" },
+    { city: "Ashland", state: "Kentucky", code: "KY", country: "United States", zip: "411" },
+    { city: "Kingston", state: "New York", code: "NY", country: "United States", zip: "124" },
+    { city: "Dover", state: "Delaware", code: "DE", country: "United States", zip: "199" },
+    { city: "Burlington", state: "Vermont", code: "VT", country: "United States", zip: "054" },
+    { city: "Milton", state: "Georgia", code: "GA", country: "United States", zip: "300" },
+    { city: "Greenville", state: "South Carolina", code: "SC", country: "United States", zip: "296" },
+    { city: "Auburn", state: "Alabama", code: "AL", country: "United States", zip: "368" },
+    { city: "Centerville", state: "Utah", code: "UT", country: "United States", zip: "840" },
+    { city: "Arlington", state: "Virginia", code: "VA", country: "United States", zip: "222" },
+    { city: "Hamilton", state: "Ontario", code: "ON", country: "Canada", zip: "L8P" },
+    { city: "Kelowna", state: "British Columbia", code: "BC", country: "Canada", zip: "V1Y" },
+    { city: "Brandon", state: "Manitoba", code: "MB", country: "Canada", zip: "R7A" },
+    { city: "Fredericton", state: "New Brunswick", code: "NB", country: "Canada", zip: "E3B" },
+  ],
+  streets: [
+    "Main", "Oak", "Maple", "Cedar", "Elm", "Pine", "Washington", "Lake", "Hill", "Park",
+    "Walnut", "Sunset", "Railroad", "Church", "Willow", "River", "Meadow", "Highland", "Spring", "Chestnut",
+  ],
+  streetSuffixes: ["St", "Ave", "Rd", "Ln", "Blvd", "Way", "Ct", "Dr"],
+  jobTitles: [
+    "Software Engineer", "Product Manager", "Data Analyst", "Designer", "Accountant", "Nurse", "Electrician",
+    "Teacher", "Marketing Lead", "Operations Manager", "Support Specialist", "Chef", "Architect", "Librarian",
+    "Mechanic", "Researcher", "Editor", "Pharmacist", "Logistics Coordinator", "Sales Representative",
+  ],
+  industries: [
+    "Software", "Healthcare", "Logistics", "Education", "Retail", "Manufacturing", "Finance", "Energy",
+    "Media", "Hospitality", "Agriculture", "Construction",
+  ],
+  companyHeads: [
+    "Harbor", "Summit", "Juniper", "Northwind", "Bluebird", "Ironwood", "Lantern", "Meridian", "Cobalt", "Willow",
+    "Granite", "Evergreen", "Beacon", "Foxglove", "Kestrel", "Pinnacle", "Redwood", "Silverline", "Tidewater", "Brightside",
+  ],
+  companySuffixes: ["Labs", "Industries", "Group", "Partners", "Systems", "Works", "Holdings", "Collective", "Co", "Studio"],
+  productAdjectives: [
+    "Compact", "Classic", "Deluxe", "Portable", "Rustic", "Smart", "Sturdy", "Sleek", "Organic", "Vintage",
+    "Ergonomic", "Everyday", "Premium", "Lightweight", "Handmade", "Modular",
+  ],
+  productNouns: [
+    "Lamp", "Backpack", "Kettle", "Notebook", "Chair", "Mug", "Speaker", "Blanket", "Planter", "Wallet",
+    "Bottle", "Clock", "Toolkit", "Candle", "Headphones", "Keyboard", "Umbrella", "Tote",
+  ],
+  words: [
+    "lorem", "ipsum", "dolor", "sit", "amet", "consectetur", "adipiscing", "elit", "sed", "do",
+    "eiusmod", "tempor", "incididunt", "ut", "labore", "et", "dolore", "magna", "aliqua", "enim",
+    "ad", "minim", "veniam", "quis", "nostrud", "exercitation", "ullamco", "laboris", "nisi", "aliquip",
+    "ex", "ea", "commodo", "consequat", "duis", "aute", "irure", "in", "reprehenderit", "voluptate",
+    "velit", "esse", "cillum", "eu", "fugiat", "nulla", "pariatur", "excepteur", "sint", "occaecat",
+    "cupidatat", "non", "proident", "sunt", "culpa", "qui", "officia", "deserunt", "mollit", "anim",
+    "id", "est", "laborum", "at", "vero", "eos", "accusamus", "iusto", "odio", "dignissimos",
+    "ducimus", "blanditiis", "praesentium", "voluptatum", "deleniti", "atque", "corrupti", "quos", "dolores", "quas",
+    "molestias", "excepturi", "occaecati", "cupiditate", "provident", "similique", "mollitia", "animi", "perspiciatis", "unde",
+    "omnis", "iste", "natus", "error", "voluptatem", "accusantium", "doloremque", "laudantium", "totam", "rem",
+  ],
+  status: ["draft", "pending", "active", "published", "archived", "closed", "open", "resolved"],
+  role: ["admin", "editor", "member", "viewer", "owner", "moderator", "guest"],
+  currency: ["USD", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF", "SEK"],
+  locale: ["en-US", "en-GB", "fr-FR", "de-DE", "es-ES", "pt-BR", "ja-JP", "sv-SE"],
+  language: ["English", "French", "German", "Spanish", "Portuguese", "Japanese", "Swedish", "Italian"],
+  colors: ["red", "orange", "yellow", "green", "teal", "blue", "indigo", "violet", "pink", "brown", "black", "white", "gray", "silver"],
+});
+
+export const LOCALES = Object.freeze({ en });

package/src/world.js

@@ -0,0 +1,461 @@
+// A shared, persistent world: pinned entities and deterministic mutations (docs/design.md section 16, World).
+// State is an append-only log of effects; replaying the log rebuilds the identical state.
+import { Kind, valueFromASTUntyped, visit } from "graphql";
+import { GraceholderError } from "./errors.js";
+import { toDocument } from "./infer.js";
+import { compileSpec } from "./spec.js";
+import { keyStream } from "./key.js";
+import { tokenize, typeNameFor } from "./naming.js";
+import { ID_ARGS, entityKeyFromArgs } from "./args.js";
+import { streamWorld } from "./bulk/stream.js";
+import { globalScenarios, errorRateOf } from "./scenario.js";
+import { explainWith, parsePath } from "./explain.js";
+import { anchorMs, checkLocale, generateResult, realismOptions, DEFAULT_ANCHOR, DEFAULT_SEED } from "./generate.js";
+
+const DEFAULT_VERBS = {
+  create: "create", add: "create", insert: "create",
+  update: "update", edit: "update", set: "update",
+  delete: "delete", remove: "delete",
+};
+const INPUT_ARGS = ["input", "data", "patch"];
+const RELATION = /^(.+?)(?:Id|_id)$/;
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const bad = (msg, extra) => new GraceholderError("bad-options", msg, extra);
+const recKey = (type, key) => `${type}\u0000${key}`;
+const lowerFirst = (s) => s[0].toLowerCase() + s.slice(1);
+
+function parseRef(ref) {
+  const i = typeof ref === "string" ? ref.indexOf(":") : -1;
+  const type = i > 0 ? ref.slice(0, i) : "";
+  const key = i > 0 ? ref.slice(i + 1) : "";
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(type) || key === "") {
+    throw bad(`an entity reference looks like "User:42", got ${JSON.stringify(ref)}`);
+  }
+  return { type, key };
+}
+
+/** The state the executor reads (see execute.js `ws`), rebuilt from the log. */
+class WorldState {
+  constructor() {
+    /** @type {Map<string, { fields: Record<string, any>, created: boolean, updated: boolean }>} "Type\0key" -> record */
+    this.recs = new Map();
+    /** @type {Map<string, Set<string>>} Type -> deleted keys */
+    this.deleted = new Map();
+    /** @type {Map<string, string[]>} Type -> keys in creation order (may include deleted keys) */
+    this.created = new Map();
+    /** @type {Map<string, Array<{ ownerType: string, ownerKey: string }>>} */
+    this.rels = new Map();
+    /** @type {"start"|"end"|undefined} */
+    this.position = undefined;
+    /** @type {Set<string>} "Type.field" of every field set to null, which must be nullable in the SDL */
+    this.nulls = new Set();
+  }
+
+  clear() {
+    this.recs.clear();
+    this.deleted.clear();
+    this.created.clear();
+    this.rels.clear();
+    this.nulls.clear();
+    this.position = undefined;
+  }
+
+  entity(type, key) {
+    return this.recs.get(recKey(type, key));
+  }
+
+  isDeleted(type, key) {
+    return this.deleted.get(type)?.has(key) ?? false;
+  }
+
+  nullFields() {
+    return this.nulls.size ? this.nulls : undefined;
+  }
+
+  deletedKeys(type) {
+    return this.deleted.get(type) ?? [];
+  }
+
+  deletedTypes() {
+    const out = new Set();
+    for (const [t, set] of this.deleted) if (set.size) out.add(t);
+    return out.size ? out : undefined;
+  }
+
+  createdKeys(type) {
+    return (this.created.get(type) ?? []).filter((k) => !this.isDeleted(type, k));
+  }
+
+  relatedKeys(type, ownerType, ownerKey) {
+    return this.createdKeys(type).filter((k) => (this.rels.get(recKey(type, k)) ?? []).some((r) => r.ownerType === ownerType && r.ownerKey === ownerKey));
+  }
+
+  touches(type) {
+    return (this.deleted.get(type)?.size ?? 0) > 0 || (this.created.get(type)?.length ?? 0) > 0;
+  }
+
+  taken(type, key) {
+    return this.isDeleted(type, key) || (this.created.get(type) ?? []).includes(key);
+  }
+
+  /**
+   * Apply one log entry.
+   * @param {any} e
+   */
+  apply(e) {
+    const rk = recKey(e.type, e.key);
+    if (e.op === "pin" || e.op === "update") {
+      const rec = this.recs.get(rk) ?? { fields: {}, created: false, updated: false };
+      this.recs.set(rk, rec);
+      Object.assign(rec.fields, e.fields);
+      for (const [k, v] of Object.entries(e.fields)) if (v === null) this.nulls.add(`${e.type}.${k}`);
+      if (e.op === "update") rec.updated = true;
+      if (e.rel) this.rels.set(rk, e.rel);
+    } else if (e.op === "create") {
+      this.deleted.get(e.type)?.delete(e.key);
+      const list = this.created.get(e.type) ?? [];
+      this.created.set(e.type, [...list.filter((k) => k !== e.key), e.key]);
+      this.recs.set(rk, { fields: { ...e.fields }, created: true, updated: false });
+      for (const [k, v] of Object.entries(e.fields)) if (v === null) this.nulls.add(`${e.type}.${k}`);
+      if (e.rel?.length) this.rels.set(rk, e.rel);
+      else this.rels.delete(rk);
+    } else if (e.op === "delete") {
+      if (!this.deleted.has(e.type)) this.deleted.set(e.type, new Set());
+      /** @type {Set<string>} */ (this.deleted.get(e.type)).add(e.key);
+      this.recs.delete(rk);
+      this.rels.delete(rk);
+    }
+  }
+}
+
+const OPS = new Set(["pin", "create", "update", "delete"]);
+
+function checkEntry(e, i) {
+  const fail = (m) => bad(`log entry ${i}: ${m}`);
+  if (!isObject(e) || !OPS.has(e.op)) throw fail("op must be one of pin, create, update, delete");
+  if (typeof e.type !== "string" || typeof e.key !== "string" || e.key === "") throw fail("type and key must be strings");
+  if (e.op !== "delete" && !isObject(e.fields)) throw fail("fields must be an object");
+  if (e.rel !== undefined && !Array.isArray(e.rel)) throw fail("rel must be an array");
+}
+
+function plainErrors(errors) {
+  return errors.map((e) => {
+    const out = { message: e.message };
+    if (e.locations) out.locations = e.locations.map((l) => ({ line: l.line, column: l.column }));
+    if (e.path) out.path = [...e.path];
+    const ext = { ...(e.extensions ?? {}) };
+    if (e.originalError instanceof GraceholderError) ext.code = e.originalError.code;
+    if (Object.keys(ext).length) out.extensions = ext;
+    return out;
+  });
+}
+
+function thrownErrors(e) {
+  if (!(e instanceof GraceholderError)) throw e;
+  if (e.code === "graphql" && e.errors) return plainErrors(e.errors);
+  const ext = { code: e.code };
+  if (e.path !== undefined) ext.path = e.path;
+  if (e.hint !== undefined) ext.hint = e.hint;
+  return [{ message: e.message, extensions: ext }];
+}
+
+function selectOperation(doc, operationName) {
+  const ops = doc.definitions.filter((d) => d.kind === Kind.OPERATION_DEFINITION);
+  let op;
+  if (operationName !== undefined && operationName !== null) {
+    op = ops.find((o) => o.name?.value === operationName);
+    if (!op) throw new GraceholderError("bad-operation", `no operation named ${JSON.stringify(operationName)}`);
+  } else if (ops.length === 1) {
+    op = ops[0];
+  } else {
+    throw new GraceholderError("bad-operation", ops.length === 0 ? "the document has no operation" : "the document has several operations; pass operationName");
+  }
+  if (op.operation === "subscription") throw new GraceholderError("bad-operation", "subscription operations are not supported");
+  return op;
+}
+
+/** @skip / @include on a root field. */
+function skipped(node, vars) {
+  for (const d of node.directives ?? []) {
+    const name = d.name.value;
+    if (name !== "skip" && name !== "include") continue;
+    const arg = d.arguments?.find((a) => a.name.value === "if");
+    const v = arg ? valueFromASTUntyped(arg.value, vars) : undefined;
+    if (name === "skip" && v === true) return true;
+    if (name === "include" && v === false) return true;
+  }
+  return false;
+}
+
+/** Root fields of a mutation, looking through fragments on `Mutation`. */
+function rootFields(selSet, fragments, vars, out = []) {
+  for (const s of selSet.selections) {
+    if (skipped(s, vars)) continue;
+    if (s.kind === Kind.FIELD) out.push(s);
+    else if (s.kind === Kind.INLINE_FRAGMENT) rootFields(s.selectionSet, fragments, vars, out);
+    else if (s.kind === Kind.FRAGMENT_SPREAD) {
+      const def = fragments.get(s.name.value);
+      if (!def) throw new GraceholderError("graphql", `Unknown fragment "${s.name.value}".`);
+      rootFields(def.selectionSet, fragments, vars, out);
+    }
+  }
+  return out;
+}
+
+/**
+ * Mutation inference (docs/design.md section 16, World): the verb and entity type of a root mutation field.
+ * @returns {{ op: "create"|"update"|"delete", type: string, read: string, cfg: any }}
+ */
+export function classifyMutation(fieldName, mutations) {
+  const cfg = mutations.fields[fieldName];
+  const tokens = tokenize(fieldName);
+  const op = cfg?.op ?? mutations.verbs[tokens[0]] ?? DEFAULT_VERBS[tokens[0]];
+  if (!op) {
+    throw new GraceholderError("bad-mutation", `cannot tell what the mutation "${fieldName}" does: "${tokens[0]}" is not a known verb`, {
+      hint: `known verbs: ${Object.keys({ ...DEFAULT_VERBS, ...mutations.verbs }).join(", ")}; declare others in the spec: { "$mutations": { "verbs": { "${tokens[0]}": "update" } } } or { "fields": { "${fieldName}": { "op": "update", "type": "..." } } }`,
+    });
+  }
+  const noun = tokens.slice(1).join("_");
+  if (!cfg?.type && noun === "") {
+    throw new GraceholderError("bad-mutation", `the mutation "${fieldName}" names no entity type`, { hint: `name it like ${tokens[0]}User or set { "$mutations": { "fields": { "${fieldName}": { "op": "${op}", "type": "User" } } } }` });
+  }
+  const type = cfg?.type ?? typeNameFor(noun);
+  return { op, type, read: cfg?.read ?? lowerFirst(type), cfg };
+}
+
+/**
+ * @param {import("./index.js").WorldOptions & { log?: any[] }} [options]
+ */
+export function createWorld(options = {}) {
+  if (!isObject(options)) throw bad("createWorld expects an options object");
+  const seed = options.seed ?? DEFAULT_SEED;
+  const locale = options.locale ?? "en";
+  checkLocale(locale);
+  const anchorDate = options.anchorDate ?? DEFAULT_ANCHOR;
+  const anchorIso = new Date(anchorMs(anchorDate)).toISOString();
+  const spec = options.spec === undefined ? undefined : structuredClone(options.spec);
+  const mutations = compileSpec(spec).mutations;
+  // realism options (docs/design.md section 16, Realism) apply to every query of the world; fail early on a bad one
+  realismOptions(options);
+  const scenario = globalScenarios(options.scenario);
+  errorRateOf(options.scenarioOptions);
+  const realism = {
+    ...(options.packs ? { packs: options.packs } : {}),
+    ...(options.images !== undefined ? { images: options.images } : {}),
+    ...(options.distributions !== undefined ? { distributions: options.distributions } : {}),
+    ...(scenario.length ? { scenario } : {}),
+    ...(options.scenarioOptions !== undefined ? { scenarioOptions: { ...options.scenarioOptions } } : {}),
+  };
+  const base = { seed, spec, anchorDate: anchorIso, locale, strict: options.strict, ...realism, schema: options.schema };
+
+  const state = new WorldState();
+  state.position = mutations.position;
+  /** @type {any[]} */
+  let log = [];
+  const append = (entry) => {
+    state.apply(entry);
+    log.push(entry);
+  };
+  const replay = (entries) => {
+    if (!Array.isArray(entries)) throw bad("log must be an array");
+    entries.forEach(checkEntry);
+    for (const e of entries) append(structuredClone(e));
+  };
+  if (options.log !== undefined) replay(options.log);
+
+  const view = state;
+  const run = (query, opts) => generateResult(query, { ...base, ...opts }, view);
+
+  /** Variable values: declared defaults, then the provided ones. */
+  const varsOf = (op, provided) => {
+    const out = {};
+    for (const def of op.variableDefinitions ?? []) if (def.defaultValue) out[def.variable.name.value] = valueFromASTUntyped(def.defaultValue);
+    return { ...out, ...(provided ?? {}) };
+  };
+
+  const notFound = (type, key) => new GraceholderError("not-found", `${type} ${JSON.stringify(key)} does not exist (it was deleted)`);
+
+  /** Decide the effect of one mutation field and return it (nothing is written). */
+  function effectOf(node, vars) {
+    const name = node.name.value;
+    const cls = classifyMutation(name, mutations);
+    const args = {};
+    for (const a of node.arguments ?? []) args[a.name.value] = valueFromASTUntyped(a.value, vars);
+    const inputName = cls.cfg?.input;
+    let input;
+    if (inputName === "args") input = undefined;
+    else if (inputName) input = isObject(args[inputName]) ? args[inputName] : undefined;
+    else input = INPUT_ARGS.map((n) => args[n]).find(isObject);
+
+    const idNames = cls.op === "create" ? [cls.cfg?.idArg ?? "id"] : cls.cfg?.idArg ? [cls.cfg.idArg] : ID_ARGS;
+    const idName = idNames.find((n) => args[n] != null) ?? idNames.find((n) => input?.[n] != null) ?? idNames.find((n) => isObject(args.where) && args.where[n] != null);
+    const idValue = idName === undefined ? undefined : (args[idName] ?? input?.[idName] ?? args.where?.[idName]);
+    const key = idName === undefined ? undefined : entityKeyFromArgs({ id: idValue });
+
+    let fields;
+    if (input) {
+      fields = { ...input };
+    } else {
+      fields = {};
+      for (const [k, v] of Object.entries(args)) if (k !== "where" || !isObject(v)) fields[k] = v;
+    }
+    if (idName !== undefined) delete fields[idName];
+    for (const k of Object.keys(fields)) if (fields[k] === undefined) delete fields[k];
+
+    const rel = [];
+    for (const [fname, value] of Object.entries(fields)) {
+      const m = RELATION.exec(fname);
+      if (!m || value === null || typeof value === "object") continue;
+      const ownerType = mutations.relations[`${cls.type}.${fname}`] ?? typeNameFor(m[1]);
+      rel.push({ ownerType, ownerKey: entityKeyFromArgs({ id: value }) });
+    }
+    return { name, ...cls, key, fields, rel };
+  }
+
+  /** Evaluate the selection of a mutation field as the query field for the affected entity. */
+  function selectionOf(node, doc, op, vars, cls, key, errorsOut) {
+    const alias = node.alias?.value ?? node.name.value;
+    const field = {
+      kind: Kind.FIELD,
+      alias: { kind: Kind.NAME, value: alias },
+      name: { kind: Kind.NAME, value: cls.read },
+      arguments: [{ kind: Kind.ARGUMENT, name: { kind: Kind.NAME, value: "id" }, value: { kind: Kind.STRING, value: key } }],
+      directives: [],
+      selectionSet: node.selectionSet,
+    };
+    const fragments = doc.definitions.filter((d) => d.kind === Kind.FRAGMENT_DEFINITION);
+    const used = new Set();
+    for (const part of [field, ...fragments]) visit(part, { Variable: (v) => void used.add(v.name.value) });
+    const query = {
+      kind: Kind.DOCUMENT,
+      definitions: [
+        {
+          kind: Kind.OPERATION_DEFINITION,
+          operation: "query",
+          variableDefinitions: (op.variableDefinitions ?? []).filter((d) => used.has(d.variable.name.value)),
+          selectionSet: { kind: Kind.SELECTION_SET, selections: [field] },
+        },
+        ...fragments,
+      ],
+    };
+    /** @type {any} */
+    const mutSpec = { ...(spec ?? {}) };
+    mutSpec[cls.read] = { ...(mutSpec[cls.read] ?? {}) };
+    if (mutSpec[cls.read].list === undefined) mutSpec[cls.read].one = true;
+    if (typeNameFor(cls.read) !== cls.type && mutSpec[cls.read].type === undefined) mutSpec[cls.read].type = cls.type;
+    const res = run(query, { variables: vars, spec: mutSpec, strict: false });
+    if (res.errors?.length) errorsOut.push(...plainErrors(res.errors).map((e) => ({ ...e, path: [alias, ...(e.path ?? []).slice(1)] })));
+    return res.data?.[alias] ?? null;
+  }
+
+  function mutate(doc, op, provided) {
+    const vars = varsOf(op, provided);
+    const fragments = new Map(doc.definitions.filter((d) => d.kind === Kind.FRAGMENT_DEFINITION).map((d) => [d.name.value, d]));
+    const data = {};
+    const errors = [];
+    for (const node of rootFields(op.selectionSet, fragments, vars)) {
+      const alias = node.alias?.value ?? node.name.value;
+      try {
+        if (node.name.value === "__typename") {
+          data[alias] = "Mutation";
+          continue;
+        }
+        const eff = effectOf(node, vars);
+        const { op: kind, type } = eff;
+        let key = eff.key;
+        if (kind === "create") {
+          const seq = log.length + 1;
+          if (key === undefined) {
+            let n = keyStream({ seed, scope: "a", typeName: type, entityKey: "world", fieldName: "create", subKeys: [seq] }).int(1000000, 9999999);
+            while (state.taken(type, String(n))) n++;
+            key = String(n);
+          } else if (state.createdKeys(type).includes(key)) {
+            throw new GraceholderError("bad-mutation", `${type} ${JSON.stringify(key)} already exists`);
+          }
+          // a decimal key is its own id; any other key needs the id field pinned to it
+          if (!/^[0-9]+$/.test(key) && eff.fields.id === undefined) eff.fields = { id: key, ...eff.fields };
+          append({ op: "create", type, key, fields: eff.fields, ...(eff.rel.length ? { rel: eff.rel } : {}), mutation: eff.name });
+        } else {
+          if (key === undefined) {
+            throw new GraceholderError("bad-mutation", `the mutation "${eff.name}" needs an identifying argument (${ID_ARGS.join(", ")}), in its arguments or its input`);
+          }
+          if (state.isDeleted(type, key)) throw notFound(type, key);
+          if (kind === "update") {
+            append({ op: "update", type, key, fields: eff.fields, ...(eff.rel.length ? { rel: eff.rel } : {}), mutation: eff.name });
+          }
+        }
+        if (!node.selectionSet) {
+          data[alias] = kind === "delete" ? true : key;
+        } else {
+          data[alias] = selectionOf(node, doc, op, vars, eff, key, errors);
+        }
+        // a delete returns the entity as it was; the write comes after the read
+        if (kind === "delete") append({ op: "delete", type, key, mutation: eff.name });
+      } catch (e) {
+        if (!(e instanceof GraceholderError)) throw e;
+        data[alias] = null;
+        errors.push({ ...thrownErrors(e)[0], path: [alias] });
+      }
+    }
+    return errors.length ? { data, errors } : { data };
+  }
+
+  return {
+    /**
+     * Run a query or a mutation against the world. Returns a GraphQL result: `{ data }`, or with
+     * `errors` (parse, validation, argument and mutation errors never throw here).
+     */
+    query(query, opts = {}) {
+      try {
+        const doc = toDocument(query);
+        const op = selectOperation(doc, opts.operationName);
+        if (op.operation === "mutation") return mutate(doc, op, opts.variables);
+        const res = run(doc, { variables: opts.variables, operationName: opts.operationName });
+        if (res.errors?.length) return res.data === undefined ? { errors: plainErrors(res.errors) } : { data: res.data, errors: plainErrors(res.errors) };
+        return { data: res.data };
+      } catch (e) {
+        return { errors: thrownErrors(e) };
+      }
+    },
+
+    /**
+     * The root collection of a query as a lazy iterable (see `stream`), reflecting the pins and
+     * mutations at the time each window is generated: consume it before mutating the world.
+     */
+    stream(query, opts = {}) {
+      return streamWorld(query, { ...base, ...opts }, view);
+    },
+
+    /** Why the value at `path` looks the way it does in this world, pins and mutations included (see `explain`). */
+    explain(query, path, opts = {}) {
+      return explainWith(query, parsePath(path), { ...base, ...opts }, view);
+    },
+
+    /** Override fields of one entity ("User:42"); unpinned fields stay generated. Pins are logged. */
+    pin(ref, fields) {
+      const { type, key } = parseRef(ref);
+      if (!isObject(fields)) throw bad("pin expects an object of field values");
+      if (state.isDeleted(type, key)) throw notFound(type, key);
+      const clean = {};
+      for (const [k, v] of Object.entries(fields)) if (v !== undefined) clean[k] = v;
+      append(structuredClone({ op: "pin", type, key, fields: clean }));
+      return this;
+    },
+
+    /** `{ seed, spec, anchorDate, locale, log }`: pass it to createWorld to replay to the same state. */
+    export() {
+      // pack objects are exported by name: register them (registerPack) before replaying
+      const extra = { ...realism, ...(realism.packs ? { packs: realism.packs.map((p) => (typeof p === "string" ? p : p.name)) } : {}) };
+      return structuredClone({ seed, spec, anchorDate: anchorIso, locale, ...extra, log });
+    },
+
+    /** Forget every pin and mutation. */
+    reset() {
+      state.clear();
+      state.position = mutations.position;
+      log = [];
+      return this;
+    },
+  };
+}

package/src/xxh64.js

@@ -0,0 +1,87 @@
+// XXH64 as published (https://github.com/Cyan4973/xxHash, XXH64 spec v0.8).
+// BigInt implementation: synchronous, dependency free, identical in Node and browsers.
+// FROZEN: any deviation from the published algorithm is a bug (docs/design.md 2.1).
+
+const M = 0xffffffffffffffffn;
+const P1 = 0x9e3779b185ebca87n;
+const P2 = 0xc2b2ae3d27d4eb4fn;
+const P3 = 0x165667b19e3779f9n;
+const P4 = 0x85ebca77c2b2ae63n;
+const P5 = 0x27d4eb2f165667c5n;
+
+const rotl = (x, r) => ((x << BigInt(r)) | (x >> BigInt(64 - r))) & M;
+
+function read64(b, i) {
+  let v = 0n;
+  for (let k = 7; k >= 0; k--) v = (v << 8n) | BigInt(b[i + k]);
+  return v;
+}
+
+function read32(b, i) {
+  return BigInt((b[i] | (b[i + 1] << 8) | (b[i + 2] << 16) | (b[i + 3] << 24)) >>> 0);
+}
+
+function round(acc, input) {
+  acc = (acc + input * P2) & M;
+  acc = rotl(acc, 31);
+  return (acc * P1) & M;
+}
+
+function mergeRound(acc, val) {
+  acc ^= round(0n, val);
+  return (acc * P1 + P4) & M;
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @param {bigint} [seed]
+ * @returns {bigint} unsigned 64-bit hash
+ */
+export function xxh64(bytes, seed = 0n) {
+  const len = bytes.length;
+  let i = 0;
+  let h;
+  if (len >= 32) {
+    let v1 = (seed + P1 + P2) & M;
+    let v2 = (seed + P2) & M;
+    let v3 = seed & M;
+    let v4 = (seed - P1) & M;
+    const limit = len - 32;
+    do {
+      v1 = round(v1, read64(bytes, i));
+      v2 = round(v2, read64(bytes, i + 8));
+      v3 = round(v3, read64(bytes, i + 16));
+      v4 = round(v4, read64(bytes, i + 24));
+      i += 32;
+    } while (i <= limit);
+    h = (rotl(v1, 1) + rotl(v2, 7) + rotl(v3, 12) + rotl(v4, 18)) & M;
+    h = mergeRound(h, v1);
+    h = mergeRound(h, v2);
+    h = mergeRound(h, v3);
+    h = mergeRound(h, v4);
+  } else {
+    h = (seed + P5) & M;
+  }
+  h = (h + BigInt(len)) & M;
+  while (i + 8 <= len) {
+    h ^= round(0n, read64(bytes, i));
+    h = (rotl(h, 27) * P1 + P4) & M;
+    i += 8;
+  }
+  if (i + 4 <= len) {
+    h ^= (read32(bytes, i) * P1) & M;
+    h = (rotl(h, 23) * P2 + P3) & M;
+    i += 4;
+  }
+  while (i < len) {
+    h ^= (BigInt(bytes[i]) * P5) & M;
+    h = (rotl(h, 11) * P1) & M;
+    i++;
+  }
+  h ^= h >> 33n;
+  h = (h * P2) & M;
+  h ^= h >> 29n;
+  h = (h * P3) & M;
+  h ^= h >> 32n;
+  return h;
+}