frontend-project-context 1.8.0 → 1.9.1

package/src/project-context/authoring.mjs

@@ -1,5 +1,6 @@
 import { canonicalJson } from "./canonical-json.mjs";
 import {
+  promoteContractToSchema3,
   sourceForContract,
   sourceRegistrationShape,
   sourceStatus,
@@ -32,8 +33,8 @@ function sourceLocator(source) {
   });
 }
 
-export async function buildRegisteredSource(root, input) {
-  const { id, kind, path: sourcePath, pointer, reference } = input;
+export async function buildRegisteredSource(root, input, options = {}) {
+  const { id, kind, path: sourcePath, pointer, reference, digestMode } = input;
   let source;
   if (LOCAL_SOURCE_KINDS.has(kind)) {
     if (!has(sourcePath) || has(reference) || (kind === "json-pointer" ? !has(pointer) : has(pointer))) {
@@ -44,21 +45,23 @@ export async function buildRegisteredSource(root, input) {
       kind,
       path: normalizeRelativePath(sourcePath, { label: "source path" }),
       ...(kind === "json-pointer" ? { pointer } : {}),
+      ...(digestMode !== undefined ? { digestMode } : {}),
     };
-    source.digest = await readSourceDigest(root, source);
+    if (digestMode !== undefined && kind !== "file") fail("argument-conflict", "--digest-mode is only valid for file sources");
+    source.digest = await readSourceDigest(root, source, undefined, { projectionsLock: options.projectionsLock });
   } else if (REFERENCE_SOURCE_KINDS.has(kind)) {
-    if (!has(reference) || has(sourcePath) || has(pointer)) {
+    if (!has(reference) || has(sourcePath) || has(pointer) || has(digestMode)) {
       fail("argument-conflict", `${kind} source requires only --reference`, { details: { source: id } });
     }
     source = { id, kind, reference };
   } else {
     fail("schema-invalid-enum", `source kind is invalid: ${kind}`, { details: { source: id } });
   }
-  return validateSource(source);
+  return validateSource(source, "source", { contractSchemaVersion: digestMode === undefined ? 1 : 3, proposal: true });
 }
 
 export async function registerSource(root, project, input, options = {}) {
-  const source = await buildRegisteredSource(root, input);
+  const source = await buildRegisteredSource(root, input, { projectionsLock: project.projectionsLock });
   const existingById = project.contract.sources.find((entry) => entry.id === source.id);
   if (existingById) {
     if (sourceStatus(existingById) === "deprecated" || canonicalJson(sourceRegistrationShape(existingById)) !== canonicalJson(source)) {
@@ -77,6 +80,7 @@ export async function registerSource(root, project, input, options = {}) {
   }
 
   const nextContract = structuredClone(project.contract);
+  if (source.digestMode !== undefined) promoteContractToSchema3(nextContract);
   const storedSource = sourceForContract(source, nextContract.schemaVersion);
   nextContract.sources.push(storedSource);
   nextContract.sources.sort((left, right) => left.id.localeCompare(right.id));
@@ -91,7 +95,7 @@ export async function registerSource(root, project, input, options = {}) {
 
   if (options.write) {
     if (LOCAL_SOURCE_KINDS.has(source.kind)) {
-      const actual = await readSourceDigest(root, source);
+      const actual = await readSourceDigest(root, source, undefined, { projectionsLock: project.projectionsLock });
       if (actual !== source.digest) {
         fail("source-changed-during-register", `source changed while registration was being prepared: ${source.id}`, {
           exitCode: 1,
@@ -157,6 +161,21 @@ export function buildItemProposal(project, input) {
       details: { item: input.id, source: verification.source },
     });
   }
+  const requiredSources = input.requiredSources ?? [];
+  const conditionalSources = input.conditionalSources ?? [];
+  if (new Set(requiredSources).size !== requiredSources.length) fail("schema-duplicate", "--required-source contains duplicate IDs");
+  if (new Set(conditionalSources).size !== conditionalSources.length) fail("schema-duplicate", "--conditional-source contains duplicate IDs");
+  const roleSources = [...requiredSources, ...conditionalSources];
+  const overlap = requiredSources.find((source) => conditionalSources.includes(source));
+  if (overlap) fail("argument-conflict", `source cannot be both required and conditional: ${overlap}`);
+  for (const sourceId of roleSources) {
+    if (!sourceIds.includes(sourceId)) fail("source-reference-missing", `consumption source must be included in --sources: ${sourceId}`);
+    if (!LOCAL_SOURCE_KINDS.has(sourceMap.get(sourceId)?.kind)) fail("argument-conflict", `consumption source must be local: ${sourceId}`);
+  }
+  const consumption = roleSources.length > 0 ? {
+    requiredSources: [...requiredSources].sort((left, right) => left.localeCompare(right)),
+    conditionalSources: [...conditionalSources].sort((left, right) => left.localeCompare(right)),
+  } : undefined;
   const item = {
     id: input.id,
     kind: input.kind,
@@ -167,9 +186,10 @@ export function buildItemProposal(project, input) {
     status: "proposed",
     sources: sourceIds,
     overrides: input.overrides ?? [],
+    ...(consumption ? { consumption } : {}),
     ...(verification ? { verification } : {}),
   };
-  validateItem(item, "proposal item", { proposal: true });
+  validateItem(item, "proposal item", { proposal: true, contractSchemaVersion: 3 });
 
   if (item.overrides.length > 0) {
     const hypothetical = { ...structuredClone(item), status: "approved", approval: { by: "proposal-preflight", at: "1970-01-01T00:00:00.000Z" } };

package/src/project-context/capabilities.mjs

@@ -13,6 +13,7 @@ import { inspectProjectInitialization, loadProject } from "./project-store.mjs";
 import { RENDERER_VERSION } from "./renderer.mjs";
 import { AI_ENTRY_RENDERER_VERSION } from "./ai-entry.mjs";
 import { PROJECT_STATUS_SCHEMA_VERSION } from "./project-status.mjs";
+import { CONTEXT_BUNDLE_SCHEMA_VERSION } from "./context-bundle.mjs";
 import { EVIDENCE_BUNDLE_SCHEMA_VERSION, EVIDENCE_INPUT_SCHEMA_VERSION } from "./evidence-schema.mjs";
 import {
   CONTEXT_BUDGET_UNIT,
@@ -49,7 +50,9 @@ function schemas(projectionLockWritten = 1) {
     adaptiveContextBundle: ADAPTIVE_CONTEXT_BUNDLE_SCHEMA_VERSION,
     assistBundle: ASSIST_BUNDLE_SCHEMA_VERSION,
     capabilities: CAPABILITIES_SCHEMA_VERSION,
-    contract: 2,
+    contract: 3,
+    contractReadable: [1, 2, 3],
+    contextBundle: CONTEXT_BUNDLE_SCHEMA_VERSION,
     contextQuery: CONTEXT_QUERY_SCHEMA_VERSION,
     coverageAudit: COVERAGE_AUDIT_SCHEMA_VERSION,
     dashboardViewModel: DASHBOARD_SCHEMA_VERSION,

package/src/project-context/checker.mjs

@@ -26,7 +26,7 @@ export async function checkProject(root, project, options = {}) {
       continue;
     }
     try {
-      const actual = await readSourceDigest(root, source, sourceReadContext);
+      const actual = await readSourceDigest(root, source, sourceReadContext, { projectionsLock: project.projectionsLock });
       if (actual !== locked) findings.push({ code: "source-changed", source: source.id, path: source.path, expected: locked, actual });
     } catch (error) {
       const code = error.code === "source-missing"

package/src/project-context/cli.mjs

@@ -5,6 +5,7 @@ import { buildItemProposal, registerSource } from "./authoring.mjs";
 import { blockingContextFindings, checkExitCode, checkProject } from "./checker.mjs";
 import { digestJson, prettyCanonicalJson } from "./canonical-json.mjs";
 import { validateProposal } from "./contract-schema.mjs";
+import { buildContextBundle } from "./context-bundle.mjs";
 import { buildDashboardModel } from "./dashboard-model.mjs";
 import { renderDashboardHtml } from "./dashboard-renderer.mjs";
 import { discoverProject } from "./discovery.mjs";
@@ -20,7 +21,6 @@ import { initializeProject, inspectProjectInitialization, loadProject } from "./
 import { publishProjection } from "./projection-store.mjs";
 import { publishAiEntry, removeAiEntry } from "./ai-entry.mjs";
 import { buildProjectStatus } from "./project-status.mjs";
-import { renderContextBundle } from "./renderer.mjs";
 import { buildIntegrationReviewBundleFiles, buildStageContextBundleFiles } from "./task-context.mjs";
 import { applyMigrationPlanFile, buildMigrationPlanFile, buildUpgradeAssessment } from "./upgrade.mjs";
 import { buildTruthReconciliationReviewFiles } from "./truth-reconciliation.mjs";
@@ -38,16 +38,16 @@ Usage:
   project-context upgrade-plan --project PATH --assessment FILE [--json]
   project-context upgrade-apply --project PATH --plan FILE [--write] [--json]
   project-context setup --project PATH --id ID --name NAME [--output FILE] [--write] [--json]
-  project-context register --project PATH --id SOURCE_ID --kind KIND [--path PATH] [--pointer POINTER] [--reference TEXT] [--write] [--json]
-  project-context propose --project PATH --id ITEM_ID --kind KIND --subject SUBJECT (--value TEXT | --value-json JSON) --statement TEXT --sources SOURCE_ID... --scope SCOPE [--scope-path PATH] [--overrides ITEM_ID...] [--verification KIND] [--verification-source SOURCE_ID] [--verification-expected-json JSON] [--output FILE --write] [--json]
+  project-context register --project PATH --id SOURCE_ID --kind KIND [--path PATH] [--pointer POINTER] [--reference TEXT] [--digest-mode full-file|outside-owned-ai-entry] [--write] [--json]
+  project-context propose --project PATH --id ITEM_ID --kind KIND --subject SUBJECT (--value TEXT | --value-json JSON) --statement TEXT --sources SOURCE_ID... --scope SCOPE [--scope-path PATH] [--overrides ITEM_ID...] [--required-source SOURCE_ID...] [--conditional-source SOURCE_ID...] [--verification KIND] [--verification-source SOURCE_ID] [--verification-expected-json JSON] [--output FILE --write] [--json]
   project-context review-source --project PATH --id SOURCE_ID [--json]
   project-context accept-source-change --project PATH --id SOURCE_ID --expected-digest SHA256 [--affected-items ITEM_ID...] [--write] [--json]
-  project-context revise --project PATH --id ITEM_ID [--expected-item-digest SHA256] --kind KIND --subject SUBJECT (--value TEXT | --value-json JSON) --statement TEXT --sources SOURCE_ID... --scope SCOPE [--scope-path PATH] [--overrides ITEM_ID...] [--verification KIND] [--verification-source SOURCE_ID] [--verification-expected-json JSON] [--write] [--json]
+  project-context revise --project PATH --id ITEM_ID [--expected-item-digest SHA256] --kind KIND --subject SUBJECT (--value TEXT | --value-json JSON) --statement TEXT --sources SOURCE_ID... --scope SCOPE [--scope-path PATH] [--overrides ITEM_ID...] [--required-source SOURCE_ID...] [--conditional-source SOURCE_ID...] [--verification KIND] [--verification-source SOURCE_ID] [--verification-expected-json JSON] [--write] [--json]
   project-context deprecate --project PATH --id ITEM_ID [--expected-item-digest SHA256] --by NAME --rationale TEXT [--write] [--json]
   project-context deprecate-source --project PATH --id SOURCE_ID [--expected-source-digest SHA256] --by NAME --rationale TEXT [--write] [--json]
   project-context discover --project PATH [--output FILE --write] [--json]
   project-context approve --project PATH (--proposal FILE | --pending) --ids ID... --by NAME [--rationale TEXT] [--write] [--json | --full-json]
-  project-context context --project PATH --path RELATIVE_PATH... [--task TEXT] [--locale zh-CN|en|all] [--json]
+  project-context context --project PATH (--locate --task TEXT | --path RELATIVE_PATH... [--task TEXT]) [--locale zh-CN|en|all] [--json]
   project-context context-query --project PATH --input FILE [--previous FILE] [--json | --prompt]
   project-context coverage-audit --project PATH [--changed-path RELATIVE_PATH...] [--json]
   project-context index-context --project PATH [--write] [--json]
@@ -67,13 +67,13 @@ All commands are read-only unless their own --write flag is present.
 const VALUE_FLAGS = new Set([
   "project", "id", "name", "output", "proposal", "by", "task", "target", "rationale",
   "kind", "pointer", "reference", "subject", "value", "value-json", "statement", "scope", "scope-path",
-  "verification", "verification-source", "verification-expected-json",
+  "verification", "verification-source", "verification-expected-json", "digest-mode",
   "expected-digest", "expected-item-digest", "expected-source-digest", "locale", "plan", "stage", "from-version", "assessment", "previous", "previous-review",
 ]);
 const LIST_FLAGS = new Set([
-  "ids", "path", "input", "changed-path", "sources", "overrides", "affected-items", "receipt", "receipt-bundle", "main-changed-path", "branch-changed-path",
+  "ids", "path", "input", "changed-path", "sources", "overrides", "required-source", "conditional-source", "affected-items", "receipt", "receipt-bundle", "main-changed-path", "branch-changed-path",
 ]);
-const BOOLEAN_FLAGS = new Set(["write", "json", "full-json", "help", "pending", "prompt"]);
+const BOOLEAN_FLAGS = new Set(["write", "json", "full-json", "help", "pending", "prompt", "locate"]);
 const COMMAND_OPTIONS = new Map([
   ["init", new Set(["project", "id", "name", "write", "json", "help"])],
   ["capabilities", new Set(["project", "json", "help"])],
@@ -84,10 +84,10 @@ const COMMAND_OPTIONS = new Map([
   ["upgrade-plan", new Set(["project", "assessment", "json", "help"])],
   ["upgrade-apply", new Set(["project", "plan", "write", "json", "help"])],
   ["setup", new Set(["project", "id", "name", "output", "write", "json", "help"])],
-  ["register", new Set(["project", "id", "kind", "path", "pointer", "reference", "write", "json", "help"])],
+  ["register", new Set(["project", "id", "kind", "path", "pointer", "reference", "digest-mode", "write", "json", "help"])],
   ["propose", new Set([
     "project", "id", "kind", "subject", "value", "value-json", "statement", "sources", "scope", "scope-path",
-    "overrides", "verification", "verification-source", "verification-expected-json", "output", "write", "json", "help",
+    "overrides", "required-source", "conditional-source", "verification", "verification-source", "verification-expected-json", "output", "write", "json", "help",
   ])],
   ["review-source", new Set(["project", "id", "json", "help"])],
   ["accept-source-change", new Set([
@@ -95,7 +95,7 @@ const COMMAND_OPTIONS = new Map([
   ])],
   ["revise", new Set([
     "project", "id", "expected-item-digest", "kind", "subject", "value", "value-json", "statement", "sources",
-    "scope", "scope-path", "overrides", "verification", "verification-source", "verification-expected-json",
+    "scope", "scope-path", "overrides", "required-source", "conditional-source", "verification", "verification-source", "verification-expected-json",
     "write", "json", "help",
   ])],
   ["deprecate", new Set([
@@ -106,7 +106,7 @@ const COMMAND_OPTIONS = new Map([
   ])],
   ["discover", new Set(["project", "output", "write", "json", "help"])],
   ["approve", new Set(["project", "proposal", "pending", "ids", "by", "rationale", "write", "json", "full-json", "help"])],
-  ["context", new Set(["project", "path", "task", "locale", "json", "help"])],
+  ["context", new Set(["project", "path", "locate", "task", "locale", "json", "help"])],
   ["context-query", new Set(["project", "input", "previous", "json", "prompt", "help"])],
   ["coverage-audit", new Set(["project", "changed-path", "json", "help"])],
   ["index-context", new Set(["project", "write", "json", "help"])],
@@ -233,6 +233,8 @@ function itemInput(options) {
     scope: required(options, "scope"),
     scopePath: options["scope-path"],
     overrides: options.overrides ?? [],
+    requiredSources: options["required-source"] ?? [],
+    conditionalSources: options["conditional-source"] ?? [],
     verification: options.verification,
     verificationSource: options["verification-source"],
     verificationExpectedPresent: hasExpected,
@@ -449,7 +451,7 @@ async function runCommand(command, options) {
   if (command === "coverage-audit") {
     const audit = await buildCoverageAuditFiles(root, options["changed-path"] ?? []);
     const summary = `Registration coverage ${audit.registrationCoverage}: ${audit.categories["review-required"].length} review-required candidate(s).\n`;
-    return { exitCode: audit.registrationCoverage === "review-required" ? 1 : 0, stdout: jsonOrText(options, audit, summary), stderr: "" };
+    return { exitCode: ["review-required", "unresolved"].includes(audit.registrationCoverage) ? 1 : 0, stdout: jsonOrText(options, audit, summary), stderr: "" };
   }
   if (command === "index-context") {
     const index = await indexContextFiles(root, { write: options.write });
@@ -479,6 +481,7 @@ async function runCommand(command, options) {
       path: optionalOneListValue(options, "path"),
       pointer: options.pointer,
       reference: options.reference,
+      digestMode: options["digest-mode"],
     }, { write: options.write });
     const summary = result.action === "unchanged"
       ? `Source unchanged: ${result.source.id}.\n`
@@ -637,9 +640,19 @@ async function runCommand(command, options) {
   if (command === "context") {
     const findings = blockingContextFindings(await checkProject(root, project));
     if (findings.length > 0) fail("context-blocked", "context generation is blocked by contract or source findings", { exitCode: 1, details: { findings } });
-    const paths = required(options, "path");
-    const content = renderContextBundle(project.contract, paths, options.task, { locale: contextLocale(options) });
-    return { exitCode: 0, stdout: options.json ? prettyCanonicalJson({ content }) : content, stderr: "" };
+    const hasLocate = options.locate === true;
+    const hasPaths = options.path !== undefined;
+    if (hasLocate === hasPaths) fail("argument-conflict", "context requires exactly one of --locate or --path");
+    if (hasLocate && (typeof options.task !== "string" || options.task.trim().length === 0)) {
+      fail("argument-missing", "--locate requires a non-empty --task");
+    }
+    const bundle = await buildContextBundle(root, project, {
+      mode: hasLocate ? "locate" : "targeted",
+      paths: options.path ?? [],
+      task: options.task,
+      locale: contextLocale(options),
+    });
+    return { exitCode: 0, stdout: options.json ? prettyCanonicalJson(bundle) : bundle.content, stderr: "" };
   }
   if (command === "publish") {
     const findings = blockingContextFindings(await checkProject(root, project));

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

@@ -0,0 +1,378 @@
+import { canonicalJson, canonicalValue, digestJson } from "./canonical-json.mjs";
+import { sourceStatus } from "./contract-schema.mjs";
+import { coverageDomainForPath, coverageProfile } from "./coverage-profile.mjs";
+import { fail } from "./errors.mjs";
+import { normalizeRelativePath, resolveExistingInside } from "./path-policy.mjs";
+import { renderCollectedContextBundle } from "./renderer.mjs";
+import { effectiveItems } from "./scope-compiler.mjs";
+
+export const CONTEXT_BUNDLE_SCHEMA_VERSION = 1;
+
+const LOCAL_SOURCE_KINDS = new Set(["file", "path", "json-pointer"]);
+const ROLES = Object.freeze({ "provenance-only": 0, conditional: 1, required: 2 });
+const SHA256 = /^sha256:[a-f0-9]{64}$/u;
+
+function uniqueSorted(values) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function snapshots(project) {
+  return {
+    contract: project.contractDigest,
+    sourcesLock: project.sourcesLockDigest,
+    projectionsLock: project.projectionsLockDigest,
+  };
+}
+
+function scopeCoverage(items) {
+  if (items.length === 0) return "none";
+  return items.some((item) => item.scope.kind !== "project") ? "scoped" : "project-only";
+}
+
+function itemRecord(item) {
+  return canonicalValue({
+    id: item.id,
+    kind: item.kind,
+    subject: item.subject,
+    scope: structuredClone(item.scope),
+    sourceIds: [...item.sources].sort(),
+    statement: item.statement,
+    value: structuredClone(item.value),
+    overrides: [...item.overrides].sort(),
+    ...(item.verification !== undefined ? { verification: structuredClone(item.verification) } : {}),
+    ...(item.consumption !== undefined ? { consumption: structuredClone(item.consumption) } : {}),
+  });
+}
+
+function sourceRole(item, sourceId) {
+  if (item.consumption?.requiredSources.includes(sourceId)) return "required";
+  if (item.consumption?.conditionalSources.includes(sourceId)) return "conditional";
+  if (item.consumption === undefined && item.kind === "reference") return "conditional";
+  return "provenance-only";
+}
+
+function sourceLocator(source) {
+  if (source.kind === "json-pointer") return { path: source.path, pointer: source.pointer };
+  if (LOCAL_SOURCE_KINDS.has(source.kind)) return { path: source.path };
+  return { reference: source.reference };
+}
+
+async function consumptionRecords(root, contract, items, paths) {
+  const sourceMap = new Map(contract.sources.filter((source) => sourceStatus(source) === "active").map((source) => [source.id, source]));
+  const records = new Map();
+  const merge = (value) => {
+    const current = records.get(value.path);
+    if (!current) {
+      records.set(value.path, value);
+      return;
+    }
+    if (ROLES[value.role] > ROLES[current.role]) current.role = value.role;
+    current.itemIds = uniqueSorted([...current.itemIds, ...value.itemIds]);
+    current.sourceIds = uniqueSorted([...current.sourceIds, ...value.sourceIds]);
+    current.reasons = uniqueSorted([...current.reasons, ...value.reasons]);
+    const pointers = uniqueSorted([...(current.pointers ?? []), ...(value.pointers ?? [])]);
+    if (pointers.length > 0) current.pointers = pointers;
+    else delete current.pointers;
+  };
+  for (const targetPath of paths) {
+    merge({
+      path: targetPath,
+      role: "required",
+      itemIds: [],
+      sourceIds: [],
+      reasons: ["task-target"],
+    });
+  }
+  for (const item of items) {
+    for (const sourceId of item.sources) {
+      const source = sourceMap.get(sourceId);
+      const role = sourceRole(item, sourceId);
+      if (!source || !LOCAL_SOURCE_KINDS.has(source.kind)) continue;
+      merge({
+        path: source.path,
+        role,
+        itemIds: [item.id],
+        sourceIds: [sourceId],
+        reasons: [`contract-source:${role}`],
+        ...(source.kind === "json-pointer" ? { pointers: [source.pointer] } : {}),
+      });
+    }
+  }
+  const all = [...records.values()].sort((left, right) => left.path.localeCompare(right.path));
+  const readTargets = all.filter((entry) => entry.role !== "provenance-only");
+  const provenancePaths = new Set(all.filter((entry) => entry.role === "provenance-only").map((entry) => entry.path));
+  const provenanceSources = [];
+  for (const item of items) {
+    for (const sourceId of item.sources) {
+      const source = sourceMap.get(sourceId);
+      if (!source || sourceRole(item, sourceId) !== "provenance-only") continue;
+      if (LOCAL_SOURCE_KINDS.has(source.kind) && records.get(source.path)?.role !== "provenance-only") continue;
+      provenanceSources.push({ sourceId, itemIds: [item.id], kind: source.kind, locator: sourceLocator(source) });
+    }
+  }
+  const bySource = new Map();
+  for (const record of provenanceSources) {
+    const current = bySource.get(record.sourceId);
+    if (current) current.itemIds = uniqueSorted([...current.itemIds, ...record.itemIds]);
+    else bySource.set(record.sourceId, record);
+  }
+  const unavailable = [];
+  for (const target of readTargets.filter((entry) => entry.role === "required" && entry.sourceIds.length > 0)) {
+    try {
+      await resolveExistingInside(root, target.path);
+    } catch (error) {
+      unavailable.push({ code: "required-read-target-unavailable", path: target.path, sourceIds: target.sourceIds, reason: error.code ?? "unavailable" });
+    }
+  }
+  return {
+    readTargets: readTargets.map((entry) => canonicalValue(entry)),
+    provenanceSources: [...bySource.values()].sort((left, right) => left.sourceId.localeCompare(right.sourceId)).map(canonicalValue),
+    unavailable,
+    provenancePaths,
+  };
+}
+
+function coverageFor(profile, targets) {
+  const domains = targets.map((target) => {
+    const domain = coverageDomainForPath(profile, target.path);
+    return {
+      path: target.path,
+      disposition: domain?.disposition ?? "outside-declared-coverage",
+      domainId: domain?.id ?? null,
+    };
+  });
+  let registrationCoverage = "closed-for-declared-scope";
+  if (!profile) registrationCoverage = "not-declared";
+  else if (domains.some((entry) => entry.disposition === "unresolved")) registrationCoverage = "unresolved";
+  else if (profile.version !== 2) registrationCoverage = "review-required";
+  return {
+    profileItemId: profile?.itemId ?? null,
+    profileVersion: profile?.version ?? null,
+    registrationCoverage,
+    targets: domains,
+    guarantee: "declared-scope-only-never-all-project-truth",
+  };
+}
+
+function stableGaps(gaps) {
+  const byJson = new Map();
+  for (const gap of gaps) byJson.set(canonicalJson(gap), canonicalValue(gap));
+  return [...byJson.values()].sort((left, right) => canonicalJson(left).localeCompare(canonicalJson(right)));
+}
+
+function authority() {
+  return {
+    productTaskExecution: false,
+    productBusinessCodeWrites: false,
+    hostTaskAuthority: "external-to-project-context",
+    resolveFrom: ["current-user-request", "human-authored-project-instructions", "higher-priority-safety-constraints"],
+  };
+}
+
+export async function buildContextBundle(root, project, input) {
+  const mode = input.mode;
+  if (!new Set(["locate", "targeted"]).has(mode)) fail("context-bundle-schema-invalid", "context bundle mode is invalid");
+  const paths = mode === "locate"
+    ? []
+    : uniqueSorted(input.paths.map((value) => normalizeRelativePath(value, { allowRoot: true, label: "target path" })));
+  const task = input.task ?? "";
+  const sections = mode === "locate"
+    ? [{ path: ".", items: effectiveItems(project.contract.items.filter((item) => item.scope.kind === "project"), ".") }]
+    : paths.map((targetPath) => ({ path: targetPath, items: effectiveItems(project.contract.items, targetPath) }));
+  const itemMap = new Map();
+  for (const section of sections) for (const item of section.items) itemMap.set(item.id, item);
+  const items = [...itemMap.values()].sort((left, right) => left.id.localeCompare(right.id));
+  const commonIds = sections.length === 0
+    ? []
+    : sections[0].items.map((item) => item.id).filter((id) => sections.every((section) => section.items.some((item) => item.id === id))).sort();
+  const targets = mode === "locate" ? [] : sections.map((section) => {
+    const ids = section.items.map((item) => item.id).sort();
+    return {
+      path: section.path,
+      scopeCoverage: scopeCoverage(section.items),
+      itemIds: ids,
+      scopedItemIds: section.items.filter((item) => item.scope.kind !== "project").map((item) => item.id).sort(),
+      deltaItemIds: ids.filter((id) => !commonIds.includes(id)),
+    };
+  });
+  const consumption = await consumptionRecords(root, project.contract, items, paths);
+  const profile = coverageProfile(project.contract);
+  const coverage = coverageFor(profile, targets);
+  const gaps = [...consumption.unavailable];
+  if (mode === "locate") gaps.push({ code: "target-path-not-yet-known" });
+  for (const target of targets) {
+    if (target.scopeCoverage === "project-only") gaps.push({ code: "project-scope-only", path: target.path });
+    if (target.scopeCoverage === "none") gaps.push({ code: "no-applicable-contract-item", path: target.path });
+  }
+  if (!profile) gaps.push({ code: "registration-coverage-not-declared" });
+  if (coverage.registrationCoverage === "review-required") gaps.push({ code: "registration-coverage-review-required" });
+  if (coverage.registrationCoverage === "unresolved") gaps.push({ code: "registration-coverage-review-required", disposition: "unresolved" });
+  const nextActions = mode === "locate"
+    ? ["locate-minimum-candidate-paths-inside-target-root", "recompile-targeted-context-with-all-candidate-paths"]
+    : ["consume-required-read-targets", "evaluate-conditional-read-targets", "recompile-if-affected-paths-change"];
+  const structured = {
+    schemaVersion: 1,
+    kind: "context-bundle",
+    project: { id: project.contract.project.id, name: project.contract.project.name },
+    mode,
+    task: { text: task, paths },
+    snapshots: snapshots(project),
+    semanticCompleteness: "not-claimed",
+    commonItemIds: commonIds,
+    targets,
+    items: items.map(itemRecord),
+    readTargets: consumption.readTargets,
+    provenanceSources: consumption.provenanceSources,
+    coverage,
+    authority: authority(),
+    gaps: stableGaps(gaps),
+    nextActions,
+  };
+  const content = renderCollectedContextBundle({
+    project: project.contract.project,
+    contractDigest: project.contractDigest,
+    paths: mode === "locate" ? ["."] : paths,
+    sections,
+    itemIds: items.map((item) => item.id),
+  }, project.contract.sources, task || undefined, {
+    locale: input.locale,
+    mode,
+    gaps: structured.gaps,
+    nextActions,
+  });
+  return validateContextBundle({ ...structured, content, bundleDigest: digestJson({ ...structured, content }) });
+}
+
+function requireObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail("context-bundle-schema-invalid", `${label} must be an object`);
+}
+
+function exactKeys(value, expected, label) {
+  requireObject(value, label);
+  const actual = Object.keys(value).sort();
+  const wanted = [...expected].sort();
+  if (actual.length !== wanted.length || actual.some((entry, index) => entry !== wanted[index])) {
+    fail("context-bundle-schema-invalid", `${label} must contain exactly: ${wanted.join(", ")}`);
+  }
+}
+
+function allowedKeys(value, allowed, label) {
+  requireObject(value, label);
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) fail("context-bundle-schema-invalid", `${label} contains unknown field: ${key}`);
+  }
+}
+
+function nonEmptyString(value, label) {
+  if (typeof value !== "string" || value.length === 0) fail("context-bundle-schema-invalid", `${label} must be a non-empty string`);
+}
+
+function stableRecords(values, key, label) {
+  const selected = values.map((entry) => entry[key]);
+  sortedUnique(selected, `${label} ${key}s`);
+}
+
+function sortedUnique(values, label) {
+  if (!Array.isArray(values) || values.some((entry) => typeof entry !== "string")) fail("context-bundle-schema-invalid", `${label} must be a string array`);
+  const expected = uniqueSorted(values);
+  if (canonicalJson(values) !== canonicalJson(expected)) fail("context-bundle-schema-invalid", `${label} must be sorted and unique`);
+}
+
+export function validateContextBundle(input) {
+  const value = canonicalValue(input);
+  const keys = new Set(["schemaVersion", "kind", "project", "mode", "task", "snapshots", "semanticCompleteness", "commonItemIds", "targets", "items", "readTargets", "provenanceSources", "coverage", "authority", "gaps", "nextActions", "content", "bundleDigest"]);
+  exactKeys(value, keys, "context bundle");
+  if (value.schemaVersion !== 1 || value.kind !== "context-bundle") fail("context-bundle-schema-invalid", "context bundle identity is invalid");
+  if (!["locate", "targeted"].includes(value.mode)) fail("context-bundle-schema-invalid", "context bundle mode is invalid");
+  if (typeof value.content !== "string" || value.content.length === 0) fail("context-bundle-schema-invalid", "context bundle content is required");
+  if (!SHA256.test(value.bundleDigest)) fail("context-bundle-schema-invalid", "context bundle digest must be sha256");
+  const unsigned = structuredClone(value);
+  delete unsigned.bundleDigest;
+  if (digestJson(unsigned) !== value.bundleDigest) fail("context-bundle-schema-invalid", "context bundle digest does not match canonical content");
+  exactKeys(value.project, new Set(["id", "name"]), "context bundle project");
+  nonEmptyString(value.project.id, "context bundle project.id");
+  nonEmptyString(value.project.name, "context bundle project.name");
+  exactKeys(value.task, new Set(["text", "paths"]), "context bundle task");
+  if (typeof value.task.text !== "string") fail("context-bundle-schema-invalid", "context bundle task.text must be a string");
+  exactKeys(value.snapshots, new Set(["contract", "sourcesLock", "projectionsLock"]), "context bundle snapshots");
+  for (const digest of Object.values(value.snapshots)) if (!SHA256.test(digest)) fail("context-bundle-schema-invalid", "context bundle snapshot must be sha256");
+  if (value.semanticCompleteness !== "not-claimed") fail("context-bundle-schema-invalid", "semantic completeness cannot be claimed");
+  sortedUnique(value.task.paths, "context bundle task paths");
+  sortedUnique(value.commonItemIds, "context bundle common item IDs");
+  sortedUnique(value.nextActions, "context bundle next actions");
+  for (const collection of ["targets", "items", "readTargets", "provenanceSources", "gaps"]) {
+    if (!Array.isArray(value[collection])) fail("context-bundle-schema-invalid", `context bundle ${collection} must be an array`);
+  }
+  stableRecords(value.targets, "path", "context bundle targets");
+  if (canonicalJson(value.targets.map((target) => target.path)) !== canonicalJson(value.task.paths)) {
+    fail("context-bundle-schema-invalid", "context bundle targets must correspond exactly to task paths");
+  }
+  for (const [index, target] of value.targets.entries()) {
+    const label = `context bundle targets[${index}]`;
+    exactKeys(target, new Set(["path", "scopeCoverage", "itemIds", "scopedItemIds", "deltaItemIds"]), label);
+    if (normalizeRelativePath(target.path, { allowRoot: true, label: `${label}.path` }) !== target.path) fail("context-bundle-schema-invalid", `${label}.path must be normalized`);
+    if (!["scoped", "project-only", "none"].includes(target.scopeCoverage)) fail("context-bundle-schema-invalid", `${label}.scopeCoverage is invalid`);
+    for (const key of ["itemIds", "scopedItemIds", "deltaItemIds"]) sortedUnique(target[key], `${label}.${key}`);
+    for (const itemId of [...target.scopedItemIds, ...target.deltaItemIds]) if (!target.itemIds.includes(itemId)) fail("context-bundle-schema-invalid", `${label} contains an item outside itemIds`);
+  }
+  stableRecords(value.items, "id", "context bundle items");
+  const itemIds = new Set(value.items.map((item) => item.id));
+  for (const [index, item] of value.items.entries()) {
+    const label = `context bundle items[${index}]`;
+    allowedKeys(item, new Set(["id", "kind", "subject", "scope", "sourceIds", "statement", "value", "overrides", "verification", "consumption"]), label);
+    for (const required of ["id", "kind", "subject", "scope", "sourceIds", "statement", "value", "overrides"]) if (!Object.hasOwn(item, required)) fail("context-bundle-schema-invalid", `${label}.${required} is required`);
+    nonEmptyString(item.id, `${label}.id`);
+    if (!["fact", "policy", "reference", "validation-description"].includes(item.kind)) fail("context-bundle-schema-invalid", `${label}.kind is invalid`);
+    nonEmptyString(item.subject, `${label}.subject`);
+    nonEmptyString(item.statement, `${label}.statement`);
+    requireObject(item.scope, `${label}.scope`);
+    sortedUnique(item.sourceIds, `${label}.sourceIds`);
+    sortedUnique(item.overrides, `${label}.overrides`);
+    if (item.consumption !== undefined) {
+      exactKeys(item.consumption, new Set(["requiredSources", "conditionalSources"]), `${label}.consumption`);
+      sortedUnique(item.consumption.requiredSources, `${label}.consumption.requiredSources`);
+      sortedUnique(item.consumption.conditionalSources, `${label}.consumption.conditionalSources`);
+    }
+  }
+  for (const id of value.commonItemIds) if (!itemIds.has(id)) fail("context-bundle-schema-invalid", `context bundle common item is missing: ${id}`);
+  for (const target of value.targets) for (const id of target.itemIds) if (!itemIds.has(id)) fail("context-bundle-schema-invalid", `context bundle target item is missing: ${id}`);
+  stableRecords(value.readTargets, "path", "context bundle read targets");
+  for (const [index, target] of value.readTargets.entries()) {
+    const label = `context bundle readTargets[${index}]`;
+    allowedKeys(target, new Set(["path", "role", "itemIds", "sourceIds", "reasons", "pointers"]), label);
+    for (const required of ["path", "role", "itemIds", "sourceIds", "reasons"]) if (!Object.hasOwn(target, required)) fail("context-bundle-schema-invalid", `${label}.${required} is required`);
+    if (!["required", "conditional"].includes(target.role)) fail("context-bundle-schema-invalid", `${label}.role is invalid`);
+    for (const key of ["itemIds", "sourceIds", "reasons", ...(target.pointers === undefined ? [] : ["pointers"])]) sortedUnique(target[key], `${label}.${key}`);
+  }
+  stableRecords(value.provenanceSources, "sourceId", "context bundle provenance sources");
+  for (const [index, source] of value.provenanceSources.entries()) {
+    const label = `context bundle provenanceSources[${index}]`;
+    exactKeys(source, new Set(["sourceId", "itemIds", "kind", "locator"]), label);
+    nonEmptyString(source.sourceId, `${label}.sourceId`);
+    nonEmptyString(source.kind, `${label}.kind`);
+    sortedUnique(source.itemIds, `${label}.itemIds`);
+    requireObject(source.locator, `${label}.locator`);
+  }
+  exactKeys(value.coverage, new Set(["profileItemId", "profileVersion", "registrationCoverage", "targets", "guarantee"]), "context bundle coverage");
+  if (![null, 1, 2].includes(value.coverage.profileVersion)) fail("context-bundle-schema-invalid", "context bundle coverage profileVersion is invalid");
+  if (!["not-declared", "review-required", "unresolved", "closed-for-declared-scope"].includes(value.coverage.registrationCoverage)) fail("context-bundle-schema-invalid", "context bundle registrationCoverage is invalid");
+  if (value.coverage.guarantee !== "declared-scope-only-never-all-project-truth") fail("context-bundle-schema-invalid", "context bundle coverage guarantee is invalid");
+  if (!Array.isArray(value.coverage.targets)) fail("context-bundle-schema-invalid", "context bundle coverage targets must be an array");
+  stableRecords(value.coverage.targets, "path", "context bundle coverage targets");
+  for (const [index, target] of value.coverage.targets.entries()) exactKeys(target, new Set(["path", "disposition", "domainId"]), `context bundle coverage.targets[${index}]`);
+  exactKeys(value.authority, new Set(["productTaskExecution", "productBusinessCodeWrites", "hostTaskAuthority", "resolveFrom"]), "context bundle authority");
+  if (value.authority.productTaskExecution !== false || value.authority.productBusinessCodeWrites !== false || value.authority.hostTaskAuthority !== "external-to-project-context") fail("context-bundle-schema-invalid", "context bundle authority is invalid");
+  if (canonicalJson(value.authority.resolveFrom) !== canonicalJson(authority().resolveFrom)) fail("context-bundle-schema-invalid", "context bundle authority resolution order is invalid");
+  const gapCodes = new Set(["target-path-not-yet-known", "project-scope-only", "no-applicable-contract-item", "registration-coverage-not-declared", "registration-coverage-review-required", "required-read-target-unavailable"]);
+  for (const [index, gap] of value.gaps.entries()) {
+    const label = `context bundle gaps[${index}]`;
+    allowedKeys(gap, new Set(["code", "path", "sourceIds", "reason", "disposition"]), label);
+    if (!gapCodes.has(gap.code)) fail("context-bundle-schema-invalid", `${label}.code is invalid`);
+    if (gap.sourceIds !== undefined) sortedUnique(gap.sourceIds, `${label}.sourceIds`);
+  }
+  const stableGapValues = stableGaps(value.gaps);
+  if (canonicalJson(stableGapValues) !== canonicalJson(value.gaps)) fail("context-bundle-schema-invalid", "context bundle gaps must be stably sorted and unique");
+  if (value.mode === "locate" && (value.task.paths.length > 0 || value.targets.length > 0)) fail("context-bundle-schema-invalid", "locate context cannot contain target paths");
+  if (value.mode === "targeted" && value.task.paths.length === 0) fail("context-bundle-schema-invalid", "targeted context requires paths");
+  return value;
+}