knodin 0.8.3 → 0.8.5

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

@@ -0,0 +1,209 @@
+import fs from "node:fs";
+import { Database } from "../engine/sqlite.js";
+import { acquireRepairLease } from "../repair-lease.js";
+import { decompressArtifactToCandidate } from "./artifact.js";
+import { SharedIndexCache } from "./cache.js";
+import { canonicalManifestBytes, sha256Hex } from "./contract.js";
+import { deriveSharedOverlay } from "./overlay.js";
+import { readSharedIndexProvenance, writeSharedIndexProvenance, writeSharedRestoreAttempt, } from "./provenance.js";
+import { SharedIndexError, } from "./s3-client.js";
+import { selectSharedSnapshot } from "./selection.js";
+function progress(listener, phase, message, extra = {}) {
+    try {
+        listener?.({ phase, timestamp: new Date().toISOString(), message, ...extra });
+    }
+    catch {
+        // Observability cannot change restore correctness.
+    }
+}
+function boundedFailure(error) {
+    if (error instanceof SharedIndexError)
+        return { category: error.category, reason: error.message.slice(0, 512) };
+    return { category: "unavailable", reason: "shared-index restore failed" };
+}
+function metadata(db, key) {
+    return (db.query("SELECT value FROM meta WHERE key = ?").get(key)?.value ??
+        null);
+}
+function validateSnapshotDatabase(databasePath, commit, inputFingerprint, databaseSchemaVersion) {
+    const db = new Database(databasePath, { readonly: true });
+    try {
+        const schema = db
+            .query("PRAGMA user_version")
+            .get()?.user_version;
+        if (schema !== databaseSchemaVersion)
+            throw new SharedIndexError("integrity", "shared-index database schema does not match signed manifest");
+        if (metadata(db, "lastIndexedHead") !== commit)
+            throw new SharedIndexError("integrity", "shared-index database commit does not match signed manifest");
+        const embeddedFingerprint = metadata(db, "sharedIndexInputFingerprint");
+        if (embeddedFingerprint !== inputFingerprint)
+            throw new SharedIndexError("integrity", "shared-index database compatibility does not match signed manifest");
+    }
+    finally {
+        db.close();
+    }
+}
+function stampCandidate(databasePath, values) {
+    const db = new Database(databasePath);
+    try {
+        db.run("BEGIN IMMEDIATE");
+        for (const [key, value] of Object.entries(values))
+            db.run("INSERT INTO meta(key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value", [key, value]);
+        db.run("COMMIT");
+        db.run("PRAGMA wal_checkpoint(TRUNCATE)");
+    }
+    catch (error) {
+        try {
+            db.run("ROLLBACK");
+        }
+        catch {
+            // The original database failure is authoritative.
+        }
+        throw error;
+    }
+    finally {
+        db.close();
+    }
+    for (const suffix of ["-wal", "-shm"])
+        fs.rmSync(`${databasePath}${suffix}`, { force: true });
+}
+export async function restoreSharedIndex(options) {
+    const startedAt = Date.now();
+    let candidate;
+    let lease;
+    let promoted = false;
+    let lifecycleLease;
+    try {
+        if (!options.config.enabled)
+            throw new SharedIndexError("configuration", "shared-index restore is disabled");
+        lifecycleLease = acquireRepairLease(options.repo, "shared pull");
+        progress(options.onProgress, "discovery", "Discovering shared snapshots");
+        const selection = await selectSharedSnapshot({
+            repo: options.repo,
+            config: options.config,
+            store: options.store,
+            clientCompatibility: options.clientCompatibility,
+            signal: options.signal,
+        });
+        const selected = selection.selected;
+        if (!selected) {
+            const first = selection.rejected[0];
+            throw new SharedIndexError(first?.category ?? "not-found", first?.reason ?? "no usable shared-index snapshot was found");
+        }
+        progress(options.onProgress, "verification", "Verified signed shared snapshot");
+        const cache = options.cache ?? new SharedIndexCache();
+        progress(options.onProgress, "download", "Resolving immutable shared artifact");
+        lease = await cache.acquire(options.store, selected.manifest, options.signal);
+        progress(options.onProgress, "download", lease.state === "hit" ? "Using verified cache entry" : "Verified shared artifact download", { bytes: selected.manifest.graph.compressedBytes });
+        candidate = await options.engine.createCandidate(options.repo, { empty: true });
+        progress(options.onProgress, "decompression", "Decompressing into candidate graph");
+        await decompressArtifactToCandidate({
+            repo: options.repo,
+            candidate,
+            artifact: lease,
+            manifest: selected.manifest,
+            signal: options.signal,
+        });
+        validateSnapshotDatabase(candidate.databasePath, selected.pointer.commit, selected.pointer.inputFingerprint, selected.manifest.compatibility.databaseSchemaVersion);
+        const overlay = deriveSharedOverlay(options.repo, selected.pointer.commit);
+        const restoredAt = new Date().toISOString();
+        stampCandidate(candidate.databasePath, {
+            sharedIndexRegistrationId: options.config.registrationId,
+            sharedIndexBaseCommit: selected.pointer.commit,
+            sharedIndexManifestDigest: sha256Hex(selected.manifestBytes),
+            sharedIndexInputFingerprint: selected.pointer.inputFingerprint,
+            sharedIndexEffectiveTreeFingerprint: overlay.effectiveTreeFingerprint,
+            sharedIndexOverlay: canonicalManifestBytes(overlay.counts).toString("utf8"),
+            sharedIndexCache: lease.state,
+            sharedIndexRestoredAt: restoredAt,
+        });
+        progress(options.onProgress, "reconciliation", "Reconciling local repository overlay", {
+            completed: 0,
+            total: overlay.changedPaths.length,
+        });
+        await options.engine.reconcileCandidate(candidate, options.repo, overlay.changedPaths, {
+            onProgress: (_phase, completed, message, details) => {
+                const elapsedMs = Math.max(1, Date.now() - startedAt);
+                const total = details?.phaseTotal;
+                const ratePerSecond = completed > 0 ? completed / (elapsedMs / 1000) : undefined;
+                progress(options.onProgress, "reconciliation", message, {
+                    completed,
+                    ...(total !== undefined ? { total } : {}),
+                    ...(ratePerSecond !== undefined ? { ratePerSecond } : {}),
+                    ...(ratePerSecond && total !== undefined && total > completed
+                        ? { etaSeconds: (total - completed) / ratePerSecond }
+                        : {}),
+                    elapsedMs,
+                });
+            },
+        });
+        progress(options.onProgress, "audit", "Deep-auditing reconciled candidate");
+        const audit = await options.engine.auditCandidate(candidate, { mode: "deep" });
+        if (!audit.healthy)
+            throw new SharedIndexError("integrity", `shared-index candidate audit failed (${audit.issues.slice(0, 8).join(",")})`);
+        progress(options.onProgress, "promotion", "Promoting verified candidate graph");
+        const promotion = await options.engine.promoteCandidate(candidate);
+        promoted = true;
+        const provenance = {
+            schemaVersion: 1,
+            enabled: true,
+            state: "restored-and-verified",
+            registrationId: options.config.registrationId,
+            baseCommit: selected.pointer.commit,
+            manifestDigest: sha256Hex(selected.manifestBytes),
+            source: "shared-snapshot",
+            cache: lease.state,
+            overlay: overlay.counts,
+            effectiveTreeFingerprint: overlay.effectiveTreeFingerprint,
+            restoredAt,
+        };
+        try {
+            writeSharedIndexProvenance(options.repo, provenance);
+            writeSharedRestoreAttempt(options.repo, {
+                schemaVersion: 1,
+                attemptedAt: new Date().toISOString(),
+                outcome: "restored",
+            });
+        }
+        catch {
+            // The promoted database contains the same provenance metadata and remains
+            // authoritative if the convenience sidecar cannot be written.
+        }
+        progress(options.onProgress, "completed", "Shared snapshot restored and verified");
+        return { restored: true, provenance, backupPath: promotion.backupPath };
+    }
+    catch (error) {
+        const failure = boundedFailure(error);
+        if (!promoted) {
+            try {
+                writeSharedRestoreAttempt(options.repo, {
+                    schemaVersion: 1,
+                    attemptedAt: new Date().toISOString(),
+                    outcome: "failed",
+                    failureCategory: failure.category,
+                });
+            }
+            catch {
+                // A diagnostic write cannot alter active graph preservation.
+            }
+        }
+        progress(options.onProgress, "failed", failure.reason);
+        return {
+            restored: false,
+            ...failure,
+            activeProvenance: readSharedIndexProvenance(options.repo),
+        };
+    }
+    finally {
+        lease?.release();
+        if (candidate && !promoted) {
+            try {
+                await options.engine.discardCandidate(candidate);
+            }
+            catch {
+                // Candidate cleanup never justifies touching the active graph.
+            }
+        }
+        lifecycleLease?.release();
+    }
+}

package/dist/src/shared-index/s3-client.js

@@ -0,0 +1,124 @@
+import { Readable } from "node:stream";
+import { GetObjectCommand, HeadObjectCommand, S3Client, } from "@aws-sdk/client-s3";
+import { NodeHttpHandler } from "@smithy/node-http-handler";
+import { sharedRepositoryPrefix } from "./contract.js";
+export class SharedIndexError extends Error {
+    category;
+    constructor(category, message) {
+        super(message);
+        this.name = "SharedIndexError";
+        this.category = category;
+    }
+}
+function classified(error) {
+    if (error instanceof SharedIndexError)
+        return error;
+    const record = typeof error === "object" && error !== null ? error : {};
+    const name = typeof record.name === "string" ? record.name : "";
+    const status = Number(record.$metadata?.httpStatusCode);
+    if ([
+        "CredentialsProviderError",
+        "TokenProviderError",
+        "ExpiredToken",
+        "InvalidAccessKeyId",
+        "UnrecognizedClientException",
+    ].includes(name))
+        return new SharedIndexError("authentication", "shared-index AWS authentication failed");
+    if (name === "AccessDenied" || name === "AccessDeniedException" || status === 403)
+        return new SharedIndexError("authorization", "shared-index object access was denied");
+    if (["NoSuchKey", "NotFound", "NoSuchBucket"].includes(name) || status === 404)
+        return new SharedIndexError("not-found", "shared-index object was not found");
+    if (name === "AbortError" || name === "TimeoutError" || name === "RequestTimeout")
+        return new SharedIndexError("timeout", "shared-index object request timed out or was cancelled");
+    return new SharedIndexError("unavailable", "shared-index object service is unavailable");
+}
+function requestSignal(signal, timeoutMs) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+function readableBody(body) {
+    if (body instanceof Readable)
+        return body;
+    if (body && typeof body === "object" && "transformToWebStream" in body) {
+        const stream = body.transformToWebStream();
+        return Readable.fromWeb(stream);
+    }
+    throw new SharedIndexError("unavailable", "shared-index object response had no readable body");
+}
+export class AwsSharedObjectStore {
+    client;
+    bucket;
+    prefix;
+    constructor(config, client) {
+        if (!config.enabled)
+            throw new SharedIndexError("configuration", "shared-index object access is disabled");
+        this.bucket = config.aws.bucket;
+        this.prefix = sharedRepositoryPrefix(config.repository);
+        const clientConfig = {
+            region: config.aws.region,
+            maxAttempts: 3,
+            requestHandler: new NodeHttpHandler({
+                connectionTimeout: 5_000,
+                requestTimeout: 30_000,
+            }),
+        };
+        // Omitting `credentials` intentionally selects the SDK's native Node default
+        // provider chain (environment, shared config/SSO, web identity, ECS, EC2).
+        this.client = client ?? new S3Client(clientConfig);
+    }
+    key(key) {
+        if (!key.startsWith(this.prefix) ||
+            key.length <= this.prefix.length ||
+            key.includes("\\") ||
+            key.split("/").some((segment) => segment === "" || segment === "." || segment === ".."))
+            throw new SharedIndexError("configuration", "shared-index object key escaped its repository prefix");
+        return key;
+    }
+    async head(key, options = {}) {
+        try {
+            const response = await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: this.key(key) }), { abortSignal: requestSignal(options.signal, options.timeoutMs ?? 15_000) });
+            const bytes = Number(response.ContentLength);
+            if (!Number.isSafeInteger(bytes) || bytes < 0)
+                throw new SharedIndexError("integrity", "shared-index object size metadata is invalid");
+            return {
+                bytes,
+                ...(typeof response.ETag === "string" ? { etag: response.ETag } : {}),
+            };
+        }
+        catch (error) {
+            throw classified(error);
+        }
+    }
+    async get(key, limits) {
+        if (!Number.isSafeInteger(limits.maxBytes) || limits.maxBytes <= 0)
+            throw new SharedIndexError("configuration", "shared-index download limit is invalid");
+        try {
+            const response = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: this.key(key) }), { abortSignal: requestSignal(limits.signal, limits.timeoutMs ?? 30_000) });
+            const declared = Number(response.ContentLength);
+            if (Number.isFinite(declared) && declared > limits.maxBytes)
+                throw new SharedIndexError("integrity", "shared-index object exceeds the download limit");
+            const source = readableBody(response.Body);
+            let received = 0;
+            return Readable.from((async function* bounded() {
+                try {
+                    for await (const chunk of source) {
+                        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                        received += bytes.length;
+                        if (received > limits.maxBytes)
+                            throw new SharedIndexError("integrity", "shared-index object exceeded the download limit");
+                        yield bytes;
+                    }
+                }
+                finally {
+                    source.destroy();
+                }
+            })());
+        }
+        catch (error) {
+            throw classified(error);
+        }
+    }
+}
+export function createSharedObjectStore(config, client) {
+    return config.enabled ? new AwsSharedObjectStore(config, client) : null;
+}

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,