refactor(registry): split registry store ownership

Author: kushagrchitkar

docs/intentional-architecture-rewrite-2026-06-27/decision-log.md

@@ -197,6 +197,8 @@ Setup has two edge layers. `src/edges/cli/setup/index.ts` is the public command
 
 Claude auth stays provider-owned, but provider-owned does not mean one file. `src/agent/providers/claude/auth.ts` owns auth policy and public re-exports. `auth-cli.ts` owns Claude executable discovery, public CLI spawning, legacy SDK CLI fallback, timeout behavior, and subprocess output collection. `auth-status.ts` owns the parsed JSON contract returned by `claude auth status --json`.
 
+Wiki-registry storage is not one bucket. `src/stores/wiki-registry/store.ts` owns registry read/write/add/drop/find persistence verbs. `codec.ts` owns parsing and validating `registry.json`. `lookup.ts` owns name/path matching over injected path equality. `filesystem.ts` owns path reachability, wiki-root checks, and global-directory creation. `types.ts` owns registry entry and lookup contracts.
+
 Codex app-server runtime has two layers. `app-server.ts` coordinates provider runtime state: request/config setup, JSON-RPC transport wiring, notification mapping, root-turn completion, turn watchdogs, and final result projection. `app-server-process.ts` owns child-process mechanics: spawning the Codex app-server, decoding stdout JSONL into protocol messages, collecting stderr for close failures, registering signal handlers, writing JSON-RPC messages to stdin, and terminating the managed child.
 
 Codex app-server notifications are routed by notification kind. `app-notifications.ts` owns the top-level method router and generic notification categories. `app-agent-messages.ts` owns agent-message semantics: text deltas, root result capture, structured output parsing, invalid structured-output failure state, and helper-agent completion events. `app-terminal-events.ts` owns terminal event semantics: turn completion, warnings, app-server error notifications, terminal run-state success/failure mutation, and `classifyCodexFailure` calls. Tool display, usage parsing, actor tracing, root-turn detection, and process mechanics stay in their existing named files.

docs/intentional-architecture-rewrite-2026-06-27/status.md

@@ -142,6 +142,7 @@ This is no longer a small cleanup branch. It is a real ownership rewrite.
 - Moved setup raw multi-select keyboard mechanics into a reusable setup input-control file, leaving instruction-target choice focused on target semantics and line-mode parsing.
 - Split setup phase orchestration into `setup-flow.ts`, leaving setup `index.ts` as the public TUI entry wrapper and next-step renderer.
 - Split Claude auth provider internals into auth policy, CLI subprocess mechanics, and parsed status-contract files under `src/agent/providers/claude/`.
+- Split wiki-registry storage into read/write mutation verbs, JSON codec, lookup, filesystem reachability, and type contracts.
 - Moved repeated store atomic-write temp-file mechanics into `src/stores/atomic-write.ts`, removing process-PID temp names from job and sync stores.
 - Split most command rendering into command-private render files.
 - Added architecture-boundary tests to stop old dependency leaks from returning.

docs/intentional-architecture-rewrite-2026-06-27/worklog.md

@@ -2020,3 +2020,13 @@ Two-hundred-eighty-third production slice:
 - Added `src/agent/providers/claude/auth-status.ts` for the parsed Claude auth JSON contract.
 - Kept `auth.ts` as the provider-owned auth policy surface: public auth check, subscription/API-key acceptance, unauthenticated message, and public re-exports.
 - Strengthened provider boundary tests so auth policy does not regain child-process mechanics or raw JSON parsing.
+
+Two-hundred-eighty-fourth production slice:
+
+- Split `src/stores/wiki-registry/store.ts` into registry persistence, codec, lookup, filesystem, and type owners.
+- Added `src/stores/wiki-registry/codec.ts` for registry JSON parsing and validation.
+- Added `src/stores/wiki-registry/lookup.ts` for name/path matching over injected path equality.
+- Added `src/stores/wiki-registry/filesystem.ts` for reachability, wiki-root checks, and global directory creation.
+- Added `src/stores/wiki-registry/types.ts` for registry entry and path-lookup contracts.
+- Kept `store.ts` focused on read/write/add/drop/find persistence verbs.
+- Strengthened architecture tests so registry parsing, path lookup, and filesystem checks do not collapse back into the store catchall.

src/stores/wiki-registry/codec.ts

@@ -0,0 +1,69 @@
+import { UserFacingError } from "../../shared/user-facing-error.js";
+import type { RegistryEntry } from "./types.js";
+
+export function parseRegistryFile(
+  raw: string,
+  registryPath: string,
+): RegistryEntry[] {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    return [];
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new UserFacingError(
+      `registry at ${registryPath} is not valid JSON: ${message}`,
+      { data: { path: registryPath } },
+    );
+  }
+
+  if (!Array.isArray(parsed)) {
+    throw new UserFacingError(
+      `registry at ${registryPath} must be a JSON array`,
+      { data: { path: registryPath } },
+    );
+  }
+
+  return parsed.map((item, index) =>
+    parseRegistryEntry(item, index, registryPath)
+  );
+}
+
+function parseRegistryEntry(
+  item: unknown,
+  index: number,
+  registryPath: string,
+): RegistryEntry {
+  if (typeof item !== "object" || item === null) {
+    throw new UserFacingError(
+      `registry entry ${index} is not an object`,
+      { data: { path: registryPath, index } },
+    );
+  }
+  const entry = item as Record<string, unknown>;
+  const name = typeof entry.name === "string" ? entry.name : "";
+  const path = typeof entry.path === "string" ? entry.path : "";
+  if (name.length === 0) {
+    throw new UserFacingError(
+      `registry entry ${index} is missing a non-empty "name"`,
+      { data: { path: registryPath, index, field: "name" } },
+    );
+  }
+  if (path.length === 0) {
+    throw new UserFacingError(
+      `registry entry ${index} is missing a non-empty "path"`,
+      { data: { path: registryPath, index, field: "path" } },
+    );
+  }
+  return {
+    name,
+    description: typeof entry.description === "string" ? entry.description : "",
+    path,
+    registered_at:
+      typeof entry.registered_at === "string" ? entry.registered_at : "",
+  };
+}

src/stores/wiki-registry/filesystem.ts

@@ -0,0 +1,26 @@
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+import { getGlobalAlmanacDir } from "../global-paths.js";
+import type { RegistryEntry } from "./types.js";
+
+/**
+ * A registry path is reachable if something still exists at that path.
+ * Unreachable entries stay in the registry until an explicit drop.
+ */
+export function isRegistryEntryReachable(entry: RegistryEntry): boolean {
+  return entry.path.length > 0 && existsSync(entry.path);
+}
+
+export function isRegistryEntryWikiRoot(entry: RegistryEntry): boolean {
+  return entry.path.length > 0 && existsSync(join(entry.path, ".almanac"));
+}
+
+/**
+ * Ensure the global `.almanac/` directory exists. Safe to call repeatedly;
+ * `mkdir recursive` is a no-op when the directory already exists.
+ */
+export async function ensureGlobalDir(): Promise<void> {
+  await mkdir(getGlobalAlmanacDir(), { recursive: true });
+}

src/stores/wiki-registry/index.ts

@@ -1,13 +1,17 @@
 export {
   addEntry,
   dropEntry,
-  ensureGlobalDir,
   findEntry,
-  findRegistryEntry,
-  isRegistryEntryReachable,
-  isRegistryEntryWikiRoot,
   readRegistry,
   writeRegistry,
-  type RegistryEntry,
-  type RegistryPathLookupOptions,
 } from "./store.js";
+export { ensureGlobalDir } from "./filesystem.js";
+export {
+  isRegistryEntryReachable,
+  isRegistryEntryWikiRoot,
+} from "./filesystem.js";
+export { findRegistryEntry } from "./lookup.js";
+export type {
+  RegistryEntry,
+  RegistryPathLookupOptions,
+} from "./types.js";

src/stores/wiki-registry/lookup.ts

@@ -0,0 +1,26 @@
+import type {
+  RegistryEntry,
+  RegistryPathLookupOptions,
+} from "./types.js";
+
+export function findRegistryEntry(
+  entries: RegistryEntry[],
+  params: {
+    name?: string;
+    path?: string;
+  },
+  options: RegistryPathLookupOptions = {},
+): RegistryEntry | null {
+  const pathEquals = options.pathEquals ?? exactPathEquality;
+  for (const entry of entries) {
+    if (params.name !== undefined && entry.name === params.name) return entry;
+    if (params.path !== undefined && pathEquals(entry.path, params.path)) {
+      return entry;
+    }
+  }
+  return null;
+}
+
+export function exactPathEquality(a: string, b: string): boolean {
+  return a === b;
+}

src/stores/wiki-registry/store.ts

@@ -1,31 +1,16 @@
-import { existsSync } from "node:fs";
-import { mkdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { readFile } from "node:fs/promises";
 
-import { getGlobalAlmanacDir } from "../global-paths.js";
 import { getRegistryPath } from "./paths.js";
-import type { PathEquality } from "../../shared/path-equality.js";
-import { UserFacingError } from "../../shared/user-facing-error.js";
 import { writeTextFileAtomically } from "../atomic-write.js";
-
-/**
- * One entry in `~/.almanac/registry.json`.
- *
- * `name` is the canonical kebab-case slug the user types. `path` is the
- * absolute repo root (the directory that contains `.almanac/`). We store
- * absolute paths so cross-wiki resolution works regardless of the caller's
- * cwd.
- */
-export interface RegistryEntry {
-  name: string;
-  description: string;
-  path: string;
-  registered_at: string;
-}
-
-export interface RegistryPathLookupOptions {
-  pathEquals?: PathEquality;
-}
+import { parseRegistryFile } from "./codec.js";
+import {
+  exactPathEquality,
+  findRegistryEntry,
+} from "./lookup.js";
+import type {
+  RegistryEntry,
+  RegistryPathLookupOptions,
+} from "./types.js";
 
 /**
  * Read the registry file into memory.
@@ -46,64 +31,7 @@ export async function readRegistry(): Promise<RegistryEntry[]> {
     throw err;
   }
 
-  const trimmed = raw.trim();
-  if (trimmed.length === 0) {
-    return [];
-  }
-
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(trimmed);
-  } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : String(err);
-    throw new UserFacingError(
-      `registry at ${registryPath} is not valid JSON: ${message}`,
-      { data: { path: registryPath } },
-    );
-  }
-
-  if (!Array.isArray(parsed)) {
-    throw new UserFacingError(
-      `registry at ${registryPath} must be a JSON array`,
-      { data: { path: registryPath } },
-    );
-  }
-
-  // Validate every entry. We do NOT silently coerce missing `name` or
-  // `path` — an entry with `name: ""` would be unremovable via `--drop`
-  // and an empty `path` would match any `findEntry({ path: "" })` call.
-  // If someone hand-edited the registry into a bad state, surfacing the
-  // error is strictly better than limping along with corrupt data.
-  return parsed.map((item, idx) => {
-    if (typeof item !== "object" || item === null) {
-      throw new UserFacingError(
-        `registry entry ${idx} is not an object`,
-        { data: { path: registryPath, index: idx } },
-      );
-    }
-    const e = item as Record<string, unknown>;
-    const name = typeof e.name === "string" ? e.name : "";
-    const path = typeof e.path === "string" ? e.path : "";
-    if (name.length === 0) {
-      throw new UserFacingError(
-        `registry entry ${idx} is missing a non-empty "name"`,
-        { data: { path: registryPath, index: idx, field: "name" } },
-      );
-    }
-    if (path.length === 0) {
-      throw new UserFacingError(
-        `registry entry ${idx} is missing a non-empty "path"`,
-        { data: { path: registryPath, index: idx, field: "path" } },
-      );
-    }
-    return {
-      name,
-      description: typeof e.description === "string" ? e.description : "",
-      path,
-      registered_at:
-        typeof e.registered_at === "string" ? e.registered_at : "",
-    };
-  });
+  return parseRegistryFile(raw, registryPath);
 }
 
 /**
@@ -177,48 +105,6 @@ export async function findEntry(
   return findRegistryEntry(await readRegistry(), params, options);
 }
 
-export function findRegistryEntry(
-  entries: RegistryEntry[],
-  params: {
-    name?: string;
-    path?: string;
-  },
-  options: RegistryPathLookupOptions = {},
-): RegistryEntry | null {
-  const pathEquals = options.pathEquals ?? exactPathEquality;
-  for (const entry of entries) {
-    if (params.name !== undefined && entry.name === params.name) return entry;
-    if (params.path !== undefined && pathEquals(entry.path, params.path)) {
-      return entry;
-    }
-  }
-  return null;
-}
-
-/**
- * A registry path is reachable if something still exists at that path.
- * Unreachable entries stay in the registry until an explicit drop.
- */
-export function isRegistryEntryReachable(entry: RegistryEntry): boolean {
-  return entry.path.length > 0 && existsSync(entry.path);
-}
-
-export function isRegistryEntryWikiRoot(entry: RegistryEntry): boolean {
-  return entry.path.length > 0 && existsSync(join(entry.path, ".almanac"));
-}
-
-/**
- * Ensure the global `.almanac/` directory exists. Safe to call repeatedly;
- * `mkdir recursive` is a no-op when the directory already exists.
- */
-export async function ensureGlobalDir(): Promise<void> {
-  await mkdir(getGlobalAlmanacDir(), { recursive: true });
-}
-
 function isNodeError(err: unknown): err is NodeJS.ErrnoException {
   return err instanceof Error && "code" in err;
 }
-
-function exactPathEquality(a: string, b: string): boolean {
-  return a === b;
-}

src/stores/wiki-registry/types.ts

@@ -0,0 +1,20 @@
+import type { PathEquality } from "../../shared/path-equality.js";
+
+/**
+ * One entry in `~/.almanac/registry.json`.
+ *
+ * `name` is the canonical kebab-case slug the user types. `path` is the
+ * absolute repo root (the directory that contains `.almanac/`). We store
+ * absolute paths so cross-wiki resolution works regardless of the caller's
+ * cwd.
+ */
+export interface RegistryEntry {
+  name: string;
+  description: string;
+  path: string;
+  registered_at: string;
+}
+
+export interface RegistryPathLookupOptions {
+  pathEquals?: PathEquality;
+}

test/architecture-indexer-diagnostics-boundaries.test.ts

@@ -290,27 +290,35 @@ describe("architecture boundaries: indexer, diagnostics, and registry", () => {
       "src/services/wiki/autoregistration.ts",
     );
     const registryStore = await readSource("src/stores/wiki-registry/store.ts");
+    const registryTypes = await readSource("src/stores/wiki-registry/types.ts");
+    const registryLookup = await readSource("src/stores/wiki-registry/lookup.ts");
     const cliAutoRegistration = await readSource(
       "src/edges/cli/autoregistration.ts",
     );
     const platformPathCase = await readSource("src/platform/path-case.ts");
     const sharedPathEquality = await readSource("src/shared/path-equality.ts");
 
     expect(existsSync(join(ROOT, "src/stores/wiki-registry/store.ts"))).toBe(true);
+    expect(existsSync(join(ROOT, "src/stores/wiki-registry/types.ts"))).toBe(true);
+    expect(existsSync(join(ROOT, "src/stores/wiki-registry/lookup.ts"))).toBe(true);
     expect(existsSync(join(ROOT, "src/platform/path-case.ts"))).toBe(true);
     expect(existsSync(join(ROOT, "src/shared/path-equality.ts"))).toBe(true);
     expect(existsSync(join(ROOT, "src/edges/cli/autoregistration.ts"))).toBe(true);
     expect(existsSync(join(ROOT, "src/stores/wiki/registry/store.ts"))).toBe(false);
     expect(existsSync(join(ROOT, "src/stores/wiki/registry/index.ts"))).toBe(false);
     expect(existsSync(join(ROOT, "src/stores/wiki/registry"))).toBe(false);
     expect(sharedPathEquality).toContain("type PathEquality");
-    expect(registryStore).toContain("shared/path-equality.js");
+    expect(registryTypes).toContain("shared/path-equality.js");
     expect(registryStore).not.toContain("RegistryPathEquality");
-    expect(registryStore).toContain("pathEquals");
+    expect(registryLookup).toContain("pathEquals");
     expect(registryStore).not.toContain("platform/path-case");
+    expect(registryLookup).not.toContain("platform/path-case");
     expect(registryStore).not.toContain("pathsEqualOnCurrentPlatform");
+    expect(registryLookup).not.toContain("pathsEqualOnCurrentPlatform");
     expect(registryStore).not.toContain("process.platform");
+    expect(registryLookup).not.toContain("process.platform");
     expect(registryStore).not.toContain("toLowerCase()");
+    expect(registryLookup).not.toContain("toLowerCase()");
     expect(autoRegistration).toContain("findRegistryEntry");
     expect(autoRegistration).toContain("RegistryPathLookupOptions");
     expect(autoRegistration).not.toContain("platform/path-case");