create-evda 0.1.4 → 0.1.6

package/lib/publish.mjs

@@ -0,0 +1,264 @@
+// `evda publish public`: the public circle as a signed, plaintext export (Spec 08, section 4).
+//
+// Runs on the owner's device, reads only the public circle's declared members, and writes
+//
+//   <out>/manifest.json   format, circle id, record id, publishedAt, files [{ path, sha256, bytes }],
+//                         tables [{ table, where, rows }], publicKey, signature (Ed25519 over the
+//                         canonical manifest, which is the manifest without its signature, keys sorted)
+//   <out>/files/<path>    the member files, byte for byte; and each render member's file, rendered
+//                         from the released entries that name its view (lib/render.mjs, HQ-1351),
+//                         listed in the manifest with `by: "view"`, the view's name and the source
+//                         entries' record paths and sha256s. The entries a view consumes are not
+//                         exported as themselves: the rendering is their public form, and the
+//                         public set stays exactly what the site reads.
+//
+// Never through the relay: a public circle needs no key, a durable URL and a cache, and the relay
+// is delete-on-ack with sealed envelopes a browser cannot open.
+//
+// Three checks run on the device before anything is written, and each can refuse (exit 2):
+//
+//   1. the circle is opened through `publicCircle`, which throws unless exactly one public circle
+//      is named, and only its declared members are read;
+//   2. one keyed circle per path, and that circle allows release: a file under a public path member
+//      that any other circle also covers is refused, so a private path cannot also be a public
+//      member; a file gathered by rule (Spec 07 section 3, HQ-1351) is exported at its record path
+//      only when its one home circle's release names the public circle, and a match the home
+//      refuses refuses the whole publish rather than being dropped; a view with any problem (an
+//      entry naming a view nothing renders, a repeated order, a body with no JSON) refuses too;
+//   3. render as a stranger: every private circle's label is searched for in the bytes about to be
+//      written, and a hit refuses. A label is its opaque id, its namespace, its own directory, a
+//      member path, or its name between slashes. The exported files' own paths are the released
+//      set (doctor prints them every run) and are left out of that search, since a marked file
+//      necessarily lives under a keyed circle's member path.
+//
+// The fourth check in the spec (the site holds no credential to anything else) is a property of
+// where the export is served, not of this code.
+//
+// The signing key is the record's identity key. The Node host keeps it in its own database until
+// the keychain adapter (slice 2), so this reads the 32-byte Ed25519 seed from a file the device
+// exports, hex encoded, named by --key.
+
+import { createHash, createPrivateKey, createPublicKey, sign, verify } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { openEvda } from "./manifest.mjs";
+import { publicCircle, readCircles, released, homesOf, withoutSealed, carries } from "./circles.mjs";
+import { renderViews } from "./render.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const EXPORT_FORMAT = "evda-public-export/1";
+
+// The boundary checks, as a switch a test can turn off to show that the acceptance test fails
+// without them (FALSIFIED lines in atlas-local/src/slice.e2e.test.ts). Nothing in this package
+// turns them off.
+export const PUBLISH_CHECKS = { onePerPath: true, strangerRender: true };
+
+const ED25519_PKCS8 = "302e020100300506032b657004220420";
+const sha256Hex = (bytes) => createHash("sha256").update(bytes).digest("hex");
+
+function filesUnder(abs) {
+  const st = statSync(abs);
+  if (st.isFile()) return [abs];
+  const out = [];
+  for (const name of readdirSync(abs).sort()) {
+    if (name.startsWith(".")) continue;
+    out.push(...filesUnder(join(abs, name)));
+  }
+  return out;
+}
+
+const posix = (rel) => rel.split(sep).join("/");
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+// Build the export in memory and run the checks. Writes nothing.
+export function buildPublicExport(evda, { circleName = null, publishedAt = new Date() } = {}) {
+  const circle = publicCircle(evda, circleName);
+  const all = readCircles(evda) ?? [];
+
+  const files = [];
+  for (const m of Object.values(circle.members)) {
+    if (m.kind !== "path") continue;
+    for (const abs of filesUnder(m.abs)) files.push({ abs, path: posix(relative(evda.dir, abs)), by: "path" });
+  }
+
+  if (PUBLISH_CHECKS.onePerPath) {
+    // A file under a public member is exported only when the public circle is its HOME, by longest
+    // member path (HQ-1364): a private circle at the record root does not make it private, and a
+    // private circle with a longer member under the public one does.
+    for (const f of files) {
+      const others = homesOf(evda, all, f.abs).filter((n) => n !== circle.name);
+      if (others.length) {
+        throw new EvdaError(`REFUSED: ${f.path} is a public member and is also covered by circle "${others[0]}". One access answer per entry; nothing was written.`, { code: "TWO_CIRCLES", exit: 2 });
+      }
+    }
+  }
+
+  // Files gathered by rule: from wherever they live, only out of a home whose release names this
+  // circle. With the check off (a test proving it matters), a refused match is exported like any other.
+  const gathered = released(evda, all).find((r) => r.circle === circle.name) ?? { byRule: [], refused: [] };
+  if (PUBLISH_CHECKS.onePerPath && gathered.refused.length) {
+    const f = gathered.refused[0];
+    throw new EvdaError(`REFUSED: ${f.path} matches a rule of the public circle and ${f.reason}. Nothing was written.`, { code: "REFUSED_MARK", exit: 2 });
+  }
+  for (const f of gathered.byRule) files.push({ abs: f.abs, path: f.path, by: "mark", circle: f.circle });
+  if (!PUBLISH_CHECKS.onePerPath) for (const f of gathered.refused.filter((f) => f.abs !== undefined && f.member !== "release")) files.push({ abs: f.abs, path: f.path, by: "mark", circle: f.circle });
+
+  // Views (HQ-1351): every released entry that names a view is consumed by the render member that
+  // declares it, and the rendered file is exported in its place. Any problem refuses the publish.
+  const rendered = renderViews(evda, circle, { byPath: files.filter((f) => f.by === "path"), byRule: files.filter((f) => f.by === "mark") });
+  if (rendered.problems.length) {
+    const p = rendered.problems[0];
+    throw new EvdaError(`REFUSED: ${p.path} ${p.message}${rendered.problems.length > 1 ? ` (${rendered.problems.length - 1} more problem(s); evda doctor names them all)` : ""} Nothing was written.`, { code: "REFUSED_VIEW", exit: 2 });
+  }
+  const consumed = new Set(rendered.views.flatMap((v) => v.entries.map((e) => e.path)));
+  // A sealed section (HQ-1220) is cut out of every markdown file on the way out; the rest of the
+  // file is exported, and nothing marks where the section was. A sealed FILE never gets here:
+  // released() refuses it, and a refusal refuses the publish above.
+  let sealedCut = 0;
+  const exportBytes = (abs) => {
+    const bytes = readFileSync(abs);
+    if (!/\.md$/i.test(abs) || !carries("publish", "sealed")) return bytes;
+    const cut = withoutSealed(bytes.toString("utf8"));
+    if (!cut.sections) return bytes;
+    sealedCut += cut.sections;
+    return Buffer.from(cut.text, "utf8");
+  };
+  const loaded = files.filter((f) => !consumed.has(f.path)).map((f) => ({ path: f.path, bytes: exportBytes(f.abs), by: f.by }));
+  for (const v of rendered.views) loaded.push({ path: v.path, bytes: v.bytes, by: "view", view: v.view, sources: v.entries.map((e) => ({ path: e.path, sha256: e.sha256 })) });
+  loaded.sort((a, b) => a.path.localeCompare(b.path));
+
+  const tables = Object.values(circle.members)
+    .filter((m) => m.kind === "table")
+    // A table member is a live read on the host that serves it. The snapshot for a reader that has
+    // no such host is not built in the first slice, so the rows are recorded as not included.
+    .map((m) => ({ table: m.table, where: m.where, rows: null }));
+  const manifest = {
+    format: EXPORT_FORMAT,
+    circle: circle.id,
+    record: evda.manifest.id ?? null,
+    publishedAt: publishedAt instanceof Date ? publishedAt.toISOString() : String(publishedAt),
+    files: loaded.map((f) => (f.by === "view"
+      ? { path: f.path, sha256: sha256Hex(f.bytes), bytes: f.bytes.length, by: "view", view: f.view, sources: f.sources }
+      : { path: f.path, sha256: sha256Hex(f.bytes), bytes: f.bytes.length })),
+    tables,
+  };
+
+  if (PUBLISH_CHECKS.strangerRender) {
+    // The manifest minus the exported paths themselves and a rendered file's source paths: they
+    // are the released set by definition, and a marked file's path is always under some keyed
+    // circle's member path. A rendered file's own path is chosen, not inherited, so it is searched.
+    const manifestSansPaths = { ...manifest, files: manifest.files.map(({ path: _p, sources: _s, ...rest }) => rest) };
+    const haystacks = [
+      { where: "manifest.json", text: JSON.stringify(manifestSansPaths) },
+      { where: "manifest.json (rendered paths)", text: manifest.files.filter((f) => f.by === "view").map((f) => f.path).join("\n") },
+      ...loaded.map((f) => ({ where: f.path, text: f.bytes.toString("utf8") })),
+    ];
+    for (const c of all.filter((x) => x.manifest?.public !== true)) {
+      // What identifies a private circle to a stranger is a LABEL: a path segment, the circle's own
+      // directory, or the opaque id that travels on a Change and in an export manifest. A name
+      // matched as a word anywhere in the bytes is not that test, and on a real record it refuses
+      // every publish there is: his private circles are core, health, money, people, school,
+      // therapy, wellness and workshop, and his public fact sheet says "10 core mechanics" and
+      // "help other people understand me" (2026-09-21, HQ-1199). So the name is matched only
+      // between slashes, and the id and namespace, which the word match never looked at, are
+      // matched literally. The gap this leaves, stated so the next reader does not rediscover it:
+      // a distinctive circle name written as bare prose passes.
+      const needles = [];
+      // A one-segment path is a bare name, so it is matched the way a name is: between slashes.
+      // "CLAUDE.md" is a member of his core circle AND a filename his public projects page names;
+      // as a raw substring it refuses every publish while disclosing nothing.
+      const label = (s) => (s.includes("/") ? new RegExp(escapeRe(s)) : new RegExp(`(^|[\\\\/])${escapeRe(s)}($|[\\\\/])`, "iu"));
+      for (const s of new Set([c.name, c.manifest?.title].filter((v) => typeof v === "string" && v.trim() !== ""))) {
+        needles.push({ what: `the name of private circle "${c.name}" as a path segment`, re: label(s) });
+      }
+      for (const s of new Set([c.id, c.manifest?.id, c.manifest?.namespace].filter((v) => typeof v === "string" && v.trim() !== ""))) {
+        needles.push({ what: `the id of private circle "${c.name}" (${s})`, re: new RegExp(escapeRe(s)) });
+      }
+      needles.push({ what: `the directory of private circle "${c.name}" (${c.rel})`, re: label(c.rel.replace(/\/+$/, "")) });
+      for (const m of Object.values(c.members)) {
+        // The record root ("") is a member with no name: it identifies nothing to a stranger, and as
+        // a bare label it matched every "//" in a URL and refused every publish (found 2026-09-22,
+        // the day after HQ-1364 made core a root member).
+        if (m.kind === "path" && m.rel !== "") needles.push({ what: `a member path of private circle "${c.name}" (${m.rel})`, re: label(m.rel.replace(/\/+$/, "")) });
+      }
+      for (const n of needles) {
+        const hit = haystacks.find((h) => n.re.test(h.text));
+        if (hit) throw new EvdaError(`REFUSED: rendered as a stranger, the export shows ${n.what} in ${hit.where}. Nothing was written.`, { code: "STRANGER_RENDER", exit: 2 });
+      }
+    }
+  }
+
+  return { manifest, files: loaded, sealedCut };
+}
+
+export function canonicalManifest(manifest) {
+  const sortKeys = (v) => (Array.isArray(v) ? v.map(sortKeys) : v && typeof v === "object" ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sortKeys(v[k])])) : v);
+  const { signature: _omit, ...rest } = manifest;
+  return JSON.stringify(sortKeys(rest));
+}
+
+export function signManifest(manifest, seedHex) {
+  if (!/^[0-9a-f]{64}$/i.test(seedHex.trim())) throw new EvdaError("REFUSED: the signing key must be a 32-byte Ed25519 seed, hex encoded.", { code: "BAD_KEY", exit: 2 });
+  const privateKey = createPrivateKey({ key: Buffer.concat([Buffer.from(ED25519_PKCS8, "hex"), Buffer.from(seedHex.trim(), "hex")]), format: "der", type: "pkcs8" });
+  const { x } = createPublicKey(privateKey).export({ format: "jwk" });
+  const withKey = { ...manifest, publicKey: Buffer.from(x, "base64url").toString("base64") };
+  return { ...withKey, signature: sign(null, Buffer.from(canonicalManifest(withKey)), privateKey).toString("base64") };
+}
+
+// Verify an export against a key the reader already trusts (raw 32-byte Ed25519 public key), never
+// against the key the manifest carries. Returns { ok, why }.
+export function verifyExport(out, publicKeyRaw) {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(join(out, "manifest.json"), "utf8"));
+  } catch (e) {
+    return { ok: false, why: `manifest.json is unreadable (${e.message})` };
+  }
+  const key = createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: Buffer.from(publicKeyRaw).toString("base64url") }, format: "jwk" });
+  let good = false;
+  try {
+    good = verify(null, Buffer.from(canonicalManifest(manifest)), key, Buffer.from(String(manifest.signature ?? ""), "base64"));
+  } catch {
+    good = false;
+  }
+  if (!good) return { ok: false, why: "the signature does not verify against the key given" };
+  for (const f of manifest.files ?? []) {
+    const p = join(out, "files", f.path);
+    if (!existsSync(p)) return { ok: false, why: `${f.path} is listed and missing` };
+    const bytes = readFileSync(p);
+    if (bytes.length !== f.bytes || sha256Hex(bytes) !== f.sha256) return { ok: false, why: `${f.path} does not match its manifest entry` };
+  }
+  return { ok: true, why: `signature verifies; ${manifest.files.length} file(s) match` };
+}
+
+// Write the export. The record is never the destination.
+export function writeExport(evda, out, { manifest, files }) {
+  const abs = resolve(out);
+  if (abs === evda.dir || abs.startsWith(evda.dir + sep)) throw new EvdaError(`REFUSED: ${out} is inside the record; an export is written outside it.`, { code: "EXPORT_INSIDE", exit: 2 });
+  rmSync(join(abs, "files"), { recursive: true, force: true });
+  for (const f of files) {
+    const p = join(abs, "files", f.path);
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, f.bytes);
+  }
+  writeFileSync(join(abs, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+  return abs;
+}
+
+// The CLI half, called from bin/evda.mjs so that file only dispatches.
+export async function publishCommand(dir, circleName, { out, key }) {
+  if (circleName !== "public") throw new EvdaError(`publish takes the public circle: evda publish public --out <dir> --key <seed file>`, { exit: 2 });
+  if (!out || !key) throw new EvdaError("publish needs --out <dir> and --key <file holding the identity seed, hex>", { exit: 2 });
+  const evda = openEvda(dir);
+  const built = buildPublicExport(evda);
+  const signed = signManifest(built.manifest, readFileSync(key, "utf8"));
+  const at = writeExport(evda, out, { manifest: signed, files: built.files });
+  const marked = built.files.filter((f) => f.by === "mark").length;
+  const views = built.files.filter((f) => f.by === "view");
+  const drawn = views.reduce((n, f) => n + f.sources.length, 0);
+  console.log(`published ${built.files.length} file(s) from the public circle to ${at} (${built.files.length - marked - views.length} by path, ${marked} by mark${views.length ? `, ${views.length} rendered from ${drawn} entries` : ""})`);
+  for (const f of views) console.log(`  view  ${f.path}  rendered from ${f.sources.length} entries (${f.view})`);
+  if (built.sealedCut) console.log(`  ${built.sealedCut} sealed section(s) left out of the files they sit in`);
+  console.log(`CHECKED ${built.files.length} public members, signed by ${signed.publicKey}`);
+  return 0;
+}

package/lib/readers.mjs

@@ -0,0 +1,319 @@
+// Who may read each part of a record, and the entries no AI reads (HQ-1374).
+//
+// Two facts, both written in the record where the owner can read them:
+//
+//   read_by   on a circle's eco.yaml, or on evda.json for the whole record: which AI reads that part.
+//             The default for a new record is the AI the owner chose at setup (create-evda writes it
+//             into evda.json), because most people have no local model and the barrier to using this
+//             has to be as low as it can be. Restricting it is opt-in. A circle without its own
+//             read_by takes evda.json's; neither saying anything means the record states no reader,
+//             and whatever AI opens it reads what it opens.
+//
+//               read_by: claude                     one AI, by its setup key
+//               read_by: local                      only a model on the owner's own devices
+//               read_by: none                       no AI; the owner reads it on their devices
+//               read_by:                            a list, each a key or one of these mappings:
+//                 - ai: claude                        an AI by its setup key (lib/setup.mjs PLATFORMS)
+//                   model: <name>                     optional, the model when it matters
+//                   terms: consumer | api | business optional, which of the company's terms apply
+//                   training: off | on | unknown      what the owner confirmed
+//                   confirmed: YYYY-MM-DD             when they confirmed it
+//                 - local: <model name, or any>       a model running on the owner's own hardware
+//                   on: <which devices>               optional, in the owner's words
+//
+//             Printed the way Spec 06 "The call on phrasing" rules: a statement of who reads it,
+//             never a promise that nobody can. "Read by: Anthropic through Claude, training off".
+//
+//   noted     `noted: true` in one entry's frontmatter: the owner said "just note this". It stays on
+//             their devices and in their own search, and no AI reads it until they say it can, which
+//             clears the flag (releaseNote below). It is not a circle and not a share mark, and a mark
+//             never releases it (lib/circles.mjs released()).
+//
+//   sealed    `sealed: true` in one entry's frontmatter, or a fenced ```sealed block inside one
+//             (HQ-1220): nothing but the owner's own devices opens it, ever. Stronger than noted: it
+//             is refused to every caller, a local model through the MCP included, no tool releases
+//             it, and an AI is never told where it is or whether a search touched it. A sealed
+//             section is taken out of the file the AI is shown and replaced by one line saying
+//             something sealed is there. The helpers live in lib/circles.mjs beside NOTED.
+//
+// Nothing here is a lock. The words are plain files on the owner's disk, and an agent that ignores
+// its instructions can open them. What this module gives is the answer every well-behaved reader
+// asks before it reads: the MCP server refuses in code, the Claude Code hook (hooks/) refuses the
+// ordinary file tools, and AGENTS.md tells any other agent to check and decline out loud.
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { readCircles, homesOf, frontmatterOf, NOTED, READ_BY, SEALED, sealedFront, sealedSections, withoutSealed } from "./circles.mjs";
+import { resolveRole } from "./roles.mjs";
+import { mdFiles } from "./record.mjs";
+import { parseYaml } from "./yaml.mjs";
+import { EvdaError } from "./errors.mjs";
+import { PLATFORMS, PLATFORM_KEYS } from "./setup.mjs";
+
+export { NOTED, READ_BY, SEALED, withoutSealed };
+
+// What an AI is shown where a sealed section was, and what it is told about sealed entries it was
+// not shown. Neither names a path, a count of matches, or anything that depends on the words.
+export const SEALED_PLACEHOLDER = "[sealed: only the owner opens this part, on their own devices]";
+export const SEALED_WHY = "It is sealed: only its owner opens it, on their own devices. No AI reads it, and no tool releases it.";
+export const SEALED_HELD = "Some of this record is sealed: only its owner opens it, on their own devices. No AI is shown it or told where it is; the owner's own search on their device (evda search) covers it.";
+
+export const TERMS = ["consumer", "api", "business"];
+export const TRAINING = ["off", "on", "unknown"];
+const COMPANY = { claude: "Anthropic", chatgpt: "OpenAI", gemini: "Google", cursor: "Cursor", other: null };
+const APP = { claude: "Claude", chatgpt: "ChatGPT or Codex", gemini: "Gemini", cursor: "Cursor", other: null };
+const TERMS_WORDS = { consumer: "personal-plan terms", api: "API terms", business: "business terms" };
+const READER_KEYS = { ai: ["ai", "name", "model", "terms", "training", "confirmed"], local: ["local", "on"] };
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
+
+// The test hooks. Each one breaks exactly one refusal so the tests can be watched failing.
+//   EVDA_READERS_FALSIFY=noted-readable   a noted entry is treated as readable
+//   EVDA_READERS_FALSIFY=ignore-reader    a circle's read_by is ignored
+//   EVDA_READERS_FALSIFY=accept-any       a read_by that does not parse is reported as fine
+const FALSIFY = () => process.env.EVDA_READERS_FALSIFY ?? "";
+
+// Parse one read_by value. Returns { readers, problems }: readers is null when the value is absent,
+// otherwise a list of { kind: "ai" | "local" | "none", ... }. Never throws; every problem is a
+// sentence for doctor.
+export function parseReaders(value, where = "read_by") {
+  const problems = [];
+  if (value === undefined || value === null) return { readers: null, problems };
+  const items = Array.isArray(value) ? value : [value];
+  if (items.length === 0) { problems.push(`${where} is an empty list. Say who reads it: an AI (claude, chatgpt, gemini, cursor, other), local, or none.`); return { readers: null, problems }; }
+  const readers = [];
+  items.forEach((item, i) => {
+    const at = Array.isArray(value) ? `${where}[${i}]` : where;
+    if (typeof item === "string") {
+      const s = item.trim().toLowerCase();
+      if (s === "none") readers.push({ kind: "none" });
+      else if (s === "local") readers.push({ kind: "local", model: null, on: null });
+      else if (PLATFORM_KEYS.includes(s)) readers.push({ kind: "ai", ai: s });
+      else problems.push(`${at} is ${JSON.stringify(item)}. A reader is one of ${[...PLATFORM_KEYS, "local", "none"].join(", ")}, or a mapping with "ai" or "local".`);
+      return;
+    }
+    if (!isObject(item)) { problems.push(`${at} must be a word or a mapping, got ${JSON.stringify(item)}.`); return; }
+    if (item.ai !== undefined && item.local !== undefined) { problems.push(`${at} has both "ai" and "local". One reader per item.`); return; }
+    if (item.ai !== undefined) {
+      const ai = String(item.ai).trim().toLowerCase();
+      if (!PLATFORM_KEYS.includes(ai)) { problems.push(`${at} ai is ${JSON.stringify(item.ai)}; it is one of ${PLATFORM_KEYS.join(", ")}.`); return; }
+      if (item.terms !== undefined && !TERMS.includes(item.terms)) problems.push(`${at} terms is ${JSON.stringify(item.terms)}; it is one of ${TERMS.join(", ")}.`);
+      if (item.training !== undefined && !TRAINING.includes(item.training)) problems.push(`${at} training is ${JSON.stringify(item.training)}; it is one of ${TRAINING.join(", ")}.`);
+      if (item.confirmed !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(String(item.confirmed))) problems.push(`${at} confirmed is ${JSON.stringify(item.confirmed)}; it is a date, YYYY-MM-DD.`);
+      const extra = Object.keys(item).filter((k) => !READER_KEYS.ai.includes(k));
+      if (extra.length) problems.push(`${at} has key(s) a reader does not take: ${extra.join(", ")}.`);
+      readers.push({ kind: "ai", ai, name: nonEmpty(item.name) ? item.name.trim() : null, model: nonEmpty(item.model) ? item.model.trim() : null, terms: TERMS.includes(item.terms) ? item.terms : null, training: TRAINING.includes(item.training) ? item.training : null, confirmed: item.confirmed ? String(item.confirmed) : null });
+      return;
+    }
+    if (item.local !== undefined) {
+      if (!nonEmpty(String(item.local ?? ""))) { problems.push(`${at} local is empty; name the model, or write any.`); return; }
+      const extra = Object.keys(item).filter((k) => !READER_KEYS.local.includes(k));
+      if (extra.length) problems.push(`${at} has key(s) a local reader does not take: ${extra.join(", ")}.`);
+      const model = String(item.local).trim();
+      readers.push({ kind: "local", model: model.toLowerCase() === "any" ? null : model, on: nonEmpty(item.on) ? item.on.trim() : null });
+      return;
+    }
+    problems.push(`${at} names no reader. Write ai: <${PLATFORM_KEYS.join(" | ")}> or local: <model or any>.`);
+  });
+  if (readers.some((r) => r.kind === "none") && readers.length > 1) problems.push(`${where} says none and also names a reader. None means no AI reads it; it stands alone.`);
+  if (FALSIFY() === "accept-any") return { readers, problems: [] };
+  return { readers, problems };
+}
+
+// One reader as the sentence the owner reads. States the fact, never a promise.
+export function describeReader(r) {
+  if (r.kind === "none") return "no AI; only you, on your own devices";
+  if (r.kind === "local") return `a model on your own devices${r.model ? ` (${r.model})` : ""}${r.on ? `: ${r.on}` : ""}`;
+  const company = COMPANY[r.ai];
+  const app = r.ai === "other" ? r.name ?? "an AI you named at setup" : APP[r.ai];
+  const who = company ? `${company} through ${app}${r.model ? ` (${r.model})` : ""}` : `${app}${r.model ? ` (${r.model})` : ""}`;
+  const parts = [who];
+  if (r.terms) parts.push(TERMS_WORDS[r.terms]);
+  if (r.training === "off") parts.push(`training off${r.confirmed ? `, confirmed ${r.confirmed}` : ""}`);
+  else if (r.training === "on") parts.push("training on");
+  else parts.push("training not confirmed off");
+  return parts.join(", ");
+}
+
+export function describeReaders(readers, { isPublic = false } = {}) {
+  if (isPublic) return "anyone; it is public";
+  if (readers === null) return "not stated; whatever AI opens this record reads what it opens";
+  return readers.map(describeReader).join("; ");
+}
+
+// Which AI is calling. An MCP client names itself on initialize (clientInfo.name); $EVDA_READER
+// overrides it, and is how a local model's client says it is local. Unknown is { ai: null }.
+export function callerFrom({ clientName = null, env = process.env } = {}) {
+  const stated = String(env.EVDA_READER ?? "").trim().toLowerCase();
+  if (stated === "local") return { ai: null, local: true, label: "a model on this device" };
+  if (stated && PLATFORM_KEYS.includes(stated)) return { ai: stated, local: false, label: APP[stated] ?? stated };
+  const n = String(clientName ?? "").toLowerCase();
+  const ai = /claude|anthropic/.test(n) ? "claude" : /codex|openai|chatgpt/.test(n) ? "chatgpt" : /gemini|google/.test(n) ? "gemini" : /cursor/.test(n) ? "cursor" : null;
+  return { ai, local: false, label: ai ? APP[ai] : clientName ? `a client that calls itself ${clientName}` : "an AI that did not say which it is" };
+}
+
+// Everything a run of access checks needs, read once: the circles and evda.json's reader.
+export function readContext(evda) {
+  let circles = [];
+  try { circles = readCircles(evda) ?? []; } catch { circles = []; }
+  const record = parseReaders(evda.manifest?.[READ_BY], "evda.json read_by");
+  return { evda, circles, record };
+}
+
+// The reader answer for one file: whose read_by applies, and what it says.
+export function readersFor(ctx, abs) {
+  const homes = homesOf(ctx.evda, ctx.circles, abs);
+  const home = homes.length === 1 ? ctx.circles.find((c) => c.name === homes[0]) : null;
+  if (home?.manifest?.public === true) return { readers: null, source: `circle ${home.name}`, circle: home.name, isPublic: true };
+  if (home && home.manifest?.[READ_BY] !== undefined) {
+    const own = parseReaders(home.manifest[READ_BY], `circle ${home.name} read_by`);
+    return { readers: own.problems.length ? [{ kind: "none" }] : own.readers, source: `circle ${home.name}`, circle: home.name, isPublic: false, broken: own.problems.length > 0 };
+  }
+  if (ctx.record.readers !== null) return { readers: ctx.record.problems.length ? [{ kind: "none" }] : ctx.record.readers, source: "evda.json", circle: home?.name ?? null, isPublic: false, broken: ctx.record.problems.length > 0 };
+  return { readers: null, source: null, circle: home?.name ?? null, isPublic: false };
+}
+
+export function frontOf(abs) {
+  if (!/\.md$/i.test(abs)) return null;
+  try { return frontmatterOf(readFileSync(abs, "utf8")); } catch { return null; }
+}
+
+export const isSealedFile = (abs) => sealedFront(frontOf(abs));
+
+// The text an AI may be shown of a file it may read: every sealed section replaced by one line.
+export function aiView(text) {
+  return withoutSealed(text, { placeholder: SEALED_PLACEHOLDER });
+}
+
+export const isNotedFile = (abs) => FALSIFY() !== "noted-readable" && frontOf(abs)?.[NOTED] === true;
+
+// May this caller read this file? { ok, why, kind } where kind is "noted" or "reader" on a refusal.
+// A reader that is broken (a read_by doctor fails) refuses, because a boundary nobody can read is
+// not one to guess at.
+export function mayRead(ctx, abs, caller) {
+  const rel = relative(ctx.evda.dir, abs).split(sep).join("/");
+  // Sealed before noted: an entry that is both is refused as the stronger, and no caller is exempt.
+  if (isSealedFile(abs)) return { ok: false, kind: "sealed", path: rel, why: `${rel} is sealed: only its owner opens it, on their own devices. No AI reads it, and no tool releases it.` };
+  if (isNotedFile(abs)) return { ok: false, kind: "noted", path: rel, why: `${rel} is just noted. No AI reads it until its owner says it can; they can open it themselves, or say you can read it now.` };
+  if (FALSIFY() === "ignore-reader") return { ok: true };
+  const r = readersFor(ctx, abs);
+  if (r.isPublic || r.readers === null) return { ok: true };
+  const where = r.source === "evda.json" ? "this record" : `the ${r.circle} circle`;
+  const said = describeReaders(r.readers);
+  if (r.broken) return { ok: false, kind: "reader", path: rel, why: `${rel} is in ${where}, whose read_by does not parse, so no AI reads it until doctor passes on it.` };
+  const allowed = r.readers.some((x) => (x.kind === "local" && caller.local) || (x.kind === "ai" && (x.ai === caller.ai || (x.ai === "other" && caller.ai === null && !caller.local))));
+  if (allowed) return { ok: true };
+  return { ok: false, kind: "reader", path: rel, why: `${rel} is in ${where}, which its owner set to be read by ${said}. You are ${caller.label}, so it is theirs to open, or to change who reads it.` };
+}
+
+// A plain sentence for everything that was held back from one tool answer.
+// A sealed refusal is never named; `sealed` true (or any sealed refusal) adds SEALED_HELD, which is the
+// same sentence whatever was asked.
+export function heldBack(refusals, { sealed = false } = {}) {
+  const anySealed = sealed || refusals.some((r) => r.kind === "sealed");
+  refusals = refusals.filter((r) => r.kind !== "sealed");
+  if (!refusals.length) return anySealed ? SEALED_HELD : "";
+  const noted = refusals.filter((r) => r.kind === "noted");
+  const reader = refusals.filter((r) => r.kind === "reader");
+  const show = (xs) => xs.slice(0, 10).map((r) => r.path).join(", ") + (xs.length > 10 ? `, and ${xs.length - 10} more` : "");
+  const lines = [];
+  if (noted.length) lines.push(`Not shown: ${noted.length} just-noted entr${noted.length === 1 ? "y" : "ies"} (${show(noted)}). No AI reads these until the owner says it can; they can open them, or tell you that you can read one now.`);
+  if (reader.length) lines.push(`Not shown: ${reader.length} file(s) in parts of the record set to be read by a different AI (${show(reader)}). ${reader[0].why}`);
+  if (anySealed) lines.push(SEALED_HELD);
+  return lines.join("\n");
+}
+
+// The captures folder, where a noted entry lands.
+function capturesDir(evda) {
+  const r = resolveRole(evda, "record/captures");
+  if (r.mapped) return r;
+  const d = resolveRole(evda, "record/daily");
+  if (!d.mapped) throw new EvdaError('REFUSED: this record maps neither "record/captures" nor "record/daily", so there is nowhere to note it. Nothing was written.', { code: "NO_ROLE", exit: 2 });
+  return d;
+}
+
+const pad = (n) => String(n).padStart(2, "0");
+const localDate = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+const localTime = (d) => `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+
+// Write the owner's words as a just-noted capture. Its filename carries a time and nothing of the
+// words, so a listing discloses nothing. Returns { path } relative to the record.
+export function note(evda, words, { now = new Date() } = {}) {
+  const dir = capturesDir(evda);
+  mkdirSync(dir.abs, { recursive: true });
+  const stamp = `${localDate(now)}-${pad(now.getHours())}${pad(now.getMinutes())}`;
+  let abs = join(dir.abs, `${stamp}-noted.md`);
+  for (let n = 2; existsSync(abs); n++) abs = join(dir.abs, `${stamp}-noted-${n}.md`);
+  writeFileSync(abs, ["---", `${NOTED}: true`, `date: ${localDate(now)}`, `time: "${localTime(now)}"`, "---", "", words.replace(/\n+$/, ""), ""].join("\n"));
+  return { path: relative(evda.dir, abs).split(sep).join("/") };
+}
+
+// Clear the flag on one noted entry, on the owner's yes. Changes one frontmatter line and adds the
+// date it was released; the words are never touched.
+export function releaseNote(evda, path, { now = new Date() } = {}) {
+  if (typeof path !== "string" || path.trim() === "") throw new EvdaError('REFUSED: name the noted entry to release, as a path in the record. Nothing was changed.', { code: "BAD_ARGUMENT", exit: 2 });
+  const outside = () => new EvdaError(`REFUSED: ${path} is outside the record. Nothing was changed.`, { code: "OUTSIDE", exit: 2 });
+  const named = resolve(evda.dir, path.trim());
+  if (!existsSync(named)) {
+    if (!named.startsWith(evda.dir + sep)) throw outside();
+    throw new EvdaError(`REFUSED: nothing is at ${path}. Nothing was changed.`, { code: "MISSING", exit: 2 });
+  }
+  // Inside is decided on real paths: a record reached through a symlink (the owner's shell path to
+  // it) is the same record, and a symlink inside the record that leads out of it is outside
+  // (HQ-1406: an absolute path through a link to the record was refused as outside).
+  const root = realpathSync(evda.dir);
+  const abs = realpathSync(named);
+  if (!abs.startsWith(root + sep)) throw outside();
+  if (!statSync(abs).isFile()) throw new EvdaError(`REFUSED: nothing is at ${path}. Nothing was changed.`, { code: "MISSING", exit: 2 });
+  const text = readFileSync(abs, "utf8");
+  const lines = text.split("\n");
+  const end = lines[0] === "---" ? lines.indexOf("---", 1) : -1;
+  const at = end === -1 ? -1 : lines.slice(1, end).findIndex(notedLine) + 1;
+  if (at <= 0) throw new EvdaError(`REFUSED: ${path} is not just noted (its frontmatter has no "noted: true"). Nothing was changed.`, { code: "NOT_NOTED", exit: 2 });
+  lines.splice(at, 1, `released: ${localDate(now)}`);
+  writeFileSync(abs, lines.join("\n"));
+  return { path: relative(root, abs).split(sep).join("/") };
+}
+
+// The top-level frontmatter line that makes an entry noted, spelled any way the frontmatter reader
+// reads as `noted: true` (True, a trailing comment, a quoted key), so release clears every entry
+// the rest of the package holds back (HQ-1406: `noted: True` was held back and could not be released).
+function notedLine(l) {
+  if (/^\s/.test(l)) return false;
+  try {
+    const one = parseYaml(l);
+    return one !== null && typeof one === "object" && Object.keys(one).length === 1 && one[NOTED] === true;
+  } catch {
+    return false;
+  }
+}
+
+// Every noted entry in the record's markdown, for doctor and for the owner's own search.
+export function notedFiles(evda, files) {
+  return files.filter((abs) => frontOf(abs)?.[NOTED] === true);
+}
+
+// The owner's own search, on this device, with no model: every markdown file under the record,
+// noted and sealed entries included and marked (a line in a sealed section is marked sealed too).
+// The MCP's evda_search is the AI's and leaves them out.
+export function ownerSearch(evda, query, { files }) {
+  const needle = query.toLowerCase();
+  const out = [];
+  for (const abs of files) {
+    let text;
+    try { text = readFileSync(abs, "utf8"); } catch { continue; }
+    const front = frontmatterOf(text);
+    const noted = front?.[NOTED] === true;
+    const sealedFile = sealedFront(front);
+    const sections = sealedSections(text);
+    text.split("\n").forEach((line, i) => {
+      if (!line.toLowerCase().includes(needle)) return;
+      const hit = { path: relative(evda.dir, abs).split(sep).join("/"), line: i + 1, text: line, noted };
+      if (sealedFile || sections.some((s) => i >= s.start && i <= s.end)) hit.sealed = true;
+      out.push(hit);
+    });
+  }
+  return out;
+}
+
+export { mdFiles, PLATFORMS };

package/lib/records.mjs

@@ -0,0 +1,52 @@
+// Records inside records (Spec 07 section 2, "A record inside a record", HQ-1371).
+//
+// An evda.json anywhere below a record's root starts a sub-record: its own four roles resolved from
+// its own root, its own circles, its own holders, with no depth limit. This module finds them. Only
+// the OUTERMOST sub-records of a record are its own; a sub-record's sub-records are found when the
+// sub-record itself is read, which is how doctor walks every level.
+//
+// The boundary is opt-in for circles (lib/manifest.mjs `isBounded`): a record that declares
+// "subrecords": "bounded" stops its circles, its coverage, its scan prefixes and its released set
+// at every sub-record, and holds a sub-record's files only through a circle it mounts. A record that
+// does not declare it keeps covering them as its own, which is what it synced before HQ-1371.
+//
+// The walk is the sync walk (lib/sync-rules.mjs), so a sub-record under an excluded path is not a
+// sub-record of this record: nothing of it syncs from here either way.
+
+import { dirname } from "node:path";
+import { excluder, walk } from "./sync-rules.mjs";
+import { isBounded } from "./manifest.mjs";
+
+const MANIFEST = "evda.json";
+
+// EVDA_SUBRECORDS_FALSIFY=<mode,...>, for the tests: no-boundary makes a bounded record's circles
+// cover its sub-records anyway; blind finds no sub-record at all, so doctor walks no level below.
+export const FALSIFY_MODES = ["no-boundary", "blind"];
+const falsified = (mode) => (process.env.EVDA_SUBRECORDS_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+
+// The outermost sub-record roots under `dir`, relative, sorted. `exclude` is the plan's excluder.
+export function subRecords(dir, { exclude = excluder() } = {}) {
+  const found = [];
+  if (falsified("blind")) return found;
+  for (const e of walk(dir, { exclude })) {
+    if (e.kind !== "file") continue;
+    if (!(e.rel === MANIFEST || e.rel.endsWith(`/${MANIFEST}`))) continue;
+    if (e.rel === MANIFEST) continue;
+    found.push(dirname(e.rel));
+  }
+  found.sort();
+  return found.filter((r) => !found.some((o) => o !== r && r.startsWith(`${o}/`)));
+}
+
+const cache = new WeakMap();
+
+// The sub-record roots the record's circles stop at: every outermost sub-record when the record is
+// bounded, none when it is not. Cached per open record, since coverage asks once per file.
+export function boundaries(evda) {
+  if (!isBounded(evda.manifest) || falsified("no-boundary")) return [];
+  if (!cache.has(evda)) cache.set(evda, subRecords(evda.dir));
+  return cache.get(evda);
+}
+
+// Whether a relative path is inside one of `roots`.
+export const insideAny = (roots, rel) => roots.some((r) => rel === r || rel.startsWith(`${r}/`));