create-evda 0.1.5 → 0.1.7

package/lib/connect.mjs

@@ -33,6 +33,52 @@ export function serverCommand(recordDir, { execPath = process.execPath, bin = jo
   return { command: stableNode(execPath, env), args: [real, "mcp", dir] };
 }
 
+// The command Claude Code runs for the read guard (lib/guard.mjs), by the same rule as the server:
+// absolute paths when the package is installed somewhere stable, the npx form from an npx cache.
+export function guardCommand({ execPath = process.execPath, hook = join(PACKAGE_ROOT, "hooks", "evda-read-guard.mjs"), env = process.env } = {}) {
+  let real = hook;
+  try { real = realpathSync(hook); } catch { /* not on disk yet, as in a test */ }
+  const q = (s) => (/^[A-Za-z0-9_./:@=+-]+$/.test(s) ? s : `'${String(s).replace(/'/g, "'\\''")}'`);
+  if (/[\\/]_npx[\\/]/.test(real)) return "npx -y -p create-evda@latest evda guard";
+  return `${q(stableNode(execPath, env))} ${q(real)}`;
+}
+
+// Install the read guard into one record's .claude/settings.json, for Claude Code sessions opened
+// in that folder. Merges into a settings file that is already there: an existing PreToolUse entry
+// with the same command is left alone, and nothing else in the file is touched.
+export function installGuard(recordDir, { command = guardCommand() } = {}) {
+  const path = join(resolve(recordDir), ".claude", "settings.json");
+  let settings = {};
+  if (existsSync(path)) {
+    try { settings = JSON.parse(readFileSync(path, "utf8")); } catch { return { path, action: "left alone (not valid JSON):" }; }
+  }
+  const pre = (settings.hooks ??= {}).PreToolUse ??= [];
+  if (pre.some((m) => (m.hooks ?? []).some((h) => h.command === command))) return { path, action: "already installed:" };
+  pre.push({ matcher: "Read|Grep|Bash|NotebookRead", hooks: [{ type: "command", command }] });
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(settings, null, 2) + "\n");
+  return { path, action: "installed" };
+}
+
+// Whether one record's .claude/settings.json runs the read guard, for doctor (HQ-1377):
+// { registered, target, file, problem }. `target` is the hook file the command names, `file` whether
+// it is on disk; the npx form names no file and is present whenever it is registered. Never throws.
+export const GUARD_MARK = /evda-read-guard\.mjs|\bevda guard\b/;
+// EVDA_HOOKS_FALSIFY=blind reports no guard at all, for the test that shows doctor's line is read
+// from the settings file.
+export function guardStatus(recordDir) {
+  if ((process.env.EVDA_HOOKS_FALSIFY ?? "").split(",").map((x) => x.trim()).includes("blind")) return { registered: false, target: null, file: false, problem: null };
+  const path = join(resolve(recordDir), ".claude", "settings.json");
+  if (!existsSync(path)) return { registered: false, target: null, file: false, problem: null };
+  let settings;
+  try { settings = JSON.parse(readFileSync(path, "utf8")); } catch (e) { return { registered: false, target: null, file: false, problem: `.claude/settings.json is not valid JSON (${e.message}), so no hook in it runs.` }; }
+  const commands = (settings?.hooks?.PreToolUse ?? []).flatMap((m) => (m?.hooks ?? []).map((h) => h?.command)).filter((c) => typeof c === "string" && GUARD_MARK.test(c));
+  if (!commands.length) return { registered: false, target: null, file: false, problem: null };
+  const m = /'([^']*evda-read-guard\.mjs)'|(\S*evda-read-guard\.mjs)/.exec(commands[0]);
+  const target = m ? (m[1] ?? m[2]) : null;
+  return { registered: true, target, file: target === null || existsSync(target), problem: null };
+}
+
 // A `node` on PATH that is this same binary, when there is one: Homebrew's /opt/homebrew/bin/node
 // survives an upgrade, and the versioned Cellar path process.execPath reports does not.
 function stableNode(execPath, env) {

package/lib/day-file.mjs

@@ -0,0 +1,93 @@
+// The day's file, and the one way words are appended to it (HQ-1385): evda_write over stdio and
+// over HTTP, the Claude Code prompt hook, and the chat-export backstop in `evda gather` all build
+// their bytes here, so a section looks the same whoever wrote it.
+//
+// ONE SECTION PER CONVERSATION. The first write in a conversation opens `## HH:MM` (the owner's
+// local time) with its one line of context; every later write in the same conversation appends
+// under it, as a new paragraph, with no heading. A conversation is whatever the caller passes as
+// `session`: one MCP session (a stdio process, or one Mcp-Session-Id over HTTP), or one Claude Code
+// session id in the prompt hook. When the file changed since this conversation last wrote to it
+// (another conversation wrote a section, or someone edited it by hand), the next write opens a new
+// heading, so words never land under a heading that is not theirs.
+//
+// FILING. evda.json `filing` is the owner's answer to the one setup question: "everything" (file
+// every message they send, without being asked) or "asked" (only when they ask). Absent means they
+// have not been asked yet; the MCP server asks at first connect. The tool descriptions, the server's
+// instructions, the nudge, the Stop hook and the prompt hook all read it through filingOf.
+//
+// node: built-ins only and no imports of the package's own: `evda hook install` copies this file
+// byte for byte beside the Claude Code hooks, which import it. `evda doctor` says when a copy is
+// older than this file.
+//
+// EVDA_CHAT_FALSIFY=heading-per-write opens a new heading on every write, for the test that shows
+// one conversation is one section.
+
+import { appendFileSync, existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+export const FILING_MODES = ["everything", "asked"];
+export const CONTEXT_LABEL = "Context, not their words:";
+
+const falsified = (mode) => (process.env.EVDA_CHAT_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+
+// The owner's filing answer: "everything", "asked", or null when they have not been asked (or the
+// value is not one of the two, which doctor fails).
+export function filingOf(manifest) {
+  const v = (manifest?.manifest ?? manifest)?.filing;
+  return FILING_MODES.includes(v) ? v : null;
+}
+
+// The role the day's record lives under: `record/daily` where a record maps it (every scaffold
+// does), else the `journal` role (HQ-1371). One rule, read by evda_write and by every hook.
+export function dayRole(mapping) {
+  if (typeof mapping?.["record/daily"] === "string") return "record/daily";
+  if (typeof mapping?.journal === "string") return "journal";
+  return null;
+}
+
+// The record root at or above `from`, or null.
+export function findRecord(from) {
+  let d = resolve(from);
+  for (;;) {
+    if (existsSync(join(d, "evda.json"))) return d;
+    const up = dirname(d);
+    if (up === d) return null;
+    d = up;
+  }
+}
+
+const pad = (n) => String(n).padStart(2, "0");
+export const localDate = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+export const localTime = (d) => `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+
+export const contextLine = (context) => `*${CONTEXT_LABEL} ${String(context).trim().replace(/\*/g, "")}*`;
+
+// The bytes one write appends to a day file whose current text is `current` (null when it does not
+// exist yet). `continuing` is true when this conversation's section is the last thing in the file.
+// Returns { text, opened }.
+export function sectionBytes({ current, date, time, words, context = null, continuing = false, contextWritten = false }) {
+  const body = String(words).replace(/\n+$/, "");
+  const lead = current !== null && current !== "" && !current.endsWith("\n") ? "\n" : "";
+  if (continuing && current !== null && !falsified("heading-per-write")) {
+    const ctx = context && !contextWritten ? `${contextLine(context)}\n\n` : "";
+    return { text: `${lead}\n${ctx}${body}\n`, opened: false };
+  }
+  const head = current === null ? `# ${date}\n` : "";
+  const ctx = context ? `${contextLine(context)}\n\n` : "";
+  return { text: `${lead}${head}\n## ${time}\n\n${ctx}${body}\n`, opened: true };
+}
+
+// Append `words` to the day file at `abs`. `session` is the conversation's mutable state ({} to
+// start one, null for a write that belongs to no conversation, which always opens a heading); it
+// remembers which file this conversation's section is in and how long that file was after its last
+// write. Returns { opened, bytes }.
+export function appendToDay(abs, { now = new Date(), words, context = null, session = null }) {
+  const exists = existsSync(abs);
+  const current = exists ? readFileSync(abs, "utf8") : null;
+  const s = session?.section;
+  const continuing = Boolean(s && exists && s.abs === abs && statSync(abs).size === s.size);
+  const w = sectionBytes({ current, date: localDate(now), time: localTime(now), words, context, continuing, contextWritten: Boolean(s?.context) });
+  appendFileSync(abs, w.text);
+  if (session) session.section = { abs, size: statSync(abs).size, context: Boolean(context) || (continuing && Boolean(s?.context)) };
+  return { opened: w.opened, bytes: Buffer.byteLength(w.text) };
+}

package/lib/declarations.mjs

@@ -0,0 +1,235 @@
+// Circle declarations: how a circle's declaration and its grants reach another holder (HQ-835).
+//
+// The first two-holder slice wrote the other holder's copy of a circle by hand: its manifest with
+// the owner's opaque id and a `mount`, and one grant file per reader, copied from the owner's record.
+// This module is what replaces the copying. The owner's device reads the declaration off its own
+// record (`declarationOf`), the substrate carries it to each grantee device signed by the owner
+// (`atlas-local/src/rendezvous.ts`, `deliverCircleDeclarations`), and the grantee device holds it
+// (`adoptDeclaration`): a manifest under its circles role, mounted at `mounts/<owner record id>`,
+// and a grant file per reader under its grants role, all in the shapes `circles.mjs` and
+// `grants.mjs` already read. Nothing is copied by a person.
+//
+// What travels is the owner's manifest minus what only means something on the owner's disk: the
+// opaque id and namespace, the title as the owner wrote it, `public: false`, `release`, and the
+// grant list. Not `members` (paths in the owner's tree) and not the directory name (it stays on the
+// owner's devices; the id is what travels). The receiver names its copy from the owner's record id
+// and the title, and mounts it at one path per owner.
+//
+// Revocation reaches the receiver as a "grant removed" notice, and the copy is FROZEN, never
+// deleted: the manifest gains `frozen: { since: <date>, by: revocation }`, the files under the
+// mount stay as they are, and a frozen circle is neither scanned for edits nor minted into. Spec 00
+// #37: revocation cannot reach a copy already opened, and each side keeps what it holds.
+//
+// Where a held circle lands is the `mounts` role (HQ-835). Mapped, each owner gets one directory
+// under it and each of their circles one subfolder, `<mounts>/<owner record id>/<slug of title>`,
+// so a receiver holds any number of circles from one owner side by side. The subfolder is chosen
+// once, when the circle is first held, and kept on every re-declaration, so a retitled circle does
+// not move. Unmapped, a record holds one circle per owner at `mounts/<owner record id>`, the layout
+// the first two-holder slice used, and a second circle from the same owner is refused with the
+// reason and the remedy (map the role).
+
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { circleManifest, circlesDir, ecoManifestPath, ecoNamespace, isRelease, readCircles } from "./circles.mjs";
+import { grant, grantsDir, MEMBER_ROLES, readGrants } from "./grants.mjs";
+import { resolveRole } from "./roles.mjs";
+import { HOLDER_KINDS } from "./manifest.mjs";
+import { parseYaml, toYaml } from "./yaml.mjs";
+import { EvdaError } from "./errors.mjs";
+
+// Where another holder's circles land in this record when no `mounts` role is mapped: one
+// directory per owner, holding one circle's files at their addresses.
+export const MOUNT_ROOT = "mounts";
+export const mountPathFor = (holder) => `${MOUNT_ROOT}/${holder}`;
+
+// The mount root this record declares, or null when the `mounts` role is not mapped. Normalised,
+// no trailing slash; "" is refused, since a mount root at the record root would put another
+// holder's files beside this record's own.
+export function mountRoot(evda) {
+  const r = resolveRole(evda, "mounts");
+  if (!r.mapped) return null;
+  const rel = String(r.rel).replace(/\/+$/, "").replace(/^\.\/+/, "");
+  if (rel === "" || rel === ".") throw new EvdaError('the "mounts" role cannot be the record root; another holder\'s files would sit beside this record\'s own.', { code: "BAD_MAPPING", exit: 2 });
+  return rel;
+}
+
+// Where a circle from `holder` titled `title` would be mounted here, given the mounts already
+// taken. Under a mapped root: `<root>/<holder>/<slug(title)>`, with the circle id's first eight
+// characters appended when two of the owner's circles share a title. Unmapped: the legacy path.
+export function mountFor(evda, holder, title, id, taken = new Set()) {
+  const root = mountRoot(evda);
+  if (root === null) return mountPathFor(holder);
+  const base = `${root}/${holder}/${slug(title)}`;
+  return taken.has(base) ? `${base}-${String(id).slice(0, 8)}` : base;
+}
+
+// Whether one mount path is the other or lies inside it.
+const nests = (a, b) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+// The `by` a revocation writes into `frozen`.
+export const FROZEN_BY_REVOCATION = "revocation";
+
+const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const slug = (s) => String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "circle";
+
+// The directory name a held circle gets here: the owner's record id without its `.atlas`, then the
+// title, both slugged. `ava.atlas` + "Shared with Ben" -> `ava-shared-with-ben`. A name, not an
+// identity: the id on the manifest is what the wire matches on.
+export const mountedName = (holder, title) => `${slug(holder.replace(/\.atlas$/, ""))}-${slug(title)}`;
+
+// The declaration of a circle this record homes, for the wire. Throws for a circle that is not
+// here, is malformed, is public (it travels as its export), or is held here from someone else.
+export function declarationOf(evda, circleName) {
+  const circles = readCircles(evda) ?? [];
+  const c = circles.find((x) => x.name === circleName);
+  if (!c) throw new EvdaError(`no circle named "${circleName}" in this record.`, { code: "NO_CIRCLE", exit: 2 });
+  const broken = c.problems.find((p) => p.level === "fail" && p.code !== "MISSING_MEMBER");
+  if (broken) throw new EvdaError(`circle "${circleName}" is malformed: ${broken.message}`, { code: "BAD_CIRCLE", exit: 2 });
+  if (c.manifest.public === true) throw new EvdaError(`circle "${circleName}" is public; a public circle travels as its export, not as a declaration.`, { code: "PUBLIC_CIRCLE", exit: 2 });
+  if (c.mount) throw new EvdaError(`circle "${circleName}" is held here from ${c.mount.holder}; only its owner declares it.`, { code: "NOT_OWNER", exit: 2 });
+  const grants = (readGrants(evda) ?? []).filter((g) => g.circle === circleName && g.problems.every((p) => p.level !== "fail"));
+  return {
+    id: c.id,
+    namespace: ecoNamespace(c.id),
+    title: c.manifest.title,
+    public: false,
+    release: c.release,
+    grants: grants
+      .map((g) => ({
+        principalId: g.principalId,
+        role: g.role,
+        holder: g.holder.name ? { kind: g.holder.kind, name: g.holder.name } : { kind: g.holder.kind },
+        grantedAt: String(g.manifest.grantedAt),
+        grantedBy: String(g.manifest.grantedBy),
+      }))
+      .sort((a, b) => a.principalId.localeCompare(b.principalId)),
+  };
+}
+
+// Why a declaration cannot be held, by its shape alone. null when it can.
+export function checkDeclaration(d) {
+  if (!isObject(d)) return "declaration is not a mapping";
+  if (!nonEmpty(d.id) || d.id.includes("/") || d.id.includes("..")) return "declaration has no usable id";
+  if (d.namespace !== ecoNamespace(d.id)) return `declaration namespace ${JSON.stringify(d.namespace)} does not name circle ${d.id}`;
+  if (!nonEmpty(d.title)) return "declaration has no title";
+  if (d.public !== false) return "a public circle travels as its export, not as a declaration";
+  if (!isRelease(d.release)) return `declaration release must be "never" or a list of circle names, got ${JSON.stringify(d.release)}`;
+  if (!Array.isArray(d.grants) || d.grants.length === 0) return "declaration carries no grants";
+  for (const g of d.grants) {
+    if (!isObject(g) || !nonEmpty(g.principalId)) return "a grant in the declaration names no principal";
+    if (!MEMBER_ROLES.includes(g.role)) return `the grant to ${g.principalId} has role ${JSON.stringify(g.role)}`;
+    if (!isObject(g.holder) || !HOLDER_KINDS.includes(g.holder.kind)) return `the grant to ${g.principalId} names no holder kind (${HOLDER_KINDS.join(", ")})`;
+    if (!nonEmpty(g.grantedAt) || !nonEmpty(g.grantedBy)) return `the grant to ${g.principalId} says not when or by whom`;
+  }
+  return null;
+}
+
+const maintainersOf = (grants) => grants.map((g) => ({ name: g.holder.name ?? g.principalId, role: "holder" }));
+
+// Hold a circle declared by `from`, its owner. Writes the manifest (mounted at `mounts/<from>`) and
+// one grant file per reader, and removes grant files on the circle that the declaration no longer
+// carries. Idempotent: the same declaration twice writes the same bytes and mints nothing. A
+// re-declaration of a frozen circle (a grant given again) thaws it.
+//
+// Returns { ok: true, name, mount, created } or { ok: false, why }. Refuses, with the reason:
+//   - a declaration whose grant list does not name `from` as owner (only an owner declares);
+//   - a declaration that grants nothing to this record;
+//   - a circle already homed here (a holder does not receive its own circle), or already held here
+//     from someone else under the same id;
+//   - a different circle already mounted from `from` (one mount per owner), or a circle already
+//     here under the name this one would take.
+export function adoptDeclaration(evda, from, d) {
+  const bad = checkDeclaration(d);
+  if (bad) return { ok: false, why: `circle declaration is malformed: ${bad}` };
+  if (!nonEmpty(from)) return { ok: false, why: "a declaration comes from a record id" };
+  if (!d.grants.some((g) => g.principalId === from && g.role === "owner")) return { ok: false, why: `${from} holds no owner grant in the declaration of circle ${d.id}; only its owner declares a circle` };
+  const me = evda.manifest?.id;
+  if (!nonEmpty(me)) return { ok: false, why: "this record has no id, so no declaration can name it" };
+  if (!d.grants.some((g) => g.principalId === me)) return { ok: false, why: `the declaration of circle ${d.id} grants nothing to ${me}` };
+  const cr = circlesDir(evda);
+  if (!cr.mapped) return { ok: false, why: 'no "circles" role in the mapping, so there is nowhere to hold a circle' };
+  const gr = grantsDir(evda);
+  if (!gr.mapped) return { ok: false, why: 'no "grants" role in the mapping, so there is nowhere to write its grants' };
+
+  const circles = readCircles(evda) ?? [];
+  let root;
+  try {
+    root = mountRoot(evda);
+  } catch (e) {
+    return { ok: false, why: e.message };
+  }
+  let name = mountedName(from, d.title);
+  let mount;
+  const existing = circles.find((c) => c.id === d.id);
+  if (existing) {
+    if (!existing.mount) return { ok: false, why: `circle ${d.id} is homed in this record as "${existing.name}"; a holder does not receive its own circle` };
+    if (existing.mount.holder !== from) return { ok: false, why: `circle ${d.id} is already held here from ${existing.mount.holder}, not from ${from}` };
+    name = existing.name;
+    // Chosen when the circle was first held and kept, so a retitled circle does not move.
+    mount = existing.mount.rel;
+  } else {
+    if (from === me) return { ok: false, why: `${from} is this record; a holder does not mount its own circles` };
+    const mounts = circles.filter((c) => c.mount).map((c) => ({ rel: c.mount.rel, c }));
+    mount = mountFor(evda, from, d.title, d.id, new Set(mounts.map((m) => m.rel)));
+    const clash = mounts.find((m) => nests(m.rel, mount));
+    if (clash) {
+      return root === null
+        ? { ok: false, why: `${clash.rel} already holds circle ${clash.c.id} ("${clash.c.name}") from ${clash.c.mount.holder}; without a "mounts" role a record holds one circle per owner. Map "mounts" in evda.json to hold several, one subfolder each` }
+        : { ok: false, why: `${mount} would sit inside or around ${clash.rel}, where circle ${clash.c.id} ("${clash.c.name}") is held; one subfolder per circle, never nested` };
+    }
+    if (circles.some((c) => c.name === name)) name = `${name}-${d.id.slice(0, 8)}`;
+    const named = circles.find((c) => c.name === name);
+    if (named) return { ok: false, why: `a circle named "${name}" is already here with id ${named.id ?? "(none)"}` };
+  }
+
+  mkdirSync(join(evda.dir, mount), { recursive: true });
+  const fresh = circleManifest({
+    name,
+    id: d.id,
+    title: d.title,
+    description: `Held from ${from}, by grant.`,
+    isPublic: false,
+    holders: maintainersOf(d.grants),
+    release: d.release === "never" ? null : d.release,
+    mount: { holder: from, path: mount },
+    members: { files: { path: mount } },
+  });
+  // A copy already here keeps what its holder added locally (a policy, a description of their own);
+  // what the owner declares is rewritten over it, and `frozen` is lifted by a re-declaration.
+  const manifest = existing ? { ...existing.manifest, ...fresh, description: existing.manifest.description ?? fresh.description } : fresh;
+  delete manifest.frozen;
+  const dir = join(cr.abs, name);
+  const p = ecoManifestPath(dir);
+  const text = toYaml(manifest);
+  mkdirSync(dir, { recursive: true });
+  if (!existsSync(p) || readFileSync(p, "utf8") !== text) writeFileSync(p, text);
+
+  for (const g of d.grants) {
+    grant(evda, { circle: name, to: { id: g.principalId, kind: g.holder.kind, name: g.holder.name }, role: g.role, by: g.grantedBy, at: g.grantedAt }, { overwrite: true });
+  }
+  const declared = new Set(d.grants.map((g) => g.principalId));
+  for (const g of readGrants(evda) ?? []) {
+    if (g.circle === name && g.principalId !== null && !declared.has(g.principalId)) unlinkSync(g.file);
+  }
+  return { ok: true, name, mount, created: !existing };
+}
+
+// A grant on a held circle was removed by its owner: mark the copy frozen since `at`. The files
+// under the mount and the grant files stay; nothing is deleted. Idempotent.
+// Returns { ok: true, name, already } or { ok: false, why }.
+export function freezeCircle(evda, from, circleId, at) {
+  if (!nonEmpty(from) || !nonEmpty(circleId)) return { ok: false, why: "a revocation names a record id and a circle id" };
+  const since = typeof at === "string" && /^\d{4}-\d{2}-\d{2}/.test(at) ? at.slice(0, 10) : null;
+  if (!since) return { ok: false, why: `a revocation carries the date it took effect, got ${JSON.stringify(at)}` };
+  const circles = readCircles(evda) ?? [];
+  const c = circles.find((x) => x.id === circleId);
+  if (!c) return { ok: false, why: `no circle ${circleId} is held here` };
+  if (!c.mount) return { ok: false, why: `circle ${circleId} is homed in this record as "${c.name}"; nobody else revokes it` };
+  if (c.mount.holder !== from) return { ok: false, why: `circle ${circleId} is held here from ${c.mount.holder}, not from ${from}` };
+  const p = ecoManifestPath(c.abs);
+  const m = parseYaml(readFileSync(p, "utf8"));
+  if (isObject(m.frozen)) return { ok: true, name: c.name, already: true };
+  m.frozen = { since, by: FROZEN_BY_REVOCATION };
+  writeFileSync(p, toYaml(m));
+  return { ok: true, name: c.name, already: false };
+}

package/lib/devices.mjs

@@ -0,0 +1,202 @@
+// Devices: the devices a holder's record id resolves to (HQ-835).
+//
+// A grant names a HOLDER: another record, by its record id (Spec 00 #65). A key is sealed to a
+// DEVICE: one atlas, with its own identity and sealing keys, pinned as a peer. Until this module, a
+// holder was one device and the two ids were the same string. Now a record id resolves to the
+// devices listed for it, one file per holder under the grants role:
+//
+//   grants/devices/<record id>.yaml
+//
+//   kind: holder-devices
+//   record: ben.atlas
+//   devices:
+//     - atlasId: ben.atlas
+//       identityPublicKey: <raw 32 bytes, base64: the key this record pinned for the device>
+//       addedAt: 2026-09-22T12:00:00.000Z
+//       addedBy: ben.atlas
+//     - atlasId: ben-phone.atlas
+//       identityPublicKey: ...
+//       addedAt: ...
+//       addedBy: ben.atlas
+//       retiredAt: ...            set when the holder retired the device; kept as history
+//       retiredBy: ben.atlas
+//
+// A record id with no file resolves to itself: one device whose atlas id is the record id, which is
+// every holder the first two slices built and every per-device grant HQ-1219's plan writes. So
+// nothing written before this module changes meaning.
+//
+// Who writes the file. On the holder's own record, the holder. On a record that grants the holder a
+// circle, the receiving device writes it when the holder's existing device introduces a new one
+// over the relay (`atlas-local/src/rendezvous.ts`, `holder-device`), signed by that device's pinned
+// identity key: a holder decides its own devices, and a grant to the holder reaches every device it
+// vouches for. A retired device resolves to no holder: it may no longer author into any circle, it
+// is routed nothing, and the circles it could read are re-keyed without it.
+//
+// On the holder's own devices the list is kept the same way (`addOwnDevice`, `retireHolderDevice`
+// in rendezvous.ts): the device that adds or retires writes its own copy, then tells each sibling it
+// is paired with, signed, and tells a new device the whole list, itself included. The first device
+// of a record carries the record id as its atlas id, which is what a new device trusts before any
+// list reaches it.
+//
+// Grants live outside the circles they govern; so does this, beside them.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { grantsDir, checkPrincipalId } from "./grants.mjs";
+import { parseYaml, toYaml } from "./yaml.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const DEVICES_SUBDIR = "devices";
+export const DEVICES_KIND = "holder-devices";
+// atlas-arch:yaml-encoding: a device list is a config file this layer names by its suffix, like a grant
+export const DEVICES_SUFFIX = ".yaml";
+
+const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const active = (d) => !nonEmpty(d.retiredAt);
+
+export const devicesFile = (record) => `${record}${DEVICES_SUFFIX}`;
+
+// Every device list under the grants role. Returns { lists: Map<record, { file, rel, devices }>,
+// problems } or null when the record has no grants role. Never throws for a problem in a file.
+export function readDevices(evda) {
+  const role = grantsDir(evda);
+  if (!role.mapped) return null;
+  const lists = new Map();
+  const problems = [];
+  const dir = join(role.abs, DEVICES_SUBDIR);
+  if (!existsSync(dir)) return { lists, problems };
+  for (const name of readdirSync(dir).sort()) {
+    const abs = join(dir, name);
+    if (name.startsWith(".") || !statSync(abs).isFile() || !name.endsWith(DEVICES_SUFFIX)) continue;
+    const rel = relative(evda.dir, abs);
+    const fail = (m) => problems.push({ level: "fail", message: `${rel}: ${m}` });
+    let m;
+    try {
+      m = parseYaml(readFileSync(abs, "utf8"));
+    } catch (e) {
+      fail(`is not readable YAML (${e.message}).`);
+      continue;
+    }
+    const record = name.slice(0, -DEVICES_SUFFIX.length);
+    if (!isObject(m)) { fail("must hold a mapping."); continue; }
+    if (m.kind !== DEVICES_KIND) { fail(`"kind" must be "${DEVICES_KIND}", got ${JSON.stringify(m.kind)}.`); continue; }
+    if (m.record !== record) { fail(`names record ${JSON.stringify(m.record)} but the file says ${JSON.stringify(record)}. The filename is the address.`); continue; }
+    if (!Array.isArray(m.devices)) { fail(`"devices" must be a list.`); continue; }
+    const devices = [];
+    const seen = new Set();
+    for (const [i, d] of m.devices.entries()) {
+      if (!isObject(d) || !nonEmpty(d.atlasId)) { fail(`devices[${i}] names no atlasId.`); continue; }
+      if (seen.has(d.atlasId)) { fail(`lists ${d.atlasId} twice.`); continue; }
+      seen.add(d.atlasId);
+      if (!nonEmpty(d.addedAt) || !nonEmpty(d.addedBy)) fail(`devices[${i}] (${d.atlasId}) says not when or by whom it was added.`);
+      if (nonEmpty(d.retiredAt) && !nonEmpty(d.retiredBy)) fail(`devices[${i}] (${d.atlasId}) is retired and says not by whom.`);
+      devices.push({ ...d });
+    }
+    lists.set(record, { file: abs, rel, devices });
+  }
+  // One device, one holder: an atlas active in two lists would carry two holders' authority.
+  const owner = new Map();
+  for (const [record, list] of lists) {
+    for (const d of list.devices.filter(active)) {
+      if (owner.has(d.atlasId)) problems.push({ level: "fail", message: `${d.atlasId} is an active device of both ${owner.get(d.atlasId)} and ${record}. One device, one holder.` });
+      else owner.set(d.atlasId, record);
+    }
+  }
+  return { lists, problems };
+}
+
+// The active devices a record id resolves to. No list: the record id itself.
+export function devicesOf(read, record) {
+  const list = read?.lists.get(record);
+  if (!list) return [record];
+  return list.devices.filter(active).map((d) => d.atlasId);
+}
+
+// The record a device speaks for, or null when it speaks for none (retired, or listed under a record
+// that no longer counts it). A device no list names, whose id no list is keyed by, is its own record.
+export function recordOf(read, atlasId) {
+  if (!nonEmpty(atlasId)) return null;
+  for (const [record, list] of read?.lists ?? []) {
+    if (list.devices.some((d) => d.atlasId === atlasId && active(d))) return record;
+  }
+  for (const [, list] of read?.lists ?? []) {
+    if (list.devices.some((d) => d.atlasId === atlasId)) return null;
+  }
+  if (read?.lists.has(atlasId)) return null;
+  return atlasId;
+}
+
+function writeList(evda, record, devices) {
+  const gr = grantsDir(evda);
+  if (!gr.mapped) throw new EvdaError('no "grants" role in the mapping, so there is nowhere to write a device list.', { exit: 2 });
+  const dir = join(gr.abs, DEVICES_SUBDIR);
+  mkdirSync(dir, { recursive: true });
+  const p = join(dir, devicesFile(record));
+  const text = toYaml({ kind: DEVICES_KIND, record, devices });
+  if (!existsSync(p) || readFileSync(p, "utf8") !== text) writeFileSync(p, text);
+  return p;
+}
+
+const entry = (device, by, at) => {
+  const e = { atlasId: device.atlasId };
+  if (nonEmpty(device.identityPublicKey)) e.identityPublicKey = device.identityPublicKey;
+  e.addedAt = at;
+  e.addedBy = by;
+  return e;
+};
+
+// Add a device to a holder's list, as introduced by `introducer`, a device that already speaks for
+// the holder. When no list exists yet the introducer is written first, so the list says every
+// device the record id now resolves to. Idempotent for a device already active with the same key.
+// Returns { ok: true, already, file } or { ok: false, why }.
+export function admitDevice(evda, { record, device, introducer, at }) {
+  try {
+    checkPrincipalId(record);
+    checkPrincipalId(device?.atlasId);
+    checkPrincipalId(introducer?.atlasId);
+  } catch (e) {
+    return { ok: false, why: e.message };
+  }
+  if (!nonEmpty(at)) return { ok: false, why: "a device is added at a stated time" };
+  const read = readDevices(evda);
+  if (read === null) return { ok: false, why: 'no "grants" role in the mapping, so there is nowhere to write a device list' };
+  if (recordOf(read, introducer.atlasId) !== record) return { ok: false, why: `${introducer.atlasId} is not a device of ${record} here, so it cannot add one` };
+  const holder = recordOf(read, device.atlasId);
+  if (read.lists.has(device.atlasId) && device.atlasId !== record) return { ok: false, why: `${device.atlasId} is a record here, not a device` };
+  if (holder !== null && holder !== device.atlasId && holder !== record) return { ok: false, why: `${device.atlasId} is already a device of ${holder}` };
+  const list = read.lists.get(record);
+  const devices = list ? list.devices.map((d) => ({ ...d })) : [entry(introducer, introducer.atlasId, at)];
+  const i = devices.findIndex((d) => d.atlasId === device.atlasId);
+  if (i >= 0 && active(devices[i])) {
+    if (nonEmpty(devices[i].identityPublicKey) && nonEmpty(device.identityPublicKey) && devices[i].identityPublicKey !== device.identityPublicKey) {
+      return { ok: false, why: `${device.atlasId} is already a device of ${record} under a different identity key` };
+    }
+    return { ok: true, already: true, file: list ? list.file : writeList(evda, record, devices) };
+  }
+  if (i >= 0) devices[i] = entry(device, introducer.atlasId, at);
+  else devices.push(entry(device, introducer.atlasId, at));
+  return { ok: true, already: false, file: writeList(evda, record, devices) };
+}
+
+// Retire a device of a holder: it stays in the list as history, resolves to no holder from now on,
+// and is routed nothing. `by` must be a device of the holder, or this record itself (an owner may
+// stop trusting a device on its own records). Idempotent. Returns { ok: true, already, file } or
+// { ok: false, why }.
+export function retireDevice(evda, { record, atlasId, by, at }) {
+  if (!nonEmpty(record) || !nonEmpty(atlasId) || !nonEmpty(by)) return { ok: false, why: "a retirement names the record, the device and who retired it" };
+  if (!nonEmpty(at)) return { ok: false, why: "a device is retired at a stated time" };
+  const read = readDevices(evda);
+  if (read === null) return { ok: false, why: 'no "grants" role in the mapping, so there is nowhere to write a device list' };
+  if (by !== evda.manifest?.id && recordOf(read, by) !== record) return { ok: false, why: `${by} is not a device of ${record} here, so it cannot retire one` };
+  const list = read.lists.get(record);
+  const devices = list ? list.devices.map((d) => ({ ...d })) : devicesOf(read, record).map((id) => entry({ atlasId: id }, record, at));
+  const i = devices.findIndex((d) => d.atlasId === atlasId);
+  // A device this record never listed for the holder resolves to no holder here already: the notice
+  // changes nothing, and is not a refusal (a holder tells every device it is paired with, and not
+  // every one of them was told of every device).
+  if (i < 0) return { ok: true, already: true, file: list?.file ?? null };
+  if (!active(devices[i])) return { ok: true, already: true, file: list.file };
+  devices[i] = { ...devices[i], retiredAt: at, retiredBy: by };
+  return { ok: true, already: false, file: writeList(evda, record, devices) };
+}