@agfpd/iapeer-memory-core 0.1.6 → 0.1.8

package/package.json

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

@@ -50,6 +50,16 @@ export type CoreConfig = {
     dbPath: string;
     fullScanOnStartup: boolean;
   };
+  /** Конвейерные каденции (директива Артура 10.06 ~15:31): канон-правки и
+   *  human-inbox идут ПАЧКАМИ, не событиями — правки должны устаканиться,
+   *  10 пишущих агентов не дёргают конвейер постоянно. */
+  batch: {
+    /** PERMANENT_BATCH period, ms (default 6h). */
+    permanentMs: number;
+    /** HUMAN_INBOX_BATCH — РАЗ В СУТКИ в этот локальный час (default 04:00,
+     *  как в старом контуре: человек пишет долго, ночная партия). */
+    humanInboxHour: number;
+  };
   /**
    * MCP-http endpoint of memoryd (ADR-012). The default port 8766 is the
    * neighbour of the iapeer foundation MCP (8765) — one ecosystem block,
@@ -89,7 +99,7 @@ export type CoreConfig = {
  * to BM25. Adding the exact endpoint host to NO_PROXY is idempotent and
  * monotonic — it only bypasses the explicitly configured host.
  */
-function ensureEndpointNotProxied(endpoint: string): void {
+export function ensureEndpointNotProxied(endpoint: string): void {
   let host: string;
   try {
     host = new URL(endpoint).hostname;
@@ -106,6 +116,19 @@ function ensureEndpointNotProxied(endpoint: string): void {
   }
 }
 
+/**
+ * Loopback NEVER goes through a proxy — fleet-class defect (B-приёмка
+ * 10.06, boris): every peer's shell carries HTTP(S)_PROXY (VPN tinyproxy),
+ * Bun's fetch honours it for 127.0.0.1 too → the status probe of the LIVE
+ * memoryd port detoured to the proxy and lied «nothing listening» (proven:
+ * lsof caught tinyproxy SYN_SENT to 8766; `env -u HTTP_PROXY` → truthful).
+ * Call before ANY loopback fetch from CLI paths that run in agent shells.
+ */
+export function ensureLoopbackNotProxied(): void {
+  ensureEndpointNotProxied("http://127.0.0.1/");
+  ensureEndpointNotProxied("http://localhost/");
+}
+
 function envString(name: string, fallback = ""): string {
   const value = process.env[name];
   return typeof value === "string" && value.length > 0 ? value : fallback;
@@ -237,6 +260,10 @@ export function configFromEnv(): CoreConfig {
       dbPath,
       fullScanOnStartup: envBoolean("IAPEER_MEMORY_FULL_SCAN_ON_STARTUP", true),
     },
+    batch: {
+      permanentMs: envNumber("IAPEER_MEMORY_PERMANENT_BATCH_SECS", 6 * 3600) * 1000,
+      humanInboxHour: envNumber("IAPEER_MEMORY_HUMAN_INBOX_HOUR", 4),
+    },
     mcp: {
       port: envNumber("IAPEER_MEMORY_MCP_PORT", 8766),
     },

package/src/index.ts

@@ -8,7 +8,12 @@
  */
 
 // config
-export { configFromEnv, type CoreConfig } from "./config.js";
+export {
+  configFromEnv,
+  ensureEndpointNotProxied,
+  ensureLoopbackNotProxied,
+  type CoreConfig,
+} from "./config.js";
 
 // taxonomy (ADR-002/011)
 export {

package/src/memoryd.ts

@@ -39,12 +39,13 @@ import type { CoreConfig } from "./config.js";
 import { openDatabase, type CoreDb } from "./db.js";
 import { indexAll } from "./indexer.js";
 import { runSearch, runGraph, runMap } from "./mcp-tools.js";
-import { decideUpdate, getZone } from "./human-edit-detect.js";
+import { decideUpdate, getZone, sha256 } from "./human-edit-detect.js";
 import { decideMirror, tagsDictionarySourceRel } from "./tags-mirror.js";
 import {
   snapshotVault,
-  detectPermanentChanges,
-  formatEventLines,
+  snapshotInbox,
+  snapshotFlatFolder,
+  diffSnapshots,
   type VaultSnapshot,
 } from "./permanent-detect.js";
 import { makeLogger, type Logger } from "./log.js";
@@ -399,6 +400,51 @@ export async function startMcpHttp(opts: {
 // a sync-storm right after a restart could still mis-attribute — so the
 // baseline survives restarts, atomically (same tmp+rename canon).
 
+/** Persisted batch baselines: inbox + permanent + human-inbox snapshots
+ *  (rel/name → smart hash). Survives restarts — порт паттерна старых
+ *  мониторов «seen переживает сбой». */
+export type BatchState = {
+  inbox: VaultSnapshot | null;
+  permanent: VaultSnapshot | null;
+  humanInbox: VaultSnapshot | null;
+};
+
+export function loadBatchState(filePath: string): BatchState {
+  try {
+    const raw = JSON.parse(fs.readFileSync(filePath, "utf-8")) as Record<
+      string,
+      Record<string, string>
+    >;
+    const toMap = (o: Record<string, string> | undefined): VaultSnapshot | null =>
+      o ? new Map(Object.entries(o)) : null;
+    return {
+      inbox: toMap(raw.inbox),
+      permanent: toMap(raw.permanent),
+      humanInbox: toMap(raw.humanInbox),
+    };
+  } catch {
+    return { inbox: null, permanent: null, humanInbox: null };
+  }
+}
+
+export function persistBatchState(
+  filePath: string,
+  state: { inbox: VaultSnapshot; permanent: VaultSnapshot; humanInbox: VaultSnapshot },
+): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp`;
+  fs.writeFileSync(
+    tmp,
+    JSON.stringify({
+      inbox: Object.fromEntries(state.inbox),
+      permanent: Object.fromEntries(state.permanent),
+      humanInbox: Object.fromEntries(state.humanInbox),
+    }),
+    "utf-8",
+  );
+  fs.renameSync(tmp, filePath);
+}
+
 export function loadHashState(filePath: string): Map<string, string> {
   const map = new Map<string, string>();
   try {
@@ -436,6 +482,11 @@ export type MemorydOptions = {
   tagsMirrorPath?: string;
   /** Detect-hash persistence file; default `<db dir>/memoryd.hashes.json`. */
   hashStatePath?: string;
+  /** Persisted batch baselines (inbox + permanent + human-inbox snapshots). */
+  batchStatePath?: string;
+  /** Cadence overrides (tests); default from config.batch. */
+  permanentBatchMs?: number;
+  humanInboxBatchMs?: number;
   /** Periodic hash-persist interval (ms). */
   persistMs?: number;
   /** Human owner name; human-edit detection is OFF when absent (⚖7). */
@@ -452,6 +503,8 @@ export type MemorydHandle = {
   mcpPort: number | null;
   /** Force one detect pass immediately (used by tests and shutdown flush). */
   runDetectPass: () => Promise<void>;
+  /** Force a cadence batch (tests / operator force-tick). */
+  runBatchPass: (kind: "permanent" | "human-inbox") => void;
   close: () => Promise<void>;
 };
 
@@ -471,15 +524,65 @@ export async function startMemoryd(opts: MemorydOptions): Promise<MemorydHandle>
   const db = openDatabase(config);
   await indexAll({ db, config, logger });
 
-  // Baselines: detect from NOW on; pre-existing inbox files do not replay
-  // (the Index catches them up at its own start — reference semantics).
-  let snapshot: VaultSnapshot = snapshotVault(config.vaultPath, taxonomy);
-  const inboxDir = path.join(config.vaultPath, taxonomy.folders.inbox);
-  const inboxSeen = new Set<string>(
-    fs.existsSync(inboxDir) ? fs.readdirSync(inboxDir).filter((f) => f.endsWith(".md")) : [],
-  );
+  // Baselines (каденции — директива Артура 10.06 ~15:31): inbox HASH-diffed
+  // мгновенно (B-приёмка fix: правка существующего черновика = событие, цикл
+  // reject→fix→re-review); канон + оперативка копятся и уходят ПАЧКОЙ раз в
+  // batch.permanentMs (default 6h); human-inbox — пачкой раз в
+  // batch.humanInboxMs (default 4h). Снапшоты ПЕРСИСТЯТСЯ через рестарты
+  // (порт паттерна старых мониторов: «seen переживает сбой») — рестарт не
+  // глотает накопленное и не реплеит обработанное.
+  const batchStatePath = opts.batchStatePath ?? path.join(dbDir, "memoryd.batches.json");
+  const persistedBatches = loadBatchState(batchStatePath);
+  let inboxSnapshot: VaultSnapshot =
+    persistedBatches.inbox ?? snapshotInbox(config.vaultPath, taxonomy);
+  let permanentBaseline: VaultSnapshot =
+    persistedBatches.permanent ?? snapshotVault(config.vaultPath, taxonomy);
+  const humanInboxDir = path.join(config.vaultPath, taxonomy.folders.inboxHuman);
+  let humanInboxBaseline: VaultSnapshot =
+    persistedBatches.humanInbox ?? snapshotFlatFolder(humanInboxDir);
   const lastSeenHashes = loadHashState(hashStatePath);
 
+  function persistBatches(): void {
+    try {
+      persistBatchState(batchStatePath, {
+        inbox: inboxSnapshot,
+        permanent: permanentBaseline,
+        humanInbox: humanInboxBaseline,
+      });
+    } catch (err) {
+      logger.error(`batch-state persist failed: ${String(err)}`);
+    }
+  }
+  if (!persistedBatches.inbox) persistBatches(); // first run: write baselines
+
+  /** iCloud-mount guard (порт защиты старых мониторов): корень vault
+   *  недоступен → пропускаем проход целиком, baseline не трогаем — после
+   *  восстановления mount «всё новое» не реплеится штормом. */
+  function vaultAvailable(): boolean {
+    try {
+      return fs.statSync(config.vaultPath).isDirectory();
+    } catch {
+      logger.warn("vault root unavailable (iCloud unmount?) — pass skipped");
+      return false;
+    }
+  }
+
+  /** SOURCE-фильтр кураторских правок (директива п.5 + stale-fix): свежий
+   *  last_edited_by читается ИЗ ФАЙЛА на момент пачки — правки
+   *  index/scriber/dreamweaver в пачку не попадают (эхо-брейкер механикой,
+   *  не доктриной). */
+  function lastEditedByOf(absPath: string): string | null {
+    try {
+      const head = fs.readFileSync(absPath, "utf-8").slice(0, 4096);
+      const fm = /^---[^\S\n]*\n([\s\S]*?)\n---/.exec(head);
+      if (!fm) return null;
+      const m = /^last_edited_by\s*:\s*(.+?)\s*$/m.exec(fm[1]);
+      return m ? m[1].trim() : null;
+    } catch {
+      return null;
+    }
+  }
+
   syncTagsMirror(); // best-effort materialisation at start
 
   function syncTagsMirror(): void {
@@ -519,6 +622,16 @@ export async function startMemoryd(opts: MemorydOptions): Promise<MemorydHandle>
       } catch {
         continue; // deleted mid-debounce
       }
+      // FIRST-SIGHT GUARD (churn-дефект B-приёмки, boris п.3): путь, которого
+      // нет в hash-базе — это mv размещения Индексом (Входящие → канон) или
+      // первое наблюдение после установки, НЕ человеческая правка. Запиши
+      // baseline и не стампь: фантомные last_edited_by на каждом размещении —
+      // системный churn. Цена: первая правка человеком never-seen файла
+      // пройдёт без стампа один раз (поймается следующей).
+      if (!lastSeenHashes.has(filePath)) {
+        lastSeenHashes.set(filePath, sha256(content));
+        continue;
+      }
       const decision = decideUpdate({
         content,
         zone,
@@ -561,32 +674,65 @@ export async function startMemoryd(opts: MemorydOptions): Promise<MemorydHandle>
     const changed = new Set(pending);
     pending.clear();
 
-    // INBOX_NEW — new inbox files since the baseline.
-    for (const abs of changed) {
-      const rel = path.relative(config.vaultPath, abs);
-      const parts = rel.split(path.sep);
-      if (parts[0] === taxonomy.folders.inbox && parts.length === 2) {
-        const name = parts[1];
-        if (!inboxSeen.has(name) && fs.existsSync(abs)) {
-          inboxSeen.add(name);
-          emit(`INBOX_NEW: ${name}`);
-        }
-      }
+    if (!vaultAvailable()) return;
+
+    // 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)) {
+      logger.info(`inbox event: ${name}`);
+      // ABSOLUTE path (B-приёмка 10.06): a consumer must never guess the
+      // vault root — a role peer once `find`-guessed a stale copy.
+      emit(`INBOX_NEW: ${path.join(config.vaultPath, taxonomy.folders.inbox, name)}`);
+    }
+    if (inboxNext.size > 0 || inboxSnapshot.size === 0) {
+      inboxSnapshot = inboxNext;
+      persistBatches();
     }
 
     humanEditPass(changed);
     syncTagsMirror();
     await indexAll({ db, config, logger }); // incremental by content hash
+    // PERMANENT правки НЕ эмитятся мгновенно — копятся до batch-прохода
+    // (каденция 6h); см. runPermanentBatch.
+  }
 
-    const { event, next } = detectPermanentChanges({
-      vault: config.vaultPath,
-      taxonomy,
-      prev: snapshot,
-    });
-    snapshot = next;
-    if (event) {
-      for (const line of formatEventLines(event)) emit(line);
+  /** PERMANENT_BATCH — один проход каденции: diff канона+оперативки против
+   *  baseline пачки, кураторские правки отфильтрованы ИСТОЧНИКОМ, остальное
+   *  уходит ОДНОЙ строкой (JSON-массив АБСОЛЮТНЫХ путей → одна доставка →
+   *  одна ephemeral-сессия Scriber'а → один отчёт). */
+  function runPermanentBatch(): void {
+    if (!vaultAvailable()) return;
+    const next = snapshotVault(config.vaultPath, taxonomy);
+    const changedRel = diffSnapshots(permanentBaseline, next);
+    permanentBaseline = next; // кураторские поглощаются, не реплеятся
+    const absPaths: string[] = [];
+    for (const rel of changedRel) {
+      const abs = path.join(config.vaultPath, rel);
+      const leb = lastEditedByOf(abs);
+      if (leb && config.curatorSet.includes(leb)) continue; // source-фильтр
+      absPaths.push(abs);
+    }
+    if (absPaths.length) {
+      logger.info(`permanent batch: ${absPaths.length} path(s)`);
+      emit(`PERMANENT_BATCH: ${JSON.stringify(absPaths)}`);
     }
+    persistBatches();
+  }
+
+  /** HUMAN_INBOX_BATCH — каденция human-inbox (человек пишет долго,
+   *  мгновенный триггер схватил бы недоделанное). */
+  function runHumanInboxBatch(): void {
+    if (!vaultAvailable()) return;
+    const next = snapshotFlatFolder(humanInboxDir);
+    const names = diffSnapshots(humanInboxBaseline, next);
+    humanInboxBaseline = next;
+    if (names.length) {
+      const absPaths = names.map((n) => path.join(humanInboxDir, n));
+      logger.info(`human-inbox batch: ${absPaths.length} draft(s)`);
+      emit(`HUMAN_INBOX_BATCH: ${JSON.stringify(absPaths)}`);
+    }
+    persistBatches();
   }
 
   function schedule(absPath: string): void {
@@ -641,6 +787,43 @@ export async function startMemoryd(opts: MemorydOptions): Promise<MemorydHandle>
   const persistTimer = setInterval(persistQuiet, persistMs);
   persistTimer.unref?.();
 
+  // ── cadence timers (директива ~15:31): первый прогон через полный период
+  const permanentBatchMs = opts.permanentBatchMs ?? config.batch.permanentMs;
+  const permanentTimer = setInterval(() => {
+    try {
+      runPermanentBatch();
+    } catch (err) {
+      logger.error(`permanent batch failed: ${String(err)}`);
+    }
+  }, permanentBatchMs);
+  permanentTimer.unref?.();
+  // HUMAN-INBOX: раз в СУТКИ в config.batch.humanInboxHour локального
+  // (подтверждение Артура ~15:4x: ночная партия, как в старом контуре).
+  // Тестовый override opts.humanInboxBatchMs — простой интервал.
+  let humanInboxTimer: ReturnType<typeof setTimeout> | null = null;
+  function scheduleHumanInbox(): void {
+    let delay: number;
+    if (opts.humanInboxBatchMs !== undefined) {
+      delay = opts.humanInboxBatchMs;
+    } else {
+      const now = new Date();
+      const next = new Date(now);
+      next.setHours(config.batch.humanInboxHour, 0, 0, 0);
+      if (next.getTime() <= now.getTime()) next.setDate(next.getDate() + 1);
+      delay = next.getTime() - now.getTime();
+    }
+    humanInboxTimer = setTimeout(() => {
+      try {
+        runHumanInboxBatch();
+      } catch (err) {
+        logger.error(`human-inbox batch failed: ${String(err)}`);
+      }
+      scheduleHumanInbox();
+    }, delay);
+    humanInboxTimer.unref?.();
+  }
+  scheduleHumanInbox();
+
   // ── MCP http ──
   let mcp: { port: number; close: () => Promise<void> } | null = null;
   if (opts.mcpPort !== null) {
@@ -653,6 +836,10 @@ export async function startMemoryd(opts: MemorydOptions): Promise<MemorydHandle>
 
   return {
     mcpPort: mcp?.port ?? null,
+    runBatchPass: (kind) => {
+      if (kind === "permanent") runPermanentBatch();
+      else runHumanInboxBatch();
+    },
     runDetectPass: async () => {
       if (flushTimer) {
         clearTimeout(flushTimer);
@@ -665,6 +852,8 @@ export async function startMemoryd(opts: MemorydOptions): Promise<MemorydHandle>
       watcher?.close();
       if (flushTimer) clearTimeout(flushTimer);
       clearInterval(heartbeatTimer);
+      clearInterval(permanentTimer);
+      if (humanInboxTimer) clearTimeout(humanInboxTimer);
       clearInterval(persistTimer);
       await flushing;
       persistQuiet();

package/src/permanent-detect.ts

@@ -108,3 +108,52 @@ export function detectPermanentChanges(opts: {
 export function formatEventLines(event: PermanentChangedEvent): string[] {
   return event.paths.map((p) => `PERMANENT_CHANGED: ${p}`);
 }
+
+/**
+ * Inbox snapshot: draft basename → smart hash (top-level `.md` only —
+ * drafts live flat). Same smart-hash mechanics as the permanent snapshot:
+ * service-field re-stamps are invisible, content edits are events.
+ *
+ * WHY hash-diff and not a name baseline (B-приёмка 10.06, boris): the
+ * original name-set baseline made a draft INVISIBLE FOREVER once it
+ * survived a memoryd restart, and silently broke the reject→fix→re-review
+ * cycle (an author's fix never re-entered the pipeline). The reference
+ * semantics «the Index catches pre-existing drafts up at its own start»
+ * died with the inversion — the Index no longer scans the inbox; the
+ * fail-open sweep covers pre-existing UNCHANGED drafts, the hash-diff
+ * covers everything else.
+ */
+export function snapshotFlatFolder(dir: string): VaultSnapshot {
+  const snapshot: VaultSnapshot = new Map();
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return snapshot;
+  }
+  for (const e of entries) {
+    if (!e.isFile() || !e.name.endsWith(".md")) continue;
+    const h = hashFile(path.join(dir, e.name));
+    if (h) snapshot.set(e.name, h);
+  }
+  return snapshot;
+}
+
+export function snapshotInbox(vault: string, taxonomy: TaxonomyPreset): VaultSnapshot {
+  return snapshotFlatFolder(path.join(vault, taxonomy.folders.inbox));
+}
+
+/**
+ * One inbox detection pass: new or semantically changed drafts since the
+ * previous snapshot (deletions ignored — a placement move by the Index).
+ * Scans the WHOLE inbox folder, independent of which fs.watch path
+ * triggered the flush — no dependency on watch filename fidelity.
+ */
+export function detectInboxChanges(opts: {
+  vault: string;
+  taxonomy: TaxonomyPreset;
+  prev: VaultSnapshot;
+}): { names: string[]; next: VaultSnapshot } {
+  const next = snapshotInbox(opts.vault, opts.taxonomy);
+  return { names: diffSnapshots(opts.prev, next), next };
+}

package/src/render-doctrine.ts

@@ -55,6 +55,12 @@ export function renderDoctrine(opts: {
   templatePath: string;
   peerCwd: string;
   version: string;
+  /** Host vault root — substituted for `{{VAULT_PATH}}` in the template.
+   *  B-приёмка incident 10.06: a role peer that didn't KNOW the vault root
+   *  guessed it with `find` and read a STALE git copy of the vault —
+   *  wrong-world metadata broke the echo-breaker downstream. The doctrine
+   *  must carry the host fact. */
+  vaultPath?: string;
 }): RenderOutcome {
   const target = path.join(opts.peerCwd, ".iapeer", "IAPEER.md");
 
@@ -65,7 +71,10 @@ export function renderDoctrine(opts: {
     return { action: "missing-template", target };
   }
 
-  const body = stripTemplateFrontmatter(template);
+  const body = stripTemplateFrontmatter(template).replaceAll(
+    "{{VAULT_PATH}}",
+    opts.vaultPath ?? "<unknown — see IAPEER_MEMORY_VAULT_PATH in the package config.env>",
+  );
   const rendered = `${versionMarker(opts.version)}\n${body.startsWith("\n") ? body.slice(1) : body}`;
 
   let existing: string | null = null;