knodin 0.8.4 → 0.8.6

package/dist/src/shared-index/schemas.js

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import { SHARED_INDEX_LIMITS } from "./contract.js";
+import { SharedIndexError } from "./s3-client.js";
+const sha256 = z.string().regex(/^[a-f0-9]{64}$/);
+const gitObject = z.string().regex(/^[a-f0-9]{40,64}$/);
+const timestamp = z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/);
+const repository = z
+    .object({
+    host: z
+        .string()
+        .max(253)
+        .regex(/^(?!.*\.\.)(?!.*(?:^|\.)-)(?!.*-(?:\.|$))[a-z0-9](?:[a-z0-9.-]{0,251}[a-z0-9])?$/),
+    owner: z
+        .string()
+        .max(255)
+        .regex(/^[a-z0-9](?:[a-z0-9-]{0,253}[a-z0-9])?$/),
+    name: z
+        .string()
+        .max(255)
+        .regex(/^[a-z0-9](?:[a-z0-9._-]{0,253}[a-z0-9])?$/),
+})
+    .strict();
+export const branchPointerSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    registrationId: z.string().regex(/^[a-z0-9][a-z0-9._-]{0,127}$/),
+    repository,
+    branch: z.string().min(1).max(1024),
+    commit: gitObject,
+    inputFingerprint: sha256,
+    manifestKey: z.string().min(1).max(2048),
+    manifestSha256: sha256,
+    updatedAt: timestamp,
+})
+    .strict();
+export const compatibilitySchema = z
+    .object({
+    knodinVersion: z.string().regex(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/),
+    databaseSchemaVersion: z.number().int().positive().max(2_147_483_647),
+    modelId: z.string().min(1).max(512),
+    modelDigest: sha256,
+    parserBundleDigest: sha256,
+    indexConfigDigest: sha256,
+    prunePolicyDigest: sha256,
+})
+    .strict();
+export const manifestSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    registrationId: z.string().regex(/^[a-z0-9][a-z0-9._-]{0,127}$/),
+    repository,
+    commit: gitObject,
+    generatedAt: timestamp,
+    compatibility: compatibilitySchema,
+    graph: z
+        .object({
+        key: z.string().min(1).max(2048),
+        compressedSha256: sha256,
+        compressedBytes: z.number().int().positive().max(SHARED_INDEX_LIMITS.compressedBytes),
+        uncompressedSha256: sha256,
+        uncompressedBytes: z.number().int().positive().max(SHARED_INDEX_LIMITS.uncompressedBytes),
+    })
+        .strict(),
+})
+    .strict();
+function parse(label, bytes, limit, schema) {
+    if (bytes.byteLength > limit)
+        throw new SharedIndexError("integrity", `shared-index ${label} exceeds its byte limit`);
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(bytes).toString("utf8"));
+    }
+    catch {
+        throw new SharedIndexError("integrity", `shared-index ${label} is not valid JSON`);
+    }
+    const result = schema.safeParse(value);
+    if (!result.success)
+        throw new SharedIndexError("integrity", `shared-index ${label} does not match schema v1`);
+    return result.data;
+}
+export function parseBranchPointer(bytes) {
+    return parse("branch pointer", bytes, SHARED_INDEX_LIMITS.pointerBytes, branchPointerSchema);
+}
+export function parseManifest(bytes) {
+    return parse("manifest", bytes, SHARED_INDEX_LIMITS.manifestBytes, manifestSchema);
+}

package/dist/src/shared-index/selection.js

@@ -0,0 +1,111 @@
+import child_process from "node:child_process";
+import { SHARED_INDEX_LIMITS, sharedBranchMatches, } from "./contract.js";
+import { branchPointerKey, signatureKey, validatePointerBinding, verifyManifest, } from "./manifest.js";
+import { SharedIndexError } from "./s3-client.js";
+import { parseBranchPointer, parseManifest, } from "./schemas.js";
+function git(repo, args) {
+    const result = child_process.spawnSync("git", args, {
+        cwd: repo,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    return { status: result.status, stdout: result.stdout.trim() };
+}
+function localHead(repo) {
+    const result = git(repo, ["rev-parse", "--verify", "HEAD"]);
+    if (result.status !== 0 || !/^[a-f0-9]{40,64}$/.test(result.stdout))
+        throw new SharedIndexError("unavailable", "shared-index could not resolve local HEAD");
+    return result.stdout;
+}
+function currentBranch(repo) {
+    const result = git(repo, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+    return result.status === 0 && result.stdout ? result.stdout.normalize("NFC") : undefined;
+}
+export function configuredBranchCandidates(config, branch) {
+    const candidates = new Set();
+    for (const pattern of config.branches) {
+        if (pattern.endsWith("/*")) {
+            if (branch && sharedBranchMatches(pattern, branch))
+                candidates.add(branch);
+        }
+        else
+            candidates.add(pattern.normalize("NFC"));
+    }
+    return [...candidates];
+}
+async function readBounded(stream, maxBytes) {
+    const chunks = [];
+    let received = 0;
+    for await (const chunk of stream) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        received += bytes.byteLength;
+        if (received > maxBytes)
+            throw new SharedIndexError("integrity", "shared-index object exceeded its byte limit");
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks, received);
+}
+async function objectBytes(store, key, maxBytes, signal) {
+    const metadata = await store.head(key, { signal });
+    if (metadata.bytes > maxBytes)
+        throw new SharedIndexError("integrity", "shared-index object exceeds its byte limit");
+    const stream = await store.get(key, { maxBytes, signal });
+    const bytes = await readBounded(stream, maxBytes);
+    if (bytes.byteLength !== metadata.bytes)
+        throw new SharedIndexError("integrity", "shared-index object length changed during download");
+    return bytes;
+}
+function commitRelation(repo, head, commit) {
+    if (commit === head)
+        return { relation: "exact", distance: 0 };
+    const ancestor = git(repo, ["merge-base", "--is-ancestor", commit, head]);
+    if (ancestor.status !== 0)
+        return null;
+    const count = git(repo, ["rev-list", "--count", `${commit}..${head}`]);
+    const distance = Number(count.stdout);
+    if (count.status !== 0 || !Number.isSafeInteger(distance) || distance < 1)
+        return null;
+    return { relation: "ancestor", distance };
+}
+function rejection(branch, error) {
+    if (error instanceof SharedIndexError)
+        return { branch, category: error.category, reason: error.message.slice(0, 512) };
+    return {
+        branch,
+        category: "unavailable",
+        reason: "shared-index snapshot discovery failed",
+    };
+}
+export async function selectSharedSnapshot(options) {
+    const head = localHead(options.repo);
+    const branches = configuredBranchCandidates(options.config, currentBranch(options.repo));
+    const settled = await Promise.all(branches.map(async (branch) => {
+        try {
+            const pointerBytes = await objectBytes(options.store, branchPointerKey(options.config, branch), SHARED_INDEX_LIMITS.pointerBytes, options.signal);
+            const pointer = parseBranchPointer(pointerBytes);
+            if (pointer.branch.normalize("NFC") !== branch)
+                throw new SharedIndexError("integrity", "shared-index pointer branch does not match its discovery key");
+            validatePointerBinding(options.config, pointer);
+            const relation = commitRelation(options.repo, head, pointer.commit);
+            if (!relation)
+                throw new SharedIndexError("compatibility", "shared-index snapshot commit is not a proven local ancestor");
+            const [manifestBytes, signature] = await Promise.all([
+                objectBytes(options.store, pointer.manifestKey, SHARED_INDEX_LIMITS.manifestBytes, options.signal),
+                objectBytes(options.store, signatureKey(pointer.manifestKey), SHARED_INDEX_LIMITS.signatureBytes, options.signal),
+            ]);
+            const manifest = parseManifest(manifestBytes);
+            verifyManifest(options.config, pointer, manifestBytes, manifest, signature, options.clientCompatibility);
+            return { branch, pointer, manifest, manifestBytes, signature, ...relation };
+        }
+        catch (error) {
+            return rejection(branch, error);
+        }
+    }));
+    const verified = settled.filter((item) => "manifest" in item);
+    verified.sort((left, right) => left.distance - right.distance || left.branch.localeCompare(right.branch));
+    return {
+        ...(verified[0] ? { selected: verified[0] } : {}),
+        verified,
+        rejected: settled.filter((item) => !("manifest" in item)),
+    };
+}

package/dist/src/tools/knodin-tools.js

@@ -6,6 +6,7 @@
  * `server.tool()` / Zod-to-handler inference — that path OOMs `tsc`). One flat
  * gateway keeps the client LLM's context small.
  */
+import fs from "node:fs";
 import nodePath from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveCliRuntimeCommand } from "../cli-args.js";
@@ -17,6 +18,7 @@ import { getDocSection, listDocTopics } from "../docs-sections.js";
 import { diagnoseInstallation } from "../doctor.js";
 import { createEngine, REPO_WIDE_QUERY_PATTERNS, } from "../engine/index.js";
 import { measurePerfPhaseSync } from "../engine/perf.js";
+import { resolveDbPath } from "../engine/state-paths.js";
 import { runExecutionProfile } from "../execution-profile.js";
 import { diagnoseFailure, } from "../failure-diagnosis.js";
 import { decorateGraphQueryResult, inspectGraphQueryHealth } from "../graph-query-health.js";
@@ -31,6 +33,8 @@ import { createRepairPlan } from "../repair-progress.js";
 import { runRepositoryInitializationProcess } from "../repository-init-process.js";
 import { discoverRepositories, initializeRepositories, inventoryRepository, searchRepositories, } from "../repository-management.js";
 import { applyResponseBudget } from "../response-budget.js";
+import { loadSharedIndexConfig } from "../shared-index/config.js";
+import { EMPTY_OVERLAY, readSharedIndexProvenance, readSharedRestoreAttempt, } from "../shared-index/provenance.js";
 import { configuredRepositoryInitMemoryLimitBytes, enrichSystemRelationships, incorporateSystemQueryEvidence, indexModeForPath, loadSystemConfiguration, queryConfiguredSystem, systemMembershipsForPath, validateSystemHealth, } from "../system-config.js";
 import { trustedUpdateStatus } from "../update-policy.js";
 import { waitForFresh } from "../wait-for-fresh.js";
@@ -113,6 +117,7 @@ const QUERY_PATTERNS = [
     "structural_implementations_of",
     "tests_for",
     "file_summary",
+    "file_metrics",
     "batch_outline",
     "project_overview",
     "shortest_path",
@@ -150,6 +155,7 @@ const GRAPH_INDEPENDENT_QUERY_PATTERNS = new Set([
     "lsp_definitions",
     "lsp_declarations",
     "lsp_implementations",
+    "file_metrics",
 ]);
 function buildDocumentedKnodinTools() {
     return [
@@ -302,7 +308,7 @@ function buildDocumentedKnodinTools() {
                     },
                     base: {
                         type: "string",
-                        description: "review/context: compatibility base ref (default HEAD~1). For review this maps to scope=all versus the base; compare uses it as the default older ref. context uses it only for risk.",
+                        description: "review/context: compatibility base ref (default HEAD~1). query file_metrics: local ref whose merge-base is measured. For review this maps to scope=all versus the base; compare uses it as the default older ref. context uses it only for risk.",
                     },
                     diffScope: {
                         type: "string",
@@ -379,7 +385,7 @@ function buildDocumentedKnodinTools() {
                     testScope: {
                         type: "string",
                         enum: ["all", "test", "production"],
-                        description: "search: include all, test-only, or production-only symbols.",
+                        description: "search/file_metrics: include all, test-only, or production-only files.",
                     },
                     offset: {
                         type: "number",
@@ -1305,6 +1311,45 @@ async function dispatchKnodinTool(args) {
         tokens: tokenBudget,
         items: itemBudget,
     };
+    let sharedEnvelope;
+    const sharedIndexEnvelope = () => {
+        if (sharedEnvelope)
+            return sharedEnvelope;
+        const configuration = loadSharedIndexConfig(repo);
+        const active = readSharedIndexProvenance(repo);
+        const lastRestoreAttempt = readSharedRestoreAttempt(repo);
+        if (active) {
+            sharedEnvelope = {
+                ...active,
+                enabled: configuration.state === "configured" ? configuration.config.enabled : false,
+                ...(lastRestoreAttempt ? { lastRestoreAttempt } : {}),
+            };
+            return sharedEnvelope;
+        }
+        const state = configuration.state === "not-configured"
+            ? "not-configured"
+            : configuration.state === "invalid"
+                ? "configuration-invalid"
+                : !configuration.config.enabled
+                    ? "disabled"
+                    : lastRestoreAttempt?.outcome === "failed"
+                        ? "restore-failed"
+                        : "local-only";
+        sharedEnvelope = {
+            schemaVersion: 1,
+            enabled: configuration.state === "configured" && configuration.config.enabled,
+            state,
+            source: "local-index",
+            ...(configuration.state === "configured"
+                ? { cache: "not-used", overlay: EMPTY_OVERLAY }
+                : {}),
+            ...(lastRestoreAttempt ? { lastRestoreAttempt } : {}),
+            ...(lastRestoreAttempt?.failureCategory
+                ? { failureCategory: lastRestoreAttempt.failureCategory }
+                : {}),
+        };
+        return sharedEnvelope;
+    };
     const observe = (output, op, minimal = false) => {
         const root = output;
         const budgetMeta = root.responseBudget;
@@ -1333,11 +1378,31 @@ async function dispatchKnodinTool(args) {
         return root;
     };
     const bounded = (result, op = String(operation), minimal = false) => {
+        const rootOperation = op.split(":")[0];
+        const includeSharedIndex = [
+            "status",
+            "context",
+            "query",
+            "explain",
+            "review",
+            "map",
+            "search",
+        ].includes(rootOperation);
+        const enriched = includeSharedIndex && result && typeof result === "object" && !Array.isArray(result)
+            ? { ...result, sharedIndex: sharedIndexEnvelope() }
+            : result;
         const key = `${op}${minimal ? ":minimal" : ""}`;
-        const output = applyResponseBudget(result, op, budget, RESPONSE_DEFAULTS[key] ?? RESPONSE_DEFAULTS.default);
+        const output = applyResponseBudget(enriched, op, budget, RESPONSE_DEFAULTS[key] ?? RESPONSE_DEFAULTS.default);
         return observe(output, op, minimal);
     };
     const graphRead = async (op, run, minimal = false) => {
+        const sharedConfiguration = loadSharedIndexConfig(repo);
+        if (!fs.existsSync(resolveDbPath(repo)) &&
+            sharedConfiguration.state === "configured" &&
+            sharedConfiguration.config.enabled) {
+            const { attemptOpportunisticSharedRestore } = await import("../shared-index/opportunistic.js");
+            await attemptOpportunisticSharedRestore(repo, engine);
+        }
         const health = await inspectGatewayGraphHealth(repo);
         if (!health.available)
             return bounded(health, op, minimal);
@@ -1597,6 +1662,8 @@ async function dispatchKnodinTool(args) {
                     includeDataFlow,
                 }
                 : undefined, {
+                base: pattern === "file_metrics" ? base : undefined,
+                testScope: pattern === "file_metrics" ? testScope : undefined,
                 minLines,
                 minComplexity,
                 kinds,

package/docs/CLI.md

@@ -6,6 +6,27 @@ options, numeric parsing, unknown-option rejection, and root or command help.
 `bin/cli.ts` dispatches the validated invocation to the existing product
 handlers so JSON output contracts and established commands remain compatible.
 
+## Shared indexes
+
+`knodin shared status` reports reviewed configuration, active graph provenance,
+the last bounded restore outcome, cache state, and freshness strategy without
+network access. Add `--probe` only for an explicit S3 credential/object check.
+
+`knodin shared pull` discovers signed branch pointers, selects the nearest
+locally proven ancestor, downloads or reuses an immutable digest-addressed
+artifact, reconciles the current checkout in a candidate database, deep-audits,
+and atomically promotes it. `--json` returns one result; `--jsonl` also streams
+lossless phase records. A failed pull leaves the previous graph usable.
+
+`knodin shared configure` writes the reviewed `.knodin/shared-index.yaml` trust
+configuration from explicit repository, S3, branch, and public-key options. It
+never reads or writes AWS credentials. `--disable` prevents automatic S3 access
+without deleting local graph or cache state.
+
+Index Hub publishers run `knodin index --clean` followed by
+`knodin shared publisher-metadata --json`; the latter stamps and emits the exact
+compatibility fingerprint used by clients.
+
 Run `knodin --help` for the root command inventory or append `--help` to any
 declared command path, for example:
 
@@ -59,6 +80,24 @@ dynamic names, reflection, computed aliases, and unsupported languages are
 reported rather than guessed. This is a static heuristic, not runtime reachability
 or an exploitability verdict.
 
+`knodin query file_metrics [--base <ref>] [--test-scope all|test|production]
+--format json` emits the versioned `schemas/file-metrics-v1.schema.json`
+contract. Each source file carries lexical line, import, route, and effect
+counts. With `--base`, knodin resolves the local merge-base and reads both trees
+directly from Git object storage; it does not check out or build a second graph.
+Added and removed files have null deltas, preventing consumers from mistaking
+either for an architectural improvement or regression. Output contains paths
+and integer counts only and supplies measurements, not thresholds or a verdict.
+
+```bash
+knodin query file_metrics --base origin/main --test-scope production --format json > metrics.json
+jq -e '[.files[] | select(.status == "changed") | .delta | to_entries[] | select(.value > 0)] | length == 0' metrics.json
+```
+
+An invalid ref or unresolvable merge-base fails non-zero. Binary and invalid
+UTF-8 files are skipped rather than reported as zero. The query is graph
+independent, so damaged graph state cannot become a misleading empty result.
+
 For support evidence, `knodin diagnostics enable|status|preview|archive|inspect|clear|disable`
 manages an explicit local failure journal and redacted gzip JSON bundles.
 Collection does not upload data. See `docs/DIAGNOSTICS.md` for retention,

package/docs/MCP.md

@@ -4,11 +4,23 @@ knodin exposes exactly one MCP tool named `knodin`. Capabilities such as
 context, explain, review, search, docs, doctor, repositories, and systems are
 operations of that gateway, not separate top-level tools.
 
+Shared-index support also stays inside that one gateway. Status, context,
+query, explain, review, map, and search responses include a bounded
+`sharedIndex` provenance object. `source: "shared-snapshot"` identifies origin;
+the independent freshness envelope says whether completed reconciliation and
+deep audit still match the checkout. AWS credentials, raw S3 exceptions, and
+source path lists are never returned.
+
 Use `operation: "query", pattern: "resource_reachability"` for the same bounded,
 cached, repo-wide TS/JS analysis as the CLI. It requires no symbol and retains
 the gateway's freshness refusal and response budgets; returned paths remain
 source-evidenced static heuristics with explicit coverage and omissions.
 
+Use `operation: "query", pattern: "file_metrics"`, optional `base`, and
+`testScope` for graph-independent, Git-backed file measurements. The versioned
+`fileMetrics` envelope contains paths and integer counts only—no source snippets,
+thresholds, or policy verdict.
+
 Use `operation: "evidence"` for deterministic `locate`, `outline`, `evidence`,
 and `expand` source delivery with a verified complete-file hash handshake and
 recoverable hard-budget continuations. See `docs/PROGRESSIVE-EVIDENCE.md`.

package/docs/SHARED-INDEX-CONTRACT.md

@@ -0,0 +1,132 @@
+# Shared-index contract v1
+
+This document freezes the wire and trust contract shared by the Knodin client
+and an Index Hub publisher. The normative machine schemas are:
+
+- `schemas/shared-index-config-v1.schema.json`
+- `schemas/shared-index-branch-pointer-v1.schema.json`
+- `schemas/shared-index-manifest-v1.schema.json`
+- `schemas/shared-index-provenance-v1.schema.json`
+
+The cross-implementation fixtures are in
+`src/__tests__/fixtures/shared-index-contract-v1.json`. Producers and consumers
+must validate the same fixtures before claiming v1 compatibility.
+
+## Trust and identity
+
+The reviewed `.knodin/shared-index.yaml` public key is the only trust root. A
+pointer, manifest, signature, object metadata, or S3 response cannot replace
+it. Configuration contains no credentials, role provisioning, endpoint
+override, portal data, Terraform data, or GitHub App data. `enabled: false`
+forbids automatic S3 access.
+
+Repository identity is canonicalized by removing an optional `https://` or
+`ssh://git@` transport prefix from a remote identity, removing one trailing
+dot from the host, lower-casing host/owner/name with the `en-US` locale,
+removing one `.git` suffix from the name, and NFC-normalizing every component.
+All three canonical components are compared. The S3 namespace is:
+
+`v1/<encoded-host>/<encoded-owner>/<encoded-repo>/`
+
+Each component and branch is encoded independently as UTF-8 RFC 3986 percent
+encoding with uppercase hex. `/`, spaces, Unicode, and `%` are therefore data,
+not separators. Branch patterns are either an exact Git ref name or a single
+terminal `/*` prefix pattern; matching is Unicode code-point exact after NFC
+normalization. A branch pointer never overrides local commit or ancestry truth.
+
+## Signed bytes
+
+Manifest JSON uses RFC 8785 JSON Canonicalization Scheme bytes: UTF-8, sorted
+object keys, no insignificant whitespace, and no trailing newline. The
+signature covers those raw manifest bytes, not a pre-hashed digest supplied by
+the caller. The algorithm is RSA-PSS with SHA-256, MGF1-SHA-256, and an exact
+32-byte salt. Public keys are PEM-encoded X.509 SubjectPublicKeyInfo. The
+`publicKeySha256` value is lower-case hex SHA-256 over its DER SPKI bytes.
+
+The pointer is untrusted discovery metadata. Before signature verification the
+client bounds and validates it, checks registration/repository identity,
+confines `manifestKey` beneath the canonical immutable prefix, downloads the
+manifest, and matches SHA-256 over the exact downloaded canonical bytes.
+The detached signature key is the manifest key with terminal `manifest.json`
+replaced by `manifest.sig`. Immutable snapshots use exactly
+`snapshots/<commit>/<inputFingerprint>/`; the graph key is exactly
+`graph.sqlite.zst` in that directory. Alternate filenames and nested paths are
+rejected even when they remain inside the repository prefix.
+
+## Compatibility
+
+V1 requires exact equality for database schema version, model ID and digest,
+parser bundle digest, index configuration digest, and prune-policy digest. The
+client's Knodin major version must equal the manifest major version and the
+client minor version must be greater than or equal to the manifest minor
+version. Pre-release versions are compatible only when the complete Knodin
+version is equal. Patch-version differences alone are compatible.
+
+`knodin shared publisher-metadata --json` is the single publisher/client
+implementation of these values. It also stamps `sharedIndexInputFingerprint`
+into the checkpointed publisher database so restore can bind SQLite metadata
+back to the signed manifest. In v1:
+
+- `modelDigest` hashes a canonical descriptor containing model ID, the pinned
+  immutable model revision, 384 dimensions, and the installed Transformers.js
+  version.
+- `parserBundleDigest` hashes parser policy version 1 and the installed
+  `web-tree-sitter`, `tree-sitter-wasms`, and `web-tree-sitter-sfapex`
+  versions.
+- `indexConfigDigest` hashes index-policy version 1, database schema, and
+  embedding dimensions.
+- `prunePolicyDigest` hashes prune-policy version 1, the sorted ignored
+  directory set, and the `.claude/worktrees` pattern.
+
+Any represented behavior change must increment its policy descriptor version.
+Publishers must not duplicate this logic in shell.
+
+## Bounds
+
+Limits include every byte received, not merely parsed content:
+
+| Object | Maximum bytes |
+| --- | ---: |
+| Branch pointer | 64 KiB |
+| Manifest | 256 KiB |
+| Detached signature | 16 KiB |
+| Compressed graph | 8 GiB |
+| Decompressed graph | 32 GiB |
+
+Compressed and decompressed sizes and SHA-256 digests must match the manifest
+exactly. The limits are ceilings; a deployment may configure stricter local
+bounds. Unknown schema versions and unknown fields fail closed. No failure
+before audited candidate promotion may modify the active graph.
+
+## Discovery, cache, and restore
+
+Discovery never fetches Git history. Exact local HEAD is preferred; otherwise
+only the nearest commit proven by the existing local object database to be an
+ancestor is usable. In shallow clones an unprovable commit is rejected, while
+an exact HEAD remains usable.
+
+Verified compressed artifacts are cached privately under
+`~/.knodin/shared-index-cache/v1/sha256/<compressedSha256>/graph.sqlite.zst`.
+The cache uses per-digest cross-process locks and leases, verifies size and
+digest before atomic installation, and never evicts a leased object. Every
+worktree gets a distinct writable candidate database. Decompression enforces
+the signed output size and digest, rejects trailing compressed data, validates
+the SQLite header and internal commit/schema/fingerprint, reconciles final Git
+and filesystem truth, deep-audits, and only then promotes.
+
+## Operator surfaces
+
+- `knodin shared status` is network-free. `--probe` is the explicit S3/auth
+  check.
+- `knodin shared pull` performs an explicit restore; `--jsonl` retains every
+  phase event.
+- `knodin shared configure` writes only `.knodin/shared-index.yaml` and never
+  accepts or stores AWS credentials. `--disable` preserves the graph and cache.
+- `knodin shared publisher-metadata --json` emits and stamps the frozen
+  compatibility metadata after watcher-free clean indexing.
+
+The single MCP gateway includes `sharedIndex` provenance in status, context,
+query, explain, review, map, and search responses before response budgeting.
+Snapshot provenance and freshness are separate claims. Failed attempts are
+recorded separately and never replace the provenance or bytes of the active
+graph.

package/docs/releases/0.8.5.md

@@ -0,0 +1,25 @@
+# knodin 0.8.5
+
+This release adds a versioned, fail-closed shared-index contract and safer
+large-repository lifecycle operations while preserving local-only defaults and
+the limitations recorded in the competitive roadmap.
+
+- Adds strict repository configuration, discovery-pointer, immutable-manifest,
+  signature, compatibility, and provenance contracts shared by publishers and
+  clients.
+- Adds native AWS default-credential-chain support, bounded S3 retrieval and
+  caching, verified decompression, snapshot selection, and recoverable restore.
+- Adds watcher-free candidate database creation, deep audit, reconciliation,
+  atomic promotion, rollback, and interrupted-promotion recovery.
+- Adds shared-index configuration, status, restore, and publisher operations to
+  the CLI and compact MCP gateway, plus a guarded publishing workflow.
+- Adds `file_metrics` with arbitrary Git-ref comparison for source-derived
+  architectural ratchets without a checked-in numeric baseline.
+- Hardens timing-sensitive structural-routing and behavioral-contract replay
+  under instrumented host load without weakening assertions or interactive
+  hang limits.
+
+Shared indexes remain explicitly opt-in. Reviewed repository configuration is
+the trust root, snapshots cannot replace it, and incompatible or ambiguous
+evidence fails closed. This remains an ordinary 0.x release, not GA or a claim
+of certified trusted distribution.

package/docs/releases/0.8.6.md

@@ -0,0 +1,10 @@
+# knodin 0.8.6
+
+This patch release makes bare `knodin status` adaptive and improves graceful repair cancellation.
+
+- Repositories with at most 50,000 indexed files receive the existing exact deep audit.
+- Larger repositories may reuse healthy persisted deep-audit evidence after a current Git freshness probe. The evidence is bound to the canonical repository, graph schema, knodin version, and SQLite/WAL fingerprint; `knodin status --deep` always bypasses it.
+- Human and JSON status output distinguish when the full audit ran from when freshness was most recently probed.
+- Deep status accepts an abort signal, embedding repair checks cancellation between batches, and cancelled candidate repair returns without starting another deep audit.
+
+Persisted evidence does not claim that every source file was inspected during the latest status invocation. Use `knodin status --deep` whenever an exact current filesystem/schema/orphan audit is required.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "knodin",
-	"version": "0.8.4",
+	"version": "0.8.6",
 	"description": "knodin — source-evidenced local code intelligence with known bounds. Stable identity, fresh evidence, truthful budgets, and recoverable bounded views.",
 	"license": "MIT",
 	"repository": {
@@ -42,6 +42,7 @@
 		"docs/REPOSITORIES-AND-WORKTREES.md",
 		"docs/RELEASE-0.3-EVIDENCE.md",
 		"docs/SIGNED-UPDATES.md",
+		"docs/SHARED-INDEX-CONTRACT.md",
 		"docs/releases/0.3.0.md",
 		"docs/releases/0.4.0.md",
 		"docs/releases/0.4.1.md",
@@ -60,6 +61,8 @@
 		"docs/releases/0.8.2.md",
 		"docs/releases/0.8.3.md",
 		"docs/releases/0.8.4.md",
+		"docs/releases/0.8.5.md",
+		"docs/releases/0.8.6.md",
 		"docs/assets/knodin-favicon.svg",
 		"docs/SYSTEMS-AND-RELATIONSHIPS.md",
 		"docs/TELEMETRY.md",
@@ -68,6 +71,10 @@
 		"roadmap/competitive-roadmap.md",
 		"schemas/release-attestation-v1.schema.json",
 		"schemas/support-bundle-v2.schema.json",
+		"schemas/shared-index-config-v1.schema.json",
+		"schemas/shared-index-branch-pointer-v1.schema.json",
+		"schemas/shared-index-manifest-v1.schema.json",
+		"schemas/shared-index-provenance-v1.schema.json",
 		"*.wasm"
 	],
 	"engines": {
@@ -138,14 +145,16 @@
 		"lint:fix": "biome check --write ."
 	},
 	"dependencies": {
-		"@huggingface/transformers": "^4.2.0",
+		"@aws-sdk/client-s3": "3.1106.0",
+		"@huggingface/transformers": "4.2.0",
 		"@modelcontextprotocol/sdk": "^1.30.0",
+		"@smithy/node-http-handler": "4.9.13",
 		"chokidar": "^5.0.0",
 		"commander": "15.0.0",
 		"gpt-tokenizer": "3.4.0",
 		"ora": "9.4.1",
 		"re2-wasm": "1.0.2",
-		"tree-sitter-wasms": "^0.1.13",
+		"tree-sitter-wasms": "0.1.13",
 		"web-tree-sitter": "0.20.8",
 		"web-tree-sitter-sfapex": "2.4.1",
 		"yaml": "2.9.0",