frontend-project-context 1.0.0 → 1.2.0

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

@@ -0,0 +1,528 @@
+import { canonicalValue, digestJson, validateJsonValue } from "./canonical-json.mjs";
+import { fail } from "./errors.mjs";
+import { normalizeRelativePath } from "./path-policy.mjs";
+
+export const PACKAGE_VERSION = "1.2.0";
+export const EXCHANGE_PROTOCOL_VERSION = 1;
+export const ACTION_PLAN_SCHEMA_VERSION = 1;
+export const REVIEW_BUNDLE_SCHEMA_VERSION = 1;
+export const CAPABILITIES_SCHEMA_VERSION = 1;
+
+export const ACTION_KINDS = Object.freeze([
+  "accept-source-change",
+  "deprecate-item",
+  "deprecate-source",
+  "propose-item",
+  "publish-projection",
+  "register-source",
+  "request-item-approval",
+  "revise-item",
+]);
+
+export const COMMANDS = Object.freeze([
+  "accept-source-change", "approve", "capabilities", "check", "context", "dashboard", "deprecate",
+  "deprecate-source", "discover", "init", "preflight", "propose", "publish", "register", "review-source",
+  "revise", "setup", "sync",
+]);
+
+const ACTION_KIND_SET = new Set(ACTION_KINDS);
+const ID = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/u;
+const SHA256 = /^sha256:[a-f0-9]{64}$/u;
+const ITEM_KINDS = new Set(["fact", "policy", "reference", "validation-description"]);
+const SOURCE_KINDS = new Set(["file", "path", "json-pointer", "human-decision", "external-reference"]);
+const SCOPE_KINDS = new Set(["project", "path-prefix", "file"]);
+const VERIFICATION_KINDS = new Set(["none", "file-exists", "json-value", "path-digest"]);
+const AUTHORITY_FIELDS = new Set(["write", "by", "approval", "approve", "provider", "command", "shell"]);
+
+function invalid(message, details) {
+  fail("action-plan-schema-invalid", message, { details });
+}
+
+function reviewInvalid(message, details) {
+  fail("review-bundle-schema-invalid", message, { details });
+}
+
+function object(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalid(`${label} must be an object`);
+}
+
+function exactKeys(value, allowed, label) {
+  for (const key of Object.keys(value)) {
+    if (AUTHORITY_FIELDS.has(key)) invalid(`${label} contains forbidden authority or execution field: ${key}`);
+    if (!allowed.has(key)) invalid(`${label} contains unknown field: ${key}`);
+  }
+}
+
+function string(value, label, options = {}) {
+  if (typeof value !== "string" || (!options.empty && value.length === 0)) invalid(`${label} must be a non-empty string`);
+}
+
+function stableId(value, label) {
+  string(value, label);
+  if (!ID.test(value)) invalid(`${label} must use stable lowercase dot/kebab naming`);
+}
+
+function digest(value, label, options = {}) {
+  if (value === null && options.nullable) return;
+  string(value, label);
+  if (!SHA256.test(value)) invalid(`${label} must be sha256`);
+}
+
+function uniqueStrings(values, label, options = {}) {
+  if (!Array.isArray(values) || (!options.empty && values.length === 0)) {
+    invalid(`${label} must be ${options.empty ? "an" : "a non-empty"} array`);
+  }
+  const seen = new Set();
+  for (const value of values) {
+    string(value, `${label} entry`);
+    if (seen.has(value)) invalid(`${label} contains duplicate value: ${value}`);
+    seen.add(value);
+  }
+  return [...values].sort((left, right) => left.localeCompare(right));
+}
+
+function projectPath(value, label, options = {}) {
+  try {
+    return normalizeRelativePath(value, { allowRoot: options.allowRoot, label });
+  } catch (error) {
+    invalid(`${label} must stay inside the project`, { path: value, reason: error.code ?? "invalid-path" });
+  }
+}
+
+export function normalizeProposalPath(value, label = "proposal path") {
+  const normalized = projectPath(value, label);
+  const reserved = new Set([
+    ".project-context/contract.json",
+    ".project-context/sources.lock.json",
+    ".project-context/projections.lock.json",
+  ]);
+  if (!normalized.startsWith(".project-context/") || !normalized.endsWith(".json") || reserved.has(normalized)) {
+    invalid(`${label} must be a non-store JSON file inside .project-context/`);
+  }
+  return normalized;
+}
+
+function normalizeVerification(value, label) {
+  if (value === undefined) return undefined;
+  object(value, label);
+  exactKeys(value, new Set(["kind", "source", "expected"]), label);
+  if (!VERIFICATION_KINDS.has(value.kind)) invalid(`${label}.kind is invalid`);
+  if (value.kind === "none") {
+    if (value.source !== undefined || Object.hasOwn(value, "expected")) invalid(`${label} none verification cannot contain source or expected`);
+    return { kind: "none" };
+  }
+  stableId(value.source, `${label}.source`);
+  if (value.kind === "file-exists" && Object.hasOwn(value, "expected")) invalid(`${label} file-exists cannot contain expected`);
+  if (value.kind === "json-value" && !Object.hasOwn(value, "expected")) invalid(`${label} json-value requires expected`);
+  if (value.kind === "path-digest" && Object.hasOwn(value, "expected")) digest(value.expected, `${label}.expected`);
+  if (Object.hasOwn(value, "expected")) {
+    try {
+      validateJsonValue(value.expected);
+    } catch (error) {
+      invalid(`${label}.expected must be JSON-compatible`, { reason: error.message });
+    }
+  }
+  return canonicalValue(value);
+}
+
+function normalizeScope(value, label) {
+  object(value, label);
+  exactKeys(value, new Set(["kind", "path"]), label);
+  if (!SCOPE_KINDS.has(value.kind)) invalid(`${label}.kind is invalid`);
+  if (value.kind === "project") {
+    if (value.path !== undefined && value.path !== ".") invalid(`${label}.path must be omitted or '.' for project scope`);
+    return { kind: "project" };
+  }
+  return { kind: value.kind, path: projectPath(value.path, `${label}.path`) };
+}
+
+function normalizeItemInput(input, label, extra = []) {
+  object(input, label);
+  exactKeys(input, new Set([
+    "id", "kind", "subject", "value", "statement", "sources", "scope", "overrides", "verification", ...extra,
+  ]), label);
+  stableId(input.id, `${label}.id`);
+  if (!ITEM_KINDS.has(input.kind)) invalid(`${label}.kind is invalid`);
+  stableId(input.subject, `${label}.subject`);
+  if (!Object.hasOwn(input, "value")) invalid(`${label}.value is required`);
+  try {
+    validateJsonValue(input.value);
+  } catch (error) {
+    invalid(`${label}.value must be JSON-compatible`, { reason: error.message });
+  }
+  string(input.statement, `${label}.statement`);
+  const sources = uniqueStrings(input.sources, `${label}.sources`);
+  sources.forEach((entry) => stableId(entry, `${label}.sources entry`));
+  const overrides = uniqueStrings(input.overrides ?? [], `${label}.overrides`, { empty: true });
+  overrides.forEach((entry) => stableId(entry, `${label}.overrides entry`));
+  return {
+    id: input.id,
+    kind: input.kind,
+    subject: input.subject,
+    value: canonicalValue(input.value),
+    statement: input.statement,
+    sources,
+    scope: normalizeScope(input.scope, `${label}.scope`),
+    overrides,
+    ...(input.verification !== undefined ? { verification: normalizeVerification(input.verification, `${label}.verification`) } : {}),
+  };
+}
+
+function normalizeSourceInput(input, label) {
+  object(input, label);
+  exactKeys(input, new Set(["id", "kind", "path", "pointer", "reference"]), label);
+  stableId(input.id, `${label}.id`);
+  if (!SOURCE_KINDS.has(input.kind)) invalid(`${label}.kind is invalid`);
+  if (["file", "path", "json-pointer"].includes(input.kind)) {
+    if (input.reference !== undefined) invalid(`${label}.reference is not allowed for local sources`);
+    const normalized = { id: input.id, kind: input.kind, path: projectPath(input.path, `${label}.path`) };
+    if (input.kind === "json-pointer") {
+      string(input.pointer, `${label}.pointer`, { empty: true });
+      if (input.pointer !== "" && !input.pointer.startsWith("/")) invalid(`${label}.pointer must use RFC 6901 syntax`);
+      normalized.pointer = input.pointer;
+    } else if (input.pointer !== undefined) invalid(`${label}.pointer is only allowed for json-pointer`);
+    return normalized;
+  }
+  if (input.path !== undefined || input.pointer !== undefined) invalid(`${label} cannot contain a local path`);
+  string(input.reference, `${label}.reference`);
+  return { id: input.id, kind: input.kind, reference: input.reference };
+}
+
+function normalizeActionInput(kind, input, label) {
+  if (kind === "register-source") return normalizeSourceInput(input, label);
+  if (kind === "propose-item") {
+    const normalized = normalizeItemInput(input, label, ["output"]);
+    return { ...normalized, output: normalizeProposalPath(input.output, `${label}.output`) };
+  }
+  if (kind === "revise-item") {
+    const normalized = normalizeItemInput(input, label, ["expectedItemDigest"]);
+    digest(input.expectedItemDigest, `${label}.expectedItemDigest`);
+    return { ...normalized, expectedItemDigest: input.expectedItemDigest };
+  }
+  if (kind === "accept-source-change") {
+    object(input, label);
+    exactKeys(input, new Set(["id", "sourceObjectDigest", "lockedDigest", "currentDigest", "affectedItems"]), label);
+    stableId(input.id, `${label}.id`);
+    digest(input.sourceObjectDigest, `${label}.sourceObjectDigest`);
+    digest(input.lockedDigest, `${label}.lockedDigest`);
+    digest(input.currentDigest, `${label}.currentDigest`);
+    const affectedItems = uniqueStrings(input.affectedItems, `${label}.affectedItems`, { empty: true });
+    affectedItems.forEach((entry) => stableId(entry, `${label}.affectedItems entry`));
+    return { id: input.id, sourceObjectDigest: input.sourceObjectDigest, lockedDigest: input.lockedDigest, currentDigest: input.currentDigest, affectedItems };
+  }
+  if (kind === "deprecate-item") {
+    object(input, label);
+    exactKeys(input, new Set(["id", "expectedItemDigest", "rationale"]), label);
+    stableId(input.id, `${label}.id`);
+    digest(input.expectedItemDigest, `${label}.expectedItemDigest`);
+    string(input.rationale, `${label}.rationale`);
+    return { id: input.id, expectedItemDigest: input.expectedItemDigest, rationale: input.rationale };
+  }
+  if (kind === "deprecate-source") {
+    object(input, label);
+    exactKeys(input, new Set(["id", "expectedSourceDigest", "affectedItems", "rationale"]), label);
+    stableId(input.id, `${label}.id`);
+    digest(input.expectedSourceDigest, `${label}.expectedSourceDigest`);
+    const affectedItems = uniqueStrings(input.affectedItems, `${label}.affectedItems`, { empty: true });
+    affectedItems.forEach((entry) => stableId(entry, `${label}.affectedItems entry`));
+    string(input.rationale, `${label}.rationale`);
+    return { id: input.id, expectedSourceDigest: input.expectedSourceDigest, affectedItems, rationale: input.rationale };
+  }
+  if (kind === "request-item-approval") {
+    object(input, label);
+    exactKeys(input, new Set(["mode", "ids", "proposal", "proposalDigest", "rationale"]), label);
+    if (!["pending", "proposal"].includes(input.mode)) invalid(`${label}.mode must be pending or proposal`);
+    const ids = uniqueStrings(input.ids, `${label}.ids`);
+    ids.forEach((entry) => stableId(entry, `${label}.ids entry`));
+    if (input.mode === "proposal") {
+      const proposal = normalizeProposalPath(input.proposal, `${label}.proposal`);
+      digest(input.proposalDigest, `${label}.proposalDigest`);
+      if (input.rationale !== undefined) string(input.rationale, `${label}.rationale`, { empty: true });
+      return { mode: input.mode, ids, proposal, proposalDigest: input.proposalDigest, ...(input.rationale !== undefined ? { rationale: input.rationale } : {}) };
+    }
+    if (input.proposal !== undefined || input.proposalDigest !== undefined) invalid(`${label} pending mode cannot contain proposal fields`);
+    if (input.rationale !== undefined) string(input.rationale, `${label}.rationale`, { empty: true });
+    return { mode: input.mode, ids, ...(input.rationale !== undefined ? { rationale: input.rationale } : {}) };
+  }
+  if (kind === "publish-projection") {
+    object(input, label);
+    exactKeys(input, new Set(["target", "output", "paths", "expectedContentDigest"]), label);
+    if (!["agents", "ruler"].includes(input.target)) invalid(`${label}.target must be agents or ruler`);
+    const output = projectPath(input.output, `${label}.output`);
+    const paths = uniqueStrings(input.paths, `${label}.paths`).map((entry) => projectPath(entry, `${label}.paths entry`, { allowRoot: true }));
+    digest(input.expectedContentDigest, `${label}.expectedContentDigest`, { nullable: true });
+    return { target: input.target, output, paths: [...paths].sort(), expectedContentDigest: input.expectedContentDigest };
+  }
+  invalid(`${label} kind is unsupported: ${kind}`);
+}
+
+export function validateActionPlan(input) {
+  object(input, "action plan");
+  exactKeys(input, new Set(["schemaVersion", "projectId", "baselines", "actions"]), "action plan");
+  if (input.schemaVersion !== ACTION_PLAN_SCHEMA_VERSION) invalid(`action plan schemaVersion must be ${ACTION_PLAN_SCHEMA_VERSION}`);
+  stableId(input.projectId, "action plan.projectId");
+  object(input.baselines, "action plan.baselines");
+  exactKeys(input.baselines, new Set(["contract", "sourcesLock", "projectionsLock"]), "action plan.baselines");
+  for (const key of ["contract", "sourcesLock", "projectionsLock"]) digest(input.baselines[key], `action plan.baselines.${key}`);
+  if (!Array.isArray(input.actions) || input.actions.length === 0) invalid("action plan.actions must be a non-empty array");
+  const ids = new Set();
+  const actions = input.actions.map((action, index) => {
+    const label = `action plan.actions[${index}]`;
+    object(action, label);
+    exactKeys(action, new Set(["id", "kind", "input"]), label);
+    stableId(action.id, `${label}.id`);
+    if (ids.has(action.id)) invalid(`action plan contains duplicate action id: ${action.id}`);
+    ids.add(action.id);
+    if (!ACTION_KIND_SET.has(action.kind)) invalid(`${label}.kind is invalid`);
+    return { id: action.id, kind: action.kind, input: normalizeActionInput(action.kind, action.input, `${label}.input`) };
+  }).sort((left, right) => left.id.localeCompare(right.id));
+  return canonicalValue({ schemaVersion: ACTION_PLAN_SCHEMA_VERSION, projectId: input.projectId, baselines: canonicalValue(input.baselines), actions });
+}
+
+export function actionPlanDigest(plan) {
+  return digestJson(validateActionPlan(plan));
+}
+
+function reviewObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) reviewInvalid(`${label} must be an object`);
+}
+
+function reviewExactKeys(value, allowed, label) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) reviewInvalid(`${label} contains unknown field: ${key}`);
+  }
+}
+
+function reviewString(value, label) {
+  if (typeof value !== "string" || value.length === 0) reviewInvalid(`${label} must be a non-empty string`);
+}
+
+function reviewStableId(value, label) {
+  reviewString(value, label);
+  if (!ID.test(value)) reviewInvalid(`${label} must use stable lowercase dot/kebab naming`);
+}
+
+function reviewDigest(value, label) {
+  reviewString(value, label);
+  if (!SHA256.test(value)) reviewInvalid(`${label} must be sha256`);
+}
+
+function reviewStrings(values, label, options = {}) {
+  if (!Array.isArray(values) || (!options.empty && values.length === 0)) {
+    reviewInvalid(`${label} must be ${options.empty ? "an" : "a non-empty"} array`);
+  }
+  const seen = new Set();
+  for (const value of values) {
+    reviewString(value, `${label} entry`);
+    if (seen.has(value)) reviewInvalid(`${label} contains duplicate value: ${value}`);
+    seen.add(value);
+  }
+  return [...values].sort((left, right) => left.localeCompare(right));
+}
+
+function normalizeReviewInvocation(value, label, actionId) {
+  reviewObject(value, label);
+  reviewExactKeys(value, new Set(actionId ? ["actionId", "command", "args"] : ["command", "args"]), label);
+  if (actionId) {
+    reviewStableId(value.actionId, `${label}.actionId`);
+    if (value.actionId !== actionId) reviewInvalid(`${label}.actionId does not match its action`);
+  }
+  reviewString(value.command, `${label}.command`);
+  if (!COMMANDS.includes(value.command)) reviewInvalid(`${label}.command is not a supported command`);
+  if (!Array.isArray(value.args)) reviewInvalid(`${label}.args must be an array`);
+  const args = value.args.map((entry, index) => {
+    if (typeof entry !== "string") reviewInvalid(`${label}.args[${index}] must be a string`);
+    if (["--write", "--by"].includes(entry)) reviewInvalid(`${label} contains an authority-bearing argument: ${entry}`);
+    return entry;
+  });
+  return { ...(actionId ? { actionId } : {}), command: value.command, args };
+}
+
+function normalizeReviewFinding(value, label) {
+  reviewObject(value, label);
+  reviewString(value.code, `${label}.code`);
+  reviewString(value.message, `${label}.message`);
+  if (value.actionId !== undefined) reviewStableId(value.actionId, `${label}.actionId`);
+  try {
+    validateJsonValue(value);
+  } catch (error) {
+    reviewInvalid(`${label} must be JSON-compatible`, { reason: error.message });
+  }
+  return canonicalValue(value);
+}
+
+function normalizeImpact(value, label) {
+  reviewObject(value, label);
+  reviewExactKeys(value, new Set(["itemIds", "sourceIds", "paths", "projectionPaths", "directProjectionPaths"]), label);
+  const itemIds = reviewStrings(value.itemIds, `${label}.itemIds`, { empty: true });
+  itemIds.forEach((entry) => reviewStableId(entry, `${label}.itemIds entry`));
+  const sourceIds = reviewStrings(value.sourceIds, `${label}.sourceIds`, { empty: true });
+  sourceIds.forEach((entry) => reviewStableId(entry, `${label}.sourceIds entry`));
+  return {
+    itemIds,
+    sourceIds,
+    paths: reviewStrings(value.paths, `${label}.paths`, { empty: true }),
+    projectionPaths: reviewStrings(value.projectionPaths, `${label}.projectionPaths`, { empty: true }),
+    ...(value.directProjectionPaths !== undefined
+      ? { directProjectionPaths: reviewStrings(value.directProjectionPaths, `${label}.directProjectionPaths`, { empty: true }) }
+      : {}),
+  };
+}
+
+export function validateReviewBundle(input) {
+  reviewObject(input, "review bundle");
+  reviewExactKeys(input, new Set([
+    "schemaVersion", "projectId", "planDigest", "baselines", "status", "summary", "actions", "groups", "findings", "invocations",
+  ]), "review bundle");
+  if (input.schemaVersion !== REVIEW_BUNDLE_SCHEMA_VERSION) reviewInvalid(`review bundle schemaVersion must be ${REVIEW_BUNDLE_SCHEMA_VERSION}`);
+  reviewStableId(input.projectId, "review bundle.projectId");
+  reviewDigest(input.planDigest, "review bundle.planDigest");
+  reviewObject(input.baselines, "review bundle.baselines");
+  reviewExactKeys(input.baselines, new Set(["contract", "sourcesLock", "projectionsLock"]), "review bundle.baselines");
+  for (const key of ["contract", "sourcesLock", "projectionsLock"]) reviewDigest(input.baselines[key], `review bundle.baselines.${key}`);
+  if (!Array.isArray(input.actions) || input.actions.length === 0) reviewInvalid("review bundle.actions must be a non-empty array");
+  const ids = new Set();
+  const actions = input.actions.map((action, index) => {
+    const label = `review bundle.actions[${index}]`;
+    reviewObject(action, label);
+    reviewExactKeys(action, new Set([
+      "id", "kind", "status", "current", "proposed", "baselines", "impact", "blockers", "humanApprovalRequired", "invocation",
+    ]), label);
+    reviewStableId(action.id, `${label}.id`);
+    if (ids.has(action.id)) reviewInvalid(`review bundle contains duplicate action id: ${action.id}`);
+    ids.add(action.id);
+    if (!ACTION_KIND_SET.has(action.kind)) reviewInvalid(`${label}.kind is invalid`);
+    if (!["reviewable", "blocked"].includes(action.status)) reviewInvalid(`${label}.status is invalid`);
+    if (action.humanApprovalRequired !== true) reviewInvalid(`${label}.humanApprovalRequired must be true`);
+    reviewObject(action.baselines, `${label}.baselines`);
+    for (const key of ["contract", "sourcesLock", "projectionsLock"]) reviewDigest(action.baselines[key], `${label}.baselines.${key}`);
+    if (!Array.isArray(action.blockers)) reviewInvalid(`${label}.blockers must be an array`);
+    const blockers = action.blockers.map((entry, blockerIndex) => normalizeReviewFinding(entry, `${label}.blockers[${blockerIndex}]`));
+    if (action.status === "reviewable" && (blockers.length > 0 || action.invocation === undefined)) {
+      reviewInvalid(`${label} reviewable action must have an invocation and no blockers`);
+    }
+    if (action.status === "blocked" && (blockers.length === 0 || action.invocation !== undefined)) {
+      reviewInvalid(`${label} blocked action must have blockers and no invocation`);
+    }
+    for (const field of ["current", "proposed", "baselines"]) {
+      try {
+        validateJsonValue(action[field]);
+      } catch (error) {
+        reviewInvalid(`${label}.${field} must be JSON-compatible`, { reason: error.message });
+      }
+    }
+    return {
+      id: action.id,
+      kind: action.kind,
+      status: action.status,
+      current: canonicalValue(action.current),
+      proposed: canonicalValue(action.proposed),
+      baselines: canonicalValue(action.baselines),
+      impact: normalizeImpact(action.impact, `${label}.impact`),
+      blockers,
+      humanApprovalRequired: true,
+      ...(action.invocation !== undefined ? { invocation: normalizeReviewInvocation(action.invocation, `${label}.invocation`) } : {}),
+    };
+  }).sort((left, right) => left.id.localeCompare(right.id));
+
+  if (!Array.isArray(input.groups) || input.groups.length === 0) reviewInvalid("review bundle.groups must be a non-empty array");
+  const groups = input.groups.map((group, index) => {
+    const label = `review bundle.groups[${index}]`;
+    reviewObject(group, label);
+    reviewExactKeys(group, new Set(["kind", "actionIds"]), label);
+    if (!["source-change", "new-or-revised-knowledge", "deprecation", "approval-request", "projection", "blocker"].includes(group.kind)) {
+      reviewInvalid(`${label}.kind is invalid`);
+    }
+    const actionIds = reviewStrings(group.actionIds, `${label}.actionIds`);
+    for (const id of actionIds) {
+      reviewStableId(id, `${label}.actionIds entry`);
+      if (!ids.has(id)) reviewInvalid(`${label} references an unknown action: ${id}`);
+    }
+    return { kind: group.kind, actionIds };
+  }).sort((left, right) => left.kind.localeCompare(right.kind));
+
+  if (!Array.isArray(input.findings)) reviewInvalid("review bundle.findings must be an array");
+  const findings = input.findings.map((entry, index) => normalizeReviewFinding(entry, `review bundle.findings[${index}]`));
+  for (const finding of findings) {
+    if (!finding.actionId || !ids.has(finding.actionId)) reviewInvalid("review bundle finding must reference a known action");
+  }
+  if (!Array.isArray(input.invocations)) reviewInvalid("review bundle.invocations must be an array");
+  const actionById = new Map(actions.map((action) => [action.id, action]));
+  const invocations = input.invocations.map((entry, index) => {
+    const normalized = normalizeReviewInvocation(entry, `review bundle.invocations[${index}]`, entry?.actionId);
+    const action = actionById.get(normalized.actionId);
+    if (!action || action.status !== "reviewable") reviewInvalid(`review bundle invocation references a non-reviewable action: ${normalized.actionId}`);
+    if (JSON.stringify(normalized, ["command", "args"]) !== JSON.stringify(action.invocation, ["command", "args"])) {
+      reviewInvalid(`review bundle invocation does not match action: ${normalized.actionId}`);
+    }
+    return normalized;
+  }).sort((left, right) => left.actionId.localeCompare(right.actionId));
+
+  reviewObject(input.summary, "review bundle.summary");
+  reviewExactKeys(input.summary, new Set(["actions", "reviewable", "blocked", "groups"]), "review bundle.summary");
+  const reviewable = actions.filter((action) => action.status === "reviewable").length;
+  const blocked = actions.length - reviewable;
+  const expectedSummary = { actions: actions.length, reviewable, blocked, groups: groups.length };
+  for (const key of Object.keys(expectedSummary)) {
+    if (input.summary[key] !== expectedSummary[key]) reviewInvalid(`review bundle.summary.${key} is inconsistent`);
+  }
+  const expectedStatus = blocked === 0 ? "reviewable" : "blocked";
+  if (input.status !== expectedStatus) reviewInvalid(`review bundle.status must be ${expectedStatus}`);
+  if (invocations.length !== reviewable) reviewInvalid("review bundle must contain exactly one invocation per reviewable action");
+  if (findings.length !== actions.reduce((count, action) => count + action.blockers.length, 0)) {
+    reviewInvalid("review bundle findings must match action blockers");
+  }
+  if (JSON.stringify(input).includes("exchange-preflight-not-authority")) reviewInvalid("review bundle contains internal preview authority data");
+
+  return canonicalValue({
+    schemaVersion: REVIEW_BUNDLE_SCHEMA_VERSION,
+    projectId: input.projectId,
+    planDigest: input.planDigest,
+    baselines: canonicalValue(input.baselines),
+    status: expectedStatus,
+    summary: expectedSummary,
+    actions,
+    groups,
+    findings,
+    invocations,
+  });
+}
+
+export function assertActionPlanConflictFree(plan) {
+  const owners = new Map();
+  const conflicts = [];
+  for (const action of plan.actions) {
+    const targets = [];
+    if (["register-source", "accept-source-change", "deprecate-source"].includes(action.kind)) targets.push(`source:${action.input.id}`);
+    if (["propose-item", "revise-item", "deprecate-item"].includes(action.kind)) targets.push(`item:${action.input.id}`);
+    if (action.kind === "request-item-approval") targets.push(...action.input.ids.map((id) => `item:${id}`));
+    if (action.kind === "publish-projection") targets.push(`projection:${action.input.output}`);
+    for (const target of targets) {
+      const existing = owners.get(target);
+      if (existing) conflicts.push({ target, actions: [existing, action.id].sort() });
+      else owners.set(target, action.id);
+    }
+  }
+  if (conflicts.length > 0) {
+    fail("action-plan-conflict", "action plan contains actions that mutate the same governed target", { exitCode: 1, details: { conflicts } });
+  }
+  return plan;
+}
+
+export function itemPrimitiveInput(input) {
+  return {
+    id: input.id,
+    kind: input.kind,
+    subject: input.subject,
+    value: structuredClone(input.value),
+    statement: input.statement,
+    sources: [...input.sources],
+    scope: input.scope.kind,
+    scopePath: input.scope.path,
+    overrides: [...input.overrides],
+    verification: input.verification?.kind,
+    verificationSource: input.verification?.source,
+    verificationExpectedPresent: Boolean(input.verification && Object.hasOwn(input.verification, "expected")),
+    verificationExpected: input.verification?.expected,
+  };
+}