@agfpd/iapeer-memory-core 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer-memory-core",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "iapeer-memory core — host-neutral TypeScript memory primitive: vault schema/taxonomy config, search engine, memoryd, context renderer, role contracts. Consumed by the @agfpd/iapeer-memory facade; version kept in lockstep by its release flow (docs/10-distribution.md).",
   "license": "MIT",
   "type": "module",

package/src/context-render.ts

@@ -27,6 +27,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
+import { guardedWriteFileSync, guardedUnlinkSync } from "./fs-guard.js";
 
 export const FRAGMENT_STEM = "iapeer-memory.md";
 
@@ -140,11 +141,11 @@ export function writeFragmentAtomic(
     `.${stem}.${crypto.randomBytes(6).toString("hex")}.tmp`,
   );
   try {
-    fs.writeFileSync(tmp, text, "utf-8");
+    guardedWriteFileSync(tmp, text, "utf-8");
     fs.renameSync(tmp, target);
   } catch (err) {
     try {
-      if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+      if (fs.existsSync(tmp)) guardedUnlinkSync(tmp);
     } catch {
       // best effort
     }

package/src/frontmatter-fill.ts

@@ -38,6 +38,7 @@ import path from "node:path";
 import crypto from "node:crypto";
 import type { TaxonomyPreset } from "./taxonomy.js";
 import { DEFAULT_CURATOR_SET } from "./taxonomy.js";
+import { guardedWriteFileSync, guardedUnlinkSync } from "./fs-guard.js";
 
 const FRONTMATTER_RE = /^---[^\S\n]*\n([\s\S]*?\n)---[^\S\n]*(?:\n|$)/;
 
@@ -417,11 +418,11 @@ export function atomicWrite(filePath: string, content: string): void {
     `.fm-${crypto.randomBytes(6).toString("hex")}.tmp`,
   );
   try {
-    fs.writeFileSync(tmp, content, "utf-8");
+    guardedWriteFileSync(tmp, content, "utf-8");
     fs.renameSync(tmp, filePath);
   } catch (err) {
     try {
-      if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+      if (fs.existsSync(tmp)) guardedUnlinkSync(tmp);
     } catch {
       // best effort
     }

package/src/fs-guard.ts

@@ -0,0 +1,92 @@
+/**
+ * FS belt — the file-system half of deny-by-default
+ * (iapeer-memory docs/_planning/DENY_BY_DEFAULT_DESIGN.md §4 П4, accepted
+ * by boris 11.06).
+ *
+ * Incident class №2 («лестница рассинхронилась»): the db path ladder lived
+ * in TWO copies (core config + package paths) and a drift wrote a sandbox
+ * SQLite into the PROD `~/.iapeer/cache`. Path conventions cannot be the
+ * only belt — so every raw write/unlink/rm in BOTH src trees goes through
+ * the wrappers below, and under an armed test-sandbox env they REFUSE any
+ * path under a production anchor, no matter what the ladder computed:
+ *
+ *   ~/.iapeer            — ecosystem state/cache/config of the live host
+ *   ~/.claude, ~/.codex  — harness config surfaces of the live fleet
+ *   ~/Library/Mobile Documents — the iCloud root (the live vault lives there)
+ *
+ * Outside the sandbox env the wrappers are pass-through: live init/update/
+ * migrate write exactly where they always did. The grep invariant (И3) pins
+ * the funnel: no raw `fs.writeFileSync`/`Bun.write`/`fs.rmSync`/
+ * `fs.unlinkSync` outside this file in either src tree.
+ *
+ * Deliberately NOT guarded in v1: `mkdirSync` (creates empty dirs — no data
+ * loss / no content leak; the write that would fill them refuses) and reads.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** Both test belts — the ecosystem-wide var survives generic
+ *  IAPEER_MEMORY_* env-stripping (incident 10.06 №3). The ONE definition
+ *  for both packages: the package egress hub imports this. */
+export function sandboxEnvArmed(): boolean {
+  return (
+    process.env.IAPEER_MEMORY_SUPPRESS_IAP_SEND === "1" ||
+    process.env.IAPEER_TEST_SANDBOX === "1"
+  );
+}
+
+function prodAnchors(): string[] {
+  const home = os.homedir();
+  return [
+    path.join(home, ".iapeer"),
+    path.join(home, ".claude"),
+    path.join(home, ".codex"),
+    path.join(home, "Library", "Mobile Documents"),
+  ];
+}
+
+/** True when the resolved path sits under a production anchor. Exported for
+ *  tests: the predicate is checkable without arming any write. */
+export function isUnderProdAnchor(filePath: string): boolean {
+  const resolved = path.resolve(filePath);
+  return prodAnchors().some(
+    (a) => resolved === a || resolved.startsWith(a + path.sep),
+  );
+}
+
+/** Throws under an armed sandbox env when the path targets a prod anchor.
+ *  The op name makes the refusal teach: WHICH write was stopped. */
+export function assertSandboxWritablePath(filePath: string, op: string): void {
+  if (!sandboxEnvArmed()) return;
+  if (isUnderProdAnchor(filePath)) {
+    throw new Error(
+      `fs-guard: ${op} refused under the test sandbox — "${filePath}" is under a production anchor ` +
+        "(~/.iapeer, ~/.claude, ~/.codex or the iCloud root). A test must write " +
+        "inside its own tmp root; if the path came from the env ladder, the ladder drifted.",
+    );
+  }
+}
+
+export function guardedWriteFileSync(
+  filePath: string,
+  data: string | NodeJS.ArrayBufferView,
+  options?: Parameters<typeof fs.writeFileSync>[2],
+): void {
+  assertSandboxWritablePath(filePath, "write");
+  fs.writeFileSync(filePath, data, options);
+}
+
+export function guardedUnlinkSync(filePath: string): void {
+  assertSandboxWritablePath(filePath, "unlink");
+  fs.unlinkSync(filePath);
+}
+
+export function guardedRmSync(
+  filePath: string,
+  options?: Parameters<typeof fs.rmSync>[1],
+): void {
+  assertSandboxWritablePath(filePath, "rm");
+  fs.rmSync(filePath, options);
+}

package/src/index-render.ts

@@ -28,6 +28,7 @@ import path from "node:path";
 import crypto from "node:crypto";
 import type { RankingConfig, TaxonomyPreset } from "./taxonomy.js";
 import { statusGroup as taxonomyStatusGroup } from "./taxonomy.js";
+import { guardedWriteFileSync, guardedUnlinkSync } from "./fs-guard.js";
 
 const WIKILINK_RE = /\[\[([^\]|#]+)/g;
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n/;
@@ -821,11 +822,11 @@ export function atomicWrite(filePath: string, content: string): void {
   const dir = path.dirname(filePath) || ".";
   const tmp = path.join(dir, `.vault-index-${crypto.randomBytes(6).toString("hex")}.tmp`);
   try {
-    fs.writeFileSync(tmp, content, "utf-8");
+    guardedWriteFileSync(tmp, content, "utf-8");
     fs.renameSync(tmp, filePath);
   } catch (err) {
     try {
-      if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+      if (fs.existsSync(tmp)) guardedUnlinkSync(tmp);
     } catch {
       // best effort
     }

package/src/index.ts

@@ -70,3 +70,12 @@ export { prepareSqliteRuntime, type SqliteRuntime } from "./sqlite-loader.js";
 
 // logging
 export { makeLogger, type Logger } from "./log.js";
+
+export {
+  sandboxEnvArmed,
+  isUnderProdAnchor,
+  assertSandboxWritablePath,
+  guardedWriteFileSync,
+  guardedUnlinkSync,
+  guardedRmSync,
+} from "./fs-guard.js";

package/src/memoryd.ts

@@ -58,6 +58,14 @@ import {
   type RenderContext,
 } from "./index-render.js";
 import { renderPeerFragment, type FragmentEnv } from "./context-render.js";
+import { guardedWriteFileSync, guardedUnlinkSync } from "./fs-guard.js";
+import {
+  isSilentEdit,
+  readStampRecord,
+  restampUnstamped,
+  type SilentZone,
+  type StampRecord,
+} from "./silent-edit-detect.js";
 
 // ── identity ────────────────────────────────────────────────────────────────
 
@@ -410,44 +418,78 @@ export async function startMcpHttp(opts: {
 // baseline survives restarts, atomically (same tmp+rename canon).
 
 /** Persisted batch baselines: inbox + permanent + human-inbox snapshots
- *  (rel/name → smart hash). Survives restarts — порт паттерна старых
- *  мониторов «seen переживает сбой». */
+ *  (rel/name → smart hash) + the silent-edit stamp baseline (rel →
+ *  {updated, leb}; the unstamped detector judges stamp movement against
+ *  it). Survives restarts — порт паттерна старых мониторов «seen
+ *  переживает сбой». Migration is FIRST-SIGHT by construction: an absent
+ *  silentStamps key (pre-detector state file) reads as an empty map — one
+ *  warm-up pass records, never judges. */
 export type BatchState = {
   inbox: VaultSnapshot | null;
   permanent: VaultSnapshot | null;
   humanInbox: VaultSnapshot | null;
+  silentStamps: Map<string, StampRecord> | null;
 };
 
 export function loadBatchState(filePath: string): BatchState {
   try {
     const raw = JSON.parse(fs.readFileSync(filePath, "utf-8")) as Record<
       string,
-      Record<string, string>
+      Record<string, unknown>
     >;
-    const toMap = (o: Record<string, string> | undefined): VaultSnapshot | null =>
-      o ? new Map(Object.entries(o)) : null;
+    const toMap = (o: Record<string, unknown> | undefined): VaultSnapshot | null =>
+      o
+        ? new Map(
+            Object.entries(o).filter((e): e is [string, string] => typeof e[1] === "string"),
+          )
+        : null;
+    const toStamps = (
+      o: Record<string, unknown> | undefined,
+    ): Map<string, StampRecord> | null => {
+      if (!o) return null;
+      const m = new Map<string, StampRecord>();
+      for (const [k, v] of Object.entries(o)) {
+        if (v && typeof v === "object" && !Array.isArray(v)) {
+          const r = v as { hash?: unknown; updated?: unknown; leb?: unknown };
+          if (typeof r.hash !== "string") continue; // schema drift → first-sight
+          m.set(k, {
+            hash: r.hash,
+            updated: typeof r.updated === "string" ? r.updated : null,
+            leb: typeof r.leb === "string" ? r.leb : null,
+          });
+        }
+      }
+      return m;
+    };
     return {
       inbox: toMap(raw.inbox),
       permanent: toMap(raw.permanent),
       humanInbox: toMap(raw.humanInbox),
+      silentStamps: toStamps(raw.silentStamps),
     };
   } catch {
-    return { inbox: null, permanent: null, humanInbox: null };
+    return { inbox: null, permanent: null, humanInbox: null, silentStamps: null };
   }
 }
 
 export function persistBatchState(
   filePath: string,
-  state: { inbox: VaultSnapshot; permanent: VaultSnapshot; humanInbox: VaultSnapshot },
+  state: {
+    inbox: VaultSnapshot;
+    permanent: VaultSnapshot;
+    humanInbox: VaultSnapshot;
+    silentStamps: Map<string, StampRecord>;
+  },
 ): void {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   const tmp = `${filePath}.tmp`;
-  fs.writeFileSync(
+  guardedWriteFileSync(
     tmp,
     JSON.stringify({
       inbox: Object.fromEntries(state.inbox),
       permanent: Object.fromEntries(state.permanent),
       humanInbox: Object.fromEntries(state.humanInbox),
+      silentStamps: Object.fromEntries(state.silentStamps),
     }),
     "utf-8",
   );
@@ -470,7 +512,7 @@ export function loadHashState(filePath: string): Map<string, string> {
 export function persistHashState(filePath: string, map: Map<string, string>): void {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   const tmp = `${filePath}.tmp`;
-  fs.writeFileSync(tmp, JSON.stringify(Object.fromEntries(map)), "utf-8");
+  guardedWriteFileSync(tmp, JSON.stringify(Object.fromEntries(map)), "utf-8");
   fs.renameSync(tmp, filePath);
 }
 
@@ -579,6 +621,10 @@ export async function startMemoryd(opts: MemorydOptions): Promise<MemorydHandle>
   let humanInboxBaseline: VaultSnapshot =
     persistedBatches.humanInbox ?? snapshotFlatFolder(humanInboxDir);
   const lastSeenHashes = loadHashState(hashStatePath);
+  /** Silent-edit stamp baseline (rel → {updated, leb}); absent key in an
+   *  old state file = empty map = first-sight warm-up (design §4). */
+  const silentStamps: Map<string, StampRecord> =
+    persistedBatches.silentStamps ?? new Map();
 
   function persistBatches(): void {
     try {
@@ -586,6 +632,7 @@ export async function startMemoryd(opts: MemorydOptions): Promise<MemorydHandle>
         inbox: inboxSnapshot,
         permanent: permanentBaseline,
         humanInbox: humanInboxBaseline,
+        silentStamps,
       });
     } catch (err) {
       logger.error(`batch-state persist failed: ${String(err)}`);
@@ -729,11 +776,87 @@ export async function startMemoryd(opts: MemorydOptions): Promise<MemorydHandle>
     if (decision.action !== "write") return;
     fs.mkdirSync(path.dirname(tagsMirrorPath), { recursive: true });
     const tmp = `${tagsMirrorPath}.tmp`;
-    fs.writeFileSync(tmp, srcContent!, "utf-8");
+    guardedWriteFileSync(tmp, srcContent!, "utf-8");
     fs.renameSync(tmp, tagsMirrorPath);
     logger.info(`tags mirror updated (${decision.reason})`);
   }
 
+  /** Zone map of the unstamped detector (design §3): the agent inbox +
+   *  the six permanent folders (five canonical + agent memory — wider than
+   *  humanEditPass's getZone, which has no agent-memory notion). */
+  function silentZoneOf(absPath: string): SilentZone | null {
+    const rel = path.relative(config.vaultPath, absPath);
+    if (rel.startsWith("..")) return null;
+    const first = rel.split(path.sep)[0];
+    const f = taxonomy.folders;
+    if (first === f.inbox) return "inbox";
+    if (
+      first === f.knowledge ||
+      first === f.decisions ||
+      first === f.projects ||
+      first === f.ideas ||
+      first === f.lists ||
+      first === f.agentMemory
+    ) {
+      return "permanent";
+    }
+    return null;
+  }
+
+  /**
+   * Unstamped-write detector (design doc, boris-accepted 11.06). Runs
+   * BEFORE the inbox emission loop and BEFORE humanEditPass: a re-stamped
+   * file then reads `last_edited_by: unstamped` — the curator source
+   * filters pass it into the pipeline, and humanEditPass sees a fresh
+   * agent stamp (echo-agent skip, no double stamp — order instead of ifs).
+   * Candidates carry CHANGED files only (fs.watch set ∪ inbox diff) — the
+   * semantic-hash precondition of the rule; service-only echoes never
+   * reach here (smart-hash blindness = echo safety of our own re-stamp).
+   */
+  function silentEditPass(candidatesAbs: Set<string>): void {
+    for (const abs of candidatesAbs) {
+      const zone = silentZoneOf(abs);
+      if (!zone) continue;
+      const rel = path.relative(config.vaultPath, abs);
+      let content: string;
+      try {
+        content = fs.readFileSync(abs, "utf-8");
+      } catch {
+        silentStamps.delete(rel); // deleted mid-debounce — drop the record
+        continue;
+      }
+      const curr = readStampRecord(content);
+      const prev = silentStamps.get(rel);
+      if (prev === undefined) {
+        silentStamps.set(rel, curr); // first sight: record, never judge
+        continue;
+      }
+      if (!isSilentEdit({ prev, curr, zone, nowMs: Date.now(), freshEditWindowS: opts.freshEditWindowS })) {
+        silentStamps.set(rel, curr);
+        continue;
+      }
+      const restamped = restampUnstamped(content, Date.now());
+      if (restamped === null) {
+        silentStamps.set(rel, curr); // bare draft — the fill machinery's job
+        continue;
+      }
+      const tmp = `${abs}.memoryd.tmp`;
+      try {
+        guardedWriteFileSync(tmp, restamped, "utf-8");
+        fs.renameSync(tmp, abs);
+        silentStamps.set(rel, readStampRecord(restamped));
+        logger.info(`silent edit re-stamped (${zone}): ${rel}`);
+      } catch (err) {
+        try {
+          guardedUnlinkSync(tmp);
+        } catch {
+          // best effort
+        }
+        logger.error(`silent-edit re-stamp failed for ${abs}: ${String(err)}`);
+      }
+    }
+  }
+
   function humanEditPass(changedAbs: Set<string>): void {
     const human = opts.humanName ?? null;
     if (!human) return; // ⚖7: no human role — detection off
@@ -776,13 +899,13 @@ export async function startMemoryd(opts: MemorydOptions): Promise<MemorydHandle>
       }
       const tmp = `${filePath}.memoryd.tmp`;
       try {
-        fs.writeFileSync(tmp, decision.newContent, "utf-8");
+        guardedWriteFileSync(tmp, decision.newContent, "utf-8");
         fs.renameSync(tmp, filePath);
         lastSeenHashes.set(filePath, decision.recordHash);
         logger.info(`human-edit ${decision.reason}: ${path.relative(config.vaultPath, filePath)}`);
       } catch (err) {
         try {
-          fs.unlinkSync(tmp);
+          guardedUnlinkSync(tmp);
         } catch {
           // best effort
         }
@@ -805,7 +928,20 @@ export async function startMemoryd(opts: MemorydOptions): Promise<MemorydHandle>
     // INBOX_NEW — мгновенно: new OR semantically changed drafts (hash-diff
     // over the WHOLE inbox folder; no dependency on fs.watch filenames).
     const inboxNext = snapshotInbox(config.vaultPath, taxonomy);
-    for (const name of diffSnapshots(inboxSnapshot, inboxNext)) {
+    const inboxChanged = diffSnapshots(inboxSnapshot, inboxNext);
+
+    // Unstamped detector FIRST (design §3 order): re-stamps land before the
+    // curator suppress below reads leb and before humanEditPass judges.
+    // Candidates: fs.watch set (permanent fresh-window branch) ∪ the inbox
+    // diff (the diff is semantic — a re-stamp does not invalidate it).
+    silentEditPass(
+      new Set([
+        ...changed,
+        ...inboxChanged.map((n) => path.join(config.vaultPath, taxonomy.folders.inbox, n)),
+      ]),
+    );
+
+    for (const name of inboxChanged) {
       const abs = path.join(config.vaultPath, taxonomy.folders.inbox, name);
       // Source-фильтр кураторов — ПАРИТЕТ с PERMANENT_BATCH (живое эхо
       // 10.06: стилистическая правка Scriber'а ВО ВРЕМЯ вычитки породила
@@ -905,7 +1041,7 @@ export async function startMemoryd(opts: MemorydOptions): Promise<MemorydHandle>
   function touchHeartbeat(): void {
     try {
       fs.mkdirSync(path.dirname(heartbeatPath), { recursive: true });
-      fs.writeFileSync(heartbeatPath, `${new Date().toISOString()} ${os.hostname()}\n`);
+      guardedWriteFileSync(heartbeatPath, `${new Date().toISOString()} ${os.hostname()}\n`);
     } catch (err) {
       logger.error(`heartbeat write failed: ${String(err)}`);
     }
@@ -1020,7 +1156,7 @@ export async function startMemoryd(opts: MemorydOptions): Promise<MemorydHandle>
       persistQuiet();
       if (mcp) await mcp.close();
       try {
-        fs.unlinkSync(heartbeatPath);
+        guardedUnlinkSync(heartbeatPath);
       } catch {
         // best effort
       }

package/src/migrate-auto-memory.ts

@@ -32,6 +32,7 @@ import fs from "node:fs";
 import path from "node:path";
 import type { TaxonomyPreset } from "./taxonomy.js";
 import { yamlSafeScalar } from "./fm-update.js";
+import { guardedWriteFileSync, guardedUnlinkSync } from "./fs-guard.js";
 
 /** Source files that are backed up but never copied into the vault. */
 export const SKIP_FILES: ReadonlySet<string> = new Set(["MEMORY.md"]);
@@ -217,7 +218,7 @@ export function applyMigration(opts: {
     // 2a. Non-md and SKIP_FILES: backup-only, removed from the source.
     if (!name.endsWith(".md") || SKIP_FILES.has(name)) {
       try {
-        fs.unlinkSync(srcPath);
+        guardedUnlinkSync(srcPath);
       } catch (err) {
         errors.push(`${name}: unlink after backup failed — ${String(err)}`);
       }
@@ -229,7 +230,7 @@ export function applyMigration(opts: {
     if (fs.existsSync(targetFile)) {
       skipped.push(name);
       try {
-        fs.unlinkSync(srcPath);
+        guardedUnlinkSync(srcPath);
       } catch (err) {
         errors.push(`${name}: unlink (already migrated) failed — ${String(err)}`);
       }
@@ -261,7 +262,7 @@ export function applyMigration(opts: {
 
     try {
       const tmp = `${targetFile}.tmp`;
-      fs.writeFileSync(tmp, newText, "utf-8");
+      guardedWriteFileSync(tmp, newText, "utf-8");
       fs.renameSync(tmp, targetFile);
     } catch (err) {
       errors.push(`${name}: write failed — ${String(err)}`);
@@ -269,7 +270,7 @@ export function applyMigration(opts: {
     }
 
     try {
-      fs.unlinkSync(srcPath);
+      guardedUnlinkSync(srcPath);
       migrated.push(name);
     } catch (err) {
       errors.push(`${name}: written to target but source unlink failed — ${String(err)}`);

package/src/render-doctrine.ts

@@ -24,6 +24,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
+import { guardedWriteFileSync, guardedUnlinkSync } from "./fs-guard.js";
 
 /** `<!-- iapeer-memory doctrine v<version> -->` — machine-checkable. */
 export function versionMarker(version: string): string {
@@ -93,11 +94,11 @@ export function renderDoctrine(opts: {
     `.IAPEER.md.${crypto.randomBytes(6).toString("hex")}.tmp`,
   );
   try {
-    fs.writeFileSync(tmp, rendered, "utf-8");
+    guardedWriteFileSync(tmp, rendered, "utf-8");
     fs.renameSync(tmp, target);
   } catch (err) {
     try {
-      if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+      if (fs.existsSync(tmp)) guardedUnlinkSync(tmp);
     } catch {
       // best effort
     }

package/src/silent-edit-detect.ts

@@ -0,0 +1,126 @@
+/**
+ * Silent-edit detector — the unstamped-write belt
+ * (docs/_planning/UNSTAMPED_EDIT_DETECTOR_DESIGN.md, accepted by boris
+ * 11.06; precedent: the Index's catch — a Bash-heredoc edit of a canon
+ * note 52 s after a curator stamp was swallowed FOREVER by the human-edit
+ * echo window, masquerading as the curator for the source filters).
+ *
+ * A vault write that bypasses the PostToolUse hook (Bash, python-heredoc,
+ * any non-Write/Edit tool) leaves the stamp untouched. The discriminator
+ * is the SEMANTIC hash (smart-hash: frontmatter minus service fields +
+ * body) — the battle-proven anti-echo of permanent-detect: a hook echo
+ * changes ONLY service fields (semantic hash still), a silent edit moves
+ * the semantic hash while the stamp stands still. The same property makes
+ * our response re-stamp echo-safe BY CONSTRUCTION: a re-stamp touches only
+ * service fields, so it never re-triggers the detector or the batch diffs.
+ *
+ * ZONED rule (the humanEditPass intersection, §3a of the design):
+ *   permanent — ONLY the fresh-window case (stamp ≤ FRESH_EDIT_WINDOW_S):
+ *     that is exactly the echo-window swallow; STALE cases stay with
+ *     humanEditPass (human attribution — the Obsidian main case; a wider
+ *     rule would regress «Артур правит кураторскую заметку»);
+ *   inbox — UNCONDITIONAL: humanEditPass does not cover the agent inbox at
+ *     all, human edits there are marginal, and the curator-masquerade
+ *     (memoryd's 822-suppress) plus the silent author edit are both closed
+ *     by one branch.
+ *
+ * Attribution token: `unstamped` — NEUTRAL on purpose (the mechanism
+ * cannot tell a Bash agent from a human outside Obsidian; a false «agent»
+ * on the human's edit is worse than an honest «don't know» — the
+ * author-guard symmetry: a visible anomaly beats a silently assigned
+ * identity). The Index resolves it by context; needs_review rides along.
+ *
+ * Pure decision core — no I/O; the memoryd shell owns reading, the atomic
+ * write and the persisted stamp baseline (first-sight warm-up: a file
+ * without a baseline record is recorded, never judged — the 0.1.8 guard).
+ */
+
+import {
+  formatStamp,
+  parseUpdated,
+  upsertField,
+  DEFAULT_FRESH_EDIT_WINDOW_S,
+} from "./human-edit-detect.js";
+import { smartHash } from "./smart-hash.js";
+
+export const UNSTAMPED_TOKEN = "unstamped";
+
+export type SilentZone = "permanent" | "inbox";
+
+/** The per-file baseline record (design §4): the SEMANTIC hash (the BASE
+ *  precondition — without it an iCloud mtime-echo inside the fresh window
+ *  would false-trigger a re-stamp on identical content) + the stamp pair
+ *  compared verbatim between passes. */
+export type StampRecord = {
+  hash: string;
+  updated: string | null;
+  leb: string | null;
+};
+
+const FM_RE = /^---[^\S\n]*\n([\s\S]*?)\n---[^\S\n]*(?:\n|$)/;
+
+/** Read the baseline record from note content. No frontmatter → null stamps. */
+export function readStampRecord(content: string): StampRecord {
+  const fm = FM_RE.exec(content);
+  const hash = smartHash(new TextEncoder().encode(content));
+  if (!fm) return { hash, updated: null, leb: null };
+  const upd = /^updated\s*:\s*(.+?)\s*$/m.exec(fm[1]);
+  const leb = /^last_edited_by\s*:\s*(.+?)\s*$/m.exec(fm[1]);
+  return {
+    hash,
+    updated: upd ? upd[1].trim() : null,
+    leb: leb ? leb[1].trim() : null,
+  };
+}
+
+export type DecideSilentInput = {
+  /** Baseline record (the PREVIOUS pass). */
+  prev: StampRecord;
+  curr: StampRecord;
+  zone: SilentZone;
+  nowMs: number;
+  freshEditWindowS?: number;
+};
+
+/**
+ * BASE: the semantic hash MOVED ∧ the stamp pair did not move verbatim.
+ * Zone branch: permanent → only when the standing stamp is FRESH (the
+ * echo-window swallow); inbox → unconditional. A service-only change
+ * (hook echo, our own re-stamp) keeps the semantic hash still → never
+ * silent; an mtime-only event keeps content identical → never silent.
+ */
+export function isSilentEdit(input: DecideSilentInput): boolean {
+  if (input.prev.hash === input.curr.hash) return false; // BASE: no semantic move
+  const stampUnmoved =
+    input.prev.updated === input.curr.updated && input.prev.leb === input.curr.leb;
+  if (!stampUnmoved) return false;
+  if (input.zone === "inbox") return true;
+  const windowS = input.freshEditWindowS ?? DEFAULT_FRESH_EDIT_WINDOW_S;
+  const editAt = parseUpdated(input.curr.updated);
+  return editAt !== null && (input.nowMs - editAt) / 1000 < windowS;
+}
+
+/**
+ * The response re-stamp: `last_edited_by: unstamped` + fresh `updated` +
+ * `needs_review: true`. Content without frontmatter → null (a bare draft
+ * is the fill machinery's job, not ours).
+ *
+ * SURGICAL splice: only the captured frontmatter block is replaced — the
+ * rest of the file (the `---` fences, the blank line after them, the body)
+ * stays byte-exact. That is what makes the re-stamp service-fields-only
+ * and therefore echo-safe (a reassembly once ate the post-fence blank
+ * line, moved the semantic hash and broke the no-loop property — caught
+ * by the test, fixed by construction).
+ */
+export function restampUnstamped(content: string, nowMs: number): string | null {
+  const fm = FM_RE.exec(content);
+  if (!fm) return null;
+  let block = fm[1];
+  block = upsertField(block, "last_edited_by", UNSTAMPED_TOKEN);
+  block = upsertField(block, "updated", formatStamp(new Date(nowMs)));
+  block = upsertField(block, "needs_review", "true");
+  block = block.replace(/\n$/, ""); // the capture carries no trailing \n
+  const blockStart = fm[0].indexOf("\n") + 1; // right after the opening fence line
+  const blockEnd = blockStart + fm[1].length;
+  return content.slice(0, blockStart) + block + content.slice(blockEnd);
+}