harden: swap finally safety, tests, retire runtime-test-isolation plan

Pair exitRuntimeSwap in outer finally; reset swap depth in test teardown.
Add createCodemap/configureResolver/makeWorktreeReindex coverage; consumer-clean
docs/changeset; delete plan and repoint orchestrator + roadmap.

Author: SutuSebastian

.changeset/runtime-test-isolation.md

@@ -2,4 +2,4 @@
 "@stainless-code/codemap": minor
 ---
 
-`createCodemap()` and `loadUserConfig()` now fail fast: switching to a different project root in the same process throws (audit `--base` worktree reindex is exempt), and invalid config files throw at load time instead of on first resolve.
+`createCodemap()` now fails fast when switching to a different project root in the same process (audit `--base` worktree reindex is exempt), and invalid config files throw at load time instead of on first use.

docs/architecture.md

@@ -234,13 +234,13 @@ The npm package exports **`createCodemap`**, **`Codemap`** (`query`, `index`), *
 2. **`await cm.index({ mode, files?, quiet? })`** — same pipeline as the CLI (incremental / full / targeted).
 3. **`cm.query(sql)`** — read-only SQL against `.codemap/index.db` (opens the DB per call).
 
-**Constraint:** One project root per process — a second `initCodemap` / `createCodemap` with a different `root` throws. Audit `--base` worktree reindex brackets root swaps via `runtime-swap.ts`. Re-init on the same root is allowed.
+**Constraint:** One project root per process — a second `initCodemap` / `createCodemap` with a different `root` throws. Audit `--base` worktree reindex brackets temporary root swaps (internal swap guard). Re-init on the same root is allowed.
 
 ### User config
 
 Optional **`<state-dir>/config.{ts,js,json}`** (default `.codemap/config.*`; default export: object or async factory). **`--config <path>`** overrides with an explicit file (absolute or relative to cwd). Example shape: [`codemap.config.example.json`](../codemap.config.example.json). **Self-healing (D11):** `<state-dir>/.gitignore` is reconciled to canonical on every codemap boot via **`ensureStateGitignore`** (`src/application/state-dir.ts`); JSON config is reconciled via **`ensureStateConfig`** (`src/application/state-config.ts` — prunes unknown keys with a warning, sorts alphabetically, write-only-on-drift). TS/JS configs are validate-only at load time. Bumping the canonical `STATE_GITIGNORE_BODY` constant or the Zod schema IS the migration — every consumer's project repairs itself on next boot. Single attachment point: **`src/cli/bootstrap-codemap.ts`** runs the reconcilers before `loadUserConfig`.
 
-**Validation:** **`codemapUserConfigSchema`** ([Zod](https://zod.dev)) — strict object (unknown keys are rejected). **`defineConfig({ ... })`**, **`parseCodemapUserConfig`**, **`loadUserConfig`**, and **`resolveCodemapConfig`** (CLI and merged `createCodemap({ config })`) all go through the same schema. Invalid config throws **`TypeError`** with a short path/message list.
+**Validation:** **`codemapUserConfigSchema`** ([Zod](https://zod.dev)) — strict object (unknown keys are rejected). **`defineConfig({ ... })`**, **`parseCodemapUserConfig`**, and **`resolveCodemapConfig`** (CLI and merged `createCodemap({ config })`) all go through the same schema; **`createCodemap`** and the CLI load path validate config files at load time. Invalid config throws **`TypeError`** with a short path/message list.
 
 **Exports:** `codemapUserConfigSchema`, `parseCodemapUserConfig`, `defineConfig`, and **`CodemapUserConfig`** (inferred type) from the package entry — see **`src/config.ts`** / **`dist/index.d.mts`**.
 

docs/plans/runtime-test-isolation.md

@@ -21,11 +21,11 @@
 
 ## PR schedule
 
-| PR    | Plan                                                            | Status                                                                              | Blocks                              |
-| ----- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------- |
-| **1** | lifted → [`architecture.md`](../architecture.md) (plan retired) | **merged** ([#180](https://github.com/stainless-code/codemap/pull/180) · `a5caca8`) | —                                   |
-| **2** | lifted → [`architecture.md`](../architecture.md) (plan retired) | **merged** ([#181](https://github.com/stainless-code/codemap/pull/181) · `aae172f`) | —                                   |
-| **3** | [`runtime-test-isolation.md`](./runtime-test-isolation.md)      | **in progress** (`fix/runtime-test-isolation`)                                      | PR **1** merged (PR **2** optional) |
+| PR    | Plan                                                            | Status                                                                                                  | Blocks |
+| ----- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------ |
+| **1** | lifted → [`architecture.md`](../architecture.md) (plan retired) | **merged** ([#180](https://github.com/stainless-code/codemap/pull/180) · `a5caca8`)                     | —      |
+| **2** | lifted → [`architecture.md`](../architecture.md) (plan retired) | **merged** ([#181](https://github.com/stainless-code/codemap/pull/181) · `aae172f`)                     | —      |
+| **3** | lifted → [`architecture.md`](../architecture.md) (plan retired) | **PR open** ([#182](https://github.com/stainless-code/codemap/pull/182) · `fix/runtime-test-isolation`) | —      |
 
 | — | — | **deferred** | golden `schema.test.ts` + path guards |
 | — | — | **skip** | atomic `ensureStateConfig` writes |
@@ -74,6 +74,7 @@ Evaluated 2026-06 against [roadmap § Floors](../roadmap.md#floors-v1-product-sh
 | 2026-06-05 | PR 2 harden | `/harden-pr full` — plan retired; CLI/MCP/docs parity.                        |
 | 2026-06-05 | PR 2 merge  | [#181](https://github.com/stainless-code/codemap/pull/181) → `aae172f`.       |
 | 2026-06-05 | PR 3 start  | `fix/runtime-test-isolation` — root guards + test teardown + config validate. |
+| 2026-06-05 | PR 3 harden | `/harden-pr full` — plan retired; swap finally fix + API/config tests.        |
 | —          | PR 3 merge  | _fill · close orchestrator_                                                   |
 
 ---

docs/plans/security-hardening-orchestrator.md

@@ -108,7 +108,7 @@ Predicate-as-API only — enrich row shape and audit deltas; no standalone pass/
 - [ ] **`organize-imports` diff-shape recipe** — deterministic single-file import sort/group; `imports.line_number` + `source` substrate sufficient. Review-first (`auto_fixable: false`). Effort: S.
 - [ ] **`codemap-to-tsmorph` Path B adapter** — separate package experiment: `query_recipe` discovery → `ts-morph` / `jscodeshift` transforms for AST-shape edits codemap's substring executor defers (see [architecture § Rejected apply-path alternatives](./architecture.md#apply--input-modes-transport-and-policy)). Not an in-tree AST writer (Path A rejected). Effort: M.
 - [ ] **Apply write-safety hardening** — close apply TOCTOU: SHA-256 `hashContent` at phase-1 read, recheck disk hash immediately before phase-2 write (`file content changed` conflict); `fsync` temp file before `rename`; skip files with mixed CRLF/LF (`mixed line endings`). Preserves all-or-nothing on any conflict. Plan: [`plans/apply-write-safety.md`](./plans/apply-write-safety.md). Effort: L.
-- [ ] **Read-surface hardening (3 PRs)** — query/HTTP/validate safety, `impact` `inPath` homonyms, runtime guards + test teardown. **Orchestrator:** [`plans/security-hardening-orchestrator.md`](./plans/security-hardening-orchestrator.md). PR1 ([#180](https://github.com/stainless-code/codemap/pull/180), lifted to [architecture](./architecture.md)) · PR2 (`impact` homonyms, lifted to [architecture](./architecture.md)) · Plans: [PR3](./plans/runtime-test-isolation.md). Effort: S–M.
+- [ ] **Read-surface hardening (3 PRs)** — query/HTTP/validate safety, `impact` `inPath` homonyms, runtime guards + test teardown. **Orchestrator:** [`plans/security-hardening-orchestrator.md`](./plans/security-hardening-orchestrator.md). PR1 ([#180](https://github.com/stainless-code/codemap/pull/180), lifted to [architecture](./architecture.md)) · PR2 ([#181](https://github.com/stainless-code/codemap/pull/181), lifted to [architecture](./architecture.md)) · PR3 ([#182](https://github.com/stainless-code/codemap/pull/182), lifted to [architecture](./architecture.md)). Effort: S–M.
 - [ ] **`history` table** (deferred — revisit-triggered) — temporal queries: "when did symbol X get `@deprecated`?", "coverage trend over last 50 commits", "files that became dead this week". `audit --base <ref>` covers the most-common temporal question (PR-scoped diff) without schema growth, so the table earns its place only when bigger questions emerge. Two shapes (per-commit snapshots ~N × DB size; append-only event log heavier CTE walks); both pay an N-reindexes backfill cost (~30s per reindex). **Revisit triggers:** two consumers ship `jq`-based "audit-runs-over-time" workflows, OR `query_baselines` evolution becomes a recurring agent need.
 - [ ] **`codemap audit` verdict + thresholds** (v1.x) — `verdict: "pass" | "warn" | "fail"` driven by an `audit.deltas[<key>].{added_max, action}` field on the config object (`.codemap/config.{ts,js,json}`). Triggers: two consumers ship `jq`-based threshold scripts with similar shapes, OR one consumer asks with a concrete config sketch. Until then, raw deltas + consumer-side `jq` is the CI exit-code idiom. **Likely accelerant:** the Marketplace Action (next item) shipping is the most plausible path to firing the trigger — once `- uses: stainless-code/codemap@v1` is the dominant CI path, real `jq` threshold scripts will surface.
 - [ ] **GitHub Marketplace Action — publish + listing finish** — core Action implementation is in-tree: root `action.yml`, `query --ci`, `audit --format sarif` / `--ci`, package-manager detection, dogfood smoke, and opt-in `pr-comment` summary renderer have shipped. Remaining work is the release/listing slice: `MARKETPLACE.md`, `v1.0.0` / floating `v1` tags, Marketplace setup, sacrificial-repo smoke, and making `action-smoke` blocking once the Action tag exists. Action version stream is independent of CLI version (`package.json` currently drives CLI/npm version; Action publishes at its own `v1.0.0`). Plan: [`plans/github-marketplace-action.md`](./plans/github-marketplace-action.md). Effort: S.

docs/roadmap.md

@@ -16,4 +16,24 @@ describe("createCodemap", () => {
     const rows = cm.query("SELECT 1 as ok") as { ok: number }[];
     expect(rows[0]?.ok).toBe(1);
   });
+
+  test("throws when switching to a different root in the same process", async () => {
+    const rootA = mkdtempSync(join(tmpdir(), "codemap-api-a-"));
+    const rootB = mkdtempSync(join(tmpdir(), "codemap-api-b-"));
+    writeFileSync(join(rootA, "package.json"), "{}");
+    writeFileSync(join(rootB, "package.json"), "{}");
+    await createCodemap({ root: rootA });
+    await expect(createCodemap({ root: rootB })).rejects.toThrow(
+      /cannot switch project root/,
+    );
+  });
+
+  test("throws when config file is invalid at load", async () => {
+    const root = mkdtempSync(join(tmpdir(), "codemap-api-bad-"));
+    const configPath = join(root, "bad.json");
+    writeFileSync(configPath, JSON.stringify({ include: [1, 2] }));
+    await expect(
+      createCodemap({ root, configFile: configPath }),
+    ).rejects.toThrow(/include/);
+  });
 });

src/api.test.ts

@@ -47,7 +47,10 @@ export interface CodemapInitOptions {
  * @remarks
  * One project root per process: a second `createCodemap()` with a different `root` throws.
  * Re-initializing the same root is allowed. Audit `--base` worktree reindex is the only
- * production path that may temporarily switch roots (`runtime-swap.ts`).
+ * production path that may temporarily switch roots.
+ *
+ * Invalid project config (unknown keys, wrong types) throws at load time via the same
+ * schema as {@link parseCodemapUserConfig}.
  */
 export async function createCodemap(
   options: CodemapInitOptions = {},

src/api.ts

@@ -1,19 +1,31 @@
-import { describe, expect, it } from "bun:test";
+import { describe, expect, it, spyOn } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
+import { resolveCodemapConfig } from "../config";
 import { createTables, insertFile, upsertQueryBaseline } from "../db";
 import type { CodemapDatabase } from "../db";
 import { diffRows } from "../diff-rows";
+import { configureResolver } from "../resolver";
+import { getProjectRoot, initCodemap } from "../runtime";
 import { openCodemapDatabase } from "../sqlite-db";
+import { installCodemapTestTeardown } from "../test-helpers/runtime-reset";
 import {
   buildFindingKeySet,
   collapseAuditEnvelopeForSummary,
   computeDelta,
   findingKey,
+  makeWorktreeReindex,
   runAudit,
   tagAddedWithAttribution,
   V1_DELTAS,
 } from "./audit-engine";
 import type { AuditEnvelope } from "./audit-engine";
+import * as runIndex from "./run-index";
+import type { IndexResult } from "./types";
+
+installCodemapTestTeardown();
 
 function freshDb(): CodemapDatabase {
   const db = openCodemapDatabase(":memory:");
@@ -488,3 +500,34 @@ describe("computeDelta — files", () => {
     }
   });
 });
+
+describe("makeWorktreeReindex", () => {
+  it("swaps roots under runtime bracket and restores live config", async () => {
+    const liveRoot = mkdtempSync(join(tmpdir(), "audit-reindex-live-"));
+    const wtRoot = mkdtempSync(join(tmpdir(), "audit-reindex-wt-"));
+    writeFileSync(join(liveRoot, "package.json"), "{}");
+    writeFileSync(join(wtRoot, "package.json"), "{}");
+    mkdirSync(join(wtRoot, ".codemap"), { recursive: true });
+
+    initCodemap(resolveCodemapConfig(liveRoot, {}));
+    configureResolver(liveRoot, null);
+
+    const spy = spyOn(runIndex, "runCodemapIndex").mockResolvedValue({
+      mode: "full",
+      indexed: 0,
+      skipped: 0,
+      elapsedMs: 0,
+      stats: { files: 0 },
+    } as IndexResult);
+    try {
+      await makeWorktreeReindex()(wtRoot);
+      expect(getProjectRoot()).toBe(liveRoot);
+      expect(() =>
+        initCodemap(resolveCodemapConfig("/other-root", {})),
+      ).toThrow(/cannot switch project root/);
+      expect(spy).toHaveBeenCalled();
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});

src/application/audit-engine.test.ts

@@ -459,15 +459,18 @@ export function makeWorktreeReindex(): ReindexFn {
       let wtDb;
       enterRuntimeSwap();
       try {
-        const wtUser = await loadUserConfig(worktreePath, undefined);
-        initCodemap(resolveCodemapConfig(worktreePath, wtUser));
-        configureResolver(getProjectRoot(), getTsconfigPath());
-        wtDb = openCodemapDatabase();
-        await runCodemapIndex(wtDb, { mode: "full", quiet: true, commit });
+        try {
+          const wtUser = await loadUserConfig(worktreePath, undefined);
+          initCodemap(resolveCodemapConfig(worktreePath, wtUser));
+          configureResolver(getProjectRoot(), getTsconfigPath());
+          wtDb = openCodemapDatabase();
+          await runCodemapIndex(wtDb, { mode: "full", quiet: true, commit });
+        } finally {
+          wtDb?.close();
+          initCodemap(savedConfig);
+          configureResolver(getProjectRoot(), getTsconfigPath());
+        }
       } finally {
-        wtDb?.close();
-        initCodemap(savedConfig);
-        configureResolver(getProjectRoot(), getTsconfigPath());
         exitRuntimeSwap();
       }
     });

src/application/audit-engine.ts

@@ -15,3 +15,8 @@ export function exitRuntimeSwap(): void {
 export function isRuntimeSwapActive(): boolean {
   return _runtimeSwapDepth > 0;
 }
+
+/** Maintainer test helper — clears swap depth between test cases. */
+export function resetRuntimeSwapForTest(): void {
+  _runtimeSwapDepth = 0;
+}