@agfpd/iapeer-memory-core 0.1.1

package/src/human-edit-detect.ts

@@ -0,0 +1,213 @@
+/**
+ * Human-edit detector — attribution of edits made OUTSIDE harness sessions
+ * (external editors: Obsidian is one case, any editor works — нюанс 6: the
+ * component is generic fs logic, nothing Obsidian-specific).
+ *
+ * TS port of the pure core of the reference
+ * `scripts/mergemind-obsidian-watcher.cjs` (behavioural parity against
+ * `tests/obsidian-watcher.test.ts`, 17 fixtures). In iapeer-memory this is
+ * a memoryd SUBSYSTEM (ADR-004) — the daemon shell (fs.watch, debounce,
+ * hash persistence) arrives with the memoryd stage; everything
+ * load-bearing (the anti-loop decision core) lives here, pure.
+ *
+ * PERMANENT mode (the five canonical folders):
+ *   - `last_edited_by == human` AND `updated` fresh → echo of our own
+ *     write — skip;
+ *   - `last_edited_by` is an agent AND fresh → the post-write hook just
+ *     ran — skip (the hook's zone);
+ *   - otherwise → an external-editor edit: stamp
+ *     `last_edited_by: <human>` + `updated` + `needs_review: true`.
+ *
+ * HUMAN-INBOX mode: anti-loop as above, then the idempotent 4-field fill.
+ *
+ * `freshEditWindowS` is CONFIG (the stage-7 review note): default 90s —
+ * the reference VALUE IS 90 (bumped from the historical 30: second-
+ * precision `updated` removed minute-truncation loss, while iCloud event
+ * delivery can take tens of seconds under a sync storm; the asymmetry of
+ * harm favours the larger window — a human edit inside the window
+ * self-corrects on the next event, an agent placement mis-attributed as
+ * human used to loop permanently).
+ */
+
+import crypto from "node:crypto";
+import path from "node:path";
+import type { TaxonomyPreset } from "./taxonomy.js";
+
+export const DEFAULT_FRESH_EDIT_WINDOW_S = 90;
+
+export function sha256(content: string): string {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+function pad(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+/** Second precision — symmetric with frontmatter-fill's writer stamp. */
+export function formatStamp(d: Date): string {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+
+/**
+ * Parse `updated` into ms. Strictly backward-compatible:
+ * `YYYY-MM-DD HH:MM:SS` (current), `YYYY-MM-DD HH:MM` (legacy, SS=0),
+ * `YYYY-MM-DD` (legacy date-only). Legacy formats are LOAD-BEARING:
+ * without them every touched old note mis-attributes as a human edit.
+ */
+export function parseUpdated(s: string | null | undefined): number | null {
+  if (!s) return null;
+  const trimmed = s.trim();
+  let m = /^(\d{4})-(\d{2})-(\d{2})\s+(\d{2}):(\d{2})(?::(\d{2}))?$/.exec(trimmed);
+  if (m) {
+    return new Date(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], m[6] ? +m[6] : 0).getTime();
+  }
+  m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(trimmed);
+  if (m) {
+    return new Date(+m[1], +m[2] - 1, +m[3]).getTime();
+  }
+  return null;
+}
+
+export function upsertField(fm: string, key: string, value: string): string {
+  const re = new RegExp(`^${key}\\s*:.*$`, "m");
+  if (re.test(fm)) {
+    return fm.replace(re, () => `${key}: ${value}`);
+  }
+  const tail = fm.endsWith("\n") ? "" : "\n";
+  return `${fm}${tail}${key}: ${value}\n`;
+}
+
+export function setIfMissing(fm: string, key: string, value: string): string {
+  const re = new RegExp(`^${key}\\s*:`, "m");
+  if (re.test(fm)) return fm;
+  const tail = fm.endsWith("\n") ? "" : "\n";
+  return `${fm}${tail}${key}: ${value}\n`;
+}
+
+export type HumanEditZone = "permanent" | "human-inbox";
+
+/** Zone of a file for the detector: permanent / human-inbox / null. */
+export function getZone(
+  filepath: string,
+  vault: string,
+  taxonomy: TaxonomyPreset,
+): HumanEditZone | null {
+  const rel = path.relative(vault, filepath);
+  const first = rel.split(path.sep)[0];
+  const f = taxonomy.folders;
+  if (first === f.inboxHuman) return "human-inbox";
+  if (
+    first === f.knowledge ||
+    first === f.decisions ||
+    first === f.projects ||
+    first === f.ideas ||
+    first === f.lists
+  ) {
+    return "permanent";
+  }
+  return null;
+}
+
+export type DecideUpdateInput = {
+  content: string;
+  zone: HumanEditZone;
+  human: string;
+  nowMs: number;
+  birthtimeMs: number;
+  mtimeMs: number;
+  basename: string;
+  lastHash: string | null;
+  taxonomy: TaxonomyPreset;
+  /** Config (default DEFAULT_FRESH_EDIT_WINDOW_S). */
+  freshEditWindowS?: number;
+};
+
+export type DecideUpdateResult =
+  | { action: "skip"; recordHash: string | null; reason: string }
+  | { action: "write"; newContent: string; recordHash: string; reason: string };
+
+/**
+ * The pure core: decides what to do from file content and context. No I/O,
+ * no module state — all the load-bearing anti-loop logic is here.
+ * `recordHash` is what the caller must store in its last-seen map
+ * (null = leave untouched, parity with the reference).
+ */
+export function decideUpdate(input: DecideUpdateInput): DecideUpdateResult {
+  const currentHash = sha256(input.content);
+  const windowS = input.freshEditWindowS ?? DEFAULT_FRESH_EDIT_WINDOW_S;
+
+  // Content-hash guard: an iCloud mtime-only event without a content change.
+  if (input.lastHash === currentHash) {
+    return { action: "skip", recordHash: null, reason: "content-unchanged" };
+  }
+
+  const fmMatch = /^---[^\S\n]*\n([\s\S]*?)\n---[^\S\n]*(?:\n|$)/.exec(input.content);
+  let fmBlock: string;
+  let body: string;
+  if (fmMatch) {
+    fmBlock = fmMatch[1];
+    body = input.content.slice(fmMatch[0].length);
+  } else if (input.zone === "human-inbox") {
+    fmBlock = "";
+    body = input.content;
+  } else {
+    // PERMANENT without frontmatter — not our zone.
+    return { action: "skip", recordHash: null, reason: "permanent-no-frontmatter" };
+  }
+
+  const lebMatch = /^last_edited_by\s*:\s*(.+?)\s*$/m.exec(fmBlock);
+  const updMatch = /^updated\s*:\s*(.+?)\s*$/m.exec(fmBlock);
+  const currentLeb = lebMatch ? lebMatch[1].trim() : null;
+  const currentUpd = updMatch ? updMatch[1].trim() : null;
+
+  const editAt = parseUpdated(currentUpd);
+  const isFresh = editAt !== null && (input.nowMs - editAt) / 1000 < windowS;
+
+  // Case 1: our own echo — our write came back through the fs watch.
+  if (currentLeb === input.human && isFresh) {
+    return { action: "skip", recordHash: currentHash, reason: "echo-human" };
+  }
+  // Case 2: a fresh agent edit — the post-write hook just ran.
+  if (currentLeb && currentLeb !== input.human && isFresh) {
+    return { action: "skip", recordHash: currentHash, reason: "echo-agent" };
+  }
+
+  // Otherwise — an external-editor edit (or a new human-inbox file).
+  const nowStamp = formatStamp(new Date(input.nowMs));
+  let newFm = fmBlock;
+
+  if (input.zone === "human-inbox") {
+    const titleDefault = input.basename.endsWith(".md")
+      ? input.basename.slice(0, -3)
+      : input.basename;
+    // `created` — file creation date. birthtime is the real creation on
+    // APFS; mtime creeps with edits. birthtime 0 (non-APFS) → mtime.
+    const createdSource =
+      input.birthtimeMs > 0 ? new Date(input.birthtimeMs) : new Date(input.mtimeMs);
+    const createdDate = createdSource.toISOString().slice(0, 10);
+
+    newFm = setIfMissing(newFm, "title", titleDefault);
+    newFm = setIfMissing(newFm, "status", input.taxonomy.statusTokens.draft);
+    newFm = setIfMissing(newFm, "created", createdDate);
+    newFm = setIfMissing(newFm, "author", input.human);
+    newFm = setIfMissing(newFm, "needs_review", "true");
+  } else {
+    newFm = upsertField(newFm, "last_edited_by", input.human);
+    newFm = upsertField(newFm, "updated", nowStamp);
+    newFm = upsertField(newFm, "needs_review", "true");
+  }
+
+  if (newFm === fmBlock) {
+    return { action: "skip", recordHash: currentHash, reason: "noop" };
+  }
+
+  const fmTail = newFm.endsWith("\n") ? "" : "\n";
+  const bodyPrefix = body.startsWith("\n") ? "" : "\n";
+  const newContent = `---\n${newFm}${fmTail}---${bodyPrefix}${body}`;
+  return {
+    action: "write",
+    newContent,
+    recordHash: sha256(newContent),
+    reason: input.zone === "human-inbox" ? "fill" : "stamp",
+  };
+}