@agfpd/iapeer-memory 0.1.12 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer-memory",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "iapeer-memory — peer memory for the iapeer ecosystem: vault, memoryd (index/search/MCP-http), layer-5 context fragments, role doctrines. The package IS the system; the claude/codex plugins are thin session sockets (docs/10-distribution.md, ADR-009).",
   "license": "MIT",
   "type": "module",
@@ -27,7 +27,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@agfpd/iapeer-memory-core": "0.1.12"
+    "@agfpd/iapeer-memory-core": "0.1.13"
   },
   "devDependencies": {
     "@types/bun": "^1.2.0",

package/src/commands/init.ts

@@ -34,6 +34,7 @@ import { memoryPaths } from "../paths.js";
 import { provisionVault, writeDefaultConfig } from "../provision.js";
 import { writeRolesManifest, type RoleEntry } from "../roles.js";
 import { applyMemoryPlugin, writeSlot } from "../slot.js";
+import { writeFleetMap } from "../fleet.js";
 import {
   doctrineOwnership,
   guideText,
@@ -340,6 +341,27 @@ export async function cmdInit(argv: string[]): Promise<number> {
     );
   }
 
+  // 6b. fleet map — personality → cwd for memoryd's fragment renderer
+  // (docs/05; дыра 10.06: без карты пиры не получали paths-блок и индекс).
+  // ПЕРЕД watcher-регистрацией: memoryd, поднятый notifier'ом, рендерит
+  // весь флот уже на старте. Roles-степ выше уже создал ролевых пиров —
+  // карта включает их.
+  if (flags.skipEcosystem) {
+    step("fleet", "skipped (--skip-ecosystem)");
+  } else {
+    const fleet = writeFleetMap({
+      fleetMapPath: paths.fleetMapPath,
+      iapeerBin: flags.iapeerBin,
+    });
+    step(
+      "fleet",
+      fleet.action === "written"
+        ? fleet.detail
+        : `fleet map not written (${fleet.detail}) — fragments stay off until verify --repair`,
+      fleet.action === "written",
+    );
+  }
+
   // 7. notifier wiring (ADR-015, инверсия): the EVENT trigger targets the
   // SCRIBER (first receiver); two TIMERS target the index — weekly
   // DREAM_TICK and the check-gated fail-open sweep. Registrant = index for
@@ -448,7 +470,9 @@ export async function cmdInit(argv: string[]): Promise<number> {
   if (flags.skipGuide) {
     step("guide", "skipped (--skip-guide) — roll out by a separate decision after the fleet plugin swap");
   } else {
-    const guidePath = writeHostWideGuideFragment(iapeerDir, guideText(locale));
+    // vault substituted into the {{VAULT_PATH}} marker (дыра 10.06: the
+    // literal placeholder left peers without the write path).
+    const guidePath = writeHostWideGuideFragment(iapeerDir, guideText(locale, vault));
     step("guide", guidePath);
   }
 

package/src/commands/memoryd.ts

@@ -18,7 +18,7 @@
 
 import fs from "node:fs";
 import { configFromEnv, startMemoryd } from "@agfpd/iapeer-memory-core";
-import { memoryPaths } from "../paths.js";
+import { authorIndexPath, memoryPaths } from "../paths.js";
 
 export async function cmdMemoryd(argv: string[]): Promise<number> {
   let mcpPort: number | undefined;
@@ -72,6 +72,23 @@ export async function cmdMemoryd(argv: string[]): Promise<number> {
     humanName: human ?? process.env.IAPEER_MEMORY_HUMAN_NAME ?? null,
     freshEditWindowS,
     mcpPort: noMcp ? null : mcpPort,
+    // Per-peer fragment rendering (docs/05; дыра 10.06): the package owns
+    // the ecosystem joint — fleet-map path + paths-block facts; core
+    // renders at startup, on vault changes and on fleet-map changes.
+    fragments: {
+      fleetMapPath: paths.fleetMapPath,
+      paths: {
+        vault: config.vaultPath,
+        db: config.index.dbPath,
+        config: paths.configFile,
+        state: paths.stateDir,
+        cache: paths.cacheDir,
+        logs: paths.logsDir,
+      },
+      authorIndexPathFor: (agent) => authorIndexPath(paths, agent),
+      indexAgent: process.env.IAPEER_MEMORY_INDEX_AGENT || "index",
+      projectsRoot: process.env.IAPEER_MEMORY_PROJECTS_ROOT || undefined,
+    },
   });
 
   return await new Promise<number>((resolve) => {

package/src/commands/render.ts

@@ -166,7 +166,14 @@ function renderGuide(argv: string[]): number {
         "the whole fleet — the target is never implicit)",
     );
   }
-  const text = fs.readFileSync(source, "utf-8");
+  let text = fs.readFileSync(source, "utf-8");
+  // {{VAULT_PATH}} marker → host fact (дыра 10.06); unprovisioned env
+  // keeps the marker — an honest template passthrough, never a guess.
+  try {
+    text = text.replaceAll("{{VAULT_PATH}}", configFromEnv().vaultPath);
+  } catch {
+    // no config — leave the marker as is
+  }
   const written = writeHostWideGuideFragment(target, text);
   console.log(`render guide: ${written}`);
   return 0;

package/src/commands/update.ts

@@ -24,17 +24,21 @@
  * Idempotent: same version re-run → identical/no-op on every surface.
  */
 
+import fs from "node:fs";
+import path from "node:path";
 import {
   configFromEnv,
   isLocaleId,
   renderDoctrine,
+  writeHostWideGuideFragment,
   type LocaleId,
 } from "@agfpd/iapeer-memory-core";
 import { installBinary } from "../binary.js";
+import { writeFleetMap } from "../fleet.js";
 import { memoryPaths } from "../paths.js";
 import { readRolesManifest } from "../roles.js";
 import { writeSlot } from "../slot.js";
-import { materialiseTemplates } from "../templates/index.js";
+import { guideText, materialiseTemplates } from "../templates/index.js";
 import { packageVersion } from "../version.js";
 import {
   dreamTimerMessage,
@@ -169,6 +173,37 @@ export function cmdUpdate(argv: string[]): number {
     );
   }
 
+  // 5c. host-wide guide — update an ALREADY-ROLLED-OUT guide only
+  // (presence = the rollout sanction; init --skip-guide hosts stay
+  // untouched). Vault substituted into {{VAULT_PATH}} (дыра 10.06: the
+  // literal placeholder left peers without the write path).
+  {
+    const iapeerDir = path.dirname(paths.slotPath);
+    const guidePath = path.join(iapeerDir, "fragments", "iapeer-memory.md");
+    if (!fs.existsSync(guidePath)) {
+      step("guide", "not rolled out on this host — left untouched (roll out via init)");
+    } else if (!vaultPathForDoctrines) {
+      step("guide", "unprovisioned env — vault unknown, guide left as is", false);
+    } else {
+      writeHostWideGuideFragment(iapeerDir, guideText(locale, vaultPathForDoctrines));
+      step("guide", `${guidePath} re-written (v${version}, vault path substituted)`);
+    }
+  }
+
+  // 5d. fleet map — personality → cwd for memoryd's fragment renderer
+  // (docs/05; дыра 10.06). BEFORE the memoryd restart below: the fresh
+  // daemon renders the whole fleet at startup from this very map.
+  {
+    const fleet = writeFleetMap({ fleetMapPath: paths.fleetMapPath });
+    step(
+      "fleet",
+      fleet.action === "written"
+        ? fleet.detail
+        : `fleet map not written (${fleet.detail}) — fragments stay stale until verify --repair`,
+      fleet.action === "written",
+    );
+  }
+
   // 6. memoryd managed restart (the watcher relaunches with the new binary)
   step("memoryd", `${stopMemorydByPidFile(paths.pidPath)} — the notifier watcher relaunches it with the new binary`);
 

package/src/commands/verify.ts

@@ -25,6 +25,7 @@ import {
   renderDoctrine,
   renderedVersion,
 } from "@agfpd/iapeer-memory-core";
+import { writeFleetMap } from "../fleet.js";
 import { memoryPaths, type MemoryPaths } from "../paths.js";
 import { readRolesManifest } from "../roles.js";
 import { readSlot, writeSlot, SLOT_PROVIDER } from "../slot.js";
@@ -131,6 +132,43 @@ export function runVerify(opts: VerifyOptions = {}): CheckResult[] {
     }
   }
 
+  // 1c. fleet map — memoryd's fragment renderer reads it (docs/05; дыра
+  // 10.06: без карты пиры не получали paths-блок и индекс автора). Repair
+  // re-writes from `iapeer list --json` — the self-healing loop for new
+  // peers (SessionStart kick → repair → map fresh → memoryd renders the
+  // newcomer on the next heartbeat tick).
+  if (!configOk) {
+    results.push({ name: "fleet-map", status: "skip", detail: "not provisioned (config check failed)" });
+  } else {
+    let mapPeers = -1; // -1 = unreadable/missing
+    try {
+      const raw = JSON.parse(fs.readFileSync(paths.fleetMapPath, "utf-8")) as {
+        peers?: unknown[];
+      };
+      mapPeers = Array.isArray(raw?.peers) ? raw.peers.length : -1;
+    } catch {
+      mapPeers = -1;
+    }
+    if (mapPeers > 0) {
+      results.push({ name: "fleet-map", status: "ok", detail: `${mapPeers} peer(s) in ${paths.fleetMapPath}` });
+    } else {
+      const problem =
+        mapPeers === 0
+          ? `fleet map is empty at ${paths.fleetMapPath}`
+          : `fleet map missing/unreadable at ${paths.fleetMapPath}`;
+      if (!repair) {
+        results.push({ name: "fleet-map", status: "fail", detail: problem });
+      } else {
+        const w = writeFleetMap({ fleetMapPath: paths.fleetMapPath, iapeerBin: opts.iapeerBin });
+        results.push(
+          w.action === "written"
+            ? { name: "fleet-map", status: "repaired", detail: `${problem} — ${w.detail}` }
+            : { name: "fleet-map", status: "fail", detail: `${problem}; repair failed — ${w.detail}` },
+        );
+      }
+    }
+  }
+
   // 2. memoryd heartbeat
   try {
     const stat = fs.statSync(paths.heartbeatPath);

package/src/fleet.ts

@@ -0,0 +1,85 @@
+/**
+ * Fleet map — the personality → cwd joint between the package (ecosystem
+ * knowledge, ADR-009) and core memoryd's per-peer fragment renderer
+ * (docs/05). Written from `iapeer list --json` (the registry cwd is the
+ * FACT — iapeer 0.2.14); memoryd reads it fail-open and re-checks the
+ * mtime on every heartbeat tick, so the self-healing loop is:
+ * new peer wakes → SessionStart kick → `verify --repair` re-writes the
+ * map → memoryd renders the newcomer's fragment within a tick.
+ *
+ * `iapeer list` is READ-ONLY on the host — no test fuse needed here
+ * (the fuse class guards host MUTATIONS); deterministic tests pass a
+ * fake `iapeerBin` instead.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+export type FleetMapResult = {
+  action: "written" | "failed";
+  count: number;
+  detail: string;
+};
+
+type ListedPeer = { personality?: unknown; cwd?: unknown };
+
+export function writeFleetMap(opts: {
+  fleetMapPath: string;
+  iapeerBin?: string;
+  /** Injectable for tests. */
+  nowIso?: string;
+}): FleetMapResult {
+  const bin = opts.iapeerBin ?? "iapeer";
+  let stdout: string;
+  try {
+    const proc = Bun.spawnSync([bin, "list", "--json"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (proc.exitCode !== 0) {
+      return {
+        action: "failed",
+        count: 0,
+        detail:
+          (proc.stderr.toString().trim() || `iapeer list exited ${proc.exitCode}`).slice(0, 160),
+      };
+    }
+    stdout = proc.stdout.toString();
+  } catch (err) {
+    return { action: "failed", count: 0, detail: `${bin} unavailable: ${String(err)}` };
+  }
+
+  let listed: ListedPeer[];
+  try {
+    const raw = JSON.parse(stdout) as unknown;
+    listed = Array.isArray(raw) ? (raw as ListedPeer[]) : [];
+  } catch {
+    return { action: "failed", count: 0, detail: "iapeer list --json: unparsable output" };
+  }
+
+  const peers = listed
+    .filter(
+      (p): p is { personality: string; cwd: string } =>
+        typeof p.personality === "string" &&
+        p.personality.trim() !== "" &&
+        typeof p.cwd === "string" &&
+        p.cwd.trim() !== "",
+    )
+    .map((p) => ({ personality: p.personality.trim(), cwd: p.cwd.trim() }));
+
+  const body =
+    JSON.stringify(
+      { updatedAt: opts.nowIso ?? new Date().toISOString(), peers },
+      null,
+      2,
+    ) + "\n";
+  fs.mkdirSync(path.dirname(opts.fleetMapPath), { recursive: true });
+  const tmp = `${opts.fleetMapPath}.tmp`;
+  fs.writeFileSync(tmp, body, "utf-8");
+  fs.renameSync(tmp, opts.fleetMapPath); // atomic — memoryd may race a read
+  return {
+    action: "written",
+    count: peers.length,
+    detail: `${peers.length} peer(s) → ${opts.fleetMapPath}`,
+  };
+}

package/src/paths.ts

@@ -52,6 +52,10 @@ export type MemoryPaths = {
   launcherPath: string;
   /** Sweep check-script — gates the fail-open inbox sweep (ADR-015). */
   checkScriptPath: string;
+  /** Fleet map (personality → cwd) — written by init/update/verify --repair
+   *  from `iapeer list --json`, consumed by memoryd's fragment renderer
+   *  (docs/05; дыра 10.06: без карты пиры не получали paths-блок и индекс). */
+  fleetMapPath: string;
 };
 
 export function memoryPaths(
@@ -90,6 +94,7 @@ export function memoryPaths(
     templatesDir: path.join(path.dirname(configFile), "templates"),
     launcherPath: path.join(path.dirname(configFile), "memoryd-launcher.sh"),
     checkScriptPath: path.join(path.dirname(configFile), "inbox-stale-check.sh"),
+    fleetMapPath: path.join(stateDir, "fleet.json"),
   };
 }
 

package/src/templates/guide-en.ts

@@ -46,7 +46,7 @@ with zero graph connections — check with \`vault_graph\` first).
 Write the BARE BODY only — no frontmatter, no links section (the post-write
 hook stamps the 4 draft fields; the links section belongs to the Index):
 
-    Write("<vault>/00_Inbox/<Meaningful title>.md", "<body>")
+    Write("{{VAULT_PATH}}/00_Inbox/<Meaningful title>.md", "<body>")
 
 Canon style: idiomatic vault language, academic tone, self-contained text
 (no dialogue references, expand abbreviations on first use), no emoji.

package/src/templates/guide-ru.ts

@@ -44,7 +44,7 @@ iapeer-memory — общая память команды (агенты + чел
 Пиши ГОЛОЕ ТЕЛО — без frontmatter и без секции связей (post-write хук
 проставит 4 поля черновика; секция связей — зона Индекса):
 
-    Write("<vault>/00_Входящие/<Понятное название>.md", "<тело>")
+    Write("{{VAULT_PATH}}/00_Входящие/<Понятное название>.md", "<тело>")
 
 Стиль канона: идиоматичный русский, академический тон, самодостаточный
 текст (без отсылок к диалогу, аббревиатуры расшифровывай при первом

package/src/templates/index.ts

@@ -95,8 +95,17 @@ export function roleDoctrineTemplate(locale: LocaleId, role: RoleName): string {
   return ROLES[locale][role];
 }
 
-export function guideText(locale: LocaleId): string {
-  return GUIDES[locale];
+/**
+ * Writer-guide text. With `vaultPath` the `{{VAULT_PATH}}` marker is
+ * substituted (host fact — дыра 10.06: the host-wide guide shipped the
+ * write-path as a literal placeholder, peers could not know where to
+ * write); without it the marker is preserved — that is the TEMPLATE form
+ * (materialiseTemplates keeps templates host-neutral).
+ */
+export function guideText(locale: LocaleId, vaultPath?: string): string {
+  const text = GUIDES[locale];
+  if (!vaultPath) return text;
+  return text.replaceAll("{{VAULT_PATH}}", vaultPath);
 }
 
 /** Stable on-disk path of a materialised role template. */