frontend-project-context 1.6.0 → 1.7.0

package/schemas/upgrade-result-bundle.schema.json

@@ -10,7 +10,7 @@
     "kind": {"const": "upgrade-result-bundle"},
     "product": {"type": "object", "additionalProperties": false, "required": ["name"], "properties": {"name": {"const": "frontend-project-context"}}},
     "fromVersion": {"type": "string"},
-    "targetVersion": {"const": "1.6.0"},
+    "targetVersion": {"const": "1.7.0"},
     "manifestDigest": {"$ref": "#/$defs/digest"},
     "planDigest": {"$ref": "#/$defs/digest"},
     "mode": {"enum": ["preview", "write"]},

package/src/project-context/a130-evaluation.mjs

@@ -0,0 +1,91 @@
+import { canonicalJson, digestJson } from "./canonical-json.mjs";
+import { fail } from "./errors.mjs";
+
+function median(values) {
+  const sorted = [...values].sort((left, right) => left - right);
+  return sorted[Math.floor(sorted.length / 2)];
+}
+
+function sameStringSet(left = [], right = []) {
+  return canonicalJson([...left].sort()) === canonicalJson([...right].sort());
+}
+
+function pairEntries(entries) {
+  return Array.from({ length: entries.length / 2 }, (_, index) => entries.slice(index * 2, index * 2 + 2));
+}
+
+function pairArms(pair) {
+  return {
+    full: pair.find((run) => run.arm === "full"),
+    candidate: pair.find((run) => run.arm === "candidate"),
+  };
+}
+
+function assertFailureEvidence(run) {
+  if (run.score < 8 && (!Array.isArray(run.failedChecks) || run.failedChecks.length === 0 || run.failedChecks.some((entry) => typeof entry !== "string" || !entry))) {
+    fail("a130-run-result-invalid", "a failed A-130 run must name its failed checks");
+  }
+}
+
+export function validateA130EvaluationPlan(plan, contract, readablePaths) {
+  if (!plan || typeof plan !== "object" || Array.isArray(plan)) fail("a130-evaluation-invalid", "evaluation plan must be an object");
+  const allowed = new Set(["arms", "cases", "forbiddenPaths", "model", "oracleApproval", "wrapper"]);
+  if (Object.keys(plan).some((key) => !allowed.has(key)) || !Array.isArray(plan.arms) || !Array.isArray(plan.cases)) fail("a130-evaluation-invalid", "evaluation plan structure is invalid");
+  if (plan.arms.length !== 2 || plan.arms.some((arm) => !arm || typeof arm !== "object" || arm.format !== plan.arms[0].format || canonicalJson(arm.wrapper) !== canonicalJson(plan.wrapper))) fail("arm-format-mismatch", "full and candidate arms must use the same delivery format and wrapper");
+  const approvedIds = new Set(contract.items.filter((item) => item.status === "approved").map((item) => item.id));
+  const readable = new Set(readablePaths);
+  for (const scenario of plan.cases) {
+    if (!Array.isArray(scenario.oracle) || scenario.oracle.length === 0) fail("oracle-evidence-missing", "every evaluation case needs a non-empty oracle");
+    for (const oracle of scenario.oracle) {
+      if (!oracle.contractItemId && !oracle.sourcePath) fail("oracle-evidence-missing", "oracle truth must be available to both arms through Contract or readable source");
+      if (oracle.contractItemId && !approvedIds.has(oracle.contractItemId)) fail("oracle-evidence-missing", `oracle item ${oracle.contractItemId} is not approved`);
+      if (oracle.sourcePath && !readable.has(oracle.sourcePath)) fail("oracle-evidence-missing", `oracle source ${oracle.sourcePath} is not readable by both arms`);
+      if (plan.forbiddenPaths.includes(oracle.sourcePath)) fail("oracle-evidence-forbidden", "forbidden oracle locators cannot be model evidence");
+    }
+  }
+  const oracleDigest = digestJson(plan.cases.map(({ id, oracle }) => ({ id, oracle })));
+  const approval = plan.oracleApproval;
+  if (!approval || typeof approval !== "object" || Array.isArray(approval) || Object.keys(approval).some((key) => !["at", "by", "oracleDigest"].includes(key)) || typeof approval.by !== "string" || !approval.by || typeof approval.at !== "string" || !approval.at || approval.oracleDigest !== oracleDigest) {
+    fail("oracle-human-approval-missing", "the exact A-130 oracle table must be digest-bound and explicitly approved by a human before Provider use");
+  }
+  return { planDigest: digestJson(plan), status: "ready", armFormat: plan.arms[0].format, oracleDigest, wrapperDigest: digestJson(plan.wrapper) };
+}
+
+export function evaluateA130Runs(runs) {
+  if (!Array.isArray(runs) || runs.length !== 8) fail("a130-run-set-invalid", "A-130 requires one S pair and three order-balanced L pairs (eight runs maximum)");
+  const expectedOrders = { S: ["full", "candidate"], L: ["full", "candidate", "candidate", "full", "full", "candidate"] };
+  for (const caseId of ["S", "L"]) {
+    const entries = runs.filter((run) => run.caseId === caseId);
+    if (canonicalJson(entries.map((run) => run.arm)) !== canonicalJson(expectedOrders[caseId])) fail("a130-run-order-invalid", `${caseId} does not match its frozen pair order`);
+    if (entries.some((run) => run.forbiddenAccess || run.targetWritten || run.gitChanged)) fail("a130-safety-gate-failed", `${caseId} contains a forbidden Host action`);
+    entries.forEach(assertFailureEvidence);
+  }
+  const small = runs.filter((run) => run.caseId === "S");
+  if (small[0].promptDigest !== small[1].promptDigest) fail("a130-small-prompt-mismatch", "A-130-S prompts must be byte-identical before Provider comparison");
+  if (small[0].score !== 8 || small[1].score !== 8) {
+    if (small[0].score < 8 && small[1].score < 8 && sameStringSet(small[0].failedChecks, small[1].failedChecks)) fail("a130-fixture-inconclusive", "byte-identical A-130-S arms failed the same checks; review the task/oracle without changing product selection");
+    fail("a130-provider-variance-inconclusive", "byte-identical A-130-S arms produced different quality and cannot identify a product defect");
+  }
+  const large = runs.filter((run) => run.caseId === "L");
+  const full = large.filter((run) => run.arm === "full");
+  const candidate = large.filter((run) => run.arm === "candidate");
+  if (candidate.some((run) => run.deliveryMode !== "adaptive" || run.requiredRecall !== 1)) fail("a130-adaptive-evidence-defect", "A-130-L candidate runs must be real adaptive deliveries with complete required-item recall");
+  const attributedFailures = [];
+  for (const pair of pairEntries(large)) {
+    const { full: fullRun, candidate: candidateRun } = pairArms(pair);
+    if (fullRun.score < 8 && candidateRun.score < 8 && sameStringSet(fullRun.failedChecks, candidateRun.failedChecks)) fail("a130-fixture-inconclusive", "paired A-130-L arms failed the same checks; review the task/oracle without changing product selection");
+    if (fullRun.score < 8) fail("a130-baseline-inconclusive", "an A-130-L full baseline failed, so the pair cannot identify an adaptive product defect");
+    if (candidateRun.score < 8) {
+      const attribution = candidateRun.attribution;
+      if (!attribution || attribution.kind !== "delivery-evidence-gap" || !Array.isArray(attribution.itemIds) || attribution.itemIds.length === 0) fail("a130-causality-inconclusive", "a candidate-only failure needs a governed delivery-evidence attribution before it can be a product defect");
+      attributedFailures.push(attribution.itemIds.slice().sort());
+    }
+  }
+  if (attributedFailures.length > 0) {
+    const reproducible = attributedFailures.some((ids, index) => attributedFailures.some((other, otherIndex) => otherIndex > index && canonicalJson(ids) === canonicalJson(other)));
+    if (!reproducible) fail("a130-causality-inconclusive", "an attributed adaptive failure was not reproduced in a second balanced pair");
+    fail("a130-adaptive-evidence-defect", "a governed delivery-evidence gap reproducibly caused candidate-only quality failure");
+  }
+  if (median(candidate.map((run) => run.promptBytes)) > median(full.map((run) => run.promptBytes)) * 0.7 || median(candidate.map((run) => run.inputTokens)) > median(full.map((run) => run.inputTokens)) || median(candidate.map((run) => run.commandCount)) > median(full.map((run) => run.commandCount)) || median(candidate.map((run) => run.wallSeconds)) > median(full.map((run) => run.wallSeconds)) * 1.1) fail("a130-efficiency-gate-failed", "A-130-L median efficiency gates failed");
+  return { status: "passed", pairs: 4, runs: 8 };
+}

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

@@ -0,0 +1,392 @@
+import { canonicalJson, canonicalValue, digestJson, validateJsonValue } from "./canonical-json.mjs";
+import { fail } from "./errors.mjs";
+import { normalizeRelativePath } from "./path-policy.mjs";
+
+export const CONTEXT_QUERY_SCHEMA_VERSION = 2;
+export const ADAPTIVE_CONTEXT_BUNDLE_SCHEMA_VERSION = 2;
+export const ROUTING_INDEX_SCHEMA_VERSION = 2;
+export const COVERAGE_AUDIT_SCHEMA_VERSION = 1;
+export const ADAPTIVE_SELECTOR_VERSION = 2;
+export const ROUTING_INDEX_PATH = ".project-context/derived/routing-index.json";
+
+const SHA256 = /^sha256:[a-f0-9]{64}$/u;
+const ID = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/u;
+const AUTHORITY_FIELDS = new Set(["approval", "approve", "by", "command", "provider", "shell", "write"]);
+
+function invalid(kind, message, details = {}) { fail(`${kind}-schema-invalid`, message, { details }); }
+function object(value, kind, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalid(kind, `${label} must be an object`);
+}
+function exactKeys(value, allowed, kind, label, required = allowed) {
+  for (const key of Object.keys(value)) {
+    if (AUTHORITY_FIELDS.has(key)) invalid(kind, `${label} contains forbidden authority or execution field: ${key}`);
+    if (!allowed.has(key)) invalid(kind, `${label} contains unknown field: ${key}`);
+  }
+  for (const key of required) if (!Object.hasOwn(value, key)) invalid(kind, `${label}.${key} is required`);
+}
+function text(value, kind, label, options = {}) {
+  if (typeof value !== "string" || (!options.empty && value.length === 0)) invalid(kind, `${label} must be a non-empty string`);
+  return value;
+}
+function id(value, kind, label) {
+  text(value, kind, label);
+  if (!ID.test(value)) invalid(kind, `${label} must use stable lowercase dot/kebab naming`);
+  return value;
+}
+function digest(value, kind, label) {
+  text(value, kind, label);
+  if (!SHA256.test(value)) invalid(kind, `${label} must be sha256`);
+  return value;
+}
+function integer(value, kind, label, minimum = 0) {
+  if (!Number.isSafeInteger(value) || value < minimum) invalid(kind, `${label} must be an integer >= ${minimum}`);
+  return value;
+}
+function enumeration(value, allowed, kind, label) {
+  if (!allowed.includes(value)) invalid(kind, `${label} is invalid`);
+  return value;
+}
+function uniqueStrings(values, kind, label, options = {}) {
+  if (!Array.isArray(values) || (!options.empty && values.length === 0)) invalid(kind, `${label} must be ${options.empty ? "an" : "a non-empty"} array`);
+  const seen = new Set();
+  for (const value of values) {
+    text(value, kind, `${label} entry`);
+    if (seen.has(value)) invalid(kind, `${label} contains duplicate value: ${value}`);
+    seen.add(value);
+  }
+  const sorted = [...values].sort((left, right) => left.localeCompare(right));
+  if (canonicalJson(values) !== canonicalJson(sorted)) invalid(kind, `${label} must be stably sorted`);
+  return sorted;
+}
+function ids(values, kind, label, options = {}) {
+  const result = uniqueStrings(values, kind, label, { empty: options.empty ?? true });
+  result.forEach((entry) => id(entry, kind, `${label} entry`));
+  return result;
+}
+function snapshots(value, kind, label) {
+  object(value, kind, label);
+  const keys = new Set(["contract", "projectionsLock", "sourcesLock"]);
+  exactKeys(value, keys, kind, label);
+  return {
+    contract: digest(value.contract, kind, `${label}.contract`),
+    sourcesLock: digest(value.sourcesLock, kind, `${label}.sourcesLock`),
+    projectionsLock: digest(value.projectionsLock, kind, `${label}.projectionsLock`),
+  };
+}
+function projectPaths(values, kind, label, options = {}) {
+  const original = uniqueStrings(values, kind, label, { empty: options.empty ?? true });
+  const normalized = original.map((value) => {
+    try { return normalizeRelativePath(value, { allowRoot: true, label }); }
+    catch (error) { invalid(kind, `${label} entry must stay inside the project`, { path: value, reason: error.code ?? "invalid-path" }); }
+  });
+  if (canonicalJson(normalized) !== canonicalJson(original)) invalid(kind, `${label} must contain normalized paths`);
+  return normalized;
+}
+function byteBudget(value, kind, label, targetName) {
+  object(value, kind, label);
+  const keys = new Set([targetName, "maxUtf8Bytes"]);
+  exactKeys(value, keys, kind, label);
+  const result = { [targetName]: integer(value[targetName], kind, `${label}.${targetName}`, 1), maxUtf8Bytes: integer(value.maxUtf8Bytes, kind, `${label}.maxUtf8Bytes`, 1) };
+  if (result[targetName] > result.maxUtf8Bytes) invalid(kind, `${label} soft target cannot exceed hard limit`);
+  return result;
+}
+
+export function validateContextQuery(input) {
+  const kind = "context-query";
+  object(input, kind, kind);
+  const keys = new Set(["budget", "expansion", "freshness", "kind", "level", "projectId", "schemaVersion", "snapshots", "task"]);
+  exactKeys(input, keys, kind, kind);
+  if (input.schemaVersion !== CONTEXT_QUERY_SCHEMA_VERSION || input.kind !== kind) invalid(kind, "context-query identity is invalid");
+  id(input.projectId, kind, "context-query.projectId");
+  const level = enumeration(input.level, ["initial", "expanded", "complete"], kind, "context-query.level");
+  const freshness = enumeration(input.freshness, ["snapshot-and-signal-bound", "strict-current"], kind, "context-query.freshness");
+  object(input.task, kind, "context-query.task");
+  const taskKeys = new Set(["changedPaths", "itemIds", "paths", "text", "topics"]);
+  exactKeys(input.task, taskKeys, kind, "context-query.task");
+  object(input.budget, kind, "context-query.budget");
+  const budgetKeys = new Set(["audit", "delivery", "readTargets"]);
+  exactKeys(input.budget, budgetKeys, kind, "context-query.budget");
+  object(input.budget.readTargets, kind, "context-query.budget.readTargets");
+  exactKeys(input.budget.readTargets, new Set(["max", "target"]), kind, "context-query.budget.readTargets");
+  const budget = {
+    audit: byteBudget(input.budget.audit, kind, "context-query.budget.audit", "targetUtf8Bytes"),
+    delivery: byteBudget(input.budget.delivery, kind, "context-query.budget.delivery", "completeBelowUtf8Bytes"),
+    readTargets: { target: integer(input.budget.readTargets.target, kind, "context-query.budget.readTargets.target", 1), max: integer(input.budget.readTargets.max, kind, "context-query.budget.readTargets.max", 1) },
+  };
+  if (budget.readTargets.target > budget.readTargets.max) invalid(kind, "context-query read target soft target cannot exceed hard limit");
+  let expansion = null;
+  if (input.expansion !== null) {
+    object(input.expansion, kind, "context-query.expansion");
+    const expansionKeys = new Set(["previousBundleDigest", "requestedItemIds", "requestedSourceIds", "requestedSubjects"]);
+    exactKeys(input.expansion, expansionKeys, kind, "context-query.expansion");
+    expansion = {
+      previousBundleDigest: digest(input.expansion.previousBundleDigest, kind, "context-query.expansion.previousBundleDigest"),
+      requestedItemIds: ids(input.expansion.requestedItemIds, kind, "context-query.expansion.requestedItemIds"),
+      requestedSubjects: ids(input.expansion.requestedSubjects, kind, "context-query.expansion.requestedSubjects"),
+      requestedSourceIds: ids(input.expansion.requestedSourceIds, kind, "context-query.expansion.requestedSourceIds"),
+    };
+  }
+  if (level === "expanded" && expansion === null) invalid(kind, "expanded context-query requires expansion");
+  if (level !== "expanded" && expansion !== null) invalid(kind, `${level} context-query cannot contain expansion`);
+  return canonicalValue({
+    schemaVersion: 2, kind, projectId: input.projectId,
+    snapshots: snapshots(input.snapshots, kind, "context-query.snapshots"),
+    task: {
+      text: text(input.task.text, kind, "context-query.task.text"),
+      paths: projectPaths(input.task.paths, kind, "context-query.task.paths", { empty: false }),
+      topics: uniqueStrings(input.task.topics, kind, "context-query.task.topics", { empty: true }),
+      itemIds: ids(input.task.itemIds, kind, "context-query.task.itemIds"),
+      changedPaths: projectPaths(input.task.changedPaths, kind, "context-query.task.changedPaths"),
+    },
+    level, freshness, budget, expansion,
+  });
+}
+
+function validateSealedArtifact(input, { kind, schemaVersion, digestField }) {
+  object(input, kind, kind);
+  if (input.schemaVersion !== schemaVersion || input.kind !== kind) invalid(kind, `${kind} identity is invalid`);
+  digest(input[digestField], kind, `${kind}.${digestField}`);
+  const copy = structuredClone(input);
+  delete copy[digestField];
+  if (digestJson(copy) !== input[digestField]) invalid(kind, `${kind}.${digestField} does not match canonical content`);
+  return canonicalValue(input);
+}
+export function sealArtifact(input, digestField) {
+  const copy = canonicalValue(input);
+  delete copy[digestField];
+  return canonicalValue({ ...copy, [digestField]: digestJson(copy) });
+}
+function array(value, kind, label) {
+  if (!Array.isArray(value)) invalid(kind, `${label} must be an array`);
+  return value;
+}
+function optionalDigest(value, kind, label) {
+  if (value !== null) digest(value, kind, label);
+}
+function scope(value, kind, label) {
+  object(value, kind, label);
+  if (value.kind === "project") exactKeys(value, new Set(["kind"]), kind, label);
+  else {
+    exactKeys(value, new Set(["kind", "path"]), kind, label);
+    enumeration(value.kind, ["path-prefix", "file"], kind, `${label}.kind`);
+    projectPaths([value.path], kind, `${label}.path`, { empty: false });
+  }
+}
+function locator(value, kind, label) {
+  object(value, kind, label);
+  if (Object.hasOwn(value, "reference")) {
+    exactKeys(value, new Set(["reference"]), kind, label);
+    text(value.reference, kind, `${label}.reference`);
+    return;
+  }
+  const keys = Object.hasOwn(value, "pointer") ? new Set(["path", "pointer"]) : new Set(["path"]);
+  exactKeys(value, keys, kind, label);
+  projectPaths([value.path], kind, `${label}.path`, { empty: false });
+  if (Object.hasOwn(value, "pointer")) text(value.pointer, kind, `${label}.pointer`, { empty: true });
+}
+
+export function validateRoutingIndex(input) {
+  const kind = "routing-index";
+  const value = validateSealedArtifact(input, { kind, schemaVersion: 2, digestField: "indexDigest" });
+  const keys = new Set(["indexDigest", "items", "kind", "projectId", "schemaVersion", "selectorVersion", "snapshots", "sources"]);
+  exactKeys(value, keys, kind, kind);
+  id(value.projectId, kind, `${kind}.projectId`);
+  snapshots(value.snapshots, kind, `${kind}.snapshots`);
+  if (value.selectorVersion !== 2) invalid(kind, `${kind}.selectorVersion is unsupported`);
+  const itemIds = [];
+  for (const [index, item] of array(value.items, kind, `${kind}.items`).entries()) {
+    object(item, kind, `${kind}.items[${index}]`);
+    exactKeys(item, new Set(["id", "itemDigest", "kind", "scope", "sourceIds", "subject", "terms"]), kind, `${kind}.items[${index}]`);
+    itemIds.push(id(item.id, kind, `${kind}.items[${index}].id`));
+    text(item.kind, kind, `${kind}.items[${index}].kind`);
+    id(item.subject, kind, `${kind}.items[${index}].subject`);
+    enumeration(item.kind, ["fact", "policy", "reference", "validation-description"], kind, `${kind}.items[${index}].kind`);
+    scope(item.scope, kind, `${kind}.items[${index}].scope`);
+    digest(item.itemDigest, kind, `${kind}.items[${index}].itemDigest`);
+    ids(item.sourceIds, kind, `${kind}.items[${index}].sourceIds`);
+    uniqueStrings(item.terms, kind, `${kind}.items[${index}].terms`, { empty: true });
+  }
+  ids(itemIds, kind, `${kind}.item ids`);
+  const sourceIds = [];
+  for (const [index, source] of array(value.sources, kind, `${kind}.sources`).entries()) {
+    object(source, kind, `${kind}.sources[${index}]`);
+    exactKeys(source, new Set(["id", "itemIds", "kind", "locator", "sourceDigest"]), kind, `${kind}.sources[${index}]`);
+    sourceIds.push(id(source.id, kind, `${kind}.sources[${index}].id`));
+    text(source.kind, kind, `${kind}.sources[${index}].kind`);
+    ids(source.itemIds, kind, `${kind}.sources[${index}].itemIds`);
+    digest(source.sourceDigest, kind, `${kind}.sources[${index}].sourceDigest`);
+    locator(source.locator, kind, `${kind}.sources[${index}].locator`);
+  }
+  ids(sourceIds, kind, `${kind}.source ids`);
+  return value;
+}
+
+export function validateAdaptiveContextBundle(input) {
+  const kind = "adaptive-context-bundle";
+  const value = validateSealedArtifact(input, { kind, schemaVersion: 2, digestField: "bundleDigest" });
+  const keys = new Set(["budget", "bundleDigest", "deferredItems", "delivery", "evidenceEdges", "excluded", "expansionDepth", "findings", "globalHealth", "guarantees", "hydratedItems", "kind", "level", "metrics", "previousBundleDigest", "project", "queryDigest", "readTargets", "retainedItemIds", "routing", "schemaVersion", "snapshots", "sources", "targetStates", "task", "taskDigest", "taskHealth"]);
+  exactKeys(value, keys, kind, kind, new Set([...keys].filter((entry) => entry !== "previousBundleDigest")));
+  digest(value.queryDigest, kind, `${kind}.queryDigest`);
+  digest(value.taskDigest, kind, `${kind}.taskDigest`);
+  if (value.previousBundleDigest !== undefined) digest(value.previousBundleDigest, kind, `${kind}.previousBundleDigest`);
+  snapshots(value.snapshots, kind, `${kind}.snapshots`);
+  const level = enumeration(value.level, ["initial", "expanded", "complete"], kind, `${kind}.level`);
+  const expansionDepth = integer(value.expansionDepth, kind, `${kind}.expansionDepth`);
+  if ((level === "expanded") !== (value.previousBundleDigest !== undefined) || expansionDepth !== (level === "expanded" ? 1 : 0)) invalid(kind, "adaptive context expansion lineage is invalid");
+  object(value.project, kind, `${kind}.project`);
+  exactKeys(value.project, new Set(["id", "name"]), kind, `${kind}.project`);
+  id(value.project.id, kind, `${kind}.project.id`);
+  text(value.project.name, kind, `${kind}.project.name`);
+  object(value.task, kind, `${kind}.task`);
+  exactKeys(value.task, new Set(["changedPaths", "itemIds", "paths", "text", "topics"]), kind, `${kind}.task`);
+  text(value.task.text, kind, `${kind}.task.text`);
+  projectPaths(value.task.paths, kind, `${kind}.task.paths`, { empty: false });
+  uniqueStrings(value.task.topics, kind, `${kind}.task.topics`, { empty: true });
+  ids(value.task.itemIds, kind, `${kind}.task.itemIds`);
+  projectPaths(value.task.changedPaths, kind, `${kind}.task.changedPaths`);
+  object(value.routing, kind, `${kind}.routing`);
+  exactKeys(value.routing, new Set(["indexDigest", "indexState", "rejectedDigest"]), kind, `${kind}.routing`, new Set(["indexDigest", "indexState"]));
+  digest(value.routing.indexDigest, kind, `${kind}.routing.indexDigest`);
+  enumeration(value.routing.indexState, ["current", "invalid-rebuilt-in-memory", "stale-rebuilt-in-memory", "missing-rebuilt-in-memory"], kind, `${kind}.routing.indexState`);
+  if (value.routing.rejectedDigest !== undefined) digest(value.routing.rejectedDigest, kind, `${kind}.routing.rejectedDigest`);
+  object(value.guarantees, kind, `${kind}.guarantees`);
+  exactKeys(value.guarantees, new Set(["declaredDependencyCoverage", "freshness", "mandatoryCoverage", "registrationCoverage", "retrievalStatus", "semanticCompleteness"]), kind, `${kind}.guarantees`);
+  text(value.guarantees.registrationCoverage, kind, `${kind}.guarantees.registrationCoverage`);
+  enumeration(value.guarantees.mandatoryCoverage, ["complete", "blocked"], kind, `${kind}.guarantees.mandatoryCoverage`);
+  enumeration(value.guarantees.declaredDependencyCoverage, ["complete", "missing", "not-declared"], kind, `${kind}.guarantees.declaredDependencyCoverage`);
+  enumeration(value.guarantees.retrievalStatus, ["matched", "no-candidate", "ambiguous", "complete"], kind, `${kind}.guarantees.retrievalStatus`);
+  if (value.guarantees.semanticCompleteness !== "not-claimed") invalid(kind, "semantic completeness cannot be claimed");
+  enumeration(value.guarantees.freshness, ["strict-current", "snapshot-and-signal-bound"], kind, `${kind}.guarantees.freshness`);
+  enumeration(value.globalHealth, ["clean", "attention", "conflict", "not-checked", "snapshot-stale"], kind, `${kind}.globalHealth`);
+  enumeration(value.taskHealth, ["ready", "needs-expansion", "blocked"], kind, `${kind}.taskHealth`);
+  ids(value.retainedItemIds, kind, `${kind}.retainedItemIds`);
+  for (const collection of ["hydratedItems", "deferredItems", "sources", "evidenceEdges", "readTargets", "findings", "targetStates"]) array(value[collection], kind, `${kind}.${collection}`);
+  const hydratedIds = [];
+  for (const [index, item] of value.hydratedItems.entries()) {
+    const label = `${kind}.hydratedItems[${index}]`;
+    object(item, kind, label);
+    exactKeys(item, new Set(["id", "itemDigest", "kind", "overrides", "scope", "selectionReasons", "sourceIds", "statement", "subject", "value", "verification"]), kind, label, new Set(["id", "itemDigest", "kind", "overrides", "scope", "selectionReasons", "sourceIds", "statement", "subject", "value"]));
+    hydratedIds.push(id(item.id, kind, `${label}.id`));
+    enumeration(item.kind, ["fact", "policy", "reference", "validation-description"], kind, `${label}.kind`);
+    id(item.subject, kind, `${label}.subject`);
+    text(item.statement, kind, `${label}.statement`);
+    scope(item.scope, kind, `${label}.scope`);
+    ids(item.sourceIds, kind, `${label}.sourceIds`);
+    ids(item.overrides, kind, `${label}.overrides`);
+    uniqueStrings(item.selectionReasons, kind, `${label}.selectionReasons`, { empty: false });
+    digest(item.itemDigest, kind, `${label}.itemDigest`);
+    validateJsonValue(item.value);
+    if (item.verification !== undefined) validateJsonValue(item.verification);
+  }
+  ids(hydratedIds, kind, `${kind}.hydrated item ids`);
+  const deferredIds = [];
+  for (const [index, item] of value.deferredItems.entries()) {
+    const label = `${kind}.deferredItems[${index}]`;
+    object(item, kind, label);
+    exactKeys(item, new Set(["id", "itemDigest", "kind", "reason", "scope", "sourceIds", "subject"]), kind, label);
+    deferredIds.push(id(item.id, kind, `${label}.id`));
+    enumeration(item.kind, ["fact", "policy", "reference", "validation-description"], kind, `${label}.kind`);
+    id(item.subject, kind, `${label}.subject`);
+    scope(item.scope, kind, `${label}.scope`);
+    ids(item.sourceIds, kind, `${label}.sourceIds`);
+    digest(item.itemDigest, kind, `${label}.itemDigest`);
+    if (item.reason !== "applicable-not-selected") invalid(kind, `${label}.reason is invalid`);
+  }
+  ids(deferredIds, kind, `${kind}.deferred item ids`);
+  const sourceIds = [];
+  for (const [index, source] of value.sources.entries()) {
+    const label = `${kind}.sources[${index}]`;
+    object(source, kind, label);
+    exactKeys(source, new Set(["actualDigest", "expectedDigest", "freshness", "id", "kind", "locator", "sourceDigest"]), kind, label, new Set(["freshness", "id", "kind", "locator", "sourceDigest"]));
+    sourceIds.push(id(source.id, kind, `${label}.id`));
+    text(source.kind, kind, `${label}.kind`);
+    locator(source.locator, kind, `${label}.locator`);
+    digest(source.sourceDigest, kind, `${label}.sourceDigest`);
+    enumeration(source.freshness, ["current", "drifted", "unreadable", "unverifiable-non-local"], kind, `${label}.freshness`);
+    if (source.expectedDigest !== undefined) optionalDigest(source.expectedDigest, kind, `${label}.expectedDigest`);
+    if (source.actualDigest !== undefined) optionalDigest(source.actualDigest, kind, `${label}.actualDigest`);
+  }
+  ids(sourceIds, kind, `${kind}.source ids`);
+  for (const [index, edge] of value.evidenceEdges.entries()) {
+    const label = `${kind}.evidenceEdges[${index}]`;
+    object(edge, kind, label);
+    exactKeys(edge, new Set(["itemId", "sourceId"]), kind, label);
+    id(edge.itemId, kind, `${label}.itemId`);
+    id(edge.sourceId, kind, `${label}.sourceId`);
+  }
+  for (const [index, target] of value.readTargets.entries()) {
+    const label = `${kind}.readTargets[${index}]`;
+    object(target, kind, label);
+    exactKeys(target, new Set(["path", "reason", "sourceId"]), kind, label, new Set(["path", "reason"]));
+    projectPaths([target.path], kind, `${label}.path`, { empty: false });
+    enumeration(target.reason, ["task-target", "host-changed-path-signal", "contract-source"], kind, `${label}.reason`);
+    if (target.sourceId !== undefined) id(target.sourceId, kind, `${label}.sourceId`);
+  }
+  const findingKeys = new Set(["actual", "actualDigest", "code", "conflicts", "expected", "expectedDigest", "itemId", "itemIds", "limit", "path", "paths", "projectFinding", "reason", "required", "requiredItemId", "severity", "sourceId", "state", "subject", "target"]);
+  for (const [index, finding] of value.findings.entries()) {
+    const label = `${kind}.findings[${index}]`;
+    object(finding, kind, label);
+    exactKeys(finding, findingKeys, kind, label, new Set(["code", "severity"]));
+    text(finding.code, kind, `${label}.code`);
+    enumeration(finding.severity, ["attention", "needs-expansion", "blocked"], kind, `${label}.severity`);
+    for (const key of ["itemId", "requiredItemId", "sourceId", "subject"]) if (finding[key] !== undefined) id(finding[key], kind, `${label}.${key}`);
+    if (finding.itemIds !== undefined) ids(finding.itemIds, kind, `${label}.itemIds`);
+    if (finding.paths !== undefined) projectPaths(finding.paths, kind, `${label}.paths`);
+    if (finding.path !== undefined) projectPaths([finding.path], kind, `${label}.path`, { empty: false });
+    for (const key of ["limit", "required", "target"]) if (finding[key] !== undefined) integer(finding[key], kind, `${label}.${key}`);
+    validateJsonValue(finding);
+  }
+  for (const [index, target] of value.targetStates.entries()) {
+    const label = `${kind}.targetStates[${index}]`;
+    object(target, kind, label);
+    exactKeys(target, new Set(["path", "state"]), kind, label);
+    projectPaths([target.path], kind, `${label}.path`, { empty: false });
+    enumeration(target.state, ["existing", "prospective-or-deleted"], kind, `${label}.state`);
+  }
+  uniqueStrings(value.excluded, kind, `${kind}.excluded`, { empty: true });
+  object(value.metrics, kind, `${kind}.metrics`);
+  const metricKeys = new Set(["deferredItemCount", "hostToolCalls", "hydratedItemCount", "retainedItemCount", "sourceBodyReads", "sourceDigestReads", "sourceIdentityReads"]);
+  exactKeys(value.metrics, metricKeys, kind, `${kind}.metrics`);
+  for (const key of metricKeys) integer(value.metrics[key], kind, `${kind}.metrics.${key}`);
+  if (value.metrics.hostToolCalls !== 1) invalid(kind, "adaptive context must remain one Host tool call");
+  object(value.budget, kind, `${kind}.budget`);
+  exactKeys(value.budget, new Set(["audit", "delivery", "readTargets", "unit"]), kind, `${kind}.budget`);
+  if (value.budget.unit !== "canonical-utf8-bytes") invalid(kind, "adaptive context budget unit is invalid");
+  object(value.budget.audit, kind, `${kind}.budget.audit`);
+  exactKeys(value.budget.audit, new Set(["maxUtf8Bytes", "targetUtf8Bytes", "usedUtf8Bytes"]), kind, `${kind}.budget.audit`);
+  integer(value.budget.audit.targetUtf8Bytes, kind, `${kind}.budget.audit.targetUtf8Bytes`, 1);
+  integer(value.budget.audit.maxUtf8Bytes, kind, `${kind}.budget.audit.maxUtf8Bytes`, 1);
+  integer(value.budget.audit.usedUtf8Bytes, kind, `${kind}.budget.audit.usedUtf8Bytes`, 1);
+  object(value.budget.delivery, kind, `${kind}.budget.delivery`);
+  exactKeys(value.budget.delivery, new Set(["completeBelowUtf8Bytes", "maxUtf8Bytes", "usedUtf8Bytes"]), kind, `${kind}.budget.delivery`);
+  integer(value.budget.delivery.completeBelowUtf8Bytes, kind, `${kind}.budget.delivery.completeBelowUtf8Bytes`, 1);
+  integer(value.budget.delivery.maxUtf8Bytes, kind, `${kind}.budget.delivery.maxUtf8Bytes`, 1);
+  integer(value.budget.delivery.usedUtf8Bytes, kind, `${kind}.budget.delivery.usedUtf8Bytes`);
+  object(value.budget.readTargets, kind, `${kind}.budget.readTargets`);
+  exactKeys(value.budget.readTargets, new Set(["count", "max", "target"]), kind, `${kind}.budget.readTargets`);
+  integer(value.budget.readTargets.target, kind, `${kind}.budget.readTargets.target`, 1);
+  integer(value.budget.readTargets.max, kind, `${kind}.budget.readTargets.max`, 1);
+  integer(value.budget.readTargets.count, kind, `${kind}.budget.readTargets.count`);
+  if (value.budget.readTargets.count !== value.readTargets.length) invalid(kind, "read target count does not match bundle");
+  object(value.delivery, kind, `${kind}.delivery`);
+  exactKeys(value.delivery, new Set(["contentDigest", "format", "itemIds", "mode", "status", "utf8Bytes"]), kind, `${kind}.delivery`);
+  enumeration(value.delivery.status, ["ready", "withheld"], kind, `${kind}.delivery.status`);
+  if (value.delivery.format !== "project-context-markdown") invalid(kind, `${kind}.delivery.format is invalid`);
+  const deliveryIds = ids(value.delivery.itemIds, kind, `${kind}.delivery.itemIds`);
+  integer(value.delivery.utf8Bytes, kind, `${kind}.delivery.utf8Bytes`);
+  if (value.delivery.status === "ready") {
+    enumeration(value.delivery.mode, ["adaptive", "complete"], kind, `${kind}.delivery.mode`);
+    digest(value.delivery.contentDigest, kind, `${kind}.delivery.contentDigest`);
+    if (value.delivery.utf8Bytes === 0) invalid(kind, "ready delivery must contain rendered bytes");
+    if (value.budget?.delivery?.usedUtf8Bytes !== value.delivery.utf8Bytes) invalid(kind, "delivery byte count does not match budget accounting");
+    const available = new Set([...value.retainedItemIds, ...value.hydratedItems.map((entry) => entry.id)]);
+    if (deliveryIds.some((entry) => !available.has(entry))) invalid(kind, "delivery item ids are not backed by hydrated or retained items");
+  } else if (value.delivery.mode !== null || value.delivery.contentDigest !== null || deliveryIds.length !== 0 || value.delivery.utf8Bytes !== 0) {
+    invalid(kind, "withheld delivery must not expose consumable content metadata");
+  }
+  if ((value.taskHealth === "ready") !== (value.delivery.status === "ready")) invalid(kind, "task health and delivery status disagree");
+  try { validateJsonValue(value); } catch (error) { invalid(kind, `${kind} must be JSON-compatible`, { reason: error.message }); }
+  return value;
+}
+
+export function sameCanonical(left, right) { return canonicalJson(left) === canonicalJson(right); }