frontend-project-context 1.3.1 → 1.7.0

package/src/project-context/adaptive-context.mjs

@@ -0,0 +1,547 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { canonicalJson, digestJson, prettyCanonicalJson, sha256 } from "./canonical-json.mjs";
+import { blockingContextFindings, checkProject } from "./checker.mjs";
+import { sourceStatus } from "./contract-schema.mjs";
+import { discoverProject } from "./discovery.mjs";
+import { ProjectContextError, fail } from "./errors.mjs";
+import { atomicWriteFile, readJsonFile } from "./io.mjs";
+import { normalizeRelativePath, resolveExistingInside, resolveWritableInside } from "./path-policy.mjs";
+import { loadProject } from "./project-store.mjs";
+import { renderTaskContextBundle } from "./renderer.mjs";
+import { effectiveItems, findConflicts, scopeApplies, validateOverrides } from "./scope-compiler.mjs";
+import { createSourceReadContext, readSourceDigest, verifyItem } from "./source-reader.mjs";
+import {
+  ADAPTIVE_CONTEXT_BUNDLE_SCHEMA_VERSION,
+  ADAPTIVE_SELECTOR_VERSION,
+  COVERAGE_AUDIT_SCHEMA_VERSION,
+  ROUTING_INDEX_PATH,
+  ROUTING_INDEX_SCHEMA_VERSION,
+  sealArtifact,
+  validateAdaptiveContextBundle,
+  validateContextQuery,
+  validateRoutingIndex,
+} from "./adaptive-context-schema.mjs";
+
+const LOCAL_SOURCE_KINDS = new Set(["file", "path", "json-pointer"]);
+const MANDATORY_KINDS = new Set(["policy", "validation-description"]);
+const ROUTED_KINDS = new Set(["fact", "reference"]);
+const COVERAGE_SUBJECT = "project.registration-coverage";
+const RETRIEVAL_SUBJECT = "project.context-retrieval";
+const EXCLUDED_BODIES = Object.freeze(["chat-history", "git-diffs", "source-bodies", "task-path-bodies", "verification-logs"]);
+const ROUTING_STOP_TERMS = new Set(["a", "an", "and", "apply", "change", "for", "in", "of", "on", "project", "rule", "the", "to", "update", "use"]);
+
+function uniqueSorted(values) { return [...new Set(values)].sort((left, right) => left.localeCompare(right)); }
+function snapshots(project) {
+  return { contract: project.contractDigest, sourcesLock: project.sourcesLockDigest, projectionsLock: project.projectionsLockDigest };
+}
+function stableFindings(findings) {
+  const byJson = new Map();
+  for (const entry of findings) byJson.set(canonicalJson(entry), entry);
+  return [...byJson.values()].sort((left, right) => canonicalJson(left).localeCompare(canonicalJson(right)));
+}
+function semanticParts(value, output = []) {
+  if (typeof value === "string") output.push(value);
+  else if (Array.isArray(value)) value.forEach((entry) => semanticParts(entry, output));
+  else if (value && typeof value === "object") {
+    for (const [key, entry] of Object.entries(value)) { output.push(key); semanticParts(entry, output); }
+  }
+  return output;
+}
+function tokenize(...values) {
+  const terms = new Set();
+  for (const value of values.flat(Infinity)) {
+    if (value === undefined || value === null) continue;
+    const expanded = String(value).normalize("NFKC").replace(/([a-z0-9])([A-Z])/gu, "$1 $2").toLowerCase();
+    for (const term of expanded.split(/[^a-z0-9\u3400-\u9fff]+/u)) {
+      if (term.length > 1 && !ROUTING_STOP_TERMS.has(term)) terms.add(term);
+    }
+  }
+  return [...terms].sort((left, right) => left.localeCompare(right));
+}
+function sourceLocator(source) {
+  if (source.kind === "json-pointer") return { path: source.path, pointer: source.pointer };
+  if (LOCAL_SOURCE_KINDS.has(source.kind)) return { path: source.path };
+  return { reference: source.reference };
+}
+
+function retrievalProfile(contract) {
+  const profiles = contract.items.filter((item) => item.status === "approved" && item.kind === "policy" && item.subject === RETRIEVAL_SUBJECT);
+  if (profiles.length === 0) return { item: null, rules: [], aliases: new Map() };
+  if (profiles.length > 1) fail("retrieval-profile-conflict", `multiple approved ${RETRIEVAL_SUBJECT} items are active`);
+  const item = profiles[0];
+  const value = item.value;
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some((key) => key !== "rules") || !Array.isArray(value.rules)) {
+    fail("retrieval-profile-invalid", `${item.id} must contain only a rules array`);
+  }
+  const approved = new Map(contract.items.filter((entry) => entry.status === "approved").map((entry) => [entry.id, entry]));
+  const rules = value.rules.map((rule, index) => {
+    if (!rule || typeof rule !== "object" || Array.isArray(rule) || Object.keys(rule).some((key) => !["aliases", "itemId", "requires"].includes(key))) {
+      fail("retrieval-profile-invalid", `${item.id} rules[${index}] is invalid`);
+    }
+    if (!approved.has(rule.itemId) || !Array.isArray(rule.requires) || !Array.isArray(rule.aliases)) fail("retrieval-profile-invalid", `${item.id} rules[${index}] references invalid items`);
+    const requires = uniqueSorted(rule.requires);
+    const aliases = uniqueSorted(rule.aliases);
+    if (requires.length !== rule.requires.length || aliases.length !== rule.aliases.length || requires.includes(rule.itemId)) fail("retrieval-profile-invalid", `${item.id} rules[${index}] is not stable or contains a self dependency`);
+    for (const required of requires) if (!approved.has(required)) fail("retrieval-profile-invalid", `${item.id} requires unknown approved item ${required}`);
+    return { itemId: rule.itemId, requires, aliases };
+  }).sort((left, right) => left.itemId.localeCompare(right.itemId));
+  const dependencyMap = new Map(rules.map((rule) => [rule.itemId, rule.requires]));
+  const visit = (id, stack = []) => {
+    if (stack.includes(id)) fail("retrieval-profile-invalid", `${item.id} contains a dependency cycle`);
+    for (const next of dependencyMap.get(id) ?? []) visit(next, [...stack, id]);
+  };
+  for (const id of dependencyMap.keys()) visit(id);
+  return { item, rules, aliases: new Map(rules.map((rule) => [rule.itemId, rule.aliases])) };
+}
+
+function itemIndexRecord(item, aliases = []) {
+  return {
+    id: item.id,
+    kind: item.kind,
+    subject: item.subject,
+    scope: structuredClone(item.scope),
+    sourceIds: [...item.sources].sort(),
+    terms: tokenize(item.id, item.subject, item.statement, semanticParts(item.value), aliases),
+    itemDigest: digestJson(item),
+  };
+}
+export function buildRoutingIndex(project) {
+  const approved = project.contract.items.filter((item) => item.status === "approved");
+  const profile = retrievalProfile(project.contract);
+  const items = approved.map((item) => itemIndexRecord(item, profile.aliases.get(item.id) ?? [])).sort((left, right) => left.id.localeCompare(right.id));
+  const sources = project.contract.sources.filter((source) => sourceStatus(source) === "active").map((source) => ({
+    id: source.id,
+    kind: source.kind,
+    locator: sourceLocator(source),
+    itemIds: approved.filter((item) => item.sources.includes(source.id) || item.verification?.source === source.id).map((item) => item.id).sort(),
+    sourceDigest: digestJson(source),
+  })).sort((left, right) => left.id.localeCompare(right.id));
+  return sealArtifact({ schemaVersion: 2, kind: "routing-index", projectId: project.contract.project.id, selectorVersion: 2, snapshots: snapshots(project), items, sources }, "indexDigest");
+}
+async function routingIndexForQuery(root, project) {
+  const rebuilt = buildRoutingIndex(project);
+  try {
+    const resolved = await resolveExistingInside(root, ROUTING_INDEX_PATH);
+    let stored;
+    try { stored = validateRoutingIndex(await readJsonFile(resolved.absolute, "routing index")); }
+    catch (error) {
+      if (!(error instanceof ProjectContextError)) throw error;
+      return { index: rebuilt, state: "invalid-rebuilt-in-memory", rejectedDigest: null };
+    }
+    if (canonicalJson(stored.snapshots) !== canonicalJson(rebuilt.snapshots) || stored.indexDigest !== rebuilt.indexDigest) return { index: rebuilt, state: "stale-rebuilt-in-memory", rejectedDigest: stored.indexDigest };
+    return { index: stored, state: "current", rejectedDigest: null };
+  } catch (error) {
+    if (error?.code !== "source-missing") throw error;
+    return { index: rebuilt, state: "missing-rebuilt-in-memory", rejectedDigest: null };
+  }
+}
+export async function indexContext(root, project, options = {}) {
+  const index = buildRoutingIndex(project);
+  if (options.write) {
+    const resolved = await resolveWritableInside(root, ROUTING_INDEX_PATH, { createParent: true });
+    await atomicWriteFile(resolved.absolute, prettyCanonicalJson(index));
+  }
+  return index;
+}
+
+function pathWithin(target, parent) { return parent === "." || target === parent || target.startsWith(`${parent}/`); }
+function coverageProfile(contract) {
+  const candidates = contract.items.filter((item) => item.status === "approved" && item.kind === "policy" && item.subject === COVERAGE_SUBJECT);
+  if (candidates.length === 0) return null;
+  if (candidates.length > 1) fail("coverage-profile-conflict", `multiple approved ${COVERAGE_SUBJECT} items are active`);
+  const item = candidates[0];
+  const value = item.value;
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some((key) => !["excludedPaths", "roots"].includes(key)) || !Array.isArray(value.roots) || !Array.isArray(value.excludedPaths)) fail("coverage-profile-invalid", `${item.id} coverage value is invalid`);
+  const normalize = (values, label) => uniqueSorted(values.map((entry) => normalizeRelativePath(entry, { allowRoot: true, label })));
+  return { itemId: item.id, itemDigest: digestJson(item), sourceIds: [...item.sources].sort(), roots: normalize(value.roots, "coverage root"), excludedPaths: normalize(value.excludedPaths, "coverage excluded path") };
+}
+function coverageClass(profile, registeredPaths, candidatePath) {
+  if (registeredPaths.has(candidatePath)) return "registered";
+  if (!profile) return "outside-declared-coverage";
+  if (profile.excludedPaths.some((entry) => pathWithin(candidatePath, entry))) return "excluded-approved";
+  if (profile.roots.some((entry) => pathWithin(candidatePath, entry))) return "review-required";
+  return "outside-declared-coverage";
+}
+export async function buildCoverageAudit(root, project, changedPaths = []) {
+  const profile = coverageProfile(project.contract);
+  const proposal = await discoverProject(root, project.contract);
+  const registered = project.contract.sources.filter((source) => sourceStatus(source) === "active" && source.path).map((source) => source.path);
+  const registeredPaths = new Set(registered);
+  const byPath = new Map();
+  for (const source of proposal.sources.filter((entry) => entry.path)) byPath.set(source.path, { path: source.path, origin: "conservative-discovery", proposedSourceId: source.id });
+  for (const changedPath of changedPaths) {
+    const normalized = normalizeRelativePath(changedPath, { allowRoot: true, label: "changed path" });
+    if (!byPath.has(normalized)) byPath.set(normalized, { path: normalized, origin: "host-changed-path-signal" });
+  }
+  for (const registeredPath of registered) if (!byPath.has(registeredPath)) byPath.set(registeredPath, { path: registeredPath, origin: "registered-source" });
+  const categories = { registered: [], "excluded-approved": [], "review-required": [], "outside-declared-coverage": [] };
+  for (const candidate of [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path))) categories[coverageClass(profile, registeredPaths, candidate.path)].push(candidate);
+  const registrationCoverage = !profile ? "not-declared" : categories["review-required"].length === 0 ? "closed-for-declared-scope" : "review-required";
+  return sealArtifact({ schemaVersion: 1, kind: "coverage-audit", project: { id: project.contract.project.id, name: project.contract.project.name }, snapshots: snapshots(project), profile, registrationCoverage, categories, guarantee: "declared-scope-only-never-all-project-truth" }, "auditDigest");
+}
+
+function effectiveByTarget(contract, paths, findings) {
+  const result = new Map();
+  for (const target of paths) {
+    try { result.set(target, effectiveItems(contract.items, target)); }
+    catch (error) {
+      if (!(error instanceof ProjectContextError) || error.code !== "contract-conflict") throw error;
+      findings.push({ code: "contract-conflict", severity: "blocked", path: target, conflicts: error.details?.findings ?? [] });
+      result.set(target, contract.items.filter((item) => item.status === "approved" && scopeApplies(item.scope, target)));
+    }
+  }
+  return result;
+}
+function unionEffective(byTarget) {
+  const byId = new Map();
+  for (const items of byTarget.values()) for (const item of items) byId.set(item.id, item);
+  return [...byId.values()].sort((left, right) => left.id.localeCompare(right.id));
+}
+function queryTerms(query) { return tokenize(query.task.text, query.task.topics); }
+function matchReasons(itemRecord, terms) {
+  const matches = itemRecord?.terms.filter((term) => terms.includes(term)) ?? [];
+  return matches.map((term) => `term:${term}`);
+}
+function resolvesOverride(item, targetId, byId, seen = new Set()) {
+  if (item.overrides.includes(targetId)) return true;
+  if (seen.has(item.id)) return false;
+  seen.add(item.id);
+  return item.overrides.some((id) => byId.has(id) && resolvesOverride(byId.get(id), targetId, byId, seen));
+}
+function effectiveResolution(requiredId, targetItems, byId) {
+  const direct = targetItems.find((item) => item.id === requiredId);
+  if (direct) return direct;
+  const replacements = targetItems.filter((item) => resolvesOverride(item, requiredId, byId));
+  return replacements.length === 1 ? replacements[0] : null;
+}
+function closeDependencies(contract, profile, byTarget, selected, reasons, findings) {
+  const byId = new Map(contract.items.filter((item) => item.status === "approved").map((item) => [item.id, item]));
+  const rules = new Map(profile.rules.map((rule) => [rule.itemId, rule.requires]));
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const requiringId of [...selected]) {
+      for (const requiredId of rules.get(requiringId) ?? []) {
+        const requiringTargets = [...byTarget.entries()].filter(([, items]) => items.some((item) => item.id === requiringId));
+        if (requiringTargets.length === 0) continue;
+        for (const [target, items] of requiringTargets) {
+          const resolved = effectiveResolution(requiredId, items, byId);
+          if (!resolved) {
+            findings.push({ code: "declared-dependency-missing", severity: "blocked", itemId: requiringId, requiredItemId: requiredId, path: target });
+            continue;
+          }
+          if (!selected.has(resolved.id)) {
+            selected.add(resolved.id);
+            reasons.set(resolved.id, uniqueSorted([...(reasons.get(resolved.id) ?? []), `dependency-of:${requiringId}`]));
+            changed = true;
+          }
+        }
+      }
+    }
+  }
+}
+
+export function selectAdaptiveItems(contract, index, query, options = {}) {
+  const findings = options.findings ?? [];
+  const byTarget = effectiveByTarget(contract, query.task.paths, findings);
+  const applicable = unionEffective(byTarget);
+  const applicableIds = new Set(applicable.map((item) => item.id));
+  const approvedById = new Map(contract.items.filter((item) => item.status === "approved").map((item) => [item.id, item]));
+  const allById = new Map(contract.items.map((item) => [item.id, item]));
+  const indexById = new Map((index?.items ?? []).map((item) => [item.id, item]));
+  const profile = retrievalProfile(contract);
+  const selected = new Set();
+  const reasons = new Map();
+  for (const item of applicable) if (MANDATORY_KINDS.has(item.kind)) { selected.add(item.id); reasons.set(item.id, ["mandatory-kind"]); }
+  for (const explicitId of query.task.itemIds) {
+    const approved = approvedById.get(explicitId);
+    if (!approved) findings.push({ code: "requested-item-unavailable", severity: "blocked", itemId: explicitId });
+    else if (!applicableIds.has(explicitId)) {
+      const replaced = applicable.some((item) => resolvesOverride(item, explicitId, approvedById));
+      findings.push({ code: replaced ? "requested-item-not-effective" : "requested-item-out-of-scope", severity: "blocked", itemId: explicitId });
+    } else { selected.add(explicitId); reasons.set(explicitId, ["explicit-item-id"]); }
+  }
+  if (query.level === "complete") {
+    for (const item of applicable) { selected.add(item.id); reasons.set(item.id, uniqueSorted([...(reasons.get(item.id) ?? []), "complete-baseline"])); }
+  } else if (query.level === "expanded") {
+    const catalog = options.previousCatalog ?? [];
+    const requested = query.expansion;
+    const matches = catalog.filter((entry) => requested.requestedItemIds.includes(entry.id) || requested.requestedSubjects.includes(entry.subject) || entry.sourceIds.some((id) => requested.requestedSourceIds.includes(id)));
+    const requestedCount = requested.requestedItemIds.length + requested.requestedSubjects.length + requested.requestedSourceIds.length;
+    if (requestedCount === 0 || matches.length === 0) findings.push({ code: "expansion-request-unavailable", severity: "blocked" });
+    for (const id of requested.requestedItemIds) if (!catalog.some((entry) => entry.id === id)) findings.push({ code: "expansion-request-unavailable", severity: "blocked", itemId: id });
+    for (const subject of requested.requestedSubjects) if (!catalog.some((entry) => entry.subject === subject)) findings.push({ code: "expansion-request-unavailable", severity: "blocked", subject });
+    for (const sourceId of requested.requestedSourceIds) if (!catalog.some((entry) => entry.sourceIds.includes(sourceId))) findings.push({ code: "expansion-request-unavailable", severity: "blocked", sourceId });
+    for (const entry of matches) if (applicableIds.has(entry.id)) { selected.add(entry.id); reasons.set(entry.id, ["targeted-expansion"]); }
+  } else {
+    const terms = queryTerms(query);
+    for (const item of applicable.filter((entry) => ROUTED_KINDS.has(entry.kind))) {
+      const matches = matchReasons(indexById.get(item.id), terms);
+      if (matches.length > 0) { selected.add(item.id); reasons.set(item.id, matches); }
+    }
+  }
+  closeDependencies(contract, profile, byTarget, selected, reasons, findings);
+  for (const conflict of findConflicts(applicable)) {
+    if (!conflict.items?.some((id) => selected.has(id))) continue;
+    findings.push({ code: "contract-conflict", severity: "blocked", subject: conflict.subject, itemIds: [...conflict.items].sort() });
+  }
+  const selectedItems = [...selected].filter((id) => applicableIds.has(id)).map((id) => approvedById.get(id)).filter(Boolean).sort((left, right) => left.id.localeCompare(right.id));
+  const deferred = applicable.filter((item) => !selected.has(item.id));
+  return { selected: selectedItems, reasons, deferred, applicable, byTarget, profile, allById };
+}
+
+function hydratedItem(item, reasons) {
+  return { id: item.id, kind: item.kind, subject: item.subject, value: structuredClone(item.value), statement: item.statement, scope: structuredClone(item.scope), sourceIds: [...item.sources].sort(), overrides: [...item.overrides].sort(), ...(item.verification ? { verification: structuredClone(item.verification) } : {}), selectionReasons: [...reasons].sort(), itemDigest: digestJson(item) };
+}
+function deferredItem(item) { return { id: item.id, kind: item.kind, subject: item.subject, scope: structuredClone(item.scope), sourceIds: [...item.sources].sort(), itemDigest: digestJson(item), reason: "applicable-not-selected" }; }
+function baselineFindings(query, project) {
+  const current = snapshots(project);
+  return Object.keys(current).filter((key) => current[key] !== query.snapshots[key]).map((key) => ({ code: `${key === "contract" ? "contract" : key === "sourcesLock" ? "sources-lock" : "projections-lock"}-baseline-stale`, severity: "blocked", expected: query.snapshots[key], actual: current[key] }));
+}
+function structuralFindings(project, selectedIds, targetPaths) {
+  const selected = new Set(selectedIds);
+  const relevantSourceIds = new Set(project.contract.items.filter((item) => selected.has(item.id)).flatMap((item) => [...item.sources, item.verification?.source].filter(Boolean)));
+  const lock = new Map(project.sourcesLock.sources.map((entry) => [entry.id, entry.digest]));
+  const findings = [];
+  for (const source of project.contract.sources.filter((entry) => sourceStatus(entry) === "active" && LOCAL_SOURCE_KINDS.has(entry.kind))) {
+    const severity = relevantSourceIds.has(source.id) ? "blocked" : "attention";
+    if (!lock.has(source.id)) findings.push({ code: "source-lock-missing", severity, sourceId: source.id, path: source.path });
+    else if (lock.get(source.id) !== source.digest) findings.push({ code: "source-lock-mismatch", severity, sourceId: source.id, path: source.path });
+  }
+  for (const finding of validateOverrides(project.contract.items)) {
+    const ids = [finding.item, finding.target].filter(Boolean);
+    findings.push({ code: finding.code, severity: ids.some((id) => selected.has(id)) ? "blocked" : "attention", projectFinding: finding });
+  }
+  for (const item of project.contract.items.filter((entry) => entry.status === "proposed")) {
+    const taskRelated = targetPaths.some((target) => scopeApplies(item.scope, target));
+    findings.push({ code: "item-approval-pending", severity: taskRelated && MANDATORY_KINDS.has(item.kind) ? "blocked" : "attention", itemId: item.id });
+  }
+  return findings;
+}
+async function auditRelevantSources(root, project, items, sourceReadContext) {
+  const sourceIds = new Set(items.flatMap((item) => [...item.sources, item.verification?.source].filter(Boolean)));
+  const sourceById = new Map(project.contract.sources.map((source) => [source.id, source]));
+  const lock = new Map(project.sourcesLock.sources.map((entry) => [entry.id, entry.digest]));
+  const evidence = [];
+  const findings = [];
+  for (const sourceId of [...sourceIds].sort()) {
+    const source = sourceById.get(sourceId);
+    if (!source || sourceStatus(source) !== "active") { findings.push({ code: "source-unavailable", severity: "blocked", sourceId }); continue; }
+    const base = { id: source.id, kind: source.kind, locator: sourceLocator(source), sourceDigest: digestJson(source) };
+    if (!LOCAL_SOURCE_KINDS.has(source.kind)) { evidence.push({ ...base, freshness: "unverifiable-non-local" }); continue; }
+    try {
+      const actual = await readSourceDigest(root, source, sourceReadContext);
+      const expected = lock.get(source.id) ?? null;
+      const freshness = expected !== null && expected === source.digest && actual === expected ? "current" : "drifted";
+      evidence.push({ ...base, freshness, expectedDigest: expected, actualDigest: actual });
+      if (freshness !== "current") findings.push({ code: "source-drift", severity: "blocked", sourceId: source.id, path: source.path, expectedDigest: expected, actualDigest: actual });
+    } catch (error) {
+      evidence.push({ ...base, freshness: "unreadable", expectedDigest: lock.get(source.id) ?? null, actualDigest: null });
+      findings.push({ code: "source-drift", severity: "blocked", sourceId: source.id, path: source.path, reason: error.code ?? "source-unreadable" });
+    }
+  }
+  for (const item of items) {
+    if (!item.verification || item.verification.kind === "none") continue;
+    try { const finding = await verifyItem(root, item, sourceById, sourceReadContext); if (finding) findings.push({ code: "verification-failed", severity: "blocked", projectFinding: finding }); }
+    catch (error) { findings.push({ code: "verification-failed", severity: "blocked", itemId: item.id, reason: error.code ?? "unreadable" }); }
+  }
+  return { evidence, findings };
+}
+function readTargets(query, sourceEvidence) {
+  const byPath = new Map();
+  const add = (entry) => { if (entry.path && !byPath.has(entry.path)) byPath.set(entry.path, entry); };
+  query.task.paths.forEach((entry) => add({ path: entry, reason: "task-target" }));
+  query.task.changedPaths.forEach((entry) => add({ path: entry, reason: "host-changed-path-signal" }));
+  sourceEvidence.forEach((source) => add(source.locator.path ? { path: source.locator.path, reason: "contract-source", sourceId: source.id } : {}));
+  return [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path));
+}
+function taskHealth(findings) {
+  if (findings.some((entry) => entry.severity === "blocked")) return "blocked";
+  if (findings.some((entry) => entry.severity === "needs-expansion")) return "needs-expansion";
+  return "ready";
+}
+function checkerFinding(entry) { return { code: entry.code.startsWith("source-") ? "source-drift" : entry.code, severity: blockingContextFindings([entry]).length > 0 ? "blocked" : "attention", projectFinding: entry }; }
+function taskDigest(query) { return digestJson({ projectId: query.projectId, task: query.task, freshness: query.freshness }); }
+function monotonicBudget(previous, query, findings) {
+  const before = previous.budget;
+  const after = query.budget;
+  const shrunk = after.audit.targetUtf8Bytes < before.audit.targetUtf8Bytes || after.audit.maxUtf8Bytes < before.audit.maxUtf8Bytes || after.delivery.completeBelowUtf8Bytes < before.delivery.completeBelowUtf8Bytes || after.delivery.maxUtf8Bytes < before.delivery.maxUtf8Bytes || after.readTargets.target < before.readTargets.target || after.readTargets.max < before.readTargets.max;
+  if (shrunk) findings.push({ code: "context-query-budget-shrunk", severity: "blocked" });
+}
+async function targetStates(root, paths) {
+  const result = [];
+  for (const entry of paths) {
+    try { await access(path.resolve(root, entry)); result.push({ path: entry, state: "existing" }); }
+    catch (error) { if (error?.code !== "ENOENT") throw error; result.push({ path: entry, state: "prospective-or-deleted" }); }
+  }
+  return result;
+}
+function withAuditBytesAndDigest(input) {
+  const value = structuredClone(input);
+  let used = 0;
+  for (let iteration = 0; iteration < 12; iteration += 1) {
+    value.budget.audit.usedUtf8Bytes = used;
+    delete value.bundleDigest;
+    value.bundleDigest = digestJson(value);
+    const next = Buffer.byteLength(canonicalJson(value), "utf8");
+    if (next === used) break;
+    used = next;
+  }
+  value.budget.audit.usedUtf8Bytes = used;
+  delete value.bundleDigest;
+  value.bundleDigest = digestJson(value);
+  return value;
+}
+function validatePreviousAgainstProject(previous, project, query, findings) {
+  if (canonicalJson(previous.snapshots) !== canonicalJson(snapshots(project))) findings.push({ code: "context-query-previous-stale", severity: "blocked" });
+  if (previous.taskDigest !== taskDigest(query)) findings.push({ code: "context-query-previous-task-mismatch", severity: "blocked" });
+  if (query.expansion?.previousBundleDigest !== previous.bundleDigest) findings.push({ code: "context-query-previous-digest-mismatch", severity: "blocked" });
+  if (previous.expansionDepth !== 0) findings.push({ code: "context-query-expansion-depth-exceeded", severity: "blocked" });
+  if (canonicalJson(previous.task.itemIds) !== canonicalJson(query.task.itemIds)) findings.push({ code: "context-query-previous-task-mismatch", severity: "blocked" });
+  const effective = new Set(unionEffective(effectiveByTarget(project.contract, query.task.paths, findings)).map((item) => item.id));
+  const liveById = new Map(project.contract.items.filter((item) => item.status === "approved").map((item) => [item.id, item]));
+  for (const artifactItem of previous.hydratedItems) {
+    const live = liveById.get(artifactItem.id);
+    if (!live || !effective.has(artifactItem.id) || digestJson(live) !== artifactItem.itemDigest) findings.push({ code: "context-query-previous-item-invalid", severity: "blocked", itemId: artifactItem.id });
+  }
+  monotonicBudget(previous, query, findings);
+}
+
+export async function buildAdaptiveContextBundle(root, project, queryInput, options = {}) {
+  const query = validateContextQuery(queryInput);
+  if (query.projectId !== project.contract.project.id) fail("context-query-project-mismatch", "context query belongs to a different project");
+  if (query.level === "expanded" && !options.previous) fail("context-query-previous-required", "expanded context requires --previous");
+  if (query.level !== "expanded" && options.previous) fail("context-query-previous-not-allowed", `${query.level} context cannot use --previous`);
+  const previous = options.previous ?? null;
+  const indexResult = await routingIndexForQuery(root, project);
+  const findings = baselineFindings(query, project);
+  if (previous) validatePreviousAgainstProject(previous, project, query, findings);
+  const selection = selectAdaptiveItems(project.contract, indexResult.index, query, { findings, previousCatalog: previous?.deferredItems ?? [] });
+  const previousIds = new Set(previous?.delivery.itemIds ?? []);
+  const selectedIds = new Set(selection.selected.map((item) => item.id));
+  if (previous) for (const id of previousIds) selectedIds.add(id);
+  const approvedById = new Map(project.contract.items.filter((item) => item.status === "approved").map((item) => [item.id, item]));
+  const applicableIds = new Set(selection.applicable.map((item) => item.id));
+  const selectedItems = [...selectedIds].filter((id) => applicableIds.has(id)).map((id) => approvedById.get(id)).filter(Boolean).sort((left, right) => left.id.localeCompare(right.id));
+  findings.push(...structuralFindings(project, selectedItems.map((item) => item.id), query.task.paths));
+  if (query.level === "initial" && uniqueSorted(query.task.paths.filter((entry) => entry !== ".").map((entry) => entry.split("/")[0])).length > 1) findings.push({ code: "cross-module-context", severity: "needs-expansion" });
+
+  const completeIds = selection.applicable.map((item) => item.id).sort();
+  const adaptiveIds = selectedItems.map((item) => item.id).sort();
+  const renderBlocked = findings.some((entry) => entry.code === "contract-conflict" && entry.severity === "blocked");
+  const completeContent = renderBlocked ? "" : renderTaskContextBundle(project.contract, query.task.paths, completeIds, query.task.text);
+  const adaptiveContent = renderBlocked ? "" : renderTaskContextBundle(project.contract, query.task.paths, adaptiveIds, query.task.text);
+  const completeBytes = Buffer.byteLength(completeContent, "utf8");
+  const adaptiveBytes = Buffer.byteLength(adaptiveContent, "utf8");
+  let mode = "adaptive";
+  if (query.level === "complete" || completeBytes <= query.budget.delivery.completeBelowUtf8Bytes || (adaptiveBytes >= completeBytes && completeBytes <= query.budget.delivery.maxUtf8Bytes)) mode = "complete";
+  if (mode === "complete") {
+    for (let index = findings.length - 1; index >= 0; index -= 1) if (["task-candidate-miss", "cross-module-context"].includes(findings[index].code)) findings.splice(index, 1);
+  } else if (query.level === "initial" && selection.deferred.some((item) => ROUTED_KINDS.has(item.kind)) && !selection.selected.some((item) => ROUTED_KINDS.has(item.kind))) {
+    findings.push({ code: "task-candidate-miss", severity: "needs-expansion" });
+  }
+  const finalItems = (mode === "complete" ? selection.applicable : selectedItems).sort((left, right) => left.id.localeCompare(right.id));
+  const finalIds = finalItems.map((item) => item.id);
+  const finalContent = mode === "complete" ? completeContent : adaptiveContent;
+  const finalBytes = mode === "complete" ? completeBytes : adaptiveBytes;
+  if (finalBytes > query.budget.delivery.maxUtf8Bytes) findings.push({ code: "delivery-budget-insufficient", severity: "blocked", limit: query.budget.delivery.maxUtf8Bytes, required: finalBytes });
+
+  const sourceReadContext = createSourceReadContext();
+  const relevantAudit = await auditRelevantSources(root, project, finalItems, sourceReadContext);
+  findings.push(...relevantAudit.findings);
+  let globalHealth = findings.some((entry) => entry.code.endsWith("baseline-stale")) ? "snapshot-stale" : "not-checked";
+  let registrationCoverage = "not-checked";
+  const strictMode = query.freshness === "strict-current" || query.level === "complete";
+  if (strictMode) {
+    const strict = await checkProject(root, project, { sourceReadContext });
+    findings.push(...strict.map(checkerFinding));
+    globalHealth = strict.length === 0 ? "clean" : blockingContextFindings(strict).length > 0 ? "conflict" : "attention";
+    const coverage = await buildCoverageAudit(root, project, query.task.changedPaths);
+    registrationCoverage = coverage.registrationCoverage;
+    if (registrationCoverage === "review-required") findings.push({ code: "registration-coverage-review-required", severity: "blocked", paths: coverage.categories["review-required"].map((entry) => entry.path) });
+  }
+  const targets = readTargets(query, relevantAudit.evidence);
+  if (targets.length > query.budget.readTargets.target) findings.push({ code: "soft-read-target-exceeded", severity: "attention", target: query.budget.readTargets.target, required: targets.length });
+  if (targets.length > query.budget.readTargets.max) findings.push({ code: "read-target-budget-insufficient", severity: "blocked", limit: query.budget.readTargets.max, required: targets.length });
+  if (indexResult.state !== "current") findings.push({ code: "routing-index-fallback", severity: "attention", state: indexResult.state });
+  const normalizedFindings = stableFindings(findings);
+  const health = taskHealth(normalizedFindings);
+  const ready = health === "ready";
+  const retainedItemIds = previous ? finalIds.filter((id) => previousIds.has(id)).sort() : [];
+  const hydratedItems = finalItems.filter((item) => !previousIds.has(item.id)).map((item) => hydratedItem(item, selection.reasons.get(item.id) ?? [mode === "complete" ? "complete-baseline" : "dependency-or-retained-closure"]));
+  const hasDependencies = selection.profile.rules.some((rule) => finalIds.includes(rule.itemId));
+  let bundle = withAuditBytesAndDigest({
+    schemaVersion: ADAPTIVE_CONTEXT_BUNDLE_SCHEMA_VERSION,
+    kind: "adaptive-context-bundle",
+    project: { id: project.contract.project.id, name: project.contract.project.name },
+    task: structuredClone(query.task),
+    queryDigest: digestJson(query),
+    taskDigest: taskDigest(query),
+    ...(previous ? { previousBundleDigest: previous.bundleDigest } : {}),
+    level: query.level,
+    expansionDepth: previous ? 1 : 0,
+    snapshots: snapshots(project),
+    routing: { indexDigest: indexResult.index.indexDigest, indexState: indexResult.state, ...(indexResult.rejectedDigest ? { rejectedDigest: indexResult.rejectedDigest } : {}) },
+    guarantees: {
+      registrationCoverage,
+      mandatoryCoverage: normalizedFindings.some((entry) => entry.severity === "blocked" && ["contract-conflict", "requested-item-out-of-scope", "requested-item-not-effective"].includes(entry.code)) ? "blocked" : "complete",
+      declaredDependencyCoverage: normalizedFindings.some((entry) => entry.code === "declared-dependency-missing") ? "missing" : hasDependencies ? "complete" : "not-declared",
+      retrievalStatus: mode === "complete" ? "complete" : normalizedFindings.some((entry) => entry.code === "task-candidate-miss") ? "no-candidate" : "matched",
+      semanticCompleteness: "not-claimed",
+      freshness: strictMode ? "strict-current" : "snapshot-and-signal-bound",
+    },
+    globalHealth,
+    taskHealth: health,
+    targetStates: await targetStates(root, query.task.paths),
+    hydratedItems,
+    retainedItemIds,
+    deferredItems: selection.deferred.filter((item) => !finalIds.includes(item.id)).map(deferredItem),
+    sources: relevantAudit.evidence,
+    evidenceEdges: finalItems.flatMap((item) => item.sources.map((sourceId) => ({ itemId: item.id, sourceId }))).sort((left, right) => canonicalJson(left).localeCompare(canonicalJson(right))),
+    readTargets: targets,
+    findings: normalizedFindings,
+    excluded: [...EXCLUDED_BODIES],
+    metrics: { sourceDigestReads: sourceReadContext.metrics.sourceDigestReads, sourceBodyReads: sourceReadContext.metrics.sourceBodyReads, sourceIdentityReads: sourceReadContext.metrics.sourceIdentityReads, hydratedItemCount: hydratedItems.length, retainedItemCount: retainedItemIds.length, deferredItemCount: selection.deferred.length, hostToolCalls: 1 },
+    budget: {
+      unit: "canonical-utf8-bytes",
+      audit: { targetUtf8Bytes: query.budget.audit.targetUtf8Bytes, maxUtf8Bytes: query.budget.audit.maxUtf8Bytes, usedUtf8Bytes: 0 },
+      delivery: { completeBelowUtf8Bytes: query.budget.delivery.completeBelowUtf8Bytes, maxUtf8Bytes: query.budget.delivery.maxUtf8Bytes, usedUtf8Bytes: ready ? finalBytes : 0 },
+      readTargets: { target: query.budget.readTargets.target, max: query.budget.readTargets.max, count: targets.length },
+    },
+    delivery: ready ? { status: "ready", format: "project-context-markdown", mode, itemIds: finalIds, contentDigest: sha256(finalContent), utf8Bytes: finalBytes } : { status: "withheld", format: "project-context-markdown", mode: null, itemIds: [], contentDigest: null, utf8Bytes: 0 },
+  });
+  if (bundle.budget.audit.usedUtf8Bytes > query.budget.audit.targetUtf8Bytes) {
+    bundle.findings = stableFindings([...bundle.findings, { code: "soft-audit-budget-exceeded", severity: "attention", target: query.budget.audit.targetUtf8Bytes, required: bundle.budget.audit.usedUtf8Bytes }]);
+    bundle = withAuditBytesAndDigest(bundle);
+  }
+  return validateAdaptiveContextBundle(bundle);
+}
+
+async function loadPrevious(root, previousPath) {
+  if (!previousPath) return null;
+  const resolved = await resolveExistingInside(root, previousPath);
+  return validateAdaptiveContextBundle(await readJsonFile(resolved.absolute, "previous adaptive context bundle"));
+}
+export async function buildAdaptiveContextBundleFiles(root, inputPath, options = {}) {
+  const resolved = await resolveExistingInside(root, inputPath);
+  const input = await readJsonFile(resolved.absolute, "context query");
+  const project = await loadProject(root);
+  const previous = await loadPrevious(root, options.previousPath);
+  const bundle = await buildAdaptiveContextBundle(root, project, input, { previous });
+  if (!options.forPrompt && bundle.budget.audit.usedUtf8Bytes > bundle.budget.audit.maxUtf8Bytes) fail("audit-budget-insufficient", "adaptive context audit exceeds its hard byte budget", { exitCode: 1, details: { limit: bundle.budget.audit.maxUtf8Bytes, required: bundle.budget.audit.usedUtf8Bytes } });
+  return bundle;
+}
+export async function buildAdaptiveContextDeliveryFiles(root, inputPath, options = {}) {
+  const resolved = await resolveExistingInside(root, inputPath);
+  const input = validateContextQuery(await readJsonFile(resolved.absolute, "context query"));
+  const project = await loadProject(root);
+  const previous = await loadPrevious(root, options.previousPath);
+  const bundle = await buildAdaptiveContextBundle(root, project, input, { previous });
+  if (bundle.taskHealth !== "ready" || bundle.delivery.status !== "ready") fail("adaptive-context-delivery-withheld", "adaptive context delivery is not ready; inspect --json", { exitCode: 1, details: { taskHealth: bundle.taskHealth } });
+  const content = renderTaskContextBundle(project.contract, input.task.paths, bundle.delivery.itemIds, input.task.text);
+  if (sha256(content) !== bundle.delivery.contentDigest || Buffer.byteLength(content, "utf8") !== bundle.delivery.utf8Bytes) fail("adaptive-context-delivery-invalid", "adaptive context delivery projection does not match its digest or byte count");
+  return { bundle, content };
+}
+export async function buildCoverageAuditFiles(root, changedPaths = []) { return buildCoverageAudit(root, await loadProject(root), changedPaths); }
+export async function indexContextFiles(root, options = {}) { return indexContext(root, await loadProject(root), options); }