@remnic/core 9.65.8 → 9.66.0

package/src/support-passport/card-service.ts

@@ -832,7 +832,7 @@ export class SupportPassportCardService {
     if (currentCard.card.status === "pending_review") {
       const priorId = currentMemory.frontmatter.supersedes;
       if (!priorId) return currentMemory;
-      const prior = await storage.getMemoryById(priorId);
+      const prior = await storage.getMemoryByIdIncludingArchived(priorId);
       if (
         prior &&
         ownsMemory(prior, namespace, principal) &&
@@ -973,7 +973,10 @@ export class SupportPassportCardService {
     onCommitted?: () => void
   ): Promise<void> {
     if (!replacement.replacesDraftId) return;
-    const replacedDraft = await storage.getMemoryById(replacement.replacesDraftId);
+    // Tier-independent: an interrupted edit's rejected predecessor can be
+    // demoted to the cold tier before recovery runs; a hot-only lookup would
+    // mistake it for deleted and orphan the valid replacement (#2387).
+    const replacedDraft = await storage.getMemoryByIdIncludingArchived(replacement.replacesDraftId);
     const projectedDraft = replacedDraft ? projectOwnedCard(replacedDraft, namespace, principal) : null;
     if (
       replacedDraft &&
@@ -999,7 +1002,7 @@ export class SupportPassportCardService {
         return;
       }
     }
-    const currentDraft = await storage.getMemoryById(replacement.replacesDraftId);
+    const currentDraft = await storage.getMemoryByIdIncludingArchived(replacement.replacesDraftId);
     if (
       currentDraft &&
       ownsMemory(currentDraft, namespace, principal) &&

package/src/support-passport/card-state.ts

@@ -152,7 +152,11 @@ export function ownerListCards(storedCards: StoredSupportPassportCard[]): Stored
     if (activeReplacementPredecessors.has(item.card.cardId)) return false;
     if (replacedDraftIds.has(item.card.cardId)) return false;
     if (!item.replacesDraftId) return true;
+    // The replaced draft may be demoted to the cold tier or archived after
+    // its rejection; a hot-only projection then reports it missing. A
+    // missing predecessor must not hide the replacement — only a restored
+    // active predecessor does (#2387).
     const replacedStatus = byId.get(item.replacesDraftId)?.card.status;
-    return replacedStatus === "pending_review" || replacedStatus === "rejected";
+    return replacedStatus === undefined || replacedStatus === "pending_review" || replacedStatus === "rejected";
   });
 }

package/src/support-passport/offline-sync-guard.ts

@@ -9,9 +9,13 @@ import {
   type OfflineSyncApplyChangesetResult,
   type OfflineSyncApplyFileContentChunkResult,
 } from "../offline-sync.js";
+import { parseFrontmatter } from "../storage.js";
 import { validateArchiveRelativePath } from "../transfer/fs-utils.js";
 import type { MemoryFile } from "../types.js";
-import { createSupportPassportPrivateFileExclusion } from "./card-projection.js";
+import {
+  createSupportPassportPrivateFileExclusion,
+  isSupportPassportPrivateMemory,
+} from "./card-projection.js";
 
 const MAX_SUPPORT_PASSPORT_FRONTMATTER_BYTES = 1_048_576;
 const SUPPORT_PASSPORT_MARKER = "support-passport-";
@@ -64,6 +68,15 @@ function assertFrontmatterAllowed(frontmatter: string, relativePath: string): vo
   if (frontmatter.includes(SUPPORT_PASSPORT_MARKER)) {
     throw new Error(`offline sync cannot modify private support-passport record: ${relativePath}`);
   }
+  // Canonical classification (#2387): YAML/JSON escapes — e.g. a
+  // structured-attribute key written as `support\u002dpassport-owner` — hide
+  // the marker from the raw scan above, while the storage reader's
+  // JSON.parse reconstructs it after the write. Validate the parsed
+  // frontmatter with the same predicate the read path classifies by.
+  const parsed = parseFrontmatter(frontmatter);
+  if (parsed && isSupportPassportPrivateMemory({ frontmatter: parsed.frontmatter })) {
+    throw new Error(`offline sync cannot modify private support-passport record: ${relativePath}`);
+  }
 }
 
 function inspectBufferedFrontmatter(

package/src/transfer/export-okf.test.ts

@@ -0,0 +1,164 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm, writeFile, symlink } from "node:fs/promises";
+import { existsSync, lstatSync, readdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { StorageManager } from "../storage.js";
+import {
+  DEFAULT_OKF_LOG_MAX_ENTRIES,
+  exportOkfBundle,
+  OKF_EXPORT_VERSION,
+  OKF_LOG_TRUNCATION_MARKER,
+  parseIncludeStatus,
+} from "./export-okf.js";
+
+async function seedStore(dir: string): Promise<{ factId: string; decisionId: string }> {
+  const storage = new StorageManager(dir);
+  await storage.ensureDirectories();
+  const decision = await storage.writeMemory("decision", "# Use SQLite\n\nWe use SQLite for the local store.", {
+    source: "test",
+    confidence: 0.9,
+  });
+  const fact = await storage.writeMemory(
+    "fact",
+    "# Rate limit\n\nAPI rate limit is 100/min.\n\n<oai-mem-citation>\n<citation_entries>\nfacts/note.md:1-2|note=[source]\n</citation_entries>\n</oai-mem-citation>\n",
+    {
+      source: "test",
+      confidence: 0.9,
+      tags: ["api"],
+      links: [{ targetId: decision.id, linkType: "supports", strength: 0.8 }],
+    },
+  );
+  const superseded = await storage.writeMemory("fact", "# Old limit\n\nAPI rate limit is 10/min.", { source: "test" });
+  await storage.writeMemoryFrontmatter((await storage.getMemoryById(superseded.id))!, { status: "superseded" });
+  const pending = await storage.writeMemory("correction", "# Pending\n\nNeeds review.", { source: "test" });
+  await storage.writeMemoryFrontmatter((await storage.getMemoryById(pending.id))!, { status: "pending_review" });
+  await writeFile(path.join(dir, "profile.md"), "# User\n\nPrefers short answers.\n", "utf8");
+  return { factId: fact.id, decisionId: decision.id };
+}
+test("parseIncludeStatus rejects unknown values", () => {
+  assert.deepEqual(parseIncludeStatus(undefined), ["active"]);
+  assert.throws(() => parseIncludeStatus("nope"), /allowed:/);
+});
+
+test("exportOkfBundle writes a deterministic active-only bundle", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-okf-src-"));
+  const outA = await mkdtemp(path.join(os.tmpdir(), "remnic-okf-a-"));
+  const outB = path.join(os.tmpdir(), `remnic-okf-b-${Date.now()}`);
+  try {
+    await seedStore(memoryDir);
+    await rm(outA, { recursive: true, force: true });
+    const first = await exportOkfBundle({ memoryDir, outDir: outA });
+    assert.equal(first.exported, 2);
+    assert.ok(first.excluded >= 2);
+    const root = await readFile(path.join(outA, "index.md"), "utf8");
+    assert.match(root, new RegExp(`okf_version: "${OKF_EXPORT_VERSION}"`));
+    assert.doesNotMatch(root, /^type:/m);
+    assert.equal(existsSync(path.join(outA, "profile.md")), false);
+    const files = collectFiles(outA);
+    assert.ok(files.some((f) => f.includes("facts/")));
+    const factFile = files.find((f) => f.includes("facts/"))!;
+    const factBody = await readFile(path.join(outA, factFile), "utf8");
+    assert.match(factBody, /# Citations/);
+    assert.match(factBody, /# Related/);
+    assert.match(factBody, /type: Memory Fact/);
+    await exportOkfBundle({ memoryDir, outDir: outB });
+    assert.deepEqual(collectFiles(outA), collectFiles(outB));
+    for (const rel of collectFiles(outA)) {
+      assert.equal(await readFile(path.join(outA, rel), "utf8"), await readFile(path.join(outB, rel), "utf8"));
+    }
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+    await rm(outA, { recursive: true, force: true });
+    await rm(outB, { recursive: true, force: true });
+  }
+});
+
+test("profile stays off unless requested; non-empty out requires --force", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-okf-src-"));
+  const outDir = await mkdtemp(path.join(os.tmpdir(), "remnic-okf-out-"));
+  try {
+    await seedStore(memoryDir);
+    await rm(outDir, { recursive: true, force: true });
+    await exportOkfBundle({ memoryDir, outDir, includeProfile: true });
+    const profile = await readFile(path.join(outDir, "profile.md"), "utf8");
+    assert.match(profile, /type: Profile/);
+    await writeFile(path.join(outDir, "keep.txt"), "old", "utf8");
+    await assert.rejects(exportOkfBundle({ memoryDir, outDir }), /not empty/);
+    assert.equal(await readFile(path.join(outDir, "keep.txt"), "utf8"), "old");
+    await exportOkfBundle({ memoryDir, outDir, force: true });
+    assert.equal(existsSync(path.join(outDir, "keep.txt")), false);
+    assert.equal(existsSync(path.join(outDir, "index.md")), true);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+    await rm(outDir, { recursive: true, force: true });
+  }
+});
+
+test("log.md is newest-first and marks truncation", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-okf-src-"));
+  const outDir = path.join(os.tmpdir(), `remnic-okf-log-${Date.now()}`);
+  try {
+    const storage = new StorageManager(memoryDir);
+    await storage.ensureDirectories();
+    await storage.writeMemory("fact", "# One\n\nbody", { source: "test" });
+    await storage.appendMemoryLifecycleEvents([
+      {
+        eventId: "e2",
+        memoryId: "m1",
+        eventType: "created",
+        timestamp: "2026-08-02T00:00:00.000Z",
+        actor: "test",
+        ruleVersion: "1",
+      },
+      {
+        eventId: "e1",
+        memoryId: "m1",
+        eventType: "updated",
+        timestamp: "2026-08-01T00:00:00.000Z",
+        actor: "test",
+        ruleVersion: "1",
+      },
+    ]);
+    await exportOkfBundle({ memoryDir, outDir, includeLog: true, logMaxEntries: 1 });
+    const log = await readFile(path.join(outDir, "log.md"), "utf8");
+    assert.match(log, /## 20\d{2}-\d{2}-\d{2}/);
+    assert.match(log, new RegExp(OKF_LOG_TRUNCATION_MARKER));
+    assert.ok(DEFAULT_OKF_LOG_MAX_ENTRIES > 1);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+    await rm(outDir, { recursive: true, force: true });
+  }
+});
+
+test("symlink out is rejected", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-okf-src-"));
+  const real = await mkdtemp(path.join(os.tmpdir(), "remnic-okf-real-"));
+  const link = `${real}-link`;
+  try {
+    await seedStore(memoryDir);
+    await symlink(real, link);
+    await assert.rejects(exportOkfBundle({ memoryDir, outDir: link }), /symlink/);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+    await rm(real, { recursive: true, force: true });
+    await rm(link, { force: true });
+  }
+});
+
+function collectFiles(root: string): string[] {
+  const out: string[] = [];
+  const walk = (dir: string): void => {
+    for (const name of readdirSync(dir).sort()) {
+      const full = path.join(dir, name);
+      const stat = lstatSync(full);
+      if (stat.isSymbolicLink()) continue;
+      if (stat.isDirectory()) walk(full);
+      else out.push(path.relative(root, full).split(path.sep).join("/"));
+    }
+  };
+  walk(root);
+  return out.sort();
+}

package/src/transfer/export-okf.ts

@@ -0,0 +1,286 @@
+import { rmSync } from "node:fs";
+import { mkdtemp } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { parseOaiMemCitation } from "../citations.js";
+import { inferMemoryStatus } from "../memory-lifecycle-ledger-utils.js";
+import { normalizeProjectionPreview } from "../memory-projection-format.js";
+import { lintOkfDir } from "../okf/lint.js";
+import { okfTypeForMemory, OKF_PROFILE_TYPE } from "../okf/type-mapping.js";
+import {
+  OKF_EXPORT_VERSION,
+  publishBundle,
+  renderFrontmatter,
+  rejectSymlinkPath,
+  writeBundleFile,
+} from "../okf/render.js";
+// Re-exported for the existing `@remnic/core/export-okf` consumers and tests
+// (one public surface; the value itself now lives in okf/render.ts).
+export { OKF_EXPORT_VERSION };
+import { StorageManager } from "../storage.js";
+import type { MemoryFile, MemoryLink, MemoryStatus } from "../types.js";
+
+// Shared bundle mechanics (frontmatter, publish, symlink guard, file write)
+// live in ../okf/render.ts — one source of truth for every OKF exporter.
+export const OKF_LOG_TRUNCATION_MARKER = "<!-- okf-log-truncated -->";
+export const DEFAULT_OKF_LOG_MAX_ENTRIES = 500;
+
+const MEMORY_STATUSES: readonly MemoryStatus[] = [
+  "active",
+  "pending_review",
+  "rejected",
+  "quarantined",
+  "superseded",
+  "archived",
+  "forgotten",
+];
+
+export interface ExportOkfOptions {
+  memoryDir: string;
+  outDir: string;
+  includeStatus?: readonly string[];
+  includeCategories?: readonly string[];
+  excludeTags?: readonly string[];
+  includeProfile?: boolean;
+  includeWearables?: boolean;
+  includeLog?: boolean;
+  logMaxEntries?: number;
+  force?: boolean;
+}
+
+export interface ExportOkfResult {
+  exported: number;
+  excluded: number;
+  byCategory: Record<string, number>;
+  plaintextWarning: boolean;
+}
+
+export function parseIncludeStatus(raw: unknown): MemoryStatus[] {
+  const values = splitCsv(raw);
+  if (values.length === 0) return ["active"];
+  const allowed = new Set<string>(MEMORY_STATUSES);
+  for (const value of values) {
+    if (!allowed.has(value)) {
+      throw new Error(`invalid --include-status ${value}; allowed: ${MEMORY_STATUSES.join(", ")}`);
+    }
+  }
+  return values as MemoryStatus[];
+}
+
+export async function exportOkfBundle(opts: ExportOkfOptions): Promise<ExportOkfResult> {
+  const outDir = path.resolve(opts.outDir);
+  rejectSymlinkPath(outDir);
+  const includeStatus = new Set(parseIncludeStatus(opts.includeStatus));
+  const includeCategories = opts.includeCategories?.length ? new Set(opts.includeCategories) : null;
+  const excludeTags = new Set(opts.excludeTags ?? []);
+  const storage = new StorageManager(opts.memoryDir);
+  const memories = await storage.readAllMemories();
+  const included: MemoryFile[] = [];
+  let excluded = 0;
+  for (const memory of memories) {
+    const rel = toRel(memory.path, opts.memoryDir);
+    if (!opts.includeWearables && rel.startsWith("wearables/")) {
+      excluded += 1;
+      continue;
+    }
+    const status = inferMemoryStatus(memory.frontmatter, memory.path);
+    if (!includeStatus.has(status)) {
+      excluded += 1;
+      continue;
+    }
+    if (includeCategories && !includeCategories.has(memory.frontmatter.category)) {
+      excluded += 1;
+      continue;
+    }
+    if ((memory.frontmatter.tags ?? []).some((tag) => excludeTags.has(tag))) {
+      excluded += 1;
+      continue;
+    }
+    included.push(memory);
+  }
+  included.sort((a, b) => toRel(a.path, opts.memoryDir).localeCompare(toRel(b.path, opts.memoryDir)));
+
+  const staging = await mkdtemp(path.join(os.tmpdir(), "remnic-okf-export-"));
+  const byCategory: Record<string, number> = {};
+  const idToRel = new Map<string, string>();
+  for (const memory of included) {
+    const rel = toRel(memory.path, opts.memoryDir);
+    idToRel.set(memory.frontmatter.id, rel);
+  }
+  for (const memory of included) {
+    const rel = toRel(memory.path, opts.memoryDir);
+    const rendered = renderMemory(memory, rel, idToRel);
+    writeBundleFile(staging, rel, rendered);
+    const category = memory.frontmatter.category;
+    byCategory[category] = (byCategory[category] ?? 0) + 1;
+  }
+
+  if (opts.includeProfile) {
+    try {
+      const profile = await storage.readProfile();
+      if (profile) {
+        writeBundleFile(
+          staging,
+          "profile.md",
+          renderFrontmatter({
+            type: OKF_PROFILE_TYPE,
+            title: "User Profile",
+            timestamp: new Date(0).toISOString(),
+          }) + profile.replace(/^\uFEFF/, ""),
+        );
+      }
+    } catch {
+      // Profile is optional even when requested.
+    }
+  }
+
+  if (opts.includeLog) {
+    const events = await storage.readAllMemoryLifecycleEvents();
+    writeBundleFile(staging, "log.md", renderLog(events, idToRel, opts.logMaxEntries ?? DEFAULT_OKF_LOG_MAX_ENTRIES));
+  }
+
+  writeIndexes(staging, included, opts.memoryDir);
+  const lint = lintOkfDir(staging);
+  const blocking = lint.findings.filter((f) => f.code !== "skipped_encrypted" && f.code !== "reserved_basename");
+  if (blocking.length > 0) {
+    rmSync(staging, { recursive: true, force: true });
+    throw new Error(`OKF export failed lint: ${blocking.map((f) => `${f.file}: ${f.message}`).join("; ")}`);
+  }
+
+  publishBundle(staging, outDir, opts.force === true);
+  return {
+    exported: included.length,
+    excluded,
+    byCategory,
+    plaintextWarning: true,
+  };
+}
+
+
+function renderMemory(memory: MemoryFile, rel: string, idToRel: Map<string, string>): string {
+  const fm = memory.frontmatter;
+  const title = firstHeading(memory.content) ?? `${humanize(fm.category)} ${fm.created.slice(0, 10)}`;
+  const type = fm.type ?? okfTypeForMemory(fm);
+  const fields: Record<string, unknown> = {
+    ...fm,
+    type,
+    title,
+    description: normalizeProjectionPreview(memory.content),
+    tags: fm.tags ?? [],
+    timestamp: fm.updated,
+  };
+  if (fm.artifactType) fields.resource = rel;
+  let body = memory.content.trim();
+  const citation = parseOaiMemCitation(body);
+  if (citation) {
+    const start = body.indexOf("<oai-mem-citation>");
+    const end = body.indexOf("</oai-mem-citation>");
+    if (start >= 0 && end > start) {
+      body = `${body.slice(0, start).trimEnd()}\n\n${body.slice(end + "</oai-mem-citation>".length).trimStart()}`.trim();
+    }
+    const lines = citation.entries.map((entry, index) => `${index + 1}. [${entry.path}](${entry.path})`);
+    body = `${body}\n\n# Citations\n\n${lines.join("\n")}\n`;
+  }
+  const links = fm.links ?? [];
+  if (links.length > 0) {
+    body += `\n# Related\n\n${links.map((link) => renderRelated(link, idToRel)).join("\n")}\n`;
+  }
+  return renderFrontmatter(fields) + body + (body.endsWith("\n") ? "" : "\n");
+}
+
+function renderRelated(link: MemoryLink, idToRel: Map<string, string>): string {
+  const target = idToRel.get(link.targetId) ?? link.targetId;
+  const href = target.startsWith("/") ? target : `/${target}`;
+  return `- ${link.linkType}: [${link.targetId}](${href})`;
+}
+
+function writeIndexes(root: string, memories: MemoryFile[], memoryDir: string): void {
+  const groups = new Map<string, MemoryFile[]>();
+  for (const memory of memories) {
+    const rel = toRel(memory.path, memoryDir);
+    const dir = path.posix.dirname(rel);
+    const key = dir === "." ? "" : dir.split("/")[0] ?? "";
+    const list = groups.get(key) ?? [];
+    list.push(memory);
+    groups.set(key, list);
+  }
+  const sections = [...groups.keys()].sort().map((key) => {
+    const heading = key === "" ? "Root" : humanize(key);
+    const lines = (groups.get(key) ?? [])
+      .sort((a, b) => toRel(a.path, memoryDir).localeCompare(toRel(b.path, memoryDir)))
+      .map((memory) => {
+        const rel = toRel(memory.path, memoryDir);
+        const title = firstHeading(memory.content) ?? memory.frontmatter.id;
+        const description = normalizeProjectionPreview(memory.content);
+        return `* [${title}](/${rel}) - ${description}`;
+      });
+    return `## ${heading}\n\n${lines.join("\n")}`;
+  });
+  writeBundleFile(root, "index.md", `---\nokf_version: "${OKF_EXPORT_VERSION}"\n---\n\n${sections.join("\n\n")}\n`);
+}
+
+function renderLog(
+  events: Array<{ timestamp?: string; type?: string; action?: string; memoryId?: string }>,
+  idToRel: Map<string, string>,
+  maxEntries: number,
+): string {
+  const sorted = [...events].sort((a, b) => String(b.timestamp ?? "").localeCompare(String(a.timestamp ?? "")));
+  const truncated = sorted.length > maxEntries;
+  const kept = sorted.slice(0, maxEntries);
+  const byDay = new Map<string, typeof kept>();
+  for (const event of kept) {
+    const day = String(event.timestamp ?? "").slice(0, 10) || "unknown";
+    const list = byDay.get(day) ?? [];
+    list.push(event);
+    byDay.set(day, list);
+  }
+  const days = [...byDay.keys()].sort((a, b) => b.localeCompare(a));
+  const parts = ["# Log", ""];
+  for (const day of days) {
+    parts.push(`## ${day}`, "");
+    for (const event of byDay.get(day) ?? []) {
+      const action = boldAction(event.type ?? event.action ?? "Update");
+      const id = event.memoryId;
+      const rel = id ? idToRel.get(id) : undefined;
+      const target = rel ? `[${id}](/${rel})` : id ?? "";
+      parts.push(`- **${action}** ${target}`.trimEnd());
+    }
+    parts.push("");
+  }
+  if (truncated) parts.push(OKF_LOG_TRUNCATION_MARKER, "");
+  return `${parts.join("\n")}\n`;
+}
+
+function boldAction(raw: string): string {
+  const lower = raw.toLowerCase();
+  if (lower.includes("create") || lower.includes("add")) return "Creation";
+  if (lower.includes("deprecat") || lower.includes("delete") || lower.includes("archiv")) return "Deprecation";
+  return "Update";
+}
+
+
+function firstHeading(content: string): string | undefined {
+  for (const line of content.split("\n")) {
+    const match = /^#\s+(.+)$/.exec(line.trim());
+    if (match) return match[1]!.trim();
+  }
+  return undefined;
+}
+
+function humanize(value: string): string {
+  return value.replace(/[_-]/g, " ").replace(/\b\w/g, (ch) => ch.toUpperCase());
+}
+
+
+
+function splitCsv(raw: unknown): string[] {
+  if (raw === undefined || raw === null || raw === "") return [];
+  const parts = Array.isArray(raw) ? raw.map(String) : String(raw).split(",");
+  return parts.map((part) => part.trim()).filter((part) => part.length > 0);
+}
+
+function toRel(abs: string, root: string): string {
+  return path.relative(path.resolve(root), path.resolve(abs)).split(path.sep).join("/");
+}
+