create-evda 0.1.8 → 0.1.9

package/lib/filechanges.mjs

@@ -36,6 +36,10 @@ import { admitDevice, devicesOf, readDevices, recordOf, retireDevice } from "./d
 import { resolveRole } from "./roles.mjs";
 import { boundaries, insideAny } from "./records.mjs";
 import { EvdaError } from "./errors.mjs";
+import { carryList, datalessAmong, excluder, fileClass, walk as walkRules } from "./sync-rules.mjs";
+// The day role, re-exported so pairing reads it through the four person libs the phone bundles.
+export { dayRole } from "./day-file.mjs";
+import { dayRole, localDate } from "./day-file.mjs";
 
 export const FILE_SET = "file.set";
 export const FILE_REMOVE = "file.remove";
@@ -365,6 +369,49 @@ export function grantView(evda) {
   };
 }
 
+// The id this record's computer speaks as (HQ-2005). A record create-evda made grants its own id
+// owner, and the computer is the record id. A record whose parts were declared by hand may grant
+// owner to a named device instead (his: `laptop.atlas` owner of every part, `hestia.atlas` an
+// editor, the record id nothing); then the computer is the one device that owns every private part
+// this record homes. None, or more than one, is refused in one line naming what was found, so a
+// caller can refuse before it writes anything. A record with no private parts is its own id.
+//
+// A computer that pins a device as a PEER in its own state is not that device (HQ-2040): Hestia
+// holds the laptop as a peer, so it never speaks as laptop.atlas. `notMe` lists those pins. With
+// them set aside, the one owner left is this computer even when it owns only some parts (his
+// Hestia owns core, where a phone pairs); none left is the same refusal, so a computer with no
+// grant of its own writes nothing rather than minting a second identity for another device's id.
+export const NOT_AN_OWNER_LEAD = "This record has private parts";
+export async function ownerDevice(evda, { notMe = [] } = {}) {
+  const own = typeof evda.manifest?.id === "string" ? evda.manifest.id : "";
+  const view = grantView(evda);
+  const parts = view.index.filter((c) => !c.public && !c.mount);
+  if (!own || parts.length === 0) return own;
+  const owns = async (id) => {
+    const out = [];
+    for (const c of parts) if (await view.mayShareKey(id, c.id)) out.push(c.name);
+    return out;
+  };
+  if ((await owns(own)).length > 0) return own;
+  const grants = (readGrants(evda) ?? []).filter((g) => g.role === "owner" && g.principalId && g.problems.every((p) => p.level !== "fail"));
+  const devices = readDevices(evda) ?? { lists: new Map(), problems: [] };
+  const names = new Map();
+  for (const g of grants) for (const d of devicesOf(devices, g.principalId)) if (!names.has(d)) names.set(d, g.holder?.name ?? d);
+  const found = [];
+  const peers = new Set(notMe);
+  for (const id of [...names.keys()].sort()) if (id !== own && !peers.has(id)) found.push({ id, name: names.get(id), parts: await owns(id) });
+  const full = found.filter((f) => f.parts.length === parts.length);
+  if (full.length === 1) return full[0].id;
+  const some = found.filter((f) => f.parts.length > 0);
+  if (peers.size > 0 && full.length === 0 && some.length === 1) return some[0].id;
+  const list = parts.map((c) => c.name).join(", ");
+  if (full.length > 1) {
+    throw new EvdaError(`${NOT_AN_OWNER_LEAD} (${list}), and ${full.length} devices own every one of them (${full.map((f) => f.name).join(", ")}), so this computer cannot tell which of them it is. Nothing was written.`, { code: "NOT_AN_OWNER", exit: 2 });
+  }
+  const who = found.filter((f) => f.parts.length > 0).map((f) => `${f.name} owns ${f.parts.join(", ")}`);
+  throw new EvdaError(`${NOT_AN_OWNER_LEAD} (${list}), but this computer is not an owner of any of them, and no one device owns them all${who.length ? `: ${who.join("; ")}` : ": no grant names an owner"}. Nothing was written.`, { code: "NOT_AN_OWNER", exit: 2 });
+}
+
 // Paths under an append-only role, where two devices' concurrent appends union instead of
 // conflicting: the daily notes and the ledger (Spec 08, section 3).
 export function unionPaths(evda) {
@@ -415,10 +462,16 @@ export function circleCrypto(crypto) {
 //                  has no mapping for the home record, still unions where the home does.
 //   onMinted       optional ({ change, circle, payload }) -> after the Change is appended, once per
 //                  circle the file reaches
-//   blobs          optional { seal(bytes) -> { hash, contentKey }, link(changeId, hash) }: a file above
-//                  BLOB_THRESHOLD bytes, or one that is not UTF-8, rides the blob lane (Spec 08 §1). Its
-//                  bytes are sealed once under a fresh content key and kept by the device; the payload
-//                  carries { hash, contentKey } in place of the text. Absent, such a file is minted as text.
+//   blobs          optional { seal(bytes) -> { hash, contentKey }, link(changeId, hash) }: a text file
+//                  above BLOB_THRESHOLD bytes or not UTF-8, and a file the manifest carries, rides the
+//                  blob lane (Spec 08 §1). Its bytes are sealed once under a fresh content key and kept
+//                  by the device; the payload carries { hash, contentKey } in place of the text. Absent,
+//                  such a file is minted as text.
+//   carry          optional, the manifest's `sync.carry` list (sync-rules `carryList`). Every file that
+//                  is neither text nor carried is a REFERENCE (HQ-2017): its payload is { path, sha256,
+//                  baseSha256, ref: { name, size } }, with no text and no blob, and nothing is sealed.
+//                  The scan passes `how.reference` for such a file and no bytes; a file that reaches
+//                  mint with bytes is classified here again, so no caller can seal media by mistake.
 //
 // Throwing is how a callback says "not recorded": the scan leaves the path for the next run.
 export const BLOB_THRESHOLD = 256 * 1024;
@@ -431,8 +484,17 @@ const utf8OrNull = (bytes) => {
   }
 };
 
-export function fileMinter({ log, index, seal, notifyFor, previousSha, changesetId, originUser = null, onMinted, blobs, unionPath = null, readText = null }) {
+// The reference payload for a file whose bytes do not travel (HQ-2017).
+const refPayload = (address, sha256, baseSha256, size) => ({
+  path: address,
+  sha256,
+  baseSha256,
+  ref: { name: address.slice(address.lastIndexOf("/") + 1), size },
+});
+
+export function fileMinter({ log, index, seal, notifyFor, previousSha, changesetId, originUser = null, onMinted, blobs, unionPath = null, readText = null, carry = [] }) {
   const at = addressing(index);
+  const classOf = fileClass(carry);
   const circleOf = (path) => {
     const c = circleForPath(index, path);
     if (!c) throw new EvdaError(`${path} is in no circle, so it has no one to sync to.`, { code: "NO_CIRCLE" });
@@ -461,10 +523,11 @@ export function fileMinter({ log, index, seal, notifyFor, previousSha, changeset
     return first;
   };
   return {
-    async mint(item, bytes) {
+    async mint(item, bytes, how = {}) {
       const home = circleOf(item.path);
       const address = at.address(home, item.path);
-      const text = utf8OrNull(bytes);
+      const kind = how.reference ? "reference" : classOf(item.path);
+      const text = kind === "reference" ? null : utf8OrNull(bytes);
       const circles = home.mount ? [home] : circlesFor(index, item.path, text, readText);
       const union = unionPath?.(item.path) === true ? { union: true } : {};
       // A circle the file reached before and reaches no longer (its mark was taken off, or its home
@@ -474,7 +537,13 @@ export function fileMinter({ log, index, seal, notifyFor, previousSha, changeset
       const withdraw = async () => {
         if (withdrawn.length > 0) await append(FILE_REMOVE, item.path, { path: address, sha256: null, baseSha256: await previousSha(item.path) }, withdrawn);
       };
-      if (blobs && (text === null || bytes.length > BLOB_THRESHOLD)) {
+      if (kind === "reference") {
+        const size = how.reference?.size ?? bytes.length;
+        await append(FILE_SET, item.path, refPayload(address, item.sha256, await previousSha(item.path), size), circles);
+        await withdraw();
+        return;
+      }
+      if (blobs && (kind === "carried" || text === null || bytes.length > BLOB_THRESHOLD)) {
         const sealed = await blobs.seal(bytes);
         const blob = { hash: sealed.hash, contentKey: Buffer.from(sealed.contentKey).toString("base64") };
         await append(FILE_SET, item.path, { path: address, sha256: item.sha256, baseSha256: await previousSha(item.path), blob }, circles, sealed.hash);
@@ -528,28 +597,35 @@ export function fileMinter({ log, index, seal, notifyFor, previousSha, changeset
 // `ancestors`: every sha this device logged for the address before the current one, from any circle
 // it can open. A receiver holding any of them fast-forwards; a receiver holding a version nobody
 // here has seen keeps it and gets the current text beside it, by the ordinary merge table.
-export function catchUp({ evda, view, log, seal, open, changesetId, originUser = null, unionPath = null, blobs = null, exclude = null }) {
+//
+// `stream(circleId, { skip })` yields the same Changes one at a time, minting each as it is asked
+// for, today's day file first and then newest first (HQ-2068); `snapshot` is the stream collected.
+//
+// `onFileSet(rel, sha256)`, when given, is awaited once per file.set this mints (HQ-2109): the
+// catch-up reads and hashes the file itself, so it is the one place that can tell the scan index the
+// file is already accounted for, at no extra read. Without it, a device's next ordinary scan finds no
+// row for a file the catch-up just sent, reads it as never-before-seen, and mints a second Change for
+// bytes the peer already has.
+export function catchUp({ evda, view, log, seal, open, changesetId, originUser = null, unionPath = null, blobs = null, exclude = null, onFileSet = null }) {
+  // What travels, by the same rule as the scan (sync-rules, HQ-2017): a reference is hashed from a
+  // local file and carries no bytes; a dataless file is not opened at all, and is left out of the
+  // catch-up (it is neither sent nor withdrawn) until its bytes are on this disk.
+  const classOf = fileClass(carryList(evda.manifest));
   const readText = (rel) => {
     const abs = join(evda.dir, rel);
     return existsSync(abs) && statSync(abs).isFile() ? readFileSync(abs, "utf8") : null;
   };
+  // The files a circle member holds, by the sync rules' own walk (HQ-2017): the same exclusions the
+  // scan lists by (node_modules, .git, .evda, the plan's paths), no symlink, no iCloud placeholder,
+  // nothing over the blob lane. The catch-up once walked by its own rule (every dot name skipped,
+  // node_modules kept), so what it sent and withdrew disagreed with what the scan minted.
+  const skip = exclude ?? excluder();
   const walk = (prefix) => {
-    const out = [];
     const start = join(evda.dir, prefix);
-    if (!existsSync(start)) return out;
-    if (statSync(start).isFile()) return [prefix];
-    const stack = [prefix.replace(/\/+$/, "")];
-    while (stack.length > 0) {
-      const dir = stack.pop();
-      for (const name of readdirSync(join(evda.dir, dir)).sort()) {
-        if (name.startsWith(".")) continue;
-        const rel = dir === "" ? name : `${dir}/${name}`;
-        const st = statSync(join(evda.dir, rel));
-        if (st.isDirectory()) stack.push(rel);
-        else if (st.isFile()) out.push(rel);
-      }
-    }
-    return out;
+    if (!existsSync(start)) return [];
+    const from = prefix.replace(/\/+$/, "");
+    if (statSync(start).isFile()) return skip(from) ? [] : [from];
+    return [...walkRules(evda.dir, { exclude: skip, from })].filter((e) => e.kind === "file").map((e) => e.rel);
   };
   const shaOf = async (bytes) => Buffer.from(await crypto.subtle.digest("SHA-256", bytes)).toString("hex");
 
@@ -568,55 +644,114 @@ export function catchUp({ evda, view, log, seal, open, changesetId, originUser =
     return out;
   };
 
-  return {
-    async snapshot(circleId) {
-      const index = view().index;
-      const target = circleById(index, circleId);
-      if (!target) throw new EvdaError(`no circle ${circleId} in this record.`, { code: "NO_CIRCLE" });
-      if (target.mount) throw new EvdaError(`circle "${target.name}" is held from ${target.mount.holder}; only its home catches a device up.`, { code: "NOT_OWNER" });
-      const at = addressing(index);
-      const present = new Map();
-      for (const { prefix, match } of scanPrefixes(index, (c) => !c.mount && !c.frozen)) {
-        for (const rel of walk(prefix)) {
-          if (!match(rel) || present.has(rel) || exclude?.(rel)) continue;
-          const bytes = readFileSync(join(evda.dir, rel));
-          const text = utf8OrNull(bytes);
-          if (!circlesFor(index, rel, text, readText).includes(target)) continue;
-          present.set(rel, { bytes, text });
-        }
+  const dayDir = dayFolderOf(evda.manifest);
+
+  // One Change per file the circle reaches now, newest first (HQ-2068), then one removal per address
+  // it no longer reaches. Each is minted only when the caller asks for the next, so a caller that
+  // posts as it goes has the first batch on the relay before the rest is read. `skip` holds
+  // addresses already sent by an earlier, interrupted run: neither minted again nor withdrawn.
+  async function* stream(circleId, { skip = new Set(), now = new Date() } = {}) {
+    const index = view().index;
+    const target = circleById(index, circleId);
+    if (!target) throw new EvdaError(`no circle ${circleId} in this record.`, { code: "NO_CIRCLE" });
+    if (target.mount) throw new EvdaError(`circle "${target.name}" is held from ${target.mount.holder}; only its home catches a device up.`, { code: "NOT_OWNER" });
+    const at = addressing(index);
+    const listed = new Set();
+    const skipped = new Set();
+    const files = [];
+    for (const { prefix, match } of scanPrefixes(index, (c) => !c.mount && !c.frozen)) {
+      const rels = walk(prefix).filter((rel) => match(rel) && !listed.has(rel));
+      const dataless = datalessAmong(evda.dir, rels);
+      for (const rel of rels) {
+        if (listed.has(rel)) continue;
+        listed.add(rel);
+        if (dataless.has(rel)) { skipped.add(rel); continue; }
+        let mtimeMs = 0;
+        try { mtimeMs = statSync(join(evda.dir, rel)).mtimeMs; } catch { continue; }
+        files.push({ rel, mtimeMs });
       }
-      const minted = [];
-      const append = async (kind, payload, blobHash = null) => {
-        const id = await changesetId();
-        const change = await log.append({ changesetId: id, eco: target.id, originUser, kind, target: payload.path, payload: await seal(target, payload), notify: [] });
-        if (blobHash !== null) await blobs.link(change.id, blobHash);
-        minted.push(change);
-      };
-      const addresses = new Set();
-      for (const [rel, { bytes, text }] of [...present.entries()].sort(([a], [b]) => a.localeCompare(b))) {
-        const address = at.address(circleForPath(index, rel), rel);
-        addresses.add(address);
-        const sha256 = await shaOf(bytes);
-        const ancestors = await ancestorsOf(address, sha256);
-        const base = { path: address, sha256, baseSha256: ancestors.at(-1) ?? null, ancestors };
-        if (blobs && (text === null || bytes.length > BLOB_THRESHOLD)) {
-          const sealed = await blobs.seal(bytes);
-          await append(FILE_SET, { ...base, blob: { hash: sealed.hash, contentKey: Buffer.from(sealed.contentKey).toString("base64") } }, sealed.hash);
-          continue;
-        }
-        await append(FILE_SET, { ...base, text: text ?? new TextDecoder("utf-8", { ignoreBOM: true }).decode(bytes), ...(unionPath?.(rel) === true ? { union: true } : {}) });
+    }
+    files.sort(catchUpOrder(dayDir, localDate(now)));
+    const mint = async (kind, payload, blobHash = null) => {
+      const id = await changesetId();
+      const change = await log.append({ changesetId: id, eco: target.id, originUser, kind, target: payload.path, payload: await seal(target, payload), notify: [] });
+      if (blobHash !== null) await blobs.link(change.id, blobHash);
+      return change;
+    };
+    const addresses = new Set();
+    for (const { rel } of files) {
+      const kind = classOf(rel);
+      let bytes = null;
+      let text = null;
+      let size = 0;
+      let known = null;
+      if (kind === "reference") {
+        // Only its home circle: a mark to release is frontmatter, and a reference has no text.
+        if (circleForPath(index, rel) !== target) continue;
+        const raw = readFileSync(join(evda.dir, rel));
+        size = raw.length;
+        known = await shaOf(raw);
+      } else {
+        bytes = readFileSync(join(evda.dir, rel));
+        text = utf8OrNull(bytes);
+        if (!circlesFor(index, rel, text, readText).includes(target)) continue;
       }
-      // Addresses the circle held before and does not now: removed, or no longer released into it.
-      const gone = new Set();
-      for (const change of await log.forEco(target.id)) {
-        if (change.kind === FILE_SET && !addresses.has(change.target)) gone.add(change.target);
+      const address = at.address(circleForPath(index, rel), rel);
+      addresses.add(address);
+      if (skip.has(address)) continue;
+      const sha256 = known ?? (await shaOf(bytes));
+      // Told as soon as the hash is known, whichever branch below mints: a file.set is coming for
+      // this path either way, and the scan index should already agree with it by the time it lands.
+      if (onFileSet) await onFileSet(rel, sha256);
+      const ancestors = await ancestorsOf(address, sha256);
+      const base = { path: address, sha256, baseSha256: ancestors.at(-1) ?? null, ancestors };
+      if (kind === "reference") {
+        yield await mint(FILE_SET, { ...refPayload(address, sha256, base.baseSha256, size), ancestors });
+        continue;
       }
-      for (const address of [...gone].sort()) {
-        const ancestors = await ancestorsOf(address, null);
-        if (ancestors.length === 0) continue;
-        await append(FILE_REMOVE, { path: address, sha256: null, baseSha256: ancestors.at(-1), ancestors });
+      if (blobs && (kind === "carried" || text === null || bytes.length > BLOB_THRESHOLD)) {
+        const sealed = await blobs.seal(bytes);
+        yield await mint(FILE_SET, { ...base, blob: { hash: sealed.hash, contentKey: Buffer.from(sealed.contentKey).toString("base64") } }, sealed.hash);
+        continue;
       }
+      yield await mint(FILE_SET, { ...base, text: text ?? new TextDecoder("utf-8", { ignoreBOM: true }).decode(bytes), ...(unionPath?.(rel) === true ? { union: true } : {}) });
+    }
+    // Addresses the circle held before and does not now: removed, or no longer released into it.
+    const gone = new Set();
+    const skippedAddresses = new Set([...skipped].map((rel) => { try { return at.address(circleForPath(index, rel), rel); } catch { return rel; } }));
+    for (const change of await log.forEco(target.id)) {
+      if (change.kind === FILE_SET && !addresses.has(change.target) && !skippedAddresses.has(change.target) && !skip.has(change.target)) gone.add(change.target);
+    }
+    for (const address of [...gone].sort()) {
+      const ancestors = await ancestorsOf(address, null);
+      if (ancestors.length === 0) continue;
+      yield await mint(FILE_REMOVE, { path: address, sha256: null, baseSha256: ancestors.at(-1), ancestors });
+    }
+  }
+
+  return {
+    stream,
+    async snapshot(circleId, o = {}) {
+      const minted = [];
+      for await (const change of stream(circleId, o)) minted.push(change);
       return minted;
     },
   };
 }
+
+// The order a catch-up sends a circle's files in (HQ-2068): today's day file first, then the most
+// recently modified, then by path, so a phone joining a large record shows what was written last
+// within seconds instead of after the alphabet.
+export function catchUpOrder(dayDir, today) {
+  const dayPrefix = `${String(dayDir ?? "").replace(/\/+$/, "")}/`;
+  const rank = (rel) => (rel.startsWith(dayPrefix) && rel.slice(dayPrefix.length).startsWith(today) ? 0 : 1);
+  return (a, b) => rank(a.rel) - rank(b.rel) || b.mtimeMs - a.mtimeMs || (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0);
+}
+
+// The day folder a record's mapping names, else create-evda's default (as pairing.ts reads it).
+function dayFolderOf(manifest) {
+  const mapping = manifest?.mapping;
+  const role = dayRole(mapping);
+  const rel = role ? mapping?.[role] : undefined;
+  return typeof rel === "string" && rel.trim() !== "" ? rel.replace(/\/+$/, "") : "record/daily";
+}

package/lib/gather-apply.mjs

@@ -51,6 +51,7 @@ import { proposeCircle, onlyKeys, refuse } from "./tools.mjs";
 import { doctor } from "./doctor.mjs";
 import { gatherDir, loadProposal, checkOut, presentIndex, presentAt, GATHERED, chatPlan, dayDirOf } from "./gather.mjs";
 import { dayAppend } from "./chat-export.mjs";
+import { sealForKeychain, removeSecret, SERVICE } from "./keychain.mjs";
 import { EvdaError } from "./errors.mjs";
 import { carries, NOTED, SEALED } from "./circles.mjs";
 import { parseArgs, scaffold } from "../create-evda.mjs";
@@ -297,8 +298,12 @@ function plan(evda, p, { mode }) {
     if (add.sealed && !/^sealed:[ \t]*true[ \t]*$/m.test(bytes.toString("utf8").split(/\n---/)[0])) bytes = Buffer.from(bytes.toString("utf8").replace(/^sealed:.*$/m, `${SEALED}: true`), "utf8");
     for (const flag of [NOTED, SEALED]) if (md && !carries("gather-apply", flag)) bytes = Buffer.from(bytes.toString("utf8").replace(new RegExp(`^${flag}:[ \\t]*true[ \\t]*\\n`, "m"), ""), "utf8");
     const st = statSync(src);
+    // A note gather caught as holding a credential, newly sealed here (HQ-1916): its value(s) are
+    // moved into the Keychain at apply, not left in the file. A file that already carried its own
+    // seal (re-gathered, or hand-marked) is not a fresh credential detection and is left as it is.
     out.writes.push({
       kind: mode === "move" ? "move" : "copy", item: pl.item, source: src, sourceSha: i.sha256, to: claim(to), folder, bytes, original: buf,
+      credential: !!(md && pl.sealed && i.credential && !i.sealed),
       schemes: md && add.references ? pl.refs.map((r) => r.split(":")[0]) : [],
       times: { atime: st.atimeMs / 1000, mtime: st.mtimeMs / 1000 }, mode: st.mode & 0o7777, atimeMs: st.atimeMs, mtimeMs: st.mtimeMs,
     });
@@ -385,13 +390,34 @@ export async function applyGather(p, into, { mode = "copy", dry = false, now = n
   }
   // 3. The files.
   const ledger = [];
+  // HQ-1916: a credential's value moves into the Keychain here, before its file ever touches disk;
+  // the tracker only ever sees the redacted bytes. Not macOS, or the write fails: the value stays in
+  // the sealed file exactly as HQ-1368 left it, and the fallback says why in one plain line.
+  const keychainPath = env.EVDA_KEYCHAIN_PATH || null;
+  const keychainAccounts = [];
+  const keychainLines = [];
+  let keychainFilesMoved = 0;
+  let keychainFilesKept = 0;
   for (const w of pl.writes) {
-    t.writeNew(w.to, w.bytes, w.times ?? null);
+    let bytes = w.bytes;
+    if (w.credential) {
+      const sealed = sealForKeychain(bytes.toString("utf8"), basename(w.to), { keychainPath });
+      if (sealed.ok) {
+        bytes = Buffer.from(sealed.text, "utf8");
+        keychainAccounts.push(...sealed.accounts);
+        keychainFilesMoved += 1;
+        keychainLines.push(`  kept     ${w.to}: ${sealed.accounts.length} value(s) moved to the Keychain (${SERVICE}); the file holds a pointer, not the value`);
+      } else {
+        keychainFilesKept += 1;
+        keychainLines.push(`  kept     ${w.to}: the value stays in the sealed file (${sealed.why})`);
+      }
+    }
+    t.writeNew(w.to, bytes, w.times ?? null);
     if (w.source) ledger.push({ source: w.sourceSha, to: w.to, proposal: p.id, at: now.toISOString() });
     if (w.kind === "move") {
       unlinkSync(w.source);
       // A file the apply changed on the way in keeps its source bytes here, so revert can put them back.
-      t.moved.push({ source: w.source, to: w.to, sha256: w.sourceSha, mode: w.mode, atimeMs: w.atimeMs, mtimeMs: w.mtimeMs, ...(sha256(w.bytes) !== w.sourceSha ? { bytes: w.original.toString("base64") } : {}) });
+      t.moved.push({ source: w.source, to: w.to, sha256: w.sourceSha, mode: w.mode, atimeMs: w.atimeMs, mtimeMs: w.mtimeMs, ...(sha256(bytes) !== w.sourceSha ? { bytes: w.original.toString("base64") } : {}) });
     }
   }
   // 3b. The owner's chat messages no agent filed (HQ-1385), appended to their days.
@@ -454,6 +480,10 @@ export async function applyGather(p, into, { mode = "copy", dry = false, now = n
     placed: pl.writes.map((w) => ({ item: w.item, kind: w.kind, from: w.source ?? null, to: w.to })),
     chats: [...pl.chats.byFile.keys()],
     counts: result.counts,
+    // HQ-1916: the Keychain items this apply added, and the keychain they went into (null is the
+    // login keychain), so revert can remove exactly these and nothing else.
+    keychain: keychainAccounts,
+    keychainPath,
   };
   mkdirSync(dirname(manifestAbs), { recursive: true });
   writeFileSync(manifestAbs, JSON.stringify(manifest, null, 2) + "\n", { flag: "wx" });
@@ -461,6 +491,9 @@ export async function applyGather(p, into, { mode = "copy", dry = false, now = n
   const lines = [];
   const d = doctor(evda.dir, { out: (l) => lines.push(l), via: "gather apply" });
   result.doctor = { exit: d.exit, lines, failures: d.failures, warnings: d.warnings.length };
+  result.keychainLines = keychainLines;
+  result.keychainMoved = keychainFilesMoved;
+  result.keychainKept = keychainFilesKept;
   result.lines = applyLines(result, p);
   return result;
 }
@@ -519,6 +552,7 @@ function applyLines(r, p) {
   if (c.pages) out.push(`  ${verb === "did" ? "wrote   " : "write   "} ${c.pages} page(s) the answers asked for`);
   if (c.referenceOnly) out.push(`  kept     ${c.referenceOnly} export(s) as references only, never copied`);
   if (c.present) out.push(`  present  ${c.present} item(s) already in the record, left where they are`);
+  if (r.keychainLines?.length) out.push(...r.keychainLines);
   for (const x of r.plan.changed) out.push(`  changed  ${x.item} ${x.why}`);
   if ((p.chats ?? []).length) {
     out.push(`  ${verb === "did" ? "added   " : "add     "} ${c.chatAdded} message(s) of the owner's from ${p.chats.length} chat export(s) to ${c.chatDays} day file(s), each conversation under its date and time; ${c.chatFiled} already in the record${c.chatSecret ? `, ${c.chatSecret} left out for holding something shaped like a secret` : ""}`);
@@ -536,6 +570,7 @@ function applyLines(r, p) {
   out.push(checkedLine(c));
   if ((p.chats ?? []).length) out.push(`CHECKED ${c.chatAdded + c.chatFiled + c.chatSecret} chat message(s) of the owner's  ${c.chatAdded} added, ${c.chatFiled} already filed, ${c.chatSecret} secret-shaped`);
   out.push(`CHECKED ${c.copied + c.moved} file(s) ${r.mode === "move" ? "moved" : "copied"}, ${c.references} reference entr${c.references === 1 ? "y" : "ies"}, ${c.pages} page(s), ${c.present} already in the record, ${c.refused} refused, ${c.changed} changed since the gather`);
+  if (r.keychainLines?.length) out.push(`CHECKED ${r.keychainMoved + r.keychainKept} credential file(s)  ${r.keychainMoved} with their value(s) moved to the Keychain, ${r.keychainKept} kept in the sealed file`);
   return out;
 }
 
@@ -587,6 +622,10 @@ export function revertGather(path, { force = false, now = new Date() } = {}) {
   }
   let removed = 0;
   for (const f of files) { const a = join(root, f.path); if (existsSync(a)) { unlinkSync(a); removed += 1; } }
+  // HQ-1916: every Keychain item this apply added, removed again. Never blocks the revert: a value
+  // already gone from the Keychain (the owner deleted it by hand) is simply not there to remove.
+  let keychainRemoved = 0;
+  for (const account of m.keychain ?? []) if (removeSecret({ account, keychainPath: m.keychainPath ?? null })) keychainRemoved += 1;
   let put = 0;
   if (!falsified("revert-not-exact")) {
     for (const f of m.modified) {
@@ -610,7 +649,7 @@ export function revertGather(path, { force = false, now = new Date() } = {}) {
   if (m.made?.root && existsSync(root) && readdirSync(root).length === 0) rmdirSync(root);
   m.reverted = now.toISOString();
   writeFileSync(abs, JSON.stringify(m, null, 2) + "\n");
-  return { manifest: abs, target: root, restored, removed, put, kept, gone, edited, forced: force && edited.length > 0 };
+  return { manifest: abs, target: root, restored, removed, put, kept, gone, edited, forced: force && edited.length > 0, keychainRemoved };
 }
 
 export function revertLines(r) {
@@ -621,7 +660,9 @@ export function revertLines(r) {
   if (r.forced) out.push(`  forced   ${r.edited.length} file(s) edited since the apply were removed: ${r.edited.join(", ")}`);
   for (const d of r.kept) out.push(`  kept     ${d}/, which holds files the apply did not write`);
   if (r.gone.length) out.push(`  gone     ${r.gone.length} file(s) were already removed`);
+  if (r.keychainRemoved) out.push(`  removed  ${r.keychainRemoved} Keychain item(s) the apply added`);
   out.push(`CHECKED ${r.removed + r.restored + r.put} file(s) reverted  ${r.kept.length} folder(s) kept`);
+  if (r.keychainRemoved) out.push(`CHECKED ${r.keychainRemoved} Keychain item(s) removed`);
   return out;
 }
 

package/lib/gather.mjs

@@ -75,7 +75,9 @@ export const PEOPLE_MIN_FILES = 3;
 const CRED_QUALIFIER = String.raw`(?:(?:wi-?fi|home|network|router|guest|email|e-mail|bank|account|admin|root|master|login|app|door|alarm|phone|sim|card|atm|debit|garage)\s+)*`;
 const CRED_SHORT = String.raw`pass(?:word|wd|code|phrase)?|pwd|pw|pin(?:\s*code)?|api[\s_-]*key|access[\s_-]*key|secret(?:[\s_-]*key)?|(?:auth[\s_-]*|access[\s_-]*|api[\s_-]*)?token|private[\s_-]*key|login`;
 const CRED_LONG = String.raw`(?:recovery|backup|2fa|mfa|one[\s-]*time)[\s_-]*(?:codes?|keys?|phrase)|seed[\s_-]*(?:phrase|words)|mnemonic(?:[\s_-]*phrase)?|secret[\s_-]*phrase`;
-const CRED_LINE = new RegExp(String.raw`^\s*(?:[-*+•>]\s+|\d+[.)]\s+)?[*_\x60]*${CRED_QUALIFIER}(?:(${CRED_LONG})|(${CRED_SHORT}))[*_\x60]*\s*(?:[:=]|\s[-\u2013]\s)[*_\x60]*\s*(.*)$`, "i");
+// Exported for lib/keychain.mjs (HQ-1916): the same line shape that types a note as holding a
+// credential is used again at apply, to find each value on its own line and move it off disk.
+export const CRED_LINE = new RegExp(String.raw`^\s*(?:[-*+•>]\s+|\d+[.)]\s+)?[*_\x60]*${CRED_QUALIFIER}(?:(${CRED_LONG})|(${CRED_SHORT}))[*_\x60]*\s*(?:[:=]|\s[-\u2013]\s)[*_\x60]*\s*(.*)$`, "i");
 export function credentialLine(lines) {
   const all = Array.isArray(lines) ? lines : String(lines ?? "").split("\n");
   for (let n = 0; n < all.length; n++) {

package/lib/keychain.mjs

@@ -0,0 +1,144 @@
+// macOS Keychain storage for the credential lines gather finds (HQ-1916, builds on HQ-1368).
+// First version, his own words: "it just needs to be super initial versioning" -- the smallest thing
+// that takes the password off disk.
+//
+// At `evda gather apply`, a note gather caught as holding a credential (lib/gather.mjs CRED_LINE, or
+// a bare token line shaped like a secret) is still sealed into Credentials/ as it is today, but each
+// value found in it is written into the login Keychain (service EVÐA) instead of staying in the
+// file. The line keeps its own label; only the value becomes a plain pointer:
+//   Password: in your Keychain (EVÐA, wifi.md, password)
+// Not macOS, or the Keychain write fails: the value stays in the file, unchanged, as it did before
+// this ticket, and gather-apply says so in one line. Nothing here calls any MCP tool, and nothing
+// here is registered as one: the owner reads a secret with `evda secret <file>`, on their own Mac,
+// printed to their own terminal only (Spec 07, the sealed folder's own guarantee).
+//
+// EVDA_KEYCHAIN_FALSIFY=<mode,...>, for the tests:
+//   no-keychain    keychainAvailable() always says no, so a credential file is never redacted
+//   write-fails    every "security add-generic-password" fails, so the value stays in the file
+
+import { execFileSync } from "node:child_process";
+import { CRED_LINE } from "./gather.mjs";
+import { secretShape } from "./references.mjs";
+
+export const SERVICE = "EVÐA";
+export const KEYCHAIN_FALSIFY_MODES = ["no-keychain", "write-fails"];
+const falsified = (mode) => (process.env.EVDA_KEYCHAIN_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+
+// The account a credential's Keychain item is filed under: the record file it came from, and its
+// label, so `evda secret <file>` can find every value a file's pointers name.
+export const accountFor = (fileName, label) => `${fileName} :: ${label}`;
+
+// Whether this machine can hold a secret in the Keychain at all. Never throws.
+export function keychainAvailable() {
+  if (falsified("no-keychain")) return false;
+  if (process.platform !== "darwin") return false;
+  try {
+    execFileSync("security", ["list-keychains"], { stdio: ["ignore", "ignore", "ignore"] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const keychainArgs = (keychainPath) => (keychainPath ? [keychainPath] : []);
+
+// `security add-generic-password`, overwriting an item already at this account (a second gather of
+// the same file lands on the same value). Throws on failure; the caller decides what that means.
+export function addSecret({ account, value, keychainPath = null } = {}) {
+  if (falsified("write-fails")) throw new Error("EVDA_KEYCHAIN_FALSIFY=write-fails");
+  execFileSync("security", ["add-generic-password", "-a", account, "-s", SERVICE, "-w", value, "-U", ...keychainArgs(keychainPath)], { stdio: ["ignore", "ignore", "pipe"] });
+}
+
+// Never throws: revert removes what it can and says what it removed.
+export function removeSecret({ account, keychainPath = null } = {}) {
+  try {
+    execFileSync("security", ["delete-generic-password", "-a", account, "-s", SERVICE, ...keychainArgs(keychainPath)], { stdio: ["ignore", "ignore", "ignore"] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// The value at an account, or throws (no item, or the Keychain refused to read it).
+export function readSecret({ account, keychainPath = null } = {}) {
+  return execFileSync("security", ["find-generic-password", "-a", account, "-s", SERVICE, "-w", ...keychainArgs(keychainPath)], { stdio: ["ignore", "pipe", "ignore"] }).toString("utf8").replace(/\n$/, "");
+}
+
+// Every credential value on its own line in `text`: a labeled line (CRED_LINE, the same shape that
+// typed the note in the first place) keeps its label and the text before the value, so only the
+// value itself is later replaced; a bare line shaped like a secret (a token with no "label:") has no
+// label of its own, so it is numbered "secret", "secret 2", ... in the order it appears. A labeled
+// line whose value is empty (the code sits on the next line instead) is left alone: multi-line values
+// are out of this first version's scope.
+export function extractSecrets(text) {
+  const lines = text.split("\n");
+  const out = [];
+  let bare = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = CRED_LINE.exec(line);
+    if (m) {
+      const label = (m[1] ?? m[2]).toLowerCase().replace(/[\s_-]+/g, " ");
+      const value = m[3].replace(/[*_\x60]+$/g, "").trim();
+      if (!value) continue;
+      out.push({ index: i, label, prefix: line.slice(0, line.length - m[3].length), value, whole: false });
+      continue;
+    }
+    if (secretShape(line.trim())) {
+      bare += 1;
+      out.push({ index: i, label: bare === 1 ? "secret" : `secret ${bare}`, prefix: "", value: line, whole: true });
+    }
+  }
+  return out;
+}
+
+// A pointer line reads back its account: "in your Keychain (EVÐA, wifi.md, password)".
+const POINTER = /in your Keychain \(([^,]+), ([^,]+), ([^)]+)\)/;
+export const pointerFor = (fileName, label) => `in your Keychain (${SERVICE}, ${fileName}, ${label})`;
+
+// Move every credential value in `text` into the Keychain, one item per line, and return the text
+// with each replaced by its pointer. All-or-nothing per file: if any value fails to write, every
+// item this call added is removed again and the original text comes back unchanged, so a file is
+// never left half in the Keychain and half redacted.
+// Returns { ok: true, text, accounts } or { ok: false, why }.
+export function sealForKeychain(text, fileName, { keychainPath = null } = {}) {
+  if (!keychainAvailable()) return { ok: false, why: "not on macOS, or the Keychain is unavailable" };
+  const secrets = extractSecrets(text);
+  if (!secrets.length) return { ok: false, why: "no credential value was found on its own line" };
+  const added = [];
+  try {
+    for (const s of secrets) {
+      const account = accountFor(fileName, s.label);
+      addSecret({ account, value: s.value, keychainPath });
+      added.push(account);
+    }
+  } catch (e) {
+    for (const account of added) removeSecret({ account, keychainPath });
+    return { ok: false, why: `the Keychain write failed (${String(e.message ?? e).split("\n")[0]})` };
+  }
+  const lines = text.split("\n");
+  for (const s of secrets) lines[s.index] = s.whole ? pointerFor(fileName, s.label) : `${s.prefix}${pointerFor(fileName, s.label)}`;
+  return { ok: true, text: lines.join("\n"), accounts: added };
+}
+
+// The owner's own read: every pointer in `text` resolved back to its value, for `evda secret <file>`
+// only. No MCP tool calls this.
+export function resolvePointers(text, { keychainPath = null } = {}) {
+  const lines = text.split("\n");
+  let resolved = 0;
+  let failed = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const m = POINTER.exec(lines[i]);
+    if (!m) continue;
+    const account = accountFor(m[2], m[3]);
+    try {
+      const value = readSecret({ account, keychainPath });
+      lines[i] = lines[i].slice(0, m.index) + value + lines[i].slice(m.index + m[0].length);
+      resolved += 1;
+    } catch {
+      lines[i] = `${lines[i]}  (could not read this from the Keychain)`;
+      failed += 1;
+    }
+  }
+  return { text: lines.join("\n"), resolved, failed };
+}

package/lib/manifest.mjs

@@ -16,7 +16,9 @@ export const SCHEMA_VERSION = 1;
 export const KNOWN_LAYERS = ["record", "ledger", "circles"];
 // `filing` (HQ-1385) is the owner's answer to the one setup question, "everything" or "asked";
 // lib/day-file.mjs filingOf reads it for every agent and hook.
-export const KNOWN_KEYS = ["evda", "id", "name", "owner", "created", "layers", "mapping", "subrecords", "read_by", "filing"];
+// `every_chat` (HQ-2205) is, per chat app, whether the owner put the every-chat line in that app's
+// settings ("set") or does not want it ("declined"); lib/every-chat.mjs reads it, evda_every_chat writes it.
+export const KNOWN_KEYS = ["evda", "id", "name", "owner", "created", "layers", "mapping", "subrecords", "read_by", "filing", "every_chat", "sync"];
 
 // Whether a record's circles stop at its sub-records (HQ-1371). A sub-record is a directory below
 // the root holding its own evda.json. "bounded": the parent's circles, coverage, scan and release