frontend-project-context 1.3.0 → 1.6.0

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

@@ -0,0 +1,157 @@
+import { buildSyncAssistBundle } from "./assist.mjs";
+import { inspectAiEntry } from "./ai-entry.mjs";
+import { checkExitCode, checkProject } from "./checker.mjs";
+import { ProjectContextError } from "./errors.mjs";
+import { PACKAGE_VERSION } from "./exchange-schema.mjs";
+import { inspectProjectInitialization, loadProject } from "./project-store.mjs";
+
+export const PROJECT_STATUS_SCHEMA_VERSION = 1;
+
+function uniqueSorted(values) {
+  return [...new Set(values.filter((value) => value !== undefined && value !== null))]
+    .sort((left, right) => String(left).localeCompare(String(right)));
+}
+
+function emptySummary() {
+  return { findings: 0, changedSources: 0, pendingItems: 0, affectedProjections: 0 };
+}
+
+function compactReadTarget(target) {
+  return {
+    sourceId: target.sourceId,
+    locator: structuredClone(target.locator),
+    reason: target.reason,
+    priority: target.priority,
+  };
+}
+
+function compactWorkUnit(unit) {
+  const compact = { kind: unit.kind };
+  for (const key of ["sourceIds", "itemIds", "fallbackItemIds", "paths", "projectionPaths", "findingCodes"]) {
+    if (unit[key] !== undefined) compact[key] = [...unit[key]];
+  }
+  return compact;
+}
+
+function base(initialization, health, nextActions) {
+  return {
+    schemaVersion: PROJECT_STATUS_SCHEMA_VERSION,
+    package: { name: "frontend-project-context", version: PACKAGE_VERSION },
+    initialization: {
+      state: initialization,
+      present: [],
+      missing: [],
+    },
+    project: null,
+    snapshots: null,
+    health,
+    entry: { state: "absent", path: null, rendererVersion: null },
+    summary: emptySummary(),
+    findingCodes: [],
+    sourceIds: [],
+    itemIds: [],
+    projectionPaths: [],
+    readTargets: [],
+    workUnits: [],
+    nextActions,
+    boundaries: {},
+  };
+}
+
+function statusBoundaries(boundaries) {
+  return structuredClone(boundaries);
+}
+
+export async function buildProjectStatus(root, boundaries) {
+  const initialization = await inspectProjectInitialization(root);
+  if (initialization.status !== "initialized") {
+    const result = base(initialization.status, initialization.status, initialization.status === "uninitialized" ? ["run-setup-preview"] : ["resolve-conflict"]);
+    result.initialization.present = [...initialization.present];
+    result.initialization.missing = [...initialization.missing];
+    if (initialization.status === "partial") result.findingCodes = ["project-state-partial"];
+    result.summary.findings = result.findingCodes.length;
+    result.boundaries = statusBoundaries(boundaries);
+    return { status: result, exitCode: initialization.status === "uninitialized" ? 1 : 2 };
+  }
+
+  let project;
+  try {
+    project = await loadProject(root);
+  } catch (error) {
+    if (!(error instanceof ProjectContextError)) throw error;
+    const result = base("invalid", "invalid", ["resolve-conflict"]);
+    result.initialization.present = [...initialization.present];
+    result.initialization.missing = [...initialization.missing];
+    result.findingCodes = ["project-state-invalid"];
+    result.summary.findings = 1;
+    result.boundaries = statusBoundaries(boundaries);
+    return { status: result, exitCode: 2 };
+  }
+
+  const regionEntries = project.projectionsLock.projections.filter((entry) => entry.ownership === "region" && entry.target === "ai-entry");
+  const entryPath = regionEntries[0]?.path ?? "AGENTS.md";
+  const [sync, entry] = await Promise.all([
+    buildSyncAssistBundle(root, project),
+    inspectAiEntry(root, project, entryPath),
+  ]);
+  const findings = [...sync.findings];
+  if (entry.state === "absent") findings.push({ code: "ai-entry-missing", path: null });
+  if (entry.state === "conflict" && !findings.some((finding) => finding.code === "ai-entry-ownership-conflict")) {
+    findings.push({ code: "ai-entry-ownership-conflict", path: entry.path });
+  }
+  const conflict = entry.state === "conflict" || findings.some((finding) => finding.code.includes("ownership-conflict"));
+  const sourceOrContractBlocker = findings.some((finding) =>
+    finding.code.startsWith("source-") || finding.code.startsWith("verification-") || finding.code.startsWith("scope-") || finding.code === "contract-conflict",
+  );
+  const health = conflict ? "conflict" : findings.length > 0 || entry.state !== "current" ? "attention" : "clean";
+  const nextActions = [];
+  if (conflict) nextActions.push("resolve-conflict");
+  else {
+    if (sync.summary.changedSources > 0 || sourceOrContractBlocker) nextActions.push("review-source-change");
+    if (sync.summary.pendingItems > 0) nextActions.push("review-pending");
+    if (sync.summary.affectedProjections > 0) nextActions.push("review-projection");
+    if (entry.state !== "current") nextActions.push("publish-ai-entry");
+    if (findings.length > 0 && nextActions.length === 0) nextActions.push("run-sync");
+    if (health === "clean") nextActions.push("ready-for-task");
+  }
+  const sourceIds = uniqueSorted([
+    ...findings.flatMap((finding) => finding.source ? [finding.source] : []),
+    ...sync.workUnits.flatMap((unit) => unit.sourceIds ?? []),
+  ]);
+  const itemIds = uniqueSorted([
+    ...findings.flatMap((finding) => finding.items ?? (finding.item ? [finding.item] : [])),
+    ...sync.workUnits.flatMap((unit) => unit.itemIds ?? []),
+  ]);
+  const projectionPaths = uniqueSorted([
+    ...sync.projectionPaths,
+    ...findings.flatMap((finding) => finding.path ? [finding.path] : []),
+  ]);
+  const status = {
+    schemaVersion: PROJECT_STATUS_SCHEMA_VERSION,
+    package: { name: "frontend-project-context", version: PACKAGE_VERSION },
+    initialization: { state: "initialized", present: [...initialization.present], missing: [] },
+    project: { id: project.contract.project.id, name: project.contract.project.name },
+    snapshots: {
+      contract: project.contractDigest,
+      sourcesLock: project.sourcesLockDigest,
+      projectionsLock: project.projectionsLockDigest,
+    },
+    health,
+    entry,
+    summary: {
+      findings: findings.length,
+      changedSources: sync.summary.changedSources,
+      pendingItems: sync.summary.pendingItems,
+      affectedProjections: projectionPaths.length,
+    },
+    findingCodes: uniqueSorted(findings.map((finding) => finding.code)),
+    sourceIds,
+    itemIds,
+    projectionPaths,
+    readTargets: sync.readTargets.map(compactReadTarget),
+    workUnits: sync.workUnits.map(compactWorkUnit),
+    nextActions: uniqueSorted(nextActions),
+    boundaries: statusBoundaries(boundaries),
+  };
+  return { status, exitCode: health === "clean" ? 0 : conflict ? 3 : Math.max(1, checkExitCode(findings)) };
+}

package/src/project-context/projection-store.mjs

@@ -28,6 +28,12 @@ export async function publishProjection(root, project, options, dependencies = {
   const rendered = renderProjection(project.contract, paths, target);
   const existing = await readContent(resolved.absolute);
   const lockEntry = project.projectionsLock.projections.find((entry) => entry.path === resolved.normalized);
+  if (lockEntry?.ownership === "region") {
+    fail("ai-entry-path-conflict", `refusing whole-file projection over managed AI Entry: ${resolved.normalized}`, {
+      exitCode: 3,
+      details: { path: resolved.normalized },
+    });
+  }
   if (existing !== null) {
     const marker = parseProjectionMarker(existing);
     if (
@@ -46,6 +52,7 @@ export async function publishProjection(root, project, options, dependencies = {
   const nextEntry = {
     path: resolved.normalized,
     target,
+    ...(project.projectionsLock.schemaVersion === 2 ? { ownership: "file" } : {}),
     paths: rendered.paths,
     contractDigest: rendered.contractDigest,
     bundleDigest: rendered.bundleDigest,
@@ -54,7 +61,7 @@ export async function publishProjection(root, project, options, dependencies = {
     rendererVersion: rendered.rendererVersion,
   };
   const nextLock = {
-    schemaVersion: 1,
+    schemaVersion: project.projectionsLock.schemaVersion,
     projections: [
       ...project.projectionsLock.projections.filter((entry) => entry.path !== resolved.normalized),
       nextEntry,

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

@@ -1,4 +1,4 @@
-import { canonicalValue, digestJson } from "./canonical-json.mjs";
+import { canonicalJson, canonicalValue, digestJson, validateJsonValue } from "./canonical-json.mjs";
 import { fail } from "./errors.mjs";
 import { normalizeRelativePath } from "./path-policy.mjs";
 
@@ -288,3 +288,239 @@ export function validateStageReceipt(input, planInput, options = {}) {
 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;
+}

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

@@ -10,6 +10,7 @@ import {
   INTEGRATION_REVIEW_BUNDLE_SCHEMA_VERSION,
   STAGE_CONTEXT_BUNDLE_SCHEMA_VERSION,
   taskContextPlanDigest,
+  validateStageContextBundle,
   validateStageReceipt,
   validateTaskContextPlan,
 } from "./task-context-schema.mjs";
@@ -185,17 +186,13 @@ function acceptanceFor(plan, stage) {
   return plan.task.acceptance.filter((entry) => ids.has(entry.id)).map((entry) => structuredClone(entry));
 }
 
-export async function buildStageContextBundle(root, project, planInput, options) {
-  const plan = validateTaskContextPlan(planInput);
-  if (plan.projectId !== project.contract.project.id) fail("task-context-project-mismatch", "task context plan belongs to a different project");
-  await validatePlanPaths(root, plan);
+async function buildStageContextBundleCore(root, project, plan, options, receipts, bindingFindings = []) {
   const stage = plan.stages.find((entry) => entry.id === options.stageId);
   if (!stage) fail("task-context-stage-missing", `task context plan has no stage: ${options.stageId}`);
   const changedPaths = normalizeSignalPaths(options.changedPaths ?? [], "changed path");
   await validateProjectPaths(root, changedPaths, "changed path");
-  const receipts = normalizedReceipts(options.receipts ?? [], plan);
   const planDigest = taskContextPlanDigest(plan);
-  const findings = [...baselineFindings(plan, project), ...checkerFindings(await checkProject(root, project))];
+  const findings = [...bindingFindings, ...baselineFindings(plan, project), ...checkerFindings(await checkProject(root, project))];
   const dependencyReceipts = [];
   for (const dependencyId of stage.dependsOn) {
     const receipt = receipts.get(dependencyId);
@@ -259,6 +256,142 @@ export async function buildStageContextBundle(root, project, planInput, options)
   return bundle;
 }
 
+function sameJson(left, right) {
+  return canonicalJson(left) === canonicalJson(right);
+}
+
+function artifactStageId(input) {
+  return input && typeof input === "object" && !Array.isArray(input) && input.stage
+    && typeof input.stage === "object" && !Array.isArray(input.stage) && typeof input.stage.id === "string"
+    ? input.stage.id
+    : undefined;
+}
+
+async function verifyReceiptBundleBindings(root, project, plan, receipts, receiptBundleInputs) {
+  const findings = [];
+  const candidatesByStage = new Map();
+  for (const input of receiptBundleInputs) {
+    const stageId = artifactStageId(input);
+    let bundle;
+    try {
+      bundle = validateStageContextBundle(input);
+    } catch (error) {
+      if (!(error instanceof ProjectContextError) || error.code !== "stage-context-bundle-schema-invalid") throw error;
+      findings.push(finding("stage-receipt-input-bundle-invalid", "blocked", {
+        ...(stageId ? { stageId } : {}),
+        reason: error.message,
+      }));
+    }
+    if (!stageId) continue;
+    const candidates = candidatesByStage.get(stageId) ?? [];
+    candidates.push(bundle);
+    candidatesByStage.set(stageId, candidates);
+  }
+
+  for (const [stageId, candidates] of candidatesByStage) {
+    if (!receipts.has(stageId)) findings.push(finding("stage-receipt-input-bundle-mismatch", "blocked", {
+      stageId,
+      reason: "receipt-missing",
+    }));
+    if (candidates.length > 1) findings.push(finding("stage-receipt-input-bundle-duplicate", "blocked", {
+      stageId,
+      count: candidates.length,
+    }));
+  }
+
+  const planDigest = taskContextPlanDigest(plan);
+  const currentSnapshots = snapshots(project);
+  const verifiedReceipts = new Map();
+  const verification = new Map();
+
+  async function verify(stageId) {
+    if (verification.has(stageId)) return verification.get(stageId);
+    const pending = (async () => {
+      const receipt = receipts.get(stageId);
+      if (!receipt) return false;
+      const candidates = candidatesByStage.get(stageId) ?? [];
+      if (candidates.length === 0) {
+        findings.push(finding("stage-receipt-input-bundle-missing", "blocked", { stageId }));
+        return false;
+      }
+      if (candidates.length !== 1 || !candidates[0]) return false;
+      const bundle = candidates[0];
+      let valid = true;
+      const mismatch = (reason, details = {}) => {
+        valid = false;
+        findings.push(finding("stage-receipt-input-bundle-mismatch", "blocked", { stageId, reason, ...details }));
+      };
+      const stale = (reason, details = {}) => {
+        valid = false;
+        findings.push(finding("stage-receipt-input-bundle-stale", "blocked", { stageId, reason, ...details }));
+      };
+      if (bundle.project.id !== receipt.projectId) mismatch("project-id", { expected: receipt.projectId, actual: bundle.project.id });
+      if (bundle.task.id !== receipt.taskId) mismatch("task-id", { expected: receipt.taskId, actual: bundle.task.id });
+      if (bundle.stage.id !== receipt.stageId) mismatch("stage-id", { expected: receipt.stageId, actual: bundle.stage.id });
+      if (bundle.project.id !== plan.projectId || bundle.task.id !== plan.task.id || !plan.stages.some((entry) => entry.id === bundle.stage.id)) {
+        mismatch("plan-identity");
+      }
+      if (receipt.planDigest !== planDigest) {
+        stale("receipt-plan-digest", { expected: planDigest, actual: receipt.planDigest });
+        findings.push(finding("stage-receipt-stale", "blocked", { stageId, reason: "plan-digest" }));
+      }
+      if (bundle.planDigest !== planDigest) stale("bundle-plan-digest", { expected: planDigest, actual: bundle.planDigest });
+      for (const key of Object.keys(currentSnapshots)) {
+        if (bundle.snapshots[key] !== plan.snapshots[key] || bundle.snapshots[key] !== currentSnapshots[key]) {
+          stale(`${key}-snapshot`, {
+            plan: plan.snapshots[key],
+            current: currentSnapshots[key],
+            actual: bundle.snapshots[key],
+          });
+        }
+      }
+
+      const stage = plan.stages.find((entry) => entry.id === stageId);
+      const dependencyReceipts = new Map();
+      for (const dependencyId of stage.dependsOn) {
+        if (receipts.has(dependencyId) && await verify(dependencyId)) dependencyReceipts.set(dependencyId, receipts.get(dependencyId));
+      }
+      const rebuilt = await buildStageContextBundleCore(root, project, plan, {
+        stageId,
+        changedPaths: bundle.changedPaths,
+      }, dependencyReceipts);
+      if (!sameJson(bundle, rebuilt)) stale("canonical-content", {
+        expectedBundleDigest: rebuilt.bundleDigest,
+        actualBundleDigest: bundle.bundleDigest,
+      });
+      if (receipt.inputBundleDigest !== bundle.bundleDigest) mismatch("receipt-input-bundle-digest", {
+        expected: bundle.bundleDigest,
+        actual: receipt.inputBundleDigest,
+      });
+      if (receipt.status === "completed" && bundle.status === "blocked") {
+        valid = false;
+        findings.push(finding("stage-receipt-input-bundle-invalid", "blocked", {
+          stageId,
+          reason: "completed-receipt-bound-to-blocked-bundle",
+        }));
+      }
+      if (valid) verifiedReceipts.set(stageId, receipt);
+      return valid;
+    })();
+    verification.set(stageId, pending);
+    return pending;
+  }
+
+  for (const stage of plan.stages) {
+    if (receipts.has(stage.id)) await verify(stage.id);
+  }
+  return { receipts: verifiedReceipts, findings: stableFindings(findings) };
+}
+
+export async function buildStageContextBundle(root, project, planInput, options) {
+  const plan = validateTaskContextPlan(planInput);
+  if (plan.projectId !== project.contract.project.id) fail("task-context-project-mismatch", "task context plan belongs to a different project");
+  await validatePlanPaths(root, plan);
+  const receipts = normalizedReceipts(options.receipts ?? [], plan);
+  const binding = await verifyReceiptBundleBindings(root, project, plan, receipts, options.receiptBundles ?? []);
+  return buildStageContextBundleCore(root, project, plan, options, binding.receipts, binding.findings);
+}
+
 function receiptScopeEscapes(plan, receipt) {
   const stage = plan.stages.find((entry) => entry.id === receipt.stageId);
   if (!stage) return receipt.changedPaths;
@@ -286,9 +419,12 @@ export async function buildIntegrationReviewBundle(root, project, planInput, opt
   const mainChangedPaths = normalizeSignalPaths(options.mainChangedPaths ?? [], "main changed path");
   const branchChangedPaths = normalizeSignalPaths(options.branchChangedPaths ?? [], "branch changed path");
   await validateProjectPaths(root, [...mainChangedPaths, ...branchChangedPaths], "integration changed path");
-  const receipts = normalizedReceipts(options.receipts ?? [], plan);
+  const suppliedReceipts = normalizedReceipts(options.receipts ?? [], plan);
+  const binding = await verifyReceiptBundleBindings(root, project, plan, suppliedReceipts, options.receiptBundles ?? []);
+  const receipts = binding.receipts;
   const planDigest = taskContextPlanDigest(plan);
   const findings = [
+    ...binding.findings,
     ...baselineFindings(plan, project),
     ...checkerFindings(await checkProject(root, project)),
     ...pathOverlapFindings(mainChangedPaths, branchChangedPaths),
@@ -337,7 +473,7 @@ export async function buildIntegrationReviewBundle(root, project, planInput, opt
   return { ...bundle, bundleDigest: digestJson(bundle) };
 }
 
-async function readInputs(root, planPath, receiptPaths) {
+async function readInputs(root, planPath, receiptPaths, receiptBundlePaths) {
   const resolvedPlan = await resolveExistingInside(root, planPath);
   const plan = await readJsonFile(resolvedPlan.absolute, "task context plan");
   const receipts = [];
@@ -345,17 +481,22 @@ async function readInputs(root, planPath, receiptPaths) {
     const resolved = await resolveExistingInside(root, receiptPath);
     receipts.push(await readJsonFile(resolved.absolute, "stage receipt"));
   }
-  return { plan, receipts };
+  const receiptBundles = [];
+  for (const bundlePath of receiptBundlePaths) {
+    const resolved = await resolveExistingInside(root, bundlePath);
+    receiptBundles.push(await readJsonFile(resolved.absolute, "stage context bundle"));
+  }
+  return { plan, receipts, receiptBundles };
 }
 
 export async function buildStageContextBundleFiles(root, planPath, options) {
-  const { plan, receipts } = await readInputs(root, planPath, options.receiptPaths ?? []);
+  const { plan, receipts, receiptBundles } = await readInputs(root, planPath, options.receiptPaths ?? [], options.receiptBundlePaths ?? []);
   const project = await loadProject(root);
-  return buildStageContextBundle(root, project, plan, { ...options, receipts });
+  return buildStageContextBundle(root, project, plan, { ...options, receipts, receiptBundles });
 }
 
 export async function buildIntegrationReviewBundleFiles(root, planPath, options) {
-  const { plan, receipts } = await readInputs(root, planPath, options.receiptPaths ?? []);
+  const { plan, receipts, receiptBundles } = await readInputs(root, planPath, options.receiptPaths ?? [], options.receiptBundlePaths ?? []);
   const project = await loadProject(root);
-  return buildIntegrationReviewBundle(root, project, plan, { ...options, receipts });
+  return buildIntegrationReviewBundle(root, project, plan, { ...options, receipts, receiptBundles });
 }