kernel-lore-mcp 0.2.2__tar.gz → 0.3.0__tar.gz

{kernel_lore_mcp-0.2.2 → kernel_lore_mcp-0.3.0}/.github/workflows/ci.yml

@@ -51,6 +51,24 @@ jobs:
       - run: uv run maturin develop --release
       - run: uv run pytest -v
 
+  hosted-load:
+    name: hosted load harness
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: uv sync
+      - run: uv run maturin develop --release
+      - run: .venv/bin/python scripts/bench/bench_hosted_adversarial.py --json-out hosted-load.json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: hosted-load-report
+          path: hosted-load.json
+
   wheels:
     name: build abi3 wheels (${{ matrix.target }})
     runs-on: ${{ matrix.os }}

{kernel_lore_mcp-0.2.2 → kernel_lore_mcp-0.3.0}/CHANGELOG.md

@@ -10,6 +10,57 @@ release tags move them into a dated section. Release process in
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-04-21
+
+### Added
+
+**Hosted deployment profile + operator profiling.**
+- `kernel-lore-mcp serve` now accepts `--mode local|hosted`, and the
+  chosen runtime posture is logged explicitly at startup along with
+  bind/port, data dir, and the active slow-path thresholds.
+- Python-side hosted logging now emits structured slow-path events for
+  MCP requests, tool calls, inner runtime, and cost-class admission
+  delay, so operators can distinguish queueing from tool-body work
+  during live incidents.
+- New environment knobs:
+  `KLMCP_SLOW_REQUEST_MS`, `KLMCP_SLOW_TOOL_MS`, and
+  `KLMCP_SLOW_QUEUE_WAIT_MS`.
+
+**Repeatable hosted-load gate.**
+- Added `scripts/bench/bench_hosted_adversarial.py`: a real HTTP/MCP
+  harness that boots the server in hosted mode, floods cheap queries,
+  saturates moderate and expensive tools, polls `/status` concurrently,
+  and emits a JSON report comparing client-observed latency with
+  server-side histograms.
+- Wired the harness into CI and added
+  `docs/ops/public-launch-checklist.md` so launch readiness is a
+  repeatable gate, not an operator memory exercise.
+
+### Changed
+
+**The would-be `0.2.3` hosted-hardening line ships here.**
+- `kernel-lore-sync` now self-heals poisoned local shard repos by
+  deleting zero-ref / unopenable repos and recloning them during sync.
+- Hosted `lore_regex` is permanently narrowed to list-scoped,
+  anchored, metadata-only regex shapes; unsafe full-corpus / prose /
+  patch scans now reject fast with `hosted_restriction`.
+- `lore_corpus_stats` is now cached by generation and warmed at server
+  startup so the steady-state path stays off the timeout cliff.
+- Sync rebuilds `paths/vocab.txt` automatically, eliminating the
+  post-sync manual step for `lore_path_mentions`.
+- `/metrics` now records end-to-end request latency, queue-wait, tool
+  latency, and non-`ok` statuses including `rate_limited` even when a
+  call is rejected before the tool body runs.
+
+### Fixed
+
+- Hosted default logs are quiet enough to follow a real incident:
+  third-party INFO chatter is suppressed by default while our own
+  warnings/errors remain visible.
+- The latency gap seen in client stress runs is now measurable rather
+  than anecdotal: the hosted-load harness and the new metrics/logging
+  surface make queueing / transport inflation directly visible.
+
 ## [0.2.2] — 2026-04-21
 
 ### Fixed

{kernel_lore_mcp-0.2.2 → kernel_lore_mcp-0.3.0}/Cargo.lock

@@ -2638,7 +2638,7 @@ dependencies = [
 
 [[package]]
 name = "kernel_lore_mcp"
-version = "0.2.2"
+version = "0.3.0"
 dependencies = [
  "aho-corasick",
  "anyhow",

{kernel_lore_mcp-0.2.2 → kernel_lore_mcp-0.3.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kernel_lore_mcp"
-version = "0.2.2"
+version = "0.3.0"
 edition = "2024"
 rust-version = "1.85"
 authors = ["Michael Bommarito <michael@bommaritollc.com>"]
@@ -179,3 +179,7 @@ path = "src/bin/bench_ingest_stages.rs"
 [[bin]]
 name = "kernel-lore-sync"
 path = "src/bin/sync.rs"
+
+[[bin]]
+name = "kernel-lore-doctor"
+path = "src/bin/doctor.rs"

{kernel_lore_mcp-0.2.2 → kernel_lore_mcp-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kernel-lore-mcp
-Version: 0.2.2
+Version: 0.3.0
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -88,6 +88,10 @@ kernel-lore-mcp status --data-dir "$KLMCP_DATA_DIR"
 # maintainers / git_sidecar boolean tells you which tools will actually
 # return data on this deployment.
 
+# 4b. inspect shard/index health; add --heal to repair unborn shard HEADs
+#     and remove unrecoverable shard repos so the next sync reclones them
+kernel-lore-doctor --data-dir "$KLMCP_DATA_DIR"
+
 # 5. verify the MCP surface — zero API cost
 git clone --depth 1 https://github.com/mjbommar/kernel-lore-mcp.git
 cd kernel-lore-mcp && ./scripts/agentic_smoke.sh local
@@ -130,8 +134,9 @@ git clone https://github.com/mjbommar/kernel-lore-mcp.git
 cd kernel-lore-mcp
 uv sync
 uv run maturin develop --release
-cargo build --release --bin kernel-lore-sync --bin kernel-lore-ingest
+cargo build --release --bin kernel-lore-sync --bin kernel-lore-ingest --bin kernel-lore-doctor
 ./target/release/kernel-lore-sync --data-dir $KLMCP_DATA_DIR --with-over
+./target/release/kernel-lore-doctor --data-dir $KLMCP_DATA_DIR
 ```
 
 ### Going bigger
@@ -143,13 +148,15 @@ Want production-grade systemd deployment (single `klmcp-sync.timer`
 replacing the pre-v0.2.0 grokmirror + ingest pair)?
 [`docs/ops/runbook.md`](./docs/ops/runbook.md) §1 onwards.
 
-## Status — v0.2.2 (2026-04-21)
+## Status — v0.3.0 (2026-04-21)
 
-Latest patch release: hardens `kernel-lore-sync` for real full-corpus
-bootstrap loads. Sync now chooses a memory-aware worker count, reports
-its RAM budget in startup logs, and emits live RSS / available-memory
-telemetry during fetch and ingest so operators can see pressure before
-the host gets OOM-killed.
+Current release: the hosted-readiness line that would previously have
+been cut as `0.2.3` now lands in `v0.3.0`. The main additions on top of
+`0.2.2` are: sync self-healing for poisoned shard repos, hosted-mode
+regex gating, generation-bound `lore_corpus_stats` caching, automatic
+path-vocab rebuild during sync, explicit `local`/`hosted` deployment
+profiles, structured slow-path profiling logs, and a repeatable
+HTTP/MCP adversarial-load harness plus public-launch checklist.
 
 Shipped:
 
@@ -245,6 +252,8 @@ retriever on that self-supervised signal. Recipe:
   5-min cadence policy + fanout-to-one cost analysis
 - [`docs/ops/production-hardening.md`](./docs/ops/production-hardening.md) —
   threat model, cost-class caps, capability flags, systemd layout
+- [`docs/ops/public-launch-checklist.md`](./docs/ops/public-launch-checklist.md) —
+  pre-launch hosted-box gate: shard health, metrics, harness, log readability
 - [`docs/mcp/client-config.md`](./docs/mcp/client-config.md) —
   copy-paste snippets for Claude Code, Codex, Cursor, Zed
 - [`docs/mcp/transport-auth.md`](./docs/mcp/transport-auth.md) —

{kernel_lore_mcp-0.2.2 → kernel_lore_mcp-0.3.0}/README.md

@@ -53,6 +53,10 @@ kernel-lore-mcp status --data-dir "$KLMCP_DATA_DIR"
 # maintainers / git_sidecar boolean tells you which tools will actually
 # return data on this deployment.
 
+# 4b. inspect shard/index health; add --heal to repair unborn shard HEADs
+#     and remove unrecoverable shard repos so the next sync reclones them
+kernel-lore-doctor --data-dir "$KLMCP_DATA_DIR"
+
 # 5. verify the MCP surface — zero API cost
 git clone --depth 1 https://github.com/mjbommar/kernel-lore-mcp.git
 cd kernel-lore-mcp && ./scripts/agentic_smoke.sh local
@@ -95,8 +99,9 @@ git clone https://github.com/mjbommar/kernel-lore-mcp.git
 cd kernel-lore-mcp
 uv sync
 uv run maturin develop --release
-cargo build --release --bin kernel-lore-sync --bin kernel-lore-ingest
+cargo build --release --bin kernel-lore-sync --bin kernel-lore-ingest --bin kernel-lore-doctor
 ./target/release/kernel-lore-sync --data-dir $KLMCP_DATA_DIR --with-over
+./target/release/kernel-lore-doctor --data-dir $KLMCP_DATA_DIR
 ```
 
 ### Going bigger
@@ -108,13 +113,15 @@ Want production-grade systemd deployment (single `klmcp-sync.timer`
 replacing the pre-v0.2.0 grokmirror + ingest pair)?
 [`docs/ops/runbook.md`](./docs/ops/runbook.md) §1 onwards.
 
-## Status — v0.2.2 (2026-04-21)
+## Status — v0.3.0 (2026-04-21)
 
-Latest patch release: hardens `kernel-lore-sync` for real full-corpus
-bootstrap loads. Sync now chooses a memory-aware worker count, reports
-its RAM budget in startup logs, and emits live RSS / available-memory
-telemetry during fetch and ingest so operators can see pressure before
-the host gets OOM-killed.
+Current release: the hosted-readiness line that would previously have
+been cut as `0.2.3` now lands in `v0.3.0`. The main additions on top of
+`0.2.2` are: sync self-healing for poisoned shard repos, hosted-mode
+regex gating, generation-bound `lore_corpus_stats` caching, automatic
+path-vocab rebuild during sync, explicit `local`/`hosted` deployment
+profiles, structured slow-path profiling logs, and a repeatable
+HTTP/MCP adversarial-load harness plus public-launch checklist.
 
 Shipped:
 
@@ -210,6 +217,8 @@ retriever on that self-supervised signal. Recipe:
   5-min cadence policy + fanout-to-one cost analysis
 - [`docs/ops/production-hardening.md`](./docs/ops/production-hardening.md) —
   threat model, cost-class caps, capability flags, systemd layout
+- [`docs/ops/public-launch-checklist.md`](./docs/ops/public-launch-checklist.md) —
+  pre-launch hosted-box gate: shard health, metrics, harness, log readability
 - [`docs/mcp/client-config.md`](./docs/mcp/client-config.md) —
   copy-paste snippets for Claude Code, Codex, Cursor, Zed
 - [`docs/mcp/transport-auth.md`](./docs/mcp/transport-auth.md) —

{kernel_lore_mcp-0.2.2 → kernel_lore_mcp-0.3.0}/TODO.md

@@ -10,6 +10,53 @@ Status markers:
 - `[DEFER]` — decided to defer past v1; must have a `--> docs/...`
   pointer explaining why
 
+## Current release track (2026-04-21)
+
+We are working straight to `v0.3.0` now. There is **no standalone
+`0.2.3` release tag** planned, but the would-be `0.2.3` hardening
+line is still tracked separately here because it is the first block
+of work that must land before a public hosted launch.
+
+### 0.2.3 carry-forward — land these in `v0.3.0` first
+
+- [x] `kernel-lore-sync` self-heals poisoned shard repos: detect
+  zero-ref / unopenable local shard repos, delete them, and
+  reclone automatically. `kernel-lore-doctor --heal` stays as the
+  explicit maintenance tool, not the primary recovery path.
+- [x] `lore_regex` public-hosted posture: disable/gate it in hosted
+  mode or add enough admission control that the full-corpus default
+  path never just burns 5 s and returns `query_timeout`.
+- [x] `_cached_corpus_stats` generation cache + warm path so warm
+  calls stay well under the wall-clock cap on the full corpus.
+- [x] `/metrics` must record `rate_limited` and every other
+  non-`ok` status consistently, including overload that rejects
+  before the tool body runs.
+- [x] Add end-to-end request latency + queue-wait histograms so the
+  client-side p95 inflation seen under concurrency is visible in
+  Prometheus.
+- [x] Auto-build `paths/vocab.txt` during sync so
+  `lore_path_mentions` works on a fresh healthy hosted box without
+  a manual follow-up command.
+- [x] Hosted default logging drops `tantivy::*` INFO churn unless
+  explicitly enabled; operator logs should show our own progress /
+  warning / error lines first.
+
+### 0.3.0 target — ship after the carry-forward hardening line above
+
+- [x] Hosted deployment profile (`local` vs `hosted`, or equivalent)
+  that flips the exact runtime defaults we intend to expose on the
+  public internet.
+- [x] Repeatable adversarial HTTP/MCP load harness in CI: cheap
+  flood, moderate over-cap concurrency, expensive-tool saturation,
+  and concurrent `/status` responsiveness checks.
+- [x] Public-safe `lore_regex` redesign or permanently narrower
+  admission control. Current full-corpus behavior is not launchable.
+- [x] Reconcile client-observed latency vs server-side tool latency
+  before retuning concurrency caps or over.db pool sizes.
+- [x] Public-launch checklist against a full-corpus host: generation
+  health, shard health, tool surface, metrics, abuse posture, and
+  operator-log readability.
+
 ## Phase 0 — scaffold correctness (blocks everything else)
 
 - [x] Use `uv init --build-backend maturin` for canonical layout
@@ -323,7 +370,8 @@ wired to real data. Those are Phase 2.
 ## Public Instance Track
 
 Independent of Phase 1–6. Gates the hosted instance, not the
-code. Runs in parallel.
+code. Runs in parallel. Release-gated by the current release-track
+section above.
 
 - [ ] Pin `KLMCP_MODE` in `kernel_lore_mcp.config`
   (`local` default, `hosted` opt-in). Same binary, runtime

{kernel_lore_mcp-0.2.2 → kernel_lore_mcp-0.3.0}/docs/architecture/deployment-modes.md

@@ -71,6 +71,9 @@ env-driven). Proposed:
 ```
 KLMCP_MODE=local     # default
 KLMCP_MODE=hosted    # enables embargo quarantine + rate limits
+
+# or equivalently on the serve CLI:
+kernel-lore-mcp serve --transport http --mode hosted
 ```
 
 No feature flag hides the code paths. A hosted instance that

{kernel_lore_mcp-0.2.2 → kernel_lore_mcp-0.3.0}/docs/ops/production-hardening.md

@@ -49,7 +49,11 @@ at the open internet.
 | `KLMCP_COST_CAP_EXPENSIVE` | 4 | Rarely; expensive tools are expensive |
 | `KLMCP_MAINTAINERS_FILE` | `<data_dir>/MAINTAINERS` | Custom kernel-tree snapshot path |
 | `KLMCP_CURSOR_KEY` | (unset) | Required in http mode once pagination ships |
+| `KLMCP_MODE` | `local` | `hosted` for the public-safe posture + quieter operator logs |
 | `KLMCP_LOG_LEVEL` | INFO | DEBUG when diagnosing a specific request |
+| `KLMCP_SLOW_REQUEST_MS` | mode-aware (`1000` hosted / `3000` local) | Lower for tighter slow-request profiling |
+| `KLMCP_SLOW_TOOL_MS` | mode-aware (`500` hosted / `2000` local) | Lower for tool-latency profiling |
+| `KLMCP_SLOW_QUEUE_WAIT_MS` | mode-aware (`25` hosted / `100` local) | Lower to surface admission-delay incidents sooner |
 | `KLMCP_DISABLE_OVER` | (unset) | Set to `1` for parity tests that compare the over.db indexed paths against the legacy Parquet scan. Production leaves this unset. |
 | `KLMCP_BIND` | 127.0.0.1 | **`0.0.0.0` only when behind a reverse proxy** |
 
@@ -134,6 +138,25 @@ What to alert on:
   regression (the OOM round should make this unreachable, but
   worth watching).
 
+## Adversarial harness
+
+Before changing cost caps or the over.db pool, run the hosted-load
+harness and compare client-observed latency with the server-side
+histograms:
+
+```sh
+./.venv/bin/python scripts/bench/bench_hosted_adversarial.py \
+    --json-out /tmp/klmcp-hosted-load.json
+```
+
+Interpretation:
+
+- If client p95 rises while `/status` stays fast and the server-side
+  tool histogram stays modest, the pain is queueing / transport /
+  admission overhead, not the inner reader path.
+- If server-side tool p95 rises with client p95, the tool body is the
+  real hotspot and merits profiling before any cap changes.
+
 ## Known gaps (not blocking launch, worth knowing)
 
 - **Per-IP fairness** — the cost-class semaphore is process-global.

kernel_lore_mcp-0.3.0/docs/ops/public-launch-checklist.md

@@ -0,0 +1,89 @@
+# Public Launch Checklist
+
+This is the "do we actually trust this hosted box?" checklist for a
+full-corpus public deployment.
+
+The goal is not paperwork. The goal is to keep us from launching a
+box that is technically up but operationally blind, query-hostile, or
+quietly broken.
+
+## 1. Corpus and shard health
+
+- `kernel-lore-mcp status --data-dir "$KLMCP_DATA_DIR"` reports
+  `generation >= 1` and `freshness_ok == true`.
+- `kernel-lore-doctor --data-dir "$KLMCP_DATA_DIR"` reports:
+  `healthy == total`, `broken == 0`, `repairable == 0`.
+- `over_db_ready/open_ok == true/true`.
+- Expected tier markers are present for the surface we are exposing:
+  `bm25`, `trigram`, `tid`, `path_vocab`.
+
+## 2. Hosted posture
+
+- The server is running with `KLMCP_MODE=hosted` or
+  `kernel-lore-mcp serve --mode hosted`.
+- Bind is intentional:
+  `127.0.0.1` behind a reverse proxy, or explicit `0.0.0.0`
+  with equivalent network controls.
+- Hosted regex posture is enforced:
+  list-scoped, anchored, metadata-only regexes succeed; unsafe
+  full-corpus or patch/prose regex shapes reject fast with
+  `hosted_restriction`.
+
+## 3. Metrics and overload visibility
+
+- `/metrics` is reachable from the monitoring path.
+- `kernel_lore_mcp_requests_total`,
+  `kernel_lore_mcp_request_latency_seconds`,
+  `kernel_lore_mcp_tool_calls_total`,
+  `kernel_lore_mcp_tool_latency_seconds`,
+  `kernel_lore_mcp_tool_runtime_seconds`,
+  `kernel_lore_mcp_tool_queue_wait_seconds`, and
+  `kernel_lore_mcp_tool_inflight` are all present.
+- A synthetic overload run records non-`ok` statuses, including
+  `rate_limited`, in `/metrics`.
+
+## 4. Repeatable hosted-load gate
+
+Run the adversarial harness against the exact binary + config you
+intend to expose:
+
+```sh
+./.venv/bin/python scripts/bench/bench_hosted_adversarial.py \
+    --json-out /tmp/klmcp-hosted-load.json
+```
+
+Pass criteria:
+
+- Cheap flood completes without `rate_limited`.
+- Moderate and expensive saturation both emit `rate_limited`.
+- `/status` remains responsive while those tool classes saturate.
+- The JSON report shows both client-observed latency and server-side
+  histogram summaries so we can distinguish queueing from tool-body
+  work.
+
+## 5. Operator-log readability
+
+- Hosted default logs are readable without hand-filtering.
+- Third-party INFO spam is absent by default.
+- Startup logs state:
+  version, mode, transport, bind/port, data dir, and slow-path
+  profiling thresholds.
+- Slow requests, slow tool runs, delayed admission, and timeouts emit
+  structured warning/info lines with enough context to debug the next
+  incident.
+
+## 6. Surface sanity
+
+- `scripts/agentic_smoke.sh local` passes against the target data dir.
+- HTTP smoke passes:
+  `uv run pytest tests/python/test_http_transport.py -q`
+- stdio smoke passes:
+  `uv run pytest tests/python/test_stdio_subprocess.py -q`
+
+## 7. Release proof
+
+- The tagged release version matches:
+  `pyproject.toml`, `Cargo.toml`, `src/kernel_lore_mcp/__init__.py`.
+- `CHANGELOG.md` contains a dated section for the exact version.
+- A clean install from PyPI succeeds in a throwaway venv and both
+  `kernel-lore-mcp --help` and `kernel-lore-sync --help` work.

{kernel_lore_mcp-0.2.2 → kernel_lore_mcp-0.3.0}/docs/ops/runbook.md

@@ -64,6 +64,14 @@ mkdir -p "$KLMCP_DATA_DIR"
 ./.venv/bin/kernel-lore-mcp status --data-dir "$KLMCP_DATA_DIR"
 # Expect: {"generation": >= 1, "freshness_ok": true, ...}
 
+# 0A.6b — inspect shard/index health. If a prior run left poisoned shard
+# repos behind, --heal repairs unborn HEADs in place and removes
+# unrecoverable shard repos so the next sync reclones them cleanly.
+cargo build --release --bin kernel-lore-doctor
+./target/release/kernel-lore-doctor --data-dir "$KLMCP_DATA_DIR"
+# Or repair + clean automatically:
+./target/release/kernel-lore-doctor --data-dir "$KLMCP_DATA_DIR" --heal
+
 # 0A.7 — sanity-check the MCP surface without burning API tokens
 ./scripts/agentic_smoke.sh local
 # Expect: PASS: local probe — 6/6 tools, 5/5 resource templates,

{kernel_lore_mcp-0.2.2 → kernel_lore_mcp-0.3.0}/docs/plans/2026-04-17-overdb-followups.md

@@ -10,6 +10,32 @@ inconsistencies — discovered during the build or validation.
 
 Items are ordered by **user-visible impact**, not by ease of fix.
 
+## Hosted-readiness addendum (2026-04-21)
+
+The live full-corpus hosted run on `server6` closed one loop and
+opened another:
+
+- The shard-corruption incident was real, and the new
+  `kernel-lore-doctor --heal` path fixed it cleanly (16 broken
+  shard repos removed; full refetch + ingest completed with
+  `failed_shards=0`). The remaining gap is **automatic sync-side
+  self-heal**, not further manual-repair tooling.
+- The expensive-path posture is now the bigger blocker:
+  `lore_regex` on the full corpus timed out even for simple,
+  list-scoped patterns, and overload produced the correct
+  `query_timeout` + `rate_limited` mix but still proved the tool is
+  not public-ready in its current shape.
+- Client-side stress also showed a metrics gap: `rate_limited`
+  surfaced to callers but did not show up cleanly in `/metrics`,
+  and end-to-end request latency inflated under concurrency without
+  a matching request-scope histogram on the server side.
+- `_cached_corpus_stats` improved from timeout to ~2.2 s once
+  warmed, but still needs a generation-bound cache/warm path before
+  it is safe on a public box.
+
+These items now roll into `docs/plans/2026-04-20-v0.3.0-plan.md`
+Phase 2 (hosted-readiness hardening).
+
 ## Performance
 
 ### F1. patch_search latency = 68 seconds (SHIPPED 2026-04-19, 6.8x win)