knodin 0.12.2 → 0.13.0

package/README.md

@@ -150,7 +150,7 @@ Start broad, inspect the likely change surface, then review the actual diff:
 
 ```bash
 # Orient on an unfamiliar checkout
-knodin context
+knodin context "understand this checkout"
 
 # Explain a symbol with source and relationships
 knodin explain createServer
@@ -170,6 +170,21 @@ knodin map
 knodin pack createServer --max-tokens 4000
 ```
 
+For a task that needs an implementation and its dependencies:
+
+```bash
+knodin context "find code that persists an order" --implementations --json
+knodin context "rename persist" --symbol persist --file src/storage.ts --json
+knodin evidence expand --files src/storage.ts --items 100 --json
+```
+
+Discovery returns candidates for you to select; investigation collects source,
+callers, importers, tests, and impact for the selected identity. Evidence bundles
+page exact source and issue reusable per-file receipts after complete delivery.
+Ambiguity, incomplete coverage, and budget limits stay visible. See the
+[CLI guide](docs/CLI.md#task-discovery-and-investigation) and
+[evidence protocol](docs/PROGRESSIVE-EVIDENCE.md#graph-backed-file-bundles).
+
 If freshness or lifecycle checks fail:
 
 ```bash

package/dist/bin/cli.js

@@ -20,6 +20,10 @@ import { inspectClaudeAgentHooks, installClaudeAgentHooks, uninstallClaudeAgentH
 import { detectSupportedAgents, parseInitScope, } from "../src/agent-integration.js";
 import { refreshExternalGraphArtifacts, writeArtifactRefreshRecord, } from "../src/artifact-refresh.js";
 import { formatBackupHuman, installBackupRetention, listBackups, maybeRunOpportunisticRetention, pruneBackups, removeBackupRetention, retentionDoctor, retentionStatus, runInstalledRetention, } from "../src/backup-retention.js";
+import { ClassConsumerQueryError, } from "../src/class-consumer-contract.js";
+import { readClassConsumerCursor } from "../src/class-consumer-cursor.js";
+import { validateClassConsumerDelivery } from "../src/class-consumer-delivery.js";
+import { finalizeClassConsumerPage } from "../src/class-consumer-page.js";
 import { checkIndexed, extractPositionals, extractRepoFlag, parseReviewArgs, planIndex, resolveCliRuntimeCommand, resolveRepo, } from "../src/cli-args.js";
 import { helpCommandPath, parseCliInvocation, renderCliHelp } from "../src/cli-model.js";
 import { buildKnodinContext } from "../src/context.js";
@@ -31,19 +35,24 @@ import { createEngine, describeThrown, KNODIN_SCHEMA_VERSION, REPO_WIDE_QUERY_PA
 import { runSeal } from "../src/engine/seal-command.js";
 import { runSealedQuery } from "../src/engine/sealed-query.js";
 import { resolveDbPath } from "../src/engine/state-paths.js";
+import { deliverEvidenceBundle } from "../src/evidence-bundle.js";
+import { createEvidenceGraphAdapter } from "../src/evidence-graph.js";
 import { diagnoseFailure, } from "../src/failure-diagnosis.js";
 import { gitExecutable } from "../src/git-executable.js";
 import { decorateGraphQueryResult, inspectGraphQueryHealth } from "../src/graph-query-health.js";
+import { findImplementationCandidates } from "../src/implementation-search.js";
 import { createIndexActivityReporter } from "../src/index-activity.js";
+import { indexCoverageCore, indexCoverageNotice, indexCoverageSnapshot, } from "../src/index-coverage-read.js";
 import { InitializationHealthError, initializeRepository, inspectRepositoryIntegrationStatus, readRepositoryIntegrationConfig, refreshFromGitEvent, repairLifecycleRouting, } from "../src/init.js";
 import { createInitProgressRenderer } from "../src/init-progress.js";
+import { buildTaskInvestigation } from "../src/investigation.js";
 import { attachLifecycleHealth, attachRepairLifecycle } from "../src/lifecycle-health.js";
 import { acknowledgeUpdateFailure, queryOwnerAvailability, readManagerUpdateState, readUpdateJournal, resolveManagerOwnership, setManualPin, unpinUpdate, updateAttention, writeManagerUpdateState, } from "../src/manager-update.js";
 import { addMirror, listMirrors, refreshMirror, removeMirror } from "../src/mirror.js";
 import { compressOutput, compressOutputFile, deleteOutputArtifact, readOutputArtifact, } from "../src/output-compression.js";
 import { clearTelemetry, exportTelemetry, readTelemetryRecords, telemetryStatus, writeTelemetryReport, } from "../src/output-telemetry.js";
 import { auditPullRequests } from "../src/pr-triage.js";
-import { deliverProgressiveEvidence, } from "../src/progressive-evidence.js";
+import { deliverProgressiveEvidence, evidenceHandleSecret, } from "../src/progressive-evidence.js";
 import { acquireRepairLease } from "../src/repair-lease.js";
 import { createRepairPlan, createRepairProgressRenderer, parseRepairCliArgs, resolveRepairProgressMode, serializeRepairJsonlRecord, } from "../src/repair-progress.js";
 import { runRepositoryInitializationProcess } from "../src/repository-init-process.js";
@@ -161,15 +170,21 @@ function formatSemanticGap(readiness) {
 }
 function formatIndexHuman(result) {
     const semantic = formatSemanticGap(result.semanticReadiness);
+    const scope = formatIndexCoverageHuman(result.indexCoverage);
     if (result.indexed.length === 0 && result.unchanged.length > 0) {
         const noun = result.unchanged.length === 1 ? "file" : "files";
-        return `Graph already current: ${result.unchanged.length.toLocaleString()} requested ${noun} needed no work; health verified.${semantic}\n`;
+        return `Graph already current: ${result.unchanged.length.toLocaleString()} requested ${noun} needed no work; health verified.${semantic}\n${scope}\n`;
     }
     const unchanged = result.unchanged.length > 0
         ? `; ${result.unchanged.length.toLocaleString()} already current`
         : "";
     const noun = result.indexed.length === 1 ? "file" : "files";
-    return `Index complete: ${result.indexed.length.toLocaleString()} ${noun} indexed${unchanged}; graph health verified.${semantic}\n`;
+    return `Index complete: ${result.indexed.length.toLocaleString()} ${noun} indexed${unchanged}; graph health verified.${semantic}\n${scope}\n`;
+}
+function formatIndexCoverageHuman(coverage) {
+    if (!coverage)
+        return "Local graph index coverage is unknown; a negative graph answer does not establish absence.";
+    return `Local graph index coverage: ${coverage.mode}; intent ${coverage.intentState}; repository inventory complete: ${coverage.repositoryComplete}. ${indexCoverageNotice(coverage) ?? "Inventory extent does not establish complete static relationships or runtime use."}`;
 }
 function formatIndexVerificationError(result) {
     const firstIssue = result.verification.missing.files[0] ?? result.verification.missing.records[0];
@@ -414,7 +429,7 @@ function formatStatusHuman(result) {
     const indexedCounts = result.coverage.countsUnknown
         ? "indexed and symbol counts unknown; the graph could not be read"
         : `${result.coverage.indexedFiles} indexed files, ${result.coverage.filesWithSymbols} files with symbols`;
-    const coverage = `${result.coverage.sourceFiles} source files, ${indexedCounts}${formatCoverageGaps(result.coverage.skipped)}${mirrorNote}${semanticNote}`;
+    const coverage = `${result.coverage.sourceFiles} source files, ${indexedCounts}${formatCoverageGaps(result.coverage.skipped)}${mirrorNote}${semanticNote}. ${formatIndexCoverageHuman(result.indexCoverage)}`;
     if (result.status === "indexing" && result.activity) {
         const count = result.activity.phaseTotal === undefined
             ? ""
@@ -1537,6 +1552,8 @@ async function main() {
         return attemptOpportunisticSharedRestore(repo, engine);
     };
     let result;
+    let finalizedClassConsumer = false;
+    let classConsumerErrorContract;
     let repairOutput;
     let repairWasPlan = false;
     let repairWasLifecycle = false;
@@ -1555,7 +1572,7 @@ async function main() {
             process.exitCode = 1;
             return verified;
         }
-        return decorateGraphQueryResult(value, verified.state, verified.graph.freshness);
+        return decorateGraphQueryResult(value, verified.state, verified.graph.freshness, verified.graph.indexCoverage, health.graph.indexCoverage);
     };
     switch (cmd) {
         case "shared": {
@@ -1830,10 +1847,11 @@ async function main() {
             }
             const freshness = status.freshness?.state ?? "unknown";
             const cacheKey = JSON.stringify({
-                schemaVersion: 1,
+                schemaVersion: 2,
                 head: status.freshness?.currentHead,
                 fingerprint: status.freshness?.workingTree?.indexedFingerprint,
                 generation: status.indexGeneration,
+                indexCoverage: indexCoverageCore(status.indexCoverage),
                 budgets: [600, 8192, 12],
             });
             const cacheEligible = canUseSessionContextCache(status.status, freshness);
@@ -1848,7 +1866,11 @@ async function main() {
                 cacheHit = false;
                 try {
                     const context = await buildKnodinContext(engine, "Orient this coding session", repo, undefined, []);
-                    text = renderSessionContext(context, freshness);
+                    const verified = await engine.status(repo, { audit: "cached" });
+                    if (indexCoverageSnapshot(status.indexCoverage) !==
+                        indexCoverageSnapshot(verified.indexCoverage))
+                        throw new Error("Index coverage changed during session context generation");
+                    text = renderSessionContext(context, freshness, verified.indexCoverage);
                     writeSessionContextCache(repo, cacheKey, text);
                 }
                 catch {
@@ -2687,6 +2709,24 @@ async function main() {
         case "evidence": {
             const level = rest[0];
             const file = rest[1];
+            const files = selectorValue("--files")?.split(",");
+            if (files) {
+                if (level !== "evidence" && level !== "expand")
+                    throw new Error("Evidence bundles require evidence or expand level");
+                if (file && !file.startsWith("--"))
+                    throw new Error("Choose a file or --files, not both");
+                result = await deliverEvidenceBundle({
+                    repo,
+                    files,
+                    level,
+                    continuation: selectorValue("--continuation"),
+                    alreadyPresent: selectorValue("--already-present")?.split(","),
+                    byteLimit: responseBudget.bytes,
+                    tokenLimit: responseBudget.tokens,
+                    itemLimit: responseBudget.items,
+                }, createEvidenceGraphAdapter(engine));
+                break;
+            }
             if (!file || !["locate", "outline", "evidence", "expand"].includes(level))
                 throw new Error("knodin evidence requires locate|outline|evidence|expand <file>");
             result = deliverProgressiveEvidence({
@@ -2717,7 +2757,7 @@ async function main() {
                 ? ""
                 : (rest[1] ?? "");
             if (!pattern) {
-                process.stderr.write("knodin query requires a <pattern> (lsp_diagnostics|lsp_definitions|lsp_declarations|lsp_implementations|callers_of|callees_of|imports_of|importers_of|import_cycles|file_summary|file_metrics|batch_outline|project_overview|shortest_path|cross_substrate_path|inheritors_of|structural_implementations_of|tests_for|impact|dead_code|large_functions|large_files|rename_preview|flows|flow_of|stats|traverse|feature_path|flow_analysis|resource_reachability|knowledge_gaps|surprising_connections|suggested_questions|architecture_overview|community|triggers_of|publishers_of|listeners_of|handlers_of|endpoints_for|consumers_of|children_of|federated_repos|mcp_tools|api_contract_mismatches)\n");
+                process.stderr.write("knodin query requires a <pattern> (lsp_diagnostics|lsp_definitions|lsp_declarations|lsp_implementations|callers_of|callees_of|imports_of|importers_of|import_cycles|file_summary|file_metrics|batch_outline|project_overview|shortest_path|cross_substrate_path|inheritors_of|structural_implementations_of|tests_for|impact|dead_code|large_functions|large_files|rename_preview|flows|flow_of|stats|traverse|feature_path|flow_analysis|resource_reachability|knowledge_gaps|surprising_connections|suggested_questions|architecture_overview|community|triggers_of|publishers_of|listeners_of|handlers_of|endpoints_for|consumers_of|class_consumers|children_of|federated_repos|mcp_tools|api_contract_mismatches)\n");
                 process.exit(1);
             }
             const directionValue = selectorValue("--direction");
@@ -2788,6 +2828,82 @@ async function main() {
                 process.exitCode = 1;
                 break;
             }
+            if (pattern === "class_consumers") {
+                if (queryLimitRaw && Number(queryLimitRaw) > 1000)
+                    throw new Error("class_consumers --limit must not exceed 1000 sites");
+                if (["--offset", "--kinds", "--relations", "--direction", "--depth", "--exclude-tests"].some((flag) => rest.includes(flag)))
+                    throw new Error("class_consumers supports --test-scope/--path and --continuation, not offset/kinds/relations/direction/depth/exclude-tests");
+                const secret = evidenceHandleSecret(repo).secret;
+                const token = selectorValue("--continuation");
+                const cursor = token ? readClassConsumerCursor(token, secret) : undefined;
+                const request = {
+                    symbol: target,
+                    selector,
+                    testScope: (testScopeValue ?? "all"),
+                    path: selectorValue("--path"),
+                    limit: queryLimitRaw ? Number(queryLimitRaw) : 100,
+                    ...(cursor
+                        ? {
+                            after: cursor.after,
+                            expectedQueryDigest: cursor.queryDigest,
+                            expectedSnapshotDigest: cursor.snapshotDigest,
+                        }
+                        : {}),
+                };
+                try {
+                    const page = await engine.queryClassConsumers(repo, request);
+                    // Defer maintenance, not the audit, until a later eligible status or close.
+                    const verified = await inspectGraphQueryHealth(repo, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached", checkpoint: "defer" })));
+                    if (!verified.available) {
+                        result = verified;
+                        process.exitCode = 1;
+                        break;
+                    }
+                    await validateClassConsumerDelivery(page, request, (next) => engine.queryClassConsumers(repo, next));
+                    result = finalizeClassConsumerPage(page, {
+                        secret,
+                        budget: responseBudget,
+                        decorate: (candidate) => decorateGraphQueryResult(candidate, verified.state, undefined, verified.graph.indexCoverage, queryHealth?.available ? queryHealth.graph.indexCoverage : undefined),
+                    });
+                    finalizedClassConsumer = true;
+                }
+                catch (error) {
+                    if (error instanceof ClassConsumerQueryError &&
+                        [
+                            "CLASS_CONSUMER_TARGET_NOT_FOUND",
+                            "CLASS_CONSUMER_TARGET_AMBIGUOUS",
+                            "CLASS_CONSUMER_TARGET_CAPABILITY_MISSING",
+                        ].includes(error.code)) {
+                        result = {
+                            available: false,
+                            status: "unavailable",
+                            pattern,
+                            targetResolution: error.code === "CLASS_CONSUMER_TARGET_CAPABILITY_MISSING"
+                                ? "capability-missing"
+                                : error.code === "CLASS_CONSUMER_TARGET_NOT_FOUND"
+                                    ? "not-found"
+                                    : "ambiguous",
+                            code: error.code,
+                            error: error.message,
+                            candidates: error.candidates,
+                            ...(queryHealth?.available
+                                ? {
+                                    indexCoverage: queryHealth.graph.indexCoverage,
+                                    freshness: queryHealth.graph.freshness,
+                                }
+                                : {}),
+                        };
+                        classConsumerErrorContract = {
+                            code: error.code,
+                            targetResolution: result.targetResolution,
+                        };
+                        process.exitCode = 1;
+                    }
+                    else
+                        throw error;
+                }
+                break;
+            }
             result = await engine.query(pattern, target, repo, to, queryLimitRaw ? Number(queryLimitRaw) : undefined, depth, detailLevel, selector, pattern === "impact"
                 ? {
                     mode: selectorValue("--impact-mode") === "file" ? "file" : "symbol",
@@ -2847,12 +2963,12 @@ async function main() {
                     process.exitCode = 1;
                     break;
                 }
-                result = decorateGraphQueryResult(result, verifiedQueryHealth.state, verifiedQueryHealth.graph.freshness);
+                result = decorateGraphQueryResult(result, verifiedQueryHealth.state, verifiedQueryHealth.graph.freshness, verifiedQueryHealth.graph.indexCoverage, queryHealth.graph.indexCoverage);
             }
             // A target that does not exist is operator error, not a negative
             // answer, so it exits non-zero like an unavailable graph rather than
             // like real dead code (KNODIN-28). `resolved` with zero rows keeps
-            // exit 0: the symbol exists and genuinely has no callers.
+            // exit 0: no callers were found within the reported index coverage.
             if (result?.targetResolution === "not-found")
                 process.exitCode = 1;
             break;
@@ -3034,7 +3150,26 @@ async function main() {
                 process.stderr.write('knodin context requires a "<task>" description\n');
                 process.exit(1);
             }
-            result = await graphRead(() => buildKnodinContext(engine, task, repo, rest[1]));
+            const symbol = selectorValue("--symbol");
+            if (rest.includes("--implementations")) {
+                if (symbol)
+                    throw new Error("Choose --implementations or --symbol, not both");
+                result = await graphRead(() => findImplementationCandidates(engine, repo, {
+                    task,
+                    limit: selectorValue("--limit") ? Number(selectorValue("--limit")) : undefined,
+                    offset: selectorValue("--offset") ? Number(selectorValue("--offset")) : undefined,
+                }));
+                break;
+            }
+            result = await graphRead(() => symbol
+                ? buildTaskInvestigation(engine, repo, {
+                    task,
+                    symbol,
+                    ...selector,
+                    limit: selectorValue("--limit") ? Number(selectorValue("--limit")) : undefined,
+                    depth: selectorValue("--depth") ? Number(selectorValue("--depth")) : undefined,
+                })
+                : buildKnodinContext(engine, task, repo, rest[1]));
             break;
         }
         default:
@@ -3042,6 +3177,8 @@ async function main() {
             process.exit(1);
     }
     await engine.close();
+    if (result?.available === false)
+        process.exitCode = 1;
     if (agentEventOutput) {
         if (result !== null && result !== undefined)
             process.stdout.write(`${JSON.stringify(result)}\n`);
@@ -3050,9 +3187,31 @@ async function main() {
     if (statusWasWatched)
         return;
     const fileMetricsOutput = cmd === "query" && rest[0] === "file_metrics";
-    const boundedResult = applyResponseBudget(result, cmd, responseBudget, fileMetricsOutput
-        ? { bytes: 16_777_216, tokens: 4_194_304, items: 100_000 }
-        : { bytes: 65_536, tokens: 16_384, items: 100 });
+    // The bundle protocol budgets its signed manifest, source and continuation together.
+    // Generic post-truncation would invalidate that recoverable envelope.
+    const evidenceBundle = cmd === "evidence" && selectorValue("--files") !== undefined;
+    const boundedResult = evidenceBundle || finalizedClassConsumer
+        ? result
+        : applyResponseBudget(result, cmd === "query" && rest[0] === "flow_analysis" ? "query:flow_analysis" : cmd, responseBudget, fileMetricsOutput
+            ? { bytes: 16_777_216, tokens: 4_194_304, items: 100_000 }
+            : { bytes: 65_536, tokens: 16_384, items: 100 });
+    if (classConsumerErrorContract) {
+        const delivered = boundedResult;
+        if (delivered.code !== classConsumerErrorContract.code ||
+            delivered.targetResolution !== classConsumerErrorContract.targetResolution ||
+            delivered.available !== false ||
+            delivered.status !== "unavailable")
+            throw new Error("Response budget cannot preserve the class-consumer error contract; increase the budget.");
+    }
+    if (cmd === "query" && rest[0] === "inheritors_of") {
+        const qualification = result
+            ?.inheritanceQuery;
+        const delivered = boundedResult
+            ?.inheritanceQuery;
+        if (qualification &&
+            ["version", "mode", "partial", "truncated", "apex"].some((key) => delivered?.[key] !== qualification[key]))
+            throw new Error("Response budget cannot preserve the inheritance qualification; increase the budget.");
+    }
     const finalExitCode = Math.max(Number(process.exitCode ?? 0), repairExitCode);
     if (cmd === "init" && !jsonOutput) {
         process.stdout.write(formatInitHuman(boundedResult));

package/dist/src/agent-events.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { indexCoverageCore, indexCoverageNotice } from "./index-coverage-read.js";
 import { countOutputTokens } from "./output-telemetry.js";
 import { appendSessionEvent, } from "./session-telemetry.js";
 export const SESSION_CONTEXT_BUDGET_LINE = "Budget: at most 600 tokens, 8 KiB, 12 items.";
@@ -81,23 +82,40 @@ export function writeSessionContextCache(repo, key, text) {
 export function canUseSessionContextCache(status, freshness) {
     return status === "healthy" && freshness === "fresh";
 }
-export function renderSessionContext(context, freshness) {
+export function renderSessionContext(context, freshness, coverage) {
     const list = (values, render) => (values ?? []).slice(0, 3).map(render).join(", ") || "none reported";
-    let text = [
+    const header = [
         "## knodin session context",
         `Graph evidence: ${freshness}. Treat stale or unavailable evidence as incomplete.`,
         SESSION_CONTEXT_BUDGET_LINE,
-        `Repository: ${context.stats?.files ?? "?"} files, ${context.stats?.symbols ?? "?"} symbols.`,
+        `Index coverage: ${JSON.stringify(indexCoverageCore(coverage) ?? { mode: "unknown", repositoryComplete: false, negativeScope: "unknown" })}`,
+        indexCoverageNotice(coverage) ??
+            (coverage
+                ? "Inventory extent does not prove complete relationships or runtime use."
+                : "Index coverage is unknown; negatives do not establish repository-wide absence."),
+    ];
+    const details = [
+        `Indexed scope: ${context.stats?.files ?? "?"} files, ${context.stats?.symbols ?? "?"} symbols.`,
         `Subsystems: ${list(context.communities, (value) => `${value.name} (${value.size})`)}`,
         `Hubs: ${list(context.hubs, (value) => `${value.symbol} (${value.degree})`)}`,
         `Flows: ${list(context.flows, (value) => value.symbol ?? "unnamed")}`,
         `Suggested next operation: ${context.suggestedOperation ?? "context"} (heuristic only).`,
         "Use exact source evidence and preserve ambiguity, freshness, omissions, and response budgets.",
-    ].join("\n");
-    while ((countOutputTokens(text) > 600 || Buffer.byteLength(text) > 8192) && text.includes("\n")) {
-        text = `${text.slice(0, text.lastIndexOf("\n"))}\nContext truncated to the configured session budget.`;
+    ];
+    let truncated = false;
+    for (;;) {
+        const text = [
+            ...header,
+            ...details,
+            ...(truncated ? ["Context truncated to the configured session budget."] : []),
+        ].join("\n");
+        if (countOutputTokens(text) <= 600 && Buffer.byteLength(text) <= 8192)
+            return text;
+        if (details.length === 0)
+            throw new RangeError("Session context budget cannot preserve index coverage");
+        details.pop();
+        truncated = true;
     }
-    return text;
 }
 export function recordClaudeLifecycleEvent(repo, event, payload) {
     const sessionId = payload.session_id;

package/dist/src/authenticated-cursor.js

@@ -0,0 +1,81 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+export const MAX_CURSOR_PAYLOAD_BYTES = 4096;
+export const MAX_AUTHENTICATED_CURSOR_LENGTH = 6144;
+const DOMAIN = "knodin:authenticated-cursor:v1\0";
+function checkParameters(secret, prefix) {
+    if (!Buffer.isBuffer(secret) || secret.length !== 32)
+        throw new TypeError("cursor signing key must be 32 bytes");
+    if (!/^[a-z][a-z0-9]{1,15}$/.test(prefix))
+        throw new TypeError("invalid cursor prefix");
+}
+function signature(secret, prefix, body) {
+    return createHmac("sha256", secret)
+        .update(DOMAIN)
+        .update(prefix)
+        .update("\0")
+        .update(body)
+        .digest();
+}
+function isRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * Authentication only, not encryption, schema validation or a freshness lease.
+ * Callers supply the existing per-repository evidence secret and a distinct
+ * protocol prefix; they must validate payload shape and current query/snapshot.
+ * Sign only the boundary of rows actually delivered after response budgeting.
+ */
+export function signAuthenticatedCursor(value, secret, prefix) {
+    checkParameters(secret, prefix);
+    let serialized;
+    try {
+        if (!isRecord(value))
+            throw new Error("cursor payload is not a record");
+        serialized = JSON.stringify(value);
+        if (typeof serialized !== "string" || !isRecord(JSON.parse(serialized)))
+            throw new Error("serialized cursor payload is not a record");
+    }
+    catch {
+        throw new TypeError("cursor payload must be a serializable JSON object");
+    }
+    if (Buffer.byteLength(serialized) > MAX_CURSOR_PAYLOAD_BYTES)
+        throw new RangeError("cursor payload exceeds its byte limit");
+    const body = Buffer.from(serialized).toString("base64url");
+    return `${prefix}.${body}.${signature(secret, prefix, body).toString("base64url")}`;
+}
+export function verifyAuthenticatedCursor(value, secret, prefix) {
+    checkParameters(secret, prefix);
+    const invalid = () => new Error("invalid authenticated cursor");
+    if (typeof value !== "string" || value.length > MAX_AUTHENTICATED_CURSOR_LENGTH)
+        throw invalid();
+    const parts = value.split(".");
+    if (parts.length !== 3 || parts[0] !== prefix)
+        throw invalid();
+    const [, body, encodedSignature] = parts;
+    if (!/^[A-Za-z0-9_-]+$/.test(body) || !/^[A-Za-z0-9_-]+$/.test(encodedSignature))
+        throw invalid();
+    const actual = Buffer.from(encodedSignature, "base64url");
+    const expected = signature(secret, prefix, body);
+    if (actual.length !== expected.length ||
+        actual.toString("base64url") !== encodedSignature ||
+        !timingSafeEqual(actual, expected))
+        throw invalid();
+    const bytes = Buffer.from(body, "base64url");
+    if (bytes.length > MAX_CURSOR_PAYLOAD_BYTES || bytes.toString("base64url") !== body)
+        throw invalid();
+    const text = bytes.toString("utf8");
+    if (!Buffer.from(text).equals(bytes))
+        throw invalid();
+    try {
+        const payload = JSON.parse(text);
+        if (isRecord(payload))
+            return payload;
+    }
+    catch {
+        // Never echo untrusted cursor contents or decoder error details.
+    }
+    throw invalid();
+}

package/dist/src/class-consumer-contract.js

@@ -0,0 +1,18 @@
+/** Matches SQLite TEXT COLLATE BINARY for canonical UTF-8 paths and ASCII role names. */
+export function compareClassConsumerKeys(left, right) {
+    return (Buffer.compare(Buffer.from(left.file), Buffer.from(right.file)) ||
+        left.startByte - right.startByte ||
+        left.endByte - right.endByte ||
+        Buffer.compare(Buffer.from(left.kind), Buffer.from(right.kind)));
+}
+/** Adapters translate these typed failures; never manufacture a successful target identity. */
+export class ClassConsumerQueryError extends Error {
+    code;
+    candidates;
+    constructor(code, message, candidates = []) {
+        super(message);
+        this.code = code;
+        this.candidates = candidates;
+        this.name = "ClassConsumerQueryError";
+    }
+}

package/dist/src/class-consumer-cursor.js

@@ -0,0 +1,91 @@
+import { signAuthenticatedCursor, verifyAuthenticatedCursor } from "./authenticated-cursor.js";
+import { canonicalCoveragePath } from "./engine/index-coverage.js";
+const PREFIX = "cc1";
+const DIGEST = /^[a-f0-9]{64}$/;
+const KINDS = [
+    "static_field_read",
+    "constructor",
+    "variable_type",
+    "cast",
+    "class_literal",
+    "parameter_type",
+    "generic_parameter_type",
+    "loop_variable_type",
+    "generic_type_argument",
+];
+function record(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function exactKeys(value, keys) {
+    return (Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key)));
+}
+function validPayload(value) {
+    if (!record(value) || !exactKeys(value, ["v", "type", "queryDigest", "snapshotDigest", "after"]))
+        return false;
+    if (value.v !== 1 ||
+        value.type !== "class-consumers" ||
+        typeof value.queryDigest !== "string" ||
+        !DIGEST.test(value.queryDigest) ||
+        typeof value.snapshotDigest !== "string" ||
+        !DIGEST.test(value.snapshotDigest))
+        return false;
+    const key = value.after;
+    return (record(key) &&
+        exactKeys(key, ["file", "startByte", "endByte", "kind"]) &&
+        typeof key.file === "string" &&
+        canonicalCoveragePath(key.file) &&
+        Buffer.from(key.file).toString("utf8") === key.file &&
+        typeof key.startByte === "number" &&
+        Number.isSafeInteger(key.startByte) &&
+        key.startByte >= 0 &&
+        typeof key.endByte === "number" &&
+        Number.isSafeInteger(key.endByte) &&
+        key.endByte > key.startByte &&
+        typeof key.kind === "string" &&
+        KINDS.includes(key.kind));
+}
+function invalid() {
+    return new Error("invalid class-consumer continuation; restart the query without continuation");
+}
+/** Only call after the final wire envelope is fitted, using its last delivered site key. */
+export function signClassConsumerCursor(payload, secret) {
+    if (!validPayload(payload))
+        throw invalid();
+    // Copy validated fields explicitly: signing never invokes a caller-provided toJSON hook.
+    return signAuthenticatedCursor({
+        v: 1,
+        type: "class-consumers",
+        queryDigest: payload.queryDigest,
+        snapshotDigest: payload.snapshotDigest,
+        after: {
+            file: payload.after.file,
+            startByte: payload.after.startByte,
+            endByte: payload.after.endByte,
+            kind: payload.after.kind,
+        },
+    }, secret, PREFIX);
+}
+/** Authenticates and validates shape. Backend must still bind both digests to its current lease. */
+export function readClassConsumerCursor(cursor, secret) {
+    let payload;
+    try {
+        payload = verifyAuthenticatedCursor(cursor, secret, PREFIX);
+    }
+    catch {
+        throw invalid();
+    }
+    if (!validPayload(payload))
+        throw invalid();
+    return payload;
+}
+export function assertClassConsumerCursorBinding(cursor, queryDigest, snapshotDigest) {
+    if (!validPayload(cursor) || !DIGEST.test(queryDigest) || !DIGEST.test(snapshotDigest))
+        throw invalid();
+    if (cursor.queryDigest !== queryDigest)
+        throw new Error("class-consumer continuation belongs to another query; restart without continuation");
+    if (cursor.snapshotDigest !== snapshotDigest)
+        throw new Error("class-consumer evidence changed; restart the query without continuation");
+}

package/dist/src/class-consumer-delivery.js

@@ -0,0 +1,22 @@
+import { ClassConsumerQueryError, } from "./class-consumer-contract.js";
+/**
+ * Run once after the captured post-read health probe and before page packing.
+ * Revalidates the backend facts/coverage lease, not only freshness timestamps.
+ * Never replace the original page's rows or freshness with the validation read.
+ * Current seam repeats a limit-one raw read; measure before optimizing it into
+ * a dedicated lease check. Do not call it per candidate in the packing loop.
+ */
+export async function validateClassConsumerDelivery(page, request, read) {
+    const checked = await read({
+        ...request,
+        limit: 1,
+        expectedQueryDigest: page.queryDigest,
+        expectedSnapshotDigest: page.snapshotDigest,
+    });
+    if (checked.queryDigest !== page.queryDigest ||
+        checked.targetIdentity !== page.targetIdentity ||
+        checked.targetKind !== page.targetKind)
+        throw new ClassConsumerQueryError("CLASS_CONSUMER_QUERY_MISMATCH", "The class-consumer query changed before delivery.");
+    if (checked.snapshotDigest !== page.snapshotDigest)
+        throw new ClassConsumerQueryError("CLASS_CONSUMER_STALE_CURSOR", "The class-consumer evidence changed before delivery; restart the query.");
+}