archctx-contracts 0.7.1 → 0.8.0

package/src/projection.ts

@@ -1,3 +1,4 @@
+import type { EvidenceCoverageLevelV2 } from "./ledger";
 import { digestJson, isRepoRelativePosixPath, type Json } from "./schema";
 
 export const PROJECTION_REQUEST_SCHEMA_VERSION = "archcontext.projection-request/v1" as const;
@@ -11,7 +12,12 @@ 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/v5" as const;
+export const ARCHITECTURE_DOCS_RENDERER_VERSION = "archcontext.docs-renderer/v6" as const;
+/**
+ * The committed projection manifest's path. `projection-manifest.ts` owns its shape and byte layout;
+ * the path lives here because a projection result's `files[]` names the manifest write.
+ */
+export const ARCHITECTURE_DOCS_PROJECTION_MANIFEST_PATH = "docs/architecture/.projection-manifest.json" 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;
@@ -20,14 +26,28 @@ export const PROJECTION_TARGETS = ["agent-context", "architecture-docs"] as cons
 export const PROJECTION_RESULT_STATUSES = [
   "adoption-required",
   "applied",
+  "applied-partial",
   "applied-reconcile-required",
   "blocked",
   "human-action-required",
   "noop",
   "permanent-failure",
   "planned",
+  "planned-partial",
   "retryable-failure"
 ] as const;
+/**
+ * The two statuses of a projection that covers only part of its targets (#327, Phase 1 capability
+ * isolation): `planned-partial` from `check` and `plan`, `applied-partial` from `apply`. Exactly
+ * these results carry `coverage`, always with `complete: false`; a complete result omits it.
+ */
+export const PROJECTION_PARTIAL_RESULT_STATUSES = ["applied-partial", "planned-partial"] as const;
+/**
+ * Why a target is carried forward instead of applied: a capability it depends on has an
+ * unprovable P1 or P2 proof (`unprovable-required-flow`), or its flow proof moved since the
+ * committed baseline while its semantic fingerprint held (`verified-flow-proof-changed`).
+ */
+export const PROJECTION_COVERAGE_REASON_CODES = ["unprovable-required-flow", "verified-flow-proof-changed"] as const;
 export const PROJECTION_HUMAN_ACTION_REASON_CODES = [
   "adoption-required",
   "manual-region-conflict",
@@ -60,8 +80,10 @@ export const ARCHITECTURE_REFRESH_TARGETS = [
 ] as const;
 export const ARCHCTX_FEATURES = [
   "architecture-change-capabilities-v1",
+  "architecture-debt-v1",
   "architecture-docs-renderer-v2",
   "architecture-refresh-signal-v1",
+  "capability-dependencies-declared-v1",
   "capability-dependencies-v1",
   "changeset-entity-operations-v1",
   "changeset-ownership-delta-v1",
@@ -69,17 +91,24 @@ export const ARCHCTX_FEATURES = [
   "docs-anchors-v1",
   "flow-selector-check-v1",
   "module-statistics-v1",
+  "native-context-export-v1",
   "projection-apply-readback-v1",
   "projection-apply-receipt-v1",
   "projection-apply-recovery-v1",
+  "projection-apply-replay-restore-v1",
   "projection-apply-replay-v1",
+  "projection-architecture-debt-v1",
+  "projection-capability-isolation-v1",
+  "projection-change-classification-v1",
   "projection-check-freshness-v1",
-  "projection-manifest-contract-v2",
+  "projection-freshness-v1",
+  "projection-manifest-contract-v3",
   "projection-observed-major-change-acceptance-v1",
   "projection-orphan-review-v1",
   "projection-preview-v1",
   "projection-prior-committed-applies-v1",
   "projection-protocol-v2",
+  "projection-snapshot-v1",
   "recommendation-scan-decision-v1",
   "recommendation-v3",
   "refactor-assessment-v1",
@@ -185,22 +214,99 @@ export const PROJECTION_PREVIEW_TOTAL_MAX_BYTES = 1_048_576;
 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;
 
+/** The architecture debt a `check` or `plan` result reports. Debt is a finding, never a blocker. */
+export const PROJECTION_ARCHITECTURE_DEBT_REASON_CODES = ["undeclared-dependency"] as const;
+/**
+ * Why the debt read is not a complete observation. The `code-facts-*` codes mean what they mean on
+ * `archctx deps`; `workspace-resolution-failed` means the workspace package map was unreadable, so
+ * no bare workspace import specifier could be resolved.
+ */
+export const PROJECTION_ARCHITECTURE_DEBT_COVERAGE_REASON_CODES = [
+  "code-facts-import-limit",
+  "code-facts-truncated",
+  "code-facts-unavailable",
+  "workspace-resolution-failed"
+] as const;
+
+/**
+ * How one target of a `check` or `plan` result changes (#327 finding 2), from the strongest reason
+ * down: `blocked` (a human must act before the target can be written: Phase 1 isolation, an orphan
+ * that needs review, an adoption or ownership rejection), `proof-change` (a known proof change,
+ * which a missing baseline never hides), `baseline-missing` (a comparison is unknown: no committed
+ * v3 manifest, or no committed row for the target), `semantic-change`, `output-change`,
+ * `stamp-only` (only the source stamps moved) and `unchanged`.
+ * `projectionTargetChangeClassification` is the one precedence rule.
+ */
+export const PROJECTION_TARGET_CHANGE_CLASSIFICATIONS = [
+  "baseline-missing",
+  "blocked",
+  "output-change",
+  "proof-change",
+  "semantic-change",
+  "stamp-only",
+  "unchanged"
+] as const;
+/** What the projection write does to the target's file: the result's own `files[]` decision for that path. */
+export const PROJECTION_TARGET_CHANGE_PLANNED_ACTIONS = ["create", "delete", "none", "update"] as const;
+/** The reason codes that block a target: no apply writes it until a human acts. */
+export const PROJECTION_TARGET_CHANGE_BLOCKING_REASON_CODES = [
+  "adoption-required",
+  "ambiguous-ownership",
+  "orphan-review-required",
+  "unprovable-required-flow",
+  "verified-flow-proof-changed"
+] as const;
+/**
+ * Why a target is classified as it is. Each comparison flag has its codes: `stampChanged` is
+ * `source-stamp-changed`; `semanticChanged` is `semantic-fingerprint-changed` or, for a target that
+ * describes the whole model, `model-digest-changed` (the committed `semanticBaseline.modelDigest`
+ * differs from the current model's); `proofChanged` is
+ * `flow-proof-changed` or `selector-evidence-changed`; `outputChanged` is `rendered-output-changed`
+ * (the rendered output differs from the committed row's `outputDigest`), `target-added`,
+ * `target-removed` or `file-bytes-changed` (the write changes the file although its rendered output
+ * is the committed one: a marker, a missing file, an edited region); an unknown comparison is
+ * `baseline-missing` or `target-row-missing`.
+ */
+export const PROJECTION_TARGET_CHANGE_REASON_CODES = [
+  "adoption-required",
+  "ambiguous-ownership",
+  "baseline-missing",
+  "file-bytes-changed",
+  "flow-proof-changed",
+  "model-digest-changed",
+  "orphan-review-required",
+  "rendered-output-changed",
+  "selector-evidence-changed",
+  "semantic-fingerprint-changed",
+  "source-stamp-changed",
+  "target-added",
+  "target-removed",
+  "target-row-missing",
+  "unprovable-required-flow",
+  "verified-flow-proof-changed"
+] as const;
+
 export type ProjectionMode = (typeof PROJECTION_MODES)[number];
+export type ProjectionTargetChangeClassification = (typeof PROJECTION_TARGET_CHANGE_CLASSIFICATIONS)[number];
+export type ProjectionTargetChangePlannedAction = (typeof PROJECTION_TARGET_CHANGE_PLANNED_ACTIONS)[number];
+export type ProjectionTargetChangeReasonCode = (typeof PROJECTION_TARGET_CHANGE_REASON_CODES)[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 ProjectionPartialResultStatus = (typeof PROJECTION_PARTIAL_RESULT_STATUSES)[number];
+export type ProjectionCoverageReasonCode = (typeof PROJECTION_COVERAGE_REASON_CODES)[number];
 export type ProjectionHumanActionReasonCode = (typeof PROJECTION_HUMAN_ACTION_REASON_CODES)[number];
 export type ProjectionPriorCommittedApplyOperation = (typeof PROJECTION_PRIOR_COMMITTED_APPLY_OPERATIONS)[number];
 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 ProjectionArchitectureDebtReasonCode = (typeof PROJECTION_ARCHITECTURE_DEBT_REASON_CODES)[number];
+export type ProjectionArchitectureDebtCoverageReasonCode = (typeof PROJECTION_ARCHITECTURE_DEBT_COVERAGE_REASON_CODES)[number];
 export type ArchitectureSemanticFacet = (typeof ARCHITECTURE_SEMANTIC_FACETS)[number];
 export type ProjectionFilePreviewFormat = (typeof PROJECTION_FILE_PREVIEW_FORMATS)[number];
 export type Sha256Digest = `sha256:${string}`;
@@ -280,7 +386,7 @@ export interface ProjectionSnapshotV1 extends ProjectionExpectedSnapshotV1 {
   layoutVersion: "archcontext.docs-layout/v1";
   generatedFrom: {
     codeGraphPackage: "@colbymchenry/codegraph";
-    codeGraphVersion: "1.6.1";
+    codeGraphVersion: "1.6.2";
     codeGraphStatus: "ready" | "unavailable";
   };
 }
@@ -405,6 +511,108 @@ export interface ProjectionFreshnessV1 {
   staleNodes: ProjectionFreshnessStaleNodeV1[];
 }
 
+/**
+ * One capability pair whose imports no model relation declares, under the rule of
+ * CAPABILITY_DEPENDENCY_DECLARING_RELATION_KINDS. It is the same pair, with the same edge count,
+ * that `archctx deps` reports as a cross-capability cell with `declared: false`, measured over
+ * the files this run measured instead of the `HEAD` tree.
+ */
+export interface ProjectionUndeclaredDependencyV1 {
+  reasonCode: "undeclared-dependency";
+  fromCapabilityId: string;
+  toCapabilityId: string;
+  /** Distinct file-to-file import edges from `fromCapabilityId` into `toCapabilityId`; at least 1. */
+  importEdgeCount: number;
+}
+
+/**
+ * Architecture debt that this `check` or `plan` run found. It reuses the import facts the run
+ * already read, never blocks a mode and changes no rendered output. It covers every capability
+ * pair in the repository, not only pairs that touch the request's `changedPaths`.
+ */
+export interface ProjectionArchitectureDebtV1 {
+  /**
+   * `unknown` when the run had no code facts (`code-facts-unavailable`): `items` is then empty and
+   * says nothing about the repository. `partial` when the import read is a prefix of the index or
+   * a workspace specifier could not be resolved: `items` then holds what was observed.
+   */
+  coverage: EvidenceCoverageLevelV2;
+  /** Sorted and unique; empty exactly when `coverage` is `complete`. */
+  coverageReasonCodes: ProjectionArchitectureDebtCoverageReasonCode[];
+  /** Sorted by `fromCapabilityId`, then `toCapabilityId`. */
+  items: ProjectionUndeclaredDependencyV1[];
+}
+
+/** One target a partial result carries forward instead of applying. */
+export interface ProjectionCoverageBlockedTargetV1 {
+  targetId: string;
+  path: string;
+  /** The blocked capabilities this target depends on, sorted. Never empty. */
+  capabilityIds: string[];
+  /** Why those capabilities block it, sorted. Never empty. */
+  reasonCodes: ProjectionCoverageReasonCode[];
+}
+
+/**
+ * Which part of the projection a `planned-partial` or `applied-partial` result covers (#327,
+ * Phase 1 capability isolation). The blocked capabilities are those whose proof is unprovable or
+ * whose flow proof moved without an accepted change, while their semantic fingerprint held. Every
+ * target that depends on one of them is carried forward unchanged: its document, its manifest row
+ * and the capability's baseline entry keep their committed bytes. `appliedTargetIds` are all the
+ * other targets, which the result renders from the current model and sources.
+ *
+ * `complete` is always `false`: a result that covers every target omits `coverage` instead. A
+ * partial result is never an acceptance. It carries no apply receipt and no refresh signal, and a
+ * complete check or the `complete` gate still reports the blocked capabilities until they are
+ * fixed or accepted.
+ */
+export interface ProjectionCoverageV1 {
+  complete: false;
+  /** Sorted and unique. Never empty. */
+  blockedCapabilityIds: string[];
+  /** Sorted and unique by targetId. Never empty. */
+  blockedTargets: ProjectionCoverageBlockedTargetV1[];
+  /** Sorted and unique; disjoint from the blocked targets. */
+  appliedTargetIds: string[];
+}
+
+/**
+ * One target of a `check` or `plan` result (#327 finding 2): how it changes since the committed
+ * projection, and what this run's write does to its file. The entries cover the union of the
+ * current layout's targets and the committed manifest's rows (plus orphans the manifest does not
+ * record), one per path. The projection manifest is not a target; its write is the `files[]` entry
+ * no change names.
+ *
+ * Each comparison is against the committed v3 manifest: `stampChanged` the target row's
+ * `sourceStamps`; `outputChanged` the row's `outputDigest`, or any byte the write changes;
+ * `semanticChanged` the `semanticFingerprint` of a capability the target documents (every
+ * capability for a target that is not an entity summary, which also compares the manifest's
+ * `semanticBaseline.modelDigest`, because it renders the whole model); `proofChanged` the `flowProofFingerprint`
+ * or `selectorEvidenceDigest` of a capability an entity summary documents. `null` is an unknown
+ * comparison, never `false`.
+ *
+ * `plannedAction` is the result's own write decision (`files[]`) for that path. When `status` is
+ * `planned` or `planned-partial`, the targets whose action is not `none` are exactly the documents
+ * an apply of this run writes or deletes; under `adoption-required` or `human-action-required`
+ * apply writes nothing, and `plannedAction` reports only what the render would write. A
+ * path rejected for adoption or ownership repair is `blocked` and `none`, because only an
+ * approved adoption writes it. `classification` never changes `status`, the write set or a gate.
+ */
+export interface ProjectionTargetChangeV1 {
+  targetId: string;
+  path: string;
+  /** Sorted and unique: the documented capabilities whose change affects this target. Empty when unchanged. */
+  affectedCapabilityIds: string[];
+  stampChanged: boolean | null;
+  outputChanged: boolean;
+  semanticChanged: boolean | null;
+  proofChanged: boolean | null;
+  plannedAction: ProjectionTargetChangePlannedAction;
+  classification: ProjectionTargetChangeClassification;
+  /** Sorted and unique. Empty exactly when `classification` is `unchanged`. */
+  reasonCodes: ProjectionTargetChangeReasonCode[];
+}
+
 export interface ProjectionResultV2 {
   schemaVersion: typeof PROJECTION_RESULT_SCHEMA_VERSION;
   requestId: string;
@@ -427,12 +635,31 @@ export interface ProjectionResultV2 {
    * Consumers gate on the `projection-check-freshness-v1` capability, not on field presence.
    */
   freshness?: ProjectionFreshnessV1;
+  /**
+   * Present on every `check` and `plan` result, and on no other: the architecture debt this run
+   * found. It never changes `status`. Consumers gate on the `projection-architecture-debt-v1`
+   * capability, not on field presence.
+   */
+  architectureDebt?: ProjectionArchitectureDebtV1;
+  /**
+   * Present on every `check` and `plan` result, and on no other: per-target change classification,
+   * sorted by path (#327). It never changes `status` or `files`.
+   */
+  changes?: ProjectionTargetChangeV1[];
   /**
    * 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 exactly when `replayed` is: whether this response wrote projection-owned files (#325).
+   * `false` means it wrote nothing; the committed result is returned as recorded. `true` means
+   * the projection-owned outputs differed from the approved result at the approved snapshot, so
+   * the provider wrote the committed fixed point again under the original receipt. Excluded from
+   * `receiptDigest`.
+   */
+  written?: boolean;
   /**
    * 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
@@ -441,6 +668,11 @@ export interface ProjectionResultV2 {
    * so a caller can tell a declined flag from an absent one (#275).
    */
   majorChangeAcceptance?: "declined-unprovable-proof";
+  /**
+   * Present exactly on `planned-partial` and `applied-partial` results, with `complete: false`; a
+   * result that covers every target omits it. Consumers gate on `projection-capability-isolation-v1`.
+   */
+  coverage?: ProjectionCoverageV1;
   receiptDigest: Sha256Digest;
 }
 
@@ -623,9 +855,27 @@ export function projectionRequestInvariantIssues(input: ProjectionRequestV1): st
  * `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}`]
-    : [];
+  const issues: string[] = [];
+  if (mode !== "plan" && input.files.some((file) => file.preview !== undefined)) {
+    issues.push(`files[].preview is only allowed on a plan result, never when mode=${mode}`);
+  }
+  if (mode !== "check" && mode !== "plan" && input.architectureDebt !== undefined) {
+    issues.push(`architectureDebt is only allowed on a check or plan result, never when mode=${mode}`);
+  }
+  if (mode !== "check" && mode !== "plan" && input.changes !== undefined) {
+    issues.push(`changes is only allowed on a check or plan result, never when mode=${mode}`);
+  }
+  // The schema cannot condition on the request mode, so the presence promise is checked here.
+  if ((mode === "check" || mode === "plan") && input.changes === undefined) {
+    issues.push(`changes is required on every check or plan result, also when mode=${mode}`);
+  }
+  if (input.status === "planned-partial" && mode !== "check" && mode !== "plan") {
+    issues.push(`planned-partial is only allowed on a check or plan result, never when mode=${mode}`);
+  }
+  if (input.status === "applied-partial" && mode !== "apply") {
+    issues.push(`applied-partial is only allowed on an apply result, never when mode=${mode}`);
+  }
+  return issues;
 }
 
 export function projectionResultInvariantIssues(input: ProjectionResultV2): string[] {
@@ -647,6 +897,15 @@ 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");
   }
+  const partial = (PROJECTION_PARTIAL_RESULT_STATUSES as readonly string[]).includes(input.status);
+  if (partial !== (input.coverage !== undefined)) issues.push("coverage must be present exactly when status is planned-partial or applied-partial");
+  if (input.coverage !== undefined) issues.push(...projectionCoverageIssues(input.coverage, input.files));
+  if (partial) {
+    // An incomplete projection is never an acceptance: it records no apply and signals no refresh.
+    if (input.applyReceipt !== undefined) issues.push(`${input.status} status never carries applyReceipt`);
+    if (input.refreshSignals.length > 0) issues.push(`${input.status} status carries no refreshSignals`);
+  }
+  const committedApply = input.applyReceipt !== undefined || input.status === "applied" || input.status === "applied-partial" || input.status === "applied-reconcile-required";
   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`);
@@ -682,14 +941,30 @@ export function projectionResultInvariantIssues(input: ProjectionResultV2): stri
   }
   // 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")) {
+  if (input.files.some((file) => file.preview !== undefined) && committedApply) {
     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.architectureDebt) {
+    issues.push(...projectionArchitectureDebtIssues(input.architectureDebt));
+    if (committedApply) {
+      issues.push("architectureDebt is only allowed on a check or plan result, never on a committed apply");
+    }
+  }
+  if (input.changes) {
+    issues.push(...projectionTargetChangesIssues(input.changes, input.files));
+    if (committedApply) issues.push("changes is only allowed on a check or plan result, never on a committed apply");
+    // A carried-forward target is blocked, by the same reasons its coverage entry names.
+    for (const target of input.coverage?.blockedTargets ?? []) {
+      const entry = input.changes.find((candidate) => candidate.path === target.path);
+      if (!entry || entry.classification !== "blocked" || target.reasonCodes.some((code) => !entry.reasonCodes.includes(code))) {
+        issues.push(`changes must classify the carried-forward target ${target.path} as blocked with its coverage reason codes`);
+      }
+    }
+  }
   if (input.majorChangeAcceptance !== undefined) {
     if (input.majorChangeAcceptance !== "declined-unprovable-proof") issues.push("majorChangeAcceptance is unsupported");
     if (input.status !== "human-action-required"
@@ -704,6 +979,8 @@ export function projectionResultInvariantIssues(input: ProjectionResultV2): stri
       issues.push("replayed is only allowed on a committed apply result with applyReceipt");
     }
   }
+  if ((input.replayed !== undefined) !== (input.written !== undefined)) issues.push("written must be present exactly when replayed is present");
+  if (input.written !== undefined && typeof input.written !== "boolean") issues.push("written must be a boolean when present");
   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()) {
@@ -744,6 +1021,134 @@ function utf8ByteLength(value: string): number {
   return UTF8.encode(value).length;
 }
 
+/**
+ * Shape and canonical order of a partial result's `coverage`, and its binding to the result's
+ * files: a carried-forward target is never also a written file.
+ */
+export function projectionCoverageIssues(input: ProjectionCoverageV1, files: readonly ProjectionFileResultV1[] = []): string[] {
+  const issues = [
+    ...sortedUniqueIssues("coverage.blockedCapabilityIds", input.blockedCapabilityIds),
+    ...sortedUniqueIssues("coverage.blockedTargets.targetId", input.blockedTargets.map((target) => target.targetId)),
+    ...sortedUniqueIssues("coverage.appliedTargetIds", input.appliedTargetIds)
+  ];
+  if (input.complete !== false) issues.push("coverage.complete must be false; a result that covers every target omits coverage");
+  if (input.blockedCapabilityIds.length === 0) issues.push("coverage.blockedCapabilityIds must name at least one capability");
+  if (input.blockedTargets.length === 0) issues.push("coverage.blockedTargets must name at least one target");
+  if (input.blockedCapabilityIds.some((id) => typeof id !== "string" || id.trim() === "")) issues.push("coverage.blockedCapabilityIds must not contain empty ids");
+  if (input.appliedTargetIds.some((id) => typeof id !== "string" || id.trim() === "")) issues.push("coverage.appliedTargetIds must not contain empty ids");
+  const blockedCapabilities = new Set(input.blockedCapabilityIds);
+  const blockingCapabilities = new Set<string>();
+  const blockedPaths = new Set<string>();
+  const reasons = new Set<string>(PROJECTION_COVERAGE_REASON_CODES);
+  for (const [index, target] of input.blockedTargets.entries()) {
+    const prefix = `coverage.blockedTargets[${index}]`;
+    if (typeof target.targetId !== "string" || target.targetId.trim() === "") issues.push(`${prefix}.targetId must not be empty`);
+    if (!isRepoRelativePosixPath(target.path)) issues.push(`${prefix}.path must be a repository-relative POSIX path`);
+    else if (blockedPaths.has(target.path)) issues.push(`${prefix}.path is named by another blocked target`);
+    blockedPaths.add(target.path);
+    issues.push(...sortedUniqueIssues(`${prefix}.capabilityIds`, target.capabilityIds), ...sortedUniqueIssues(`${prefix}.reasonCodes`, target.reasonCodes));
+    if (target.capabilityIds.length === 0) issues.push(`${prefix}.capabilityIds must name at least one capability`);
+    if (target.reasonCodes.length === 0) issues.push(`${prefix}.reasonCodes must name at least one reason`);
+    for (const capabilityId of target.capabilityIds) {
+      if (!blockedCapabilities.has(capabilityId)) issues.push(`${prefix}.capabilityIds names ${capabilityId}, which is not a blocked capability`);
+      blockingCapabilities.add(capabilityId);
+    }
+    const reason = target.reasonCodes.find((code) => !reasons.has(code));
+    if (reason !== undefined) issues.push(`${prefix}.reasonCodes contains unsupported reason: ${reason}`);
+    if (input.appliedTargetIds.includes(target.targetId)) issues.push(`${prefix}.targetId must not also be an applied target`);
+  }
+  for (const capabilityId of input.blockedCapabilityIds) {
+    if (!blockingCapabilities.has(capabilityId)) issues.push(`coverage.blockedCapabilityIds names ${capabilityId}, which blocks no target`);
+  }
+  for (const file of files) {
+    if (blockedPaths.has(file.path)) issues.push(`files[] must not write the carried-forward target path ${file.path}`);
+  }
+  return issues;
+}
+
+const TARGET_CHANGE_BLOCKING_REASONS = new Set<string>(PROJECTION_TARGET_CHANGE_BLOCKING_REASON_CODES);
+const TARGET_CHANGE_UNKNOWN_REASONS = ["baseline-missing", "target-row-missing"] as const;
+const TARGET_CHANGE_OUTPUT_REASONS = ["file-bytes-changed", "rendered-output-changed", "target-added", "target-removed"] as const;
+const TARGET_CHANGE_PROOF_REASONS = ["flow-proof-changed", "selector-evidence-changed"] as const;
+const TARGET_CHANGE_SEMANTIC_REASONS = ["model-digest-changed", "semantic-fingerprint-changed"] as const;
+
+/**
+ * The one precedence rule of a target change: blocked > proof-change (`proofChanged === true`) >
+ * baseline-missing > semantic-change > output-change > stamp-only > unchanged. A known proof change
+ * is never hidden by an unknown comparison (a target without a committed row can still carry a
+ * moved flow proof); an unknown comparison outranks everything below the proof change and is never
+ * `unchanged`. `stamp-only` therefore means the stamps moved while the output bytes, and the
+ * semantic and proof comparisons, are known and unchanged on a target nothing blocks.
+ */
+export function projectionTargetChangeClassification(
+  input: Pick<ProjectionTargetChangeV1, "reasonCodes" | "stampChanged" | "outputChanged" | "semanticChanged" | "proofChanged">
+): ProjectionTargetChangeClassification {
+  if (input.reasonCodes.some((code) => TARGET_CHANGE_BLOCKING_REASONS.has(code))) return "blocked";
+  if (input.proofChanged === true) return "proof-change";
+  if (input.stampChanged === null || input.semanticChanged === null || input.proofChanged === null) return "baseline-missing";
+  if (input.semanticChanged) return "semantic-change";
+  if (input.outputChanged) return "output-change";
+  if (input.stampChanged) return "stamp-only";
+  return "unchanged";
+}
+
+/**
+ * Shape, canonical order and internal consistency of a result's `changes`, and their binding to its
+ * `files`: a change with a planned action names the `files[]` entry of its path with that action; a
+ * `files[]` entry a change names but does not plan is a path rejected for adoption or ownership
+ * repair, so that change is blocked by that rejection, and still reports the bytes that entry
+ * changes (`outputChanged`). Every `files[]` entry that changes a file has a change of its path,
+ * except the projection manifest, which is never a target.
+ */
+export function projectionTargetChangesIssues(input: readonly ProjectionTargetChangeV1[], files: readonly ProjectionFileResultV1[] = []): string[] {
+  const issues = sortedUniqueIssues("changes.path", input.map((entry) => entry.path));
+  const fileByPath = new Map(files.map((file) => [file.path, file]));
+  const reasons = new Set<string>(PROJECTION_TARGET_CHANGE_REASON_CODES);
+  for (const [index, entry] of input.entries()) {
+    const prefix = `changes[${index}]`;
+    const has = (codes: readonly string[]) => codes.some((code) => entry.reasonCodes.includes(code as ProjectionTargetChangeReasonCode));
+    if (typeof entry.targetId !== "string" || entry.targetId.trim() === "") issues.push(`${prefix}.targetId must not be empty`);
+    if (!isRepoRelativePosixPath(entry.path)) issues.push(`${prefix}.path must be a repository-relative POSIX path`);
+    issues.push(...sortedUniqueIssues(`${prefix}.affectedCapabilityIds`, entry.affectedCapabilityIds), ...sortedUniqueIssues(`${prefix}.reasonCodes`, entry.reasonCodes));
+    if (entry.affectedCapabilityIds.some((id) => typeof id !== "string" || id.trim() === "")) issues.push(`${prefix}.affectedCapabilityIds must not contain empty ids`);
+    const unsupported = entry.reasonCodes.find((code) => !reasons.has(code));
+    if (unsupported !== undefined) issues.push(`${prefix}.reasonCodes contains an unsupported code: ${unsupported}`);
+    for (const field of ["stampChanged", "semanticChanged", "proofChanged"] as const) {
+      if (entry[field] !== null && typeof entry[field] !== "boolean") issues.push(`${prefix}.${field} must be a boolean or null`);
+    }
+    if (typeof entry.outputChanged !== "boolean") issues.push(`${prefix}.outputChanged must be a boolean`);
+    if (!(PROJECTION_TARGET_CHANGE_PLANNED_ACTIONS as readonly string[]).includes(entry.plannedAction)) issues.push(`${prefix}.plannedAction is unsupported`);
+    if ((entry.stampChanged === true) !== has(["source-stamp-changed"])) issues.push(`${prefix}.stampChanged must be true exactly when source-stamp-changed is reported`);
+    if ((entry.semanticChanged === true) !== has(TARGET_CHANGE_SEMANTIC_REASONS)) issues.push(`${prefix}.semanticChanged must be true exactly when semantic-fingerprint-changed or model-digest-changed is reported`);
+    if ((entry.proofChanged === true) !== has(TARGET_CHANGE_PROOF_REASONS)) issues.push(`${prefix}.proofChanged must be true exactly when flow-proof-changed or selector-evidence-changed is reported`);
+    if (entry.outputChanged !== has(TARGET_CHANGE_OUTPUT_REASONS)) issues.push(`${prefix}.outputChanged must be true exactly when an output reason code is reported`);
+    if ((entry.stampChanged === null || entry.semanticChanged === null || entry.proofChanged === null) !== has(TARGET_CHANGE_UNKNOWN_REASONS)) {
+      issues.push(`${prefix} must report baseline-missing or target-row-missing exactly when a comparison is unknown`);
+    }
+    const derived = projectionTargetChangeClassification(entry);
+    if (entry.classification !== derived) issues.push(`${prefix}.classification must be ${derived} for its comparisons and reason codes`);
+    if ((entry.classification === "unchanged") !== (entry.reasonCodes.length === 0)) issues.push(`${prefix}.reasonCodes must be empty exactly when classification is unchanged`);
+    if (entry.classification === "unchanged" && entry.affectedCapabilityIds.length > 0) issues.push(`${prefix} is unchanged, so affectedCapabilityIds must be empty`);
+    if (entry.classification === "blocked" && entry.plannedAction !== "none") issues.push(`${prefix} is blocked, so plannedAction must be none`);
+    if (entry.plannedAction !== "none" && entry.outputChanged !== true) issues.push(`${prefix} writes its file, so outputChanged must be true`);
+    if (entry.path === ARCHITECTURE_DOCS_PROJECTION_MANIFEST_PATH) issues.push(`${prefix} names the projection manifest, which is not a target`);
+    const file = fileByPath.get(entry.path);
+    const fileAction = file === undefined || file.action === "unchanged" ? "none" : file.action;
+    const rejected = has(["adoption-required", "ambiguous-ownership"]);
+    if (entry.plannedAction !== fileAction && !(rejected && entry.plannedAction === "none" && fileAction === "update")) {
+      issues.push(`${prefix}.plannedAction must be ${fileAction}, the files[] action for ${entry.path}`);
+    }
+    // The file result proves the bytes change, whether or not this run may write them.
+    if (fileAction !== "none" && entry.outputChanged !== true) issues.push(`${prefix}.outputChanged must be true, the files[] entry for ${entry.path} changes its bytes`);
+  }
+  const changedPaths = new Set(input.map((entry) => entry.path));
+  for (const file of files) {
+    if (file.action === "unchanged" || file.path === ARCHITECTURE_DOCS_PROJECTION_MANIFEST_PATH || changedPaths.has(file.path)) continue;
+    issues.push(`changes must name the files[] ${file.action} of ${file.path}; only the projection manifest has none`);
+  }
+  return issues;
+}
+
 export function projectionFreshnessIssues(input: ProjectionFreshnessV1): string[] {
   const issues = [
     ...sortedUniqueIssues("freshness.reasonCodes", input.reasonCodes),
@@ -764,6 +1169,31 @@ export function projectionFreshnessIssues(input: ProjectionFreshnessV1): string[
   return issues;
 }
 
+export function projectionArchitectureDebtIssues(input: ProjectionArchitectureDebtV1): string[] {
+  const issues = [
+    ...sortedUniqueIssues("architectureDebt.coverageReasonCodes", input.coverageReasonCodes),
+    ...sortedUniqueIssues("architectureDebt.items", input.items.map((item) => JSON.stringify([item.fromCapabilityId, item.toCapabilityId])))
+  ];
+  if (!(["complete", "partial", "unknown"] as const).includes(input.coverage)) issues.push("architectureDebt.coverage is unsupported");
+  const unsupported = input.coverageReasonCodes.find((code) => !(PROJECTION_ARCHITECTURE_DEBT_COVERAGE_REASON_CODES as readonly string[]).includes(code));
+  if (unsupported) issues.push(`architectureDebt.coverageReasonCodes contains an unsupported code: ${unsupported}`);
+  if ((input.coverage === "complete") !== (input.coverageReasonCodes.length === 0)) {
+    issues.push("architectureDebt.coverageReasonCodes must be empty exactly when coverage is complete");
+  }
+  if ((input.coverage === "unknown") !== input.coverageReasonCodes.includes("code-facts-unavailable")) {
+    issues.push("architectureDebt.coverage must be unknown exactly when code-facts-unavailable is reported");
+  }
+  if (input.coverage === "unknown" && input.items.length > 0) issues.push("architectureDebt.items must be empty when coverage is unknown");
+  for (const [index, item] of input.items.entries()) {
+    const prefix = `architectureDebt.items[${index}]`;
+    if (!(PROJECTION_ARCHITECTURE_DEBT_REASON_CODES as readonly string[]).includes(item.reasonCode)) issues.push(`${prefix}.reasonCode is unsupported`);
+    if (item.fromCapabilityId.trim() === "" || item.toCapabilityId.trim() === "") issues.push(`${prefix} must name two capabilities`);
+    else if (item.fromCapabilityId === item.toCapabilityId) issues.push(`${prefix} must name two different capabilities`);
+    if (!Number.isSafeInteger(item.importEdgeCount) || item.importEdgeCount < 1) issues.push(`${prefix}.importEdgeCount must be a positive integer`);
+  }
+  return issues;
+}
+
 export function projectionPriorCommittedAppliesIssues(
   input: readonly ProjectionPriorCommittedApplyV1[],
   requestId: string
@@ -804,7 +1234,7 @@ export function projectionPriorCommittedAppliesIssues(
  * projectionReceiptDigest, which projectionResultInvariantIssues verifies.
  */
 export function projectionResultReceiptDigest(input: Omit<ProjectionResultV2, "receiptDigest">): Sha256Digest {
-  const { replayed: _replayed, ...payload } = input;
+  const { replayed: _replayed, written: _written, ...payload } = input;
   const refreshSignals = payload.refreshSignals.map(({ projectionReceiptDigest: _projectionReceiptDigest, ...signal }) => signal);
   return digestJson({ ...payload, refreshSignals } as unknown as Json) as Sha256Digest;
 }
@@ -866,6 +1296,8 @@ export function projectionApplyReceiptInvariantIssues(input: ProjectionApplyRece
     issues.push("projection apply identity must bind the committed files and original refresh signals");
   }
   if (input.result.status !== "applied") issues.push("projection apply receipt result status must be applied");
+  // A partial projection is never accepted, so no receipt ever records one.
+  if (input.result.coverage !== undefined) issues.push("projection apply receipt result must cover every target");
   if (digestJson(input.result.applyReceipt as unknown as Json) !== digestJson(input.identity as unknown as Json)) {
     issues.push("projection apply receipt result must carry the same apply identity");
   }