@klhapp/skillmux 1.11.2 → 1.13.0

package/docs/sdd/config-authority-rerank-resilience/spec.md

@@ -0,0 +1,78 @@
+# Specification: Configuration Authority and Rerank Resilience
+
+Feature Slug: `config-authority-rerank-resilience`
+Plan: [plan.md](file:///Users/lancehsu/Code/skillmux/docs/sdd/config-authority-rerank-resilience/plan.md)
+Status: Draft
+
+## Overview
+
+Give Skillmux a predictable OSS configuration contract, bound reranker work via `k_rerank`, introduce `output.ambiguous_candidate_limit` with 1.x deprecation for `thresholds.candidate_limit`, and expose structured inference fallback reasons and evaluation details.
+
+## User Stories & Acceptance Criteria
+
+### Change 1: Configuration Authority (AC 1-5, 13, 17)
+
+- **AC 1.1 (Precedence & Policy)**: When `config.environment_overrides = true` (default), configuration precedence is:
+  1. CLI flags
+  2. `SKILLMUX_*` environment variables
+  3. TOML configuration file
+  4. Built-in defaults
+- **AC 1.2 (Strict TOML Mode)**: When `config.environment_overrides = false`, behavioral `SKILLMUX_*` environment variables (e.g. `SKILLMUX_EMBED_MODEL`, `SKILLMUX_HOST`, etc.) are ignored. TOML configuration is authoritative.
+- **AC 1.3 (Exempt Variables in Strict Mode)**: In both `true` and `false` modes, Skillmux MUST continue to resolve:
+  - `SKILLMUX_CONFIG` (config path locator)
+  - `SKILLMUX_CONFIG_READONLY` (admin API read-only enforcement)
+  - Secret variables referenced by `api_key_env`
+  - Process environment variables (`HOME`, `PATH`, etc.)
+  - Explicit CLI flags
+- **AC 1.4 (Generic Env & Deprecated Keys)**: Generic environment variables (`EMBED_*`, `RERANK_*`, etc.) and deprecated `thresholds.candidate_limit` trigger a 1.x deprecation warning pointing to `SKILLMUX_*` and `output.ambiguous_candidate_limit` equivalents.
+- **AC 1.5 (Provenance & Diagnostics)**: `config show --sources` and `doctor` report `config.environment_overrides` status and source provenance for each behavioral value.
+- **AC 1.6 (Output Candidate Limit)**: `output.ambiguous_candidate_limit` controls candidate limits returned on ambiguous outcomes. `thresholds.candidate_limit` remains as a deprecated 1.x alias.
+
+### Change 2: Bounded Reranking (AC 6-8)
+
+- **AC 2.1 (Schema & Validation)**: Add `recall.k_rerank` to TOML config and schema. Validate:
+  - `k_lexical`, `k_vector`, and `k_rerank` are positive integers.
+  - `k_rerank <= k_lexical + k_vector`.
+  - Default provides a safe fallback for existing installations without breaking.
+- **AC 2.2 (Runtime Fusion & Truncation)**: In `retrieveAndRerank`, retrieve lexical (up to `k_lexical`) and vector (up to `k_vector`), fuse candidates, truncate the fused list to `k_rerank`, and only send `k_rerank` candidates to the reranker.
+- **AC 2.3 (Calibration & Evaluation Alignment)**: Dataset generation, calibration tuning, and evaluation record and use the configured `k_rerank`, `k_lexical`, and `k_vector` settings matching runtime.
+
+### Change 3: Failure Visibility & Degradation Reasons (AC 9-12)
+
+- **AC 3.1 (Error Classification & Stable Codes)**: Remote inference errors, timeouts, and transport failures map to stable reason codes:
+  - `embedding_timeout`
+  - `embedding_unavailable`
+  - `embedding_protocol_error`
+  - `reranker_timeout`
+  - `reranker_unavailable`
+  - `reranker_protocol_error`
+- **AC 3.2 (Safe Fallback & Metadata)**: When fallback occurs:
+  - Embedding failure falls back to lexical retrieval with degradation metadata (`degraded_from = "reranked"` or `"hybrid"`, `degradation_reason = "<code_name>"`).
+  - Reranker failure falls back to fused hybrid candidates with `degraded_from = "reranked"` and reason.
+- **AC 3.3 (MCP & Safe Sanitization)**: MCP `resolve_skill` responses return structured degradation fields. Audit records, logs, and Prometheus metrics log/increment safe error classes without exposing credentials, URLs with secrets, or raw exception bodies.
+
+### Change 4: Routing Evidence Gate & Evaluation Details (AC 15)
+
+- **AC 4.1 (Evaluation Case Output)**: `evalVault` records each evaluation case's fused rank, reranked rank, final outcome, latency, effective recall/rerank settings, and degradation state.
+
+## Implementation Tasks
+
+- [x] **Task 1: Configuration Schema, Loader, and Provenance**
+  - Add `config.environment_overrides` boolean option (defaults to `true`).
+  - Add `output.ambiguous_candidate_limit` and 1.x deprecation warning for `thresholds.candidate_limit`.
+  - Add migration deprecation warnings for generic `EMBED_*` / `RERANK_*` env vars.
+  - Enforce `environment_overrides = false` behavior ignoring behavioral env vars while preserving `SKILLMUX_CONFIG`, `api_key_env`, etc.
+  - Update `config show --sources` and `doctor` provenance tracking.
+- [x] **Task 2: Bounded Reranking (`k_rerank`)**
+  - Add `recall.k_rerank` to config types, schema, defaults, and validation.
+  - Update `retrieveAndRerank` pipeline to truncate fused candidates to `k_rerank` before reranking.
+  - Align calibration and dataset generator with `k_rerank`.
+- [x] **Task 3: Failure Classification and Degradation Metadata**
+  - Define stable error reason enums/types.
+  - Classify `RemoteInferenceError`, timeouts, and transport errors in embedding and reranker callers.
+  - Add degradation metadata to MCP responses, structured logs, audit logger, and metric counters.
+  - Verify secret redaction and error masking in audit/logs.
+- [ ] **Task 4: Output Limits, Calibration Settings & Evaluation Reporting**
+  - Support `output.ambiguous_candidate_limit` with 1.x deprecation warning on `thresholds.candidate_limit`.
+  - Update `evalVault` to record candidate fused/reranked ranks, latency, recall settings, and degradation state.
+  - Record recall settings in calibration runs.

package/docs/sdd/feat-packaging-deployment/review.md

@@ -0,0 +1,95 @@
+# Packaging and deployment review
+
+- **Branch:** `feat/packaging-deployment`
+- **Reviewed range:** `main...1d940ca`
+- **Specification:** `docs/skillmux-packaging-deployment-plan.md`
+- **Verdict:** approved pending CI
+- **Reverification:** all review findings resolved by `1d940ca`
+
+## Findings
+
+### Resolved — The default Docker server exited before listening
+
+`ConfigWatcher` now tolerates a missing parent directory. A rebuilt slim image
+started the default HTTP server without a config directory, reached healthy
+state, and exited with status 0 after SIGTERM. Containerized stdio also started
+and closed with status 0.
+
+The original runtime failure was:
+
+```text
+error: ENOENT: no such file or directory, watch '/root/.config/skillmux'
+```
+
+**Resolution:** verified by focused unit coverage and a rebuilt-image runtime
+smoke test.
+
+### Resolved — Docker runtime validation
+
+CI now builds and loads the AMD64 slim image, then runs
+`tests/docker-smoke.sh`. The script covers command replacement, rejected host
+management, stdio, default HTTP readiness, and SIGTERM.
+
+The release workflow now runs the same smoke contract for full and slim images
+on AMD64 and ARM64 before the GHCR publishing job can start.
+
+**Location:** `.github/workflows/release-please.yml:238`
+
+**Resolution:** the four-way release matrix uses QEMU and blocks image
+publication on smoke-test success.
+
+### Resolved — Public terminology
+
+The documentation hub and architecture diagram now use the CLI-first
+hierarchy. Concepts, deployment, routing, configuration, and most
+troubleshooting references were also updated.
+
+The remaining getting-started, troubleshooting, example-config, and issue
+template references now use “Skillmux CLI” and “standalone Linux executable.”
+A repository terminology scan finds the old labels only in historical plan and
+review text.
+
+### Resolved — Live configuration after zero-config startup
+
+`ConfigWatcher` creates the config parent before installing the watcher. A
+later config creation therefore triggers the normal reload path.
+
+**Locations:** `src/config-watcher.ts:139`, `src/config-service.ts:317`
+
+**Resolution:** unit coverage creates a config after zero-config startup. A
+Linux-container runtime check also confirmed that a late-created malformed
+config reached the watcher and produced the expected reload error without
+stopping the server.
+
+## Validation
+
+- `bunx tsc --noEmit`: pass
+- Changed Docker-policy tests: 5 passed, 0 failed
+- Missing-directory ConfigWatcher regression: 1 passed, 0 failed
+- Late-created config watcher test: times out in this macOS environment with
+  the existing `node:fs.watch` tests; Linux-container runtime verification
+  passed
+- Slim Docker build: pass
+- `docker run ... config show`: pass
+- `docker run ... init`: correctly rejected with exit code 2 and host guidance
+- Default Docker HTTP startup: pass; container reached healthy state
+- Containerized stdio: pass
+- SIGTERM shutdown: pass; exit code 0
+- `bash -n tests/docker-smoke.sh`: pass
+- Full `bun test`: fail in this environment with 37 failures, largely from
+  port-0 server startup, filesystem watcher timeouts, and Git fixture behavior
+  outside this diff. Focused changed tests pass, but the branch
+  cannot be called suite-green from this run.
+
+## AC Status
+
+| Criterion | Status | Notes |
+| --- | --- | --- |
+| Present Skillmux as CLI-first for individual management and local MCP | ✅ Done | README, documentation hub, concepts, and architecture diagram use the CLI-first hierarchy |
+| Treat the Bun package and standalone Linux executable as installations of one CLI | ✅ Done | Public terminology now follows the CLI/server hierarchy |
+| Preserve zero-argument Docker HTTP startup | ✅ Done | Rebuilt slim image reached healthy state without a config directory |
+| Support documented one-shot and stdio Docker overrides | ✅ Done | Runtime verification covered command replacement and stdio |
+| Reject host-management commands inside Docker | ✅ Done | Guard and focused tests cover the documented command families |
+| Recommend full by default and slim for remote or lexical retrieval | ✅ Done | Root README and getting-started guide establish the intended default |
+| Document Git-backed vault copies for combined native and shared retrieval | ✅ Done | Getting-started and deployment guides state that replication is external |
+| Add runtime Docker and release-architecture validation | ✅ Done | PR CI smokes slim AMD64; release publishing waits for full/slim AMD64/ARM64 smoke jobs |

package/docs/sdd/fetch-outcome-flywheel/review.md

@@ -0,0 +1,103 @@
+# Review — fetch-outcome routing quality flywheel
+
+Reviewed: `git diff main...HEAD` on `feat/fetch-outcome-flywheel` (26 files, +2243/-302 across 12 feature commits + 1 docs commit + 1 review-fix commit).
+
+Goose's `sdd-review` fan-out hit the day's Bifrost token rate limit before any sub-pass returned results, so this review was run manually per the skill's fallback path (five focus passes + build check + test execution, done inline).
+
+## Compliance
+
+| # | Criterion (abridged) | Status |
+|---|---|---|
+| 1 | `audit.sqlite3` separate from `index.sqlite3`, WAL + `auto_vacuum=INCREMENTAL` at creation | ✅ Done |
+| 2 | Idempotent one-time transactional migration of legacy audit rows | ✅ Done — tested including a second-open idempotency check |
+| 3 | `resolve_skill` response carries unique `request_id`, stored on the audit row | ✅ Done |
+| 4 | Pre-existing audit rows with no `request_id` still load/report/render | ✅ Done |
+| 5 | `fetch_skill` optional `request_id` correlates to the resolve when known | ✅ Done |
+| 6 | `fetch_skill` without `request_id` records an uncorrelated fetch | ✅ Done |
+| 7 | Unknown/malformed `request_id` still succeeds, records uncorrelated | ✅ Done |
+| 8 | Fetch row stores ts, skill_id, request_id/null, resolve id/null, rank_at_resolve | ✅ Done |
+| 9 | `report` computes acceptance_rate / observed_mrr / top1_acceptance_rate | ✅ Done |
+| 10 | Signal marked unavailable (not `0.000`) when no correlated fetches | ✅ Done |
+| 11 | `top_unused_shortlist_queries` distinct from `top_empty_shortlist_queries` | ✅ Done |
+| 12 | `audit.retention_days`, default 90, `0` disables, invalid rejected at load | ✅ Done |
+| 13 | Prune deletes resolve/fetch independently by own timestamp; pruned resolve reads as uncorrelated | ✅ Done |
+| 14 | Prune runs at startup + ≤ once/24h, never blocks readiness/resolve | ✅ Done (race fixed during this review — see Findings) |
+| 15 | `skillmux audit prune` with `--older-than`/`--dry-run`/`--yes`/`--json` | ✅ Done |
+| 16 | Incremental vacuum after prune; never locks `index.sqlite3` | ✅ Done — structural (separate files/connections) |
+| 17 | `skillmux eval promote` writes `{query, split:"observed", relevant_skill_ids}`, deduped by normalized query, default target ≠ `eval/queries.json`, warns about raw queries | ✅ Done |
+| 18 | `eval promote` never rewrites an existing case; skipped count reported | ✅ Done |
+| 19 | `report`/`audit prune`/`eval promote` honor `--json`; exit codes unchanged | ✅ Done |
+
+**Spec compliance: 19/19.** **Schema compliance:** all types in `docs/sdd/fetch-outcome-flywheel/schema.json` match the implementation; `docs/schema.json` (the committed wire contract) was updated for `request_id` on both tools and `AuditConfig`, consistent with the project's existing precedent of not documenting CLI JSON output shapes there (matches `StatsResponse`'s prior absence).
+
+## Findings
+
+### 1. [Fixed] `getEnv()` race: two concurrent callers at startup each opened their own DB handles
+**File:** `src/router-core.ts` (pre-fix) · **Confidence:** High · **Class:** AUTO-FIX (applied)
+
+`startServer()` calls `initializeRuntime(readinessState)` (which awaits `getRuntime()` → `getEnv()`) and then, synchronously right after, fires the new AC14 `pruneAuditIfDue()` (which also calls `getEnv()`) — fire-and-forget, per AC14's "never blocks readiness" requirement. `getEnv()`'s memoization was `if (env) return env;` with `env` assigned only after several `await` points. Because both call chains reach that guard *before either has awaited anything* (JS runs an async function body synchronously up to its first `await`), both saw `env === null` and independently ran `openIndex()` + `openAudit()` (and, on a cold index, could both run `ingestVault()` concurrently). One of the two resulting handles is orphaned — never closed by `closeRuntime()`, since that only closes whatever `env` last got overwritten to — leaking a `Database` connection on every server startup, not just occasionally.
+
+Reproduced with a regression test (`tests/guarantees.test.ts`, "concurrent callers racing at startup share one env..."), confirmed genuinely RED (`a.db !== b.db`), then fixed by memoizing the in-flight `Promise` instead of the resolved value, with a `resolvedEnv` side-reference so `closeRuntime()` keeps its existing synchronous best-effort close. Commit `91dfd7e`. Full suite: 666/666 pass after the fix (up from 665, +1 for the new regression test).
+
+### 2. [Not a defect] SQL built via template-literal interpolation in `adoptAuditFromIndex`
+**File:** `src/db.ts` — `adoptAuditFromIndex` · **Confidence:** N/A (verified safe) · **Class:** none
+
+`retrieval`/`degradedFrom`/`degradationReason` are interpolated into the migration `INSERT ... SELECT`. Checked for injection: all three are selected via ternary from a fixed 2-way enum of literal strings (`"COALESCE(retrieval, 'lexical')"` / `"'lexical'"`, etc.) keyed off `legacyColumns.has(...)` — never derived from row data or user input. Same pattern as the pre-existing in-place migration this replaced. No finding.
+
+### 3. [Nitpick] No index on `audit.ts` / `fetch.ts` / `fetch.resolve_audit_id`
+**Files:** `src/db.ts` (`openAudit`) · **Confidence:** Low · **Class:** NITPICK
+
+`queryAuditRows`, `queryFetchRows`, `pruneAuditBefore`/`countPrunable`, and the new `queryPromotableFetches` join all filter or join on these columns without an index, so they full-scan at scale. This predates the feature (the original `audit` table had no `ts` index either) and performance tuning is out of scope per the spec. Mentioning for awareness, not blocking.
+
+## Security
+
+No injection, auth, secrets, or trust-boundary issues found. All new SQL uses parameterized `?` bindings except the one interpolation site above, which was verified safe. `eval promote --target <path>` and `audit prune`/`report --db <path>` accept arbitrary local paths, but these are operator-supplied CLI flags on a tool the operator already has filesystem access to — not a privilege boundary. `request_id` inputs are deliberately unvalidated at the schema level (by design, per AC7 — an unknown/malformed value must still succeed) and are only ever used as a parameterized lookup key, never interpolated or executed. Security escalation via `/security-review` not recommended — no auth/session/payment/deserialization/new-egress surface touched.
+
+## Performance
+
+No regressions. The one Low-confidence nitpick (missing indexes) is pre-existing scope, not introduced here. Pruning's incremental-vacuum runs unconditionally after every prune call (including no-op ones); cheap and harmless.
+
+## Tests
+
+**Build check:** PASS ✅ (`bun run tsc --noEmit`, clean)
+**Test execution:** PASS ✅ (666/666, 1750 `expect()` calls, 53 files — up from 629 at the start of this SDD session)
+
+Coverage is thorough: every AC has at least one test locking it in, including edge cases (pruned-resolve-reads-as-uncorrelated, retention_days=0 disabling pruning, dedupe-by-normalized-query, skip-existing-case-in-target-file, the 24h prune gate, and now the startup concurrency race). No gaps found worth a new test beyond the one added for Finding 1.
+
+## Review Summary
+
+**Spec compliance:** 19/19 criteria met
+**Schema compliance:** All types match
+**Critical findings:** 1 (1 high confidence, fixed)
+**Auto-fixed:** 1 issue (the `getEnv()` race)
+**Needs decision:** 0
+**Test coverage (static):** Adequate
+**Build check:** PASS ✅
+**Test execution (runtime):** PASS ✅ (666/666)
+**AC status table:** Written above
+**Security escalation:** Not needed
+**Learnings retained:** 1 memory (Hindsight `infra` bank) — the async-memoization gotcha, for reuse if this codebase (or another) adds more fire-and-forget background work off a lazily-initialized singleton.
+
+## AC Status
+
+| Criterion | Status | Notes |
+|---|---|---|
+| AC1: audit.sqlite3 separate store, WAL + incremental auto_vacuum | ✅ Done | |
+| AC2: idempotent transactional migration from index.sqlite3 | ✅ Done | Idempotency explicitly tested (second open) |
+| AC3: request_id on resolve_skill response + audit row | ✅ Done | |
+| AC4: pre-existing rows without request_id still work | ✅ Done | |
+| AC5: fetch_skill request_id correlates to known resolve | ✅ Done | |
+| AC6: fetch_skill without request_id records uncorrelated | ✅ Done | |
+| AC7: unknown/malformed request_id still succeeds, uncorrelated | ✅ Done | |
+| AC8: fetch row shape (ts, skill_id, request_id, resolve id, rank) | ✅ Done | |
+| AC9: acceptance_rate / observed_mrr / top1_acceptance_rate | ✅ Done | |
+| AC10: signal marked unavailable, not 0.000, when no correlated fetches | ✅ Done | |
+| AC11: top_unused_shortlist_queries distinct list | ✅ Done | |
+| AC12: audit.retention_days, default 90, 0 disables, invalid rejected | ✅ Done | |
+| AC13: prune deletes independently by timestamp; pruned resolve → uncorrelated | ✅ Done | |
+| AC14: prune at startup + ≤1/24h, never blocks readiness/resolve | ✅ Done | Startup race found and fixed during this review |
+| AC15: `skillmux audit prune` flags | ✅ Done | |
+| AC16: incremental vacuum, never locks index.sqlite3 | ✅ Done | |
+| AC17: `skillmux eval promote` case shape, dedupe, default target, warning | ✅ Done | |
+| AC18: never rewrites existing case | ✅ Done | |
+| AC19: `--json` honored, exit codes unchanged | ✅ Done | |

package/docs/sdd/fetch-outcome-flywheel/schema.json

@@ -0,0 +1,347 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://klh.app/schemas/skillmux/fetch-outcome-flywheel.json",
+  "title": "Skillmux — fetch-outcome routing quality flywheel contract",
+  "description": "Contract delta for docs/sdd/fetch-outcome-flywheel/spec.md. Each $def is either a NEW type or a full replacement for a def of the same name in docs/schema.json. At implementation time these merge into docs/schema.json $defs; nothing here is a second source of truth. Merge targets are noted per def in $comment.",
+  "$defs": {
+    "RequestId": {
+      "$comment": "NEW. AC3.",
+      "type": "string",
+      "description": "Per-resolve correlation id minted by resolve_skill. Lowercase UUIDv4.",
+      "format": "uuid",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+
+    "InboundRequestId": {
+      "$comment": "NEW. AC7. Deliberately NOT pattern-validated: AC7 requires that an unknown OR MALFORMED request_id still succeed and record an uncorrelated fetch. Pattern-validating this at the tool boundary would raise a validation error before the handler runs and break AC7. Correlation validity is decided in the handler. The length bound is the single boundary check, present only to cap an unbounded string.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+
+    "Window": {
+      "$comment": "NEW. AC15, AC17. Mirrors SINCE_PATTERN at src/stats.ts:4 exactly.",
+      "type": "string",
+      "description": "Relative window (30d, 12h, 2w, 6m, 1y) or an absolute date/datetime (YYYY-MM-DD, optionally with time).",
+      "pattern": "^(\\d+[hdwmy]|\\d{4}-\\d{2}-\\d{2}([T ].+)?)$"
+    },
+
+    "ResolveSkillResult": {
+      "$comment": "REPLACES docs/schema.json #/$defs/ResolveSkillResult. AC3: request_id added to properties AND to required, since the server always mints one.",
+      "type": "object",
+      "description": "Ranked candidates response from resolve_skill.",
+      "properties": {
+        "request_id": { "$ref": "#/$defs/RequestId" },
+        "retrieval": { "enum": ["exact", "reranked", "hybrid", "lexical"] },
+        "degraded_from": { "enum": ["reranked", "hybrid"] },
+        "degradation_reason": { "$ref": "https://klh.app/schemas/skillmux/router-core.json#/$defs/DegradationReason" },
+        "candidates": {
+          "type": "array",
+          "items": { "$ref": "https://klh.app/schemas/skillmux/router-core.json#/$defs/RankedCandidate" },
+          "description": "Shortlist of candidates in descending score order with contiguous 1-based ranks."
+        }
+      },
+      "required": ["request_id", "retrieval", "candidates"],
+      "additionalProperties": false
+    },
+
+    "FetchSkillInput": {
+      "$comment": "REPLACES docs/schema.json #/$defs/FetchSkillInput. AC5, AC6, AC7: request_id is optional and stays absent from required, preserving the documented guarantee that fetch works with no prior resolve.",
+      "type": "object",
+      "properties": {
+        "skill_id": { "$ref": "https://klh.app/schemas/skillmux/router-core.json#/$defs/SkillId" },
+        "request_id": { "$ref": "#/$defs/InboundRequestId" }
+      },
+      "required": ["skill_id"],
+      "additionalProperties": false
+    },
+
+    "ResolveAuditRow": {
+      "$comment": "NEW. AC3, AC4. Persisted shape in audit.sqlite3. request_id is nullable so rows migrated from index.sqlite3 (AC2) and rows written before this feature still load.",
+      "type": "object",
+      "properties": {
+        "id": { "type": "integer", "minimum": 1 },
+        "ts": { "type": "string", "format": "date-time" },
+        "request_id": {
+          "oneOf": [{ "$ref": "#/$defs/RequestId" }, { "type": "null" }],
+          "description": "Null only for rows written before this feature."
+        },
+        "query": { "type": "string", "minLength": 1 },
+        "retrieval": { "enum": ["exact", "reranked", "hybrid", "lexical"] },
+        "degraded_from": { "oneOf": [{ "enum": ["reranked", "hybrid"] }, { "type": "null" }] },
+        "degradation_reason": {
+          "oneOf": [
+            { "$ref": "https://klh.app/schemas/skillmux/router-core.json#/$defs/DegradationReason" },
+            { "type": "null" }
+          ]
+        },
+        "candidates": {
+          "type": "array",
+          "items": { "$ref": "https://klh.app/schemas/skillmux/router-core.json#/$defs/RankedCandidate" }
+        },
+        "latency_ms": { "type": "integer", "minimum": 0 }
+      },
+      "required": ["id", "ts", "request_id", "query", "retrieval", "candidates", "latency_ms"],
+      "additionalProperties": false
+    },
+
+    "FetchAuditRow": {
+      "$comment": "NEW. AC8, AC13. Persisted shape in audit.sqlite3.",
+      "type": "object",
+      "properties": {
+        "id": { "type": "integer", "minimum": 1 },
+        "ts": { "type": "string", "format": "date-time" },
+        "skill_id": { "$ref": "https://klh.app/schemas/skillmux/router-core.json#/$defs/SkillId" },
+        "request_id": {
+          "oneOf": [{ "$ref": "#/$defs/InboundRequestId" }, { "type": "null" }],
+          "description": "Exactly as supplied by the caller, including a value that matched no resolve. Null when the caller sent none."
+        },
+        "resolve_audit_id": {
+          "oneOf": [{ "type": "integer", "minimum": 1 }, { "type": "null" }],
+          "description": "Null when the fetch is uncorrelated: no request_id sent, an unknown or malformed one sent (AC7), or the resolve row has since been pruned (AC13)."
+        },
+        "rank_at_resolve": {
+          "oneOf": [{ "type": "integer", "minimum": 1 }, { "type": "null" }],
+          "description": "Rank of skill_id in that resolve's shortlist. Null when the fetch is uncorrelated, or when correlated but the skill was absent from the shortlist."
+        }
+      },
+      "required": ["id", "ts", "skill_id", "request_id", "resolve_audit_id", "rank_at_resolve"],
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "$comment": "AC8 invariant: a rank can only exist relative to a known resolve. An uncorrelated fetch therefore has no rank.",
+          "if": {
+            "properties": { "resolve_audit_id": { "type": "null" } },
+            "required": ["resolve_audit_id"]
+          },
+          "then": {
+            "properties": { "rank_at_resolve": { "type": "null" } }
+          }
+        }
+      ]
+    },
+
+    "AcceptanceSignal": {
+      "$comment": "NEW. AC9, AC10. Modelled as a discriminated union on `available` so that the unavailable case CANNOT carry a rate. This makes AC10 a type error rather than a formatting convention: there is no shape in which a window with no correlated fetches emits acceptance_rate 0.0.",
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "available": { "const": false },
+            "uncorrelated_fetch_count": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Fetches seen in the window that could not be tied to a resolve. A non-zero value here with available=false is the signature of a client that never sends request_id."
+            }
+          },
+          "required": ["available", "uncorrelated_fetch_count"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "available": { "const": true },
+            "resolves_with_candidates": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Denominator: resolves in the window that returned at least one candidate."
+            },
+            "accepted_count": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Resolves with at least one correlated fetch."
+            },
+            "acceptance_rate": { "type": "number", "minimum": 0, "maximum": 1 },
+            "observed_mrr": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Mean reciprocal rank of the first fetched candidate, over accepted resolves."
+            },
+            "top1_acceptance_rate": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Share of accepted resolves whose rank-1 candidate was the one fetched."
+            },
+            "uncorrelated_fetch_count": { "type": "integer", "minimum": 0 }
+          },
+          "required": [
+            "available",
+            "resolves_with_candidates",
+            "accepted_count",
+            "acceptance_rate",
+            "observed_mrr",
+            "top1_acceptance_rate",
+            "uncorrelated_fetch_count"
+          ],
+          "additionalProperties": false
+        }
+      ]
+    },
+
+    "QueryCount": {
+      "$comment": "NEW. Shared by both query lists. Mirrors EmptyShortlistQuery at src/stats.ts:11.",
+      "type": "object",
+      "properties": {
+        "query": { "type": "string", "minLength": 1 },
+        "count": { "type": "integer", "minimum": 1 }
+      },
+      "required": ["query", "count"],
+      "additionalProperties": false
+    },
+
+    "ReportOutput": {
+      "$comment": "NEW to docs/schema.json, but existing fields transcribe StatsResponse at src/stats.ts:23 unchanged. AC9, AC10, AC11, AC19.",
+      "type": "object",
+      "description": "JSON output of `skillmux report --json`.",
+      "properties": {
+        "since": { "type": "string", "format": "date-time" },
+        "until": { "type": "string", "format": "date-time" },
+        "total_requests": { "type": "integer", "minimum": 0 },
+        "empty_shortlist_count": { "type": "integer", "minimum": 0 },
+        "empty_shortlist_rate": { "type": "number", "minimum": 0, "maximum": 1 },
+        "retrieval_totals": {
+          "type": "object",
+          "properties": {
+            "exact": { "type": "integer", "minimum": 0 },
+            "reranked": { "type": "integer", "minimum": 0 },
+            "hybrid": { "type": "integer", "minimum": 0 },
+            "lexical": { "type": "integer", "minimum": 0 }
+          },
+          "required": ["exact", "reranked", "hybrid", "lexical"],
+          "additionalProperties": false
+        },
+        "degraded_count": { "type": "integer", "minimum": 0 },
+        "average_latency_ms": { "type": "number", "minimum": 0 },
+        "skills": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "skill_id": { "$ref": "https://klh.app/schemas/skillmux/router-core.json#/$defs/SkillId" },
+              "candidate_count": { "type": "integer", "minimum": 0 }
+            },
+            "required": ["skill_id", "candidate_count"],
+            "additionalProperties": false
+          }
+        },
+        "top_empty_shortlist_queries": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/QueryCount" }
+        },
+        "acceptance": { "$ref": "#/$defs/AcceptanceSignal" },
+        "top_unused_shortlist_queries": {
+          "type": "array",
+          "description": "AC11: queries that DID return candidates and received no correlated fetch. Distinct from top_empty_shortlist_queries, which covers queries that returned nothing at all.",
+          "items": { "$ref": "#/$defs/QueryCount" }
+        }
+      },
+      "required": [
+        "since",
+        "until",
+        "total_requests",
+        "empty_shortlist_count",
+        "empty_shortlist_rate",
+        "retrieval_totals",
+        "degraded_count",
+        "average_latency_ms",
+        "skills",
+        "top_empty_shortlist_queries",
+        "acceptance",
+        "top_unused_shortlist_queries"
+      ],
+      "additionalProperties": false
+    },
+
+    "PruneOutput": {
+      "$comment": "NEW. AC15, AC19.",
+      "type": "object",
+      "description": "JSON output of `skillmux audit prune --json`.",
+      "properties": {
+        "dry_run": { "type": "boolean" },
+        "older_than": { "$ref": "#/$defs/Window" },
+        "cutoff": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Resolved absolute cutoff. Rows at or before this instant are removed."
+        },
+        "removed": {
+          "type": "object",
+          "description": "AC15: rows removed per table. Both counts are what WOULD be removed when dry_run is true.",
+          "properties": {
+            "resolves": { "type": "integer", "minimum": 0 },
+            "fetches": { "type": "integer", "minimum": 0 }
+          },
+          "required": ["resolves", "fetches"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["dry_run", "older_than", "cutoff", "removed"],
+      "additionalProperties": false
+    },
+
+    "PromotedEvalCase": {
+      "$comment": "NEW. AC17. Must validate under parseEvalCases at src/eval.ts:15, hence relevant_skill_ids is a unique array of SkillId.",
+      "type": "object",
+      "properties": {
+        "query": { "type": "string", "minLength": 1 },
+        "split": {
+          "const": "observed",
+          "description": "Fixed value keeps promoted cases out of the hand-curated tune and test splits."
+        },
+        "relevant_skill_ids": {
+          "type": "array",
+          "items": { "$ref": "https://klh.app/schemas/skillmux/router-core.json#/$defs/SkillId" },
+          "uniqueItems": true,
+          "minItems": 1,
+          "description": "Skills actually fetched for this query. A promoted case always has at least one, otherwise there was no outcome to promote."
+        }
+      },
+      "required": ["query", "split", "relevant_skill_ids"],
+      "additionalProperties": false
+    },
+
+    "PromoteOutput": {
+      "$comment": "NEW. AC17, AC18, AC19.",
+      "type": "object",
+      "description": "JSON output of `skillmux eval promote --json`.",
+      "properties": {
+        "dry_run": { "type": "boolean" },
+        "since": { "$ref": "#/$defs/Window" },
+        "target_path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "AC17: defaults to a path other than eval/queries.json unless one is given explicitly."
+        },
+        "promoted": { "type": "integer", "minimum": 0 },
+        "skipped_existing": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "AC18: queries already present in the target file, skipped rather than rewritten."
+        }
+      },
+      "required": ["dry_run", "since", "target_path", "promoted", "skipped_existing"],
+      "additionalProperties": false
+    },
+
+    "AuditConfig": {
+      "$comment": "NEW. AC12. Merges into docs/schema.json #/$defs/Config properties as `audit`. NOT added to Config.required: the section is optional and defaults apply when absent, matching how `server` is handled.",
+      "type": "object",
+      "properties": {
+        "retention_days": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 90,
+          "description": "Age in days beyond which audit rows are pruned. 0 disables pruning and retains rows indefinitely. OPEN DECISION: whether the shipped default is 90 or 0. The type is identical either way; only the default value differs."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "ConfigStateDirDescription": {
+      "$comment": "REPLACES the description string on docs/schema.json #/$defs/Config/properties/state_dir, which currently reads 'index SQLite (incl. audit log)'. That parenthetical is false once the audit store splits out (AC1).",
+      "const": "All router writes are confined here (AC9): index SQLite (index.sqlite3), audit SQLite (audit.sqlite3), vector matrix."
+    }
+  }
+}