@agfpd/iapeer-memory 0.1.1

package/src/roles.ts

@@ -0,0 +1,43 @@
+/**
+ * Roles manifest — the init→verify bridge (`<state>/roles.json`):
+ * which role peers exist, where their cwd is, which template renders their
+ * doctrine. init writes it after `iapeer create`; verify reads it to
+ * compare rendered doctrine versions against the package (ADR-010) and
+ * `--repair` re-renders from the referenced templates.
+ *
+ * Role peer location: the CORE'S DEFAULT (`iapeer create` without
+ * `--path` → its documented default peers folder). Host-specific layouts
+ * must never leak into the product (требование Артура, 10.06).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+export type RoleEntry = { role: string; peerCwd: string; template: string };
+
+export type RolesManifest = { roles: RoleEntry[] };
+
+export function writeRolesManifest(opts: {
+  rolesManifestPath: string;
+  roles: RoleEntry[];
+}): void {
+  fs.mkdirSync(path.dirname(opts.rolesManifestPath), { recursive: true });
+  const tmp = `${opts.rolesManifestPath}.tmp`;
+  fs.writeFileSync(
+    tmp,
+    JSON.stringify({ roles: opts.roles } satisfies RolesManifest, null, 2) + "\n",
+    "utf-8",
+  );
+  fs.renameSync(tmp, opts.rolesManifestPath);
+}
+
+/** Never throws: absent/malformed → null (verify treats it as "init has not run"). */
+export function readRolesManifest(rolesManifestPath: string): RolesManifest | null {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(rolesManifestPath, "utf-8")) as RolesManifest;
+    if (!Array.isArray(parsed.roles)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}

package/src/slot.ts

@@ -0,0 +1,89 @@
+/**
+ * Memory-provider slot declaration — the iapeer memory-slot contract (FINAL,
+ * iapeer docs fc68c54/e2195a7/c968219). The slot file tells the core that
+ * the three public surfaces (layer-5 fragments / MCP tools / daemon under a
+ * notifier watcher) are occupied:
+ *
+ * - the PROVIDER writes and removes the file (our init/uninstall), atomic
+ *   temp+rename; the core only reads it (absent/unreadable = empty slot);
+ * - a slot held by a FOREIGN provider is never touched — explicit refusal
+ *   (mirror of the core's own init-step refusal);
+ * - `version` = the package version (the same single source as the doctrine
+ *   marker, ADR-010); our `update` re-writes it (P4 obligation);
+ * - `heartbeat` (optional) = the absolute path whose mtime memoryd touches —
+ *   the core may show staleness in `iapeer status`, never acts on it.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const SLOT_PROVIDER = "iapeer-memory";
+export const SLOT_PACKAGE = "@agfpd/iapeer-memory";
+
+export type MemoryProviderSlot = {
+  provider: string;
+  package: string;
+  version: string;
+  registeredAt: string;
+  heartbeat?: string;
+};
+
+/** Never throws: missing / unreadable / malformed → null (empty slot). */
+export function readSlot(slotPath: string): MemoryProviderSlot | null {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(slotPath, "utf-8")) as MemoryProviderSlot;
+    if (!parsed || typeof parsed.provider !== "string") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export type SlotWriteResult = {
+  action: "written" | "identical" | "refused-foreign";
+  existing: MemoryProviderSlot | null;
+};
+
+export function writeSlot(opts: {
+  slotPath: string;
+  version: string;
+  heartbeat?: string;
+  /** Injectable for tests. */
+  nowIso?: string;
+}): SlotWriteResult {
+  const existing = readSlot(opts.slotPath);
+  if (existing && existing.provider !== SLOT_PROVIDER) {
+    return { action: "refused-foreign", existing };
+  }
+  if (
+    existing &&
+    existing.version === opts.version &&
+    existing.heartbeat === opts.heartbeat &&
+    existing.package === SLOT_PACKAGE
+  ) {
+    return { action: "identical", existing }; // idempotent re-init: no churn
+  }
+  const slot: MemoryProviderSlot = {
+    provider: SLOT_PROVIDER,
+    package: SLOT_PACKAGE,
+    version: opts.version,
+    registeredAt: opts.nowIso ?? new Date().toISOString(),
+    ...(opts.heartbeat ? { heartbeat: opts.heartbeat } : {}),
+  };
+  fs.mkdirSync(path.dirname(opts.slotPath), { recursive: true });
+  const tmp = `${opts.slotPath}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(slot, null, 2) + "\n", "utf-8");
+  fs.renameSync(tmp, opts.slotPath);
+  return { action: "written", existing };
+}
+
+export type SlotRemoveResult = "removed" | "absent" | "refused-foreign";
+
+/** Uninstall removes ONLY our own declaration; a foreign slot is left intact. */
+export function removeSlot(slotPath: string): SlotRemoveResult {
+  const existing = readSlot(slotPath);
+  if (!existing) return "absent";
+  if (existing.provider !== SLOT_PROVIDER) return "refused-foreign";
+  fs.unlinkSync(slotPath);
+  return "removed";
+}

package/src/sync-versions.ts

@@ -0,0 +1,110 @@
+/**
+ * Manifest version sync (docs/10 §Версионная синхронизация): propagate the
+ * facade `package/package.json` version into every other manifest of the
+ * monorepo — `core/package.json` + `adapters/{claude,codex}` plugin
+ * manifests. Wired into the npm `version` lifecycle, runnable standalone:
+ *
+ *     bun src/sync-versions.ts
+ *
+ * Missing manifests are reported and skipped (the adapters land in P2/P5 —
+ * the script must not fail before they exist). The MergeMind
+ * sync-plugin-version pattern, generalised to N manifests.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+export type SyncOutcome = { file: string; action: "updated" | "identical" | "missing" };
+
+/** Relative (to the monorepo root) manifests that must carry one version. */
+export const SYNC_TARGETS = [
+  "core/package.json",
+  "adapters/claude/.claude-plugin/plugin.json",
+  "adapters/codex/.codex-plugin/plugin.json",
+] as const;
+
+export function syncVersions(opts: {
+  rootDir: string;
+  version: string;
+  targets?: readonly string[];
+}): SyncOutcome[] {
+  const targets = opts.targets ?? SYNC_TARGETS;
+  const outcomes: SyncOutcome[] = [];
+  for (const rel of targets) {
+    const file = path.join(opts.rootDir, rel);
+    let raw: string;
+    try {
+      raw = fs.readFileSync(file, "utf-8");
+    } catch {
+      outcomes.push({ file: rel, action: "missing" });
+      continue;
+    }
+    const manifest = JSON.parse(raw) as Record<string, unknown>;
+    if (manifest.version === opts.version) {
+      outcomes.push({ file: rel, action: "identical" });
+      continue;
+    }
+    manifest.version = opts.version;
+    // 2-space indent + trailing newline — the repo's manifest style.
+    fs.writeFileSync(file, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+    outcomes.push({ file: rel, action: "updated" });
+  }
+  return outcomes;
+}
+
+/**
+ * The facade's dependency on the core is an EXACT version pin kept in
+ * lockstep by this script (release decision: two npm packages, one shared
+ * version). `npm publish` ships the manifest verbatim — it does NOT
+ * rewrite the `workspace:*` protocol (only bun/pnpm publish do), so the
+ * pin on disk is the published truth. Locally the exact pin still resolves
+ * to the workspace copy: bun matches workspace packages against semver
+ * ranges, and syncVersions keeps core/package.json at the same version.
+ */
+export function syncCoreDependencyPin(opts: {
+  packageManifestPath: string;
+  version: string;
+}): SyncOutcome {
+  const rel = path.basename(opts.packageManifestPath);
+  let raw: string;
+  try {
+    raw = fs.readFileSync(opts.packageManifestPath, "utf-8");
+  } catch {
+    return { file: rel, action: "missing" };
+  }
+  const manifest = JSON.parse(raw) as {
+    dependencies?: Record<string, string>;
+  };
+  const deps = manifest.dependencies ?? {};
+  if (deps["@agfpd/iapeer-memory-core"] === opts.version) {
+    return { file: rel, action: "identical" };
+  }
+  deps["@agfpd/iapeer-memory-core"] = opts.version;
+  manifest.dependencies = deps;
+  fs.writeFileSync(
+    opts.packageManifestPath,
+    JSON.stringify(manifest, null, 2) + "\n",
+    "utf-8",
+  );
+  return { file: rel, action: "updated" };
+}
+
+if (import.meta.main) {
+  const pkgDir = path.dirname(path.dirname(new URL(import.meta.url).pathname));
+  const pkg = JSON.parse(
+    fs.readFileSync(path.join(pkgDir, "package.json"), "utf-8"),
+  ) as { version: string };
+  const outcomes = syncVersions({
+    rootDir: path.dirname(pkgDir),
+    version: pkg.version,
+  });
+  outcomes.push(
+    syncCoreDependencyPin({
+      packageManifestPath: path.join(pkgDir, "package.json"),
+      version: pkg.version,
+    }),
+  );
+  for (const o of outcomes) {
+    console.log(`sync-versions: ${o.action.padEnd(9)} ${o.file}`);
+  }
+}

package/src/templates/guide-en.ts

@@ -0,0 +1,103 @@
+/**
+ * Writer's guide — EN base. The HOST-WIDE layer-5 fragment: every peer of
+ * the fleet reads this on every cold wake (ADR-001). Token-frugal by
+ * design — bloat here costs the whole team on every session. Source of
+ * truth: docs/01–05; the style base is the proven MergeMind guide.
+ */
+
+export const GUIDE_EN = `# iapeer-memory — the team's shared memory
+
+iapeer-memory is the team's shared memory (agents + human): the canon
+(knowledge / decisions / ideas / projects / lists) plus each agent's
+personal memory. You read it and you write it.
+
+**Search the memory first.** Someone may have already solved your problem
+and written it down. Use \`vault_search\` (then \`Read\` the note),
+\`vault_graph\` for a note's neighborhood, \`vault_map\` for the global map.
+
+**Verify before acting.** A note is a snapshot at write time. Check that
+the function/file/flag still exists — especially before the user acts on
+your recommendation.
+
+**On a conflict between memory and observation — trust the observation.**
+Update or deprecate the stale note. This is living memory.
+
+## Write proactively — you don't exist between sessions
+
+A session is ephemeral: when it ends, the context is gone. The vault is
+the ONLY thing that survives. Not written down → lost forever.
+
+Write without asking permission. A meaningful result (a fix, a decision,
+a pitfall, feedback, a system nuance) is recorded immediately, by you.
+Canon material → a draft in \`00_Inbox/\`; personal material → your own
+agent-memory folder. Asking the human "should I write this down?" is an
+anti-pattern.
+
+**Write concisely.** Notes are injected into readers' contexts; bloat
+costs tokens for the whole team.
+
+**Sweep as you write.** Added or updated a note → immediately check
+whether an older note on the same topic became stale: flip its \`status\`
+to the final token, or delete it (your own memory notes only, and only
+with zero graph connections — check with \`vault_graph\` first).
+
+## Canon drafts → \`00_Inbox/\`
+
+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>")
+
+Canon style: idiomatic vault language, academic tone, self-contained text
+(no dialogue references, expand abbreviations on first use), no emoji.
+The canon's viewpoint is objective knowledge about a system — your
+personal "how I do it" belongs in your agent memory instead. Mark
+hypotheses as hypotheses. The filename IS the title readers will see in
+their index — make it understandable without opening the file.
+
+## Your agent memory → \`06_Agent_Memory/<your name>/\`
+
+Personal notes useful to you, written directly (no inbox). Frontmatter:
+only \`subtype\` + \`description\`, the hook fills the rest:
+
+    ---
+    subtype: <one of below>
+    description: "1–2 sentences on the content"
+    ---
+    <body>
+
+Five \`subtype\` values: \`feedback\` (from colleagues), \`context\`
+(project/task handoff), \`reference\` (your navigation marks and
+procedures), \`person_profile\` (facts about a person), \`pitfall\`
+(a rule born from one incident — stepped on it once, wrote it down).
+
+Material that is BOTH team knowledge and personal → do both: a draft in
+\`00_Inbox/\` + a memory note mentioning it inline as \`[[Draft title]]\`.
+
+## Editing rules
+
+Edit the BODY of your own notes freely (you are \`author\` or in
+\`coauthors\`) — reword, update, replace stale text in place; no
+"Update YYYY-MM-DD" journals. Additions to FOREIGN notes go through a new
+inbox draft (the Index merges and adds you to \`coauthors\`).
+
+From the frontmatter you change ONLY \`status\`, by your note type's scale
+(knowledge/list/memory: current → outdated; idea: new → in_progress /
+dropped; decision: accepted → superseded; project files: active → paused /
+completed; phases: planned → active → completed / paused / cancelled).
+The decision STATEMENT in \`02_Decisions/\` is immutable — supersede it
+with a new draft instead. \`needs_review\` is the Index's field, not yours.
+Never edit the links section, tags, \`type\`, or another agent's memory
+folder.
+
+Deletion (\`rm\`) — only in YOUR memory folder and only at zero
+connections (\`vault_graph\` first); otherwise flip \`status\` and let the
+Index archive. Renames — same watershed.
+
+## Projects
+
+\`Plan <name>.md\` = the high-level phase list; \`Phase — <title>.md\` =
+that phase's task checklist. Both are append-only: add, don't rewrite
+history. The full Plan text is read with \`Read\` — the path is in your
+index.
+`;

package/src/templates/guide-ru.ts

@@ -0,0 +1,99 @@
+/**
+ * Гайд писателя — RU-пресет. Host-wide фрагмент слоя 5; см. заголовок
+ * guide-en.ts. Семантическое зеркало EN-базы с RU-таксономией; стилевая
+ * база — живой гайд MergeMind.
+ */
+
+export const GUIDE_RU = `# iapeer-memory — общая память команды
+
+iapeer-memory — общая память команды (агенты + человек): канон
+(знания / решения / идеи / проекты / списки) + личная оперативка каждого
+агента. Ты читаешь и пишешь.
+
+**Перед ответом — сначала ищи в памяти.** Кто-то мог решить эту задачу и
+записать. \`vault_search\` (найденное читай \`Read\`), \`vault_graph\` —
+окрестность заметки, \`vault_map\` — глобальная карта.
+
+**Проверяй прежде чем действовать.** Заметка — снимок на момент записи.
+Проверь, что функция/файл/флаг существуют сейчас — особенно когда
+пользователь собирается действовать по твоей рекомендации.
+
+**При конфликте память vs наблюдение — доверяй наблюдению.** Обнови или
+депрекируй устаревшую заметку. Память живая.
+
+## Пиши проактивно — между сессиями тебя нет
+
+Сессия эфемерна: завершится — контекст исчезнет. Vault — единственное,
+что выживает. Не записал → потеряно навсегда.
+
+Пиши без спроса. Осмысленный результат (фикс, решение, грабли, фидбек,
+нюанс системы) фиксируется сразу, тобой. Канон — черновиком в
+\`00_Входящие/\`; личное — в свою оперативку. Вопрос человеку «записать
+ли?» — анти-паттерн.
+
+**Пиши кратко.** Заметки инжектятся в контекст читателей; раздутость
+стоит токенов всей команде.
+
+**Подметай за собой — там же, сразу.** Записал или обновил заметку →
+проверь, не устарела ли прежняя по теме: ставь финальный \`status\` или
+удаляй (только свою оперативку и только при нуле связей — сначала
+\`vault_graph\`).
+
+## Канон-черновики → \`00_Входящие/\`
+
+Пиши ГОЛОЕ ТЕЛО — без frontmatter и без секции связей (post-write хук
+проставит 4 поля черновика; секция связей — зона Индекса):
+
+    Write("<vault>/00_Входящие/<Понятное название>.md", "<тело>")
+
+Стиль канона: идиоматичный русский, академический тон, самодостаточный
+текст (без отсылок к диалогу, аббревиатуры расшифровывай при первом
+упоминании), без эмодзи. Ракурс канона — объективное знание о системе;
+личное «как я действую» — в оперативку. Гипотезы помечай как гипотезы.
+Имя файла = title, который читатели увидят в индексе — должно быть понятно
+без открытия файла.
+
+## Твоя оперативка → \`06_Оперативка_агентов/<твоё имя>/\`
+
+Личные заметки, полезные тебе, пишутся напрямую (мимо Входящих).
+Frontmatter: только \`subtype\` + \`description\`, остальное дозаполнит хук:
+
+    ---
+    subtype: <одно из ниже>
+    description: «Краткое 1–2 предложения о содержимом»
+    ---
+    <тело>
+
+Пять значений \`subtype\`: \`обратная_связь\` (от коллег), \`контекст\`
+(handoff проекта/задачи), \`справка\` (навигационные метки и процедурные
+приёмы), \`профиль_человека\` (факты о человеке), \`грабли\` (правило после
+конкретного инцидента — наступил раз, записал).
+
+Материал и для команды, и лично тебе → делай оба: черновик во Входящих +
+заметка в оперативке с inline \`[[Название черновика]]\` в теле.
+
+## Правила правок
+
+Тело СВОИХ заметок (ты \`author\` или в \`coauthors\`) правь свободно —
+переформулируй, заменяй устаревшее прямо в тексте; без журналов
+«## Update YYYY-MM-DD». Дополнение к ЧУЖОЙ заметке — новым черновиком во
+Входящих (Индекс сольёт и допишет тебя в \`coauthors\`).
+
+Из frontmatter меняешь ТОЛЬКО \`status\` по шкале типа (знание/список/
+оперативка: актуально → устарело; идея: новая → реализуется / отброшена;
+решение: принято → заменено; файлы проекта: активный → на паузе /
+завершён; фазы: запланирована → активная → завершена / на паузе /
+отменена). Утверждение решения в \`02_Решения/\` иммутабельно — замена
+только новым черновиком. \`needs_review\` — поле Индекса, не твоё.
+Секцию связей, теги, \`type\` и чужую оперативку не трогаешь никогда.
+
+Удаление (\`rm\`) — только своя оперативка и только при нуле связей
+(сначала \`vault_graph\`); иначе финальный \`status\`, заархивирует Индекс.
+Переименование — тот же водораздел.
+
+## Проекты
+
+\`План <имя>.md\` — высокоуровневый список фаз; \`Фаза — <название>.md\` —
+чеклист задач фазы. Оба append-only: дописывай, не переписывай историю.
+Полный текст Плана читается \`Read\` — путь есть в твоём индексе.
+`;

package/src/templates/index.ts

@@ -0,0 +1,105 @@
+/**
+ * Template registry + materialisation. Content is EMBEDDED in the package
+ * (TS constants → bundled into the compiled binary; no fs lookup into an
+ * evictable npx cache). init/update MATERIALISE the templates to
+ * `<plugins>/iapeer-memory/templates/<locale>/…` — the stable on-disk form
+ * the roles manifest points at and `verify --repair` re-renders from.
+ *
+ * Ownership: unlike the vault 99_System seeds (operator-owned, written
+ * once), the materialised templates are PACKAGE-owned runtime artifacts —
+ * they follow the package version and are overwritten on change
+ * (bytes-compare, no mtime churn).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import type { LocaleId } from "@agfpd/iapeer-memory-core";
+import { GUIDE_EN } from "./guide-en.js";
+import { GUIDE_RU } from "./guide-ru.js";
+import {
+  COPYWRITER_DOCTRINE_EN,
+  DREAMWEAVER_DOCTRINE_EN,
+  INDEX_DOCTRINE_EN,
+} from "./roles-en.js";
+import {
+  COPYWRITER_DOCTRINE_RU,
+  DREAMWEAVER_DOCTRINE_RU,
+  INDEX_DOCTRINE_RU,
+} from "./roles-ru.js";
+
+export const ROLE_NAMES = ["index", "copywriter", "dreamweaver"] as const;
+export type RoleName = (typeof ROLE_NAMES)[number];
+
+const ROLES: Record<LocaleId, Record<RoleName, string>> = {
+  en: {
+    index: INDEX_DOCTRINE_EN,
+    copywriter: COPYWRITER_DOCTRINE_EN,
+    dreamweaver: DREAMWEAVER_DOCTRINE_EN,
+  },
+  ru: {
+    index: INDEX_DOCTRINE_RU,
+    copywriter: COPYWRITER_DOCTRINE_RU,
+    dreamweaver: DREAMWEAVER_DOCTRINE_RU,
+  },
+};
+
+const GUIDES: Record<LocaleId, string> = { en: GUIDE_EN, ru: GUIDE_RU };
+
+export function roleDoctrineTemplate(locale: LocaleId, role: RoleName): string {
+  return ROLES[locale][role];
+}
+
+export function guideText(locale: LocaleId): string {
+  return GUIDES[locale];
+}
+
+/** Stable on-disk path of a materialised role template. */
+export function roleTemplatePath(
+  templatesDir: string,
+  locale: LocaleId,
+  role: RoleName,
+): string {
+  return path.join(templatesDir, locale, `${role}.md`);
+}
+
+export function guideTemplatePath(templatesDir: string, locale: LocaleId): string {
+  return path.join(templatesDir, locale, "guide.md");
+}
+
+export type MaterialiseResult = { written: string[]; identical: string[] };
+
+/** Write the locale's templates to disk (package-owned: overwrite on change). */
+export function materialiseTemplates(opts: {
+  templatesDir: string;
+  locale: LocaleId;
+}): MaterialiseResult {
+  const written: string[] = [];
+  const identical: string[] = [];
+  const entries: Array<[string, string]> = [
+    ...ROLE_NAMES.map(
+      (role): [string, string] => [
+        roleTemplatePath(opts.templatesDir, opts.locale, role),
+        roleDoctrineTemplate(opts.locale, role),
+      ],
+    ),
+    [guideTemplatePath(opts.templatesDir, opts.locale), guideText(opts.locale)],
+  ];
+  for (const [file, content] of entries) {
+    let existing: string | null = null;
+    try {
+      existing = fs.readFileSync(file, "utf-8");
+    } catch {
+      existing = null;
+    }
+    if (existing === content) {
+      identical.push(file);
+      continue;
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp`;
+    fs.writeFileSync(tmp, content, "utf-8");
+    fs.renameSync(tmp, file);
+    written.push(file);
+  }
+  return { written, identical };
+}