@agfpd/iapeer-memory-core 0.1.13 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer-memory-core",
-  "version": "0.1.13",
+  "version": "0.2.1",
   "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,7 @@ import {
   type RenderContext,
 } from "./index-render.js";
 import { renderPeerFragment, type FragmentEnv } from "./context-render.js";
+import { guardedWriteFileSync, guardedUnlinkSync } from "./fs-guard.js";
 
 // ── identity ────────────────────────────────────────────────────────────────
 
@@ -442,7 +443,7 @@ export function persistBatchState(
 ): void {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   const tmp = `${filePath}.tmp`;
-  fs.writeFileSync(
+  guardedWriteFileSync(
     tmp,
     JSON.stringify({
       inbox: Object.fromEntries(state.inbox),
@@ -470,7 +471,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);
 }
 
@@ -729,7 +730,7 @@ 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})`);
   }
@@ -776,13 +777,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
         }
@@ -905,7 +906,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 +1021,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
     }