frontend-project-context 1.3.1 → 1.7.0

package/src/project-context/evidence.mjs

@@ -0,0 +1,99 @@
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+import { PERMANENT_BOUNDARIES } from "./capabilities.mjs";
+import { fail, ProjectContextError } from "./errors.mjs";
+import { EVIDENCE_BUNDLE_SCHEMA_VERSION, finalizeEvidenceBundle, normalizeEvidenceInput } from "./evidence-schema.mjs";
+import { EXCHANGE_PROTOCOL_VERSION, PACKAGE_VERSION } from "./exchange-schema.mjs";
+import { normalizeRelativePath, resolveExistingInside } from "./path-policy.mjs";
+import { buildProjectStatus } from "./project-status.mjs";
+
+async function readEvidenceInput(root, inputPath) {
+  let normalized;
+  try {
+    normalized = normalizeRelativePath(inputPath, { label: "evidence input" });
+  } catch (error) {
+    fail("evidence-input-outside-project", "evidence input must stay inside the project", { cause: error, details: { path: inputPath } });
+  }
+  const candidate = path.join(root, normalized);
+  let info;
+  try {
+    info = await lstat(candidate);
+  } catch (error) {
+    if (error?.code === "ENOENT") fail("evidence-input-missing", `evidence input does not exist: ${normalized}`, { cause: error });
+    fail("evidence-input-invalid", `cannot inspect evidence input: ${normalized}`, { cause: error });
+  }
+  if (info.isSymbolicLink()) {
+    fail("evidence-input-outside-project", "evidence input cannot be a symlink", { details: { path: normalized } });
+  }
+  if (!info.isFile()) fail("evidence-input-invalid", "evidence input must be an ordinary file", { details: { path: normalized } });
+  let resolved;
+  try {
+    resolved = await resolveExistingInside(root, normalized);
+  } catch (error) {
+    if (error?.code === "path-outside-project") {
+      fail("evidence-input-outside-project", "evidence input must stay inside the project", { cause: error, details: { path: normalized } });
+    }
+    if (error?.code === "source-missing") fail("evidence-input-missing", `evidence input does not exist: ${normalized}`, { cause: error });
+    throw error;
+  }
+  let source;
+  try {
+    source = await readFile(resolved.absolute, "utf8");
+  } catch (error) {
+    fail("evidence-input-invalid", `cannot read evidence input: ${normalized}`, { cause: error });
+  }
+  try {
+    return JSON.parse(source);
+  } catch (error) {
+    fail("evidence-input-invalid", "evidence input contains invalid JSON", { cause: error });
+  }
+}
+
+function minimalProjectContext(status) {
+  return {
+    initialization: status.initialization.state,
+    health: status.health,
+    entryState: status.entry.state,
+    findingCodes: [...new Set(status.findingCodes)].sort((left, right) => left.localeCompare(right)),
+    schemas: {
+      contract: 2,
+      sourcesLock: 1,
+      projectionsLock: 2,
+    },
+  };
+}
+
+export async function buildEvidenceBundle(root, input) {
+  const normalized = normalizeEvidenceInput(input);
+  let statusResult;
+  try {
+    statusResult = await buildProjectStatus(root, PERMANENT_BOUNDARIES);
+  } catch (error) {
+    fail("evidence-project-state-unreadable", "cannot form minimal Project Context status", {
+      cause: error,
+      details: { reason: error instanceof ProjectContextError ? error.code : "internal-state-error" },
+    });
+  }
+  const { schemaVersion: _inputSchemaVersion, ...observation } = normalized;
+  return finalizeEvidenceBundle({
+    schemaVersion: EVIDENCE_BUNDLE_SCHEMA_VERSION,
+    kind: "target-project-evidence",
+    product: {
+      name: "frontend-project-context",
+      version: PACKAGE_VERSION,
+      exchangeProtocolVersion: EXCHANGE_PROTOCOL_VERSION,
+    },
+    ...observation,
+    projectContext: minimalProjectContext(statusResult.status),
+    transfer: {
+      state: "human-review-required",
+      automaticUpload: false,
+      destination: null,
+    },
+    boundaries: { ...PERMANENT_BOUNDARIES },
+  });
+}
+
+export async function buildEvidenceBundleFile(root, inputPath) {
+  return buildEvidenceBundle(root, await readEvidenceInput(root, inputPath));
+}

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

@@ -2,27 +2,31 @@ import { canonicalValue, digestJson, validateJsonValue } from "./canonical-json.
 import { fail } from "./errors.mjs";
 import { normalizeRelativePath } from "./path-policy.mjs";
 
-export const PACKAGE_VERSION = "1.3.1";
-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 PACKAGE_VERSION = "1.7.0";
+export const EXCHANGE_PROTOCOL_VERSION = 7;
+export const ACTION_PLAN_SCHEMA_VERSION = 2;
+export const REVIEW_BUNDLE_SCHEMA_VERSION = 2;
+export const CAPABILITIES_SCHEMA_VERSION = 7;
 
 export const ACTION_KINDS = Object.freeze([
   "accept-source-change",
   "deprecate-item",
   "deprecate-source",
   "propose-item",
+  "publish-ai-entry",
   "publish-projection",
   "register-source",
+  "remove-ai-entry",
   "request-item-approval",
   "revise-item",
 ]);
 
 export const COMMANDS = Object.freeze([
-  "accept-source-change", "approve", "capabilities", "check", "context", "dashboard", "deprecate",
-  "deprecate-source", "discover", "init", "integration-review", "preflight", "propose", "publish", "register",
-  "review-source", "revise", "setup", "stage-context", "sync",
+  "accept-source-change", "approve", "capabilities", "check", "context", "context-query", "coverage-audit", "dashboard", "deprecate",
+  "deprecate-source", "discover", "evidence", "init", "integration-review", "preflight", "propose", "publish", "register",
+  "index-context", "publish-entry", "remove-entry", "review-source", "revise", "setup", "stage-context", "status", "sync",
+  "upgrade-apply", "upgrade-check", "upgrade-plan",
+  "reconcile-truth",
 ]);
 
 const ACTION_KIND_SET = new Set(ACTION_KINDS);
@@ -253,13 +257,20 @@ function normalizeActionInput(kind, input, label) {
     digest(input.expectedContentDigest, `${label}.expectedContentDigest`, { nullable: true });
     return { target: input.target, output, paths: [...paths].sort(), expectedContentDigest: input.expectedContentDigest };
   }
+  if (kind === "publish-ai-entry" || kind === "remove-ai-entry") {
+    object(input, label);
+    exactKeys(input, new Set(["output"]), label);
+    const output = projectPath(input.output, `${label}.output`);
+    if (output.split("/").at(-1) !== "AGENTS.md") invalid(`${label}.output must name AGENTS.md`);
+    return { output };
+  }
   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}`);
+  if (![1, ACTION_PLAN_SCHEMA_VERSION].includes(input.schemaVersion)) invalid(`action plan schemaVersion must be 1 or ${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");
@@ -273,10 +284,10 @@ export function validateActionPlan(input) {
     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`);
+    if (!ACTION_KIND_SET.has(action.kind) || (input.schemaVersion === 1 && ["publish-ai-entry", "remove-ai-entry"].includes(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 });
+  return canonicalValue({ schemaVersion: input.schemaVersion, projectId: input.projectId, baselines: canonicalValue(input.baselines), actions });
 }
 
 export function actionPlanDigest(plan) {
@@ -496,7 +507,7 @@ export function assertActionPlanConflictFree(plan) {
     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}`);
+    if (["publish-projection", "publish-ai-entry", "remove-ai-entry"].includes(action.kind)) 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() });

package/src/project-context/exchange.mjs

@@ -16,6 +16,7 @@ import { acceptSourceChange, deprecateItem, deprecateSource, reviewSource, revis
 import { resolveExistingInside, resolveWritableInside } from "./path-policy.mjs";
 import { loadProject } from "./project-store.mjs";
 import { publishProjection } from "./projection-store.mjs";
+import { publishAiEntry, removeAiEntry } from "./ai-entry.mjs";
 export { buildCapabilities } from "./capabilities.mjs";
 
 const INTERNAL_AUTHORITY_SENTINEL = "exchange-preflight-not-authority";
@@ -29,6 +30,8 @@ const GROUP_BY_ACTION = new Map([
   ["deprecate-source", "deprecation"],
   ["request-item-approval", "approval-request"],
   ["publish-projection", "projection"],
+  ["publish-ai-entry", "projection"],
+  ["remove-ai-entry", "projection"],
 ]);
 
 function uniqueSorted(values) {
@@ -37,13 +40,13 @@ function uniqueSorted(values) {
 
 
 function allProjectionPaths(project) {
-  return project.projectionsLock.projections.map((entry) => entry.path).sort();
+  return project.projectionsLock.projections.filter((entry) => entry.ownership !== "region").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)))
+    .filter((entry) => entry.ownership !== "region" && entry.itemIds.some((id) => ids.has(id)))
     .map((entry) => entry.path)
     .sort();
 }
@@ -414,6 +417,24 @@ async function previewPublish(root, project, action) {
   };
 }
 
+async function previewEntry(root, project, action) {
+  const result = action.kind === "publish-ai-entry"
+    ? await publishAiEntry(root, project, { output: action.input.output, write: false })
+    : await removeAiEntry(root, project, { output: action.input.output, write: false });
+  return {
+    current: result.current,
+    proposed: { ...result.proposed, action: result.action, migration: result.migration, afterSourceDigest: result.impact.afterSourceDigest },
+    baselines: actionBaseline(project, { currentContentDigest: result.baselines.content }),
+    impact: {
+      itemIds: result.impact.itemIds,
+      sourceIds: result.impact.sourceIds,
+      paths: result.impact.paths,
+      projectionPaths: result.impact.projectionPaths,
+    },
+    invocation: invocation(root, action.kind === "publish-ai-entry" ? "publish-entry" : "remove-entry", ["--output", action.input.output]),
+  };
+}
+
 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);
@@ -423,6 +444,7 @@ async function previewAction(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);
+  if (action.kind === "publish-ai-entry" || action.kind === "remove-ai-entry") return previewEntry(root, project, action);
   fail("action-plan-schema-invalid", `unsupported action kind: ${action.kind}`);
 }
 
@@ -452,9 +474,9 @@ function blockedContext(project, action, error) {
     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") {
+  if (["publish-projection", "publish-ai-entry", "remove-ai-entry"].includes(action.kind)) {
     current = structuredClone(project.projectionsLock.projections.find((entry) => entry.path === action.input.output) ?? null);
-    impact.paths = uniqueSorted([...action.input.paths, action.input.output]);
+    impact.paths = uniqueSorted([...(action.input.paths ?? []), action.input.output]);
     impact.projectionPaths = [action.input.output];
   }
   return {

package/src/project-context/maintenance.mjs

@@ -72,14 +72,14 @@ export function sourceImpact(project, sourceId) {
   const relations = relationDetails(project.contract, sourceId);
   const affectedIds = new Set(relations.items.map((item) => item.id));
   const directProjectionPaths = project.projectionsLock.projections
-    .filter((entry) => entry.itemIds.some((id) => affectedIds.has(id)))
+    .filter((entry) => entry.ownership !== "region" && entry.itemIds.some((id) => affectedIds.has(id)))
     .map((entry) => entry.path)
     .sort();
-  const staleProjectionPaths = project.projectionsLock.projections.map((entry) => entry.path).sort();
+  const staleProjectionPaths = project.projectionsLock.projections.filter((entry) => entry.ownership !== "region").map((entry) => entry.path).sort();
   return { ...relations, directProjectionPaths, staleProjectionPaths };
 }
 
-export async function reviewSource(root, project, sourceId) {
+export async function reviewSource(root, project, sourceId, options = {}) {
   const source = project.contract.sources.find((entry) => entry.id === sourceId);
   if (!source) fail("source-not-found", `source is not registered: ${sourceId}`, { details: { source: sourceId } });
   const sourceObjectDigest = digestJson(source);
@@ -104,7 +104,7 @@ export async function reviewSource(root, project, sourceId) {
   let status;
   let reason;
   try {
-    currentDigest = await readSourceDigest(root, source);
+    currentDigest = await readSourceDigest(root, source, options.sourceReadContext);
     if (lockedDigest === null || lockedDigest !== source.digest) {
       status = "unreadable";
       reason = lockedDigest === null ? "source-lock-missing" : "source-lock-mismatch";

package/src/project-context/migration-manifest.mjs

@@ -0,0 +1,168 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { digestJson } from "./canonical-json.mjs";
+import { fail } from "./errors.mjs";
+
+export const MIGRATION_MANIFEST_SCHEMA_VERSION = 2;
+
+export const BUILT_IN_MIGRATIONS = Object.freeze({
+  "upgrade.republish-ai-entry.v1": "republish-ai-entry",
+  "upgrade.republish-projection.v1": "republish-projection",
+});
+
+const MANIFEST_FILE = fileURLToPath(new URL("../../migration-manifest.json", import.meta.url));
+const SHA256 = /^sha256:[a-f0-9]{64}$/u;
+const VERSION = /^\d+\.\d+\.\d+$/u;
+const MIGRATION_KINDS = new Set([
+  "package-only",
+  "republish-ai-entry",
+  "republish-projection",
+  "built-in-store-migration",
+  "invalidate-ephemeral-protocol",
+]);
+const ROLLBACK_CLASSES = new Set(["package-only", "reversible-data", "forward-only"]);
+const CONSUMER_CHANGE_KEYS = new Set([
+  "actionPlan", "adaptiveContextBundle", "capabilities", "contextQuery", "coverageAudit", "evidenceBundle", "evidenceInput", "exchange",
+  "hostPromotionEvidence", "integrationReviewBundle", "reviewBundle", "routingIndex", "stageContextBundle", "stageReceipt", "taskContextPlan",
+  "truthReconciliationInput", "truthReconciliationReviewBundle",
+]);
+
+function invalid(message, details) {
+  fail("upgrade-manifest-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) {
+  object(value, label);
+  const keys = Object.keys(value).sort();
+  const expected = [...allowed].sort();
+  if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index])) {
+    invalid(`${label} must contain exactly: ${expected.join(", ")}`);
+  }
+}
+
+function string(value, label) {
+  if (typeof value !== "string" || value.length === 0) invalid(`${label} must be a non-empty string`);
+}
+
+function boolean(value, label) {
+  if (typeof value !== "boolean") invalid(`${label} must be a boolean`);
+}
+
+function integer(value, label) {
+  if (!Number.isInteger(value) || value < 1) invalid(`${label} must be a positive integer`);
+}
+
+function sortedUnique(values, label, validate = string) {
+  if (!Array.isArray(values)) invalid(`${label} must be an array`);
+  values.forEach((value) => validate(value, `${label} entry`));
+  const sorted = [...values].sort((left, right) => String(left).localeCompare(String(right)));
+  if (new Set(values).size !== values.length || values.some((value, index) => value !== sorted[index])) {
+    invalid(`${label} must be unique and sorted`);
+  }
+}
+
+function versions(values, label) {
+  sortedUnique(values, label, (value, entryLabel) => {
+    string(value, entryLabel);
+    if (!VERSION.test(value)) invalid(`${entryLabel} must be an exact semantic version`);
+  });
+}
+
+function versionMatrix(value, label) {
+  exactKeys(value, new Set(["readable", "written"]), label);
+  sortedUnique(value.readable, `${label}.readable`, integer);
+  if (Array.isArray(value.written)) sortedUnique(value.written, `${label}.written`, integer);
+  else integer(value.written, `${label}.written`);
+}
+
+function validateMigration(entry, index) {
+  const label = `builtInMigrations[${index}]`;
+  exactKeys(entry, new Set(["id", "kind", "input", "targetType", "writes", "rollbackClass", "reverseMigrationId"]), label);
+  string(entry.id, `${label}.id`);
+  if (!MIGRATION_KINDS.has(entry.kind)) invalid(`${label}.kind is unsupported`);
+  exactKeys(entry.input, new Set(["schemaVersions", "beforeDigestRequired"]), `${label}.input`);
+  sortedUnique(entry.input.schemaVersions, `${label}.input.schemaVersions`, integer);
+  boolean(entry.input.beforeDigestRequired, `${label}.input.beforeDigestRequired`);
+  if (!["none", "ai-entry", "projection", "store", "ephemeral-protocol"].includes(entry.targetType)) invalid(`${label}.targetType is invalid`);
+  boolean(entry.writes, `${label}.writes`);
+  if (!ROLLBACK_CLASSES.has(entry.rollbackClass)) invalid(`${label}.rollbackClass is invalid`);
+  if (entry.reverseMigrationId !== null) string(entry.reverseMigrationId, `${label}.reverseMigrationId`);
+  if (entry.rollbackClass === "reversible-data" && entry.reverseMigrationId === null) invalid(`${label} requires a reverse migration`);
+  if (BUILT_IN_MIGRATIONS[entry.id] !== entry.kind) invalid(`${label} does not match the runtime migration registry`);
+}
+
+export function validateMigrationManifest(input) {
+  const manifest = structuredClone(input);
+  exactKeys(manifest, new Set([
+    "schemaVersion", "package", "upgradeFrom", "stores", "renderers", "protocols", "paths",
+    "builtInMigrations", "consumerChanges", "acceptanceCommands", "rollback", "externalEffects", "manifestDigest",
+  ]), "migration manifest");
+  if (manifest.schemaVersion !== MIGRATION_MANIFEST_SCHEMA_VERSION) invalid("migration manifest schemaVersion must be 2");
+  exactKeys(manifest.package, new Set(["name", "version"]), "migration manifest package");
+  if (manifest.package.name !== "frontend-project-context" || manifest.package.version !== "1.7.0") invalid("migration manifest package does not match this runtime");
+  versions(manifest.upgradeFrom, "upgradeFrom");
+  if (manifest.upgradeFrom.length === 0) invalid("upgradeFrom must not be empty");
+  exactKeys(manifest.stores, new Set(["contract", "projectionLock", "proposal", "sourceLock"]), "stores");
+  for (const name of Object.keys(manifest.stores)) versionMatrix(manifest.stores[name], `stores.${name}`);
+  exactKeys(manifest.renderers, new Set(["aiEntry", "projection"]), "renderers");
+  for (const name of Object.keys(manifest.renderers)) versionMatrix(manifest.renderers[name], `renderers.${name}`);
+  exactKeys(manifest.protocols, new Set([
+    "exchange", "actionPlan", "adaptiveContextBundle", "contextQuery", "coverageAudit", "reviewBundle", "evidenceInput", "evidenceBundle", "taskContextPlan",
+    "routingIndex", "stageReceipt", "stageContextBundle", "integrationReviewBundle", "hostPromotionEvidence",
+    "truthReconciliationInput", "truthReconciliationReviewBundle",
+  ]), "protocols");
+  for (const name of Object.keys(manifest.protocols)) versionMatrix(manifest.protocols[name], `protocols.${name}`);
+  if (!Array.isArray(manifest.builtInMigrations)) invalid("builtInMigrations must be an array");
+  manifest.builtInMigrations.forEach(validateMigration);
+  const migrationIds = manifest.builtInMigrations.map((entry) => entry.id);
+  sortedUnique(migrationIds, "builtInMigrations ids");
+  const runtimeMigrationIds = Object.keys(BUILT_IN_MIGRATIONS).sort((left, right) => left.localeCompare(right));
+  if (migrationIds.length !== runtimeMigrationIds.length || migrationIds.some((id, index) => id !== runtimeMigrationIds[index])) {
+    invalid("builtInMigrations must exactly match the runtime migration registry");
+  }
+  if (!Array.isArray(manifest.paths) || manifest.paths.length !== manifest.upgradeFrom.length) invalid("paths must contain one path for every upgradeFrom version");
+  manifest.paths.forEach((entry, index) => {
+    const label = `paths[${index}]`;
+    exactKeys(entry, new Set(["fromVersion", "classification", "migrationIds", "requiresHumanReview", "rollbackClass", "acceptance"]), label);
+    if (entry.fromVersion !== manifest.upgradeFrom[index]) invalid("paths must be ordered exactly like upgradeFrom");
+    if (!VERSION.test(entry.fromVersion)) invalid(`${label}.fromVersion must be exact`);
+    if (!MIGRATION_KINDS.has(entry.classification)) invalid(`${label}.classification is invalid`);
+    sortedUnique(entry.migrationIds, `${label}.migrationIds`);
+    for (const id of entry.migrationIds) if (!migrationIds.includes(id)) invalid(`${label} references unknown migration: ${id}`);
+    boolean(entry.requiresHumanReview, `${label}.requiresHumanReview`);
+    if (!ROLLBACK_CLASSES.has(entry.rollbackClass)) invalid(`${label}.rollbackClass is invalid`);
+    sortedUnique(entry.acceptance, `${label}.acceptance`);
+  });
+  exactKeys(manifest.consumerChanges, CONSUMER_CHANGE_KEYS, "consumerChanges");
+  for (const [name, change] of Object.entries(manifest.consumerChanges)) {
+    exactKeys(change, new Set(["state", "reason"]), `consumerChanges.${name}`);
+    if (!["preserve", "regenerate", "invalidate"].includes(change.state)) invalid(`consumerChanges.${name}.state is invalid`);
+    string(change.reason, `consumerChanges.${name}.reason`);
+  }
+  sortedUnique(manifest.acceptanceCommands, "acceptanceCommands");
+  exactKeys(manifest.rollback, new Set(["defaultClass", "externalRestoreRequired", "automatic"]), "rollback");
+  if (!ROLLBACK_CLASSES.has(manifest.rollback.defaultClass)) invalid("rollback.defaultClass is invalid");
+  boolean(manifest.rollback.externalRestoreRequired, "rollback.externalRestoreRequired");
+  if (manifest.rollback.automatic !== false) invalid("rollback.automatic must be false");
+  exactKeys(manifest.externalEffects, new Set(["packageManager", "network", "git", "projectTests", "businessCode", "automaticUpgrade"]), "externalEffects");
+  for (const [name, value] of Object.entries(manifest.externalEffects)) if (value !== false) invalid(`externalEffects.${name} must be false`);
+  if (!SHA256.test(manifest.manifestDigest)) invalid("manifestDigest must be sha256");
+  const unsigned = Object.fromEntries(Object.entries(manifest).filter(([key]) => key !== "manifestDigest"));
+  if (digestJson(unsigned) !== manifest.manifestDigest) invalid("manifestDigest does not match manifest bytes");
+  return manifest;
+}
+
+export async function loadMigrationManifest(dependencies = {}) {
+  const read = dependencies.readFile ?? readFile;
+  let parsed;
+  try {
+    parsed = JSON.parse(await read(MANIFEST_FILE, "utf8"));
+  } catch (error) {
+    invalid("cannot read the package migration manifest", { reason: error.message });
+  }
+  return validateMigrationManifest(parsed);
+}

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

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

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

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