@remnic/core 9.65.7 → 9.66.0

package/src/location/tagging.test.ts

@@ -0,0 +1,119 @@
+/**
+ * Write-time location tagging regression (issue #2046): the post-write
+ * enrichment path the extraction coordinator calls after a batch is durable.
+ * Pins the gates, the provider-owned patch contract (StorageManager
+ * chokepoint, actor "location-tagging"), and per-memory failure isolation.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { MemoryFile } from "../types.js";
+import type { StorageManager } from "../index.js";
+import { parseLocationConfig } from "./config.js";
+import type { LocationSourceSegments } from "./matching.js";
+import { enrichMemoriesWithLocation } from "./tagging.js";
+
+function memory(id: string, frontmatter: Record<string, unknown> = {}): MemoryFile {
+  return { path: `facts/${id}.md`, content: "body", frontmatter: { id, ...frontmatter } } as MemoryFile;
+}
+
+function taggedConfig() {
+  return parseLocationConfig({
+    enabled: true,
+    timezone: "UTC",
+    sources: [{ id: "reitti" }],
+    tagging: { enabled: true },
+  });
+}
+
+const HOME: LocationSourceSegments = {
+  sourceId: "reitti",
+  segments: [
+    {
+      startUtc: "2026-08-01T12:00:00.000Z",
+      endUtc: "2026-08-01T14:00:00.000Z",
+      place: { id: "reitti:place:home-1", label: "Home", kind: "home" },
+      confidence: 0.9,
+    },
+  ],
+};
+
+const index = new Map([["2026-08-01", [HOME]]]);
+
+function storageFor(memories: MemoryFile[], failWriteFor?: string) {
+  const byId = new Map(memories.map((m) => [m.frontmatter.id, m]));
+  const writes: Array<{ id: string; patch: Record<string, unknown>; actor: string }> = [];
+  const storage: Pick<StorageManager, "getMemoryById" | "writeMemoryFrontmatter"> = {
+    getMemoryById: (id) => Promise.resolve(byId.get(id) ?? null),
+    writeMemoryFrontmatter: (file, patch, lifecycle) => {
+      if (file.frontmatter.id === failWriteFor) return Promise.reject(new Error("disk full"));
+      writes.push({ id: file.frontmatter.id, patch: patch as Record<string, unknown>, actor: lifecycle?.actor ?? "" });
+      return Promise.resolve(true);
+    },
+  };
+  return { storage, writes };
+}
+
+test("write-time enrichment tags matched memories through the storage chokepoint", async () => {
+  const { storage, writes } = storageFor([
+    memory("matched", { valid_at: "2026-08-01T12:30:00.000Z", invalid_at: "2026-08-01T13:30:00.000Z", tags: [] }),
+    memory("untimed", { tags: [] }),
+    memory("elsewhere", { valid_at: "2026-08-02T12:30:00.000Z", invalid_at: "2026-08-02T13:30:00.000Z", tags: [] }),
+  ]);
+  const counts = await enrichMemoriesWithLocation({
+    storage,
+    memoryIds: ["matched", "untimed", "elsewhere"],
+    memoryDir: "/unused-when-index-passed",
+    config: taggedConfig(),
+    index,
+  });
+
+  assert.equal(counts.tagged, 1);
+  assert.equal(counts.untimed, 1);
+  assert.equal(counts.unmatched, 1);
+  assert.equal(counts.failed, 0);
+  assert.equal(writes.length, 1, "only the matched memory is patched");
+  assert.equal(writes[0]?.id, "matched");
+  assert.equal(writes[0]?.actor, "location-tagging");
+  const tags = (writes[0]?.patch.tags as string[] | undefined) ?? [];
+  assert.ok(tags.some((tag) => tag.startsWith("location:")), `provider tag written: ${JSON.stringify(tags)}`);
+  const attributes = (writes[0]?.patch.structuredAttributes as Record<string, string> | undefined) ?? {};
+  assert.equal(attributes.locationSource, "reitti");
+  assert.equal(attributes.locationPlaceId, "reitti:place:home-1");
+});
+
+test("tagging gates off inside the shared core: no reads, no writes", async () => {
+  const { storage, writes } = storageFor([
+    memory("matched", { valid_at: "2026-08-01T12:30:00.000Z", invalid_at: "2026-08-01T13:30:00.000Z", tags: [] }),
+  ]);
+  const counts = await enrichMemoriesWithLocation({
+    storage,
+    memoryIds: ["matched"],
+    memoryDir: "/unused-when-index-passed",
+    config: parseLocationConfig({ enabled: true, timezone: "UTC", sources: [{ id: "reitti" }] }),
+    index,
+  });
+  assert.equal(counts.tagged, 0);
+  assert.equal(writes.length, 0);
+});
+
+test("a failing memory write is counted and never blocks the others", async () => {
+  const { storage, writes } = storageFor(
+    [
+      memory("boom", { valid_at: "2026-08-01T12:30:00.000Z", invalid_at: "2026-08-01T13:30:00.000Z", tags: [] }),
+      memory("fine", { valid_at: "2026-08-01T12:30:00.000Z", invalid_at: "2026-08-01T13:30:00.000Z", tags: [] }),
+    ],
+    "boom",
+  );
+  const counts = await enrichMemoriesWithLocation({
+    storage,
+    memoryIds: ["boom", "fine"],
+    memoryDir: "/unused-when-index-passed",
+    config: taggedConfig(),
+    index,
+  });
+  assert.equal(counts.failed, 1);
+  assert.equal(counts.tagged, 1);
+  assert.deepEqual(writes.map((w) => w.id), ["fine"]);
+});

package/src/location/tagging.ts

@@ -0,0 +1,277 @@
+/**
+ * Location tagging service (issue #2046) — the IO half around the pure
+ * matcher in `matching.ts`. Three consumers share it so the policy can never
+ * fork:
+ *
+ *  1. Write-time enrichment: after an extraction batch has cleared the
+ *     trust/importance/content-hash gates and persisted, the caller tags the
+ *     new memories (post-write, best-effort, never fails the extraction).
+ *  2. Historical backfill (`location/backfill.ts`): the same plan/apply core
+ *     over a bounded date range, idempotent by construction.
+ *  3. Wearable conversation fill: `WearableConversation.location` is filled
+ *     ONLY when the source did not provide one and the match passes policy.
+ *
+ * Segment data comes from the machine-global location sync state
+ * (`state/locations/sync.json`, ≤ 90 tracked days — matching the bounded
+ * backfill range). Reads are plain file loads; every memory mutation goes
+ * through `StorageManager.writeMemoryFrontmatter`, the atomic frontmatter
+ * chokepoint that preserves content (and therefore the content hash),
+ * lifecycle, and versioning invariants.
+ */
+
+import type { StorageManager } from "../index.js";
+import { log } from "../logger.js";
+import type { MemoryFile } from "../types.js";
+import type { WearableConversation } from "../wearables/types.js";
+import { localDayKey, placeDurations } from "./intervals.js";
+import {
+  matchDominantPlace,
+  memoryLocationWindow,
+  planLocationUpdate,
+  type LocationSourceSegments,
+  type LocationTagPolicy,
+  type LocationUpdatePlan,
+} from "./matching.js";
+import { loadLocationSyncState } from "./store.js";
+import type { LocationConfig } from "./types.js";
+
+/** Segments for one local day, per source id, from the sync state. */
+export type DaySegmentIndex = Map<string, LocationSourceSegments[]>;
+
+/** Load every tracked day's per-source segments (one file read). */
+export async function loadDaySegmentIndex(memoryDir: string): Promise<DaySegmentIndex> {
+  const state = await loadLocationSyncState(memoryDir);
+  const index: DaySegmentIndex = new Map();
+  for (const [sourceId, source] of Object.entries(state.sources)) {
+    for (const [date, payload] of Object.entries(source.days ?? {})) {
+      const entry: LocationSourceSegments = { sourceId, segments: payload.segments ?? [] };
+      const existing = index.get(date);
+      if (existing === undefined) index.set(date, [entry]);
+      else existing.push(entry);
+    }
+  }
+  return index;
+}
+
+export function locationTagPolicy(config: LocationConfig): LocationTagPolicy {
+  return {
+    minimumOverlapSeconds: config.minimumOverlapSeconds,
+    minimumConfidence: config.minimumConfidence,
+    retainCoordinates: config.retainCoordinates,
+  };
+}
+
+/** Every tagging path is off unless BOTH gates are on. */
+export function locationTaggingEnabled(config: LocationConfig): boolean {
+  return config.enabled && config.tagging.enabled;
+}
+
+/**
+ * Write-time post-persist hook (issue #2046): tag the memories an extraction
+ * batch just made durable. Best-effort by contract — gated on both location
+ * gates, and a location failure must never fail the extraction that already
+ * persisted.
+ */
+export async function tagPersistedMemories(
+  storage: StorageManager,
+  memoryIds: string[],
+  config: { memoryDir: string; location?: LocationConfig },
+): Promise<void> {
+  if (memoryIds.length === 0 || !config.location || !locationTaggingEnabled(config.location)) return;
+  try {
+    await enrichMemoriesWithLocation({
+      storage,
+      memoryIds,
+      memoryDir: config.memoryDir,
+      config: config.location,
+    });
+  } catch (locationError) {
+    log.warn("[location] post-write tagging failed (non-fatal)", locationError);
+  }
+}
+
+function segmentsForDays(index: DaySegmentIndex, days: readonly string[]): LocationSourceSegments[] {
+  const merged = new Map<string, LocationSourceSegments>();
+  for (const day of days) {
+    for (const entry of index.get(day) ?? []) {
+      const existing = merged.get(entry.sourceId);
+      if (existing === undefined) {
+        merged.set(entry.sourceId, { sourceId: entry.sourceId, segments: [...entry.segments] });
+        continue;
+      }
+      existing.segments.push(...entry.segments);
+    }
+  }
+  return [...merged.values()];
+}
+
+/** The full plan for one memory: window → segments → match → provider-owned diff. */
+function planForMemory(
+  frontmatter: Pick<MemoryFile["frontmatter"], "valid_at" | "observedAt" | "invalid_at" | "tags" | "structuredAttributes">,
+  index: DaySegmentIndex,
+  config: LocationConfig,
+): LocationUpdatePlan {
+  const policy = locationTagPolicy(config);
+  const result = memoryLocationWindow(frontmatter, (instant) => localDayKey(instant, config.timezone));
+  if (result.rejected === "span-too-long") return { outcome: "span-too-long" };
+  if (result.rejected === "untimed" || result.window === undefined || result.days === undefined) {
+    return { outcome: "untimed" };
+  }
+  const sources = segmentsForDays(index, result.days);
+  return planLocationUpdate(frontmatter, matchDominantPlace(result.window, sources, policy), policy);
+}
+
+export interface LocationEnrichmentCounts {
+  tagged: number;
+  updated: number;
+  removed: number;
+  unchanged: number;
+  unmatched: number;
+  manual: number;
+  untimed: number;
+  spanTooLong: number;
+  failed: number;
+}
+
+export function emptyEnrichmentCounts(): LocationEnrichmentCounts {
+  return {
+    tagged: 0,
+    updated: 0,
+    removed: 0,
+    unchanged: 0,
+    unmatched: 0,
+    manual: 0,
+    untimed: 0,
+    spanTooLong: 0,
+    failed: 0,
+  };
+}
+
+function countOutcome(counts: LocationEnrichmentCounts, outcome: LocationUpdatePlan["outcome"]): void {
+  if (outcome === "tagged") counts.tagged += 1;
+  else if (outcome === "updated") counts.updated += 1;
+  else if (outcome === "removed") counts.removed += 1;
+  else if (outcome === "unchanged") counts.unchanged += 1;
+  else if (outcome === "manual-metadata") counts.manual += 1;
+  else if (outcome === "unmatched") counts.unmatched += 1;
+  else if (outcome === "untimed") counts.untimed += 1;
+  else if (outcome === "span-too-long") counts.spanTooLong += 1;
+}
+
+export interface EnrichMemoriesOptions {
+  storage: Pick<StorageManager, "getMemoryById" | "writeMemoryFrontmatter">;
+  memoryDir: string;
+  config: LocationConfig;
+  /** Enrich exactly these memory ids (write-time path). */
+  memoryIds?: string[];
+  /** Pre-loaded memories (backfill path — one readAllMemories per run). */
+  memories?: MemoryFile[];
+  /** Reuse a caller-loaded segment index (backfill). */
+  index?: DaySegmentIndex;
+  /** Skip every mutation and only report (dry-run). */
+  dryRun?: boolean;
+}
+
+/**
+ * Apply the matcher to a set of memories and patch provider-owned location
+ * metadata. A failure on ONE memory is counted and skipped — it never blocks
+ * the others (failure isolation, issue #2046).
+ */
+export async function enrichMemoriesWithLocation(
+  options: EnrichMemoriesOptions,
+): Promise<LocationEnrichmentCounts> {
+  if (!locationTaggingEnabled(options.config)) return emptyEnrichmentCounts();
+  const counts = emptyEnrichmentCounts();
+  const index = options.index ?? (await loadDaySegmentIndex(options.memoryDir));
+
+  let memories = options.memories;
+  if (memories === undefined && options.memoryIds !== undefined) {
+    memories = [];
+    for (const id of options.memoryIds) {
+      const memory = await options.storage.getMemoryById(id);
+      if (memory !== null) memories.push(memory);
+    }
+  }
+  if (memories === undefined) return counts;
+
+  for (const memory of memories) {
+    try {
+      const plan = planForMemory(memory.frontmatter, index, options.config);
+      // Count patch outcomes (tagged/updated/removed) only after the write
+      // lands — a rejected write is `failed`, never also `tagged`.
+      if (plan.patch === undefined || options.dryRun === true) {
+        countOutcome(counts, plan.outcome);
+        continue;
+      }
+      await options.storage.writeMemoryFrontmatter(memory, plan.patch, { actor: "location-tagging" });
+      countOutcome(counts, plan.outcome);
+    } catch {
+      counts.failed += 1;
+    }
+  }
+  return counts;
+}
+
+/**
+ * Fill `WearableConversation.location` for conversations whose source did not
+ * provide one. Missing-only and source-aware: a provider-supplied value is
+ * never overwritten, and a failing conversation never blocks the others.
+ */
+export async function fillWearableConversationLocations(
+  conversations: WearableConversation[],
+  deps: { memoryDir: string; config: LocationConfig },
+): Promise<void> {
+  if (!locationTaggingEnabled(deps.config) || conversations.length === 0) return;
+  let index: DaySegmentIndex;
+  try {
+    index = await loadDaySegmentIndex(deps.memoryDir);
+  } catch {
+    return;
+  }
+  const policy = locationTagPolicy(deps.config);
+  for (const conversation of conversations) {
+    if (conversation.location !== undefined && conversation.location.length > 0) continue;
+    try {
+      const startMs = Date.parse(conversation.startIso);
+      const endMs = conversation.endIso !== undefined ? Date.parse(conversation.endIso) : Number.NaN;
+      const window =
+        Number.isFinite(startMs) && Number.isFinite(endMs) && endMs > startMs
+          ? { kind: "interval" as const, startUtc: conversation.startIso, endUtc: conversation.endIso as string }
+          : { kind: "instant" as const, atUtc: conversation.startIso };
+      const anchor = window.kind === "interval" ? new Date(Date.parse(window.endUtc) - 1).toISOString() : window.atUtc;
+      const days = [...new Set([localDayKey(anchor, deps.config.timezone), localDayKey(conversation.startIso, deps.config.timezone)])];
+      const outcome = matchDominantPlace(window, segmentsForDays(index, days), policy);
+      if (outcome.status === "matched") {
+        conversation.location = outcome.match.place.label;
+      }
+    } catch {
+      // One bad conversation never blocks the rest of the day's fill.
+    }
+  }
+}
+
+/** Render an opt-in, labels-only location context section for a day summary. */
+export async function renderDayLocationContext(
+  memoryDir: string,
+  date: string,
+  config: LocationConfig,
+): Promise<string | null> {
+  if (!locationTaggingEnabled(config)) return null;
+  const state = await loadLocationSyncState(memoryDir);
+  const segments = [];
+  for (const source of Object.values(state.sources)) {
+    for (const segment of source.days?.[date]?.segments ?? []) segments.push(segment);
+  }
+  if (segments.length === 0) return null;
+  const durations = placeDurations(segments)
+    .filter((duration) => ["home", "work", "poi"].includes(duration.place.kind ?? "poi"))
+    .sort((a, b) => (a.totalMs !== b.totalMs ? b.totalMs - a.totalMs : a.place.id < b.place.id ? -1 : 1));
+  if (durations.length === 0) return null;
+  const lines = durations.map((duration) => {
+    const minutes = Math.round(duration.totalMs / 60_000);
+    const hours = Math.floor(minutes / 60);
+    const rendered = hours <= 0 ? `${minutes}m` : `${hours}h ${String(minutes % 60).padStart(2, "0")}m`;
+    return `- ${duration.place.label.replace(/\s+/g, " ").replace(/[`*_]/g, "").trim()}: ${rendered}`;
+  });
+  return `## Location context\n\n${lines.join("\n")}`;
+}

package/src/location/types.ts

@@ -21,7 +21,6 @@ export interface LocationPlace {
   longitude?: number;
 }
 
-/** One place observation at a single instant, from a single provider. */
 export interface LocationObservation {
   /** UTC ISO-8601 observation instant. */
   observedAtUtc: string;
@@ -85,6 +84,27 @@ export interface LocationConfig {
    */
   retainCoordinates: boolean;
   sources: LocationSourceConfig[];
+  /**
+   * Minimum dominant-place overlap (seconds) required to tag a memory.
+   * `0` disables the overlap floor. Integer ≥ 0; default 300.
+   */
+  minimumOverlapSeconds: number;
+  /**
+   * Minimum provider-reported place confidence in [0,1] for a tagging
+   * match. Providers that report no confidence pass this gate (there is
+   * nothing to doubt), reported values below it fail. Default 0.7.
+   */
+  minimumConfidence: number;
+  /** Provider-owned location tagging gates (issue #2046). */
+  tagging: LocationTaggingConfig;
+}
+
+/** Opt-in gates for attaching provider location context to memories. */
+export interface LocationTaggingConfig {
+  /** `false` (default) disables every memory-tagging path. */
+  enabled: boolean;
+  /** Extra gate for the historical backfill command; default `false`. */
+  backfillEnabled: boolean;
 }
 
 /** A time-resolved place visit derived from consecutive observations. */
@@ -92,4 +112,6 @@ export interface LocationSegment {
   startUtc: string;
   endUtc: string;
   place: LocationPlace;
+  /** Minimum contributing observation confidence, when any was reported. */
+  confidence?: number;
 }

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

@@ -27,6 +27,7 @@ export const MCP_READ_ONLY_TOOL_SUFFIXES: Readonly<Record<string, true>> = {
   location_day: true,
   meetings_list: true,
   meetings_get: true,
+  standup: true,
   action_confidence: true,
   capsule_list: true,
   procedural_stats: true,

package/src/memory-action-policy.ts

@@ -78,3 +78,31 @@ export function evaluateMemoryActionPolicy(input: {
     eligibility,
   };
 }
+
+/**
+ * Gate for active-context SUMMARY/FILTER plans (issue #2347). The single
+ * deny rule is the shared `contextCompressionActionsEnabled` gate — a closed
+ * gate returns `feature_disabled` before any selection or model work. LLM
+ * summaries carry their own cap gate (`activeContextTransformLlmEnabled`)
+ * resolved at plan time, not here.
+ */
+export interface ActiveContextTransformPolicyResult {
+  decision: "allow" | "deny";
+  rationale: string;
+}
+
+export function evaluateActiveContextTransformPolicy(options: {
+  actionsEnabled: boolean;
+  operation: "SUMMARY" | "FILTER";
+}): ActiveContextTransformPolicyResult {
+  if (!options.actionsEnabled) {
+    return {
+      decision: "deny",
+      rationale: "contextCompressionActionsEnabled=false",
+    };
+  }
+  return {
+    decision: "allow",
+    rationale: `${options.operation.toLowerCase()}_eligible`,
+  };
+}

package/src/memory-projection-store.ts

@@ -130,11 +130,13 @@ function migrateMemoryCurrentTable(db: BetterSqlite3Database): void {
   if (!columns.has("preview_text")) {
     db.exec(`ALTER TABLE memory_current ADD COLUMN preview_text TEXT NOT NULL DEFAULT ''`);
   }
+  if (!columns.has("private_record")) db.exec(`ALTER TABLE memory_current ADD COLUMN private_record INTEGER NOT NULL DEFAULT 0; UPDATE memory_current SET private_record = 1 WHERE tags_json LIKE '%support-passport-%'`);
 }
 
 function memoryCurrentRequiresMigration(db: BetterSqlite3Database): boolean {
   const columns = listTableColumns(db, "memory_current");
-  return columns.size > 0 && (!columns.has("tags_json") || !columns.has("preview_text"));
+  return columns.size > 0 &&
+    (!columns.has("tags_json") || !columns.has("preview_text") || !columns.has("private_record"));
 }
 
 function migrateProjectionSchemaIfNeeded(memoryDir: string): void {

package/src/okf/cli.ts

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

package/src/okf/config.ts

@@ -10,11 +10,14 @@ export interface OkfConfig {
   conformanceEnabled: boolean;
   /** Opt-in governance sweep that backfills `type` on legacy files (default false). */
   sweepEnabled: boolean;
+  /** Generate OKF index.md files in the live store (default false). */
+  indexFilesEnabled: boolean;
 }
 
 export const DEFAULT_OKF_CONFIG: OkfConfig = Object.freeze({
   conformanceEnabled: true,
   sweepEnabled: false,
+  indexFilesEnabled: false,
 });
 
 export function parseOkfConfig(raw: unknown): OkfConfig {
@@ -27,8 +30,10 @@ export function parseOkfConfig(raw: unknown): OkfConfig {
   const record = raw as Record<string, unknown>;
   const conformance = coerceBooleanLike(record.conformanceEnabled, "okf.conformanceEnabled");
   const sweep = coerceBooleanLike(record.sweepEnabled, "okf.sweepEnabled");
+  const indexFiles = coerceBooleanLike(record.indexFilesEnabled, "okf.indexFilesEnabled");
   return {
     conformanceEnabled: conformance ?? DEFAULT_OKF_CONFIG.conformanceEnabled,
     sweepEnabled: sweep ?? DEFAULT_OKF_CONFIG.sweepEnabled,
+    indexFilesEnabled: indexFiles ?? DEFAULT_OKF_CONFIG.indexFilesEnabled,
   };
 }

package/src/okf/index-files.test.ts

@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { isGenericRecallExcludedPath } from "../orchestration/generic-recall-paths.js";
+import { parseOkfConfig } from "./config.js";
+import { OKF_INDEX_MARKER, runOkfIndexMaintenance } from "./index-files.js";
+
+function store(): string {
+  const root = mkdtempSync(path.join(tmpdir(), "okf-index-"));
+  mkdirSync(path.join(root, "facts", "2026-01-02"), { recursive: true });
+  writeFileSync(
+    path.join(root, "facts", "2026-01-02", "fact-1.md"),
+    "---\nid: fact-1\ncategory: fact\n---\nPostgres is the store.\n",
+  );
+  return root;
+}
+
+test("parseOkfConfig defaults indexFilesEnabled off", () => {
+  assert.equal(parseOkfConfig(undefined).indexFilesEnabled, false);
+  assert.equal(parseOkfConfig({ indexFilesEnabled: "false" }).indexFilesEnabled, false);
+  assert.equal(parseOkfConfig({ indexFilesEnabled: true }).indexFilesEnabled, true);
+});
+
+test("flag off writes nothing", async () => {
+  const root = store();
+  const report = await runOkfIndexMaintenance(root, false);
+  assert.deepEqual(report.written, []);
+  assert.throws(() => readFileSync(path.join(root, "facts", "2026-01-02", "index.md")));
+});
+
+test("flag on writes a deterministic generated index", async () => {
+  const root = store();
+  const first = await runOkfIndexMaintenance(root, true);
+  const second = await runOkfIndexMaintenance(root, true);
+  const file = path.join(root, "facts", "2026-01-02", "index.md");
+  assert.equal(first.written.length, 1);
+  assert.equal(second.written.length, 0);
+  const body = readFileSync(file, "utf8");
+  assert.match(body, new RegExp(OKF_INDEX_MARKER));
+  assert.match(body, /fact-1\.md/);
+});
+
+test("disable removes generated indexes and keeps user files", async () => {
+  const root = store();
+  await runOkfIndexMaintenance(root, true);
+  const user = path.join(root, "facts", "index.md");
+  writeFileSync(user, "# mine\n");
+  const report = await runOkfIndexMaintenance(root, false);
+  assert.ok(report.removed.some((item) => item.endsWith(`${path.sep}2026-01-02${path.sep}index.md`)));
+  assert.equal(readFileSync(user, "utf8"), "# mine\n");
+});
+
+test("reserved OKF basenames are excluded from generic recall", () => {
+  assert.equal(isGenericRecallExcludedPath("facts/2026-01-02/index.md"), true);
+  assert.equal(isGenericRecallExcludedPath("log.md"), true);
+  assert.equal(isGenericRecallExcludedPath("facts/2026-01-02/fact-1.md"), false);
+});