archctx-contracts 0.6.2 → 0.7.0

package/src/projection.ts

@@ -11,7 +11,7 @@ export const PROJECTION_APPLY_RECOVERY_RESULT_SCHEMA_VERSION = "archcontext.proj
 export const PROJECTION_APPLY_READBACK_RESULT_SCHEMA_VERSION = "archcontext.projection-apply-readback-result/v1" as const;
 export const ARCHITECTURE_REFRESH_SIGNAL_SCHEMA_VERSION = "archcontext.architecture-refresh-signal/v1" as const;
 export const ARCHCTX_CAPABILITIES_SCHEMA_VERSION = "archcontext.capabilities/v1" as const;
-export const ARCHITECTURE_DOCS_RENDERER_VERSION = "archcontext.docs-renderer/v4" as const;
+export const ARCHITECTURE_DOCS_RENDERER_VERSION = "archcontext.docs-renderer/v5" as const;
 export const AGENT_CONTEXT_RENDERER_VERSION = "archcontext.agent-context-renderer/v1" as const;
 
 export const PROJECTION_MODES = ["check", "plan", "apply", "adopt"] as const;
@@ -31,6 +31,7 @@ export const PROJECTION_RESULT_STATUSES = [
 export const PROJECTION_HUMAN_ACTION_REASON_CODES = [
   "adoption-required",
   "manual-region-conflict",
+  "orphaned-document-review",
   "target-collision",
   "unprovable-required-flow",
   "unresolved-major-change"
@@ -58,20 +59,73 @@ export const ARCHITECTURE_REFRESH_TARGETS = [
   "capability-index"
 ] as const;
 export const ARCHCTX_FEATURES = [
+  "architecture-change-capabilities-v1",
   "architecture-docs-renderer-v2",
   "architecture-refresh-signal-v1",
+  "changeset-entity-operations-v1",
+  "code-facts-unavailable-error-v1",
   "module-statistics-v1",
   "projection-apply-readback-v1",
   "projection-apply-receipt-v1",
   "projection-apply-recovery-v1",
+  "projection-apply-replay-v1",
+  "projection-check-freshness-v1",
+  "projection-manifest-contract-v2",
+  "projection-observed-major-change-acceptance-v1",
+  "projection-orphan-review-v1",
+  "projection-preview-v1",
   "projection-prior-committed-applies-v1",
   "projection-protocol-v2",
+  "recommendation-scan-decision-v1",
   "recommendation-v3",
   "refactor-assessment-v1",
-  "refactor-resolution-v1"
+  "refactor-observation-evidence-v1",
+  "refactor-resolution-v1",
+  "refactor-scan-limits-v1"
+] as const;
+
+/**
+ * The closed set of semantic facets a capability's semantic state digests. Each facet maps to the
+ * major-change reason code it raises when its digest moves.
+ */
+export const ARCHITECTURE_SEMANTIC_FACETS = [
+  "constraints",
+  "entrypoints",
+  "interfaces",
+  "lifecycle",
+  "names",
+  "ownership",
+  "placement",
+  "relations",
+  "responsibilities",
+  "riskBoundaries"
+] as const;
+export const ARCHITECTURE_PROOF_P1_STATUSES = ["proven", "unprovable"] as const;
+export const ARCHITECTURE_PROOF_P2_STATUSES = ["not-applicable", "proven", "unprovable"] as const;
+
+/** `files[].preview.format`: a `create` carries the rendered body, an `update` or `delete` a unified diff. */
+export const PROJECTION_FILE_PREVIEW_FORMATS = ["body", "unified-diff"] as const;
+/** Upper bound, in UTF-8 bytes, on one `files[].preview.content`. */
+export const PROJECTION_FILE_PREVIEW_MAX_BYTES = 65_536;
+/** Upper bound, in UTF-8 bytes, on the sum of every `files[].preview.content` of one result. */
+export const PROJECTION_PREVIEW_TOTAL_MAX_BYTES = 1_048_576;
+
+/**
+ * Why a projection is not fresh. Shared by the core freshness evaluator and the `check` result's
+ * `freshness` field so the two can never disagree.
+ */
+export const PROJECTION_FRESHNESS_REASON_CODES = [
+  "projection-manifest-missing",
+  "projection-manifest-unreadable",
+  "projection-snapshot-provenance-missing",
+  "projection-source-changed-since-stamp",
+  "projection-source-stamp-invalid",
+  "projection-source-stamp-missing",
+  "projection-source-tree-digest-mismatch"
 ] as const;
 
 export type ProjectionMode = (typeof PROJECTION_MODES)[number];
+export type ProjectionFreshnessReasonCode = (typeof PROJECTION_FRESHNESS_REASON_CODES)[number];
 export type ProjectionTarget = (typeof PROJECTION_TARGETS)[number];
 export type ProjectionResultStatus = (typeof PROJECTION_RESULT_STATUSES)[number];
 export type ProjectionHumanActionReasonCode = (typeof PROJECTION_HUMAN_ACTION_REASON_CODES)[number];
@@ -79,8 +133,47 @@ export type ProjectionPriorCommittedApplyOperation = (typeof PROJECTION_PRIOR_CO
 export type ArchitectureMajorChangeReasonCode = (typeof ARCHITECTURE_MAJOR_CHANGE_REASON_CODES)[number];
 export type ArchitectureRefreshTarget = (typeof ARCHITECTURE_REFRESH_TARGETS)[number];
 export type ArchctxFeature = (typeof ARCHCTX_FEATURES)[number];
+export type ArchitectureSemanticFacet = (typeof ARCHITECTURE_SEMANTIC_FACETS)[number];
+export type ProjectionFilePreviewFormat = (typeof PROJECTION_FILE_PREVIEW_FORMATS)[number];
 export type Sha256Digest = `sha256:${string}`;
 
+/** One capability's P1/P2 proof status, as its semantic state records it. */
+export interface ArchitectureCapabilityProofStatusV1 {
+  p1: (typeof ARCHITECTURE_PROOF_P1_STATUSES)[number];
+  p2: (typeof ARCHITECTURE_PROOF_P2_STATUSES)[number];
+}
+
+/**
+ * Why one capability is part of a major change: the reason codes and semantic facets that moved for
+ * it between the committed semantic baseline and this run. `proofStatusBefore` is null when the
+ * baseline has no such capability (or no baseline exists); `proofStatusAfter` is null when the
+ * capability was removed. A capability present on one side only lists no changed facets. A
+ * capability listed only because its current proof is unprovable, while another capability carries
+ * the observed change, lists no reason codes.
+ */
+export interface ArchitectureCapabilityChangeV1 {
+  capabilityId: string;
+  reasonCodes: ArchitectureMajorChangeReasonCode[];
+  changedFacets: ArchitectureSemanticFacet[];
+  proofStatusBefore: ArchitectureCapabilityProofStatusV1 | null;
+  proofStatusAfter: ArchitectureCapabilityProofStatusV1 | null;
+}
+
+/**
+ * What a `plan` would write to one file, returned in the response only and never persisted: the
+ * rendered body of a `create`, or a unified diff (current bytes to rendered bytes) of an `update` or
+ * `delete`. `content` is cut at a line boundary to at most PROJECTION_FILE_PREVIEW_MAX_BYTES UTF-8
+ * bytes, and to whatever remains of PROJECTION_PREVIEW_TOTAL_MAX_BYTES across the result, in path
+ * order; `byteLength` is the UTF-8 length of the complete content and `truncated` says whether
+ * `content` is shorter.
+ */
+export interface ProjectionFilePreviewV1 {
+  format: ProjectionFilePreviewFormat;
+  content: string;
+  byteLength: number;
+  truncated: boolean;
+}
+
 export interface ProjectionExpectedSnapshotV1 {
   repositoryId: string;
   workspaceId: string;
@@ -98,6 +191,14 @@ export interface ProjectionRequestV1 {
   expected: ProjectionExpectedSnapshotV1;
   adoptionPlanId?: string;
   acceptedChange?: AcceptedArchitectureChangeReferenceV1;
+  /**
+   * `apply` and `adopt` only, never together with `acceptedChange`: accept the major change this
+   * run observes at `expected`. The provider classifies, derives the accepted change and applies
+   * it against the same expected snapshot, which the daemon re-checks under its writer lock before
+   * writing. The apply receipt records the observed change with provider-generated `changeSetId`
+   * and `eventId`. Absent, a major change still stops at `human-action-required` (#261).
+   */
+  acceptObservedMajorChange?: true;
 }
 
 export interface ProjectionSnapshotV1 extends ProjectionExpectedSnapshotV1 {
@@ -112,7 +213,6 @@ export interface ProjectionSnapshotV1 extends ProjectionExpectedSnapshotV1 {
   generatedFrom: {
     codeGraphPackage: "@colbymchenry/codegraph";
     codeGraphVersion: "1.6.1";
-    codeGraphBinaryDigest: Sha256Digest;
     codeGraphStatus: "ready" | "unavailable";
   };
 }
@@ -122,11 +222,23 @@ export interface ProjectionFileResultV1 {
   action: "create" | "delete" | "unchanged" | "update";
   preimageDigest: Sha256Digest | null;
   outputDigest: Sha256Digest | null;
+  /**
+   * `plan` results only (#264): what this entry would write. Absent on every other mode, on a
+   * committed receipt, and on an entry whose path the projection rejected for adoption or ownership
+   * repair, because no apply writes that rendered body. Consumers gate on `projection-preview-v1`.
+   */
+  preview?: ProjectionFilePreviewV1;
 }
 
 export interface ProjectionHumanActionV1 {
   reasonCode: ProjectionHumanActionReasonCode;
   affectedNodeIds: string[];
+  /**
+   * Present exactly on `orphaned-document-review`: the managed document whose target the model no
+   * longer renders and which may hold human text. `apply` never deletes it; a human must review,
+   * move or remove it. A generated-only orphan is a `files[]` delete instead.
+   */
+  path?: string;
   requestPayloadDigest: Sha256Digest;
 }
 
@@ -170,6 +282,13 @@ export interface ArchitectureRefreshSignalV1 {
   acceptedChange?: AcceptedArchitectureChangeReferenceV1;
   reasonCodes: ArchitectureMajorChangeReasonCode[];
   affectedNodeIds: string[];
+  /**
+   * The observed per-capability breakdown of the semantic delta this signal classifies, sorted by
+   * capabilityId (#264). Every signal this provider produces carries it; it is part of the signal
+   * identity; signals committed before it existed lack it. Consumers gate on
+   * `architecture-change-capabilities-v1`, not on field presence.
+   */
+  capabilities?: ArchitectureCapabilityChangeV1[];
   refreshTargets: ArchitectureRefreshTarget[];
   baseDigests: ArchitectureDigestSetV1;
   resultingDigests: ArchitectureDigestSetV1;
@@ -203,6 +322,21 @@ export interface ProjectionPriorCommittedApplyV1 {
   files: ProjectionPriorCommittedApplyFileV1[];
 }
 
+export interface ProjectionFreshnessStaleNodeV1 {
+  nodeId: string;
+  /** Source-footprint digest the node's projected document is stamped with. */
+  stampedDigest: Sha256Digest;
+  /** Source-footprint digest measured by this run. */
+  currentDigest: Sha256Digest;
+}
+
+/** Read-only per-node freshness of the committed projection, as `check` measured it. */
+export interface ProjectionFreshnessV1 {
+  ok: boolean;
+  reasonCodes: ProjectionFreshnessReasonCode[];
+  staleNodes: ProjectionFreshnessStaleNodeV1[];
+}
+
 export interface ProjectionResultV2 {
   schemaVersion: typeof PROJECTION_RESULT_SCHEMA_VERSION;
   requestId: string;
@@ -214,8 +348,31 @@ export interface ProjectionResultV2 {
   humanActions: ProjectionHumanActionV1[];
   refreshSignals: ArchitectureRefreshSignalV1[];
   applyReceipt?: ProjectionApplyIdentityV1;
-  /** Omitted, never `[]`, when no earlier attempt of this requestId committed. */
+  /**
+   * Omitted, never `[]`, when no earlier attempt of this requestId committed. Never present on
+   * `check` results: a check runs in-process without the daemon journal, so read committed applies
+   * through `apply` or `readback`.
+   */
   priorCommittedApplies?: ProjectionPriorCommittedApplyV1[];
+  /**
+   * Present on `check` results only: which nodes changed since their documents were verified.
+   * Consumers gate on the `projection-check-freshness-v1` capability, not on field presence.
+   */
+  freshness?: ProjectionFreshnessV1;
+  /**
+   * Present, as `true`, only when this response returns an apply this requestId already committed
+   * for the same request digest, without applying again (#265). It is excluded from
+   * `receiptDigest`, so a replay carries the committed receipt digest unchanged.
+   */
+  replayed?: true;
+  /**
+   * Present only on a `human-action-required` result whose request sent `acceptObservedMajorChange`
+   * and the provider declined it: `declined-unprovable-proof` means a capability's P1 or P2 proof is
+   * unprovable, so no observed change can be accepted. The result then carries an
+   * `unprovable-required-flow` action naming those capabilities, never `unresolved-major-change`,
+   * so a caller can tell a declined flag from an absent one (#275).
+   */
+  majorChangeAcceptance?: "declined-unprovable-proof";
   receiptDigest: Sha256Digest;
 }
 
@@ -243,6 +400,12 @@ export interface ProjectionApplyRecoveryBindingV1 {
   generatedFrom: ProjectionSnapshotV1["generatedFrom"];
   ownedOutputDigest: Sha256Digest;
   receiptDigest: Sha256Digest;
+  /**
+   * `digestJson` of the caller's ProjectionRequestV1 exactly as received. With the result's
+   * requestId it is the replay key of #265; it never includes provider-generated ids. Receipts
+   * committed before it existed lack it and are never replayed.
+   */
+  requestDigest?: Sha256Digest;
 }
 
 /**
@@ -365,6 +528,11 @@ export function projectionRequestInvariantIssues(input: ProjectionRequestV1): st
   if (!/^[a-zA-Z0-9_.:-]+$/.test(input.requestId)) issues.push("requestId must use the stable identifier character set");
   if (input.mode === "adopt" && !input.adoptionPlanId) issues.push("adoptionPlanId is required when mode=adopt");
   if (input.mode !== "adopt" && input.adoptionPlanId !== undefined) issues.push("adoptionPlanId is only allowed when mode=adopt");
+  if (input.acceptObservedMajorChange !== undefined) {
+    if (input.acceptObservedMajorChange !== true) issues.push("acceptObservedMajorChange must be true when present");
+    if (input.mode !== "apply" && input.mode !== "adopt") issues.push("acceptObservedMajorChange is only allowed when mode=apply or mode=adopt");
+    if (input.acceptedChange !== undefined) issues.push("acceptObservedMajorChange and acceptedChange are mutually exclusive");
+  }
   if (input.acceptedChange) {
     if (input.acceptedChange.changeSetId.trim() === "") issues.push("acceptedChange.changeSetId must not be empty");
     if (input.acceptedChange.eventId.trim() === "") issues.push("acceptedChange.eventId must not be empty");
@@ -381,6 +549,17 @@ export function projectionRequestInvariantIssues(input: ProjectionRequestV1): st
   return issues;
 }
 
+/**
+ * Invariants that bind a result to the request mode that produced it, which the result itself does
+ * not carry: only a `plan` result previews what it would write (#264); `check`, `apply` and
+ * `adopt` results never carry `files[].preview`, whatever their status.
+ */
+export function projectionResultRequestModeIssues(input: ProjectionResultV2, mode: ProjectionMode): string[] {
+  return mode !== "plan" && input.files.some((file) => file.preview !== undefined)
+    ? [`files[].preview is only allowed on a plan result, never when mode=${mode}`]
+    : [];
+}
+
 export function projectionResultInvariantIssues(input: ProjectionResultV2): string[] {
   const issues = [
     ...sortedUniqueIssues("affectedNodeIds", input.affectedNodeIds),
@@ -400,6 +579,19 @@ export function projectionResultInvariantIssues(input: ProjectionResultV2): stri
     if (!input.applyReceipt) issues.push("applied-reconcile-required status requires applyReceipt");
     if (input.refreshSignals.length > 0) issues.push("applied-reconcile-required status cannot deliver refreshSignals");
   }
+  for (const [index, action] of input.humanActions.entries()) {
+    const prefix = `humanActions[${index}]`;
+    if (!(PROJECTION_HUMAN_ACTION_REASON_CODES as readonly string[]).includes(action.reasonCode)) issues.push(`${prefix}.reasonCode is unsupported`);
+    if ((action.reasonCode === "orphaned-document-review") !== (action.path !== undefined)) {
+      issues.push(`${prefix}.path must be present exactly when reasonCode=orphaned-document-review`);
+    }
+    if (action.path !== undefined && !isRepoRelativePosixPath(action.path)) issues.push(`${prefix}.path must be a repository-relative POSIX path`);
+  }
+  const orphanReviewPaths = input.humanActions.flatMap((action) => action.reasonCode === "orphaned-document-review" && action.path !== undefined ? [action.path] : []);
+  issues.push(...sortedUniqueIssues("humanActions[orphaned-document-review].path", orphanReviewPaths));
+  if (orphanReviewPaths.some((path) => input.files.some((file) => file.path === path))) {
+    issues.push("an orphaned-document-review path must not also be a files[] entry");
+  }
   for (const [index, file] of input.files.entries()) {
     const prefix = `files[${index}]`;
     if (file.action === "create" && (file.preimageDigest !== null || file.outputDigest === null)) {
@@ -414,10 +606,36 @@ export function projectionResultInvariantIssues(input: ProjectionResultV2): stri
     if (file.action === "unchanged" && (file.preimageDigest === null || file.outputDigest === null || file.preimageDigest !== file.outputDigest)) {
       issues.push(`${prefix} unchanged requires equal non-null digests`);
     }
+    if (file.preview !== undefined) issues.push(...projectionFilePreviewIssues(file, prefix));
+  }
+  const previewBytes = input.files.reduce((total, file) => total + (file.preview ? utf8ByteLength(file.preview.content) : 0), 0);
+  if (previewBytes > PROJECTION_PREVIEW_TOTAL_MAX_BYTES) {
+    issues.push(`files[].preview.content must not exceed ${PROJECTION_PREVIEW_TOTAL_MAX_BYTES} UTF-8 bytes in total`);
+  }
+  // The result does not carry its request mode; projectionResultRequestModeIssues binds a preview
+  // to mode=plan. On the result alone, a committed apply (and so a persisted receipt) never carries one.
+  if (input.files.some((file) => file.preview !== undefined)
+    && (input.applyReceipt !== undefined || input.status === "applied" || input.status === "applied-reconcile-required")) {
+    issues.push("files[].preview is only allowed on a plan result, never on a committed apply");
   }
   if (input.priorCommittedApplies) {
     issues.push(...projectionPriorCommittedAppliesIssues(input.priorCommittedApplies, input.requestId));
   }
+  if (input.freshness) issues.push(...projectionFreshnessIssues(input.freshness));
+  if (input.majorChangeAcceptance !== undefined) {
+    if (input.majorChangeAcceptance !== "declined-unprovable-proof") issues.push("majorChangeAcceptance is unsupported");
+    if (input.status !== "human-action-required"
+      || !input.humanActions.some((action) => action.reasonCode === "unprovable-required-flow")
+      || input.humanActions.some((action) => action.reasonCode === "unresolved-major-change")) {
+      issues.push("majorChangeAcceptance requires human-action-required with unprovable-required-flow in place of unresolved-major-change");
+    }
+  }
+  if (input.replayed !== undefined) {
+    if (input.replayed !== true) issues.push("replayed must be true when present");
+    if (!input.applyReceipt || (input.status !== "applied" && input.status !== "applied-reconcile-required")) {
+      issues.push("replayed is only allowed on a committed apply result with applyReceipt");
+    }
+  }
   const { receiptDigest, ...receiptPayload } = input;
   if (projectionResultReceiptDigest(receiptPayload) !== receiptDigest) issues.push("receiptDigest must match the canonical projection result payload");
   for (const [index, signal] of input.refreshSignals.entries()) {
@@ -431,6 +649,53 @@ export function projectionResultInvariantIssues(input: ProjectionResultV2): stri
   return issues;
 }
 
+function projectionFilePreviewIssues(file: ProjectionFileResultV1, prefix: string): string[] {
+  const preview = file.preview!;
+  const issues: string[] = [];
+  const expectedFormat: ProjectionFilePreviewFormat | undefined = file.action === "create"
+    ? "body"
+    : file.action === "update" || file.action === "delete" ? "unified-diff" : undefined;
+  if (expectedFormat === undefined) issues.push(`${prefix}.preview is not allowed when action=${file.action}`);
+  else if (preview.format !== expectedFormat) issues.push(`${prefix}.preview.format must be ${expectedFormat} when action=${file.action}`);
+  if (typeof preview.content !== "string" || typeof preview.truncated !== "boolean"
+    || !Number.isSafeInteger(preview.byteLength) || preview.byteLength < 0) {
+    issues.push(`${prefix}.preview must carry string content, a boolean truncated flag and a non-negative integer byteLength`);
+    return issues;
+  }
+  const contentBytes = utf8ByteLength(preview.content);
+  if (contentBytes > PROJECTION_FILE_PREVIEW_MAX_BYTES) issues.push(`${prefix}.preview.content must not exceed ${PROJECTION_FILE_PREVIEW_MAX_BYTES} UTF-8 bytes`);
+  if (preview.truncated ? contentBytes >= preview.byteLength : contentBytes !== preview.byteLength) {
+    issues.push(`${prefix}.preview.truncated must be true exactly when content is shorter than byteLength`);
+  }
+  return issues;
+}
+
+const UTF8 = new TextEncoder();
+
+function utf8ByteLength(value: string): number {
+  return UTF8.encode(value).length;
+}
+
+export function projectionFreshnessIssues(input: ProjectionFreshnessV1): string[] {
+  const issues = [
+    ...sortedUniqueIssues("freshness.reasonCodes", input.reasonCodes),
+    ...sortedUniqueIssues("freshness.staleNodes.nodeId", input.staleNodes.map((node) => node.nodeId))
+  ];
+  const unsupported = input.reasonCodes.find((code) => !(PROJECTION_FRESHNESS_REASON_CODES as readonly string[]).includes(code));
+  if (unsupported) issues.push(`freshness.reasonCodes contains an unsupported code: ${unsupported}`);
+  if (input.ok !== (input.reasonCodes.length === 0)) issues.push("freshness.ok must be true exactly when reasonCodes is empty");
+  if ((input.staleNodes.length > 0) !== input.reasonCodes.includes("projection-source-changed-since-stamp")) {
+    issues.push("freshness.staleNodes must be non-empty exactly when projection-source-changed-since-stamp is reported");
+  }
+  for (const [index, node] of input.staleNodes.entries()) {
+    const prefix = `freshness.staleNodes[${index}]`;
+    if (node.nodeId.trim() === "") issues.push(`${prefix}.nodeId must not be empty`);
+    if (!SHA256_DIGEST.test(node.stampedDigest) || !SHA256_DIGEST.test(node.currentDigest)) issues.push(`${prefix} digests must be SHA-256 digests`);
+    else if (node.stampedDigest === node.currentDigest) issues.push(`${prefix} must name two different digests`);
+  }
+  return issues;
+}
+
 export function projectionPriorCommittedAppliesIssues(
   input: readonly ProjectionPriorCommittedApplyV1[],
   requestId: string
@@ -471,8 +736,9 @@ export function projectionPriorCommittedAppliesIssues(
  * projectionReceiptDigest, which projectionResultInvariantIssues verifies.
  */
 export function projectionResultReceiptDigest(input: Omit<ProjectionResultV2, "receiptDigest">): Sha256Digest {
-  const refreshSignals = input.refreshSignals.map(({ projectionReceiptDigest: _projectionReceiptDigest, ...signal }) => signal);
-  return digestJson({ ...input, refreshSignals } as unknown as Json) as Sha256Digest;
+  const { replayed: _replayed, ...payload } = input;
+  const refreshSignals = payload.refreshSignals.map(({ projectionReceiptDigest: _projectionReceiptDigest, ...signal }) => signal);
+  return digestJson({ ...payload, refreshSignals } as unknown as Json) as Sha256Digest;
 }
 
 export function projectionApplyLookupKey(input: {
@@ -551,6 +817,7 @@ export function projectionApplyRecoveryBindingInvariantIssues(
     issues.push("recovery schemaVersion is invalid");
   }
   if (binding.targets.length === 0) issues.push("recovery targets must contain at least one projection target");
+  if (binding.requestDigest !== undefined && !SHA256_DIGEST.test(binding.requestDigest)) issues.push("recovery requestDigest must be a SHA-256 digest");
   if (receipt) {
     if (binding.receiptDigest !== receipt.result.receiptDigest) {
       issues.push("recovery receiptDigest must match the committed result receiptDigest");
@@ -596,6 +863,33 @@ export function projectionApplyReadbackRequestInvariantIssues(request: Projectio
   return issues;
 }
 
+/**
+ * The readback request for a committed apply receipt, built only from what the receipt recorded:
+ * its requestId, the recovery binding's targets, changedPaths and original expected snapshot, and
+ * the identity's accepted change. Readback always takes `mode: "apply"`, also for an adopt receipt,
+ * because the binding never records the mode. A caller that held only `acceptObservedMajorChange`
+ * never had the accepted change, so `AC_PROJECTION_APPLY_COMMITTED` hands it this request (#278).
+ * Undefined for a receipt without a recovery binding, which readback cannot prove.
+ */
+export function projectionApplyReadbackRequestFromReceipt(receipt: ProjectionApplyReceiptV1): ProjectionRequestV1 | undefined {
+  const binding = receipt.recovery;
+  if (!binding) return undefined;
+  return {
+    schemaVersion: PROJECTION_REQUEST_SCHEMA_VERSION,
+    requestId: receipt.result.requestId,
+    profile: "repo-harness/v1",
+    mode: "apply",
+    targets: [...binding.targets],
+    changedPaths: [...binding.changedPaths],
+    expected: { ...binding.originalExpectedSnapshot },
+    acceptedChange: {
+      ...receipt.identity.acceptedChange,
+      reasonCodes: [...receipt.identity.acceptedChange.reasonCodes],
+      affectedNodeIds: [...receipt.identity.acceptedChange.affectedNodeIds]
+    }
+  };
+}
+
 export function projectionApplyAbsenceInvariantIssues(input: ProjectionApplyAbsenceV1, request: ProjectionRequestV1): string[] {
   const issues = projectionApplyReadbackRequestInvariantIssues(request);
   if (input.schemaVersion !== "archcontext.projection-apply-absence/v1") issues.push("absence schemaVersion is invalid");
@@ -773,6 +1067,7 @@ export function architectureRefreshSignalInvariantIssues(input: ArchitectureRefr
       issues.push(`${prefix}.acceptedChange.affectedNodeIds must match signal affectedNodeIds`);
     }
   }
+  if (input.capabilities !== undefined) issues.push(...architectureCapabilityChangesIssues(input.capabilities, `${prefix}.capabilities`));
   if (input.reasonCodes.length === 0) issues.push(`${prefix}.reasonCodes must contain at least one reason`);
   if (input.affectedNodeIds.length === 0) issues.push(`${prefix}.affectedNodeIds must contain at least one node`);
   if (input.refreshTargets.length === 0) issues.push(`${prefix}.refreshTargets must contain at least one target`);
@@ -791,6 +1086,43 @@ export function architectureRefreshSignalInvariantIssues(input: ArchitectureRefr
   return issues;
 }
 
+/** Shape and canonical order of a per-capability major-change breakdown (#264). */
+export function architectureCapabilityChangesIssues(input: readonly ArchitectureCapabilityChangeV1[], prefix = "capabilities"): string[] {
+  const issues = sortedUniqueIssues(`${prefix}.capabilityId`, input.map((entry) => entry.capabilityId));
+  if (input.length === 0) issues.push(`${prefix} must name at least one capability`);
+  const reasons = new Set<string>(ARCHITECTURE_MAJOR_CHANGE_REASON_CODES);
+  const facets = new Set<string>(ARCHITECTURE_SEMANTIC_FACETS);
+  for (const [index, entry] of input.entries()) {
+    const entryPrefix = `${prefix}[${index}]`;
+    if (typeof entry.capabilityId !== "string" || entry.capabilityId.trim() === "") issues.push(`${entryPrefix}.capabilityId must not be empty`);
+    issues.push(
+      ...sortedUniqueIssues(`${entryPrefix}.reasonCodes`, entry.reasonCodes),
+      ...sortedUniqueIssues(`${entryPrefix}.changedFacets`, entry.changedFacets)
+    );
+    const reason = entry.reasonCodes.find((code) => !reasons.has(code));
+    if (reason !== undefined) issues.push(`${entryPrefix}.reasonCodes contains unsupported reason: ${reason}`);
+    const facet = entry.changedFacets.find((name) => !facets.has(name));
+    if (facet !== undefined) issues.push(`${entryPrefix}.changedFacets contains unsupported facet: ${facet}`);
+    for (const field of ["proofStatusBefore", "proofStatusAfter"] as const) {
+      const status = entry[field];
+      if (status !== null && !isArchitectureCapabilityProofStatus(status)) issues.push(`${entryPrefix}.${field} must be null or a P1/P2 proof status`);
+    }
+    if (entry.proofStatusBefore === null && entry.proofStatusAfter === null) issues.push(`${entryPrefix} must exist before or after the change`);
+    if ((entry.proofStatusBefore === null || entry.proofStatusAfter === null) && entry.changedFacets.length > 0) {
+      issues.push(`${entryPrefix}.changedFacets must be empty for a capability present on one side only`);
+    }
+  }
+  return issues;
+}
+
+export function isArchitectureCapabilityProofStatus(value: unknown): value is ArchitectureCapabilityProofStatusV1 {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return Object.keys(record).length === 2
+    && (ARCHITECTURE_PROOF_P1_STATUSES as readonly unknown[]).includes(record.p1)
+    && (ARCHITECTURE_PROOF_P2_STATUSES as readonly unknown[]).includes(record.p2);
+}
+
 const SHA256_DIGEST = /^sha256:[a-f0-9]{64}$/;
 const ISO_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;