create-evda 0.1.4 → 0.1.6

package/lib/circles.mjs

@@ -9,26 +9,69 @@
 //
 //   members   where the circle's bytes live, relative to the record root. The mapping principle
 //             one level down: a record adopts a circle by declaring where its members already are,
-//             and nothing moves. A member is { path } (bytes in this record) or { table, where }
+//             and nothing moves. A path member covers the file it names or everything under the
+//             directory it names, and a member at the record root ("" or ".") covers everything.
+//             PRECEDENCE (HQ-1364): a file's home is the circle whose covering member path is
+//             LONGEST, so a circle declared at the root is the private default and every other
+//             circle carves its subtree out of it; `Health & Energy/Therapy` is therapy, not health,
+//             not core, whatever order the manifests are read in. Two circles whose members cover
+//             one file at the same length is a file with two access answers, and doctor fails it.
+//             `coverage()` here, `circleForPath` in filechanges.mjs and the scan's `scanPrefixes`
+//             all resolve this one way. A member is { path } (bytes in this record), { table, where }
 //             (rows on a host, selected by equality; allowed only in a public circle, because a
-//             private circle's host may not read it).
+//             private circle's host may not read it), or { where } alone (files in this record
+//             whose frontmatter matches, wherever they live: a standing release rule, on any
+//             circle). The mark an owner writes on one entry is `share: <circle>` or
+//             `share: [<circle>, ...]` in its frontmatter, and the circle's rule for it is
+//             `where: { share: <its name> }`; a where value matches a scalar or a list holding it.
+//             The fourth member is { render: { view, path, shape? } }, on a public circle only
+//             (HQ-1351, Spec 07 section 5): a file that does not exist in the record and is
+//             RENDERED at publish from every released entry whose frontmatter says `view: <view>`,
+//             sorted by `order`, written into the export at `path`. `shape` is "list" (the default,
+//             one JSON list of the entries' items) or "object" (exactly one entry, its item alone).
+//             The rendering is lib/render.mjs. A rendered path is never also a path member, and a
+//             released entry that names a view no render member declares refuses the publish.
+//   mount     on a circle held FROM ANOTHER HOLDER (HQ-835): `{ holder: <their record id>, path:
+//             <where their files land here> }`. The wire carries each file at its address in the
+//             home holder's tree; on this device it lands under `path` (Spec 07 section 3, "at its
+//             address under a mount, never at a path in their own tree"). `path` must be a path
+//             member of the circle, so the scan and the fold agree on where the mount is.
+//   frozen    on a circle held from another holder whose grant was revoked (HQ-835): `{ since:
+//             <date>, by: revocation }`. The copy stays readable and stops updating: it is neither
+//             scanned for edits nor minted into, and nothing under its mount is deleted (Spec 00
+//             #37). Written by `lib/declarations.mjs` when the owner's notice arrives; lifted by a
+//             re-declaration.
+//   release   on the circle a file lives in: "never", or a list of circle names it may be released
+//             into. Default never, so a new circle cannot leak by a stray mark. Spec 07 section 3,
+//             ruled 2026-09-22 (HQ-1351): every entry has exactly one HOME circle by path; it may be
+//             released into any number of other circles by mark or by rule, and each release is
+//             the same file sealed once more at sync, derived from the one copy. Public is the
+//             release with no key. Routing by home circle is unchanged; released circles are added.
 //   policy    a list of rules (Spec 07, section 6), each one a test: what the rule is in the owner's
 //             words, the correction that made it (verbatim), an example that passes, one that fails,
 //             a check written so it could come back false, and a status. A rule is never edited in
 //             place; a revision is a new rule with `revisedBy` written on the old one. The plain
 //             sentence saying who may read the circle and why goes in the substrate's `description`.
 //
+// A circle's id is opaque and random (Spec 08, ruled 2026-09-17): `id: ecos/<opaque>` and
+// `namespace: <opaque>.eco`, minted once when the circle is created and never derived from its
+// name. The name is the directory under the circles role and stays on the owner's devices; the id
+// is what travels (a Change's `eco`, an export's manifest), so a name there would be the
+// disclosure. An id still derived from the name is read, with a warning to re-mint it.
+//
 // `public: true` is the whole of what makes a circle public: the reader takes the same path it
-// would for any circle and needs no key. Reading an ENCRYPTED circle is not built; a private circle
-// is declared, validated for shape, and never read.
+// would for any circle and needs no key. This module declares and validates circles; it reads no
+// private circle's bytes. Sealing a private circle for sync is `lib/filechanges.mjs`.
 //
 // `circle.json` is the manifest this package wrote before circles converged on ecos (2026-09-16).
 // It is still read, with a warning, so a record written against it keeps working until it is
 // rewritten as `eco.yaml`. Nothing writes it any more.
 
 import { existsSync, readFileSync, readdirSync, statSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, resolve, sep, isAbsolute } from "node:path";
+import { randomBytes } from "node:crypto";
+import { join, resolve, relative, sep, isAbsolute } from "node:path";
 import { resolveRole } from "./roles.mjs";
+import { boundaries, insideAny } from "./records.mjs";
 import { parseYaml, toYaml } from "./yaml.mjs";
 import { EvdaError } from "./errors.mjs";
 
@@ -38,14 +81,59 @@ export const ECO_MANIFEST = "eco.yaml";
 export const LEGACY_MANIFEST = "circle.json";
 export const KNOWN_ECO_KEYS = [
   "id", "kind", "schemaVersion", "sourceLayer", "namespace", "title", "type", "description",
-  "ecoVersion", "layer", "public", "maintainers", "metadata", "members", "policy",
+  "ecoVersion", "layer", "public", "maintainers", "metadata", "members", "policy", "release", "mount",
+  "frozen", "read_by",
 ];
+// The frontmatter key an owner writes to release one entry: a circle name, or a list of them.
+export const MARK = "share";
+// The frontmatter flag on an entry that is just noted (HQ-1374): kept on the owner's devices,
+// searchable by them, read by no AI until they release it. Not a circle and not a mark, and a mark
+// never releases a noted entry anywhere. lib/readers.mjs holds the rest of what it means.
+export const NOTED = "noted";
+// The frontmatter flag on an entry that is sealed (HQ-1220): nothing but the owner's own devices
+// opens it, ever. Stronger than noted: no AI reads it whoever it says it is, no tool releases it,
+// no mark and no public path publishes it. A section is sealed by a fenced block whose info string
+// is `sealed` (withoutSealed below). lib/readers.mjs holds what each reader does with it.
+export const SEALED = "sealed";
+// Carrying the two flags (HQ-1414). Every command that copies or moves record content somewhere
+// else carries `noted` and `sealed` with it, so a copy is never more readable than what it copied.
+// The paths are COPY_PATHS; test/carry.test.mjs holds one canary test per path and fails when a new
+// file-writing module appears that it has not classified. EVDA_CARRY_FALSIFY=<path>:<flag>,... makes
+// that one path drop that one flag and nothing else, so each test shows the path is what holds.
+export const COPY_PATHS = ["organize", "gather", "gather-apply", "migrate-people", "publish", "sync"];
+export const carries = (path, flag) => !String(process.env.EVDA_CARRY_FALSIFY ?? "").split(",").map((m) => m.trim()).includes(`${path}:${flag}`);
+// Which flag, if any, holds an entry back when `path` copies it: "sealed" first (the stronger),
+// then "noted", else null.
+export function heldBy(front, path) {
+  if (carries(path, SEALED) && sealedFront(front)) return SEALED;
+  if (carries(path, NOTED) && front?.[NOTED] === true) return NOTED;
+  return null;
+}
+// The key on a circle (or on evda.json, for the whole record) that says which AI reads it. Validated
+// and printed by lib/readers.mjs; here it is only a key the manifest may carry.
+export const READ_BY = "read_by";
+// The shapes a render member may take: a list of every entry's item, or one entry's item alone.
+export const RENDER_SHAPES = ["list", "object"];
+// A circle's release: "never", or the names of the circles its files may be released into.
+export const isRelease = (v) => v === "never" || (Array.isArray(v) && v.length > 0 && v.every((n) => typeof n === "string" && n.trim() !== ""));
 
 export const circlesDir = (evda) => resolveRole(evda, "circles");
 export const ecoManifestPath = (dir) => join(dir, ECO_MANIFEST);
 export const ecoId = (name) => `ecos/${name}`;
 export const ecoNamespace = (name) => `${name}.eco`;
 
+// A fresh opaque circle id: `c` and 32 hex characters (128 random bits). Never a function of the
+// name, so two circles called "therapy" in two records share nothing a reader of the id could use.
+export const OPAQUE_ID = /^c[0-9a-f]{32}$/;
+export const mintCircleId = () => `c${randomBytes(16).toString("hex")}`;
+
+// The opaque part of an eco manifest's id, when its id and namespace agree on one. null otherwise.
+export function opaqueIdOf(manifest) {
+  const id = typeof manifest?.id === "string" && manifest.id.startsWith("ecos/") ? manifest.id.slice("ecos/".length) : null;
+  if (id === null || id === "" || id.includes("/")) return null;
+  return manifest.namespace === ecoNamespace(id) ? id : null;
+}
+
 // Every subdirectory of the circles role, whether or not it carries a manifest. Dotfiles are not
 // circles. A file at the top level of the role is ignored (the scaffold's README lives there).
 export function circleDirs(evda) {
@@ -151,7 +239,7 @@ export function validateCircle(evda, dir) {
   const problems = [];
   const fail = (m) => problems.push({ level: "fail", message: m });
   const warn = (m) => problems.push({ level: "warn", message: m });
-  const out = { name: dir.name, rel: dir.rel, abs: dir.abs, manifest: null, source: null, problems, readable: false, members: {}, policy: null };
+  const out = { name: dir.name, rel: dir.rel, abs: dir.abs, id: null, manifest: null, source: null, problems, readable: false, members: {}, policy: null, release: "never", mount: null, frozen: null };
 
   const { manifest: m, source } = readCircleManifest(dir);
   out.source = source;
@@ -169,12 +257,23 @@ export function validateCircle(evda, dir) {
 
   // The substrate's required fields, so the substrate's own reader can open this manifest.
   if (m.kind !== "eco") fail(`${rel}: "kind" must be "eco", got ${JSON.stringify(m.kind)}. A circle is an eco.`);
-  if (m.id !== ecoId(dir.name)) fail(`${rel}: "id" must be "${ecoId(dir.name)}" (the directory names the eco), got ${JSON.stringify(m.id)}.`);
-  if (m.namespace !== ecoNamespace(dir.name)) fail(`${rel}: "namespace" must be "${ecoNamespace(dir.name)}", got ${JSON.stringify(m.namespace)}.`);
+  const opaque = opaqueIdOf(m);
+  if (typeof m.id !== "string" || !m.id.startsWith("ecos/")) fail(`${rel}: "id" must be "ecos/<id>", got ${JSON.stringify(m.id)}.`);
+  else if (opaque === null) fail(`${rel}: "id" and "namespace" must name the same eco ("${m.id}" wants namespace "${ecoNamespace(m.id.slice("ecos/".length))}"), got ${JSON.stringify(m.namespace)}.`);
+  else if (opaque === dir.name) warn(`${rel}: "id" is derived from the circle's name, and the id is what leaves the device. Re-mint it as a random id (Spec 08, ruled 2026-09-17).`);
+  else if (!OPAQUE_ID.test(opaque)) warn(`${rel}: "id" ${JSON.stringify(m.id)} is not a minted opaque id (c and 32 hex). If it says anything about the circle, it says it wherever the id travels.`);
+  out.id = opaque;
   if (!nonEmpty(m.schemaVersion) && typeof m.schemaVersion !== "number") fail(`${rel}: "schemaVersion" is missing.`);
   if (!nonEmpty(m.title)) fail(`${rel}: "title" is missing.`);
 
   if (typeof m.public !== "boolean") fail(`${rel}: "public" must be true or false. A circle that does not say who may read it cannot be read.`);
+  // release: whether a file here may be released into the public circle by the mark. Read only on
+  // a keyed circle; the public circle releases nothing, it gathers.
+  if (m.release !== undefined) {
+    if (!isRelease(m.release)) fail(`${rel}: "release" must be "never" or a non-empty list of circle names, got ${JSON.stringify(m.release)}. It says where a file living here may be released to.`);
+    else if (m.public === true) warn(`${rel}: "release" is set on a public circle. Everyone already reads it, so there is nowhere further to release to. Ignored.`);
+    else out.release = m.release;
+  }
   if (!Array.isArray(m.maintainers) || m.maintainers.length === 0) {
     fail(`${rel}: "maintainers" must be a non-empty list. A circle nobody holds has no one who may grant it.`);
   } else {
@@ -192,13 +291,64 @@ export function validateCircle(evda, dir) {
       if (!isObject(member)) { fail(`${rel}: member "${name}" is not a mapping.`); continue; }
       const hasPath = typeof member.path === "string";
       const hasTable = typeof member.table === "string";
-      if (hasPath === hasTable) { fail(`${rel}: member "${name}" must have exactly one of "path" or "table".`); continue; }
+      const hasWhere = member.where !== undefined;
+      const hasRender = member.render !== undefined;
+      if (hasPath && hasTable) { fail(`${rel}: member "${name}" must have exactly one of "path" or "table".`); continue; }
+      if (hasRender) {
+        // A render member: a file the export carries that the record does not hold, rendered at
+        // publish from the released entries that name its view (HQ-1351). Public only, because a
+        // view is rendered on the way out and only the public circle is published.
+        if (hasPath || hasTable || hasWhere) { fail(`${rel}: member "${name}" has "render" and also path, table or where. A render member stands alone.`); continue; }
+        if (m.public !== true) { fail(`${rel}: member "${name}" is a render, and this circle is not public. A view is rendered at publish, and only the public circle is published.`); continue; }
+        const r = member.render;
+        if (!isObject(r) || !nonEmpty(r.view) || !nonEmpty(r.path)) { fail(`${rel}: member "${name}" render must be { view: <name>, path: <record path>, shape?: list | object }, got ${JSON.stringify(r)}.`); continue; }
+        const shape = r.shape ?? "list";
+        if (!RENDER_SHAPES.includes(shape)) { fail(`${rel}: member "${name}" render shape must be one of ${RENDER_SHAPES.join(" | ")}, got ${JSON.stringify(r.shape)}.`); continue; }
+        if (isAbsolute(r.path)) { fail(`${rel}: member "${name}" render path must be relative to the record root, got ${JSON.stringify(r.path)}.`); continue; }
+        const path = r.path.replace(/^\.?\/+/, "").replace(/\/+$/, "");
+        const abs = resolve(evda.dir, path);
+        if (path === "" || abs === evda.dir || !abs.startsWith(evda.dir + sep)) { fail(`${rel}: member "${name}" render path (${r.path}) is the record root or resolves outside the record.`); continue; }
+        out.members[name] = { kind: "render", view: r.view.trim(), rel: path, abs, shape };
+        continue;
+      }
+      if (!hasPath && !hasTable && !hasWhere) { fail(`${rel}: member "${name}" must have "path", "table", "where" (files selected by their frontmatter), or "render" (a view rendered at publish).`); continue; }
+      if (!hasPath && !hasTable) {
+        // A rule member: files in this record whose frontmatter matches, wherever they live. On any
+        // circle. `where: { share: <this circle> }` is the owner's per-entry mark; anything else is
+        // a standing rule by property, agreed once.
+        if (!isObject(member.where) || Object.keys(member.where).length === 0) { fail(`${rel}: member "${name}" where must be a non-empty mapping of frontmatter key -> scalar.`); continue; }
+        const bad = Object.entries(member.where).filter(([, v]) => !isScalar(v));
+        if (bad.length) { fail(`${rel}: member "${name}" where has non-scalar value(s): ${bad.map(([k]) => k).join(", ")}.`); continue; }
+        if (member.where[MARK] !== undefined && member.where[MARK] !== dir.name) warn(`${rel}: member "${name}" selects ${MARK}: ${JSON.stringify(member.where[MARK])}, and this circle is "${dir.name}". A mark names the circle it releases into; this rule would gather files marked for another one.`);
+        out.members[name] = { kind: "rule", where: member.where };
+        continue;
+      }
       if (hasPath) {
-        if (member.path === "" || isAbsolute(member.path)) { fail(`${rel}: member "${name}" path must be relative to the record root, got ${JSON.stringify(member.path)}.`); continue; }
-        const abs = resolve(evda.dir, member.path);
+        if (isAbsolute(member.path)) { fail(`${rel}: member "${name}" path must be relative to the record root, got ${JSON.stringify(member.path)}.`); continue; }
+        // "" or "." is the record root itself: the member claims everything a longer member of any
+        // circle does not (HQ-1364). It is kept as "" so every reader compares one spelling.
+        // Every member path is kept in one spelling, the resolved path relative to the root: the
+        // home of a file is picked by comparing member path lengths, so `./x` or `x/` read one
+        // level deeper than `x` and could take a file from the circle that really homes it, and
+        // `x/..` was the root under another name (HQ-1406).
+        const resolved = resolve(evda.dir, member.path);
+        const path = resolved === evda.dir ? "" : relative(evda.dir, resolved).split(sep).join("/");
+        if (path === "") {
+          if (m.public === true) { fail(`${rel}: member "${name}" is the record root, and this circle is public. The root is the private default; a public circle names what it publishes.`); continue; }
+          out.members[name] = { kind: "path", rel: "", abs: evda.dir, isDir: true };
+          continue;
+        }
+        const abs = resolve(evda.dir, path);
         if (abs !== evda.dir && !abs.startsWith(evda.dir + sep)) { fail(`${rel}: member "${name}" path (${member.path}) resolves outside the record.`); continue; }
-        if (!existsSync(abs)) { fail(`${rel}: member "${name}" is declared at ${member.path} but nothing is there. A missing member and an empty one are different facts.`); continue; }
-        out.members[name] = { kind: "path", rel: member.path, abs, isDir: statSync(abs).isDirectory() };
+        if (!existsSync(abs)) {
+          // Coded, so the sync layer can tell "this device was never sent the circle" from a broken
+          // declaration: a device without a grant on a circle has none of its members, by design.
+          fail(`${rel}: member "${name}" is declared at ${member.path} but nothing is there. A missing member and an empty one are different facts.`);
+          problems.at(-1).code = "MISSING_MEMBER";
+          problems.at(-1).member = { name, rel: path };
+          continue;
+        }
+        out.members[name] = { kind: "path", rel: path, abs, isDir: statSync(abs).isDirectory() };
       } else {
         if (member.table.trim() === "") { fail(`${rel}: member "${name}" has an empty table name.`); continue; }
         if (m.public !== true) fail(`${rel}: member "${name}" is a table, and this circle is not public. A table is readable by its host; a private circle's host may not read it (the person's threat model).`);
@@ -209,6 +359,43 @@ export function validateCircle(evda, dir) {
         out.members[name] = { kind: "table", table: member.table, where };
       }
     }
+    // A rendered file is written into the export at its path; two members rendering to one path,
+    // or two rendering one view, is one file with two answers. And a rendered path is never also
+    // a path member: the export cannot carry both the record's bytes and a rendering there.
+    const renders = Object.entries(out.members).filter(([, mm]) => mm.kind === "render");
+    const paths = Object.values(out.members).filter((mm) => mm.kind === "path");
+    const seenPath = new Map();
+    const seenView = new Map();
+    for (const [name, mm] of renders) {
+      if (seenPath.has(mm.rel)) fail(`${rel}: members "${seenPath.get(mm.rel)}" and "${name}" both render to ${mm.rel}. One file per path.`);
+      seenPath.set(mm.rel, name);
+      if (seenView.has(mm.view)) fail(`${rel}: members "${seenView.get(mm.view)}" and "${name}" both render view "${mm.view}". One member per view.`);
+      seenView.set(mm.view, name);
+      const under = paths.find((p) => p.rel === "" || (p.isDir ? mm.rel === p.rel || mm.rel.startsWith(`${p.rel}/`) : mm.rel === p.rel));
+      if (under) fail(`${rel}: member "${name}" renders to ${mm.rel}, which is also under a path member of this circle (${under.rel || "the record root"}). A rendered path is never also a path member.`);
+    }
+  }
+
+  // A circle mounted from another holder: its files land under `mount.path`, which must be one of
+  // this circle's path members, so what the scan walks and what the fold writes are one place.
+  if (m.mount !== undefined) {
+    if (!isObject(m.mount) || !nonEmpty(m.mount.holder) || !nonEmpty(m.mount.path)) fail(`${rel}: "mount" must be { holder: <record id>, path: <relative path> }, got ${JSON.stringify(m.mount)}.`);
+    else if (m.public === true) fail(`${rel}: "mount" is set on a public circle. A mount is another holder's private circle held here; a public circle is read from its export.`);
+    else {
+      const at = m.mount.path.replace(/\/+$/, "");
+      const member = Object.values(out.members).find((mm) => mm.kind === "path" && mm.rel.replace(/\/+$/, "") === at);
+      const declared = isObject(m.members) && Object.values(m.members).some((mm) => isObject(mm) && typeof mm.path === "string" && mm.path.replace(/\/+$/, "") === at);
+      if (!declared) fail(`${rel}: "mount.path" (${m.mount.path}) is not a path member of this circle. Declare it as one, so the scan and the fold agree on where the mount is.`);
+      else if (member && !member.isDir) fail(`${rel}: "mount.path" (${m.mount.path}) is a file. A mount is a directory the other holder's files land under.`);
+      else out.mount = { holder: m.mount.holder.trim(), rel: at };
+    }
+  }
+
+  // Frozen: a held copy whose grant was revoked. Says since when and by what; nothing else changes.
+  if (m.frozen !== undefined) {
+    if (!isObject(m.frozen) || !/^\d{4}-\d{2}-\d{2}$/.test(String(m.frozen.since ?? "")) || !nonEmpty(m.frozen.by)) fail(`${rel}: "frozen" must be { since: YYYY-MM-DD, by: <what froze it> }, got ${JSON.stringify(m.frozen)}.`);
+    else if (m.public === true) fail(`${rel}: "frozen" is set on a public circle. A public circle has no grant to revoke.`);
+    else out.frozen = { since: String(m.frozen.since), by: m.frozen.by.trim() };
   }
 
   if (!nonEmpty(m.description)) warn(`${rel}: has no "description". Say in plain language who may read this circle and why.`);
@@ -230,6 +417,54 @@ export function readCircles(evda) {
   return dirs.map((d) => validateCircle(evda, d));
 }
 
+// The mounts a record holds, checked against its `mounts` role (HQ-835). A circle held from another
+// holder lands at `<mounts>/<owner record id>/<one subfolder>`; without the role, anywhere its
+// manifest says, one per owner. Returns { root, held, owners, problems }, where each problem is a
+// sentence for doctor. Never throws for a problem; a mount root at the record root is one.
+//
+//   - a circle mounted from this record's own id (a holder does not mount its own circles);
+//   - under a mapped root, a mount that is not exactly one subfolder under its owner's directory;
+//   - two mounts where one is the other or lies inside it (one subfolder per circle);
+//   - a home circle with a path member under the mount root (what lands there is another holder's).
+export function mountProblems(evda, circles) {
+  const problems = [];
+  const r = resolveRole(evda, "mounts");
+  let root = null;
+  if (r.mapped) {
+    root = String(r.rel).replace(/\/+$/, "").replace(/^\.\/+/, "");
+    if (root === "" || root === ".") {
+      problems.push('the "mounts" role is the record root; another holder\'s files would sit beside this record\'s own. Map it to a directory such as mounts.');
+      root = null;
+    }
+  }
+  const me = evda.manifest?.id ?? null;
+  const held = circles.filter((c) => c.mount);
+  for (const c of held) {
+    if (me && c.mount.holder === me) problems.push(`circle "${c.name}" is mounted from ${me}, which is this record. A holder does not mount its own circles.`);
+    if (root !== null) {
+      const owner = `${root}/${c.mount.holder}/`;
+      const rest = c.mount.rel.startsWith(owner) ? c.mount.rel.slice(owner.length) : null;
+      if (rest === null || rest === "" || rest.includes("/")) problems.push(`circle "${c.name}" is mounted at ${c.mount.rel}; under the mounts role a circle from ${c.mount.holder} is held at ${owner}<one subfolder>.`);
+    }
+  }
+  for (let i = 0; i < held.length; i++) {
+    for (let j = i + 1; j < held.length; j++) {
+      const [a, b] = [held[i].mount.rel, held[j].mount.rel];
+      if (a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`)) problems.push(`circles "${held[i].name}" (${a}) and "${held[j].name}" (${b}) are mounted one inside the other. One subfolder per circle, never nested.`);
+    }
+  }
+  if (root !== null) {
+    for (const c of circles.filter((x) => !x.mount)) {
+      for (const [name, m] of Object.entries(c.members)) {
+        if (m.kind !== "path" || m.rel === "") continue;
+        const rel = m.rel.replace(/\/+$/, "");
+        if (rel === root || rel.startsWith(`${root}/`)) problems.push(`circle "${c.name}" member "${name}" (${rel}) is under the mount root ${root}; what lands there is another holder's, held by the circle mounted at it.`);
+      }
+    }
+  }
+  return { root, held: held.length, owners: new Set(held.map((c) => c.mount.holder)).size, problems };
+}
+
 // The circles this tool may read: public, and with no failing problem. Throws when the record
 // has a circles role and a circle in it is malformed, because serving a record with a broken
 // boundary declaration is worse than serving nothing.
@@ -264,30 +499,246 @@ export function holders(circle) {
   return Array.isArray(circle.manifest?.maintainers) ? circle.manifest.maintainers : [];
 }
 
-// Every entry resolves to exactly one circle (Spec 07, section 3). An entry is a file in a record
-// role, or the ledger file. A path member covers the file it names, or every file under the
-// directory it names; a table member covers no file. Returns each entry with the circles that
-// cover it, so doctor can fail on zero and on two.
+// A path member covers the file it names, or every file under the directory it names; the record
+// root ("") covers every file; a table, rule or render member covers no file.
+const underPath = (m, abs, root) => m.kind === "path" && (m.rel === "" ? abs.startsWith(root + sep) : m.isDir ? abs.startsWith(m.abs + sep) : abs === m.abs);
+
+// The circles that HOME an entry (Spec 07 section 3, HQ-1364): of every path member covering it,
+// across every circle, the ones whose member path is longest. One name is the answer; two names is
+// two circles claiming the same file at the same depth, which doctor fails; none is uncovered.
+export function homesOf(evda, circles, abs) {
+  // A file inside a sub-record of a bounded record is the sub-record's, homed in none of these.
+  const stops = boundaries(evda);
+  if (stops.length && insideAny(stops, abs.slice(evda.dir.length + 1).split(sep).join("/"))) return [];
+  let best = -1;
+  let names = [];
+  for (const c of circles) {
+    for (const m of Object.values(c.members)) {
+      if (!underPath(m, abs, evda.dir)) continue;
+      if (m.rel.length > best) { best = m.rel.length; names = [c.name]; }
+      else if (m.rel.length === best && !names.includes(c.name)) names.push(c.name);
+    }
+  }
+  return names;
+}
+
+// Every entry resolves to exactly one circle (Spec 07, section 3). Returns each entry with the
+// circles that home it, so doctor can fail on zero and on two.
 export function coverage(evda, circles, entries) {
-  const covers = (m, abs) => m.kind === "path" && (m.isDir ? abs.startsWith(m.abs + sep) : abs === m.abs);
-  return entries.map((abs) => ({
-    abs,
-    circles: circles.filter((c) => Object.values(c.members).some((m) => covers(m, abs))).map((c) => c.name),
-  }));
+  return entries.map((abs) => ({ abs, circles: homesOf(evda, circles, abs) }));
+}
+
+// The frontmatter of a markdown file as an object, or null when it has none or it does not parse.
+// A file with no frontmatter is not marked; a file whose frontmatter is broken is not marked either,
+// and doctor's typed-entry pass names it if it claims a kind.
+export function frontmatterOf(text) {
+  const lines = text.split("\n");
+  if (lines[0] !== "---") return null;
+  const end = lines.indexOf("---", 1);
+  if (end === -1) return null;
+  try {
+    const front = parseYaml(lines.slice(1, end).join("\n"));
+    return isObject(front) ? front : null;
+  } catch {
+    return null;
+  }
+}
+
+// Every markdown file under the record root, skipping dot-directories and node_modules. The mark
+// walk reads the whole record, not only the record roles: a released fact may live anywhere.
+export function markdownFiles(root) {
+  const out = [];
+  const walk = (abs) => {
+    for (const name of readdirSync(abs).sort()) {
+      if (name.startsWith(".") || name === "node_modules") continue;
+      const p = join(abs, name);
+      const st = statSync(p);
+      if (st.isDirectory()) walk(p);
+      else if (st.isFile() && /\.md$/i.test(name)) out.push(p);
+    }
+  };
+  walk(root);
+  return out;
+}
+
+// A where value matches the frontmatter value, or one item of it when the frontmatter holds a
+// list: `share: [doctor, public]` matches `where: { share: doctor }`.
+// Whether a file is just noted: markdown whose frontmatter says `noted: true`. Anything unreadable
+// or without frontmatter is not.
+export function isNoted(abs) {
+  if (!/\.md$/i.test(abs)) return false;
+  let text;
+  try { text = readFileSync(abs, "utf8"); } catch { return false; }
+  return frontmatterOf(text)?.[NOTED] === true;
+}
+
+// A markdown file's parsed frontmatter, or null when it is unreadable or has none.
+function frontOfFile(abs) {
+  if (!/\.md$/i.test(abs)) return null;
+  try { return frontmatterOf(readFileSync(abs, "utf8")); } catch { return null; }
+}
+
+// Sealed (HQ-1220). EVDA_SEALED_FALSIFY=file ignores the file flag and =sections ignores sealed
+// blocks, everywhere at once, so a test can show each reader is held by this filter and no other.
+const sealedFalsified = (mode) => String(process.env.EVDA_SEALED_FALSIFY ?? "").split(",").map((m) => m.trim()).includes(mode);
+
+// Whether parsed frontmatter seals its whole entry: `sealed: true`, nothing else.
+export const sealedFront = (front) => !sealedFalsified("file") && front?.[SEALED] === true;
+
+// Whether a file is sealed: markdown whose frontmatter says `sealed: true`. A symlink is read through,
+// so a link to a sealed file is sealed.
+export function isSealed(abs) {
+  if (!/\.md$/i.test(abs)) return false;
+  let text;
+  try { text = readFileSync(abs, "utf8"); } catch { return false; }
+  return sealedFront(frontmatterOf(text));
+}
+
+// The sealed sections of a text: a fence of three or more backticks or tildes whose info string
+// starts with the word `sealed`, to the next fence of the same character at least as long. Fenced
+// code around it does not unseal it; an unclosed one seals to the end of the text. Returns
+// [{ start, end, closed }] as 0-based line indexes, the fences included.
+const SEAL_OPEN = /^ {0,3}(`{3,}|~{3,})[ \t]*sealed(?:[ \t].*)?$/i;
+export function sealedSections(text) {
+  if (sealedFalsified("sections")) return [];
+  const lines = String(text).split("\n");
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const open = SEAL_OPEN.exec(lines[i].replace(/\r$/, ""));
+    if (!open) continue;
+    const fence = open[1];
+    const close = new RegExp(`^ {0,3}${fence[0] === "`" ? "`" : "~"}{${fence.length},}[ \\t]*$`);
+    let j = i + 1;
+    while (j < lines.length && !close.test(lines[j].replace(/\r$/, ""))) j++;
+    const closed = j < lines.length;
+    out.push({ start: i, end: closed ? j : lines.length - 1, closed });
+    i = j;
+  }
+  return out;
+}
+
+// The text with every sealed section taken out. `placeholder` null removes the lines (an export);
+// a string replaces each section with that one line (an AI's view, which says something is there).
+export function withoutSealed(text, { placeholder = null } = {}) {
+  const sections = sealedSections(text);
+  if (!sections.length) return { text, sections: 0, unclosed: 0 };
+  const lines = String(text).split("\n");
+  const kept = [];
+  let at = 0;
+  for (const s of sections) {
+    kept.push(...lines.slice(at, s.start));
+    if (placeholder !== null) kept.push(placeholder);
+    at = s.end + 1;
+  }
+  kept.push(...lines.slice(at));
+  let out = kept.join("\n");
+  if (at >= lines.length && placeholder === null && !out.endsWith("\n") && out !== "") out += "\n";
+  return { text: out, sections: sections.length, unclosed: sections.filter((s) => !s.closed).length };
 }
 
-// Build an eco manifest for a circle. `name` is the directory name; the id and namespace follow
-// from it, so the three cannot disagree.
-export function circleManifest({ name, title = name, isPublic = false, holders: hs = [], members = {}, policy = null, description = null }) {
+export const matchesWhere =(front, where) => Object.entries(where).every(([k, v]) => front[k] === v || (Array.isArray(front[k]) && front[k].includes(v)));
+const filesUnderPath = (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(...filesUnderPath(join(abs, name)));
+  }
+  return out;
+};
+
+// What each circle gathers beyond its own paths (Spec 07 section 3, HQ-1351): for every circle that
+// has a rule member, each file whose frontmatter matches, released out of its one home circle when
+// that home's `release` names this circle; plus every match it refused and why. For a public circle
+// the files under its path members and its table members are listed too, so doctor can print the
+// whole public set every run and it cannot grow quietly. `files` is the markdown to scan; the
+// default is the whole record. Only circles with a rule member or public: true are returned.
+export function released(evda, circles, { files = null } = {}) {
+  const rel = (abs) => abs.slice(evda.dir.length + 1).split(sep).join("/");
+  const stops = boundaries(evda);
+  const scan = (files ?? markdownFiles(evda.dir)).filter((abs) => !stops.length || !insideAny(stops, rel(abs)));
+  // The home circle(s) of a file, by longest member path: the same answer coverage() gives doctor.
+  const homeNames = (abs) => homesOf(evda, circles, abs);
+  const out = [];
+  for (const c of circles) {
+    const isPublic = c.manifest?.public === true;
+    const rules = Object.entries(c.members).filter(([, m]) => m.kind === "rule");
+    if (!isPublic && rules.length === 0) continue;
+    const byPath = [];
+    const byRule = [];
+    const refused = [];
+    const tables = [];
+    const renders = [];
+    if (isPublic) {
+      for (const [name, m] of Object.entries(c.members)) {
+        // Only the files this member HOMES: a file under it that a longer member of another circle
+        // claims is that circle's, not public.
+        if (m.kind === "path") for (const abs of filesUnderPath(m.abs)) {
+          if (homeNames(abs).join() !== c.name) continue;
+          const held = heldBy(frontOfFile(abs), "publish");
+          if (held === SEALED) { refused.push({ path: rel(abs), abs, member: name, reason: "it is sealed: only its owner opens it, on their own devices, and a sealed entry is never published, even from a public folder" }); continue; }
+          if (held === NOTED) { refused.push({ path: rel(abs), abs, member: name, reason: "it is just noted, and a noted entry is never published, even from a public folder" }); continue; }
+          byPath.push({ path: rel(abs), abs, member: name });
+        }
+        if (m.kind === "table") tables.push({ member: name, table: m.table, where: m.where });
+        // A render member is listed so the whole public set is on the screen; what it draws from
+        // is lib/render.mjs's answer, computed from byPath and byRule.
+        if (m.kind === "render") renders.push({ member: name, view: m.view, path: m.rel, shape: m.shape });
+      }
+    }
+    for (const [name, m] of rules) {
+      for (const abs of scan) {
+        let text;
+        try { text = readFileSync(abs, "utf8"); } catch { continue; }
+        const front = frontmatterOf(text);
+        if (!front || !matchesWhere(front, m.where)) continue;
+        // Sealed: no rule and no mark releases it, ever (HQ-1220). Checked before noted, so an entry
+        // that is both is refused as the stronger of the two.
+        const held = heldBy(front, "publish");
+        if (held === SEALED) { refused.push({ path: rel(abs), abs, member: name, reason: "it is sealed: only its owner opens it, on their own devices, and no mark releases a sealed entry" }); continue; }
+        // Just noted: no rule and no mark releases it until the owner says it can be read.
+        if (held === NOTED) { refused.push({ path: rel(abs), abs, member: name, reason: "it is just noted, and a noted entry goes nowhere until its owner releases it" }); continue; }
+        const homes = circles.filter((k) => homeNames(abs).includes(k.name));
+        if (homes.length === 1 && homes[0] === c) continue; // already here by path
+        if (homes.length === 0) { refused.push({ path: rel(abs), abs, member: name, reason: "no circle covers it by path, so nothing says it may be released" }); continue; }
+        if (homes.length > 1) { refused.push({ path: rel(abs), abs, member: name, reason: `covered by ${homes.length} circles (${homes.map((o) => o.name).join(", ")}); one home per entry` }); continue; }
+        const [home] = homes;
+        if (home.manifest?.public === true) { refused.push({ path: rel(abs), abs, member: name, circle: home.name, reason: `already public (home "${home.name}"), so there is nowhere further to release to` }); continue; }
+        if (home.release === "never") { refused.push({ path: rel(abs), abs, member: name, circle: home.name, reason: `its home circle "${home.name}" releases nothing (release: never)` }); continue; }
+        if (!home.release.includes(c.name)) { refused.push({ path: rel(abs), abs, member: name, circle: home.name, reason: `its home circle "${home.name}" may release to ${home.release.map((n) => `"${n}"`).join(", ")}, not to "${c.name}"` }); continue; }
+        byRule.push({ path: rel(abs), abs, member: name, circle: home.name });
+      }
+    }
+    out.push({ circle: c.name, public: isPublic, byPath, byRule, tables, renders, refused });
+  }
+  return out;
+}
+
+// Build an eco manifest for a circle. `name` is the directory name and never reaches the id: the
+// id is minted at random here, once, and the namespace follows from it, so the two cannot disagree.
+// Pass `id` only to rewrite a circle that already has one.
+export function circleManifest({ name, id = mintCircleId(), title = name, isPublic = false, holders: hs = [], members = {}, policy = null, description = null, release = null, mount = null }) {
   const m = {
-    id: ecoId(name),
+    id: ecoId(id),
     kind: "eco",
     schemaVersion: ECO_SCHEMA_VERSION,
-    namespace: ecoNamespace(name),
+    namespace: ecoNamespace(id),
     title,
   };
   if (description) m.description = description;
   m.public = isPublic;
+  // A circle says where a file living in it may be released to. Written explicitly, so the default
+  // is visible in the file rather than remembered.
+  if (!isPublic) {
+    if (release !== null && !isRelease(release)) throw new EvdaError(`"release" must be "never" or a non-empty list of circle names.`, { exit: 2 });
+    m.release = release ?? "never";
+  } else if (release !== null) throw new EvdaError(`a public circle has no "release"; everyone already reads it.`, { exit: 2 });
+  if (mount !== null) {
+    if (isPublic) throw new EvdaError(`a public circle has no "mount"; it is read from its export.`, { exit: 2 });
+    if (!isObject(mount) || !nonEmpty(mount.holder) || !nonEmpty(mount.path)) throw new EvdaError(`"mount" must be { holder: <record id>, path: <relative path> }.`, { exit: 2 });
+    m.mount = { holder: mount.holder, path: mount.path };
+  }
   m.maintainers = hs.map((h) => (typeof h === "string" ? { name: h, role: "holder" } : { name: h.name, role: h.role ?? "holder" }));
   m.members = members;
   if (Array.isArray(policy)) m.policy = policy;