@agfpd/iapeer-memory-core 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer-memory-core",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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/memoryd.ts

@@ -59,6 +59,13 @@ import {
 } 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 ────────────────────────────────────────────────────────────────
 
@@ -411,35 +418,68 @@ 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`;
@@ -449,6 +489,7 @@ export function persistBatchState(
       inbox: Object.fromEntries(state.inbox),
       permanent: Object.fromEntries(state.permanent),
       humanInbox: Object.fromEntries(state.humanInbox),
+      silentStamps: Object.fromEntries(state.silentStamps),
     }),
     "utf-8",
   );
@@ -580,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 {
@@ -587,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)}`);
@@ -735,6 +781,82 @@ export async function startMemoryd(opts: MemorydOptions): Promise<MemorydHandle>
     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
@@ -806,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'а ВО ВРЕМЯ вычитки породила

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);
+}