frontend-project-context 1.2.0 → 1.3.1

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

@@ -0,0 +1,526 @@
+import { canonicalJson, canonicalValue, digestJson, validateJsonValue } from "./canonical-json.mjs";
+import { fail } from "./errors.mjs";
+import { normalizeRelativePath } from "./path-policy.mjs";
+
+export const TASK_CONTEXT_PLAN_SCHEMA_VERSION = 1;
+export const STAGE_RECEIPT_SCHEMA_VERSION = 1;
+export const STAGE_CONTEXT_BUNDLE_SCHEMA_VERSION = 1;
+export const INTEGRATION_REVIEW_BUNDLE_SCHEMA_VERSION = 1;
+export const CONTEXT_BUDGET_UNIT = "canonical-utf8-bytes";
+
+const ID = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/u;
+const SHA256 = /^sha256:[a-f0-9]{64}$/u;
+const FORBIDDEN = /^(?:write|approve|approval|by|token|secret|shell|command|provider|autoRun|authority|execute|execution)$/iu;
+
+function invalid(kind, message, details) {
+  fail(`${kind}-schema-invalid`, message, { details });
+}
+
+function object(value, label, kind) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalid(kind, `${label} must be an object`);
+}
+
+function exactKeys(value, allowed, label, kind) {
+  for (const key of Object.keys(value)) {
+    if (FORBIDDEN.test(key)) invalid(kind, `${label} contains forbidden authority or execution field: ${key}`);
+    if (!allowed.has(key)) invalid(kind, `${label} contains unknown field: ${key}`);
+  }
+}
+
+function string(value, label, kind, options = {}) {
+  if (typeof value !== "string" || (!options.empty && value.length === 0)) invalid(kind, `${label} must be a non-empty string`);
+}
+
+function stableId(value, label, kind) {
+  string(value, label, kind);
+  if (!ID.test(value)) invalid(kind, `${label} must use stable lowercase dot/kebab naming`);
+}
+
+function digest(value, label, kind) {
+  string(value, label, kind);
+  if (!SHA256.test(value)) invalid(kind, `${label} must be sha256`);
+}
+
+function uniqueStrings(values, label, kind, 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) {
+    string(value, `${label} entry`, kind);
+    if (seen.has(value)) invalid(kind, `${label} contains duplicate value: ${value}`);
+    seen.add(value);
+  }
+  return [...values].sort((left, right) => left.localeCompare(right));
+}
+
+function paths(values, label, kind, options = {}) {
+  const original = uniqueStrings(values, label, kind, options);
+  const normalized = original.map((value) => {
+    try {
+      return normalizeRelativePath(value, { label: `${label} entry` });
+    } catch (error) {
+      invalid(kind, `${label} must stay inside the project`, { path: value, reason: error.code ?? "invalid-path" });
+    }
+  });
+  if (new Set(normalized).size !== normalized.length) invalid(kind, `${label} contains duplicate normalized paths`);
+  return normalized.sort((left, right) => left.localeCompare(right));
+}
+
+function snapshots(value, label, kind) {
+  object(value, label, kind);
+  exactKeys(value, new Set(["contract", "sourcesLock", "projectionsLock"]), label, kind);
+  for (const key of ["contract", "sourcesLock", "projectionsLock"]) digest(value[key], `${label}.${key}`, kind);
+  return canonicalValue(value);
+}
+
+function isWithin(target, scope) {
+  return target === scope || target.startsWith(`${scope}/`);
+}
+
+function overlaps(left, right) {
+  return isWithin(left, right) || isWithin(right, left);
+}
+
+function transitiveDependencies(stages) {
+  const byId = new Map(stages.map((stage) => [stage.id, stage]));
+  const memo = new Map();
+  const visiting = new Set();
+  function visit(id) {
+    if (memo.has(id)) return memo.get(id);
+    if (visiting.has(id)) invalid("task-context-plan", `task context plan contains a dependency cycle at ${id}`);
+    visiting.add(id);
+    const dependencies = new Set();
+    for (const dependency of byId.get(id).dependsOn) {
+      if (!byId.has(dependency)) invalid("task-context-plan", `stage ${id} depends on unknown stage: ${dependency}`);
+      dependencies.add(dependency);
+      for (const inherited of visit(dependency)) dependencies.add(inherited);
+    }
+    visiting.delete(id);
+    memo.set(id, dependencies);
+    return dependencies;
+  }
+  for (const stage of stages) visit(stage.id);
+  return memo;
+}
+
+export function validateTaskContextPlan(input) {
+  const kind = "task-context-plan";
+  object(input, "task context plan", kind);
+  exactKeys(input, new Set(["schemaVersion", "kind", "projectId", "task", "workspace", "snapshots", "budget", "stages"]), "task context plan", kind);
+  if (input.schemaVersion !== TASK_CONTEXT_PLAN_SCHEMA_VERSION) invalid(kind, `task context plan schemaVersion must be ${TASK_CONTEXT_PLAN_SCHEMA_VERSION}`);
+  if (input.kind !== "task-context-plan") invalid(kind, "task context plan.kind must be task-context-plan");
+  stableId(input.projectId, "task context plan.projectId", kind);
+
+  object(input.task, "task context plan.task", kind);
+  exactKeys(input.task, new Set(["id", "title", "goal", "acceptance"]), "task context plan.task", kind);
+  stableId(input.task.id, "task context plan.task.id", kind);
+  string(input.task.title, "task context plan.task.title", kind);
+  string(input.task.goal, "task context plan.task.goal", kind);
+  if (!Array.isArray(input.task.acceptance) || input.task.acceptance.length === 0) invalid(kind, "task context plan.task.acceptance must be a non-empty array");
+  const acceptanceIds = new Set();
+  const acceptance = input.task.acceptance.map((entry, index) => {
+    const label = `task context plan.task.acceptance[${index}]`;
+    object(entry, label, kind);
+    exactKeys(entry, new Set(["id", "text"]), label, kind);
+    stableId(entry.id, `${label}.id`, kind);
+    string(entry.text, `${label}.text`, kind);
+    if (acceptanceIds.has(entry.id)) invalid(kind, `task context plan contains duplicate acceptance id: ${entry.id}`);
+    acceptanceIds.add(entry.id);
+    return { id: entry.id, text: entry.text };
+  }).sort((left, right) => left.id.localeCompare(right.id));
+
+  object(input.workspace, "task context plan.workspace", kind);
+  exactKeys(input.workspace, new Set(["branchLabel", "baseRevision"]), "task context plan.workspace", kind);
+  string(input.workspace.branchLabel, "task context plan.workspace.branchLabel", kind);
+  string(input.workspace.baseRevision, "task context plan.workspace.baseRevision", kind);
+
+  object(input.budget, "task context plan.budget", kind);
+  exactKeys(input.budget, new Set(["maxUtf8Bytes", "maxReadTargets"]), "task context plan.budget", kind);
+  for (const key of ["maxUtf8Bytes", "maxReadTargets"]) {
+    if (!Number.isSafeInteger(input.budget[key]) || input.budget[key] <= 0) invalid(kind, `task context plan.budget.${key} must be a positive integer`);
+  }
+
+  if (!Array.isArray(input.stages) || input.stages.length === 0) invalid(kind, "task context plan.stages must be a non-empty array");
+  const stageIds = new Set();
+  const stages = input.stages.map((stage, index) => {
+    const label = `task context plan.stages[${index}]`;
+    object(stage, label, kind);
+    exactKeys(stage, new Set(["id", "title", "objective", "dependsOn", "paths", "acceptanceIds"]), label, kind);
+    stableId(stage.id, `${label}.id`, kind);
+    if (stageIds.has(stage.id)) invalid(kind, `task context plan contains duplicate stage id: ${stage.id}`);
+    stageIds.add(stage.id);
+    string(stage.title, `${label}.title`, kind);
+    string(stage.objective, `${label}.objective`, kind);
+    const dependsOn = uniqueStrings(stage.dependsOn, `${label}.dependsOn`, kind, { empty: true });
+    dependsOn.forEach((id) => stableId(id, `${label}.dependsOn entry`, kind));
+    if (dependsOn.includes(stage.id)) invalid(kind, `stage ${stage.id} cannot depend on itself`);
+    const acceptanceForStage = uniqueStrings(stage.acceptanceIds, `${label}.acceptanceIds`, kind);
+    acceptanceForStage.forEach((id) => {
+      stableId(id, `${label}.acceptanceIds entry`, kind);
+      if (!acceptanceIds.has(id)) invalid(kind, `stage ${stage.id} references unknown acceptance id: ${id}`);
+    });
+    return {
+      id: stage.id,
+      title: stage.title,
+      objective: stage.objective,
+      dependsOn,
+      paths: paths(stage.paths, `${label}.paths`, kind),
+      acceptanceIds: acceptanceForStage,
+    };
+  }).sort((left, right) => left.id.localeCompare(right.id));
+  const dependencies = transitiveDependencies(stages);
+  for (let leftIndex = 0; leftIndex < stages.length; leftIndex += 1) {
+    for (let rightIndex = leftIndex + 1; rightIndex < stages.length; rightIndex += 1) {
+      const left = stages[leftIndex];
+      const right = stages[rightIndex];
+      if (dependencies.get(left.id).has(right.id) || dependencies.get(right.id).has(left.id)) continue;
+      const conflict = left.paths.find((leftPath) => right.paths.some((rightPath) => overlaps(leftPath, rightPath)));
+      if (conflict) invalid(kind, `independent stages ${left.id} and ${right.id} have overlapping paths`, { path: conflict });
+    }
+  }
+
+  return canonicalValue({
+    schemaVersion: TASK_CONTEXT_PLAN_SCHEMA_VERSION,
+    kind: "task-context-plan",
+    projectId: input.projectId,
+    task: { id: input.task.id, title: input.task.title, goal: input.task.goal, acceptance },
+    workspace: { branchLabel: input.workspace.branchLabel, baseRevision: input.workspace.baseRevision },
+    snapshots: snapshots(input.snapshots, "task context plan.snapshots", kind),
+    budget: { maxUtf8Bytes: input.budget.maxUtf8Bytes, maxReadTargets: input.budget.maxReadTargets },
+    stages,
+  });
+}
+
+export function taskContextPlanDigest(plan) {
+  return digestJson(validateTaskContextPlan(plan));
+}
+
+function acceptanceResult(value, label, kind) {
+  object(value, label, kind);
+  exactKeys(value, new Set(["id", "status", "evidence"]), label, kind);
+  stableId(value.id, `${label}.id`, kind);
+  if (!["observed", "not-observed"].includes(value.status)) invalid(kind, `${label}.status must be observed or not-observed`);
+  return { id: value.id, status: value.status, evidence: paths(value.evidence, `${label}.evidence`, kind, { empty: true }) };
+}
+
+function verificationResult(value, label, kind) {
+  object(value, label, kind);
+  exactKeys(value, new Set(["id", "status", "summary", "evidence"]), label, kind);
+  stableId(value.id, `${label}.id`, kind);
+  if (!["passed", "failed", "observed", "skipped"].includes(value.status)) invalid(kind, `${label}.status is invalid`);
+  string(value.summary, `${label}.summary`, kind);
+  return { id: value.id, status: value.status, summary: value.summary, evidence: paths(value.evidence, `${label}.evidence`, kind, { empty: true }) };
+}
+
+export function validateStageReceipt(input, planInput, options = {}) {
+  const kind = "stage-receipt";
+  object(input, "stage receipt", kind);
+  exactKeys(input, new Set([
+    "schemaVersion", "kind", "projectId", "taskId", "stageId", "planDigest", "inputBundleDigest", "status",
+    "changedPaths", "acceptanceResults", "verificationResults", "decisions", "openIssues", "nextStageId",
+  ]), "stage receipt", kind);
+  if (input.schemaVersion !== STAGE_RECEIPT_SCHEMA_VERSION) invalid(kind, `stage receipt schemaVersion must be ${STAGE_RECEIPT_SCHEMA_VERSION}`);
+  if (input.kind !== "stage-receipt") invalid(kind, "stage receipt.kind must be stage-receipt");
+  for (const [field, label] of [["projectId", "projectId"], ["taskId", "taskId"], ["stageId", "stageId"]]) stableId(input[field], `stage receipt.${label}`, kind);
+  digest(input.planDigest, "stage receipt.planDigest", kind);
+  digest(input.inputBundleDigest, "stage receipt.inputBundleDigest", kind);
+  if (options.expectedInputBundleDigest !== undefined && input.inputBundleDigest !== options.expectedInputBundleDigest) {
+    invalid(kind, "stage receipt input bundle digest is stale", { expected: options.expectedInputBundleDigest, actual: input.inputBundleDigest });
+  }
+  if (!["completed", "blocked"].includes(input.status)) invalid(kind, "stage receipt.status must be completed or blocked");
+  const changedPaths = paths(input.changedPaths, "stage receipt.changedPaths", kind, { empty: true });
+  if (!Array.isArray(input.acceptanceResults)) invalid(kind, "stage receipt.acceptanceResults must be an array");
+  const resultIds = new Set();
+  const acceptanceResults = input.acceptanceResults.map((entry, index) => {
+    const normalized = acceptanceResult(entry, `stage receipt.acceptanceResults[${index}]`, kind);
+    if (resultIds.has(normalized.id)) invalid(kind, `stage receipt contains duplicate acceptance result: ${normalized.id}`);
+    resultIds.add(normalized.id);
+    return normalized;
+  }).sort((left, right) => left.id.localeCompare(right.id));
+  if (!Array.isArray(input.verificationResults)) invalid(kind, "stage receipt.verificationResults must be an array");
+  const verificationIds = new Set();
+  const verificationResults = input.verificationResults.map((entry, index) => {
+    const normalized = verificationResult(entry, `stage receipt.verificationResults[${index}]`, kind);
+    if (verificationIds.has(normalized.id)) invalid(kind, `stage receipt contains duplicate verification result: ${normalized.id}`);
+    verificationIds.add(normalized.id);
+    return normalized;
+  }).sort((left, right) => left.id.localeCompare(right.id));
+  const decisions = uniqueStrings(input.decisions, "stage receipt.decisions", kind, { empty: true });
+  const openIssues = uniqueStrings(input.openIssues, "stage receipt.openIssues", kind, { empty: true });
+  if (input.status === "blocked" && openIssues.length === 0) invalid(kind, "blocked stage receipt requires at least one open issue");
+  if (input.status === "completed" && openIssues.length > 0) invalid(kind, "completed stage receipt cannot contain open issues");
+  if (input.nextStageId !== undefined) stableId(input.nextStageId, "stage receipt.nextStageId", kind);
+
+  if (planInput !== undefined) {
+    const plan = validateTaskContextPlan(planInput);
+    if (input.projectId !== plan.projectId || input.taskId !== plan.task.id) invalid(kind, "stage receipt project or task does not match its plan");
+    if (input.planDigest !== digestJson(plan)) invalid(kind, "stage receipt plan digest is stale");
+    const stage = plan.stages.find((entry) => entry.id === input.stageId);
+    if (!stage) invalid(kind, `stage receipt references unknown stage: ${input.stageId}`);
+    for (const id of resultIds) if (!stage.acceptanceIds.includes(id)) invalid(kind, `stage receipt references acceptance outside stage: ${id}`);
+    if (input.status === "completed") {
+      const missing = stage.acceptanceIds.filter((id) => !resultIds.has(id));
+      if (missing.length > 0) invalid(kind, "completed stage receipt does not cover all stage acceptance IDs", { missing });
+      if (acceptanceResults.some((entry) => entry.status !== "observed")) invalid(kind, "completed stage receipt requires observed acceptance results");
+    }
+    if (input.nextStageId !== undefined && !plan.stages.some((entry) => entry.id === input.nextStageId)) invalid(kind, `stage receipt references unknown next stage: ${input.nextStageId}`);
+  }
+
+  return canonicalValue({
+    schemaVersion: STAGE_RECEIPT_SCHEMA_VERSION,
+    kind: "stage-receipt",
+    projectId: input.projectId,
+    taskId: input.taskId,
+    stageId: input.stageId,
+    planDigest: input.planDigest,
+    inputBundleDigest: input.inputBundleDigest,
+    status: input.status,
+    changedPaths,
+    acceptanceResults,
+    verificationResults,
+    decisions,
+    openIssues,
+    ...(input.nextStageId !== undefined ? { nextStageId: input.nextStageId } : {}),
+  });
+}
+
+export function stageReceiptDigest(receipt, plan) {
+  return digestJson(validateStageReceipt(receipt, plan));
+}
+
+function requiredKeys(value, required, label, kind) {
+  for (const key of required) {
+    if (!Object.hasOwn(value, key)) invalid(kind, `${label} is missing required field: ${key}`);
+  }
+}
+
+function canonicalPaths(value, label, kind, options = {}) {
+  const normalized = paths(value, label, kind, options);
+  if (canonicalJson(value) !== canonicalJson(normalized)) invalid(kind, `${label} must be sorted canonical project-relative paths`);
+}
+
+function canonicalTexts(value, label, kind, options = {}) {
+  const normalized = uniqueStrings(value, label, kind, options);
+  if (canonicalJson(value) !== canonicalJson(normalized)) invalid(kind, `${label} must be sorted unique strings`);
+}
+
+function positiveInteger(value, label, kind) {
+  if (!Number.isSafeInteger(value) || value <= 0) invalid(kind, `${label} must be a positive integer`);
+}
+
+function nonNegativeInteger(value, label, kind) {
+  if (!Number.isSafeInteger(value) || value < 0) invalid(kind, `${label} must be a non-negative integer`);
+}
+
+function validateIdentity(value, label, kind) {
+  object(value, label, kind);
+  requiredKeys(value, ["id", "name"], label, kind);
+  exactKeys(value, new Set(["id", "name"]), label, kind);
+  stableId(value.id, `${label}.id`, kind);
+  string(value.name, `${label}.name`, kind);
+}
+
+function validateBundleTask(value, label, kind) {
+  object(value, label, kind);
+  requiredKeys(value, ["id", "title", "goal"], label, kind);
+  exactKeys(value, new Set(["id", "title", "goal"]), label, kind);
+  stableId(value.id, `${label}.id`, kind);
+  string(value.title, `${label}.title`, kind);
+  string(value.goal, `${label}.goal`, kind);
+}
+
+function validateBundleWorkspace(value, label, kind) {
+  object(value, label, kind);
+  requiredKeys(value, ["branchLabel", "baseRevision"], label, kind);
+  exactKeys(value, new Set(["branchLabel", "baseRevision"]), label, kind);
+  string(value.branchLabel, `${label}.branchLabel`, kind);
+  string(value.baseRevision, `${label}.baseRevision`, kind);
+}
+
+function validateBundleStage(value, label, kind) {
+  object(value, label, kind);
+  requiredKeys(value, ["id", "title", "objective", "acceptance", "paths"], label, kind);
+  exactKeys(value, new Set(["id", "title", "objective", "acceptance", "paths"]), label, kind);
+  stableId(value.id, `${label}.id`, kind);
+  string(value.title, `${label}.title`, kind);
+  string(value.objective, `${label}.objective`, kind);
+  if (!Array.isArray(value.acceptance) || value.acceptance.length === 0) invalid(kind, `${label}.acceptance must be a non-empty array`);
+  const acceptanceIds = new Set();
+  for (const [index, entry] of value.acceptance.entries()) {
+    const entryLabel = `${label}.acceptance[${index}]`;
+    object(entry, entryLabel, kind);
+    requiredKeys(entry, ["id", "text"], entryLabel, kind);
+    exactKeys(entry, new Set(["id", "text"]), entryLabel, kind);
+    stableId(entry.id, `${entryLabel}.id`, kind);
+    string(entry.text, `${entryLabel}.text`, kind);
+    if (acceptanceIds.has(entry.id)) invalid(kind, `${label}.acceptance contains duplicate id: ${entry.id}`);
+    acceptanceIds.add(entry.id);
+  }
+  const sortedAcceptanceIds = [...acceptanceIds].sort((left, right) => left.localeCompare(right));
+  if (canonicalJson(value.acceptance.map((entry) => entry.id)) !== canonicalJson(sortedAcceptanceIds)) {
+    invalid(kind, `${label}.acceptance must be sorted by id`);
+  }
+  canonicalPaths(value.paths, `${label}.paths`, kind);
+}
+
+function validateReceiptSummary(value, label, kind) {
+  object(value, label, kind);
+  const keys = ["stageId", "status", "inputBundleDigest", "changedPaths", "acceptanceResults", "verificationResults", "decisions", "openIssues"];
+  requiredKeys(value, keys, label, kind);
+  exactKeys(value, new Set(keys), label, kind);
+  stableId(value.stageId, `${label}.stageId`, kind);
+  if (!["completed", "blocked"].includes(value.status)) invalid(kind, `${label}.status must be completed or blocked`);
+  digest(value.inputBundleDigest, `${label}.inputBundleDigest`, kind);
+  canonicalPaths(value.changedPaths, `${label}.changedPaths`, kind, { empty: true });
+  if (!Array.isArray(value.acceptanceResults)) invalid(kind, `${label}.acceptanceResults must be an array`);
+  const acceptanceIds = new Set();
+  for (const [index, entry] of value.acceptanceResults.entries()) {
+    acceptanceResult(entry, `${label}.acceptanceResults[${index}]`, kind);
+    if (acceptanceIds.has(entry.id)) invalid(kind, `${label}.acceptanceResults contains duplicate id: ${entry.id}`);
+    acceptanceIds.add(entry.id);
+  }
+  if (canonicalJson(value.acceptanceResults.map((entry) => entry.id)) !== canonicalJson([...acceptanceIds].sort((left, right) => left.localeCompare(right)))) {
+    invalid(kind, `${label}.acceptanceResults must be sorted by id`);
+  }
+  if (!Array.isArray(value.verificationResults)) invalid(kind, `${label}.verificationResults must be an array`);
+  const verificationIds = new Set();
+  for (const [index, entry] of value.verificationResults.entries()) {
+    verificationResult(entry, `${label}.verificationResults[${index}]`, kind);
+    if (verificationIds.has(entry.id)) invalid(kind, `${label}.verificationResults contains duplicate id: ${entry.id}`);
+    verificationIds.add(entry.id);
+  }
+  if (canonicalJson(value.verificationResults.map((entry) => entry.id)) !== canonicalJson([...verificationIds].sort((left, right) => left.localeCompare(right)))) {
+    invalid(kind, `${label}.verificationResults must be sorted by id`);
+  }
+  canonicalTexts(value.decisions, `${label}.decisions`, kind, { empty: true });
+  canonicalTexts(value.openIssues, `${label}.openIssues`, kind, { empty: true });
+}
+
+function validateBundleScope(value, label, kind) {
+  object(value, label, kind);
+  exactKeys(value, new Set(["kind", "path"]), label, kind);
+  if (!["project", "path-prefix", "file"].includes(value.kind)) invalid(kind, `${label}.kind is invalid`);
+  if (value.kind === "project") {
+    if (value.path !== undefined) invalid(kind, `${label}.path is not allowed for project scope`);
+  } else {
+    canonicalPaths([value.path], `${label}.path`, kind);
+  }
+}
+
+function validateContractItem(value, label, kind) {
+  object(value, label, kind);
+  const keys = ["id", "kind", "subject", "value", "statement", "scope", "sourceIds"];
+  requiredKeys(value, keys, label, kind);
+  exactKeys(value, new Set(keys), label, kind);
+  stableId(value.id, `${label}.id`, kind);
+  if (!["fact", "policy", "reference", "validation-description"].includes(value.kind)) invalid(kind, `${label}.kind is invalid`);
+  stableId(value.subject, `${label}.subject`, kind);
+  try {
+    validateJsonValue(value.value);
+  } catch (error) {
+    invalid(kind, `${label}.value must be strict JSON`, { reason: error.message });
+  }
+  string(value.statement, `${label}.statement`, kind);
+  validateBundleScope(value.scope, `${label}.scope`, kind);
+  const sourceIds = uniqueStrings(value.sourceIds, `${label}.sourceIds`, kind);
+  sourceIds.forEach((id) => stableId(id, `${label}.sourceIds entry`, kind));
+  if (canonicalJson(value.sourceIds) !== canonicalJson(sourceIds)) invalid(kind, `${label}.sourceIds must be sorted`);
+}
+
+function validateFinding(value, label, kind) {
+  object(value, label, kind);
+  requiredKeys(value, ["code", "severity"], label, kind);
+  stableId(value.code, `${label}.code`, kind);
+  if (!["attention", "blocked"].includes(value.severity)) invalid(kind, `${label}.severity is invalid`);
+  try {
+    validateJsonValue(value);
+  } catch (error) {
+    invalid(kind, `${label} must be strict JSON`, { reason: error.message });
+  }
+}
+
+export function validateStageContextBundle(input) {
+  const kind = "stage-context-bundle";
+  object(input, "stage context bundle", kind);
+  const keys = [
+    "schemaVersion", "kind", "project", "task", "stage", "workspace", "planDigest", "snapshots",
+    "dependencyReceipts", "changedPaths", "contractItems", "readTargets", "findings", "excluded", "budget", "status", "bundleDigest",
+  ];
+  requiredKeys(input, keys, "stage context bundle", kind);
+  exactKeys(input, new Set(keys), "stage context bundle", kind);
+  if (input.schemaVersion !== STAGE_CONTEXT_BUNDLE_SCHEMA_VERSION) invalid(kind, `stage context bundle schemaVersion must be ${STAGE_CONTEXT_BUNDLE_SCHEMA_VERSION}`);
+  if (input.kind !== "stage-context-bundle") invalid(kind, "stage context bundle.kind must be stage-context-bundle");
+  validateIdentity(input.project, "stage context bundle.project", kind);
+  validateBundleTask(input.task, "stage context bundle.task", kind);
+  validateBundleStage(input.stage, "stage context bundle.stage", kind);
+  validateBundleWorkspace(input.workspace, "stage context bundle.workspace", kind);
+  digest(input.planDigest, "stage context bundle.planDigest", kind);
+  snapshots(input.snapshots, "stage context bundle.snapshots", kind);
+  if (!Array.isArray(input.dependencyReceipts)) invalid(kind, "stage context bundle.dependencyReceipts must be an array");
+  const dependencyIds = new Set();
+  for (const [index, entry] of input.dependencyReceipts.entries()) {
+    validateReceiptSummary(entry, `stage context bundle.dependencyReceipts[${index}]`, kind);
+    if (dependencyIds.has(entry.stageId)) invalid(kind, `stage context bundle contains duplicate dependency receipt: ${entry.stageId}`);
+    dependencyIds.add(entry.stageId);
+  }
+  if (canonicalJson(input.dependencyReceipts.map((entry) => entry.stageId)) !== canonicalJson([...dependencyIds].sort((left, right) => left.localeCompare(right)))) {
+    invalid(kind, "stage context bundle.dependencyReceipts must be sorted by stageId");
+  }
+  canonicalPaths(input.changedPaths, "stage context bundle.changedPaths", kind, { empty: true });
+  if (!Array.isArray(input.contractItems)) invalid(kind, "stage context bundle.contractItems must be an array");
+  const itemIds = new Set();
+  for (const [index, entry] of input.contractItems.entries()) {
+    validateContractItem(entry, `stage context bundle.contractItems[${index}]`, kind);
+    if (itemIds.has(entry.id)) invalid(kind, `stage context bundle contains duplicate contract item: ${entry.id}`);
+    itemIds.add(entry.id);
+  }
+  if (canonicalJson(input.contractItems.map((entry) => entry.id)) !== canonicalJson([...itemIds].sort((left, right) => left.localeCompare(right)))) {
+    invalid(kind, "stage context bundle.contractItems must be sorted by id");
+  }
+  if (!Array.isArray(input.readTargets)) invalid(kind, "stage context bundle.readTargets must be an array");
+  const readPaths = new Set();
+  for (const [index, entry] of input.readTargets.entries()) {
+    const label = `stage context bundle.readTargets[${index}]`;
+    object(entry, label, kind);
+    requiredKeys(entry, ["path", "reason"], label, kind);
+    exactKeys(entry, new Set(["path", "reason", "sourceId"]), label, kind);
+    canonicalPaths([entry.path], `${label}.path`, kind);
+    if (!["stage-scope", "host-changed-path-signal", "contract-source"].includes(entry.reason)) invalid(kind, `${label}.reason is invalid`);
+    if (entry.reason === "contract-source") stableId(entry.sourceId, `${label}.sourceId`, kind);
+    else if (entry.sourceId !== undefined) invalid(kind, `${label}.sourceId requires contract-source reason`);
+    if (readPaths.has(entry.path)) invalid(kind, `stage context bundle contains duplicate read target: ${entry.path}`);
+    readPaths.add(entry.path);
+  }
+  if (canonicalJson(input.readTargets.map((entry) => entry.path)) !== canonicalJson([...readPaths].sort((left, right) => left.localeCompare(right)))) {
+    invalid(kind, "stage context bundle.readTargets must be sorted by path");
+  }
+  if (!Array.isArray(input.findings)) invalid(kind, "stage context bundle.findings must be an array");
+  input.findings.forEach((entry, index) => validateFinding(entry, `stage context bundle.findings[${index}]`, kind));
+  canonicalTexts(input.excluded, "stage context bundle.excluded", kind);
+  object(input.budget, "stage context bundle.budget", kind);
+  const budgetKeys = ["unit", "maxUtf8Bytes", "maxReadTargets", "usedUtf8Bytes", "readTargetCount"];
+  requiredKeys(input.budget, budgetKeys, "stage context bundle.budget", kind);
+  exactKeys(input.budget, new Set(budgetKeys), "stage context bundle.budget", kind);
+  if (input.budget.unit !== CONTEXT_BUDGET_UNIT) invalid(kind, `stage context bundle.budget.unit must be ${CONTEXT_BUDGET_UNIT}`);
+  positiveInteger(input.budget.maxUtf8Bytes, "stage context bundle.budget.maxUtf8Bytes", kind);
+  positiveInteger(input.budget.maxReadTargets, "stage context bundle.budget.maxReadTargets", kind);
+  nonNegativeInteger(input.budget.usedUtf8Bytes, "stage context bundle.budget.usedUtf8Bytes", kind);
+  nonNegativeInteger(input.budget.readTargetCount, "stage context bundle.budget.readTargetCount", kind);
+  if (input.budget.readTargetCount !== input.readTargets.length) invalid(kind, "stage context bundle read target count is invalid");
+  if (!["ready", "blocked"].includes(input.status)) invalid(kind, "stage context bundle.status must be ready or blocked");
+  digest(input.bundleDigest, "stage context bundle.bundleDigest", kind);
+
+  const normalized = canonicalValue(input);
+  const withoutDigest = structuredClone(normalized);
+  delete withoutDigest.bundleDigest;
+  const expectedDigest = digestJson(withoutDigest);
+  if (normalized.bundleDigest !== expectedDigest) {
+    invalid(kind, "stage context bundle digest is invalid", { expected: expectedDigest, actual: normalized.bundleDigest });
+  }
+  const expectedBytes = Buffer.byteLength(canonicalJson(normalized), "utf8");
+  if (normalized.budget.usedUtf8Bytes !== expectedBytes) {
+    invalid(kind, "stage context bundle byte count is invalid", { expected: expectedBytes, actual: normalized.budget.usedUtf8Bytes });
+  }
+  return normalized;
+}