create-evda 0.1.5 → 0.1.6

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}/`));

package/lib/references.mjs

@@ -34,6 +34,9 @@
 
 import { EvdaError } from "./errors.mjs";
 import { parseYaml } from "./yaml.mjs";
+import { secretShape } from "./secret-shape.mjs";
+
+export { secretShape };
 
 export const SCHEMES = ["contacts", "1password", "url", "evda"];
 export const REFERENCE_KEYS = ["ref", "label", "resolved"];
@@ -130,58 +133,9 @@ function bad(msg) {
   return new EvdaError(msg, { code: "BAD_REFERENCE", exit: 1 });
 }
 
-// Secret detection. A key named like a secret, or a value shaped like one, refuses the write.
-// The shapes are the obvious ones: a private key block, a JWT, the prefixes the common services
-// stamp on their tokens, a bearer header, a URL carrying a password or a credential in its query,
-// and as a last net a long mixed-case high-entropy token that is not a UUID.
+// Secret detection is lib/secret-shape.mjs, shared with the prompt hook; a key named like a secret
+// is refused here too.
 const SECRET_KEY = /(pass(word|wd|phrase)?|secret|token|api[-_ ]?key|access[-_ ]?key|private[-_ ]?key|credential|bearer|cookie|session[-_ ]?id|otp|pin[-_ ]?code|client[-_ ]?secret)/i;
-const SECRET_PARAM = /^(key|token|access_token|api_key|apikey|auth|password|secret|sig|signature|session|x-amz-signature|x-amz-credential)$/i;
-const SECRET_VALUE = [
-  [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, "a private key block"],
-  [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/, "a JWT"],
-  [/\b(sk|pk|rk)-[A-Za-z0-9_-]{16,}\b/, "an API key (sk-...)"],
-  [/\b(sk|pk|rk)_(live|test)_[A-Za-z0-9]{8,}\b/, "an API key (sk_live_...)"],
-  [/\bgh[pousr]_[A-Za-z0-9]{20,}\b/, "a GitHub token"],
-  [/\bglpat-[A-Za-z0-9_-]{20,}\b/, "a GitLab token"],
-  [/\bxox[abprs]-[A-Za-z0-9-]{10,}\b/, "a Slack token"],
-  [/\bAKIA[0-9A-Z]{16}\b/, "an AWS access key id"],
-  [/\bAIza[0-9A-Za-z_-]{35}\b/, "a Google API key"],
-  [/\bBearer\s+[A-Za-z0-9._~+/-]{16,}=*/i, "a bearer token"],
-];
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-function entropy(s) {
-  const counts = new Map();
-  for (const c of s) counts.set(c, (counts.get(c) ?? 0) + 1);
-  let h = 0;
-  for (const n of counts.values()) {
-    const p = n / s.length;
-    h -= p * Math.log2(p);
-  }
-  return h;
-}
-
-// Why a string looks like a secret, or null.
-export function secretShape(value) {
-  if (typeof value !== "string") return null;
-  for (const [re, what] of SECRET_VALUE) if (re.test(value)) return what;
-  const m = /^(?:url:)?([a-z][a-z0-9+.-]*:\/\/[^\s]+)$/i.exec(value);
-  if (m) {
-    let u = null;
-    try { u = new URL(m[1]); } catch { u = null; }
-    if (u) {
-      if (u.password !== "") return "a password in the URL";
-      for (const k of u.searchParams.keys()) if (SECRET_PARAM.test(k)) return `a credential in the URL query (${k})`;
-    }
-  }
-  for (const tok of value.split(/[\s"'<>]+/)) {
-    if (tok.length < 40 || UUID.test(tok)) continue;
-    if (!/[A-Z]/.test(tok) || !/[a-z]/.test(tok) || !/\d/.test(tok)) continue;
-    if (!/^[A-Za-z0-9+/=_-]+$/.test(tok)) continue;
-    if (entropy(tok) >= 4.5) return "a long high-entropy token";
-  }
-  return null;
-}
 
 // Why a key name looks like it holds a secret, or null.
 export function secretKey(name) {

package/lib/render.mjs

@@ -0,0 +1,158 @@
+// Views rendered at publish (Spec 07 section 5, HQ-1351).
+//
+// One fact, stored once, as a typed entry placed by its subject. The public circle carries a
+// `render` member for each file the site reads, and the file is rendered on the way out from every
+// released entry whose frontmatter names the view:
+//
+//   ---
+//   kind: piece
+//   share: public        the mark, so the public circle's rule gathers it
+//   view: projects       which render member it feeds
+//   order: 3             its place in the rendered list; unique within the view
+//   id: proj_iris        the item's own id, repeated so a reader of the folder sees it
+//   title: Iris
+//   ---
+//   ```json
+//   { "id": "proj_iris", ... }     the item, exactly as the rendered file carries it
+//   ```
+//
+// A list view is the entries' items as one JSON list, sorted by `order`. An object view holds
+// exactly one entry and renders its item alone. The rendered bytes are deterministic (two-space
+// JSON, one trailing newline), so the same entries render to the same file on any device.
+//
+// Provenance (HQ-1367). An entry re-derived from its subject's own record says where from and when:
+//
+//   derived_from:        the record paths (a folder, a README) and shipped tickets (HQ-<n>) it was
+//     - "01_Projects/Evda/Iris - Universal Thinking Partner/README.md"
+//     - HQ-1351          derived from; a path must exist in the record
+//   derived_at: "2026-09-25"   when; an ISO date or date-time, never in the future
+//
+// Both or neither: an entry with only one is a problem, since a stranger's answer must trace to what
+// the record held. The fields live in the entry's frontmatter and never reach the rendered file.
+// `provenance` on each rendered entry reports them, with `changed`: the source files modified after
+// derived_at, which is a fact about files the publish pass reads to find what to re-derive.
+//
+// Everything that can go wrong is a problem the caller fails on, never a dropped entry: a view no
+// render member declares, a missing or repeated `order`, a body with no JSON block or one that does
+// not parse, an `id` in the frontmatter that is not the item's, an object view with two entries, a
+// render member that draws nothing. A publish with any problem refuses; doctor names each one.
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, resolve, sep } from "node:path";
+import { createHash } from "node:crypto";
+import { frontmatterOf, withoutSealed } from "./circles.mjs";
+
+// The frontmatter keys an entry uses to reach a view.
+export const VIEW = "view";
+export const ORDER = "order";
+export const DERIVED_FROM = "derived_from";
+export const DERIVED_AT = "derived_at";
+
+const TICKET = /^HQ-[1-9][0-9]*$/;
+const ISO = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})?)?$/;
+
+// The provenance an entry carries: { provenance } (null when it carries none) or { problem }.
+// `recordDir` resolves paths; `now` is injectable so a test can pin "the future".
+export function provenanceOf(front, recordDir, { now = new Date() } = {}) {
+  const from = front?.[DERIVED_FROM];
+  const at = front?.[DERIVED_AT];
+  if (from === undefined && at === undefined) return { provenance: null };
+  if (from === undefined) return { problem: `has ${DERIVED_AT} and no ${DERIVED_FROM}. A derived entry names what it was derived from.` };
+  if (at === undefined) return { problem: `has ${DERIVED_FROM} and no ${DERIVED_AT}. A derived entry says when it was derived.` };
+  if (!Array.isArray(from) || from.length === 0 || from.some((s) => typeof s !== "string" || s.trim() === "")) return { problem: `has ${DERIVED_FROM}: ${JSON.stringify(from)}; it is a non-empty list of record paths and HQ-<n> tickets.` };
+  const when = String(at);
+  if (!ISO.test(when) || Number.isNaN(Date.parse(when))) return { problem: `has ${DERIVED_AT}: ${JSON.stringify(at)}, which is not an ISO date.` };
+  const t = Date.parse(when);
+  if (t > now.getTime() + 24 * 3600 * 1000) return { problem: `has ${DERIVED_AT}: ${when}, which is in the future.` };
+  const root = resolve(recordDir);
+  const tickets = [];
+  const files = [];
+  for (const s of from) {
+    if (TICKET.test(s)) { tickets.push(s); continue; }
+    if (isAbsolute(s)) return { problem: `derives from ${JSON.stringify(s)}, an absolute path; a source is relative to the record root.` };
+    const abs = resolve(root, s);
+    if (abs !== root && !abs.startsWith(root + sep)) return { problem: `derives from ${JSON.stringify(s)}, which is outside the record.` };
+    if (!existsSync(abs)) return { problem: `derives from ${JSON.stringify(s)}, and nothing is there. A source the record does not hold cannot be traced to.` };
+    files.push({ path: s, abs });
+  }
+  // A date with no time is the end of that day: a source saved that afternoon was read for it.
+  const cutoff = /T/.test(when) ? t : t + 24 * 3600 * 1000;
+  const changed = files.filter((f) => { try { return statSync(f.abs).mtimeMs > cutoff; } catch { return false; } }).map((f) => f.path);
+  return { provenance: { from: [...from], at: when, tickets, files: files.map((f) => f.path), changed } };
+}
+
+const sha256Hex = (bytes) => createHash("sha256").update(bytes).digest("hex");
+
+// The item an entry holds: the first ```json fence in the body. { value } or { problem }.
+export function entryJson(text) {
+  const m = /^```json[ \t]*\r?\n([\s\S]*?)\r?\n```[ \t]*$/m.exec(text);
+  if (!m) return { problem: "has no ```json block. A view entry holds its item in one fenced JSON block." };
+  try {
+    return { value: JSON.parse(m[1]) };
+  } catch (e) {
+    return { problem: `its \`\`\`json block does not parse (${e.message}).` };
+  }
+}
+
+// Render the bytes of one view. Pure: the same entries render to the same bytes in any order.
+export function renderBytes(shape, items) {
+  const value = shape === "object" ? items[0] : items;
+  return Buffer.from(JSON.stringify(value, null, 2) + "\n", "utf8");
+}
+
+// Group the files released into a public circle (`gathered` is `released()`'s row for it, or any
+// object with byPath and byRule lists of { path, abs, member, circle? }) by the view each names,
+// and render every render member of the circle.
+//
+// Returns { views, loose, problems }:
+//   views     one per render member: { member, view, path, shape, entries: [{ path, abs, sha256,
+//             order, id, home }], bytes } with entries sorted by order; bytes is null when the
+//             view has a problem
+//   loose     the released files that name no view, unchanged, exported as themselves
+//   problems  [{ path, message }], each one a refusal
+export function renderViews(evda, circle, gathered) {
+  const renders = Object.entries(circle.members).filter(([, m]) => m.kind === "render").map(([member, m]) => ({ member, view: m.view, path: m.rel, shape: m.shape, entries: [], bytes: null }));
+  const byView = new Map(renders.map((r) => [r.view, r]));
+  const loose = [];
+  const problems = [];
+  const problem = (path, message) => problems.push({ path, message });
+
+  for (const f of [...gathered.byPath, ...gathered.byRule]) {
+    let text;
+    try { text = readFileSync(f.abs, "utf8"); } catch (e) { problem(f.path, `could not be read (${e.message}).`); continue; }
+    // A sealed section (HQ-1220) is never rendered, whatever fence it holds.
+    text = withoutSealed(text).text;
+    const front = frontmatterOf(text);
+    const view = front?.[VIEW];
+    if (view === undefined || view === null || view === "") { loose.push(f); continue; }
+    if (typeof view !== "string") { problem(f.path, `has ${VIEW}: ${JSON.stringify(view)}, which is not a view name.`); continue; }
+    const target = byView.get(view);
+    if (!target) { problem(f.path, `names view "${view}", and no render member of circle "${circle.name}" declares it (declared: ${renders.map((r) => r.view).join(", ") || "none"}). A released entry that reaches nowhere is a silent drop.`); continue; }
+    const order = front[ORDER];
+    if (!Number.isInteger(order)) { problem(f.path, `has ${ORDER}: ${JSON.stringify(order)}; a view entry says where it goes with an integer.`); continue; }
+    const json = entryJson(text);
+    if (json.problem) { problem(f.path, json.problem); continue; }
+    const item = json.value;
+    const itemId = item && typeof item === "object" && !Array.isArray(item) ? item.id : undefined;
+    if (front.id !== undefined && itemId !== undefined && String(front.id) !== String(itemId)) { problem(f.path, `says id: ${JSON.stringify(front.id)} in its frontmatter and its item says "id": ${JSON.stringify(itemId)}. One id per fact.`); continue; }
+    const prov = provenanceOf(front, evda.dir);
+    if (prov.problem) { problem(f.path, prov.problem); continue; }
+    target.entries.push({ path: f.path, abs: f.abs, sha256: sha256Hex(Buffer.from(text, "utf8")), order, id: front.id ?? itemId ?? null, home: f.circle ?? circle.name, provenance: prov.provenance, item });
+  }
+
+  for (const r of renders) {
+    r.entries.sort((a, b) => a.order - b.order || a.path.localeCompare(b.path));
+    const seen = new Map();
+    for (const e of r.entries) {
+      if (seen.has(e.order)) problem(e.path, `has ${ORDER}: ${e.order} in view "${r.view}", and so does ${seen.get(e.order)}. One place per entry.`);
+      seen.set(e.order, e.path);
+    }
+    if (r.entries.length === 0) problem(r.path, `is rendered by member "${r.member}" from view "${r.view}", and no released entry names that view. A view that draws nothing is not published.`);
+    if (r.shape === "object" && r.entries.length > 1) problem(r.path, `is an object view ("${r.view}") and ${r.entries.length} entries name it: ${r.entries.map((e) => e.path).join(", ")}. An object view holds exactly one.`);
+    const mine = problems.some((p) => p.path === r.path || r.entries.some((e) => e.path === p.path));
+    if (!mine) r.bytes = renderBytes(r.shape, r.entries.map((e) => e.item));
+    for (const e of r.entries) delete e.item;
+  }
+
+  return { views: renders, loose, problems };
+}