create-evda 0.1.0

package/create-evda.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// create-evda: scaffold an EVDA, a directory that knows what it is.
+//
+//   node create-evda.mjs <dir> [--name NAME] [--owner NAME] [--layers record,ledger[,circles]] [--force]
+//
+// Writes the manifest, the operating layer, the corpus, the ledger with its own entry shape at the
+// top, and .evda/. Then runs `evda doctor` on what it wrote and prints the one instruction that
+// matters. It creates no example notes: an empty record that fills with a real life is the
+// product, and one seeded with fake content teaches the owner to ignore it. The one file it writes
+// under record/ is today's daily file holding a true event, the record's own creation, so that the
+// first session has something dated to read and the owner sees where their words go.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isEntry } from "./lib/errors.mjs";
+import { writeVersion, holderProblems, SCHEMA_VERSION, KNOWN_LAYERS, HOLDER_KINDS } from "./lib/manifest.mjs";
+import { rolesForLayer } from "./lib/roles.mjs";
+import { reindex } from "./lib/index.mjs";
+import { doctor } from "./lib/doctor.mjs";
+import { readPointer, setPointer, pointerPath } from "./lib/locate.mjs";
+import { FOLDER_MANIFEST } from "./lib/folders.mjs";
+import { EvdaError } from "./lib/errors.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES = join(HERE, "templates");
+
+// The canonical tree. It is what this scaffolder creates and it is not a requirement: the manifest
+// carries a mapping, and this is simply the identity mapping for the tree below. Nothing else in
+// the package reads these paths.
+const CANONICAL = {
+  agents: "AGENTS.md",
+  "record/daily": "record/daily",
+  "record/captures": "record/captures",
+  "record/people": "record/people",
+  ledger: "ledger",
+  circles: "circles",
+  grants: "grants",
+};
+
+// What each record folder holds (Spec 07, section 2), written as folder.evda.json beside the
+// entries. No connectors on day one: a connector is declared when the owner connects one.
+const FOLDER_TYPES = {
+  "record/daily": "record",
+  "record/captures": "capture",
+  "record/people": "person",
+};
+
+function parseArgs(argv) {
+  const opts = { layers: ["record", "ledger"], force: false, name: null, owner: "", kind: "person", id: null, pointer: true, use: false };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--force") opts.force = true;
+    else if (a === "--no-pointer") opts.pointer = false;
+    else if (a === "--use") opts.use = true;
+    else if (a === "--name") opts.name = argv[++i];
+    else if (a === "--owner") opts.owner = argv[++i] ?? "";
+    else if (a === "--kind") opts.kind = argv[++i];
+    else if (a === "--id") opts.id = argv[++i];
+    else if (a === "--layers") opts.layers = (argv[++i] ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    else if (a === "--quiet") opts.quiet = true;
+    else if (a.startsWith("--")) throw new EvdaError(`unknown option ${a}`, { exit: 2 });
+    else positional.push(a);
+  }
+  if (positional.length !== 1) throw new EvdaError("usage: create-evda <dir> [--name NAME] [--owner NAME] [--kind person|agent|company] [--id ATLAS-ID] [--layers record,ledger] [--use] [--no-pointer]", { exit: 2 });
+  opts.dir = resolve(positional[0]);
+  if (!opts.name) opts.name = opts.dir.split("/").pop();
+  for (const l of opts.layers) if (!KNOWN_LAYERS.includes(l)) throw new EvdaError(`unknown layer "${l}". Known: ${KNOWN_LAYERS.join(", ")}`, { exit: 2 });
+  if (!HOLDER_KINDS.includes(opts.kind)) throw new EvdaError(`unknown holder kind "${opts.kind}". A record is held by a ${HOLDER_KINDS.join(", a ")}.`, { exit: 2 });
+  return opts;
+}
+
+function render(name, vars) {
+  let text = readFileSync(join(TEMPLATES, name), "utf8");
+  for (const [k, v] of Object.entries(vars)) text = text.replaceAll(`{{${k}}}`, v);
+  return text;
+}
+
+export function scaffold(opts) {
+  const { dir } = opts;
+  if (existsSync(dir) && readdirSync(dir).length > 0 && !opts.force) {
+    throw new EvdaError(`REFUSED: ${dir} exists and is not empty. Nothing was written. Pass --force to scaffold into it anyway (existing files are never overwritten).`, { exit: 2 });
+  }
+  const today = localDate();
+  const mapping = { agents: CANONICAL.agents };
+  for (const layer of opts.layers) for (const role of rolesForLayer(layer)) mapping[role] = CANONICAL[role];
+
+  mkdirSync(dir, { recursive: true });
+  for (const [role, rel] of Object.entries(mapping)) if (role !== "agents") mkdirSync(join(dir, rel), { recursive: true });
+
+  // The holder: a person unless said otherwise. The id is the record's atlas id, `<name>.atlas`
+  // unless given, which is how another record names this one in a grant or a reference.
+  const kind = opts.kind ?? "person";
+  const id = opts.id ?? `${slug(opts.name)}.atlas`;
+  const problems = holderProblems({ owner: { kind }, id });
+  if (problems.length) throw new EvdaError(`REFUSED: ${problems.join(" ")}`, { exit: 2 });
+  const manifest = { evda: SCHEMA_VERSION, id, name: opts.name, owner: { name: opts.owner, kind }, created: today, layers: opts.layers, mapping };
+  writeIfAbsent(join(dir, "evda.json"), JSON.stringify(manifest, null, 2) + "\n");
+  writeIfAbsent(join(dir, mapping.agents), render("AGENTS.md", {}));
+  writeIfAbsent(join(dir, "CLAUDE.md"), render("CLAUDE.md", { agents: mapping.agents }));
+  if (mapping.ledger) writeIfAbsent(join(dir, mapping.ledger, "hypotheses.md"), render("hypotheses.md", { date: today, name: opts.name }));
+  if (mapping["record/daily"]) writeIfAbsent(join(dir, mapping["record/daily"], `${today}.md`), firstDay(today));
+  if (mapping.circles) writeIfAbsent(join(dir, mapping.circles, "README.md"), render("circles-README.md", {}));
+  for (const [role, type] of Object.entries(FOLDER_TYPES)) {
+    if (mapping[role]) writeIfAbsent(join(dir, mapping[role], FOLDER_MANIFEST), JSON.stringify({ type, connectors: [], views: [] }, null, 2) + "\n");
+  }
+  writeVersion(dir, SCHEMA_VERSION);
+  reindex({ dir, manifest, version: { declared: SCHEMA_VERSION, onDisk: SCHEMA_VERSION } });
+
+  // The locator pointer. Written when nothing points anywhere yet, or on --use; never silently
+  // repointed away from a record the owner already chose.
+  let pointer = { path: pointerPath(), action: "left alone" };
+  if (opts.pointer) {
+    const existing = readPointer();
+    if (existing === null || opts.use) { setPointer(dir); pointer.action = existing === null ? "written" : `repointed from ${existing}`; }
+    else pointer.action = `already points at ${existing}; pass --use or run \`evda use ${dir}\` to switch`;
+  } else {
+    pointer.action = "skipped (--no-pointer)";
+  }
+  return { dir, manifest, pointer };
+}
+
+// Day one. The record's first daily file records the one true thing that has happened to it: it
+// was created. It says so in three lines and says where the owner's words go, then gets out of the
+// way. It is not an example note, it asks nothing, and it schedules nothing; every later file
+// under record/ is the owner's, verbatim.
+export function firstDay(date) {
+  return [
+    `# ${date}`,
+    "",
+    "Created today with create-evda. This is the one file here not in the owner's words.",
+    "",
+    "Every later file under record/ is theirs, verbatim: one day per file in record/daily/, named by date; a thought as it arrived in record/captures/; one file per person in record/people/. The ledger stays empty until the record holds something to be wrong about.",
+    "",
+  ].join("\n");
+}
+
+// A name as a DNS-shaped label for the default atlas id: lowercase, letters digits and hyphens.
+export function slug(name) {
+  const s = String(name).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return s || "record";
+}
+
+// The owner's local date, not UTC. A record created at 10pm local time is created on that day.
+export function localDate(d = new Date()) {
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+function writeIfAbsent(path, text) {
+  if (existsSync(path)) return;
+  writeFileSync(path, text);
+}
+
+export async function main(argv) {
+  const opts = parseArgs(argv);
+  const { dir, pointer } = scaffold(opts);
+  const log = opts.quiet ? () => {} : console.log;
+  log(`created an EVDA at ${dir}`);
+  log(`locator ${pointer.path}: ${pointer.action}\n`);
+  const report = doctor(dir, { out: log, via: "create-evda" });
+  if (report.exit !== 0) {
+    console.error("\ncreate-evda wrote the layout but doctor does not pass on it. That is a bug in create-evda; the output above says where.");
+    return report.exit;
+  }
+  log(`\nOpen this directory in Claude Code, or any agent that reads AGENTS.md, and it will know what to do.`);
+  log(`First move: say something true about today. It goes into record/daily/${localDate()}.md in your words, and nothing is proposed about you until there is something there to be wrong about.`);
+  log(`The files are the record. \`evda doctor\` checks them and \`evda reindex\` rebuilds .evda/; neither is required.`);
+  return 0;
+}
+
+// Run main only when this file is the entry point. Through realpath, because an installed bin is
+// a SYMLINK (node_modules/.bin/create-evda -> ../create-evda/create-evda.mjs) and resolve() does
+// not follow it: the first clean-machine `npx create-evda` exited 0 having written nothing.
+if (process.argv[1] && isEntry(process.argv[1], import.meta.url)) {
+  main(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (e) => {
+      console.error(e instanceof EvdaError ? e.message : e.stack ?? String(e));
+      process.exit(e instanceof EvdaError ? e.exit : 1);
+    }
+  );
+}

package/lib/agents.mjs

@@ -0,0 +1,90 @@
+// AGENTS.md survives upgrades by separation, not merge (Spec 05, ruling 2 from gstack).
+//
+// One fence the installer owns:
+//     <!-- evda:generated -->  ...  <!-- /evda:generated -->
+// `evda upgrade` byte-checks the block and replaces it wholesale. Everything outside the fence is
+// the owner's, including "What I have been taught"; the upgrade never reads it, never merges it,
+// never warns about it.
+//
+// The digest is an instruction-only compression of the fenced block, generated from the same
+// text so it cannot drift, with a byte budget enforced by a test (ruling 3).
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { EvdaError } from "./errors.mjs";
+
+export const FENCE_OPEN = "<!-- evda:generated -->";
+export const FENCE_CLOSE = "<!-- /evda:generated -->";
+export const DIGEST_BUDGET = 2048;
+export const TEMPLATE_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "templates", "AGENTS.md");
+
+// {before, generated, after} where generated INCLUDES both fence lines, or null if no fence.
+export function splitFence(text) {
+  const open = text.indexOf(FENCE_OPEN);
+  const close = text.indexOf(FENCE_CLOSE);
+  if (open === -1 || close === -1 || close < open) return null;
+  if (text.indexOf(FENCE_OPEN, open + 1) !== -1 || text.indexOf(FENCE_CLOSE, close + 1) !== -1) {
+    throw new EvdaError("AGENTS.md has more than one evda:generated fence. There is exactly one, and it is the installer's.");
+  }
+  const end = close + FENCE_CLOSE.length;
+  return { before: text.slice(0, open), generated: text.slice(open, end), after: text.slice(end) };
+}
+
+export function replaceFence(text, generated) {
+  const parts = splitFence(text);
+  if (!parts) throw new EvdaError("AGENTS.md has no evda:generated fence, so there is no installer-owned block to replace. The owner has taken the whole file; nothing was changed.");
+  return parts.before + generated + parts.after;
+}
+
+export function shippedGenerated() {
+  if (!existsSync(TEMPLATE_PATH)) throw new EvdaError(`template missing at ${TEMPLATE_PATH}`, { exit: 2 });
+  const parts = splitFence(readFileSync(TEMPLATE_PATH, "utf8"));
+  if (!parts) throw new EvdaError("the shipped templates/AGENTS.md has no fence; rebuild it with scripts/build-templates.mjs", { exit: 2 });
+  return parts.generated;
+}
+
+// Instruction-only digest of a generated block. Deterministic: same input, same bytes.
+// Keeps: every `## ` heading, the indented layout lines, and for every list item the bold lead if
+// it has one, else its first sentence. Drops all explanatory prose.
+export function digestFrom(generated) {
+  const lines = generated.split("\n");
+  const out = ["# EVDA digest", "Instruction-only digest of the generated block of AGENTS.md. Read AGENTS.md in full when the host allows it."];
+  let section = null;
+  let item = null;
+  const flush = () => {
+    if (item === null) return;
+    const bold = /\*\*(.+?)\*\*/.exec(item);
+    let lead = bold ? bold[1] : item;
+    lead = lead.replace(/\s+/g, " ").trim();
+    if (!bold) {
+      const stop = lead.search(/[.:]\s|[.:]$/);
+      if (stop !== -1) lead = lead.slice(0, stop + 1);
+    }
+    lead = lead.replace(/[.:]$/, "");
+    out.push(`- ${lead}`);
+    item = null;
+  };
+  for (const raw of lines) {
+    if (raw.startsWith("<!--")) continue;
+    const h = /^## (.+)$/.exec(raw);
+    if (h) { flush(); section = h[1].trim(); out.push(`## ${section}`); continue; }
+    if (section === "Layout" && /^ {4}\S/.test(raw)) { flush(); out.push(raw.trim().replace(/\s{2,}/g, "  ")); continue; }
+    const li = /^(?:- |\d+\. )(.*)$/.exec(raw);
+    if (li) { flush(); item = li[1]; continue; }
+    if (item !== null && /^\s+\S/.test(raw)) { item += " " + raw.trim(); continue; }
+    flush();
+  }
+  flush();
+  return out.join("\n") + "\n";
+}
+
+export function digestBytes(text) {
+  return Buffer.byteLength(text, "utf8");
+}
+
+export function checkDigestBudget(text) {
+  const n = digestBytes(text);
+  if (n > DIGEST_BUDGET) throw new EvdaError(`digest is ${n} bytes, over the ${DIGEST_BUDGET} byte budget.`);
+  return n;
+}

package/lib/circles.mjs

@@ -0,0 +1,317 @@
+// Circles, read through the `circles` role. A circle is an eco.
+//
+// The substrate declares an eco with one manifest, `eco.yaml`, in the eco's own directory
+// (`ecos/<name>/eco.yaml`), carrying `id`, `kind: eco`, `schemaVersion`, `namespace`, `title`,
+// `public` and `maintainers`. A person's circle is the same manifest in a directory under the
+// circles role, so the substrate's own reader (`@evda/common` parseEco, `@evda/vault-core` EcoStore)
+// opens it unchanged; `test/eco-parity.test.mjs` proves that against the real parser. The person
+// layer adds two keys the substrate preserves and does not read:
+//
+//   members   where the circle's bytes live, relative to the record root. The mapping principle
+//             one level down: a record adopts a circle by declaring where its members already are,
+//             and nothing moves. A member is { path } (bytes in this record) or { table, where }
+//             (rows on a host, selected by equality; allowed only in a public circle, because a
+//             private circle's host may not read it).
+//   policy    a list of rules (Spec 07, section 6), each one a test: what the rule is in the owner's
+//             words, the correction that made it (verbatim), an example that passes, one that fails,
+//             a check written so it could come back false, and a status. A rule is never edited in
+//             place; a revision is a new rule with `revisedBy` written on the old one. The plain
+//             sentence saying who may read the circle and why goes in the substrate's `description`.
+//
+// `public: true` is the whole of what makes a circle public: the reader takes the same path it
+// would for any circle and needs no key. Reading an ENCRYPTED circle is not built; a private circle
+// is declared, validated for shape, and never read.
+//
+// `circle.json` is the manifest this package wrote before circles converged on ecos (2026-09-16).
+// It is still read, with a warning, so a record written against it keeps working until it is
+// rewritten as `eco.yaml`. Nothing writes it any more.
+
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve, sep, isAbsolute } from "node:path";
+import { resolveRole } from "./roles.mjs";
+import { parseYaml, toYaml } from "./yaml.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const ECO_SCHEMA_VERSION = "0.1";
+// atlas-arch:yaml-encoding: the eco manifest is a config file the substrate names by its suffix, not an entity key
+export const ECO_MANIFEST = "eco.yaml";
+export const LEGACY_MANIFEST = "circle.json";
+export const KNOWN_ECO_KEYS = [
+  "id", "kind", "schemaVersion", "sourceLayer", "namespace", "title", "type", "description",
+  "ecoVersion", "layer", "public", "maintainers", "metadata", "members", "policy",
+];
+
+export const circlesDir = (evda) => resolveRole(evda, "circles");
+export const ecoManifestPath = (dir) => join(dir, ECO_MANIFEST);
+export const ecoId = (name) => `ecos/${name}`;
+export const ecoNamespace = (name) => `${name}.eco`;
+
+// Every subdirectory of the circles role, whether or not it carries a manifest. Dotfiles are not
+// circles. A file at the top level of the role is ignored (the scaffold's README lives there).
+export function circleDirs(evda) {
+  const role = circlesDir(evda);
+  if (!role.mapped) return null;
+  if (!role.exists || !role.isDir) {
+    throw new EvdaError(`circles role is mapped to "${role.rel}" but that directory does not exist.`, { code: "MISSING_ROLE" });
+  }
+  return readdirSync(role.abs)
+    .filter((n) => !n.startsWith("."))
+    .map((n) => ({ name: n, abs: join(role.abs, n), rel: join(role.rel, n) }))
+    .filter((d) => statSync(d.abs).isDirectory())
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+const isScalar = (v) => v === null || ["string", "number", "boolean"].includes(typeof v);
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
+
+// Read the manifest of one circle directory: eco.yaml first, circle.json as the legacy form.
+// Returns { manifest, source } or { manifest: null }. Throws on a file that cannot be parsed.
+function readCircleManifest(dir) {
+  const eco = ecoManifestPath(dir.abs);
+  if (existsSync(eco)) {
+    let m;
+    try {
+      m = parseYaml(readFileSync(eco, "utf8"));
+    } catch (e) {
+      throw new EvdaError(`REFUSED: ${join(dir.rel, ECO_MANIFEST)} is not readable YAML (${e.message}).`, { code: "BAD_CIRCLE", exit: 2 });
+    }
+    return { manifest: m, source: ECO_MANIFEST };
+  }
+  const legacy = join(dir.abs, LEGACY_MANIFEST);
+  if (existsSync(legacy)) {
+    let m;
+    try {
+      m = JSON.parse(readFileSync(legacy, "utf8"));
+    } catch (e) {
+      throw new EvdaError(`REFUSED: ${join(dir.rel, LEGACY_MANIFEST)} is not valid JSON (${e.message}).`, { code: "BAD_CIRCLE", exit: 2 });
+    }
+    return { manifest: isObject(m) ? fromLegacy(m) : m, source: LEGACY_MANIFEST };
+  }
+  return { manifest: null, source: null };
+}
+
+// The circle.json shape, lifted onto the eco shape. `holders` become `maintainers`; everything
+// else is carried across by name. Unknown keys survive.
+export function fromLegacy(m) {
+  const { circle, name, holders, ...rest } = m;
+  const out = {
+    id: typeof name === "string" ? ecoId(name) : undefined,
+    kind: "eco",
+    schemaVersion: ECO_SCHEMA_VERSION,
+    namespace: typeof name === "string" ? ecoNamespace(name) : undefined,
+    title: name,
+  };
+  if (Array.isArray(holders)) out.maintainers = holders.map((h) => (isObject(h) ? { name: h.name, role: h.grant ?? "holder" } : h));
+  return { ...out, ...rest };
+}
+
+export const RULE_STATUS = ["live", "revised", "retired"];
+export const RULE_FIELDS = ["rule", "since", "from", "passes", "fails", "check", "status", "revisedBy", "retired"];
+
+// A policy is a list of rules, and a rule behaves like a test (Spec 07, section 6).
+function validatePolicy(policy, rel, fail, warn) {
+  if (!Array.isArray(policy)) { fail(`${rel}: "policy" must be a list of rules.`); return null; }
+  const rules = [];
+  policy.forEach((r, i) => {
+    const where = `${rel}: policy rule ${i + 1}`;
+    if (!isObject(r)) { fail(`${where} is not a mapping.`); return; }
+    if (!nonEmpty(r.rule)) fail(`${where} has no "rule". One line, in the owner's words where possible.`);
+    else if (/\d/.test(r.rule)) warn(`${where} has a number in its rule line. A threshold, a count or a streak about a person's life is not a rule; the check may count, the rule may not.`);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(String(r.since ?? ""))) fail(`${where} has no "since" date (YYYY-MM-DD).`);
+    if (!nonEmpty(r.from)) fail(`${where} has no "from". Every rule carries the correction that made it; a rule with nothing behind it is one nobody asked for.`);
+    else if (!/["“”]/.test(r.from)) warn(`${where} "from" has no quotation marks. A correction is quoted verbatim, not summarised.`);
+    if (!nonEmpty(r.passes)) fail(`${where} has no "passes" example.`);
+    if (!nonEmpty(r.fails)) fail(`${where} has no "fails" example.`);
+    if (!nonEmpty(r.check)) fail(`${where} has no "check". Write how to tell it was broken, so it could come back false.`);
+    if (!RULE_STATUS.includes(r.status)) fail(`${where} "status" must be one of ${RULE_STATUS.join(" | ")}, got ${JSON.stringify(r.status)}.`);
+    if (r.status === "revised" && !nonEmpty(r.revisedBy)) fail(`${where} is revised but names no "revisedBy". A revision is a new rule, and the old one says which.`);
+    if (r.status !== "revised" && r.revisedBy !== undefined) fail(`${where} names "revisedBy" but its status is ${JSON.stringify(r.status)}. Revised by is written when the revision happens, never in advance.`);
+    if (r.status === "retired" && !nonEmpty(r.retired)) warn(`${where} is retired with no reason. A retired rule is the map of where the fit ended; say why.`);
+    const unknown = Object.keys(r).filter((k) => !RULE_FIELDS.includes(k));
+    if (unknown.length) warn(`${where} has ${unknown.length} unknown field(s), preserved: ${unknown.join(", ")}.`);
+    rules.push({
+      rule: nonEmpty(r.rule) ? r.rule.trim() : "",
+      since: String(r.since ?? ""),
+      from: nonEmpty(r.from) ? r.from.trim() : "",
+      passes: nonEmpty(r.passes) ? r.passes.trim() : "",
+      fails: nonEmpty(r.fails) ? r.fails.trim() : "",
+      check: nonEmpty(r.check) ? r.check.trim() : "",
+      status: RULE_STATUS.includes(r.status) ? r.status : null,
+      revisedBy: nonEmpty(r.revisedBy) ? r.revisedBy.trim() : null,
+    });
+  });
+  return { rules, live: rules.filter((r) => r.status === "live").length };
+}
+
+// Validate one circle directory. Returns { name, rel, abs, manifest, source, problems, readable,
+// members, policy } and never throws for a problem in the manifest; every problem is listed so
+// doctor can print them all. Throws only when the manifest file itself cannot be parsed.
+export function validateCircle(evda, dir) {
+  const problems = [];
+  const fail = (m) => problems.push({ level: "fail", message: m });
+  const warn = (m) => problems.push({ level: "warn", message: m });
+  const out = { name: dir.name, rel: dir.rel, abs: dir.abs, manifest: null, source: null, problems, readable: false, members: {}, policy: null };
+
+  const { manifest: m, source } = readCircleManifest(dir);
+  out.source = source;
+  if (m === null && source === null) {
+    fail(`${dir.rel} has no ${ECO_MANIFEST}. A directory under the circles role without a manifest is not a circle; presence alone cannot say who may read it.`);
+    return out;
+  }
+  const rel = join(dir.rel, source);
+  if (!isObject(m)) {
+    fail(`${rel} must hold a mapping.`);
+    return out;
+  }
+  out.manifest = m;
+  if (source === LEGACY_MANIFEST) warn(`${dir.rel}: read from ${LEGACY_MANIFEST}, the shape before circles became ecos. Write it as ${ECO_MANIFEST}; nothing writes ${LEGACY_MANIFEST} any more.`);
+
+  // The substrate's required fields, so the substrate's own reader can open this manifest.
+  if (m.kind !== "eco") fail(`${rel}: "kind" must be "eco", got ${JSON.stringify(m.kind)}. A circle is an eco.`);
+  if (m.id !== ecoId(dir.name)) fail(`${rel}: "id" must be "${ecoId(dir.name)}" (the directory names the eco), got ${JSON.stringify(m.id)}.`);
+  if (m.namespace !== ecoNamespace(dir.name)) fail(`${rel}: "namespace" must be "${ecoNamespace(dir.name)}", got ${JSON.stringify(m.namespace)}.`);
+  if (!nonEmpty(m.schemaVersion) && typeof m.schemaVersion !== "number") fail(`${rel}: "schemaVersion" is missing.`);
+  if (!nonEmpty(m.title)) fail(`${rel}: "title" is missing.`);
+
+  if (typeof m.public !== "boolean") fail(`${rel}: "public" must be true or false. A circle that does not say who may read it cannot be read.`);
+  if (!Array.isArray(m.maintainers) || m.maintainers.length === 0) {
+    fail(`${rel}: "maintainers" must be a non-empty list. A circle nobody holds has no one who may grant it.`);
+  } else {
+    m.maintainers.forEach((h, i) => {
+      if (!isObject(h) || !nonEmpty(h.name)) fail(`${rel}: maintainers[${i}] has no "name".`);
+    });
+  }
+
+  if (!isObject(m.members)) {
+    fail(`${rel}: "members" must be a mapping naming where the circle's bytes live.`);
+  } else if (Object.keys(m.members).length === 0) {
+    fail(`${rel}: "members" is empty. A circle with nothing in it is a directory with a manifest in it.`);
+  } else {
+    for (const [name, member] of Object.entries(m.members)) {
+      if (!isObject(member)) { fail(`${rel}: member "${name}" is not a mapping.`); continue; }
+      const hasPath = typeof member.path === "string";
+      const hasTable = typeof member.table === "string";
+      if (hasPath === hasTable) { fail(`${rel}: member "${name}" must have exactly one of "path" or "table".`); continue; }
+      if (hasPath) {
+        if (member.path === "" || isAbsolute(member.path)) { fail(`${rel}: member "${name}" path must be relative to the record root, got ${JSON.stringify(member.path)}.`); continue; }
+        const abs = resolve(evda.dir, member.path);
+        if (abs !== evda.dir && !abs.startsWith(evda.dir + sep)) { fail(`${rel}: member "${name}" path (${member.path}) resolves outside the record.`); continue; }
+        if (!existsSync(abs)) { fail(`${rel}: member "${name}" is declared at ${member.path} but nothing is there. A missing member and an empty one are different facts.`); continue; }
+        out.members[name] = { kind: "path", rel: member.path, abs, isDir: statSync(abs).isDirectory() };
+      } else {
+        if (member.table.trim() === "") { fail(`${rel}: member "${name}" has an empty table name.`); continue; }
+        if (m.public !== true) fail(`${rel}: member "${name}" is a table, and this circle is not public. A table is readable by its host; a private circle's host may not read it (the person's threat model).`);
+        const where = member.where ?? {};
+        if (!isObject(where)) { fail(`${rel}: member "${name}" where must be a mapping of column -> scalar.`); continue; }
+        const bad = Object.entries(where).filter(([, v]) => !isScalar(v));
+        if (bad.length) { fail(`${rel}: member "${name}" where has non-scalar value(s): ${bad.map(([k]) => k).join(", ")}.`); continue; }
+        out.members[name] = { kind: "table", table: member.table, where };
+      }
+    }
+  }
+
+  if (!nonEmpty(m.description)) warn(`${rel}: has no "description". Say in plain language who may read this circle and why.`);
+  if (m.policy !== undefined) out.policy = validatePolicy(m.policy, rel, fail, warn);
+  else warn(`${rel}: has no "policy". The rules under it are where the owner's corrections about this circle land.`);
+
+  const unknown = Object.keys(m).filter((k) => !KNOWN_ECO_KEYS.includes(k));
+  if (unknown.length) warn(`${rel}: ${unknown.length} unknown key(s) preserved, not validated: ${unknown.join(", ")}.`);
+
+  if (m.public === false) warn(`${dir.rel}: is not public. This tool has no way to read an encrypted circle; it is declared and nothing in it is read.`);
+  out.readable = m.public === true && !problems.some((p) => p.level === "fail");
+  return out;
+}
+
+// Every circle in the record, validated. null when the record has no circles role.
+export function readCircles(evda) {
+  const dirs = circleDirs(evda);
+  if (dirs === null) return null;
+  return dirs.map((d) => validateCircle(evda, d));
+}
+
+// The circles this tool may read: public, and with no failing problem. Throws when the record
+// has a circles role and a circle in it is malformed, because serving a record with a broken
+// boundary declaration is worse than serving nothing.
+export function publicCircles(evda) {
+  const all = readCircles(evda);
+  if (all === null) return [];
+  const broken = all.filter((c) => c.problems.some((p) => p.level === "fail"));
+  if (broken.length) {
+    const first = broken[0].problems.find((p) => p.level === "fail");
+    throw new EvdaError(`circle "${broken[0].name}" is malformed: ${first.message}`, { code: "BAD_CIRCLE" });
+  }
+  return all.filter((c) => c.readable);
+}
+
+// Exactly one public circle, by name when given. Throws when there is none or more than one.
+export function publicCircle(evda, name = null) {
+  const pub = publicCircles(evda).filter((c) => name === null || c.name === name);
+  if (pub.length === 0) throw new EvdaError(name ? `no public circle named "${name}" in this record.` : "this record has no public circle.", { code: "NO_PUBLIC_CIRCLE" });
+  if (pub.length > 1) throw new EvdaError(`this record has ${pub.length} public circles (${pub.map((c) => c.name).join(", ")}); name one.`, { code: "AMBIGUOUS_CIRCLE" });
+  return pub[0];
+}
+
+// One member of a circle, by name. Throws when the circle does not declare it.
+export function member(circle, name) {
+  const m = circle.members[name];
+  if (!m) throw new EvdaError(`circle "${circle.name}" declares no member "${name}" (it has: ${Object.keys(circle.members).join(", ") || "none"}).`, { code: "NO_MEMBER" });
+  return m;
+}
+
+// The holders of a circle: its maintainers, in the substrate's word.
+export function holders(circle) {
+  return Array.isArray(circle.manifest?.maintainers) ? circle.manifest.maintainers : [];
+}
+
+// Every entry resolves to exactly one circle (Spec 07, section 3). An entry is a file in a record
+// role, or the ledger file. A path member covers the file it names, or every file under the
+// directory it names; a table member covers no file. Returns each entry with the circles that
+// cover it, so doctor can fail on zero and on two.
+export function coverage(evda, circles, entries) {
+  const covers = (m, abs) => m.kind === "path" && (m.isDir ? abs.startsWith(m.abs + sep) : abs === m.abs);
+  return entries.map((abs) => ({
+    abs,
+    circles: circles.filter((c) => Object.values(c.members).some((m) => covers(m, abs))).map((c) => c.name),
+  }));
+}
+
+// Build an eco manifest for a circle. `name` is the directory name; the id and namespace follow
+// from it, so the three cannot disagree.
+export function circleManifest({ name, title = name, isPublic = false, holders: hs = [], members = {}, policy = null, description = null }) {
+  const m = {
+    id: ecoId(name),
+    kind: "eco",
+    schemaVersion: ECO_SCHEMA_VERSION,
+    namespace: ecoNamespace(name),
+    title,
+  };
+  if (description) m.description = description;
+  m.public = isPublic;
+  m.maintainers = hs.map((h) => (typeof h === "string" ? { name: h, role: "holder" } : { name: h.name, role: h.role ?? "holder" }));
+  m.members = members;
+  if (Array.isArray(policy)) m.policy = policy;
+  return m;
+}
+
+// One rule in the shape Spec 07 gives it. Fills nothing in: a rule with a field missing is a rule
+// doctor will name, which is better than one invented to fill the field.
+export function rule({ rule: line, since, from, passes, fails, check, status = "live", revisedBy, retired }) {
+  const r = { rule: line, since, from, passes, fails, check, status };
+  if (revisedBy !== undefined) r.revisedBy = revisedBy;
+  if (retired !== undefined) r.retired = retired;
+  return r;
+}
+
+// Write a circle as eco.yaml under the circles role. Refuses to overwrite unless told to.
+export function writeCircle(evda, name, manifest, { overwrite = false } = {}) {
+  const role = circlesDir(evda);
+  if (!role.mapped) throw new EvdaError('no "circles" role in the mapping, so there is nowhere to write a circle.', { exit: 2 });
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(name)) throw new EvdaError(`"${name}" is not a circle name (letters, digits, - and _).`, { exit: 2 });
+  const dir = join(role.abs, name);
+  const p = ecoManifestPath(dir);
+  if (existsSync(p) && !overwrite) throw new EvdaError(`${join(role.rel, name, ECO_MANIFEST)} exists; pass overwrite to replace it.`, { exit: 2 });
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(p, toYaml(manifest));
+  return p;
+}