frontend-project-context 1.3.0 → 1.6.0

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

@@ -0,0 +1,209 @@
+import { canonicalJson, canonicalValue, digestJson, validateJsonValue } from "./canonical-json.mjs";
+import { fail } from "./errors.mjs";
+
+export const EVIDENCE_INPUT_SCHEMA_VERSION = 1;
+export const EVIDENCE_BUNDLE_SCHEMA_VERSION = 1;
+export const EVIDENCE_INPUT_MAX_UTF8_BYTES = 32 * 1024;
+export const EVIDENCE_OUTPUT_MAX_UTF8_BYTES = 48 * 1024;
+
+const ID = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/u;
+const SHA256 = /^sha256:[a-f0-9]{64}$/u;
+const FIELD_PATH = /^[a-z][A-Za-z0-9]*(?:\.[a-z][A-Za-z0-9]*)*$/u;
+const CAPABILITIES = new Set(["setup", "takeover", "maintenance", "staged-context", "upgrade", "other-protocol"]);
+const RESULTS = new Set(["passed", "degraded", "blocked", "failed"]);
+const RUNTIMES = new Set(["node", "other", "redacted"]);
+const PACKAGE_MANAGERS = new Set(["npm", "pnpm", "yarn", "bun", "other", "redacted"]);
+const PROJECT_SHAPES = new Set(["single", "monorepo", "multi-context", "redacted"]);
+const OPERATIONS = new Set([
+  "capabilities", "status", "setup-preview", "sync", "check", "context", "preflight", "stage-context",
+  "integration-review", "publish-entry-preview", "remove-entry-preview", "upgrade-baseline", "other-protocol",
+]);
+const REDACTION_METHODS = new Set(["removed", "generalized", "hashed", "redacted", "not-collected"]);
+const STRUCTURALLY_FORBIDDEN_FIELDS = new Set([
+  "approval", "approve", "authorization", "base64", "body", "branch", "branchName", "businessCode", "chat", "codeBody",
+  "cookie", "credential", "credentials", "cwd", "decision", "destination", "diff", "environmentVariables", "externalId", "fileName", "filename",
+  "generatedAt", "hostName", "hostname", "itemIds", "items", "locator", "log", "logs", "name", "output", "path",
+  "paths", "priority", "projectId", "projectName", "release", "repository", "repositoryUrl", "reviewer", "sourceBody",
+  "password", "secret", "sourceIds", "sources", "targetVersion", "timestamp", "token", "upload", "url", "userName", "username", "value",
+]);
+
+function invalid(message, details) {
+  fail("evidence-input-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 (STRUCTURALLY_FORBIDDEN_FIELDS.has(key)) {
+      fail("evidence-redaction-blocked", `${label} contains a structurally forbidden field: ${key}`, { details: { field: key } });
+    }
+    if (!allowed.has(key)) invalid(`${label} contains unknown field: ${key}`);
+  }
+}
+
+function requiredKeys(value, required, label) {
+  for (const key of required) if (!Object.hasOwn(value, key)) invalid(`${label}.${key} is required`);
+}
+
+function string(value, label) {
+  if (typeof value !== "string" || 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 summary(value, label) {
+  string(value, label);
+  if (/\r|\n|\u2028|\u2029/u.test(value)) invalid(`${label} must be a single line`);
+  if (Buffer.byteLength(value, "utf8") > 500) invalid(`${label} exceeds 500 UTF-8 bytes`);
+  return value;
+}
+
+function enumValue(value, allowed, label) {
+  if (!allowed.has(value)) invalid(`${label} is invalid`);
+  return value;
+}
+
+function array(value, label, max) {
+  if (!Array.isArray(value)) invalid(`${label} must be an array`);
+  if (value.length > max) invalid(`${label} exceeds ${max} entries`);
+}
+
+function uniqueSorted(values, identity = (value) => canonicalJson(value)) {
+  return [...new Map(values.map((value) => [identity(value), value])).values()]
+    .sort((left, right) => identity(left).localeCompare(identity(right)));
+}
+
+function normalizeCodes(value, label) {
+  array(value, label, 32);
+  const normalized = value.map((entry, index) => {
+    stableId(entry, `${label}[${index}]`);
+    return entry;
+  });
+  return uniqueSorted(normalized, (entry) => entry);
+}
+
+function normalizeEnvironment(value) {
+  object(value, "environment");
+  const keys = new Set(["runtime", "runtimeMajor", "packageManager", "projectShape"]);
+  exactKeys(value, keys, "environment");
+  requiredKeys(value, keys, "environment");
+  if (!Number.isInteger(value.runtimeMajor) || value.runtimeMajor < 0 || value.runtimeMajor > 999) {
+    invalid("environment.runtimeMajor must be an integer from 0 through 999");
+  }
+  return {
+    runtime: enumValue(value.runtime, RUNTIMES, "environment.runtime"),
+    runtimeMajor: value.runtimeMajor,
+    packageManager: enumValue(value.packageManager, PACKAGE_MANAGERS, "environment.packageManager"),
+    projectShape: enumValue(value.projectShape, PROJECT_SHAPES, "environment.projectShape"),
+  };
+}
+
+function normalizeObservation(value, label) {
+  object(value, label);
+  const keys = new Set(["code", "summary"]);
+  exactKeys(value, keys, label);
+  requiredKeys(value, keys, label);
+  stableId(value.code, `${label}.code`);
+  return { code: value.code, summary: summary(value.summary, `${label}.summary`) };
+}
+
+function normalizeReproduction(value) {
+  array(value, "reproduction", 20);
+  return value.map((entry, index) => {
+    const label = `reproduction[${index}]`;
+    object(entry, label);
+    const keys = new Set(["operation", "outcome", "findingCodes"]);
+    exactKeys(entry, keys, label);
+    requiredKeys(entry, keys, label);
+    return {
+      operation: enumValue(entry.operation, OPERATIONS, `${label}.operation`),
+      outcome: enumValue(entry.outcome, RESULTS, `${label}.outcome`),
+      findingCodes: normalizeCodes(entry.findingCodes, `${label}.findingCodes`),
+    };
+  });
+}
+
+function normalizeArtifacts(value) {
+  array(value, "artifacts", 32);
+  const normalized = value.map((entry, index) => {
+    const label = `artifacts[${index}]`;
+    object(entry, label);
+    const keys = new Set(["kind", "digest"]);
+    exactKeys(entry, keys, label);
+    requiredKeys(entry, keys, label);
+    stableId(entry.kind, `${label}.kind`);
+    if (typeof entry.digest !== "string" || !SHA256.test(entry.digest)) invalid(`${label}.digest must be sha256`);
+    return { kind: entry.kind, digest: entry.digest };
+  });
+  return uniqueSorted(normalized);
+}
+
+function normalizeRedactions(value) {
+  array(value, "redactions", 32);
+  const normalized = value.map((entry, index) => {
+    const label = `redactions[${index}]`;
+    object(entry, label);
+    const keys = new Set(["field", "method"]);
+    exactKeys(entry, keys, label);
+    requiredKeys(entry, keys, label);
+    string(entry.field, `${label}.field`);
+    if (!FIELD_PATH.test(entry.field)) invalid(`${label}.field must be a dotted input field path`);
+    return { field: entry.field, method: enumValue(entry.method, REDACTION_METHODS, `${label}.method`) };
+  });
+  return uniqueSorted(normalized);
+}
+
+export function normalizeEvidenceInput(input) {
+  try {
+    validateJsonValue(input);
+  } catch (error) {
+    invalid("evidence input must be JSON-compatible", { reason: error.message });
+  }
+  object(input, "evidence input");
+  const keys = new Set([
+    "schemaVersion", "capability", "result", "environment", "expected", "observed", "errorCodes",
+    "reproduction", "artifacts", "redactions",
+  ]);
+  exactKeys(input, keys, "evidence input");
+  requiredKeys(input, keys, "evidence input");
+  if (input.schemaVersion !== EVIDENCE_INPUT_SCHEMA_VERSION) invalid("evidence input schemaVersion must be 1");
+  const normalized = {
+    schemaVersion: EVIDENCE_INPUT_SCHEMA_VERSION,
+    capability: enumValue(input.capability, CAPABILITIES, "capability"),
+    result: enumValue(input.result, RESULTS, "result"),
+    environment: normalizeEnvironment(input.environment),
+    expected: normalizeObservation(input.expected, "expected"),
+    observed: normalizeObservation(input.observed, "observed"),
+    errorCodes: normalizeCodes(input.errorCodes, "errorCodes"),
+    reproduction: normalizeReproduction(input.reproduction),
+    artifacts: normalizeArtifacts(input.artifacts),
+    redactions: normalizeRedactions(input.redactions),
+  };
+  if (Buffer.byteLength(canonicalJson(normalized), "utf8") > EVIDENCE_INPUT_MAX_UTF8_BYTES) {
+    fail("evidence-input-budget-exceeded", `canonical evidence input exceeds ${EVIDENCE_INPUT_MAX_UTF8_BYTES} UTF-8 bytes`);
+  }
+  return canonicalValue(normalized);
+}
+
+export function finalizeEvidenceBundle(bundleWithoutDigest) {
+  const canonical = canonicalValue(bundleWithoutDigest);
+  const bundle = canonicalValue({ ...canonical, bundleDigest: digestJson(canonical) });
+  if (Buffer.byteLength(canonicalJson(bundle), "utf8") > EVIDENCE_OUTPUT_MAX_UTF8_BYTES) {
+    fail("evidence-output-budget-exceeded", `canonical evidence output exceeds ${EVIDENCE_OUTPUT_MAX_UTF8_BYTES} UTF-8 bytes`);
+  }
+  return bundle;
+}
+
+export function verifyEvidenceBundleDigest(bundle) {
+  object(bundle, "evidence bundle");
+  const copy = structuredClone(bundle);
+  const actual = copy.bundleDigest;
+  delete copy.bundleDigest;
+  return typeof actual === "string" && actual === digestJson(canonicalValue(copy));
+}

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,30 @@ import { canonicalValue, digestJson, validateJsonValue } from "./canonical-json.
 import { fail } from "./errors.mjs";
 import { normalizeRelativePath } from "./path-policy.mjs";
 
-export const PACKAGE_VERSION = "1.3.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 PACKAGE_VERSION = "1.6.0";
+export const EXCHANGE_PROTOCOL_VERSION = 4;
+export const ACTION_PLAN_SCHEMA_VERSION = 2;
+export const REVIEW_BUNDLE_SCHEMA_VERSION = 2;
+export const CAPABILITIES_SCHEMA_VERSION = 4;
 
 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",
+  "deprecate-source", "discover", "evidence", "init", "integration-review", "preflight", "propose", "publish", "register",
+  "publish-entry", "remove-entry", "review-source", "revise", "setup", "stage-context", "status", "sync",
+  "upgrade-apply", "upgrade-check", "upgrade-plan",
 ]);
 
 const ACTION_KIND_SET = new Set(ACTION_KINDS);
@@ -253,13 +256,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 +283,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 +506,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,10 +72,10 @@ 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 };
 }
 

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

@@ -0,0 +1,166 @@
+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", "capabilities", "evidenceBundle", "evidenceInput", "exchange",
+  "integrationReviewBundle", "reviewBundle", "stageContextBundle", "stageReceipt", "taskContextPlan",
+]);
+
+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.6.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", "reviewBundle", "evidenceInput", "evidenceBundle", "taskContextPlan",
+    "stageReceipt", "stageContextBundle", "integrationReviewBundle",
+  ]), "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);
+}