frontend-project-context 1.0.1 → 1.2.0

package/src/project-context/exchange.mjs

@@ -0,0 +1,623 @@
+import { readFile } from "node:fs/promises";
+import { approvePendingItems, approveProposal } from "./approver.mjs";
+import { registerSource, buildItemProposal } from "./authoring.mjs";
+import { blockingContextFindings, checkProject } from "./checker.mjs";
+import { canonicalJson, digestJson, prettyCanonicalJson, sha256 } from "./canonical-json.mjs";
+import { DASHBOARD_SCHEMA_VERSION } from "./dashboard-model.mjs";
+import { ProjectContextError, fail } from "./errors.mjs";
+import {
+  ACTION_KINDS,
+  ACTION_PLAN_SCHEMA_VERSION,
+  assertActionPlanConflictFree,
+  CAPABILITIES_SCHEMA_VERSION,
+  COMMANDS,
+  EXCHANGE_PROTOCOL_VERSION,
+  itemPrimitiveInput,
+  PACKAGE_VERSION,
+  REVIEW_BUNDLE_SCHEMA_VERSION,
+  validateActionPlan,
+  validateReviewBundle,
+} from "./exchange-schema.mjs";
+import { readJsonFile } from "./io.mjs";
+import { acceptSourceChange, deprecateItem, deprecateSource, reviewSource, reviseItem } from "./maintenance.mjs";
+import { resolveExistingInside, resolveWritableInside } from "./path-policy.mjs";
+import { inspectProjectInitialization, loadProject } from "./project-store.mjs";
+import { publishProjection } from "./projection-store.mjs";
+import { RENDERER_VERSION } from "./renderer.mjs";
+import { ASSIST_BUNDLE_SCHEMA_VERSION } from "./assist.mjs";
+
+const INTERNAL_AUTHORITY_SENTINEL = "exchange-preflight-not-authority";
+const INTERNAL_TIMESTAMP = "1970-01-01T00:00:00.000Z";
+const CONTRACT_SCHEMA_VERSION = 2;
+const PROPOSAL_SCHEMA_VERSION = 1;
+const SOURCE_LOCK_SCHEMA_VERSION = 1;
+const PROJECTION_LOCK_SCHEMA_VERSION = 1;
+const GROUP_BY_ACTION = new Map([
+  ["accept-source-change", "source-change"],
+  ["register-source", "source-change"],
+  ["propose-item", "new-or-revised-knowledge"],
+  ["revise-item", "new-or-revised-knowledge"],
+  ["deprecate-item", "deprecation"],
+  ["deprecate-source", "deprecation"],
+  ["request-item-approval", "approval-request"],
+  ["publish-projection", "projection"],
+]);
+
+function uniqueSorted(values) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function schemas() {
+  return {
+    actionPlan: ACTION_PLAN_SCHEMA_VERSION,
+    assistBundle: ASSIST_BUNDLE_SCHEMA_VERSION,
+    capabilities: CAPABILITIES_SCHEMA_VERSION,
+    contract: CONTRACT_SCHEMA_VERSION,
+    dashboardViewModel: DASHBOARD_SCHEMA_VERSION,
+    projectionLock: PROJECTION_LOCK_SCHEMA_VERSION,
+    projectionRenderer: RENDERER_VERSION,
+    proposal: PROPOSAL_SCHEMA_VERSION,
+    reviewBundle: REVIEW_BUNDLE_SCHEMA_VERSION,
+    sourceLock: SOURCE_LOCK_SCHEMA_VERSION,
+  };
+}
+
+export async function buildCapabilities(root) {
+  const initialization = await inspectProjectInitialization(root);
+  let project = null;
+  if (initialization.status === "initialized") {
+    const loaded = await loadProject(root);
+    project = { id: loaded.contract.project.id, name: loaded.contract.project.name };
+  }
+  return {
+    schemaVersion: CAPABILITIES_SCHEMA_VERSION,
+    package: { name: "frontend-project-context", version: PACKAGE_VERSION },
+    exchangeProtocolVersion: EXCHANGE_PROTOCOL_VERSION,
+    schemas: schemas(),
+    commands: [...COMMANDS],
+    actionKinds: [...ACTION_KINDS],
+    initialization: initialization.status,
+    initialized: initialization.status === "initialized",
+    project,
+    boundaries: {
+      provider: false,
+      agentRuntime: false,
+      git: false,
+      network: false,
+      dependencyInstallation: false,
+      automaticApproval: false,
+      businessCodeWrites: false,
+      applyPlan: false,
+      scheduler: false,
+      daemon: false,
+    },
+  };
+}
+
+function allProjectionPaths(project) {
+  return project.projectionsLock.projections.map((entry) => entry.path).sort();
+}
+
+function directProjectionPaths(project, itemIds) {
+  const ids = new Set(itemIds);
+  return project.projectionsLock.projections
+    .filter((entry) => entry.itemIds.some((id) => ids.has(id)))
+    .map((entry) => entry.path)
+    .sort();
+}
+
+function emptyImpact() {
+  return { itemIds: [], sourceIds: [], paths: [], projectionPaths: [] };
+}
+
+function invocation(root, command, args) {
+  return { command, args: ["--project", root, ...args] };
+}
+
+function itemArgs(input, options = {}) {
+  const args = [
+    "--id", input.id,
+    ...(options.expectedItemDigest ? ["--expected-item-digest", options.expectedItemDigest] : []),
+    "--kind", input.kind,
+    "--subject", input.subject,
+    "--value-json", canonicalJson(input.value),
+    "--statement", input.statement,
+    "--sources", ...input.sources,
+    "--scope", input.scope.kind,
+    ...(input.scope.path ? ["--scope-path", input.scope.path] : []),
+    ...(input.overrides.length > 0 ? ["--overrides", ...input.overrides] : []),
+  ];
+  if (input.verification) {
+    args.push("--verification", input.verification.kind);
+    if (input.verification.source) args.push("--verification-source", input.verification.source);
+    if (Object.hasOwn(input.verification, "expected")) {
+      args.push("--verification-expected-json", canonicalJson(input.verification.expected));
+    }
+  }
+  return args;
+}
+
+function sourceArgs(input) {
+  return [
+    "--id", input.id,
+    "--kind", input.kind,
+    ...(input.path ? ["--path", input.path] : []),
+    ...(input.pointer !== undefined ? ["--pointer", input.pointer] : []),
+    ...(input.reference ? ["--reference", input.reference] : []),
+  ];
+}
+
+async function readIfPresent(filePath) {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function actionBaseline(project, extra = {}) {
+  return {
+    contract: project.contractDigest,
+    sourcesLock: project.sourcesLockDigest,
+    projectionsLock: project.projectionsLockDigest,
+    ...extra,
+  };
+}
+
+async function previewRegister(root, project, action) {
+  const current = project.contract.sources.find((source) => source.id === action.input.id) ?? null;
+  const result = await registerSource(root, project, action.input, { write: false });
+  const projectionPaths = result.action === "create" ? allProjectionPaths(project) : [];
+  return {
+    current: current ? structuredClone(current) : null,
+    proposed: { action: result.action, source: structuredClone(result.source) },
+    baselines: actionBaseline(project, { sourceLocator: action.input }),
+    impact: {
+      itemIds: [],
+      sourceIds: [action.input.id],
+      paths: action.input.path ? [action.input.path] : [],
+      projectionPaths,
+    },
+    invocation: invocation(root, "register", sourceArgs(action.input)),
+  };
+}
+
+async function previewPropose(root, project, action) {
+  const proposal = buildItemProposal(project, itemPrimitiveInput(action.input));
+  const content = prettyCanonicalJson(proposal);
+  const resolved = await resolveWritableInside(root, action.input.output);
+  const existing = await readIfPresent(resolved.absolute);
+  if (existing !== null && existing !== content) {
+    fail("proposal-output-conflict", `refusing to overwrite a different proposal: ${action.input.output}`, {
+      details: { path: action.input.output, currentDigest: sha256(existing), proposedDigest: sha256(content) },
+    });
+  }
+  return {
+    current: existing === null ? null : { path: action.input.output, contentDigest: sha256(existing) },
+    proposed: { path: action.input.output, proposal, contentDigest: sha256(content) },
+    baselines: actionBaseline(project, { proposalOutput: action.input.output, currentContentDigest: existing === null ? null : sha256(existing) }),
+    impact: { itemIds: [action.input.id], sourceIds: [...action.input.sources], paths: [action.input.output], projectionPaths: [] },
+    invocation: invocation(root, "propose", [...itemArgs(action.input), "--output", action.input.output]),
+  };
+}
+
+async function previewAcceptSource(root, project, action) {
+  const review = await reviewSource(root, project, action.input.id);
+  const mismatches = {};
+  if (review.sourceObjectDigest !== action.input.sourceObjectDigest) mismatches.sourceObjectDigest = { expected: action.input.sourceObjectDigest, actual: review.sourceObjectDigest };
+  if (review.lockedDigest !== action.input.lockedDigest) mismatches.lockedDigest = { expected: action.input.lockedDigest, actual: review.lockedDigest };
+  if (review.currentDigest !== action.input.currentDigest) mismatches.currentDigest = { expected: action.input.currentDigest, actual: review.currentDigest };
+  if (Object.keys(mismatches).length > 0) {
+    fail("source-baseline-changed", "source review baseline changed after the action plan was created", { exitCode: 1, details: { source: action.input.id, mismatches } });
+  }
+  const result = await acceptSourceChange(root, project, {
+    id: action.input.id,
+    expectedDigest: action.input.currentDigest,
+    affectedItems: action.input.affectedItems,
+  }, { write: false });
+  return {
+    current: {
+      source: structuredClone(review.source),
+      sourceObjectDigest: review.sourceObjectDigest,
+      lockedDigest: review.lockedDigest,
+      currentDigest: review.currentDigest,
+      status: review.status,
+    },
+    proposed: {
+      acceptedDigest: result.acceptedDigest,
+      affectedItemsBecomePending: [...result.affectedItems],
+      nextContractDigest: result.nextContractDigest,
+    },
+    baselines: actionBaseline(project, {
+      sourceObjectDigest: review.sourceObjectDigest,
+      lockedDigest: review.lockedDigest,
+      currentDigest: review.currentDigest,
+      affectedItems: [...result.affectedItems],
+    }),
+    impact: {
+      itemIds: [...result.affectedItems],
+      sourceIds: [action.input.id],
+      paths: review.source.path ? [review.source.path] : [],
+      projectionPaths: uniqueSorted([...review.impact.directProjectionPaths, ...review.impact.staleProjectionPaths]),
+    },
+    invocation: invocation(root, "accept-source-change", [
+      "--id", action.input.id,
+      "--expected-digest", action.input.currentDigest,
+      ...(action.input.affectedItems.length > 0 ? ["--affected-items", ...action.input.affectedItems] : []),
+    ]),
+  };
+}
+
+async function previewRevise(root, project, action) {
+  const current = project.contract.items.find((item) => item.id === action.input.id);
+  const actualDigest = current ? digestJson(current) : null;
+  if (actualDigest !== action.input.expectedItemDigest) {
+    fail("item-baseline-changed", "item changed after the action plan was created", { exitCode: 1, details: { item: action.input.id, expected: action.input.expectedItemDigest, actual: actualDigest } });
+  }
+  const result = await reviseItem(root, project, { ...itemPrimitiveInput(action.input), expectedItemDigest: action.input.expectedItemDigest }, { write: false });
+  return {
+    current: structuredClone(result.currentItem),
+    proposed: structuredClone(result.proposedItem),
+    baselines: actionBaseline(project, { currentItemDigest: result.currentItemDigest }),
+    impact: {
+      itemIds: [action.input.id],
+      sourceIds: uniqueSorted([...current.sources, ...action.input.sources]),
+      paths: uniqueSorted([current.scope.path, action.input.scope.path].filter(Boolean)),
+      projectionPaths: allProjectionPaths(project),
+      directProjectionPaths: directProjectionPaths(project, [action.input.id]),
+    },
+    invocation: invocation(root, "revise", itemArgs(action.input, { expectedItemDigest: action.input.expectedItemDigest })),
+  };
+}
+
+function withoutAuthority(record, field) {
+  const copy = structuredClone(record);
+  if (field === "approval") delete copy.approval;
+  if (field === "deprecation") delete copy.deprecation;
+  return { ...copy, authorizationRequired: ["human-identity", "execution-time"] };
+}
+
+async function previewDeprecateItem(root, project, action) {
+  const current = project.contract.items.find((item) => item.id === action.input.id);
+  const actualDigest = current ? digestJson(current) : null;
+  if (actualDigest !== action.input.expectedItemDigest) {
+    fail("item-baseline-changed", "item changed after the action plan was created", { exitCode: 1, details: { item: action.input.id, expected: action.input.expectedItemDigest, actual: actualDigest } });
+  }
+  const result = await deprecateItem(project, {
+    id: action.input.id,
+    expectedItemDigest: action.input.expectedItemDigest,
+    rationale: action.input.rationale,
+    by: INTERNAL_AUTHORITY_SENTINEL,
+    at: INTERNAL_TIMESTAMP,
+  }, { write: false });
+  const blockers = result.preflightFindings.length > 0
+    ? [{
+      code: "maintenance-preflight-failed",
+      message: "item deprecation would leave invalid overrides or conflicts",
+      details: { item: action.input.id, findings: result.preflightFindings },
+    }]
+    : [];
+  return {
+    current: structuredClone(result.currentItem),
+    proposed: withoutAuthority(result.deprecatedItem, "approval"),
+    baselines: actionBaseline(project, { currentItemDigest: result.currentItemDigest }),
+    impact: {
+      itemIds: uniqueSorted([
+        action.input.id,
+        ...result.relationships.overrideDependents.map((item) => item.id),
+        ...result.relationships.fallbackItems.map((item) => item.id),
+      ]),
+      sourceIds: [...result.currentItem.sources],
+      paths: result.currentItem.scope.path ? [result.currentItem.scope.path] : [],
+      projectionPaths: allProjectionPaths(project),
+      directProjectionPaths: directProjectionPaths(project, [action.input.id]),
+    },
+    blockers,
+    invocation: invocation(root, "deprecate", [
+      "--id", action.input.id,
+      "--expected-item-digest", action.input.expectedItemDigest,
+      "--rationale", action.input.rationale,
+    ]),
+  };
+}
+
+async function previewDeprecateSource(root, project, action) {
+  const current = project.contract.sources.find((source) => source.id === action.input.id);
+  const actualDigest = current ? digestJson(current) : null;
+  if (actualDigest !== action.input.expectedSourceDigest) {
+    fail("source-baseline-changed", "source changed after the action plan was created", { exitCode: 1, details: { source: action.input.id, expected: action.input.expectedSourceDigest, actual: actualDigest } });
+  }
+  const result = await deprecateSource(project, {
+    id: action.input.id,
+    expectedSourceDigest: action.input.expectedSourceDigest,
+    rationale: action.input.rationale,
+    by: INTERNAL_AUTHORITY_SENTINEL,
+    at: INTERNAL_TIMESTAMP,
+  }, { write: false });
+  const affectedItems = result.impact.items.map((item) => item.id);
+  if (JSON.stringify(affectedItems) !== JSON.stringify(action.input.affectedItems)) {
+    fail("source-impact-changed", "source impact changed after the action plan was created", {
+      exitCode: 1,
+      details: { source: action.input.id, expected: action.input.affectedItems, actual: affectedItems },
+    });
+  }
+  const blockers = result.blockingItems.length > 0
+    ? [{
+      code: "source-still-referenced",
+      message: "source is still referenced by proposed or approved items",
+      details: { source: action.input.id, items: result.blockingItems },
+    }]
+    : [];
+  const proposed = result.deprecatedSource
+    ? withoutAuthority(result.deprecatedSource, "deprecation")
+    : {
+      ...structuredClone(result.currentSource),
+      status: "deprecated",
+      rationale: action.input.rationale,
+      authorizationRequired: ["human-identity", "execution-time"],
+    };
+  return {
+    current: structuredClone(result.currentSource),
+    proposed,
+    baselines: actionBaseline(project, { currentSourceDigest: result.currentSourceDigest }),
+    impact: {
+      itemIds: affectedItems,
+      sourceIds: [action.input.id],
+      paths: result.currentSource.path ? [result.currentSource.path] : [],
+      projectionPaths: uniqueSorted([...result.impact.directProjectionPaths, ...result.impact.staleProjectionPaths]),
+    },
+    blockers,
+    invocation: invocation(root, "deprecate-source", [
+      "--id", action.input.id,
+      "--expected-source-digest", action.input.expectedSourceDigest,
+      "--rationale", action.input.rationale,
+    ]),
+  };
+}
+
+function approvedIntent(item, rationale) {
+  const proposed = structuredClone(item);
+  proposed.status = "approved";
+  delete proposed.approval;
+  return { ...proposed, authorizationRequired: ["human-identity", "execution-time"], ...(rationale !== undefined ? { rationale } : {}) };
+}
+
+async function previewApproval(root, project, action) {
+  let result;
+  let current;
+  let proposalDigest = null;
+  if (action.input.mode === "pending") {
+    current = action.input.ids.map((id) => project.contract.items.find((item) => item.id === id) ?? null);
+    result = await approvePendingItems(root, project, {
+      ids: action.input.ids,
+      by: INTERNAL_AUTHORITY_SENTINEL,
+      at: INTERNAL_TIMESTAMP,
+      rationale: action.input.rationale,
+      write: false,
+    });
+  } else {
+    const resolved = await resolveExistingInside(root, action.input.proposal);
+    const proposal = await readJsonFile(resolved.absolute, "proposal");
+    proposalDigest = digestJson(proposal);
+    if (proposalDigest !== action.input.proposalDigest) {
+      fail("proposal-baseline-changed", "proposal changed after the action plan was created", { exitCode: 1, details: { path: action.input.proposal, expected: action.input.proposalDigest, actual: proposalDigest } });
+    }
+    current = action.input.ids.map((id) => proposal.items?.find((item) => item.id === id) ?? null);
+    result = await approveProposal(root, project, proposal, {
+      ids: action.input.ids,
+      by: INTERNAL_AUTHORITY_SENTINEL,
+      at: INTERNAL_TIMESTAMP,
+      rationale: action.input.rationale,
+      write: false,
+    });
+  }
+  const approvedById = new Map(result.contract.items.map((item) => [item.id, item]));
+  const proposed = action.input.ids.map((id) => approvedIntent(approvedById.get(id), action.input.rationale));
+  const sourceIds = uniqueSorted(proposed.flatMap((item) => item.sources));
+  return {
+    current: structuredClone(current),
+    proposed,
+    baselines: actionBaseline(project, {
+      mode: action.input.mode,
+      ...(action.input.mode === "proposal" ? { proposalPath: action.input.proposal, proposalDigest } : {}),
+      itemDigests: Object.fromEntries(current.filter(Boolean).map((item) => [item.id, digestJson(item)]).sort()),
+    }),
+    impact: {
+      itemIds: [...action.input.ids],
+      sourceIds,
+      paths: action.input.mode === "proposal" ? [action.input.proposal] : [],
+      projectionPaths: allProjectionPaths(project),
+      directProjectionPaths: directProjectionPaths(project, action.input.ids),
+    },
+    invocation: invocation(root, "approve", [
+      ...(action.input.mode === "pending" ? ["--pending"] : ["--proposal", action.input.proposal]),
+      "--ids", ...action.input.ids,
+      ...(action.input.rationale !== undefined ? ["--rationale", action.input.rationale] : []),
+    ]),
+  };
+}
+
+async function previewPublish(root, project, action) {
+  const blocking = blockingContextFindings(await checkProject(root, project));
+  if (blocking.length > 0) fail("publish-blocked", "projection is blocked by contract or source findings", { exitCode: 1, details: { findings: blocking } });
+  const resolved = await resolveWritableInside(root, action.input.output);
+  const existing = await readIfPresent(resolved.absolute);
+  const currentContentDigest = existing === null ? null : sha256(existing);
+  if (currentContentDigest !== action.input.expectedContentDigest) {
+    fail("projection-baseline-changed", "projection content changed after the action plan was created", { exitCode: 1, details: { path: action.input.output, expected: action.input.expectedContentDigest, actual: currentContentDigest } });
+  }
+  const currentEntry = project.projectionsLock.projections.find((entry) => entry.path === action.input.output) ?? null;
+  const result = await publishProjection(root, project, {
+    target: action.input.target,
+    output: action.input.output,
+    paths: action.input.paths,
+    write: false,
+  });
+  return {
+    current: { entry: structuredClone(currentEntry), content: existing, contentDigest: currentContentDigest },
+    proposed: { action: result.action, entry: result.entry, content: result.content },
+    baselines: actionBaseline(project, { currentContentDigest, currentLockEntry: structuredClone(currentEntry) }),
+    impact: {
+      itemIds: [...result.entry.itemIds],
+      sourceIds: uniqueSorted(project.contract.items.filter((item) => result.entry.itemIds.includes(item.id)).flatMap((item) => item.sources)),
+      paths: uniqueSorted([...action.input.paths, action.input.output]),
+      projectionPaths: [action.input.output],
+    },
+    invocation: invocation(root, "publish", [
+      "--target", action.input.target,
+      "--output", action.input.output,
+      "--path", ...action.input.paths,
+    ]),
+  };
+}
+
+async function previewAction(root, project, action) {
+  if (action.kind === "register-source") return previewRegister(root, project, action);
+  if (action.kind === "propose-item") return previewPropose(root, project, action);
+  if (action.kind === "accept-source-change") return previewAcceptSource(root, project, action);
+  if (action.kind === "revise-item") return previewRevise(root, project, action);
+  if (action.kind === "deprecate-item") return previewDeprecateItem(root, project, action);
+  if (action.kind === "deprecate-source") return previewDeprecateSource(root, project, action);
+  if (action.kind === "request-item-approval") return previewApproval(root, project, action);
+  if (action.kind === "publish-projection") return previewPublish(root, project, action);
+  fail("action-plan-schema-invalid", `unsupported action kind: ${action.kind}`);
+}
+
+function blocker(error) {
+  return {
+    code: error instanceof ProjectContextError ? error.code : "internal-error",
+    message: error instanceof Error ? error.message : String(error),
+    ...(error?.details ? { details: structuredClone(error.details) } : {}),
+  };
+}
+
+function blockedContext(project, action, error) {
+  let current = null;
+  const impact = emptyImpact();
+  if (["accept-source-change", "deprecate-source", "register-source"].includes(action.kind)) {
+    current = structuredClone(project.contract.sources.find((source) => source.id === action.input.id) ?? null);
+    impact.sourceIds = [action.input.id];
+    if (current?.path) impact.paths = [current.path];
+  }
+  if (["deprecate-item", "revise-item", "propose-item"].includes(action.kind)) {
+    current = structuredClone(project.contract.items.find((item) => item.id === action.input.id) ?? null);
+    impact.itemIds = [action.input.id];
+    impact.sourceIds = [...(current?.sources ?? action.input.sources ?? [])].sort();
+    if (current?.scope?.path) impact.paths = [current.scope.path];
+  }
+  if (action.kind === "request-item-approval") {
+    current = action.input.ids.map((id) => structuredClone(project.contract.items.find((item) => item.id === id) ?? null));
+    impact.itemIds = [...action.input.ids];
+  }
+  if (action.kind === "publish-projection") {
+    current = structuredClone(project.projectionsLock.projections.find((entry) => entry.path === action.input.output) ?? null);
+    impact.paths = uniqueSorted([...action.input.paths, action.input.output]);
+    impact.projectionPaths = [action.input.output];
+  }
+  return {
+    current,
+    proposed: { intent: structuredClone(action.input), authorizationRequired: ["human-approval"] },
+    baselines: actionBaseline(project, { blocker: error.code }),
+    impact,
+  };
+}
+
+function groupsFor(actions) {
+  const byKind = new Map();
+  for (const action of actions) {
+    const kind = GROUP_BY_ACTION.get(action.kind);
+    if (!byKind.has(kind)) byKind.set(kind, []);
+    byKind.get(kind).push(action.id);
+    if (action.status === "blocked") {
+      if (!byKind.has("blocker")) byKind.set("blocker", []);
+      byKind.get("blocker").push(action.id);
+    }
+  }
+  return [...byKind]
+    .map(([kind, actionIds]) => ({ kind, actionIds: uniqueSorted(actionIds) }))
+    .sort((left, right) => left.kind.localeCompare(right.kind));
+}
+
+export async function preflightActionPlan(root, project, input) {
+  const plan = validateActionPlan(input);
+  if (plan.projectId !== project.contract.project.id) {
+    fail("action-plan-project-mismatch", "action plan belongs to a different project", { details: { expected: project.contract.project.id, actual: plan.projectId } });
+  }
+  const currentBaselines = {
+    contract: project.contractDigest,
+    sourcesLock: project.sourcesLockDigest,
+    projectionsLock: project.projectionsLockDigest,
+  };
+  const changed = Object.keys(currentBaselines).filter((key) => currentBaselines[key] !== plan.baselines[key]);
+  if (changed.length > 0) {
+    fail("action-plan-baseline-changed", "action plan project snapshot is stale", { exitCode: 1, details: { changed, expected: plan.baselines, actual: currentBaselines } });
+  }
+  assertActionPlanConflictFree(plan);
+
+  const actions = [];
+  const findings = [];
+  for (const action of plan.actions) {
+    try {
+      const preview = await previewAction(root, project, action);
+      const blockers = preview.blockers ?? [];
+      const reviewable = blockers.length === 0;
+      actions.push({
+        id: action.id,
+        kind: action.kind,
+        status: reviewable ? "reviewable" : "blocked",
+        current: preview.current,
+        proposed: preview.proposed,
+        baselines: preview.baselines,
+        impact: preview.impact,
+        blockers,
+        humanApprovalRequired: true,
+        ...(reviewable ? { invocation: preview.invocation } : {}),
+      });
+      for (const entry of blockers) findings.push({ actionId: action.id, ...entry });
+    } catch (error) {
+      if (!(error instanceof ProjectContextError)) throw error;
+      const finding = { actionId: action.id, ...blocker(error) };
+      const context = blockedContext(project, action, error);
+      findings.push(finding);
+      actions.push({
+        id: action.id,
+        kind: action.kind,
+        status: "blocked",
+        current: context.current,
+        proposed: context.proposed,
+        baselines: context.baselines,
+        impact: context.impact,
+        blockers: [finding],
+        humanApprovalRequired: true,
+      });
+    }
+  }
+  const groups = groupsFor(actions);
+  const invocations = actions.filter((action) => action.status === "reviewable").map((action) => ({ actionId: action.id, ...action.invocation }));
+  const reviewable = actions.filter((action) => action.status === "reviewable").length;
+  return validateReviewBundle({
+    schemaVersion: REVIEW_BUNDLE_SCHEMA_VERSION,
+    projectId: plan.projectId,
+    planDigest: digestJson(plan),
+    baselines: currentBaselines,
+    status: reviewable === actions.length ? "reviewable" : "blocked",
+    summary: {
+      actions: actions.length,
+      reviewable,
+      blocked: actions.length - reviewable,
+      groups: groups.length,
+    },
+    actions,
+    groups,
+    findings,
+    invocations,
+  });
+}
+
+export async function preflightActionPlanFile(root, planPath) {
+  const resolved = await resolveExistingInside(root, planPath);
+  const plan = await readJsonFile(resolved.absolute, "action plan");
+  const project = await loadProject(root);
+  return preflightActionPlan(root, project, plan);
+}

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

@@ -43,6 +43,28 @@ async function exists(filePath) {
   }
 }
 
+export async function inspectProjectInitialization(root) {
+  const files = projectFiles(root);
+  const entries = [
+    [CONTEXT_DIRECTORY, files.directory],
+    [`${CONTEXT_DIRECTORY}/${CONTRACT_FILE}`, files.contract],
+    [`${CONTEXT_DIRECTORY}/${SOURCES_LOCK_FILE}`, files.sourcesLock],
+    [`${CONTEXT_DIRECTORY}/${PROJECTIONS_LOCK_FILE}`, files.projectionsLock],
+  ];
+  const present = [];
+  for (const [relative, absolute] of entries) {
+    if (await exists(absolute)) present.push(relative);
+  }
+  const storePaths = entries.slice(1).map(([relative]) => relative);
+  const complete = storePaths.every((relative) => present.includes(relative));
+  return {
+    status: present.length === 0 ? "uninitialized" : complete ? "initialized" : "partial",
+    files,
+    present,
+    missing: storePaths.filter((relative) => !present.includes(relative)),
+  };
+}
+
 export async function initializeProject(root, id, name, write) {
   const files = projectFiles(root);
   const initial = initialProjectFiles(id, name);