create-evda 0.1.0

package/lib/manifest.mjs

@@ -0,0 +1,181 @@
+// evda.json and .evda/version.
+//
+// Two copies of the schema version exist on purpose. `evda.json` declares what the record claims
+// to be; `.evda/version` records what a tool last left on disk. They are written by different
+// acts (a hand edit or a newer tool can change the manifest; only a migration changes the version
+// file), so a disagreement between them is information, and the tool refuses rather than guesses.
+//
+// Unknown keys in the manifest are preserved on every write. A v1 tool reading a v2 manifest
+// mutates only the keys it knows and writes the object back whole, in the order it was read.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { EvdaError } from "./errors.mjs";
+
+export const SCHEMA_VERSION = 1;
+export const KNOWN_LAYERS = ["record", "ledger", "circles"];
+export const KNOWN_KEYS = ["evda", "id", "name", "owner", "created", "layers", "mapping"];
+
+// Who holds the record (Spec 07, section 1): a person, an agent, or a company. `owner.kind` on the
+// manifest; absent means person. `id` is the record's atlas id, the name another record uses in a
+// grant (`@<id>/...` in a reference, `principalId` in a member tuple).
+export const HOLDER_KINDS = ["person", "agent", "company"];
+
+export function holderOf(evda) {
+  const m = evda.manifest ?? evda;
+  const owner = m.owner && typeof m.owner === "object" ? m.owner : {};
+  return { id: typeof m.id === "string" && m.id.trim() !== "" ? m.id : null, kind: owner.kind ?? "person", name: typeof owner.name === "string" ? owner.name : null };
+}
+
+// Problems with the holder fields, for doctor. [] when they are fine or absent.
+export function holderProblems(manifest) {
+  const out = [];
+  if (manifest.owner !== undefined && (manifest.owner === null || typeof manifest.owner !== "object" || Array.isArray(manifest.owner))) out.push(`"owner" must be a mapping.`);
+  else if (manifest.owner?.kind !== undefined && !HOLDER_KINDS.includes(manifest.owner.kind)) out.push(`"owner.kind" must be one of ${HOLDER_KINDS.join(", ")}, got ${JSON.stringify(manifest.owner.kind)}.`);
+  if (manifest.id !== undefined) {
+    if (typeof manifest.id !== "string" || manifest.id.trim() === "") out.push(`"id" must be the record's atlas id, a non-empty string.`);
+    else if (/\s/.test(manifest.id) || manifest.id.includes("/") || manifest.id.includes("--")) out.push(`"id" ${JSON.stringify(manifest.id)} is not a record id: no whitespace, no /, no -- (it names this record in another record's grant).`);
+  }
+  return out;
+}
+
+export const manifestPath = (dir) => join(dir, "evda.json");
+export const versionPath = (dir) => join(dir, ".evda", "version");
+
+// Walk up from `start` until a directory holding evda.json is found. Null if none.
+export function findRoot(start = process.cwd()) {
+  let dir = resolve(start);
+  for (;;) {
+    if (existsSync(manifestPath(dir))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function readManifest(dir) {
+  const p = manifestPath(dir);
+  if (!existsSync(p)) {
+    throw new EvdaError(`REFUSED: no evda.json in ${dir}. This directory is not an EVDA.`, {
+      code: "NO_MANIFEST",
+      exit: 2,
+    });
+  }
+  let m;
+  try {
+    m = JSON.parse(readFileSync(p, "utf8"));
+  } catch (e) {
+    throw new EvdaError(`REFUSED: evda.json is not valid JSON (${e.message}). Nothing was written.`, {
+      code: "BAD_MANIFEST",
+      exit: 2,
+    });
+  }
+  if (m === null || typeof m !== "object" || Array.isArray(m)) {
+    throw new EvdaError("REFUSED: evda.json must hold a JSON object.", { code: "BAD_MANIFEST", exit: 2 });
+  }
+  if (!Number.isInteger(m.evda) || m.evda < 1) {
+    throw new EvdaError('REFUSED: evda.json has no integer "evda" schema version.', {
+      code: "BAD_MANIFEST",
+      exit: 2,
+    });
+  }
+  if (!Array.isArray(m.layers) || !m.layers.every((l) => typeof l === "string")) {
+    throw new EvdaError('REFUSED: evda.json "layers" must be a list of layer names.', {
+      code: "BAD_MANIFEST",
+      exit: 2,
+    });
+  }
+  if (m.mapping === undefined) {
+    throw new EvdaError(
+      'REFUSED: evda.json has no "mapping". Every tool reads roles through the mapping, so without one there is nothing to read.',
+      { code: "BAD_MANIFEST", exit: 2 }
+    );
+  }
+  if (m.mapping === null || typeof m.mapping !== "object" || Array.isArray(m.mapping)) {
+    throw new EvdaError('REFUSED: evda.json "mapping" must be an object of role -> relative path.', {
+      code: "BAD_MANIFEST",
+      exit: 2,
+    });
+  }
+  for (const [role, rel] of Object.entries(m.mapping)) {
+    if (typeof rel !== "string" || rel === "") {
+      throw new EvdaError(`REFUSED: mapping for role "${role}" is not a path.`, { code: "BAD_MANIFEST", exit: 2 });
+    }
+  }
+  return m;
+}
+
+export function unknownKeys(manifest) {
+  return Object.keys(manifest).filter((k) => !KNOWN_KEYS.includes(k));
+}
+
+export function unknownLayers(manifest) {
+  return manifest.layers.filter((l) => !KNOWN_LAYERS.includes(l));
+}
+
+// Writes the object back whole. Key order is insertion order, which JSON.parse preserves, so a
+// manifest read and written unchanged is byte-identical apart from formatting.
+export function writeManifest(dir, manifest) {
+  writeFileSync(manifestPath(dir), JSON.stringify(manifest, null, 2) + "\n");
+}
+
+// null when the file is absent. Throws when it is present and not an integer.
+export function readVersion(dir) {
+  const p = versionPath(dir);
+  if (!existsSync(p)) return null;
+  const raw = readFileSync(p, "utf8").trim();
+  if (!/^\d+$/.test(raw)) {
+    throw new EvdaError(`REFUSED: .evda/version holds "${raw}", which is not a schema version.`, {
+      code: "BAD_VERSION",
+      exit: 2,
+    });
+  }
+  return Number(raw);
+}
+
+export function writeVersion(dir, v) {
+  mkdirSync(join(dir, ".evda"), { recursive: true });
+  writeFileSync(versionPath(dir), `${v}\n`);
+}
+
+// The refusal. Returns what it compared so callers can print it.
+export function checkVersion(dir, manifest) {
+  const onDisk = readVersion(dir);
+  if (onDisk === null) {
+    throw new EvdaError(
+      [
+        `REFUSED: evda.json declares schema ${manifest.evda} but there is no .evda/version file.`,
+        "  The manifest says what the record claims to be; .evda/version says what is actually on disk.",
+        "  Without the second there is nothing to check the first against, and guessing is how a record",
+        "  starts disagreeing with itself.",
+        "  If .evda/ was deleted on purpose: run `evda reindex --adopt`, which validates the layout",
+        `  against schema ${manifest.evda} and writes the version file only if it passes.`,
+      ].join("\n"),
+      { code: "NO_VERSION", exit: 2 }
+    );
+  }
+  if (onDisk !== manifest.evda) {
+    throw new EvdaError(
+      [
+        `REFUSED: evda.json declares schema ${manifest.evda} but .evda/version says ${onDisk}.`,
+        "  These are two records of one fact and they disagree. Nothing was read or written.",
+        `  If a migration was interrupted: run \`evda migrate\`, which moves the files on disk to ${manifest.evda}.`,
+        `  If evda.json was edited by hand: put "evda" back to ${onDisk}.`,
+      ].join("\n"),
+      { code: "VERSION_MISMATCH", exit: 2 }
+    );
+  }
+  return {
+    declared: manifest.evda,
+    onDisk,
+    newerThanTool: manifest.evda > SCHEMA_VERSION,
+  };
+}
+
+// Open a record for operating. Every command goes through here except `migrate` and
+// `reindex --adopt`, which exist to repair the two states this refuses.
+export function openEvda(dir) {
+  const manifest = readManifest(dir);
+  const version = checkVersion(dir, manifest);
+  return { dir: resolve(dir), manifest, version };
+}

package/lib/migrate.mjs

@@ -0,0 +1,66 @@
+// Migrations are files, forward-only, and each one says what it cannot reverse (Spec 05).
+//
+// A migration is `migrations/NNNN-<name>.mjs` with a default export:
+//   { from: 1, to: 2, cannotReverse: "one sentence", up(dir) }
+// `cannotReverse` is required and non-empty. A migration that does not say what it destroys does
+// not run. There are no down migrations; a record is never moved backwards, it is restored from
+// a copy.
+//
+// This runner is the only thing that writes .evda/version after `create-evda`.
+
+import { readdirSync, existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { EvdaError } from "./errors.mjs";
+import { readManifest, readVersion, writeVersion, writeManifest, SCHEMA_VERSION } from "./manifest.mjs";
+
+export const DEFAULT_MIGRATIONS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "migrations");
+
+export async function loadMigrations(dir = DEFAULT_MIGRATIONS_DIR) {
+  if (!existsSync(dir)) return [];
+  const files = readdirSync(dir).filter((f) => /^\d{4}-.*\.mjs$/.test(f)).sort();
+  const out = [];
+  for (const f of files) {
+    const mod = await import(pathToFileURL(join(dir, f)).href);
+    const m = mod.default;
+    if (!m || !Number.isInteger(m.from) || !Number.isInteger(m.to) || typeof m.up !== "function") {
+      throw new EvdaError(`migration ${f} does not export { from, to, up }.`, { exit: 2 });
+    }
+    if (m.to !== m.from + 1) throw new EvdaError(`migration ${f} must move exactly one version (${m.from} -> ${m.to}).`, { exit: 2 });
+    if (typeof m.cannotReverse !== "string" || m.cannotReverse.trim() === "") {
+      throw new EvdaError(`REFUSED: migration ${f} does not say what it cannot reverse. It does not run until it does.`, { exit: 2 });
+    }
+    out.push({ file: f, ...m });
+  }
+  return out;
+}
+
+export async function migrate(dir, { migrationsDir = DEFAULT_MIGRATIONS_DIR, target = SCHEMA_VERSION, out = () => {} } = {}) {
+  const manifest = readManifest(dir);
+  const onDisk = readVersion(dir);
+  if (onDisk === null) {
+    throw new EvdaError("REFUSED: no .evda/version, so there is no starting point to migrate from. Run `evda reindex --adopt` first.", { exit: 2 });
+  }
+  const goal = Math.max(target, manifest.evda);
+  if (onDisk > goal) {
+    throw new EvdaError(`REFUSED: .evda/version is ${onDisk}, newer than anything this tool knows (${goal}). Migrations are forward-only.`, { exit: 2 });
+  }
+  const all = await loadMigrations(migrationsDir);
+  const ran = [];
+  let v = onDisk;
+  while (v < goal) {
+    const m = all.find((x) => x.from === v);
+    if (!m) throw new EvdaError(`no migration from ${v} to ${v + 1}. On disk: ${onDisk}, wanted: ${goal}. Ran: ${ran.join(", ") || "none"}.`, { exit: 2 });
+    out(`migrate ${m.from} -> ${m.to}  ${m.file}`);
+    out(`  cannot reverse: ${m.cannotReverse}`);
+    await m.up(dir);
+    v = m.to;
+    writeVersion(dir, v);
+    ran.push(m.file);
+  }
+  if (manifest.evda !== v) {
+    manifest.evda = v;
+    writeManifest(dir, manifest);
+  }
+  return { from: onDisk, to: v, ran };
+}

package/lib/record.mjs

@@ -0,0 +1,80 @@
+// The corpus, read through roles. `moment` is the occurrence primitive from Spec 05: given a
+// window, return what was written. The interface is lifted from Iridesce's moment(); the music and
+// instrument halves are Iridesce's own sources and did not transfer.
+//
+// Same honesty rule as the original: a role the record does not have is reported as absent, never
+// as an empty list, because an empty list is a claim that nothing was written.
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { resolveRole, rolesForLayer } from "./roles.mjs";
+import { EvdaError } from "./errors.mjs";
+
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const LEADING_DATE = /^(\d{4}-\d{2}-\d{2})/;
+
+export function mdFiles(dir, { recursive = true } = {}) {
+  const out = [];
+  const walk = (d) => {
+    for (const name of readdirSync(d).sort()) {
+      if (name.startsWith(".")) continue;
+      const p = join(d, name);
+      const st = statSync(p);
+      if (st.isDirectory()) { if (recursive) walk(p); continue; }
+      if (name.endsWith(".md")) out.push(p);
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+// The date of a record file: leading YYYY-MM-DD in the filename, else a `date:` or `created:`
+// frontmatter key. null when neither exists.
+export function fileDate(path, text) {
+  const base = path.split("/").pop();
+  const fromName = LEADING_DATE.exec(base)?.[1];
+  if (fromName) return fromName;
+  if (text.startsWith("---")) {
+    const end = text.indexOf("\n---", 3);
+    const fm = end === -1 ? "" : text.slice(3, end);
+    const m = /^(?:date|created):\s*["']?(\d{4}-\d{2}-\d{2})/m.exec(fm);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+export function headings(text) {
+  return text.split("\n").filter((l) => /^#{1,6} /.test(l)).map((l) => l.replace(/^#+ /, "").trim());
+}
+
+export function moment(evda, { from, to = from } = {}) {
+  if (!DATE.test(from ?? "") || !DATE.test(to ?? "")) {
+    throw new EvdaError(`moment needs YYYY-MM-DD dates, got ${from}..${to}`);
+  }
+  const out = { window: { from, to }, roles: {}, entries: [] };
+  for (const role of rolesForLayer("record")) {
+    const r = resolveRole(evda, role);
+    if (!r.mapped) { out.roles[role] = "absent"; continue; }
+    if (!r.exists) {
+      throw new EvdaError(`role ${role} is mapped to "${r.rel}" but that directory does not exist.`, { code: "MISSING_ROLE" });
+    }
+    let undated = 0;
+    const files = mdFiles(r.abs);
+    for (const p of files) {
+      const text = readFileSync(p, "utf8");
+      const date = fileDate(p, text);
+      if (!date) { undated += 1; continue; }
+      if (date < from || date > to) continue;
+      out.entries.push({
+        date,
+        role,
+        path: relative(evda.dir, p),
+        words: text.split(/\s+/).filter(Boolean).length,
+        headings: headings(text),
+      });
+    }
+    out.roles[role] = { path: r.rel, files: files.length, undated };
+  }
+  out.entries.sort((a, b) => (a.date === b.date ? a.path.localeCompare(b.path) : a.date.localeCompare(b.date)));
+  return out;
+}

package/lib/references.mjs

@@ -0,0 +1,283 @@
+// References instead of copies (Spec 07, section 4; Spec 00 #62).
+//
+// A reference is a stable pointer to something the record does not hold. It is written once, in
+// the entry, and resolved when read. What is stored is the pointer, a label to render when the
+// source is unreachable, and the date it last resolved. Never the payload, and never a secret.
+//
+// Four schemes, each a pointer at something outside this record:
+//
+//   contacts:<identifier>                 an entry in the device's Contacts
+//   1password:op://<vault>/<item>         a password manager item. The item, never a field: the
+//                                         agent asks the manager for the field at use and never
+//                                         writes what comes back
+//   url:<https://...>                     a page
+//   @<atlasId>/<eco>/<kind>/<id>          an entry in another EVDA, the substrate's federated
+//                                         EntityRef (common/src/entity-ref.ts). The eco segment is
+//                                         optional, as it is there; `test/entity-ref-parity.test.mjs`
+//                                         checks this parser against the substrate's
+//
+// A wikilink is a pointer inside this record and is Spec 03's business, not a reference.
+//
+// In an entry, references sit in the frontmatter:
+//
+//   ---
+//   references:
+//     - ref: contacts:2F1A-77
+//       label: Sam Rivera
+//       resolved: 2026-09-10
+//   ---
+//
+// `ref` and `label` are required; `resolved` is a date or absent. Any other key is a copy of
+// something the source holds and is refused. A value shaped like a secret, or a key named like
+// one, is refused with nothing written: Spec 00 #39 puts credentials on the host, substituted at
+// egress, and ekati's own convention is a handle in the record and a value only at the boundary.
+
+import { EvdaError } from "./errors.mjs";
+import { parseYaml } from "./yaml.mjs";
+
+export const SCHEMES = ["contacts", "1password", "url", "evda"];
+export const REFERENCE_KEYS = ["ref", "label", "resolved"];
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+// The substrate's namespace rule (common/src/workflow-ref.ts hasNamespaceSuffix): a DNS-label-safe
+// stem ending in .eco or .kb. Ported, because this package imports nothing from the workspace.
+const NAMESPACE_STEM = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/;
+export function isVaultNamespace(value) {
+  for (const tld of [".eco", ".kb"]) {
+    if (value.endsWith(tld)) {
+      const stem = value.slice(0, -tld.length);
+      return stem.length > 0 && NAMESPACE_STEM.test(stem);
+    }
+  }
+  return false;
+}
+
+// The federated EntityRef, parsed as common/src/entity-ref.ts parses it. Returns
+// { atlasId, eco?, kind, id } or null. Only the federated form is a reference here: a pointer with
+// no atlas names an entry in this record, and that is a wikilink.
+export function parseEvdaAddress(input) {
+  if (typeof input !== "string" || !input.startsWith("@")) return null;
+  const slash = input.indexOf("/");
+  if (slash <= 1) return null;
+  const atlasId = input.slice(1, slash);
+  const rest = input.slice(slash + 1);
+  const s = rest.indexOf("/");
+  if (s <= 0 || s === rest.length - 1) return null;
+  const first = rest.slice(0, s);
+  let eco;
+  let kind;
+  let id;
+  if (isVaultNamespace(first)) {
+    eco = first;
+    const tail = rest.slice(s + 1);
+    const t = tail.indexOf("/");
+    if (t <= 0 || t === tail.length - 1) return null;
+    kind = tail.slice(0, t);
+    id = tail.slice(t + 1);
+  } else {
+    kind = first;
+    id = rest.slice(s + 1);
+  }
+  if (!kind || !id) return null;
+  const out = { atlasId, kind, id };
+  if (eco !== undefined) out.eco = eco;
+  return out;
+}
+
+// One pointer string to { scheme, pointer, ...parts }. Throws an EvdaError naming what is wrong,
+// so a caller that wants a yes or no wraps it; doctor wants the sentence.
+export function parseReference(input) {
+  if (typeof input !== "string" || input.trim() === "") throw bad("reference is empty.");
+  const s = input.trim();
+  if (s !== input) throw bad(`reference has leading or trailing whitespace: ${JSON.stringify(input)}.`);
+  if (s.startsWith("@")) {
+    const a = parseEvdaAddress(s);
+    if (!a) throw bad(`reference ${s} is not an EVDA address. The form is @<atlasId>/<eco>/<kind>/<id>, eco optional.`);
+    return { scheme: "evda", ref: s, pointer: s, ...a };
+  }
+  const colon = s.indexOf(":");
+  if (colon <= 0) throw bad(`reference ${s} has no scheme. Known: ${SCHEMES.join(", ")}, or an @<atlasId>/... address.`);
+  const scheme = s.slice(0, colon);
+  const pointer = s.slice(colon + 1);
+  if (!SCHEMES.includes(scheme)) throw bad(`reference scheme "${scheme}" is not one this tool knows (${SCHEMES.join(", ")}).`);
+  if (pointer === "") throw bad(`reference ${s} has nothing after the scheme.`);
+  switch (scheme) {
+    case "contacts":
+      if (/\s/.test(pointer)) throw bad(`reference contacts identifier ${JSON.stringify(pointer)} contains whitespace.`);
+      return { scheme, ref: s, pointer };
+    case "1password": {
+      const m = /^op:\/\/([^/]+)\/([^/]+)(\/.*)?$/.exec(pointer);
+      if (!m) throw bad(`reference ${s} is not an item address. The form is 1password:op://<vault>/<item>.`);
+      if (m[3]) throw bad(`reference ${s} names a field. A reference is the item, never a field; the agent asks the manager for the field at use and never writes what comes back.`);
+      return { scheme, ref: s, pointer, vault: m[1], item: m[2] };
+    }
+    case "url": {
+      let u;
+      try {
+        u = new URL(pointer);
+      } catch {
+        throw bad(`reference ${s} is not a URL.`);
+      }
+      if (u.protocol !== "http:" && u.protocol !== "https:") throw bad(`reference ${s} is not a page; only http and https are pages.`);
+      return { scheme, ref: s, pointer, url: u };
+    }
+    default:
+      throw bad(`reference ${s} has an unhandled scheme.`);
+  }
+}
+
+function bad(msg) {
+  return new EvdaError(msg, { code: "BAD_REFERENCE", exit: 1 });
+}
+
+// Secret detection. A key named like a secret, or a value shaped like one, refuses the write.
+// The shapes are the obvious ones: a private key block, a JWT, the prefixes the common services
+// stamp on their tokens, a bearer header, a URL carrying a password or a credential in its query,
+// and as a last net a long mixed-case high-entropy token that is not a UUID.
+const SECRET_KEY = /(pass(word|wd|phrase)?|secret|token|api[-_ ]?key|access[-_ ]?key|private[-_ ]?key|credential|bearer|cookie|session[-_ ]?id|otp|pin[-_ ]?code|client[-_ ]?secret)/i;
+const SECRET_PARAM = /^(key|token|access_token|api_key|apikey|auth|password|secret|sig|signature|session|x-amz-signature|x-amz-credential)$/i;
+const SECRET_VALUE = [
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, "a private key block"],
+  [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/, "a JWT"],
+  [/\b(sk|pk|rk)-[A-Za-z0-9_-]{16,}\b/, "an API key (sk-...)"],
+  [/\b(sk|pk|rk)_(live|test)_[A-Za-z0-9]{8,}\b/, "an API key (sk_live_...)"],
+  [/\bgh[pousr]_[A-Za-z0-9]{20,}\b/, "a GitHub token"],
+  [/\bglpat-[A-Za-z0-9_-]{20,}\b/, "a GitLab token"],
+  [/\bxox[abprs]-[A-Za-z0-9-]{10,}\b/, "a Slack token"],
+  [/\bAKIA[0-9A-Z]{16}\b/, "an AWS access key id"],
+  [/\bAIza[0-9A-Za-z_-]{35}\b/, "a Google API key"],
+  [/\bBearer\s+[A-Za-z0-9._~+/-]{16,}=*/i, "a bearer token"],
+];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function entropy(s) {
+  const counts = new Map();
+  for (const c of s) counts.set(c, (counts.get(c) ?? 0) + 1);
+  let h = 0;
+  for (const n of counts.values()) {
+    const p = n / s.length;
+    h -= p * Math.log2(p);
+  }
+  return h;
+}
+
+// Why a string looks like a secret, or null.
+export function secretShape(value) {
+  if (typeof value !== "string") return null;
+  for (const [re, what] of SECRET_VALUE) if (re.test(value)) return what;
+  const m = /^(?:url:)?([a-z][a-z0-9+.-]*:\/\/[^\s]+)$/i.exec(value);
+  if (m) {
+    let u = null;
+    try { u = new URL(m[1]); } catch { u = null; }
+    if (u) {
+      if (u.password !== "") return "a password in the URL";
+      for (const k of u.searchParams.keys()) if (SECRET_PARAM.test(k)) return `a credential in the URL query (${k})`;
+    }
+  }
+  for (const tok of value.split(/[\s"'<>]+/)) {
+    if (tok.length < 40 || UUID.test(tok)) continue;
+    if (!/[A-Z]/.test(tok) || !/[a-z]/.test(tok) || !/\d/.test(tok)) continue;
+    if (!/^[A-Za-z0-9+/=_-]+$/.test(tok)) continue;
+    if (entropy(tok) >= 4.5) return "a long high-entropy token";
+  }
+  return null;
+}
+
+// Why a key name looks like it holds a secret, or null.
+export function secretKey(name) {
+  return SECRET_KEY.test(String(name)) ? `a field named "${name}"` : null;
+}
+
+// Validate one stored reference { ref, label, resolved }. Returns the parsed reference with the
+// scheme and parts, or throws:
+//   SECRET_IN_REFERENCE  exit 2, refused, nothing written
+//   BAD_REFERENCE        exit 1, malformed
+export function validateReference(r, where = "reference") {
+  if (r === null || typeof r !== "object" || Array.isArray(r)) throw bad(`${where} is not a mapping of ref, label, resolved.`);
+  for (const [k, v] of Object.entries(r)) {
+    const byName = secretKey(k);
+    if (byName) throw secret(`${where} carries ${byName}. A reference holds a pointer, a label and a date; a secret is asked of its keeper at use and never written.`);
+    const byValue = secretShape(typeof v === "string" ? v : JSON.stringify(v));
+    if (byValue) throw secret(`${where}.${k} holds ${byValue}. A reference holds a pointer, a label and a date; a secret is asked of its keeper at use and never written.`);
+  }
+  const unknown = Object.keys(r).filter((k) => !REFERENCE_KEYS.includes(k));
+  if (unknown.length) throw bad(`${where} carries ${unknown.map((k) => JSON.stringify(k)).join(", ")}. A reference stores the pointer, a label and the date it last resolved; anything else is a copy of what the source holds.`);
+  if (typeof r.ref !== "string") throw bad(`${where} has no "ref".`);
+  const parsed = parseReference(r.ref);
+  if (typeof r.label !== "string" || r.label.trim() === "") throw bad(`${where} (${r.ref}) has no "label". The label is what renders when the source is unreachable; without one the reference renders as nothing.`);
+  if (r.resolved !== undefined && r.resolved !== null && !DATE.test(String(r.resolved))) throw bad(`${where} (${r.ref}) "resolved" must be a YYYY-MM-DD date, got ${JSON.stringify(r.resolved)}.`);
+  return { ...parsed, label: r.label.trim(), resolved: r.resolved ? String(r.resolved) : null };
+}
+
+function secret(msg) {
+  return new EvdaError(`REFUSED: ${msg}`, { code: "SECRET_IN_REFERENCE", exit: 2 });
+}
+
+// Build a stored reference. Same refusals as validateReference, so nothing that would fail
+// doctor is ever written.
+export function reference({ ref, label, resolved = null }) {
+  const out = { ref, label };
+  if (resolved) out.resolved = resolved;
+  validateReference(out);
+  return out;
+}
+
+// The frontmatter block of an entry, parsed, or null when the entry has none.
+export function frontmatter(text) {
+  if (!text.startsWith("---\n") && !text.startsWith("---\r\n")) return null;
+  const end = text.indexOf("\n---", 3);
+  if (end === -1) return null;
+  const block = text.slice(text.indexOf("\n") + 1, end);
+  const fm = parseYaml(block);
+  return fm !== null && typeof fm === "object" && !Array.isArray(fm) ? fm : null;
+}
+
+// Does the frontmatter block name a `references` key at all? Asked before parsing, so a file whose
+// frontmatter this YAML subset cannot read is left alone unless it is actually declaring references.
+function declaresReferences(text) {
+  if (!text.startsWith("---")) return false;
+  const end = text.indexOf("\n---", 3);
+  const block = end === -1 ? text : text.slice(0, end);
+  return /^references\s*:/m.test(block);
+}
+
+// The references an entry declares. Returns { references: [...], problems: [...] }, one problem
+// per reference that fails, so doctor names every one. `references` holds only the ones that pass.
+// A file with no `references:` in its frontmatter has nothing here, whatever else its frontmatter
+// holds; a record's other keys are not this tool's to validate.
+export function referencesIn(text, where = "entry") {
+  const out = { references: [], problems: [] };
+  if (!declaresReferences(text)) return out;
+  let fm;
+  try {
+    fm = frontmatter(text);
+  } catch (e) {
+    out.problems.push({ level: "fail", code: "BAD_YAML", message: `${where}: declares references but its frontmatter is not readable YAML (${e.message}).` });
+    return out;
+  }
+  if (!fm || fm.references === undefined) return out;
+  if (!Array.isArray(fm.references)) {
+    out.problems.push({ level: "fail", code: "BAD_REFERENCE", message: `${where}: "references" must be a list.` });
+    return out;
+  }
+  fm.references.forEach((r, i) => {
+    try {
+      out.references.push({ ...validateReference(r, `${where}: references[${i}]`), raw: r });
+    } catch (e) {
+      if (!(e instanceof EvdaError)) throw e;
+      out.problems.push({ level: "fail", code: e.code, message: e.message });
+    }
+  });
+  return out;
+}
+
+// What a reference renders as, given the result of resolving it. Never an empty string: the label
+// is always there, and an unresolved reference says so and since when.
+export function renderReference(ref, result = null) {
+  const label = ref.label;
+  if (result && result.status === "resolved") return result.label && result.label !== label ? `${label} (${result.label})` : label;
+  const since = ref.resolved ? `since ${ref.resolved}` : "never resolved";
+  if (result && result.status === "skipped") return `${label} (not resolved: ${result.why}; ${since})`;
+  if (result && result.status === "unreachable") return `${label} (unreachable ${since}: ${result.why})`;
+  return `${label} (unresolved, ${since})`;
+}