@dailephd/my-dev-kit-lab 0.8.1 → 0.8.2

package/dist/src/experiments/plugins/contextPackGeneration/localSubjectPrivacy.js

@@ -0,0 +1,276 @@
+import { compareCodeUnits } from "../../../evaluation/indexSnapshot.js";
+import { redactedFileList } from "../contextWindowScaling/localSubjectPrivacy.js";
+import { CONTEXT_PACK_GENERATION_ERROR_TEXT, CONTEXT_PACK_IDENTITY_REDACTION_SCHEMA_VERSION } from "./executionTypes.js";
+import { collectContextPackFileIdentities } from "./localSubjectExecution.js";
+/** Single fixed placeholder for a withheld case title. */
+export const CONTEXT_PACK_REDACTED_CASE_TITLE = "<redacted case title>";
+/** The one V1 marker stamped on every externally projected case. Every class it names is absent from durable output. */
+export const CONTEXT_PACK_IDENTITY_REDACTION = {
+    schemaVersion: CONTEXT_PACK_IDENTITY_REDACTION_SCHEMA_VERSION,
+    fileIdentities: "redacted",
+    symbolIdentities: "redacted",
+    sourceText: "redacted",
+    callRelationships: "redacted",
+    testIdentities: "redacted",
+    factIdentities: "redacted",
+    taskText: "redacted",
+    warningText: "redacted",
+    semanticNodeIds: "redacted",
+    caseTitle: "redacted"
+};
+export const CONTEXT_PACK_PRIVACY_FAILURE_MESSAGE = "External-local context-pack-generation privacy projection failed; no durable output was written.";
+export const CONTEXT_PACK_UNEXPECTED_EXTERNAL_FAILURE_MESSAGE = "Local subject context-pack-generation failed (EXECUTION_FAILED): execution failed before completing (details withheld).";
+export const CONTEXT_PACK_EXTERNAL_PERSISTENCE_FAILURE_MESSAGE = "External-local context-pack-generation artifact persistence failed; attempted files were removed.";
+/** Fragments shorter than this (trimmed) are never searched: they collide with ordinary words and fixed text. */
+export const CONTEXT_PACK_SOURCE_FRAGMENT_MIN_LENGTH = 8;
+/** Upper bound on distinct source fragments retained for the leak assertion. */
+export const CONTEXT_PACK_SOURCE_FRAGMENT_MAX_COUNT = 5000;
+/** Identity names shorter than this are matched only as whole string values, never as substrings. */
+export const CONTEXT_PACK_NAME_SUBSTRING_MIN_LENGTH = 8;
+const sectionTruncatedCount = (pack, sectionId) => {
+    if (pack === null)
+        return undefined;
+    if (sectionId === "sourceSlices")
+        return pack.sourceSlices.filter((slice) => slice.truncated).length;
+    return undefined;
+};
+function projectTreatment(treatment, pack) {
+    return {
+        treatmentId: treatment.treatmentId,
+        status: treatment.status,
+        availability: treatment.availability,
+        availabilityReason: treatment.availabilityReason,
+        size: treatment.size === null ? null : { ...treatment.size },
+        // Identity evidence is the calculator input only; the durable artifact carries counts, never identities.
+        identityEvidence: null,
+        includedFiles: [],
+        identityCounts: treatment.identityEvidence === null
+            ? null
+            : {
+                files: treatment.identityEvidence.files.length,
+                symbols: treatment.identityEvidence.symbols.length,
+                includedFiles: treatment.includedFiles.length
+            },
+        // Node IDs are semantic identities; kind, outcome and fixed reason survive.
+        steps: treatment.steps.map((step) => ({ kind: step.kind, nodeId: null, sourceMode: step.sourceMode, succeeded: step.succeeded, reason: step.reason })),
+        sections: treatment.sections === null
+            ? null
+            : treatment.sections.map((section) => {
+                const truncatedCount = sectionTruncatedCount(pack, section.id);
+                return { ...section, ...(truncatedCount === undefined ? {} : { truncatedCount }) };
+            }),
+        evidenceNotes: [...treatment.evidenceNotes],
+        packArtifactPath: null,
+        errors: treatment.errors.map((error) => ({ code: error.code, message: CONTEXT_PACK_GENERATION_ERROR_TEXT[error.code] }))
+    };
+}
+/**
+ * Projects identity-bearing execution evidence into privacy-safe durable evidence. It performs no metric calculation and
+ * changes no count, size, availability or status. The in-memory pack is read only to count truncated slices.
+ */
+export function projectContextPackExecutionForExternalLocalPersistence(results) {
+    return results.map((result) => {
+        const evidence = result.evidence;
+        return {
+            caseId: evidence.caseId,
+            caseName: CONTEXT_PACK_REDACTED_CASE_TITLE,
+            benchmarkProject: evidence.benchmarkProject,
+            taskLocality: evidence.taskLocality,
+            treatments: evidence.treatments.map((treatment) => projectTreatment(treatment, treatment.treatmentId === "context-pack" ? result.pack : null)),
+            identityRedaction: { ...CONTEXT_PACK_IDENTITY_REDACTION }
+        };
+    });
+}
+const placeholders = (kind, count) => Array.from({ length: count }, (_, index) => `<redacted ${kind} ${index + 1}>`);
+const filePlaceholders = (list) => (list === null ? null : redactedFileList(list.length));
+const symbolPlaceholders = (list) => (list === null ? null : placeholders("symbol", list.length));
+const factPlaceholders = (list) => (list === null ? null : placeholders("fact", list.length));
+/** Only identity lists change; every number, availability and fixed-vocabulary reason is carried through untouched. */
+function projectQuality(quality) {
+    return {
+        ...quality,
+        file: {
+            ...quality.file,
+            relevantRetrievedFiles: filePlaceholders(quality.file.relevantRetrievedFiles),
+            irrelevantRetrievedFiles: filePlaceholders(quality.file.irrelevantRetrievedFiles),
+            missedFiles: filePlaceholders(quality.file.missedFiles)
+        },
+        symbol: {
+            ...quality.symbol,
+            relevantRetrievedSymbols: symbolPlaceholders(quality.symbol.relevantRetrievedSymbols),
+            irrelevantRetrievedSymbols: symbolPlaceholders(quality.symbol.irrelevantRetrievedSymbols),
+            missedSymbols: symbolPlaceholders(quality.symbol.missedSymbols)
+        },
+        fact: {
+            ...quality.fact,
+            coveredFactIds: factPlaceholders(quality.fact.coveredFactIds),
+            uncoveredFactIds: factPlaceholders(quality.fact.uncoveredFactIds)
+        }
+    };
+}
+/**
+ * Preserves every numeric scientific value; replaces only the private identity lists inside per-treatment quality.
+ * F1, deltas, savings, scope means and matched-case membership are never recalculated.
+ */
+export function projectContextPackAnalysisForExternalLocalPersistence(analysis) {
+    const cloned = structuredClone(analysis);
+    return {
+        cases: cloned.cases.map((entry) => ({
+            ...entry,
+            treatments: entry.treatments.map((treatment) => ({
+                ...treatment,
+                quality: treatment.quality === null ? null : projectQuality(treatment.quality)
+            }))
+        })),
+        scopes: cloned.scopes
+    };
+}
+/** Distinct non-trivial source lines of a pack, in code-unit order and bounded. Never returns short tokens. */
+export function collectContextPackSourceFragments(packs) {
+    const fragments = new Set();
+    for (const pack of packs) {
+        if (pack === null)
+            continue;
+        for (const slice of pack.sourceSlices) {
+            for (const line of slice.text.split(/\r?\n/)) {
+                const trimmed = line.trim();
+                if (trimmed.length >= CONTEXT_PACK_SOURCE_FRAGMENT_MIN_LENGTH)
+                    fragments.add(trimmed);
+            }
+        }
+    }
+    return [...fragments].sort(compareCodeUnits).slice(0, CONTEXT_PACK_SOURCE_FRAGMENT_MAX_COUNT);
+}
+const variantsOf = (value) => {
+    const forward = value.replace(/\\/g, "/");
+    const backward = value.replace(/\//g, "\\");
+    return [value, forward, backward].flatMap((entry) => [entry, JSON.stringify(entry).slice(1, -1)]);
+};
+const baseName = (file) => file.slice(file.lastIndexOf("/") + 1);
+/**
+ * Fail-closed defense in depth over a complete would-be durable payload. Roots, file paths, node IDs, task text,
+ * warnings and non-trivial source fragments are searched as substrings. Symbol names, fact IDs and file base names are
+ * searched only when at least CONTEXT_PACK_NAME_SUBSTRING_MIN_LENGTH characters long: shorter names collide with fixed
+ * schema vocabulary (for example a symbol called `search`) and would make ordinary repositories unrunnable. The structural
+ * projection, not this search, is what removes short identities.
+ */
+export function assertContextPackExternalProjectionIsPrivate(projected, privateValues) {
+    const serialized = typeof projected === "string" ? projected : JSON.stringify(projected);
+    const substringCandidates = [
+        ...privateValues.privateRoots,
+        ...privateValues.filePaths,
+        ...privateValues.nodeIds,
+        ...privateValues.taskTexts,
+        ...privateValues.warnings,
+        ...privateValues.sourceFragments.filter((fragment) => fragment.trim().length >= CONTEXT_PACK_SOURCE_FRAGMENT_MIN_LENGTH),
+        ...[...privateValues.symbolNames, ...privateValues.factIds, ...privateValues.filePaths.map(baseName)].filter((name) => name.length >= CONTEXT_PACK_NAME_SUBSTRING_MIN_LENGTH)
+    ].filter((value) => value.length > 0);
+    if (substringCandidates.some((value) => variantsOf(value).some((variant) => serialized.includes(variant)))) {
+        throw new Error(CONTEXT_PACK_PRIVACY_FAILURE_MESSAGE);
+    }
+}
+const GENERIC_ISSUE_TEXT = {
+    WORK_ROOT_INSIDE_TARGET: "the output directory must be outside the local subject repository",
+    BEFORE_SNAPSHOT_FAILED: "the target snapshot before execution could not be captured",
+    AFTER_SNAPSHOT_FAILED: "the target snapshot after execution could not be captured",
+    SCRATCH_CLEANUP_FAILED: "the private scratch could not be removed",
+    GUIDED_EXCLUSION_LIMIT: "the guided-index exclusions exceeded the safe limit",
+    GUIDED_EXCLUSION_UNREPRESENTABLE: "the guided-index exclusions could not be expressed exactly"
+};
+/**
+ * Safe, persistable description of an external-local failure: issue codes, counts and mutation kinds only. Execution
+ * issue messages are fixed text by construction; nothing else (no path, identity, title, or caught text) can appear.
+ */
+export function describeContextPackLocalSubjectFailureForPersistence(error) {
+    const parts = [];
+    const seen = new Set();
+    for (const issue of error.issues) {
+        if (issue.code === "EXECUTION_FAILED" || issue.code === "GROUND_TRUTH_INVALID" || issue.code === "RETRIEVAL_OUTSIDE_ELIGIBLE_UNIVERSE") {
+            if (!seen.has(issue.message)) {
+                seen.add(issue.message);
+                parts.push(issue.message.replace(/\.$/, ""));
+            }
+            continue;
+        }
+        if (seen.has(issue.code))
+            continue;
+        seen.add(issue.code);
+        if (issue.code === "TARGET_MUTATED") {
+            const kinds = [...new Set((error.immutability?.mutations ?? []).map((mutation) => mutation.kind))].sort();
+            parts.push(`the target changed during execution${kinds.length > 0 ? ` (${kinds.join(", ")})` : ""}; it was not restored`);
+        }
+        else {
+            parts.push(GENERIC_ISSUE_TEXT[issue.code] ?? `issue ${issue.code}`);
+        }
+    }
+    return `Local subject context-pack-generation failed (${error.code}): ${parts.join("; ")}.`;
+}
+function collectNodeIds(value, into) {
+    if (Array.isArray(value))
+        for (const entry of value)
+            collectNodeIds(entry, into);
+    else if (value && typeof value === "object") {
+        for (const [key, nested] of Object.entries(value)) {
+            if ((key === "nodeId" || key === "fromNodeId" || key === "toNodeId") && typeof nested === "string")
+                into.add(nested);
+            else
+                collectNodeIds(nested, into);
+        }
+    }
+}
+/**
+ * Gathers the real private identities of one external-local run, before projection, for the fail-closed assertion.
+ * Everything is read from in-memory data already produced; nothing is read from disk or the repository.
+ */
+export function collectContextPackExternalPrivateValues(args) {
+    const { subject, results } = args;
+    const filePaths = new Set([
+        ...subject.eligibleFiles,
+        ...subject.runtimeSafetyExclusions.gitIgnoredFiles,
+        ...subject.runtimeSafetyExclusions.oversizedFiles
+    ]);
+    const symbolNames = new Set();
+    const nodeIds = new Set();
+    const taskTexts = new Set();
+    const factIds = new Set();
+    for (const evaluationCase of subject.evaluationCases) {
+        taskTexts.add(evaluationCase.title);
+        taskTexts.add(evaluationCase.query);
+        for (const name of evaluationCase.expectedSymbols)
+            symbolNames.add(name);
+        for (const file of evaluationCase.expectedFiles)
+            filePaths.add(file);
+        for (const fact of evaluationCase.answerKey?.expectedFacts ?? evaluationCase.expectedFacts ?? [])
+            factIds.add(fact.id);
+    }
+    for (const result of results) {
+        for (const file of collectContextPackFileIdentities(result))
+            filePaths.add(file);
+        for (const treatment of result.evidence.treatments) {
+            for (const symbol of treatment.identityEvidence?.symbols ?? [])
+                symbolNames.add(symbol.name);
+            collectNodeIds(treatment.steps, nodeIds);
+        }
+        if (result.pack !== null) {
+            taskTexts.add(result.pack.task.title);
+            taskTexts.add(result.pack.task.summary);
+            for (const symbol of result.pack.symbols)
+                symbolNames.add(symbol.name);
+            for (const slice of result.pack.sourceSlices) {
+                if (slice.symbolName !== null)
+                    symbolNames.add(slice.symbolName);
+            }
+            collectNodeIds(result.pack, nodeIds);
+        }
+    }
+    return {
+        privateRoots: [subject.repositoryRoot, args.outputRoot],
+        filePaths: [...filePaths].sort(compareCodeUnits),
+        symbolNames: [...symbolNames].sort(compareCodeUnits),
+        nodeIds: [...nodeIds].sort(compareCodeUnits),
+        taskTexts: [...taskTexts].sort(compareCodeUnits),
+        factIds: [...factIds].sort(compareCodeUnits),
+        warnings: [],
+        sourceFragments: collectContextPackSourceFragments(results.map((result) => result.pack))
+    };
+}

package/dist/src/experiments/plugins/contextPackGeneration/metadata.js

@@ -0,0 +1,24 @@
+export const CONTEXT_PACK_GENERATION_PLUGIN_ID = "context-pack-generation";
+export const CONTEXT_PACK_GENERATION_TREATMENT_IDS = ["raw-full-file", "context-pack"];
+export const contextPackGenerationMetadata = {
+    id: CONTEXT_PACK_GENERATION_PLUGIN_ID,
+    name: "Context Pack Generation",
+    description: "Compare a deterministic Lab-owned experimental context pack against raw full-file context on matched bundled benchmark cases without coding agents.",
+    schemaVersion: "1.0.0",
+    status: "experimental",
+    supportedTargets: ["self", "external-local"],
+    supportedOutputs: ["json", "html", "text", "artifact"]
+};
+/** Exactly two mandatory treatments, in fixed order. There is no treatment selector. */
+export const CONTEXT_PACK_GENERATION_VARIANTS = [
+    {
+        id: "raw-full-file",
+        name: "Raw full-file context",
+        description: "Include every eligible file matched by the case raw include globs as raw text."
+    },
+    {
+        id: "context-pack",
+        name: "Context pack",
+        description: "Compose a bounded, deterministic pack of task, relevant files and symbols, source slices, call relationships, tests, and evidence notes from my-dev-kit evidence."
+    }
+];

package/dist/src/experiments/plugins/contextPackGeneration/metrics.js

@@ -0,0 +1,46 @@
+import { CONTEXT_PACK_GENERATION_TREATMENT_IDS } from "./metadata.js";
+/** Projects already-calculated scientific values onto generic metrics. Owns no formula. */
+export function toContextPackGenerationOutcomeMetrics(treatment, caseId) {
+    const base = { variantId: treatment.treatmentId, caseId };
+    const quality = treatment.quality;
+    const ratio = (id, name, metric) => ({ ...base, id, name, value: metric?.value ?? null, unit: "ratio" });
+    const count = (id, name, value) => ({ ...base, id, name, value: value ?? null, unit: "count" });
+    return [
+        ratio("file-precision", "File precision", quality?.file.precision),
+        ratio("file-recall", "File recall", quality?.file.recall),
+        ratio("file-f1", "File F1", treatment.fileF1),
+        ratio("symbol-precision", "Symbol precision", quality?.symbol.precision),
+        ratio("symbol-recall", "Symbol recall", quality?.symbol.recall),
+        ratio("symbol-f1", "Symbol F1", treatment.symbolF1),
+        ratio("fact-coverage", "Fact coverage", quality?.fact.coverage),
+        ratio("irrelevant-context-ratio", "Irrelevant context ratio", quality?.irrelevantContextRatio),
+        { ...base, id: "estimated-token-count", name: "Estimated token count", value: treatment.estimatedTokens, unit: "tokens" },
+        count("missed-file-count", "Missed file count", quality?.file.missedFileCount),
+        count("missed-symbol-count", "Missed symbol count", quality?.symbol.missedSymbolCount),
+        count("uncovered-fact-count", "Uncovered fact count", quality?.fact.uncoveredFactCount)
+    ];
+}
+export function toContextPackGenerationCaseComparisonMetrics(caseAnalysis) {
+    const { comparison, caseId } = caseAnalysis;
+    return [
+        { id: "file-f1-delta", name: "File F1 delta (pack minus raw)", value: comparison.fileF1Delta, unit: "ratio", caseId },
+        { id: "symbol-f1-delta", name: "Symbol F1 delta (pack minus raw)", value: comparison.symbolF1Delta, unit: "ratio", caseId },
+        { id: "fact-coverage-delta", name: "Fact coverage delta (pack minus raw)", value: comparison.factCoverageDelta, unit: "ratio", caseId },
+        { id: "estimated-token-delta", name: "Estimated token delta (pack minus raw)", value: comparison.estimatedTokenDelta, unit: "tokens", caseId },
+        { id: "tokens-saved", name: "Tokens saved (raw minus pack)", value: comparison.tokensSaved, unit: "tokens", caseId },
+        { id: "percent-saved", name: "Percent saved", value: comparison.percentSaved, unit: "percent", caseId }
+    ];
+}
+/** Per scope: matched case count, then four objective means per treatment in fixed order. No best/rank/score/front metric. */
+export function toContextPackGenerationRunMetrics(analysis) {
+    const metrics = [];
+    for (const scope of analysis.scopes) {
+        const { scopeId } = scope;
+        metrics.push({ id: `${scopeId}-comparison-case-count`, name: `${scopeId} matched comparison cases`, value: scope.includedCaseCount, unit: "count" });
+        for (const treatmentId of CONTEXT_PACK_GENERATION_TREATMENT_IDS) {
+            const objectives = scope.treatmentSummaries.find((summary) => summary.treatmentId === treatmentId)?.objectives ?? null;
+            metrics.push({ id: `${scopeId}-mean-file-f1`, name: `${scopeId} mean file F1`, value: objectives?.meanFileF1 ?? null, unit: "ratio", variantId: treatmentId }, { id: `${scopeId}-mean-symbol-f1`, name: `${scopeId} mean symbol F1`, value: objectives?.meanSymbolF1 ?? null, unit: "ratio", variantId: treatmentId }, { id: `${scopeId}-mean-fact-coverage`, name: `${scopeId} mean fact coverage`, value: objectives?.meanFactCoverage ?? null, unit: "ratio", variantId: treatmentId }, { id: `${scopeId}-mean-estimated-token-count`, name: `${scopeId} mean estimated token count`, value: objectives?.meanEstimatedTokenCount ?? null, unit: "tokens", variantId: treatmentId });
+        }
+    }
+    return metrics;
+}

package/dist/src/experiments/plugins/contextPackGeneration/packArtifact.js

@@ -0,0 +1,17 @@
+import { taskOutputSegment } from "../warmIndexReuse/selection.js";
+export const CONTEXT_PACK_ARTIFACT_DIRECTORY = "packs";
+export const CONTEXT_PACK_ARTIFACT_SUFFIX = ".context-pack.json";
+/**
+ * Relative path of a case's bundled pack artifact. The case segment comes from the established safe output-segment helper;
+ * a raw case id is never used as a path.
+ */
+export function contextPackArtifactRelativePath(caseId) {
+    return `${CONTEXT_PACK_ARTIFACT_DIRECTORY}/${taskOutputSegment(caseId)}${CONTEXT_PACK_ARTIFACT_SUFFIX}`;
+}
+/** The per-case artifact is the complete bundled pack (schema my-dev-kit-lab-context-pack-experiment-v1); no envelope, no clock. */
+export function buildContextPackArtifact(pack) {
+    return structuredClone(pack);
+}
+export function serializeContextPackArtifact(pack) {
+    return `${JSON.stringify(buildContextPackArtifact(pack), null, 2)}\n`;
+}

package/dist/src/experiments/plugins/contextPackGeneration/packEvidence.js

@@ -0,0 +1,152 @@
+/**
+ * Pure interpretation of already-captured my-dev-kit JSON output (search, lookup, slice, source) and of the validated
+ * symbol index. No I/O, no process execution. Anything not matching the expected shape is reported as malformed rather
+ * than guessed.
+ */
+import { interpretSymbolIndexFiles } from "../../../evaluation/indexSnapshot.js";
+import { MAX_SOURCE_LINES_PER_SLICE } from "./packSelectionPolicy.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const asString = (value) => (typeof value === "string" && value.length > 0 ? value : null);
+const asLine = (value) => (typeof value === "number" && Number.isInteger(value) && value >= 1 ? value : null);
+function parseJson(stdout) {
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseNode(value) {
+    if (!isRecord(value))
+        return null;
+    const id = asString(value.id);
+    const kind = asString(value.kind);
+    if (id === null || kind === null)
+        return null;
+    return { id, kind, path: asString(value.path), symbolName: asString(value.symbolName) ?? asString(value.label), line: asLine(value.line) };
+}
+function parseEdges(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        return null;
+    const edges = [];
+    for (const entry of value) {
+        if (!isRecord(entry))
+            return null;
+        const source = asString(entry.source);
+        const target = asString(entry.target);
+        const kind = asString(entry.kind);
+        if (source === null || target === null || kind === null)
+            return null;
+        edges.push({ source, target, kind });
+    }
+    return edges;
+}
+/** Preserves upstream order: rank is the 1-based position in `results`. Only file and symbol hits carry a seed node. */
+export function parseSearchHits(stdout, limit) {
+    const payload = parseJson(stdout);
+    if (!isRecord(payload) || !Array.isArray(payload.results))
+        return { ok: false };
+    const hits = [];
+    for (const [index, entry] of payload.results.slice(0, limit).entries()) {
+        if (!isRecord(entry))
+            return { ok: false };
+        const kind = asString(entry.kind);
+        const nodeId = asString(entry.nodeId) ?? asString(entry.id);
+        if (kind === null)
+            return { ok: false };
+        if ((kind !== "file" && kind !== "symbol") || nodeId === null)
+            continue;
+        hits.push({ rank: index + 1, kind, nodeId, path: asString(entry.path), label: asString(entry.label) });
+    }
+    return { ok: true, value: hits };
+}
+export function parseLookup(stdout) {
+    const payload = parseJson(stdout);
+    if (!isRecord(payload))
+        return { ok: false };
+    const node = parseNode(payload.node);
+    return node === null ? { ok: false } : { ok: true, value: { node } };
+}
+export function parseSlice(stdout) {
+    const payload = parseJson(stdout);
+    if (!isRecord(payload) || !Array.isArray(payload.nodes))
+        return { ok: false };
+    const nodes = [];
+    for (const entry of payload.nodes) {
+        const node = parseNode(entry);
+        if (node === null)
+            return { ok: false };
+        nodes.push(node);
+    }
+    const edges = parseEdges(payload.edges);
+    return edges === null ? { ok: false } : { ok: true, value: { nodes, edges } };
+}
+export function parseSource(stdout) {
+    const payload = parseJson(stdout);
+    if (!isRecord(payload) || payload.status !== "ok" || typeof payload.content !== "string")
+        return { ok: false };
+    const startLine = asLine(payload.startLine);
+    const endLine = asLine(payload.endLine);
+    if (startLine === null || endLine === null || endLine < startLine)
+        return { ok: false };
+    const cursor = isRecord(payload.continuationCursor) ? payload.continuationCursor : null;
+    return {
+        ok: true,
+        value: {
+            startLine,
+            endLine,
+            content: payload.content,
+            eof: cursor?.eof === true,
+            boundaryKnown: !(cursor !== null && (cursor.symbolBoundaryKnown === false || cursor.reason === "symbol-end-unknown"))
+        }
+    };
+}
+/** Returns null when the symbol-index contract cannot be interpreted; symbol evidence is then unavailable. */
+export function interpretSymbolIndex(symbolIndex) {
+    if (!interpretSymbolIndexFiles(symbolIndex, null).ok)
+        return null;
+    const files = [];
+    const lineCountByFile = new Map();
+    for (const entry of symbolIndex.files) {
+        if (!isRecord(entry) || typeof entry.path !== "string" || !Array.isArray(entry.symbols))
+            return null;
+        const symbols = [];
+        for (const symbol of entry.symbols) {
+            if (!isRecord(symbol) || typeof symbol.name !== "string" || !isRecord(symbol.location))
+                return null;
+            const line = asLine(symbol.location.line);
+            if (line === null)
+                return null;
+            symbols.push({ name: symbol.name, location: { line } });
+        }
+        files.push({ path: entry.path, symbols });
+        if (typeof entry.lineCount === "number" && Number.isInteger(entry.lineCount) && entry.lineCount >= 1)
+            lineCountByFile.set(entry.path, entry.lineCount);
+    }
+    return { files, lineCountByFile };
+}
+/**
+ * Index-derived bounded range for a symbol: it starts at the definition line and ends one line before the next indexed
+ * symbol of the same file (or at the file end), then is capped at MAX_SOURCE_LINES_PER_SLICE lines. Returns null when the
+ * index cannot establish a reliable boundary, in which case the caller falls back to bounded source by node.
+ */
+export function deriveSymbolSourceRange(index, file, startLine) {
+    const entry = index.files.find((candidate) => candidate.path === file);
+    if (!entry || !entry.symbols.some((symbol) => symbol.location.line === startLine))
+        return null;
+    const next = entry.symbols.map((symbol) => symbol.location.line).filter((line) => line > startLine).sort((a, b) => a - b)[0];
+    const fileEnd = index.lineCountByFile.get(file);
+    const naturalEndLine = next !== undefined ? next - 1 : fileEnd;
+    if (naturalEndLine === undefined || naturalEndLine < startLine)
+        return null;
+    const endLine = Math.min(naturalEndLine, startLine + MAX_SOURCE_LINES_PER_SLICE - 1);
+    return { startLine, endLine, naturalEndLine, capped: naturalEndLine > endLine };
+}
+/** Finds a symbol definition line in the index by file and exact name (first definition in line order). */
+export function findIndexedSymbolLine(index, file, name) {
+    const entry = index.files.find((candidate) => candidate.path === file);
+    const lines = entry?.symbols.filter((symbol) => symbol.name === name).map((symbol) => symbol.location.line).sort((a, b) => a - b);
+    return lines && lines.length > 0 ? lines[0] : null;
+}