frontend-project-context 1.7.0 → 1.9.1

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;
+}

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

@@ -10,6 +10,7 @@ const STATUSES = new Set(["proposed", "approved", "deprecated"]);
 const SCOPE_KINDS = new Set(["project", "path-prefix", "file"]);
 const VERIFICATION_KINDS = new Set(["none", "file-exists", "json-value", "path-digest"]);
 const SHA256 = /^sha256:[a-f0-9]{64}$/u;
+const DIGEST_MODES = new Set(["full-file", "outside-owned-ai-entry"]);
 
 function object(value, label) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -64,7 +65,14 @@ export function sourceStatus(source) {
 }
 
 export function sourceForContract(source, schemaVersion) {
-  return schemaVersion === 2 ? { ...structuredClone(source), status: "active" } : structuredClone(source);
+  return schemaVersion >= 2 ? { ...structuredClone(source), status: "active" } : structuredClone(source);
+}
+
+export function promoteContractToSchema3(contract) {
+  if (contract.schemaVersion === 3) return contract;
+  contract.schemaVersion = 3;
+  contract.sources = contract.sources.map((source) => source.status === undefined ? { ...source, status: "active" } : source);
+  return contract;
 }
 
 export function sourceRegistrationShape(source) {
@@ -76,12 +84,14 @@ export function sourceRegistrationShape(source) {
 
 export function validateSource(source, label = "source", options = {}) {
   const contractSchemaVersion = options.contractSchemaVersion ?? 1;
+  const governedStatus = contractSchemaVersion >= 2 && options.proposal !== true;
   object(source, label);
   const allowed = new Set(["id", "kind", "path", "pointer", "reference", "digest"]);
-  if (contractSchemaVersion === 2) {
+  if (governedStatus) {
     allowed.add("status");
     allowed.add("deprecation");
   }
+  if (contractSchemaVersion >= 3) allowed.add("digestMode");
   exactKeys(source, allowed, label);
   stableId(source.id, `${label}.id`);
   if (!SOURCE_KINDS.has(source.kind)) fail("schema-invalid-enum", `${label}.kind is invalid`);
@@ -97,6 +107,10 @@ export function validateSource(source, label = "source", options = {}) {
     } else if (source.pointer !== undefined) {
       fail("schema-invalid", `${label}.pointer is only valid for json-pointer sources`);
     }
+    if (source.digestMode !== undefined) {
+      if (source.kind !== "file") fail("schema-invalid", `${label}.digestMode is only valid for file sources`);
+      if (!DIGEST_MODES.has(source.digestMode)) fail("schema-invalid-enum", `${label}.digestMode is invalid`);
+    }
     if (source.reference !== undefined) fail("schema-invalid", `${label}.reference is not valid for local sources`);
   } else {
     string(source.reference, `${label}.reference`);
@@ -107,7 +121,7 @@ export function validateSource(source, label = "source", options = {}) {
       fail("schema-invalid", `${label}.digest must be null or omitted for unverifiable sources`);
     }
   }
-  if (contractSchemaVersion === 2) {
+  if (governedStatus) {
     if (!SOURCE_STATUSES.has(source.status)) fail("schema-invalid-enum", `${label}.status is invalid`);
     if (source.status === "active" && source.deprecation !== undefined) {
       fail("schema-invalid", `${label}.deprecation is not allowed for active sources`);
@@ -123,6 +137,23 @@ export function validateSource(source, label = "source", options = {}) {
   return source;
 }
 
+function validateConsumption(consumption, item, label) {
+  object(consumption, label);
+  exactKeys(consumption, new Set(["requiredSources", "conditionalSources"]), label);
+  uniqueStrings(consumption.requiredSources, `${label}.requiredSources`, { empty: true });
+  uniqueStrings(consumption.conditionalSources, `${label}.conditionalSources`, { empty: true });
+  for (const [name, values] of Object.entries(consumption)) {
+    const sorted = [...values].sort((left, right) => left.localeCompare(right));
+    if (JSON.stringify(values) !== JSON.stringify(sorted)) fail("schema-invalid", `${label}.${name} must be stably sorted`);
+    for (const source of values) {
+      stableId(source, `${label}.${name} entry`);
+      if (!item.sources.includes(source)) fail("source-reference-missing", `${label}.${name} must reference item sources: ${source}`);
+    }
+  }
+  const overlap = consumption.requiredSources.find((source) => consumption.conditionalSources.includes(source));
+  if (overlap) fail("schema-invalid", `${label} source roles must be mutually exclusive: ${overlap}`);
+}
+
 function validateApproval(approval, label) {
   object(approval, label);
   exactKeys(approval, new Set(["by", "at", "rationale"]), label);
@@ -164,9 +195,12 @@ function validateVerification(verification, label) {
 
 export function validateItem(item, label = "item", options = {}) {
   object(item, label);
+  const contractSchemaVersion = options.contractSchemaVersion ?? 1;
+  const allowed = new Set(["id", "kind", "subject", "value", "statement", "scope", "status", "sources", "overrides", "approval", "verification"]);
+  if (contractSchemaVersion >= 3) allowed.add("consumption");
   exactKeys(
     item,
-    new Set(["id", "kind", "subject", "value", "statement", "scope", "status", "sources", "overrides", "approval", "verification"]),
+    allowed,
     label,
   );
   stableId(item.id, `${label}.id`);
@@ -193,6 +227,7 @@ export function validateItem(item, label = "item", options = {}) {
   }
   if (item.approval !== undefined && item.status !== "proposed") validateApproval(item.approval, `${label}.approval`);
   if (item.verification != null) validateVerification(item.verification, `${label}.verification`);
+  if (item.consumption !== undefined) validateConsumption(item.consumption, item, `${label}.consumption`);
   if (options.proposal && item.status !== "proposed") {
     fail("proposal-not-proposed", `${label} must remain proposed`);
   }
@@ -210,7 +245,7 @@ function assertUnique(records, label) {
 export function validateContract(contract) {
   object(contract, "contract");
   exactKeys(contract, new Set(["schemaVersion", "project", "sources", "items"]), "contract");
-  if (![1, 2].includes(contract.schemaVersion)) fail("schema-version-unsupported", "contract.schemaVersion must be 1 or 2");
+  if (![1, 2, 3].includes(contract.schemaVersion)) fail("schema-version-unsupported", "contract.schemaVersion must be 1, 2, or 3");
   object(contract.project, "contract.project");
   exactKeys(contract.project, new Set(["id", "name", "root"]), "contract.project");
   stableId(contract.project.id, "contract.project.id");
@@ -222,7 +257,7 @@ export function validateContract(contract) {
   contract.sources.forEach((source, index) => validateSource(source, `contract.sources[${index}]`, {
     contractSchemaVersion: contract.schemaVersion,
   }));
-  contract.items.forEach((item, index) => validateItem(item, `contract.items[${index}]`));
+  contract.items.forEach((item, index) => validateItem(item, `contract.items[${index}]`, { contractSchemaVersion: contract.schemaVersion }));
   assertUnique(contract.sources, "contract.sources");
   assertUnique(contract.items, "contract.items");
   const sourcesById = new Map(contract.sources.map((source) => [source.id, source]));
@@ -234,6 +269,15 @@ export function validateContract(contract) {
         fail("source-reference-deprecated", `item ${item.id} references deprecated source ${source}`);
       }
     }
+    for (const sourceId of [
+      ...(item.consumption?.requiredSources ?? []),
+      ...(item.consumption?.conditionalSources ?? []),
+    ]) {
+      const referenced = sourcesById.get(sourceId);
+      if (!referenced || !["file", "path", "json-pointer"].includes(referenced.kind)) {
+        fail("schema-invalid", `item ${item.id} consumption source must be a local source: ${sourceId}`);
+      }
+    }
     if (item.verification?.kind !== "none" && item.verification?.source) {
       const referenced = sourcesById.get(item.verification.source);
       if (!referenced) {
@@ -255,8 +299,8 @@ export function validateProposal(proposal) {
   if (!Array.isArray(proposal.sources) || !Array.isArray(proposal.items)) {
     fail("schema-invalid", "proposal.sources and proposal.items must be arrays");
   }
-  proposal.sources.forEach((source, index) => validateSource(source, `proposal.sources[${index}]`));
-  proposal.items.forEach((item, index) => validateItem(item, `proposal.items[${index}]`, { proposal: true }));
+  proposal.sources.forEach((source, index) => validateSource(source, `proposal.sources[${index}]`, { contractSchemaVersion: 3, proposal: true }));
+  proposal.items.forEach((item, index) => validateItem(item, `proposal.items[${index}]`, { proposal: true, contractSchemaVersion: 3 }));
   assertUnique(proposal.sources, "proposal.sources");
   assertUnique(proposal.items, "proposal.items");
   const sourceIds = new Set(proposal.sources.map((source) => source.id));
@@ -264,6 +308,15 @@ export function validateProposal(proposal) {
     for (const source of item.sources) {
       if (!sourceIds.has(source)) fail("source-reference-missing", `proposal item ${item.id} references unknown source ${source}`);
     }
+    for (const sourceId of [
+      ...(item.consumption?.requiredSources ?? []),
+      ...(item.consumption?.conditionalSources ?? []),
+    ]) {
+      const source = proposal.sources.find((entry) => entry.id === sourceId);
+      if (!source || !["file", "path", "json-pointer"].includes(source.kind)) {
+        fail("schema-invalid", `proposal item ${item.id} consumption source must be local: ${sourceId}`);
+      }
+    }
   }
   return proposal;
 }
@@ -308,7 +361,7 @@ export function validateProjectionLock(lock) {
       if (entry.regionId !== "project-context-ai-entry") fail("schema-invalid-enum", "AI Entry regionId is invalid");
       string(entry.regionDigest, `${label}.regionDigest`);
       if (!SHA256.test(entry.regionDigest)) fail("schema-invalid", "AI Entry regionDigest must be sha256");
-      if (![1, 2, 3].includes(entry.rendererVersion)) fail("schema-version-unsupported", "AI Entry rendererVersion must be 1, 2, or 3");
+      if (![1, 2, 3, 4, 5].includes(entry.rendererVersion)) fail("schema-version-unsupported", "AI Entry rendererVersion must be 1, 2, 3, 4, or 5");
       if (typeof entry.createdFile !== "boolean") fail("schema-invalid", `${label}.createdFile must be boolean`);
     } else {
       if (entry.target !== "agents" && entry.target !== "ruler") fail("schema-invalid-enum", "projection target is invalid");