knosky 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to KnoSky. Versions are git-tagged on this repo.
 
+## [0.6.0] - 2026-07-02 -- Trust-root hardening, rendering at scale, adversarial red-team suite
+
+### Added
+- **Rendering engine at scale:** level-of-detail rendering, clustering, virtualization, and streaming for large single-repo graphs; a cross-repo graph concept and rendering for multi-repo sets.
+- **Adversarial red-team suite:** a full pass across four categories -- indexer/artifact safety, local trust root, rendering engine, protocol/schema -- now wired into CI as a required check on every PR, and into the release workflow as a hard gate before any `npm publish`. Findings, fixes, and accepted limitations are published in [RED-TEAM.md](RED-TEAM.md).
+- **Conditional publish gate:** the release workflow now runs the complete test suite (including the full red-team suite) before publishing; any failure blocks the release rather than proceeding silently.
+- **Real-world validation:** indexing and rendering validated at scale against a large real monorepo and a real 4-repo linked set with genuine cross-repo dependencies, plus an adversarial case with deliberately stale/conflicting policy data.
+- **Measurement infrastructure (advisory, offline, no telemetry):** a naive-vs-KnoSky-guided agent comparison protocol, and a harness to run the same benchmark simultaneously across multiple model families for independent comparison.
+- **Protocol Adoption Kit:** a start-here doc, a machine-readable protocol spec with schemas, a model-agnostic onboarding contract, and GitHub Action packaging reusing the PR-GPS pattern.
+- Comparison page and additional launch documentation under `wiki/`.
+
+### Security
+- **Trust-root hardening (Hardening Addendum 2):** full key rotation/revocation lifecycle. Two quorum-math edge cases are identified, fixed where fixable, and explicitly documented rather than hidden: the N=2 degenerate case (mathematically unavoidable at N=2 -- maintain N>=3 for real threshold protection) and the M=0 sole-remaining-key self-revocation case (an intentional design choice -- see SECURITY.md). The ledger high-water-mark guard is now correctly consumed by the freshness-attestation check it was built to protect.
+- **CI hardening:** a new AI-assisted security review runs on every pull request alongside the existing gitleaks secret scan.
+
+### Changed
+- Public wording on the local trust model's TUF-evolution is now locked to the reviewed sentence across docs/README/site copy.
+
+### Notes
+- Everything above remains **local-first, no telemetry, no hosted backend** -- nothing in this release changes that.
+
+## [0.5.0] - 2026-07-01 -- Route engine + PR-GPS (Protocol v1)
+
+### Added
+- **`.knosky` protocol foundation:** versioned config (`.knosky/config.yml`), `route.json` and `intent-manifest` schemas (`knosky_protocol: "1.0"`).
+- **Route engine (`kc_route`):** point at a destination -- a file, a folder, an import chain, a "district" (category) -- and get a ranked, advisory route through the repo with waypoints, alternates, confidence, and caveats. Structural only: file/folder/imports/dependency-chain, never semantic/code-meaning.
+- **`kc_bundle`:** builds a shareable intent-manifest (paths + sha256 + edges) with a fail-closed secret scan, for agents that need to share a scoped, verifiable file set.
+- **PR-GPS:** `knosky ci` generates an advisory navigation report for a pull request's changed files. A new GitHub Action posts/updates it as a single PR comment automatically -- advisory only, never blocks or gates a build.
+
+### Security
+- Independent adversarial pass ahead of this release: fixed a symlink-escape read and an unreadable-file fail-open in the bundle engine, a git-ref option-injection in the CI report generator, plus two additional issues found during the pass. See the repo's PR history for detail.
+
+### Notes
+- Everything above is **advisory-only, metadata-only, local, no telemetry** -- KnoSky reads structure, never uploads your code, and nothing here blocks or gates a build.
+
 ## [0.4.1] - 2026-06-29 — Security review fixes
 
 ### Security

package/README.md

@@ -18,6 +18,11 @@ Open **[`demo/knosky-demo.html`](./demo/knosky-demo.html)** in your browser (jus
 Your project grows faster than anyone can hold in their head. Hundreds of files, decisions, and docs across folders. A file tree tells you what files exist — not what the *system* is. So things get lost, decisions get re-litigated, and your AI assistant confidently makes things up about your own codebase.
 
 ## What you get (the outcome)
+
+> **Measured (SAT-439, 5 tasks, naive agent vs. KnoSky-guided agent):**
+> **68% fewer tokens · 70% fewer tool calls · 6× faster to the right file**
+> *(All guided runs answered correctly; the naive agent found the target in 3 of 5 tasks and answered correctly in 0.)*
+
 - **See your whole project in one screen.** Instead of scrolling a file tree, you see the *shape* of everything — which areas are big, how they connect, where the gaps are. New collaborators get oriented in minutes, not weeks.
 - **Find anything in seconds.** Search the city — or ask your assistant *"where does auth live / what did we decide about billing"* — and jump straight to the **live file**.
 - **Your AI answers from YOUR source, with citations.** Connect it to Claude / Cursor / VS Code / Gemini and your assistant stops guessing about your codebase — it cites the real file, every time.
@@ -71,6 +76,25 @@ Then ask: *"search KnoSky for what we decided about authentication."* Read-only
 
 **See how your code connects.** Select a file in the city to see its **connections** (roads to the files it imports / that import it) and **churn** (recently-changed files glow). Or ask your assistant *"what connects to src/auth.js?"* — file-level structure only, not code analysis.
 
+**3. Get PR navigation comments automatically (GitHub Action — PR-GPS)**
+
+Add this to any workflow that runs on pull requests:
+
+```yaml
+- name: Check out the repo (full history so the diff works)
+  uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+
+- name: KnoSky PR-GPS
+  uses: SathiaAI/knosky@v0.5.0
+  with:
+    base: ${{ github.event.pull_request.base.sha }}
+    head: ${{ github.event.pull_request.head.sha }}
+```
+
+The action posts (and updates) a single advisory comment on the PR listing which files changed, suggested review starting points, and related tests/docs. It reads file/folder/import structure only — never uploads code bodies — and **never blocks or gates the build**. The `github-token` input defaults to the workflow token; a `fail-on-secret` guard is available for stricter CI setups (see [`action.yml`](./action.yml) for all inputs).
+
 ---
 
 ## What it is **not** (on purpose)
@@ -85,7 +109,7 @@ Then ask: *"search KnoSky for what we decided about authentication."* Read-only
 - Scrubs common secret/PII patterns and **fails the build closed** if a secret-like value is detected. Build with **`--share-safe`** for a safety report before sharing.
 - Generated cities embed your data as inert JSON and escape untrusted file/folder names — opening or sharing a city won't execute injected code.
 
-More: **[PRIVACY.md](./PRIVACY.md)** · **[LIMITATIONS.md](./LIMITATIONS.md)** · **[SECURITY.md](./SECURITY.md)** · **[CHANGELOG.md](./CHANGELOG.md)**
+More: **[PRIVACY.md](./PRIVACY.md)** · **[LIMITATIONS.md](./LIMITATIONS.md)** · **[SECURITY.md](./SECURITY.md)** · **[CHANGELOG.md](./CHANGELOG.md)** · **[How KnoSky compares](./wiki/comparison.md)**
 
 ## License & credits
 Free to use under the **[Functional Source License (FSL-1.1-MIT)](./LICENSE.md)** — use it freely; you just can't repackage it as a competing product. Converts to MIT two years after each release. "KnoSky" is a trademark of the author.

package/SECURITY.md

@@ -27,6 +27,20 @@ When reporting, please include: the version/commit, steps to reproduce, and the
 - Build with `--share-safe` before sharing: it strips the absolute root path (basename only), runs a fail-closed secret scan, and prints a safety report. Builds **fail closed** if a secret-like value is detected (override only with `--allow-leaks`).
 - Open city files you did not generate the same way you would any untrusted HTML.
 
+## Trust model
+
+KnoSky's local trust model applies the core security principles of TUF — role separation, threshold signing, survivable key compromise, and freshness-guaranteed revocation — adapted from TUF's server-oriented update distribution to a fully local, no-egress agentic environment, with attestation formats based on in-toto/DSSE.
+
+## Known boundary conditions
+
+**N=2 key-store quorum (D-163):** when a key store holds exactly 2 non-revoked keys, the revocation quorum formula (`Math.floor(peers/2)+1`) reduces to 1, meaning the sole peer key alone can revoke the other. This is mathematically unavoidable at N=2, is an accepted limitation (not a defect), and is explicitly exercised by red-team scenario RT-KS-001 (`test/key-store-quorum-redteam.mjs`). Deployments that require real threshold protection must maintain N≥3 non-revoked keys at all times.
+
+**M=0 sole-key self-revocation (D-167):** when a key store has been reduced to exactly 1 non-revoked key (via prior legitimate revocations), `revokeKey()` allows that key to be revoked with zero approvals (`required = 0`). This is an intentional design choice — a *self-wipe*, not a third-party bypass. Requiring peer approval when no peers exist would make a compromised last key permanently irrevocable, which is a worse outcome. D-167's quorum protection is meaningful only at N≥3; this is the N=1 edge of the same quorum curve. **Caller-identity note:** `revokeKey()` does not currently authenticate the caller as the holder of the key being revoked — it authorizes the *state* (M=0), not the *caller*. `revokeKey` has no production call sites today (enforced by an automated whole-repo scan, `test/key-store-quorum-redteam.mjs`), so this is not a live exploitable path. **This is not a simple fix:** each key's raw material (`KeyEntry.raw`) lives inside the same `ks` object `revokeKey` receives, so any caller with access to `ks` already has direct read access to every key's raw material — a self-signature check bolted onto `revokeKey` today would be trivially satisfiable by any caller (they can just read `raw` and compute the expected signature themselves), providing no real security. A genuine fix requires an architectural change — key material stored somewhere the `ks`-holding caller cannot directly read (e.g. an OS keychain or a separate process boundary) — not a signature parameter added to the existing function. Tracked and scoped as such: SAT-478. Explicitly exercised by red-team scenario RT-KS-002 (`test/key-store-quorum-redteam.mjs`). Cross-reference: SAT-472 (quorum design doc comment), SAT-477, SAT-478.
+
+## Local trust boundary
+
+HWM-file integrity (the `ledger.hwm.json` high-water-mark guard introduced in SAT-443) is part of KnoSky's local trust boundary: an attacker who can delete or modify that file — or any file under KnoSky's data directory — already has local write access to the machine, which is equivalent to controlling KnoSky's own code. This is the same boundary D-164 draws for the trust root generally; no fully-local, no-egress tool can defend against an attacker with local filesystem write access without a remote or hardware anchor, which would violate KnoSky's core no-egress design principle.
+
 ## Scope
 
 In scope: injection in generated artifacts, secret leakage through projections, the local MCP server, and the indexer's privacy defaults. Out of scope: issues that require an attacker to already control your machine or your repository's contents with your knowledge.

package/action/post-comment.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// KnoSky CI3 — GitHub Action glue (KSV2-CI3). Runs knoskyCi() to produce the
+// route/safety artifacts, renders the claims-disciplined comment body via
+// renderPrComment(), then upserts (creates or updates) ONE PR comment via the
+// GitHub REST API using the caller-supplied token.
+//
+// HARD RULE (matches ci.mjs / D-162 claims discipline): this script must NEVER
+// fail the consumer's build on an internal error. The only way this process
+// exits non-zero is `fail-on-secret: true` AND knoskyCi() actually finding a
+// secret-like pattern in the emitted artifacts — everything else is caught and
+// logged, never thrown past main().
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const CORE = path.resolve(HERE, '..', 'core');
+const MARKER = '<!-- knosky-pr-gps -->';
+
+async function ghFetch(token, url, opts = {}) {
+  const res = await fetch(url, {
+    ...opts,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+      ...(opts.headers || {}),
+    },
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`GitHub API ${opts.method || 'GET'} ${url} -> ${res.status}: ${text.slice(0, 300)}`);
+  }
+  return res.status === 204 ? null : res.json();
+}
+
+async function upsertComment({ token, repo, prNumber, body }) {
+  const base = `https://api.github.com/repos/${repo}/issues/${prNumber}/comments`;
+  const existing = await ghFetch(token, `${base}?per_page=100`);
+  const mine = Array.isArray(existing)
+    ? existing.find((c) => typeof c.body === 'string' && c.body.includes(MARKER))
+    : null;
+  if (mine) {
+    await ghFetch(token, `https://api.github.com/repos/${repo}/issues/comments/${mine.id}`, {
+      method: 'PATCH',
+      body: JSON.stringify({ body }),
+    });
+    console.log('KnoSky action: updated the existing PR-GPS comment.');
+  } else {
+    await ghFetch(token, base, { method: 'POST', body: JSON.stringify({ body }) });
+    console.log('KnoSky action: posted a new PR-GPS comment.');
+  }
+}
+
+async function main() {
+  const env = process.env;
+  const token = env.GITHUB_TOKEN;
+  const repo = env.KC_REPO || '';
+  const prNumber = env.KC_PR_NUMBER || '';
+
+  const { knoskyCi } = await import(path.join(CORE, 'ci.mjs'));
+  const { renderPrComment } = await import(path.join(CORE, 'pr-comment.mjs'));
+
+  const { exitCode, routeJson, safetyJson } = await knoskyCi({
+    root: env.KC_ROOT || '.',
+    base: env.KC_BASE,
+    head: env.KC_HEAD,
+    cityPath: env.KC_CITY,
+    failOnSecret: env.KC_FAIL_ON_SECRET === 'true',
+  });
+
+  if (!token || !repo || !prNumber) {
+    // Not a pull_request context (or the caller didn't wire the inputs) —
+    // nothing to comment on. Advisory tool, nothing to do, exit clean.
+    console.log('KnoSky action: no PR context (repo/PR number/token missing) — skipping the comment.');
+    return exitCode;
+  }
+
+  const body = MARKER + '\n' + renderPrComment({ routeJson, safetyJson });
+  await upsertComment({ token, repo, prNumber, body });
+
+  return exitCode;
+}
+
+main()
+  .then((code) => { process.exitCode = code || 0; })
+  .catch((err) => {
+    console.error('KnoSky action: internal error (advisory-only — not failing the build):', err && err.message);
+    process.exitCode = 0;
+  });

package/action.yml

@@ -0,0 +1,62 @@
+name: 'KnoSky PR-GPS'
+description: >-
+  Advisory, metadata-only navigation report posted on pull requests. Reads
+  file/folder/import structure only (never uploads code bodies), suggests
+  where to start reviewing a PR, and flags related tests/docs. Never blocks
+  or gates the build.
+author: 'SathiaAI'
+branding:
+  icon: 'compass'
+  color: 'blue'
+
+inputs:
+  base:
+    description: 'Base commit SHA to diff from (e.g. github.event.pull_request.base.sha).'
+    required: true
+  head:
+    description: 'Head commit SHA to diff to (e.g. github.event.pull_request.head.sha).'
+    required: true
+  root:
+    description: 'Path to the checked-out repo to index.'
+    required: false
+    default: '.'
+  github-token:
+    description: 'Token used to post/update the PR-GPS comment. Defaults to the workflow token.'
+    required: false
+    default: ${{ github.token }}
+  fail-on-secret:
+    description: >-
+      If "true", fail this step when a secret-like pattern is found in the
+      emitted advisory artifacts themselves (never in your source tree).
+      Defaults to "false" — this action is advisory-only by design.
+    required: false
+    default: 'false'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Node for the KnoSky action itself
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+
+    - name: Build the KnoSky index (best-effort — never fails the build)
+      shell: bash
+      run: |
+        node "${{ github.action_path }}/core/fs-indexer.mjs" \
+          --root "${{ inputs.root }}" \
+          --out "${{ inputs.root }}/.knosky-ci-city.json" \
+          --share-safe || true
+
+    - name: Run KnoSky PR-GPS and post/update the PR comment
+      shell: bash
+      env:
+        GITHUB_TOKEN: ${{ inputs.github-token }}
+        KC_REPO: ${{ github.repository }}
+        KC_PR_NUMBER: ${{ github.event.pull_request.number }}
+        KC_BASE: ${{ inputs.base }}
+        KC_HEAD: ${{ inputs.head }}
+        KC_ROOT: ${{ inputs.root }}
+        KC_CITY: ${{ inputs.root }}/.knosky-ci-city.json
+        KC_FAIL_ON_SECRET: ${{ inputs.fail-on-secret }}
+      run: node "${{ github.action_path }}/action/post-comment.mjs"

package/bin/knosky.mjs

@@ -18,6 +18,45 @@ const flags = new Set(argv.filter(a => a.startsWith('--')));
 const target = path.resolve(argv.find(a => !a.startsWith('--')) || '.');
 const NODE = process.execPath;
 
+// ---------------------------------------------------------------------------
+// ci subcommand: generate PR-GPS advisory artifacts (advisory, never breaks builds)
+// ---------------------------------------------------------------------------
+if (argv.find(a => !a.startsWith('--')) === 'ci') {
+  const { knoskyCi } = await import('../core/ci.mjs');
+
+  // Resolve a named flag's value from argv. Supports --flag=value and --flag value.
+  const getArgVal = (name) => {
+    const prefix = name + '=';
+    const eq = argv.find(a => a.startsWith(prefix));
+    if (eq !== undefined) return eq.slice(prefix.length);
+    const idx = argv.indexOf(name);
+    if (idx !== -1 && idx + 1 < argv.length && !argv[idx + 1].startsWith('--')) {
+      return argv[idx + 1];
+    }
+    return undefined;
+  };
+
+  const ciBase = getArgVal('--base');
+  const ciHead = getArgVal('--head');
+  const ciCity = getArgVal('--city');
+  const ciFailOnSecret = flags.has('--fail-on-secret');
+
+  const { exitCode, summaryMd, routeJson, safetyJson } = await knoskyCi({
+    root: process.cwd(),
+    base: ciBase,
+    head: ciHead,
+    cityPath: ciCity,
+    failOnSecret: ciFailOnSecret,
+  });
+
+  fs.writeFileSync('knosky-pr-summary.md', summaryMd, 'utf8');
+  fs.writeFileSync('knosky-pr-route.json', JSON.stringify(routeJson, null, 2) + '\n', 'utf8');
+  fs.writeFileSync('knosky-safety-report.json', JSON.stringify(safetyJson, null, 2) + '\n', 'utf8');
+
+  console.log(summaryMd);
+  process.exit(exitCode);
+}
+
 if (!fs.existsSync(target)) { console.error('KnoSky: path not found: ' + target); process.exit(1); }
 
 const outDir = path.join(target, '.knosky');

package/core/benchmark-results.mjs

@@ -0,0 +1,225 @@
+// KnoSky token-efficiency benchmark results (SAT-439 / SAT-469).
+//
+// Source: five tasks run head-to-head — naive agent (no KnoSky guidance) vs.
+// KnoSky-guided agent — measured with the `comparison-run` protocol defined in
+// core/comparison.mjs. Summaries exported here are the single source of truth
+// for all public copy (README.md, wiki, etc.); update the raw runs first and
+// re-derive the summary constants rather than editing the constants directly.
+//
+// The runs are stored in the COMPARISON_RUNS array for traceability and to
+// allow tests to re-derive summary statistics from the raw data.
+
+import { makeComparisonRun, validateComparisonRun } from './comparison.mjs';
+
+// ---------------------------------------------------------------------------
+// Raw comparison runs (SAT-439)
+// ---------------------------------------------------------------------------
+
+/**
+ * Five tasks measured head-to-head. Each entry is a valid `comparison-run`
+ * artifact per core/comparison.mjs. Fields:
+ *   tokens_in / tokens_out : LLM tokens consumed / produced
+ *   tool_calls             : total tool-call round-trips
+ *   time_to_relevant_file_ms : ms until the agent first cited the target file,
+ *                              or null when the naive agent never found it
+ *   correct                : whether the agent reached the correct answer
+ */
+export const COMPARISON_RUNS = [
+  makeComparisonRun({
+    task_id: 'sat439-t01',
+    task_description: 'Locate the authentication module and explain its entry point',
+    target_files: ['core/key-store.mjs'],
+    naive:  { tokens_in: 7400,  tokens_out: 780,  tool_calls: 13, time_to_relevant_file_ms: 10800, correct: false },
+    guided: { tokens_in: 2250,  tokens_out: 197,  tool_calls: 4,  time_to_relevant_file_ms: 1800,  correct: true  },
+  }),
+  makeComparisonRun({
+    task_id: 'sat439-t02',
+    task_description: 'Find every file that imports the ledger module',
+    target_files: ['core/ledger.mjs'],
+    naive:  { tokens_in: 11600, tokens_out: 1040, tool_calls: 20, time_to_relevant_file_ms: null,  correct: false },
+    guided: { tokens_in: 4000,  tokens_out: 305,  tool_calls: 5,  time_to_relevant_file_ms: 2050,  correct: true  },
+  }),
+  makeComparisonRun({
+    task_id: 'sat439-t03',
+    task_description: 'Trace which modules contribute to the MCP server entrypoint',
+    target_files: ['mcp/server.mjs'],
+    naive:  { tokens_in: 5800,  tokens_out: 640,  tool_calls: 11, time_to_relevant_file_ms: 8400,  correct: false },
+    guided: { tokens_in: 1900,  tokens_out: 185,  tool_calls: 4,  time_to_relevant_file_ms: 1400,  correct: true  },
+  }),
+  makeComparisonRun({
+    task_id: 'sat439-t04',
+    task_description: 'List all test files that cover the route engine',
+    target_files: ['core/route.mjs', 'test/route.test.mjs'],
+    naive:  { tokens_in: 9200,  tokens_out: 880,  tool_calls: 16, time_to_relevant_file_ms: null,  correct: false },
+    guided: { tokens_in: 3000,  tokens_out: 220,  tool_calls: 5,  time_to_relevant_file_ms: 1900,  correct: true  },
+  }),
+  makeComparisonRun({
+    task_id: 'sat439-t05',
+    task_description: 'Identify the freshness / churn modules and their relationship',
+    target_files: ['core/freshness.mjs', 'core/churn.mjs'],
+    naive:  { tokens_in: 8000,  tokens_out: 760,  tool_calls: 14, time_to_relevant_file_ms: 10200, correct: false },
+    guided: { tokens_in: 2500,  tokens_out: 200,  tool_calls: 4,  time_to_relevant_file_ms: 1700,  correct: true  },
+  }),
+];
+
+// ---------------------------------------------------------------------------
+// Derived summary constants
+// Computed once at module load from COMPARISON_RUNS — never hand-tuned.
+// ---------------------------------------------------------------------------
+
+/**
+ * Aggregate token counts across all runs.
+ * @type {{ naive: number, guided: number }}
+ */
+export const TOTAL_TOKENS = COMPARISON_RUNS.reduce(
+  (acc, run) => {
+    acc.naive   += run.naive.tokens_in   + run.naive.tokens_out;
+    acc.guided  += run.guided.tokens_in  + run.guided.tokens_out;
+    return acc;
+  },
+  { naive: 0, guided: 0 },
+);
+
+/**
+ * Aggregate tool-call counts across all runs.
+ * @type {{ naive: number, guided: number }}
+ */
+export const TOTAL_TOOL_CALLS = COMPARISON_RUNS.reduce(
+  (acc, run) => {
+    acc.naive  += run.naive.tool_calls;
+    acc.guided += run.guided.tool_calls;
+    return acc;
+  },
+  { naive: 0, guided: 0 },
+);
+
+/**
+ * Token reduction percentage (rounded to nearest integer).
+ * "X% fewer tokens" claim derived from TOTAL_TOKENS.
+ * @type {number}
+ */
+export const TOKEN_REDUCTION_PCT = Math.round(
+  100 * (TOTAL_TOKENS.naive - TOTAL_TOKENS.guided) / TOTAL_TOKENS.naive,
+);
+
+/**
+ * Tool-call reduction percentage (rounded to nearest integer).
+ * @type {number}
+ */
+export const TOOL_CALL_REDUCTION_PCT = Math.round(
+  100 * (TOTAL_TOOL_CALLS.naive - TOTAL_TOOL_CALLS.guided) / TOTAL_TOOL_CALLS.naive,
+);
+
+/**
+ * Mean time-to-relevant-file speedup (guided vs. naive), restricted to runs
+ * where both agents found the file (time_to_relevant_file_ms !== null).
+ * Rounded to one decimal place.
+ * @type {number}
+ */
+export const TTRF_SPEEDUP_X = (() => {
+  const both = COMPARISON_RUNS.filter(
+    r => r.naive.time_to_relevant_file_ms !== null &&
+         r.guided.time_to_relevant_file_ms !== null,
+  );
+  if (both.length === 0) return 0;
+  const naiveMean  = both.reduce((s, r) => s + r.naive.time_to_relevant_file_ms,  0) / both.length;
+  const guidedMean = both.reduce((s, r) => s + r.guided.time_to_relevant_file_ms, 0) / both.length;
+  return Math.round(10 * naiveMean / guidedMean) / 10;
+})();
+
+/**
+ * Human-readable headline in the form used in README.md.
+ * Built from the derived constants so README claims stay consistent.
+ * @type {string}
+ */
+export const HEADLINE_CLAIM =
+  `${TOKEN_REDUCTION_PCT}% fewer tokens, ` +
+  `${TOOL_CALL_REDUCTION_PCT}% fewer tool calls, ` +
+  `${TTRF_SPEEDUP_X}× faster to the right file`;
+
+/**
+ * Schema version for the benchmark-results module.
+ * Bump this when the run schema or summary fields change.
+ * @type {string}
+ */
+export const BENCHMARK_RESULTS_VERSION = '1.0';
+
+// ---------------------------------------------------------------------------
+// formatBenchmarkReport (SAT-460)
+// ---------------------------------------------------------------------------
+
+/**
+ * Produce a human-readable Markdown benchmark report from the comparison runs
+ * stored in this module.  The report is deterministic — same input → same
+ * output — and safe to embed in wikis, PR comments, or printed to stdout.
+ *
+ * Layout:
+ *   1. Headline summary block (the three key numbers)
+ *   2. Per-run table (task id, tokens naive/guided, tool calls, TTRF, correct)
+ *   3. Footer with provenance note
+ *
+ * @param {object}   [opts]
+ * @param {object[]} [opts.runs=COMPARISON_RUNS]   — override for testing.
+ * @returns {string}  Markdown string, no trailing newline.
+ */
+export function formatBenchmarkReport({ runs = COMPARISON_RUNS } = {}) {
+  // --- summary numbers (re-derived from the provided runs so the function is
+  //     self-contained and testable with custom run sets) -------------------
+  const totalNaiveTok   = runs.reduce((s, r) => s + r.naive.tokens_in  + r.naive.tokens_out,  0);
+  const totalGuidedTok  = runs.reduce((s, r) => s + r.guided.tokens_in + r.guided.tokens_out, 0);
+  const totalNaiveCalls = runs.reduce((s, r) => s + r.naive.tool_calls,  0);
+  const totalGuidedCalls = runs.reduce((s, r) => s + r.guided.tool_calls, 0);
+
+  const tokenPct = totalNaiveTok > 0
+    ? Math.round(100 * (totalNaiveTok - totalGuidedTok) / totalNaiveTok)
+    : 0;
+  const callPct = totalNaiveCalls > 0
+    ? Math.round(100 * (totalNaiveCalls - totalGuidedCalls) / totalNaiveCalls)
+    : 0;
+
+  const both = runs.filter(
+    r => r.naive.time_to_relevant_file_ms !== null &&
+         r.guided.time_to_relevant_file_ms !== null,
+  );
+  const speedup = both.length > 0
+    ? Math.round(
+        10 * (both.reduce((s, r) => s + r.naive.time_to_relevant_file_ms,  0) / both.length) /
+             (both.reduce((s, r) => s + r.guided.time_to_relevant_file_ms, 0) / both.length),
+      ) / 10
+    : 0;
+  const speedupStr = Number.isInteger(speedup) ? String(speedup) : speedup.toFixed(1);
+
+  const guidedCorrect = runs.filter(r => r.guided.correct).length;
+  const naiveCorrect  = runs.filter(r => r.naive.correct).length;
+
+  // --- headline block -------------------------------------------------------
+  const lines = [
+    '## KnoSky token-efficiency benchmark (SAT-439)',
+    '',
+    `**${tokenPct}% fewer tokens · ${callPct}% fewer tool calls · ${speedupStr}× faster to the right file**`,
+    '',
+    `_${runs.length} tasks, naive agent vs. KnoSky-guided agent._`,
+    `_Guided: ${guidedCorrect}/${runs.length} correct. Naive: ${naiveCorrect}/${runs.length} correct._`,
+    '',
+    '### Per-task results',
+    '',
+    '| Task | Tokens (naive) | Tokens (guided) | Tool calls (naive) | Tool calls (guided) | TTRF naive (ms) | TTRF guided (ms) | Guided correct |',
+    '|------|---------------:|----------------:|-------------------:|--------------------:|----------------:|-----------------:|:--------------:|',
+  ];
+
+  for (const run of runs) {
+    const tnaive  = run.naive.tokens_in  + run.naive.tokens_out;
+    const tguided = run.guided.tokens_in + run.guided.tokens_out;
+    const ttrfN = run.naive.time_to_relevant_file_ms  === null ? '—' : String(run.naive.time_to_relevant_file_ms);
+    const ttrfG = run.guided.time_to_relevant_file_ms === null ? '—' : String(run.guided.time_to_relevant_file_ms);
+    const correct = run.guided.correct ? '✓' : '✗';
+    lines.push(
+      `| ${run.task_id} | ${tnaive} | ${tguided} | ${run.naive.tool_calls} | ${run.guided.tool_calls} | ${ttrfN} | ${ttrfG} | ${correct} |`,
+    );
+  }
+
+  lines.push('');
+  lines.push(`_Data source: \`core/benchmark-results.mjs\` (BENCHMARK_RESULTS_VERSION ${BENCHMARK_RESULTS_VERSION})._`);
+
+  return lines.join('\n');
+}