@fitzzero/quickdraw-core 5.0.1 → 5.1.1

package/dist/testing/index.js

@@ -1,7 +1,10 @@
 import {
+  accessIds,
   createServer,
+  inputKeys,
+  isCustomAccess,
   runtimeOf
-} from "../chunk-NS5PUHIZ.js";
+} from "../chunk-RZTP4IEW.js";
 import {
   DevWarningError,
   STRICT_WARNINGS,
@@ -11,7 +14,7 @@ import "../chunk-QEKVYG5F.js";
 import {
   createCaller,
   lazyMembers
-} from "../chunk-2XJFNVHW.js";
+} from "../chunk-2PWMUVC7.js";
 import "../chunk-DD4SKCNO.js";
 import {
   isPrincipal,
@@ -24,8 +27,11 @@ import {
   PROTOCOL_VERSION,
   QUICKDRAW_VERSION,
   SERVER_EVENTS
-} from "../chunk-WVIRXYI4.js";
-import "../chunk-47AEXVDM.js";
+} from "../chunk-VSQBHPWH.js";
+import {
+  hasJsonSchema,
+  validate
+} from "../chunk-47AEXVDM.js";
 import {
   utf8ByteLength
 } from "../chunk-Z2LZ7IZ7.js";
@@ -232,8 +238,8 @@ function addBudgetSource(source) {
     sources.delete(source);
   };
 }
-function recordBudgetCall(record) {
-  recording?.push(record);
+function recordBudgetCall(record2) {
+  recording?.push(record2);
 }
 function totalsOf(live) {
   const counted = /* @__PURE__ */ new Set();
@@ -249,15 +255,15 @@ function totalsOf(live) {
   }
   return { statements, bytes };
 }
-function viaSocket(record) {
-  return record.transport === "socket" || record.transport === "legacy";
+function viaSocket(record2) {
+  return record2.transport === "socket" || record2.transport === "legacy";
 }
-function callOf(record) {
+function callOf(record2) {
   return {
-    call: `${record.service}.${record.method}`,
-    statements: record.sqlStatements ?? 0,
-    bytes: record.bytes,
-    ...record.outcome === "ok" ? {} : { outcome: record.outcome }
+    call: `${record2.service}.${record2.method}`,
+    statements: record2.sqlStatements ?? 0,
+    bytes: record2.bytes,
+    ...record2.outcome === "ok" ? {} : { outcome: record2.outcome }
   };
 }
 function byCodeUnit(a, b) {
@@ -270,7 +276,7 @@ function byCall(a, b) {
   return byCodeUnit(a.call, b.call) || byCodeUnit(a.outcome ?? "", b.outcome ?? "") || a.statements - b.statements || a.bytes - b.bytes;
 }
 function budgetOf(before, after, records) {
-  const replies = records.filter((record) => !viaSocket(record)).reduce((sum, record) => sum + record.bytes, 0);
+  const replies = records.filter((record2) => !viaSocket(record2)).reduce((sum, record2) => sum + record2.bytes, 0);
   return {
     statements: after.statements - before.statements,
     bytes: after.bytes - before.bytes + replies,
@@ -455,9 +461,9 @@ function instrumentOptions(options) {
   const { strictWarnings, onCall, ...rest } = options;
   return {
     ...rest,
-    onCall: (record) => {
-      recordBudgetCall(record);
-      onCall?.(record);
+    onCall: (record2) => {
+      recordBudgetCall(record2);
+      onCall?.(record2);
     },
     [STRICT_WARNINGS]: strictWarnings === true && underTestRunner()
   };
@@ -712,6 +718,601 @@ function createRecordingSink() {
   };
 }
 
+// src/testing/accessInputs.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var MAX_DEPTH = 12;
+var UNREPRESENTABLE_AS_ANY = Object.freeze({ unrepresentable: "any" });
+var FORMATS = Object.freeze({
+  email: "snapshot@example.com",
+  "idn-email": "snapshot@example.com",
+  uri: "https://example.com/",
+  url: "https://example.com/",
+  "uri-reference": "https://example.com/",
+  hostname: "example.com",
+  uuid: "00000000-0000-4000-8000-000000000000",
+  guid: "00000000-0000-4000-8000-000000000000",
+  "date-time": "2026-01-01T00:00:00.000Z",
+  date: "2026-01-01",
+  time: "00:00:00",
+  duration: "P1D",
+  ipv4: "127.0.0.1",
+  ipv6: "::1",
+  cuid: "cjld2cjxh0000qzrmn831i7rn",
+  cuid2: "tz4a98xxat96iws9zmbrgj3a",
+  ulid: "01ARZ3NDEKTSV4RRFFQ69G5FAV",
+  nanoid: "V1StGXR8_Z5jdHi6B-myT",
+  e164: "+15555550100"
+});
+var PATTERN_CANDIDATES = ["x", ...new Set(Object.values(FORMATS))];
+function referenced(node, root) {
+  const ref = node.$ref;
+  if (typeof ref !== "string") {
+    return node;
+  }
+  if (ref === "#") {
+    return root;
+  }
+  const match = /^#\/(definitions|\$defs)\/(.+)$/.exec(ref);
+  const defs = match === null ? void 0 : root[match[1] ?? ""];
+  const target = isRecord(defs) ? defs[match?.[2] ?? ""] : void 0;
+  return isRecord(target) ? target : void 0;
+}
+function typeOf(node) {
+  const { type } = node;
+  if (typeof type === "string") {
+    return type;
+  }
+  if (Array.isArray(type)) {
+    const types = type.filter((each) => typeof each === "string");
+    return types.includes("null") ? "null" : types[0];
+  }
+  return isRecord(node.properties) ? "object" : void 0;
+}
+function isNullBranch(node) {
+  return isRecord(node) && typeOf(node) === "null";
+}
+function patternOf(node) {
+  if (typeof node.pattern !== "string") {
+    return void 0;
+  }
+  try {
+    const regex = new RegExp(node.pattern, "u");
+    return (value) => regex.test(value);
+  } catch {
+    return void 0;
+  }
+}
+function sampleString(node) {
+  const format = typeof node.format === "string" ? FORMATS[node.format] : void 0;
+  const matches2 = patternOf(node);
+  let value = format ?? "x";
+  if (matches2 !== void 0 && !matches2(value)) {
+    value = PATTERN_CANDIDATES.find(matches2) ?? value;
+  }
+  const min = typeof node.minLength === "number" ? node.minLength : 0;
+  if (value.length < min) {
+    value += "x".repeat(min - value.length);
+  }
+  return typeof node.maxLength === "number" ? value.slice(0, node.maxLength) : value;
+}
+function sampleNumber(node, integer) {
+  const { minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf } = node;
+  let value = 0;
+  if (typeof minimum === "number" && value < minimum) {
+    value = integer ? Math.ceil(minimum) : minimum;
+  }
+  if (typeof exclusiveMinimum === "number" && value <= exclusiveMinimum) {
+    value = Math.floor(exclusiveMinimum) + 1;
+  }
+  if (typeof maximum === "number" && value > maximum) {
+    value = integer ? Math.floor(maximum) : maximum;
+  }
+  if (typeof exclusiveMaximum === "number" && value >= exclusiveMaximum) {
+    value = Math.ceil(exclusiveMaximum) - 1;
+  }
+  if (typeof multipleOf === "number" && multipleOf > 0 && value % multipleOf !== 0) {
+    value = Math.ceil(value / multipleOf) * multipleOf;
+  }
+  return value;
+}
+function sampleObject(node, root, depth) {
+  const properties = isRecord(node.properties) ? node.properties : {};
+  const required = Array.isArray(node.required) ? node.required : [];
+  const value = {};
+  for (const key of required) {
+    if (typeof key === "string") {
+      value[key] = sample(properties[key], root, depth + 1) ?? null;
+    }
+  }
+  return value;
+}
+function sampleArray(node, root, depth) {
+  let tuple;
+  if (Array.isArray(node.prefixItems)) {
+    tuple = node.prefixItems;
+  } else if (Array.isArray(node.items)) {
+    tuple = node.items;
+  }
+  if (tuple !== void 0) {
+    return tuple.map((item) => sample(item, root, depth + 1) ?? null);
+  }
+  const length = typeof node.minItems === "number" ? node.minItems : 0;
+  return Array.from({ length }, () => sample(node.items, root, depth + 1) ?? null);
+}
+function sampleAll(parts, root, depth) {
+  const values = parts.map((part) => sample(part, root, depth + 1));
+  if (values.every((value) => isRecord(value) || value === void 0)) {
+    return Object.assign({}, ...values);
+  }
+  return values.find((value) => value !== void 0);
+}
+function sampleType(node, root, depth) {
+  switch (typeOf(node)) {
+    case "object":
+      return sampleObject(node, root, depth);
+    case "array":
+      return sampleArray(node, root, depth);
+    case "string":
+      return sampleString(node);
+    case "integer":
+      return sampleNumber(node, true);
+    case "number":
+      return sampleNumber(node, false);
+    case "boolean":
+      return false;
+    case "null":
+      return null;
+    default:
+      return void 0;
+  }
+}
+function sample(node, root, depth) {
+  const target = isRecord(node) && depth <= MAX_DEPTH ? referenced(node, root) : void 0;
+  if (target === void 0) {
+    return void 0;
+  }
+  if (Object.hasOwn(target, "const")) {
+    return target.const;
+  }
+  if (Array.isArray(target.enum) && target.enum.length > 0) {
+    return target.enum[0];
+  }
+  const branches = Array.isArray(target.anyOf) ? target.anyOf : target.oneOf;
+  if (Array.isArray(branches) && branches.length > 0) {
+    return branches.some(isNullBranch) ? null : sample(branches[0], root, depth + 1);
+  }
+  if (Array.isArray(target.allOf) && target.allOf.length > 0) {
+    return sampleAll(target.allOf, root, depth);
+  }
+  return sampleType(target, root, depth);
+}
+var shapes = /* @__PURE__ */ new WeakMap();
+function jsonSchemaOf(method) {
+  if (!hasJsonSchema(method.input)) {
+    return void 0;
+  }
+  try {
+    const json = method.input["~standard"].jsonSchema.input({
+      target: "draft-07",
+      libraryOptions: UNREPRESENTABLE_AS_ANY
+    });
+    return isRecord(json) ? json : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function shapeOf(method) {
+  const known = shapes.get(method);
+  if (known !== void 0) {
+    return known;
+  }
+  const root = jsonSchemaOf(method);
+  const described = root === void 0 ? void 0 : referenced(root, root);
+  const shape = {
+    skeleton: root === void 0 ? void 0 : sample(root, root, 0),
+    root: root ?? {},
+    properties: isRecord(described?.properties) ? described.properties : void 0,
+    isString: described !== void 0 && typeOf(described) === "string"
+  };
+  shapes.set(method, shape);
+  return shape;
+}
+function rowForm(form) {
+  if (typeof form !== "object" || isCustomAccess(form)) {
+    return void 0;
+  }
+  return form.entry === void 0 && form.scope === void 0 ? void 0 : form;
+}
+function rowServiceOf(service, method) {
+  const form = rowForm(method.access);
+  if (form?.scope !== void 0) {
+    return form.of.name;
+  }
+  if (form !== void 0) {
+    return service.name;
+  }
+  return inputKeys(method.input)?.includes("id") === true ? service.name : void 0;
+}
+function mayHoldId(node) {
+  if (!isRecord(node)) {
+    return true;
+  }
+  const type = typeOf(node);
+  return type === void 0 || type === "string" || type === "array" || type === "null";
+}
+function keyRank(key) {
+  if (key === "id" || key === "ids") {
+    return 0;
+  }
+  return /Ids?$/.test(key) ? 1 : 2;
+}
+function selectorKeys(shape) {
+  const { properties } = shape;
+  if (properties === void 0) {
+    return shape.isString ? [] : ["id"];
+  }
+  return Object.keys(properties).filter((key) => mayHoldId(properties[key])).sort((a, b) => keyRank(a) - keyRank(b));
+}
+function idValues(shape, key, row) {
+  const node = shape.properties?.[key];
+  const target = isRecord(node) ? referenced(node, shape.root) : void 0;
+  return target !== void 0 && typeOf(target) === "array" ? [[row], row] : [row, [row]];
+}
+function rowKeys(form, shape) {
+  if (form === void 0) {
+    return ["id"];
+  }
+  if (typeof form.id === "function") {
+    return selectorKeys(shape);
+  }
+  return [form.id ?? "id"];
+}
+function candidates(method, row) {
+  const shape = shapeOf(method);
+  const form = rowForm(method.access);
+  const hasId = form !== void 0 || inputKeys(method.input)?.includes("id") === true;
+  if (row === void 0 || !hasId) {
+    return [shape.skeleton];
+  }
+  const base = isRecord(shape.skeleton) ? shape.skeleton : {};
+  const placed = rowKeys(form, shape).flatMap(
+    (key) => idValues(shape, key, row).map((value) => ({ ...base, [key]: value }))
+  );
+  const bare = typeof form?.id === "function" && (shape.isString || shape.properties === void 0);
+  return bare ? [...placed, row] : placed;
+}
+async function isValidInput(method, input) {
+  const result = await validate(method.input, input);
+  return result.issues === void 0;
+}
+function namesRow(form, parsed, row) {
+  try {
+    return accessIds(form, parsed).includes(row);
+  } catch {
+    return false;
+  }
+}
+async function generatedInput(method, row) {
+  const form = rowForm(method.access);
+  for (const input of candidates(method, row)) {
+    const result = await validate(method.input, input);
+    if (result.issues !== void 0) {
+      continue;
+    }
+    if (form === void 0 || row !== void 0 && namesRow(form, result.value, row)) {
+      return { input };
+    }
+  }
+  return void 0;
+}
+
+// src/testing/accessSnapshotFile.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { basename as basename2, dirname as dirname2, join as join2 } from "path";
+
+// src/testing/accessSnapshotCompare.ts
+var ACCESS_SECTIONS = ["methods", "subscriptions", "collections"];
+var SECTION_PREFIX = Object.freeze({
+  methods: "",
+  subscriptions: "qd:sub ",
+  collections: "qd:col:sub "
+});
+function only(items, other) {
+  return [...items].filter((item) => !other.has(item)).sort();
+}
+function samePrincipal(a, b) {
+  return a === null || b === null ? a === b : a.kind === b.kind;
+}
+function cellOf(row, principal) {
+  return Object.hasOwn(row, principal) ? row[principal] : void 0;
+}
+function compareRow(section, row, sides, principals) {
+  return principals.flatMap((principal) => {
+    const before = cellOf(sides.before, principal);
+    const after = cellOf(sides.after, principal);
+    return before === after ? [] : [{ section, row, principal, before, after }];
+  });
+}
+function comparePrincipals(before, after, shared) {
+  return shared.flatMap((name) => {
+    const was = before.principals[name] ?? null;
+    const is = after.principals[name] ?? null;
+    return samePrincipal(was, is) ? [] : [{ name, before: was, after: is }];
+  });
+}
+function compareAccessSnapshots(before, after) {
+  const namesBefore = new Set(Object.keys(before.principals));
+  const namesAfter = new Set(Object.keys(after.principals));
+  const shared = [...namesAfter].filter((name) => namesBefore.has(name)).sort();
+  const differing = [];
+  const rowsAdded = [];
+  const rowsRemoved = [];
+  for (const section of ACCESS_SECTIONS) {
+    const rowsBefore = new Set(Object.keys(before[section]));
+    const rowsAfter = new Set(Object.keys(after[section]));
+    const prefix = SECTION_PREFIX[section];
+    rowsAdded.push(...only(rowsAfter, rowsBefore).map((row) => prefix + row));
+    rowsRemoved.push(...only(rowsBefore, rowsAfter).map((row) => prefix + row));
+    for (const row of [...rowsAfter].filter((key) => rowsBefore.has(key)).sort()) {
+      const sides = { before: before[section][row] ?? {}, after: after[section][row] ?? {} };
+      differing.push(...compareRow(section, row, sides, shared));
+    }
+  }
+  const excludedBefore = new Set(before.excluded);
+  const excludedAfter = new Set(after.excluded);
+  const oneSided = (change2) => change2.before === void 0 || change2.after === void 0;
+  return {
+    changed: differing.filter((change2) => !oneSided(change2)),
+    principals: comparePrincipals(before, after, shared),
+    rowsAdded,
+    rowsRemoved,
+    principalsAdded: only(namesAfter, namesBefore),
+    principalsRemoved: only(namesBefore, namesAfter),
+    cells: differing.filter(oneSided),
+    excludedAdded: only(excludedAfter, excludedBefore),
+    excludedRemoved: only(excludedBefore, excludedAfter)
+  };
+}
+function hasDifferences(comparison) {
+  return comparison.changed.length > 0 || comparison.principals.length > 0;
+}
+function isReshaped(comparison) {
+  return [
+    comparison.rowsAdded,
+    comparison.rowsRemoved,
+    comparison.principalsAdded,
+    comparison.principalsRemoved,
+    comparison.cells,
+    comparison.excludedAdded,
+    comparison.excludedRemoved
+  ].some((list) => list.length > 0);
+}
+function denies(outcome) {
+  return outcome === "UNAUTHENTICATED" || outcome === "FORBIDDEN";
+}
+function passes(outcome) {
+  return outcome !== void 0 && outcome !== "VALIDATION" && !denies(outcome);
+}
+function accessFlip(change2) {
+  if (denies(change2.before) && passes(change2.after)) {
+    return "opens access";
+  }
+  if (passes(change2.before) && denies(change2.after)) {
+    return "closes access";
+  }
+  return void 0;
+}
+function cellName(cell) {
+  return `${SECTION_PREFIX[cell.section]}${cell.row} as ${cell.principal}`;
+}
+var MAX_LINES = 50;
+function capped(lines) {
+  if (lines.length <= MAX_LINES) {
+    return [...lines];
+  }
+  return [...lines.slice(0, MAX_LINES), `  ... and ${lines.length - MAX_LINES} more`];
+}
+function shownPrincipal(principal) {
+  if (principal === null) {
+    return "anonymous";
+  }
+  return principal.kind === null ? "no kind" : `kind ${principal.kind}`;
+}
+function flipRank(change2) {
+  const flip = accessFlip(change2);
+  if (flip === "opens access") {
+    return 0;
+  }
+  return flip === "closes access" ? 1 : 2;
+}
+function describeDifferences(comparison) {
+  const principals = comparison.principals.map(
+    (change2) => `  principal ${change2.name}: ${shownPrincipal(change2.before)} \u2192 ${shownPrincipal(change2.after)}`
+  );
+  const cells = [...comparison.changed].sort((a, b) => flipRank(a) - flipRank(b)).map((change2) => {
+    const flip = accessFlip(change2);
+    const line = `  ${cellName(change2)}: ${String(change2.before)} \u2192 ${String(change2.after)}`;
+    return flip === void 0 ? line : `${line} (${flip})`;
+  });
+  return [...capped(principals), ...capped(cells)];
+}
+function describeReshape(comparison) {
+  const lines = (label, items) => capped(items.map((item) => `  ${label}: ${item}`));
+  const cells = comparison.cells.map(
+    (cell) => `${cellName(cell)}: ${cell.before ?? "none"} \u2192 ${cell.after ?? "none"}`
+  );
+  return [
+    ...lines("added", comparison.rowsAdded),
+    ...lines("removed", comparison.rowsRemoved),
+    ...lines("added principal", comparison.principalsAdded),
+    ...lines("removed principal", comparison.principalsRemoved),
+    ...lines("now excluded", comparison.excludedAdded),
+    ...lines("no longer excluded", comparison.excludedRemoved),
+    ...lines("cell", cells)
+  ];
+}
+
+// src/testing/accessSnapshotFile.ts
+var ACCESS_SNAPSHOT_ENV = "QD_UPDATE_ACCESS_SNAPSHOT";
+function updateRequested(value = process.env[ACCESS_SNAPSHOT_ENV]) {
+  return value === "1" || value === "true";
+}
+function accessSnapshotFileOf(testFile) {
+  return join2(dirname2(testFile), "__access__", `${basename2(testFile)}.json`);
+}
+var claimed2 = /* @__PURE__ */ new WeakMap();
+var NO_RUNNER2 = {};
+function claimFile(path, state) {
+  const runner = state.runner ?? NO_RUNNER2;
+  const files = claimed2.get(runner) ?? /* @__PURE__ */ new Map();
+  claimed2.set(runner, files);
+  const test = state.testName ?? "";
+  const owner = files.get(path);
+  if (owner !== void 0 && owner !== test) {
+    throw new TypeError(
+      `snapshotAccessMatrix: two tests take an access snapshot into ${shownPath(path)} ("${owner}" and "${test}"); take one snapshot per test file (one test file per service, or pass { file })`
+    );
+  }
+  files.set(path, test);
+}
+function snapshotPathOf(file) {
+  const state = runnerState();
+  const testFile = file ?? state.testPath;
+  if (testFile === void 0) {
+    throw new TypeError(
+      "snapshotAccessMatrix: no test file is running to put the snapshot beside; pass { file }"
+    );
+  }
+  const path = accessSnapshotFileOf(testFile);
+  claimFile(path, state);
+  return path;
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRow(value) {
+  return isRecord2(value) && Object.values(value).every((cell) => typeof cell === "string");
+}
+function isPrincipal2(value) {
+  return value === null || isRecord2(value) && (value.kind === null || typeof value.kind === "string");
+}
+function isSnapshot(value) {
+  if (!isRecord2(value) || value.version !== 1 || !isRecord2(value.principals)) {
+    return false;
+  }
+  const { principals, excluded } = value;
+  return ACCESS_SECTIONS.every((section) => {
+    const rows = value[section];
+    return isRecord2(rows) && Object.values(rows).every(isRow);
+  }) && Object.values(principals).every(isPrincipal2) && Array.isArray(excluded) && excluded.every((name) => typeof name === "string");
+}
+function readAccessSnapshot(path) {
+  if (!existsSync2(path)) {
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync2(path, "utf8"));
+  } catch {
+    parsed = void 0;
+  }
+  if (!isSnapshot(parsed)) {
+    throw new Error(
+      `snapshotAccessMatrix: ${shownPath(path)} is not an access snapshot ({ "version": 1, "principals", "methods", "subscriptions", "collections", "excluded" }); delete it to record the matrix again`
+    );
+  }
+  return parsed;
+}
+function sortKeys(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortKeys);
+  }
+  if (!isRecord2(value)) {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.keys(value).sort().map((key) => [key, sortKeys(value[key])])
+  );
+}
+function writeAccessSnapshot(path, snapshot) {
+  const sorted = { ...snapshot, excluded: [...snapshot.excluded].sort() };
+  mkdirSync2(dirname2(path), { recursive: true });
+  writeFileSync2(path, `${JSON.stringify(sortKeys(sorted), null, 2)}
+`);
+}
+function plural(count, one, many) {
+  return `${count} ${count === 1 ? one : many}`;
+}
+function inconclusiveNote(inconclusive) {
+  if (inconclusive.length === 0) {
+    return [];
+  }
+  return [
+    `${plural(inconclusive.length, "cell was", "cells were")} never called (VALIDATION): no input passed the method's input schema; give their inputs with inputs.`
+  ];
+}
+function differencesError(shown, comparison, inconclusive) {
+  const counts = [
+    ...comparison.changed.length > 0 ? [plural(comparison.changed.length, "cell differs", "cells differ")] : [],
+    ...comparison.principals.length > 0 ? [plural(comparison.principals.length, "principal differs", "principals differ")] : []
+  ];
+  return new Error(
+    [
+      `snapshotAccessMatrix: ${counts.join(" and ")} from the access snapshot (${shown}):`,
+      ...describeDifferences(comparison),
+      ...isReshaped(comparison) ? describeReshape(comparison) : [],
+      `If every change is meant, run the tests again with ${ACCESS_SNAPSHOT_ENV}=1, review the file and commit it.`,
+      ...inconclusiveNote(inconclusive)
+    ].join("\n")
+  );
+}
+function settleSnapshot(path, snapshot, inconclusive) {
+  const shown = shownPath(path);
+  const ci = underCi();
+  const update = updateRequested();
+  if (update && ci) {
+    throw new Error(
+      `snapshotAccessMatrix: ${ACCESS_SNAPSHOT_ENV} is set under CI, where an access snapshot is only compared: rewrite ${shown} locally, review it and commit it`
+    );
+  }
+  const stored = readAccessSnapshot(path);
+  if (stored === void 0) {
+    if (ci) {
+      throw new Error(
+        [
+          `snapshotAccessMatrix: there is no access snapshot at ${shown}, and under CI none is written: a snapshot that writes itself pins nothing.`,
+          "Run the tests locally to record it, review it and commit it.",
+          ...inconclusiveNote(inconclusive)
+        ].join("\n")
+      );
+    }
+    writeAccessSnapshot(path, snapshot);
+    return "written";
+  }
+  const comparison = compareAccessSnapshots(stored, snapshot);
+  const differs = hasDifferences(comparison);
+  if (!differs && !isReshaped(comparison)) {
+    return "unchanged";
+  }
+  if (differs && !update) {
+    throw differencesError(shown, comparison, inconclusive);
+  }
+  if (ci) {
+    throw new Error(
+      [
+        `snapshotAccessMatrix: the access matrix has other cells than its snapshot (${shown}); rerun locally to accept:`,
+        ...describeReshape(comparison),
+        "Run the tests without CI to write the snapshot, review it and commit it.",
+        ...inconclusiveNote(inconclusive)
+      ].join("\n")
+    );
+  }
+  writeAccessSnapshot(path, snapshot);
+  return "updated";
+}
+
 // src/testing/accessMatrix.ts
 var ANONYMOUS = "anonymous";
 function matches(expected, actual, anonymous) {
@@ -733,9 +1334,10 @@ async function outcomeOf(call) {
 }
 function report(serviceName, cells) {
   const failed = cells.filter((cell) => !cell.pass);
-  const lines = failed.map(
-    (cell) => `  ${cell.case} as ${cell.principal}: expected ${cell.expected}, got ${cell.actual}`
-  );
+  const lines = failed.map((cell) => {
+    const kind = cell.kind === void 0 ? "" : ` (kind ${cell.kind})`;
+    return `  ${cell.case} as ${cell.principal}${kind}: expected ${cell.expected}, got ${cell.actual}`;
+  });
   return `describeAccessMatrix(${serviceName}): ${failed.length} of ${cells.length} cells differ
 ${lines.join("\n")}`;
 }
@@ -789,7 +1391,14 @@ async function describeAccessMatrix(app, options) {
         const made = typeof input === "function" ? await input({ name, principal }) : input;
         const actual = await outcomeOf(() => method(made));
         const pass = matches(expected, actual, principal === null);
-        cells.push({ case: entry.label ?? entry.method, principal: name, expected, actual, pass });
+        cells.push({
+          case: entry.label ?? entry.method,
+          principal: name,
+          kind: principal?.kind,
+          expected,
+          actual,
+          pass
+        });
       }
     }
   } finally {
@@ -800,11 +1409,416 @@ async function describeAccessMatrix(app, options) {
   }
   return { cells };
 }
+
+// src/testing/accessSnapshotPlan.ts
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function fail(message) {
+  throw new TypeError(`snapshotAccessMatrix: ${message}`);
+}
+function byName(a, b) {
+  if (a === b) {
+    return 0;
+  }
+  return a < b ? -1 : 1;
+}
+function keyOf(base, variant) {
+  return variant === void 0 ? base : `${base} (${variant})`;
+}
+function readPrincipals(given, fixture) {
+  const record2 = typeof given === "function" ? given(fixture) : given;
+  if (!isRecord3(record2)) {
+    fail("principals must map names to principals (null for an anonymous caller)");
+  }
+  const principals = /* @__PURE__ */ new Map();
+  for (const [name, principal] of Object.entries(record2)) {
+    if (principal !== null && !isRecord3(principal)) {
+      fail(`principals.${name} must be a principal, or null for an anonymous caller`);
+    }
+    principals.set(name, principal);
+  }
+  if (![...principals.values()].includes(null)) {
+    if (principals.has(ANONYMOUS)) {
+      fail(
+        `a principal is named "${ANONYMOUS}", the name of the anonymous caller added for you: name your anonymous caller with null, or rename that principal`
+      );
+    }
+    principals.set(ANONYMOUS, null);
+  }
+  return principals;
+}
+function variantsIn(service, value) {
+  if (typeof value === "string" && value.length > 0) {
+    return /* @__PURE__ */ new Map([[void 0, value]]);
+  }
+  const entries = isRecord3(value) ? Object.entries(value) : [];
+  const ids = [];
+  for (const [variant, id] of entries) {
+    if (typeof id === "string" && id.length > 0) {
+      ids.push([variant, id]);
+    }
+  }
+  if (ids.length === 0 || ids.length !== entries.length) {
+    fail(`rows.${service} must be a row id, or named row ids ({ own: id, other: id })`);
+  }
+  return new Map(ids.sort(([a], [b]) => byName(a, b)));
+}
+function readRows(given, served) {
+  if (!isRecord3(given)) {
+    fail("rows(fixture) must map service names to a row id, or to named row ids");
+  }
+  const rows = /* @__PURE__ */ new Map();
+  for (const [service, value] of Object.entries(given)) {
+    if (!served.has(service)) {
+      fail(`rows names ${service}, which the app does not serve`);
+    }
+    rows.set(service, variantsIn(service, value));
+  }
+  return rows;
+}
+function sameShape(a, b) {
+  const names = (map) => [...map.keys()].join("\n");
+  const rows = (of) => [...of].map(([service, ids]) => `${service}:${names(ids)}`).join("\n\n");
+  return names(a.principals) === names(b.principals) && rows(a.rows) === rows(b.rows);
+}
+function variantsOf(rows, service) {
+  const ids = service === void 0 ? void 0 : rows.get(service);
+  return ids === void 0 ? [void 0] : [...ids.keys()];
+}
+function servicesOf(app, given) {
+  const { services } = app.server.dispatcher.registry;
+  if (given === void 0) {
+    return [...services.values()].sort((a, b) => byName(a.name, b.name));
+  }
+  if (!Array.isArray(given)) {
+    fail("services must be a list of services the app serves");
+  }
+  for (const service of given) {
+    if (services.get(service.name) !== service) {
+      fail(`the app does not serve ${service.name}`);
+    }
+  }
+  return [...new Set(given)].sort((a, b) => byName(a.name, b.name));
+}
+function excludedOf(services, given) {
+  const known = new Set(
+    services.flatMap(
+      (service) => Object.keys(service.methods).map((name) => `${service.name}.${name}`)
+    )
+  );
+  if (given !== void 0 && !Array.isArray(given)) {
+    fail("exclude must be a list of methods, as <service>.<method>");
+  }
+  const excluded = /* @__PURE__ */ new Set();
+  for (const name of given ?? []) {
+    if (typeof name !== "string" || !known.has(name)) {
+      fail(
+        `exclude names ${String(name)}, which is no method (<service>.<method>) of the matrix's services`
+      );
+    }
+    excluded.add(name);
+  }
+  return excluded;
+}
+function methodRows(services, excluded, rows) {
+  const list = [];
+  for (const service of services) {
+    for (const name of Object.keys(service.methods).sort(byName)) {
+      const method = service.methods[name];
+      const base = `${service.name}.${name}`;
+      if (method === void 0 || excluded.has(base)) {
+        continue;
+      }
+      const rowService = rowServiceOf(service, method);
+      for (const variant of variantsOf(rows, rowService)) {
+        list.push({ key: keyOf(base, variant), service, method, rowService, variant });
+      }
+    }
+  }
+  return list;
+}
+function subscribeRows(services, rows) {
+  return services.filter((service) => service.model !== void 0 && service.contract.entity !== void 0).map((service) => ({
+    service: service.name,
+    keys: new Map(
+      variantsOf(rows, service.name).map((variant) => [variant, keyOf(service.name, variant)])
+    )
+  }));
+}
+function scopeRows(services, rows) {
+  const list = [];
+  for (const service of services) {
+    for (const collection of [...service.collections.keys()].sort(byName)) {
+      const anchor = service.collections.get(collection)?.anchor?.name;
+      const base = `${service.name}.${collection}`;
+      if (anchor === void 0) {
+        list.push({
+          key: keyOf(base, "self"),
+          service: service.name,
+          collection,
+          anchor,
+          variant: void 0
+        });
+        continue;
+      }
+      for (const variant of variantsOf(rows, anchor)) {
+        list.push({
+          key: keyOf(base, variant),
+          service: service.name,
+          collection,
+          anchor,
+          variant
+        });
+      }
+    }
+  }
+  return list;
+}
+function checkRowsCover(plan, rows) {
+  const needs = /* @__PURE__ */ new Map();
+  const need = (service, what) => {
+    if (service !== void 0 && !rows.has(service)) {
+      needs.set(service, (needs.get(service) ?? /* @__PURE__ */ new Set()).add(what));
+    }
+  };
+  for (const row of [...plan.queries, ...plan.mutations]) {
+    need(row.rowService, `${row.service.name}.${row.method.name}`);
+  }
+  for (const row of plan.subscribes) {
+    need(row.service, `qd:sub ${row.service}`);
+  }
+  for (const row of plan.scopes) {
+    need(row.anchor, `qd:col:sub ${row.service}.${row.collection}`);
+  }
+  if (needs.size > 0) {
+    const missing = [...needs].map(([service, what]) => `${service} (for ${[...what].join(", ")})`);
+    fail(
+      `rows names no row of ${missing.join("; ")}. Give rows(fixture) a row id of each, or named row ids ({ own: id, other: id }); leave a method out with exclude`
+    );
+  }
+}
+function planOf(services, excluded, rows) {
+  const methods = methodRows(services, excluded, rows);
+  const plan = {
+    subscribes: subscribeRows(services, rows),
+    scopes: scopeRows(services, rows),
+    queries: methods.filter((row) => row.method.kind === "query"),
+    mutations: methods.filter((row) => row.method.kind === "mutation"),
+    excluded: [...excluded].sort(byName)
+  };
+  checkRowsCover(plan, rows);
+  return plan;
+}
+
+// src/testing/accessSnapshot.ts
+var REFUSALS = /* @__PURE__ */ new Set(["UNAUTHENTICATED", "FORBIDDEN", "VALIDATION"]);
+var ANONYMOUS_SCOPE = "anonymous";
+function record(cells, key, principal, outcome) {
+  const row = cells.get(key) ?? /* @__PURE__ */ new Map();
+  cells.set(key, row.set(principal, outcome));
+}
+async function reset(run) {
+  const fixture = await run.options.reset();
+  const next = {
+    principals: readPrincipals(run.options.principals, fixture),
+    rows: readRows(run.options.rows(fixture), run.served)
+  };
+  if (!sameShape(run, next)) {
+    fail(
+      "principals and rows must name the same principals, services and variants after every reset"
+    );
+  }
+  run.fixture = fixture;
+  run.principals = next.principals;
+  run.rows = next.rows;
+}
+function rowIdOf(rows, service, variant) {
+  return rows.get(service)?.get(variant);
+}
+async function outcomeOf2(call) {
+  try {
+    await call();
+    return "ok";
+  } catch (error) {
+    if (error instanceof QuickdrawError) {
+      return error.code;
+    }
+    throw error;
+  }
+}
+function outcomeOfReply(reply, event) {
+  if (isRecord3(reply) && reply.ok === true) {
+    return "ok";
+  }
+  const code = isRecord3(reply) && isRecord3(reply.e) ? reply.e.code : void 0;
+  if (typeof code !== "string") {
+    throw new Error(`snapshotAccessMatrix: ${event} answered ${JSON.stringify(reply)}`);
+  }
+  return code;
+}
+async function inputOf(run, row, name) {
+  const id = row.rowService === void 0 ? void 0 : rowIdOf(run.rows, row.rowService, row.variant);
+  const ref = {
+    service: row.service.name,
+    method: row.method.name,
+    kind: row.method.kind,
+    variant: row.variant,
+    row: id,
+    principal: name
+  };
+  const given = await run.options.inputs?.(ref, run.fixture);
+  if (given !== void 0) {
+    return await isValidInput(row.method, given) ? { value: given } : void 0;
+  }
+  const made = await generatedInput(row.method, id);
+  return made === void 0 ? void 0 : { value: made.input };
+}
+function methodOf(app, row, principal) {
+  const caller = app.as(principal);
+  const method = caller[row.service.name]?.[row.method.name];
+  if (method === void 0) {
+    throw new TypeError(`snapshotAccessMatrix: ${row.service.name} has no ${row.method.name}`);
+  }
+  return method;
+}
+async function callCell(run, row, name) {
+  const input = await inputOf(run, row, name);
+  if (input === void 0) {
+    record(run.methods, row.key, name, "VALIDATION");
+    run.inconclusive.push(`${row.key} as ${name}`);
+    return;
+  }
+  const method = methodOf(run.app, row, run.principals.get(name) ?? null);
+  const outcome = await outcomeOf2(() => method(input.value));
+  record(run.methods, row.key, name, outcome);
+  if (row.method.kind === "mutation" && !REFUSALS.has(outcome)) {
+    await reset(run);
+  }
+}
+async function subscribeEntities(run, connection, name) {
+  for (const row of run.plan.subscribes) {
+    const variants = [...row.keys.keys()];
+    const ids = variants.map((variant) => rowIdOf(run.rows, row.service, variant) ?? "");
+    const reply = await emitWithAck(connection.socket, "qd:sub", { s: row.service, ids });
+    const results = isRecord3(reply) && reply.ok === true && Array.isArray(reply.r) ? reply.r : void 0;
+    variants.forEach((variant, index) => {
+      const outcome = outcomeOfReply(results === void 0 ? reply : results[index], "qd:sub");
+      record(run.subscriptions, row.keys.get(variant) ?? row.service, name, outcome);
+    });
+  }
+}
+async function subscribeScopes(run, connection, name) {
+  const principal = run.principals.get(name) ?? null;
+  for (const row of run.plan.scopes) {
+    const scope = row.anchor === void 0 ? principal?.userId ?? ANONYMOUS_SCOPE : rowIdOf(run.rows, row.anchor, row.variant) ?? "";
+    const frame = { s: row.service, c: row.collection, scope, limit: 1 };
+    const reply = await emitWithAck(connection.socket, "qd:col:sub", frame);
+    record(run.collections, row.key, name, outcomeOfReply(reply, "qd:col:sub"));
+  }
+}
+function refusalCode(error) {
+  const data = error instanceof Error ? error.data : void 0;
+  const code = isRecord3(data) ? data.code : void 0;
+  return typeof code === "string" ? code : void 0;
+}
+function refuseAll(run, name, code) {
+  for (const row of run.plan.subscribes) {
+    for (const key of row.keys.values()) {
+      record(run.subscriptions, key, name, code);
+    }
+  }
+  for (const row of run.plan.scopes) {
+    record(run.collections, row.key, name, code);
+  }
+}
+async function subscribeAll(run, name) {
+  if (run.plan.subscribes.length === 0 && run.plan.scopes.length === 0) {
+    return;
+  }
+  let connection;
+  try {
+    connection = await run.app.connect(run.principals.get(name) ?? null);
+  } catch (error) {
+    const code = refusalCode(error);
+    if (code === void 0) {
+      throw error;
+    }
+    refuseAll(run, name, code);
+    return;
+  }
+  try {
+    await subscribeEntities(run, connection, name);
+    await subscribeScopes(run, connection, name);
+  } finally {
+    connection.close();
+  }
+}
+function rowsOf(cells) {
+  return Object.fromEntries([...cells].map(([key, row]) => [key, Object.fromEntries(row)]));
+}
+function snapshotOf(run, principals) {
+  const recorded = [...principals].map(([name, principal]) => [
+    name,
+    principal === null ? null : { kind: principal.kind ?? null }
+  ]);
+  return {
+    version: 1,
+    principals: Object.fromEntries(recorded),
+    methods: rowsOf(run.methods),
+    subscriptions: rowsOf(run.subscriptions),
+    collections: rowsOf(run.collections),
+    excluded: run.plan.excluded
+  };
+}
+function checkOptions2(options) {
+  if (!isRecord3(options) || typeof options.reset !== "function" || typeof options.rows !== "function") {
+    fail("pass { principals, reset, rows }: reset() seeds the rows, rows(fixture) names them");
+  }
+  if (options.inputs !== void 0 && typeof options.inputs !== "function") {
+    fail("inputs must be a function of the cell and the fixture");
+  }
+}
+async function snapshotAccessMatrix(app, options) {
+  checkOptions2(options);
+  const path = snapshotPathOf(options.file);
+  const generic = app;
+  const served = generic.server.dispatcher.registry.services;
+  const services = servicesOf(generic, options.services);
+  const excluded = excludedOf(services, options.exclude);
+  const fixture = await options.reset();
+  const principals = readPrincipals(options.principals, fixture);
+  const rows = readRows(options.rows(fixture), served);
+  const run = {
+    app: generic,
+    options,
+    served,
+    plan: planOf(services, excluded, rows),
+    fixture,
+    principals,
+    rows,
+    methods: /* @__PURE__ */ new Map(),
+    subscriptions: /* @__PURE__ */ new Map(),
+    collections: /* @__PURE__ */ new Map(),
+    inconclusive: []
+  };
+  for (const name of principals.keys()) {
+    await subscribeAll(run, name);
+    for (const row of [...run.plan.queries, ...run.plan.mutations]) {
+      await callCell(run, row, name);
+    }
+  }
+  const snapshot = snapshotOf(run, principals);
+  const change2 = settleSnapshot(path, snapshot, run.inconclusive);
+  return { path, change: change2, snapshot, inconclusive: run.inconclusive };
+}
 export {
+  ACCESS_SNAPSHOT_ENV,
   ANONYMOUS,
   BUDGET_BYTES_TOLERANCE,
   BUDGET_GROWTH_ENV,
   DevWarningError,
+  accessSnapshotFileOf,
   budgetFileOf,
   createRecordingSink,
   createTestApp,
@@ -812,6 +1826,7 @@ export {
   emitWithAck,
   eventFrames,
   expectBudget,
+  snapshotAccessMatrix,
   streamFrames,
   waitForEvent
 };