@remnic/core 9.64.1 → 9.64.3

package/src/access-surface-catalog.ts

@@ -56,6 +56,7 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
   { tool: "set_coding_context", operation: "set_coding_context" },
   { tool: "recall_tier_explain", operation: "recall_tier_explain" },
   { tool: "recall_xray", operation: "recall_xray" },
+  { tool: "who_knows", operation: "who_knows" },
   { tool: "wearables_status", operation: "wearables_status" },
   { tool: "wearables_sync", operation: "wearables_sync" },
   { tool: "transcript_day", operation: "transcript_day" },
@@ -210,6 +211,7 @@ export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
   { method: "POST", pathname: "/engram/v1/action-confidence", operation: "action_confidence" },
   { method: "GET", pathname: "/engram/v1/recall/tier-explain", operation: "recall_tier_explain" },
   { method: "GET", pathname: "/engram/v1/recall/xray", operation: "recall_xray" },
+  { method: "GET", pathname: "/engram/v1/who-knows", operation: "who_knows" },
   { method: "GET", pathname: "/engram/v1/namespace/writable", operation: "namespace_writable" },
   { method: "GET", pathname: "/engram/v1/wearables/status", operation: "wearables_status" },
   { method: "POST", pathname: "/engram/v1/wearables/sync", operation: "wearables_sync" },

package/src/cli/okf-commands.ts

@@ -0,0 +1,23 @@
+import type { Orchestrator } from "../orchestrator.js";
+import type { CliCommand } from "../cli.js";
+import { runOkfCliCommand } from "../okf/cli.js";
+
+export function registerOkfCommands(cmd: CliCommand, orchestrator: Orchestrator): void {
+  const okfCmd = cmd.command("okf").description("OKF v0.1 conformance (lint, sweep)");
+  const forward = async (argv: string[]): Promise<void> => {
+    const code = await runOkfCliCommand(argv, { stdout: process.stdout, stderr: process.stderr }, {
+      memoryDir: orchestrator.config.memoryDir,
+      conformanceEnabled: orchestrator.config.okf.conformanceEnabled,
+      sweepEnabled: orchestrator.config.okf.sweepEnabled,
+    });
+    if (code !== 0) process.exitCode = code;
+  };
+  okfCmd.command("lint").description("Report OKF conformance findings").option("--json", "JSON output").action(async (...args: unknown[]) => {
+    const options = (args[0] ?? {}) as Record<string, unknown>;
+    await forward(["lint", ...(options.json === true ? ["--json"] : [])]);
+  });
+  okfCmd.command("sweep").description("Add missing type fields without bumping updated").option("--json", "JSON output").action(async (...args: unknown[]) => {
+    const options = (args[0] ?? {}) as Record<string, unknown>;
+    await forward(["sweep", ...(options.json === true ? ["--json"] : [])]);
+  });
+}

package/src/cli.ts

@@ -15,6 +15,7 @@ import { utcDayRange } from "./transcript.js";
 import { padEndDisplay, truncateGraphemeSafe } from "./whitespace.js";
 import { runWearablesCliCommand } from "./wearables/cli.js";
 import { registerMeetingsCommands } from "./cli/meetings-commands.js";
+import { registerOkfCommands } from "./cli/okf-commands.js";
 import { registerResearchStatusCommands } from "./cli/research-status-commands.js";
 import { registerCreationLedgerCommands } from "./cli/creation-ledger-commands.js";
 import type {
@@ -6227,7 +6228,7 @@ export function registerCli(
 
       registerResearchStatusCommands(cmd, orchestrator);
 
-      registerCreationLedgerCommands(cmd, orchestrator); registerMeetingsCommands(cmd, orchestrator);
+      registerCreationLedgerCommands(cmd, orchestrator); registerMeetingsCommands(cmd, orchestrator); registerOkfCommands(cmd, orchestrator);
 
       cmd
         .command("trust-zone-promote")

package/src/config.ts

@@ -63,6 +63,7 @@ import {
 import { parseWearablesConfig } from "./wearables/config.js";
 import { parseCaptureCompanionConfigs } from "./location/parse-companions.js";
 import { parseLocationConfig } from "./location/config.js";
+import { parseOkfConfig } from "./okf/config.js";
 import { parseBoundedJsonlStateConfig } from "./bounded-jsonl-state.js";
 import { parseCodingKnowledgeConfig } from "./coding/coding-knowledge-config.js";
 import { parseChatConfig } from "./chat/chat-config.js";
@@ -515,7 +516,6 @@ function normalizeMemoryRelativeDir(raw: unknown, fallback: string): string {
   return normalized.length > 0 ? normalized : fallback;
 }
 
-
 function parseSemanticChunkingConfig(
   raw: unknown,
 ): Partial<SemanticChunkingConfigShape> {
@@ -2320,6 +2320,7 @@ export function parseConfig(
     converge: parseConvergeConfig(cfg.converge),
     wearables,
     meetings,
+    okf: parseOkfConfig(cfg.okf),
     activity,
     location,
     provenance,

package/src/index.ts

@@ -499,6 +499,8 @@ export type {
   RecallXrayServedBy,
   RecallFilterTrace,
 } from "./recall-xray.js";
+export * from "./who-knows.js";
+export * from "./who-knows-cli.js";
 
 // ChatGPT Apps-compatible memory inspector demo.
 export {
@@ -1215,6 +1217,7 @@ export { runAuditMemoryCliCommand, runBulkImportCliCommand, type BulkImportCliCo
 export * from "./wearables/index.js";
 export * from "./activity/index.js";
 export * from "./meetings/index.js";
+export * from "./okf/cli.js";
 
 // ---------------------------------------------------------------------------
 // Shared importer base (issue #568)

package/src/mcp-read-only-tools.ts

@@ -16,6 +16,7 @@ export const MCP_READ_ONLY_TOOL_SUFFIXES: Readonly<Record<string, true>> = {
   recall_explain: true,
   recall_tier_explain: true,
   recall_xray: true,
+  who_knows: true,
   briefing: true,
   wearables_status: true,
   transcript_day: true,

package/src/okf/cli.ts

@@ -0,0 +1,42 @@
+import { lintOkfDir } from "./lint.js";
+import { runOkfConformanceSweep } from "./sweep.js";
+
+export async function runOkfCliCommand(
+  argv: string[],
+  io: { stdout: NodeJS.WritableStream; stderr: NodeJS.WritableStream },
+  ctx: { memoryDir: string; conformanceEnabled: boolean; sweepEnabled: boolean },
+): Promise<number> {
+  const [subcommand, ...rest] = argv;
+  if (subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+    io.stdout.write(`usage: remnic okf <lint|sweep> [--json]
+  lint   report OKF conformance findings (exit 1 when findings remain)
+  sweep  backfill missing type values (requires okf.sweepEnabled)
+`);
+    return 0;
+  }
+  if (subcommand !== "lint" && subcommand !== "sweep") {
+    io.stderr.write("okf: expected lint or sweep\n");
+    return 1;
+  }
+  for (const token of rest) {
+    if (token === "--json") continue;
+    io.stderr.write(`okf: unexpected argument '${token}' — usage: remnic okf <lint|sweep> [--json]\n`);
+    return 1;
+  }
+  const json = rest.includes("--json");
+  if (subcommand === "sweep") {
+    const result = runOkfConformanceSweep(ctx.memoryDir, ctx);
+    if (json) io.stdout.write(`${JSON.stringify(result)}\n`);
+    else io.stdout.write(`okf sweep: scanned ${result.scanned}, wrote ${result.written}\n`);
+    return 0;
+  }
+  const result = lintOkfDir(ctx.memoryDir);
+  if (json) io.stdout.write(`${JSON.stringify(result)}\n`);
+  else {
+    io.stdout.write(`okf lint: scanned ${result.scanned}, findings ${result.findings.length}\n`);
+    for (const finding of result.findings) {
+      io.stdout.write(`  ${finding.file}: ${finding.message}\n`);
+    }
+  }
+  return result.ok ? 0 : 1;
+}

package/src/okf/config.ts

@@ -0,0 +1,34 @@
+/**
+ * OKF conformance config (issue #1946). Parsed off the raw `okf` config
+ * block; mirrors the meetings/wearables parse-module seam so config.ts
+ * stays a thin caller.
+ */
+import { coerceBooleanLike } from "../connectors/coerce.js";
+
+export interface OkfConfig {
+  /** Emit inert OKF `type` metadata on writes and gate the sweep (default true). */
+  conformanceEnabled: boolean;
+  /** Opt-in governance sweep that backfills `type` on legacy files (default false). */
+  sweepEnabled: boolean;
+}
+
+export const DEFAULT_OKF_CONFIG: OkfConfig = Object.freeze({
+  conformanceEnabled: true,
+  sweepEnabled: false,
+});
+
+export function parseOkfConfig(raw: unknown): OkfConfig {
+  if (raw === undefined || raw === null) return { ...DEFAULT_OKF_CONFIG };
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(
+      `okf must be an object (got ${JSON.stringify(raw)}). Use okf: { conformanceEnabled: false } to opt out; omit the key for defaults.`,
+    );
+  }
+  const record = raw as Record<string, unknown>;
+  const conformance = coerceBooleanLike(record.conformanceEnabled, "okf.conformanceEnabled");
+  const sweep = coerceBooleanLike(record.sweepEnabled, "okf.sweepEnabled");
+  return {
+    conformanceEnabled: conformance ?? DEFAULT_OKF_CONFIG.conformanceEnabled,
+    sweepEnabled: sweep ?? DEFAULT_OKF_CONFIG.sweepEnabled,
+  };
+}

package/src/okf/lint.ts

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { MAGIC_BYTES } from "../secure-store/secure-fs.js";
+import { OKF_RESERVED_BASENAMES } from "./type-mapping.js";
+
+export interface OkfLintFinding {
+  file: string;
+  code: "missing_frontmatter" | "missing_type" | "empty_type" | "reserved_basename" | "skipped_encrypted";
+  message: string;
+}
+
+export interface OkfLintResult {
+  ok: boolean;
+  scanned: number;
+  findings: OkfLintFinding[];
+}
+
+function isEncryptedBlob(raw: string): boolean {
+  // secure-store writes a binary envelope starting with MAGIC_BYTES at offset
+  // 0 — match that fixed position, never a substring anywhere in the file.
+  return raw.startsWith(MAGIC_BYTES.toString("ascii"));
+}
+
+function hasFrontmatter(raw: string): boolean {
+  return raw.startsWith("---\n") || raw.startsWith("---\r\n");
+}
+
+function readType(raw: string): string | undefined {
+  const close = raw.indexOf("\n---", 4);
+  if (close === -1) return undefined;
+  const block = raw.slice(4, close);
+  const match = /^type:[ \t]*(.*)$/m.exec(block);
+  if (!match) return undefined;
+  const value = match[1]!.trim().replace(/^["']|["']$/g, "");
+  return value;
+}
+
+function walkMarkdown(root: string, out: string[]): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.name === "state" || entry.name === ".git") continue;
+    const full = path.join(root, entry.name);
+    let stat: fs.Stats;
+    try {
+      stat = fs.lstatSync(full);
+    } catch {
+      continue;
+    }
+    if (stat.isSymbolicLink()) continue;
+    if (stat.isDirectory()) {
+      walkMarkdown(full, out);
+      continue;
+    }
+    if (stat.isFile() && entry.name.endsWith(".md")) out.push(full);
+  }
+}
+
+export function lintOkfDir(memoryDir: string): OkfLintResult {
+  const files: string[] = [];
+  walkMarkdown(memoryDir, files);
+  const findings: OkfLintFinding[] = [];
+  for (const file of files) {
+    const rel = path.relative(memoryDir, file);
+    const base = path.basename(file);
+    if (OKF_RESERVED_BASENAMES[base] === true) {
+      findings.push({
+        file: rel,
+        code: "reserved_basename",
+        message: `${base} is reserved by OKF §6/§7`,
+      });
+      continue;
+    }
+    let raw: string;
+    try {
+      raw = fs.readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    if (isEncryptedBlob(raw)) {
+      findings.push({
+        file: rel,
+        code: "skipped_encrypted",
+        message: "skipped (encrypted)",
+      });
+      continue;
+    }
+    if (!hasFrontmatter(raw)) {
+      findings.push({
+        file: rel,
+        code: "missing_frontmatter",
+        message: "missing YAML frontmatter",
+      });
+      continue;
+    }
+    const type = readType(raw);
+    if (type === undefined) {
+      findings.push({ file: rel, code: "missing_type", message: "missing type" });
+    } else if (type.length === 0) {
+      findings.push({ file: rel, code: "empty_type", message: "empty type" });
+    }
+  }
+  const actionable = findings.filter((f) => f.code !== "skipped_encrypted");
+  return { ok: actionable.length === 0, scanned: files.length, findings };
+}

package/src/okf/sweep.ts

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { lintOkfDir } from "./lint.js";
+import { okfTypeForCategory } from "./type-mapping.js";
+
+export interface OkfSweepResult {
+  scanned: number;
+  written: number;
+}
+
+function insertType(raw: string, type: string): string | null {
+  const crlf = raw.startsWith("---\r\n");
+  if (!crlf && !raw.startsWith("---\n")) return null;
+  const lines = raw.split("\n");
+  let close = -1;
+  for (let index = 1; index < lines.length; index += 1) {
+    const line = lines[index]!;
+    if (line === "---" || line === "---\r" || line === "...") {
+      close = index;
+      break;
+    }
+  }
+  if (close === -1) return null;
+  const block = lines.slice(1, close);
+  const categoryLine = block.find((line) => line.startsWith("category:"));
+  const category = categoryLine
+    ? categoryLine.slice("category:".length).trim().replace(/^["']|["']$/g, "")
+    : "fact";
+  const resolved = type || okfTypeForCategory(category);
+  const typeIndex = block.findIndex((line) => line.startsWith("type:"));
+  if (typeIndex === -1) {
+    block.push(`type: ${resolved}${crlf ? "\r" : ""}`);
+  } else {
+    const current = block[typeIndex]!;
+    const bare = current.endsWith("\r") ? current.slice(0, -1) : current;
+    const value = bare.slice("type:".length).trim().replace(/^["']|["']$/g, "");
+    if (value !== "") return null;
+    block[typeIndex] = `type: ${resolved}${current.endsWith("\r") ? "\r" : ""}`;
+  }
+  return [lines[0], ...block, ...lines.slice(close)].join("\n");
+}
+
+export function runOkfConformanceSweep(
+  memoryDir: string,
+  options: { sweepEnabled: boolean; conformanceEnabled: boolean },
+): OkfSweepResult {
+  if (!options.sweepEnabled || !options.conformanceEnabled) {
+    return { scanned: 0, written: 0 };
+  }
+  const lint = lintOkfDir(memoryDir);
+  let written = 0;
+  for (const finding of lint.findings) {
+    if (finding.code !== "missing_type" && finding.code !== "empty_type") continue;
+    const file = path.join(memoryDir, finding.file);
+    const raw = fs.readFileSync(file, "utf8");
+    const next = insertType(raw, "");
+    if (next === null || next === raw) continue;
+    fs.writeFileSync(file, next);
+    written += 1;
+  }
+  return { scanned: lint.scanned, written };
+}

package/src/okf/type-mapping.test.ts

@@ -0,0 +1,207 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile, readFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { runOkfCliCommand } from "./cli.js";
+import { lintOkfDir } from "./lint.js";
+import { runOkfConformanceSweep } from "./sweep.js";
+import {
+  assertNotOkfReservedBasename,
+  okfTypeForCategory,
+  okfTypeForEntityKind,
+  okfTypeForMemory,
+} from "./type-mapping.js";
+import { parseEntityFile, serializeEntityFile } from "../storage.js";
+import { parseOkfConfig } from "./config.js";
+import { stripOkfProfileFrontmatter, withOkfProfileFrontmatter } from "../storage/profile-header.js";
+
+test("okfTypeForCategory maps known categories and falls back", () => {
+  assert.equal(okfTypeForCategory("fact"), "Memory Fact");
+  assert.equal(okfTypeForCategory("decision"), "Decision");
+  assert.equal(okfTypeForCategory("unknown-future"), "Memory");
+});
+
+test("okfTypeForMemory prefers Artifact when artifactType is set", () => {
+  assert.equal(okfTypeForMemory({ category: "fact" }), "Memory Fact");
+  assert.equal(okfTypeForMemory({ category: "fact", artifactType: "image" }), "Artifact");
+});
+
+test("okfTypeForEntityKind maps kinds and defaults to Entity", () => {
+  assert.equal(okfTypeForEntityKind("person"), "Person");
+  assert.equal(okfTypeForEntityKind("PROJECT"), "Project");
+  assert.equal(okfTypeForEntityKind(undefined), "Entity");
+});
+
+test("reserved basenames are rejected", () => {
+  assert.throws(() => assertNotOkfReservedBasename("/mem/index.md"), /reserved basename/);
+  assert.throws(() => assertNotOkfReservedBasename("/mem/log.md"), /reserved basename/);
+  assert.doesNotThrow(() => assertNotOkfReservedBasename("/mem/facts/fact-1.md"));
+});
+
+test("type never overrides category — mapping is presentation only", () => {
+  assert.equal(okfTypeForCategory("fact"), "Memory Fact");
+  assert.notEqual(okfTypeForCategory("fact"), "fact");
+});
+
+test("parseOkfConfig treats false as a real disable", () => {
+  assert.deepEqual(parseOkfConfig({ conformanceEnabled: false, sweepEnabled: "false" }), {
+    conformanceEnabled: false,
+    sweepEnabled: false,
+  });
+  assert.throws(() => parseOkfConfig("nope"), /okf must be an object/);
+});
+
+test("profile OKF frontmatter strips back to the original injection bytes", () => {
+  const original = "# User\n\nPrefers short answers.\n";
+  const stamped = withOkfProfileFrontmatter(original, "2026-08-18T00:00:00.000Z", true);
+  assert.match(stamped, /^---\n/);
+  assert.match(stamped, /type: Profile/);
+  assert.equal(stripOkfProfileFrontmatter(stamped), original);
+  assert.equal(withOkfProfileFrontmatter(original, "2026-08-18T00:00:00.000Z", false), original);
+});
+
+test("lintOkfDir reports missing type and skips only real encrypted envelopes", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-okf-lint-"));
+  try {
+    await mkdir(path.join(dir, "facts", "2026-08-18"), { recursive: true });
+    await writeFile(
+      path.join(dir, "facts", "2026-08-18", "fact-ok.md"),
+      "---\nid: fact-ok\ncategory: fact\ntype: Memory Fact\n---\n\nhello\n",
+    );
+    await writeFile(
+      path.join(dir, "facts", "2026-08-18", "fact-bare.md"),
+      "---\nid: fact-bare\ncategory: fact\n---\n\nno type\n",
+    );
+    // Binary secure-store envelope: starts with the REMNIC-ENC magic header.
+    await writeFile(path.join(dir, "secret.md"), "REMNIC-ENC\x00\x01cipher-bytes");
+    // Plaintext that merely mentions an encryption marker is NOT skipped.
+    await writeFile(
+      path.join(dir, "mentions-enc.md"),
+      "---\nid: mentions-enc\ncategory: fact\n---\n\ndiscusses enc:v1 in prose\n",
+    );
+    const result = lintOkfDir(dir);
+    assert.equal(result.scanned, 4);
+    assert.equal(result.ok, false);
+    assert.ok(result.findings.some((f) => f.code === "missing_type"));
+    const encrypted = result.findings.filter((f) => f.code === "skipped_encrypted");
+    assert.equal(encrypted.length, 1);
+    assert.equal(encrypted[0]!.file, "secret.md");
+    assert.ok(result.findings.some((f) => f.file === "mentions-enc.md" && f.code === "missing_type"));
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("sweep adds type without rewriting files that already have it", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-okf-sweep-"));
+  try {
+    const file = path.join(dir, "fact-bare.md");
+    await writeFile(file, "---\nid: fact-bare\ncategory: fact\nupdated: 2026-01-01T00:00:00.000Z\n---\n\nno type\n");
+    assert.equal(runOkfConformanceSweep(dir, { sweepEnabled: false, conformanceEnabled: true }).written, 0);
+    const first = runOkfConformanceSweep(dir, { sweepEnabled: true, conformanceEnabled: true });
+    assert.equal(first.written, 1);
+    const raw = await readFile(file, "utf8");
+    assert.match(raw, /type: Memory Fact/);
+    assert.match(raw, /updated: 2026-01-01T00:00:00.000Z/);
+    assert.equal(runOkfConformanceSweep(dir, { sweepEnabled: true, conformanceEnabled: true }).written, 0);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("sweep replaces an empty type in place and stays idempotent", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-okf-sweep-empty-"));
+  try {
+    const file = path.join(dir, "fact-empty.md");
+    await writeFile(file, "---\nid: fact-empty\ncategory: decision\ntype:\nupdated: 2026-01-01T00:00:00.000Z\n---\n\nempty type\n");
+    assert.equal(runOkfConformanceSweep(dir, { sweepEnabled: true, conformanceEnabled: true }).written, 1);
+    const raw = await readFile(file, "utf8");
+    const typeLines = raw.split("\n").filter((line) => line.startsWith("type:"));
+    assert.equal(typeLines.length, 1, "no duplicate type key after sweep");
+    assert.equal(typeLines[0], "type: Decision");
+    assert.match(raw, /updated: 2026-01-01T00:00:00.000Z/);
+    assert.equal(runOkfConformanceSweep(dir, { sweepEnabled: true, conformanceEnabled: true }).written, 0);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("sweep handles CRLF frontmatter the same as LF", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-okf-sweep-crlf-"));
+  try {
+    const file = path.join(dir, "fact-crlf.md");
+    await writeFile(
+      file,
+      "---\r\nid: fact-crlf\r\ncategory: fact\r\n---\r\n\r\ncrlf body\r\n",
+    );
+    assert.equal(runOkfConformanceSweep(dir, { sweepEnabled: true, conformanceEnabled: true }).written, 1);
+    const raw = await readFile(file, "utf8");
+    const typeLine = raw.split("\n").find((line) => line.startsWith("type:"));
+    assert.equal(typeLine, "type: Memory Fact\r");
+    assert.equal(runOkfConformanceSweep(dir, { sweepEnabled: true, conformanceEnabled: true }).written, 0);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+test("profile OKF frontmatter strip tolerates CRLF-rewritten files", () => {
+  // A CRLF-rewriting editor converts the whole stamped file, OKF block included.
+  const crlfStamped =
+    "---\r\ntype: Profile\r\ntitle: User Profile\r\ntimestamp: 2026-08-18T00:00:00.000Z\r\n---\r\n# User\r\n\r\nPrefers short answers.\r\n";
+  assert.equal(stripOkfProfileFrontmatter(crlfStamped), "# User\r\n\r\nPrefers short answers.\r\n");
+  // Hand-written CRLF frontmatter without the marker round-trips untouched.
+  const handWritten = "---\r\ntitle: mine\r\n---\r\n\r\nbody\r\n";
+  assert.equal(stripOkfProfileFrontmatter(handWritten), handWritten);
+});
+
+test("runOkfCliCommand handles help and rejects unexpected tokens", async () => {
+  const chunks: string[] = [];
+  const stdout = { write: (s: string) => void chunks.push(s) } as unknown as NodeJS.WritableStream;
+  for (const argv of [["--help"], ["-h"], ["help"]]) {
+    const stderr = { write: () => {} } as unknown as NodeJS.WritableStream;
+    const code = await runOkfCliCommand(argv, { stdout, stderr }, {
+      memoryDir: "/tmp",
+      conformanceEnabled: true,
+      sweepEnabled: false,
+    });
+    assert.equal(code, 0);
+    assert.match(chunks.join(""), /usage: remnic okf/);
+  }
+  const errChunks: string[] = [];
+  const stderr = { write: (s: string) => void errChunks.push(s) } as unknown as NodeJS.WritableStream;
+  for (const token of ["--json=1", "--unknown", "stray"]) {
+    errChunks.length = 0;
+    const code = await runOkfCliCommand(["lint", token], { stdout, stderr }, {
+      memoryDir: "/tmp",
+      conformanceEnabled: true,
+      sweepEnabled: false,
+    });
+    assert.equal(code, 1);
+    assert.match(errChunks.join(""), new RegExp(`unexpected argument '${token}'`));
+  }
+});
+
+test("serializeEntityFile okfType gate omits type when off, emits one when on", () => {
+  const raw = [
+    "---",
+    "created: 2026-01-01T00:00:00.000Z",
+    "updated: 2026-01-01T00:00:00.000Z",
+    "type: Entity",
+    "---",
+    "",
+    "# Jane",
+    "",
+    "**Type:** person",
+    "**Updated:** 2026-01-01T00:00:00.000Z",
+    "",
+  ].join("\n");
+  const entity = parseEntityFile(raw);
+  const off = serializeEntityFile(entity, undefined, false);
+  const on = serializeEntityFile(entity, undefined, true);
+  // Gate off: no type metadata is emitted (matches the questions-path gate).
+  assert.doesNotMatch(off, /^type:/m);
+  // Gate on: exactly one type, recomputed from the entity kind.
+  assert.equal(on.split("\n").filter((line) => line.startsWith("type:")).length, 1);
+  assert.match(on, /^type: Person$/m);
+});

package/src/okf/type-mapping.ts

@@ -0,0 +1,79 @@
+/**
+ * OKF v0.1 `type` mapping (issue #1946) — the single source of truth for
+ * the inert `type` metadata emitted alongside Remnic's canonical fields.
+ *
+ * `category` remains the canonical internal field; `type` is
+ * presentation/interop metadata for OKF consumers and NEVER overrides
+ * `category` on parse (the parser reads `type` into its own field only).
+ */
+import path from "node:path";
+
+/** OKF `type` values derived from Remnic memory categories. */
+export const OKF_TYPE_BY_CATEGORY: Readonly<Record<string, string>> = Object.freeze({
+  fact: "Memory Fact",
+  decision: "Decision",
+  preference: "Preference",
+  commitment: "Commitment",
+  relationship: "Relationship",
+  principle: "Principle",
+  moment: "Moment",
+  skill: "Skill",
+  correction: "Correction",
+  rule: "Rule",
+});
+
+/** Fallback for categories not listed above (unknown/future categories). */
+export const OKF_TYPE_FALLBACK = "Memory";
+
+/** Stable domain seam over the category table (single mapping source, AGENTS.md pattern 9). */
+export function okfTypeForCategory(category: string): string {
+  return OKF_TYPE_BY_CATEGORY[category] ?? OKF_TYPE_FALLBACK;
+}
+
+/** Artifact memories report `Artifact` regardless of their storage category. */
+export function okfTypeForMemory(fm: { category: string; artifactType?: string }): string {
+  return fm.artifactType ? "Artifact" : okfTypeForCategory(fm.category);
+}
+
+/** OKF types for entity files, derived from the entity kind. */
+export const OKF_TYPE_BY_ENTITY_KIND: Readonly<Record<string, string>> = Object.freeze({
+  person: "Person",
+  company: "Company",
+  organization: "Organization",
+  project: "Project",
+  topic: "Topic",
+  technology: "Technology",
+  place: "Place",
+  event: "Event",
+});
+
+/** Stable domain seam over the entity-kind table (single mapping source). */
+export function okfTypeForEntityKind(kind: string | undefined): string {
+  const normalized = kind?.trim().toLowerCase();
+  return (normalized !== undefined && OKF_TYPE_BY_ENTITY_KIND[normalized]) || "Entity";
+}
+
+/** Fixed OKF types for non-memory bundle files. */
+export const OKF_PROFILE_TYPE = "Profile";
+export const OKF_QUESTION_TYPE = "Question";
+export const OKF_DECISION_RECORD_TYPE = "Decision Record";
+
+/**
+ * OKF §6/§7 reserve `index.md` and `log.md` for bundle-level files with a
+ * different contract. Remnic never writes them (separate issue), and writes
+ * targeting those basenames are rejected outright so a stray ID can never
+ * shadow a reserved bundle file.
+ */
+export const OKF_RESERVED_BASENAMES: Readonly<Record<string, true>> = Object.freeze({
+  "index.md": true,
+  "log.md": true,
+});
+
+export function assertNotOkfReservedBasename(filePath: string): void {
+  const basename = path.basename(filePath);
+  if (OKF_RESERVED_BASENAMES[basename] === true) {
+    throw new Error(
+      `OKF reserved basename '${basename}' is not a valid memory file target (${filePath}); OKF §6/§7 reserves it for bundle-level files.`,
+    );
+  }
+}

package/src/orchestrator.ts

@@ -1410,6 +1410,8 @@ export class Orchestrator {
     // StorageManager over it (including ephemeral recall sub-stage instances)
     // honors the operator's rollback lever.
     StorageManager.setScopedCacheInvalidationDefault(config.memoryDir, scopedCacheInvalidationEnabled);
+    // OKF conformance gate (issue #1946): child dirs (namespaces, cold roots) inherit via ancestor walk.
+    StorageManager.setOkfConformanceDefault(config.memoryDir, config.okf?.conformanceEnabled);
     this.profiler = new ProfilingCollector({
       enabled: resolvePipelineProcessingCapabilities(this.config).profiling,
       storageDir: config.profilingStorageDir || path.join(config.memoryDir, "profiling"),