@remnic/core 9.64.0 → 9.64.2

package/src/location/types.ts

@@ -0,0 +1,95 @@
+/**
+ * Location context subsystem — shared types (issue #2044).
+ *
+ * A host-agnostic foundation: the provider contract, the observation/day
+ * shapes, and health-check results. No HTTP client lives here — providers are
+ * registered from host adapters (a future provider package is one such
+ * adapter), keeping `@remnic/core` free of host SDKs and network specifics.
+ *
+ * All timestamps are UTC ISO-8601; day bucketing is half-open [start, end).
+ */
+
+/** A named place the user was observed at. */
+export interface LocationPlace {
+  /** Provider-stable place identifier. */
+  id: string;
+  /** Human-readable label, already redacted by the provider. */
+  label: string;
+  kind?: "home" | "work" | "poi" | "transit" | "other";
+  /** Present only when coordinate retention is enabled. */
+  latitude?: number;
+  longitude?: number;
+}
+
+/** One place observation at a single instant, from a single provider. */
+export interface LocationObservation {
+  /** UTC ISO-8601 observation instant. */
+  observedAtUtc: string;
+  place: LocationPlace;
+  /** Provider confidence in [0,1], when reported. */
+  confidence?: number;
+}
+
+/** One page of observations from a provider fetch. */
+export interface LocationObservationPage {
+  observations: LocationObservation[];
+  nextCursor: string | null;
+}
+
+/** Result of a provider auth/health probe. */
+export interface LocationProviderCheck {
+  ok: boolean;
+  detail?: string;
+}
+
+/**
+ * Provider contract for a location source. Implemented by host adapters and
+ * registered in `registry.ts`; core never statically imports a provider
+ * package, so à-la-carte installs stay partial (a source whose provider is
+ * not registered is skipped, not an error).
+ */
+export interface LocationProvider {
+  /** Stable provider id (registry key; matches a config source id). */
+  id: string;
+  displayName: string;
+  /** Probe connectivity/auth without mutating anything. */
+  verify(signal?: AbortSignal): Promise<LocationProviderCheck>;
+  /** Fetch every observation in the half-open [startUtc, endUtc) window. */
+  fetchObservations(opts: {
+    startUtc: string;
+    endUtc: string;
+    cursor?: string | null;
+    signal?: AbortSignal;
+  }): Promise<LocationObservationPage>;
+}
+
+/** One configured location source: a registered provider plus its toggle. */
+export interface LocationSourceConfig {
+  /** Must match a registered provider id. */
+  id: string;
+  /** `false` short-circuits this source only. */
+  enabled: boolean;
+}
+
+/** Opt-in location synchronization settings. */
+export interface LocationConfig {
+  /** Master gate: `false` short-circuits every location path. */
+  enabled: boolean;
+  /** IANA timezone used to bucket observations into local days. */
+  timezone: string;
+  /** Number of local days to synchronize per run; integer 1..90. */
+  syncDays: number;
+  /**
+   * When `false` (the default), place coordinates are dropped before any
+   * persistence, rendering, or error reporting — only place labels remain.
+   */
+  retainCoordinates: boolean;
+  sources: LocationSourceConfig[];
+}
+
+/** A time-resolved place visit derived from consecutive observations. */
+export interface LocationSegment {
+  startUtc: string;
+  endUtc: string;
+  place: LocationPlace;
+}

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/orchestration/generic-recall-paths.ts

@@ -6,6 +6,7 @@ import { ALL_CATEGORY_DIRS } from "../utils/category-dir.js";
 import {
   isActivityDigestPath,
   isArtifactMemoryPath,
+  isLocationDayPath,
   isMeetingRecordPath,
 } from "./orchestrator-helpers.js";
 
@@ -133,6 +134,7 @@ export function isSearchExcludedPath(
     if (
       isArtifactMemoryPath(candidate) ||
       isNamespacedActivityDigestPath(candidate, policy.memoryDir) ||
+      isNamespacedLocationDayPath(candidate, policy.memoryDir) ||
       isMeetingRecordPath(candidate)
     ) {
       return true;
@@ -160,6 +162,21 @@ function isNamespacedActivityDigestPath(candidate: string, memoryDir?: string):
   return isActivityDigestPath(namespaced[2] ?? "", memoryDir);
 }
 
+/**
+ * The location day-file check, applied against the NAMESPACE root a hit came
+ * from — same rationale as `isNamespacedActivityDigestPath`: a namespaced
+ * search rewrites hits to absolute paths beneath `…/namespaces/<ns>/`, so the
+ * root-aware predicate is re-measured against the namespace's own root.
+ */
+function isNamespacedLocationDayPath(candidate: string, memoryDir?: string): boolean {
+  if (isLocationDayPath(candidate, memoryDir)) return true;
+  if (memoryDir === undefined || memoryDir.length === 0) return false;
+  const relative = path.relative(memoryDir, path.resolve(memoryDir, candidate));
+  const namespaced = /^namespaces[\\/]([^\\/]+)[\\/](.*)$/.exec(relative);
+  if (namespaced === null) return false;
+  return isLocationDayPath(namespaced[2] ?? "", memoryDir);
+}
+
 /** A path as given, plus its form with a leading COLLECTION segment removed. */
 function collectionSpellings(
   filePath: string,