archctx-contracts 0.4.8 → 0.5.2

package/fixtures/valid/archctx-capabilities.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "archcontext.capabilities/v1",
-  "package": { "name": "archctx", "version": "0.4.8" },
+  "package": { "name": "archctx", "version": "0.5.2" },
   "protocols": {
     "projectionRequest": "archcontext.projection-request/v1",
     "projectionResult": "archcontext.projection-result/v2",
@@ -10,5 +10,5 @@
     "architectureDocs": "archcontext.docs-renderer/v4",
     "agentContext": "archcontext.agent-context-renderer/v1"
   },
-  "features": ["architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-protocol-v2"]
+  "features": ["architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "module-statistics-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-protocol-v2", "recommendation-v3", "refactor-assessment-v1", "refactor-resolution-v1"]
 }

package/fixtures/valid/product-version-manifest.json

@@ -2,7 +2,7 @@
   "schemaVersion": "archcontext.product-version-manifest/v1",
   "product": {
     "name": "archctx",
-    "version": "0.4.8",
+    "version": "0.5.2",
     "distribution": "one-package"
   },
   "packageManager": "bun@1.4.0",
@@ -12,25 +12,25 @@
   "surfaces": {
     "cli": {
       "packageName": "@archcontext/surfaces",
-      "version": "0.4.8",
+      "version": "0.5.2",
       "entrypoint": "archctx"
     },
     "daemon": {
       "packageName": "@archcontext/local-runtime",
-      "version": "0.4.8",
+      "version": "0.5.2",
       "entrypoint": "archctx daemon start",
       "rpcSchemaVersion": "archcontext.runtime-rpc/v1"
     },
     "mcp": {
       "packageName": "@archcontext/surfaces",
-      "version": "0.4.8",
+      "version": "0.5.2",
       "entrypoint": "archctx mcp",
       "transport": "stdio"
     }
   },
   "schemas": {
     "schemaSetVersion": "2026-06-25.al0-ledger",
-    "contractsPackageVersion": "0.4.8",
+    "contractsPackageVersion": "0.5.2",
     "reviewChallenge": "archcontext.review-challenge/v2",
     "attestation": "archcontext.attestation/v2",
     "deviceIdentity": "archcontext.device-identity/v1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archctx-contracts",
-  "version": "0.4.8",
+  "version": "0.5.2",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",

package/schemas/runtime/archctx-capabilities.schema.json

@@ -39,7 +39,7 @@
       "type": "array",
       "minItems": 3,
       "uniqueItems": true,
-      "items": { "enum": ["architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-protocol-v2"] }
+      "items": { "enum": ["architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "module-statistics-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-protocol-v2", "recommendation-v3", "refactor-assessment-v1", "refactor-resolution-v1"] }
     }
   }
 }

package/src/index.ts

@@ -7,5 +7,6 @@ export * from "./ports";
 export * from "./practices";
 export * from "./projection";
 export * from "./product-version";
+export * from "./refactor";
 export * from "./schema";
 export * from "./validator";

package/src/ledger.ts

@@ -1,3 +1,11 @@
+import type { ArchitectureMajorChangeReasonCode } from "./projection";
+import type {
+  ArchitectureTargetDeltaV1,
+  RefactorKillListEntryV1,
+  RefactorObservationKind,
+  RefactorScale,
+  RefactorTargetOutcomeV1
+} from "./refactor";
 import { digestJson, type Json } from "./schema";
 
 export const ARCHITECTURE_EVENT_SCHEMA_VERSION = "archcontext.architecture-event/v1" as const;
@@ -6,6 +14,7 @@ export const EVIDENCE_ITEM_SCHEMA_VERSION = "archcontext.evidence-item/v2" as co
 export const EVIDENCE_BINDING_SCHEMA_VERSION = "archcontext.evidence-binding/v1" as const;
 export const RECOMMENDATION_RUN_SCHEMA_VERSION = "archcontext.recommendation-run/v1" as const;
 export const RECOMMENDATION_SCHEMA_VERSION = "archcontext.recommendation/v2" as const;
+export const RECOMMENDATION_V3_SCHEMA_VERSION = "archcontext.recommendation/v3" as const;
 export const RECOMMENDATION_FEEDBACK_SCHEMA_VERSION = "archcontext.recommendation-feedback/v1" as const;
 export const AGENT_JOB_SCHEMA_VERSION = "archcontext.agent-job/v1" as const;
 export const INVESTIGATION_REPORT_SCHEMA_VERSION = "archcontext.investigation-report/v1" as const;
@@ -14,9 +23,23 @@ export const ARCHITECTURE_CANDIDATE_DELTA_SCHEMA_VERSION = "archcontext.architec
 export const ARCHITECTURE_CANDIDATE_DELTA_POLICY_SCHEMA_VERSION = "archcontext.architecture-candidate-delta-policy/v1" as const;
 export const PROJECTION_TARGET_SCHEMA_VERSION = "archcontext.projection-target/v1" as const;
 
+export const RECOMMENDATION_CATEGORIES = ["practice", "refactor_proposal", "structural_observation"] as const;
+
 export type ArchitectureFactAuthority = "declared" | "observed" | "verified" | "proposed" | "projected";
 export type ArchitectureLedgerMode = "yaml" | "dual" | "dual-compare" | "ledger-shadow" | "ledger" | "ledger-authoritative";
 export type ArchitectureActorKind = "developer" | "daemon" | "hook" | "cli" | "mcp" | "subagent" | "migration" | "system";
+export type ArchitectureActorSource = "cli" | "mcp" | "manual" | "daemon" | "system" | "subagent";
+export type RecommendationCategory = (typeof RECOMMENDATION_CATEGORIES)[number];
+export type RecommendationStatus =
+  | "open"
+  | "acknowledged"
+  | "accepted"
+  | "rejected"
+  | "deferred"
+  | "waived"
+  | "resolved"
+  | "superseded"
+  | "expired";
 export type ArchitectureEventSource =
   | "prepare_task"
   | "checkpoint"
@@ -28,7 +51,8 @@ export type ArchitectureEventSource =
   | "projection_reconcile"
   | "migration"
   | "manual"
-  | "agent_audit";
+  | "agent_audit"
+  | "refactor_scan";
 
 export type EvidenceStrengthV2 = "heuristic" | "declared" | "observed" | "verified";
 export type EvidencePolarityV2 = "positive" | "absence" | "declaration";
@@ -621,7 +645,7 @@ export interface RecommendationV2 {
   fingerprint: string;
   subject: string;
   practiceId?: string;
-  status: "open" | "acknowledged" | "accepted" | "rejected" | "deferred" | "waived" | "resolved" | "superseded" | "expired";
+  status: RecommendationStatus;
   confidence: "low" | "medium" | "high";
   enforcement: "advisory" | "checkpoint" | "complete";
   risk: "low" | "medium" | "high";
@@ -639,12 +663,12 @@ export interface RecommendationFeedbackV1 {
   recommendationId: string;
   runId: string;
   action: "acknowledge" | "accept" | "reject" | "defer" | "waive" | "resolve";
-  previousStatus: RecommendationV2["status"];
-  nextStatus: RecommendationV2["status"];
+  previousStatus: RecommendationStatus;
+  nextStatus: RecommendationStatus;
   actor: {
     kind: ArchitectureActorKind;
     id: string;
-    source: "cli" | "mcp" | "manual" | "daemon" | "system" | "subagent";
+    source: ArchitectureActorSource;
   };
   reason: string;
   explicit: true;
@@ -655,6 +679,78 @@ export interface RecommendationFeedbackV1 {
   extensions?: Record<string, Json>;
 }
 
+export interface RecommendationAuthorV1 {
+  kind: ArchitectureActorKind;
+  id: string;
+  source: ArchitectureActorSource;
+}
+
+export interface RecommendationRelationsV1 {
+  supersedes?: string;
+  regressesFrom?: string;
+}
+
+export interface PracticeRecommendationPayloadV1 {
+  practiceId: string;
+  baselineDigest: string | null;
+}
+
+export interface StructuralObservationPayloadV1 {
+  assessmentDigest: string;
+  kind: RefactorObservationKind;
+  affectedNodeIds: string[];
+  baselineSnapshotDigest: string;
+  derivedOutcomes: RefactorTargetOutcomeV1[];
+}
+
+export interface RefactorProposalPayloadV1 {
+  assessmentDigest: string;
+  proposalDigest: string;
+  scale: RefactorScale;
+  affectedNodeIds: string[];
+  majorChangeReasons: ArchitectureMajorChangeReasonCode[];
+  baselineSnapshotDigest: string;
+  targetDelta?: ArchitectureTargetDeltaV1;
+  targetOutcomes: RefactorTargetOutcomeV1[];
+  killList: RefactorKillListEntryV1[];
+}
+
+export type RecommendationPayloadV1 =
+  | PracticeRecommendationPayloadV1
+  | StructuralObservationPayloadV1
+  | RefactorProposalPayloadV1;
+
+/** Strict superset of RecommendationV2: every v2 field is kept verbatim. */
+export interface RecommendationV3Base {
+  schemaVersion: typeof RECOMMENDATION_V3_SCHEMA_VERSION;
+  recommendationId: string;
+  runId: string;
+  fingerprint: string;
+  subject: string;
+  practiceId?: string;
+  status: RecommendationStatus;
+  confidence: "low" | "medium" | "high";
+  enforcement: "advisory" | "checkpoint" | "complete";
+  risk: "low" | "medium" | "high";
+  uncertainty: "low" | "medium" | "high";
+  evidenceBindingIds: string[];
+  explanation: string[];
+  authoredBy: RecommendationAuthorV1;
+  subjectSelectorId: string;
+  relations: RecommendationRelationsV1;
+  createdAt: string;
+  updatedAt: string;
+  extensions?: Record<string, Json>;
+}
+
+/** `category` discriminates `payload`; no other combination is representable. */
+export type RecommendationV3CategoryPayloadV1 =
+  | { category: "practice"; payload: PracticeRecommendationPayloadV1 }
+  | { category: "structural_observation"; payload: StructuralObservationPayloadV1 }
+  | { category: "refactor_proposal"; payload: RefactorProposalPayloadV1 };
+
+export type RecommendationV3 = RecommendationV3Base & RecommendationV3CategoryPayloadV1;
+
 export interface AgentJobV1 {
   schemaVersion: typeof AGENT_JOB_SCHEMA_VERSION;
   jobId: string;

package/src/product-version.ts

@@ -1,5 +1,5 @@
 export const ARCHCONTEXT_PRODUCT_NAME = "archctx";
-export const ARCHCONTEXT_PRODUCT_VERSION = "0.4.8";
+export const ARCHCONTEXT_PRODUCT_VERSION = "0.5.2";
 export const ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.4.0";
 export const ARCHCONTEXT_NODE_RANGE = ">=22.22 <26";
 export const LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v1";

package/src/projection.ts

@@ -58,9 +58,13 @@ export const ARCHITECTURE_REFRESH_TARGETS = [
 export const ARCHCTX_FEATURES = [
   "architecture-docs-renderer-v2",
   "architecture-refresh-signal-v1",
+  "module-statistics-v1",
   "projection-apply-receipt-v1",
   "projection-apply-recovery-v1",
-  "projection-protocol-v2"
+  "projection-protocol-v2",
+  "recommendation-v3",
+  "refactor-assessment-v1",
+  "refactor-resolution-v1"
 ] as const;
 
 export type ProjectionMode = (typeof PROJECTION_MODES)[number];

package/src/refactor.ts

@@ -0,0 +1,994 @@
+import { RECOMMENDATION_CATEGORIES, RECOMMENDATION_V3_SCHEMA_VERSION } from "./ledger";
+import type {
+  ArchitectureActorKind,
+  ArchitectureRepositoryIdentityV1,
+  ArchitectureWorktreeIdentityV1,
+  EvidenceCoverageLevelV2,
+  PracticeRecommendationPayloadV1,
+  RecommendationAuthorV1,
+  RecommendationCategory,
+  RecommendationPayloadV1,
+  RecommendationV3,
+  RecommendationV3Base,
+  RefactorProposalPayloadV1,
+  StructuralObservationPayloadV1
+} from "./ledger";
+import { ARCHITECTURE_MAJOR_CHANGE_REASON_CODES, type ArchitectureMajorChangeReasonCode } from "./projection";
+import { digestJson, isRepoRelativePosixPath, type Json, type Severity } from "./schema";
+
+const DIGEST_PREFIX_LENGTH = "sha256:".length;
+const SHA256_DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const BARE_SHA256_PATTERN = /^[a-f0-9]{64}$/;
+const GIT_HEAD_SHA_PATTERN = /^[a-f0-9]{40}$/;
+
+/**
+ * The bounded grammar an execution evidence `locator` must fit: 1..256 characters drawn from the
+ * unreserved plus sub-delims/gen-delims set that repo-relative paths and URLs already live in.
+ *
+ * A locator is a *reference*, not a body. Left unbounded it is a string field on a record whose
+ * envelope promises `privacy.rawDiffPersisted: false`, so a caller could park a whole diff, a
+ * credential, or a multi-line prompt in it and the digest check would still pass. Whitespace,
+ * newlines and control characters are the shapes that only a body has, and the length ceiling is
+ * what stops a single-line body from riding through anyway.
+ */
+export const REFACTOR_EXECUTION_EVIDENCE_LOCATOR_PATTERN = /^[A-Za-z0-9._~:\/?#@!$&'()*+,;=%-]{1,256}$/;
+
+/** The single sentence every ingress uses to name the locator rule, so they cannot drift apart. */
+export const REFACTOR_EXECUTION_EVIDENCE_LOCATOR_RULE =
+  "must be a bounded reference: 1-256 characters from [A-Za-z0-9._~:/?#@!$&'()*+,;=%-], no whitespace or control characters";
+
+/** The only top-level keys a verification request may carry; anything else is a caller typo. */
+export const REFACTOR_VERIFICATION_REQUEST_KEYS = [
+  "executionEvidenceRefs",
+  "expectedHeadSha",
+  "expectedWorktreeDigest",
+  "recommendationId",
+  "schemaVersion"
+] as const;
+
+export const REFACTOR_REQUEST_SCHEMA_VERSION = "archcontext.refactor-request/v1" as const;
+export const REFACTOR_PROPOSAL_SCHEMA_VERSION = "archcontext.refactor-proposal/v1" as const;
+export const MODULE_STATISTICS_SCHEMA_VERSION = "archcontext.module-statistics/v1" as const;
+export const REFACTOR_ASSESSMENT_SCHEMA_VERSION = "archcontext.refactor-assessment/v1" as const;
+export const REFACTOR_RESOLUTION_EVIDENCE_SCHEMA_VERSION = "archcontext.refactor-resolution-evidence/v1" as const;
+export const REFACTOR_VERIFICATION_REQUEST_SCHEMA_VERSION = "archcontext.refactor-verification-request/v1" as const;
+
+export const REFACTOR_SCALES = [
+  "architecture",
+  "cross_module",
+  "insufficient_evidence",
+  "model_adoption_required",
+  "module"
+] as const;
+export const REFACTOR_SCALE_REASON_CODES = [
+  "caller-coverage-unknown",
+  "code-facts-missing",
+  "code-facts-truncated",
+  "major-change-detected",
+  "multi-node-scope",
+  "node-footprint-undeclared",
+  "ownership-ambiguous",
+  "single-node-scope",
+  "target-unresolved",
+  "unowned-paths"
+] as const;
+export const REFACTOR_OBSERVATION_KINDS = [
+  "cycle",
+  "direction-violation",
+  "evidence-gap",
+  "ownership-ambiguous",
+  "undeclared-footprint",
+  "unowned-paths"
+] as const;
+export const REFACTOR_RESOLUTION_DISPOSITIONS = [
+  "not_improved",
+  "partially_resolved",
+  "regressed",
+  "resolved",
+  "stale"
+] as const;
+export const REFACTOR_OUTCOME_OPERATORS = ["absent", "equals", "greater_than", "less_than", "present"] as const;
+export const REFACTOR_OUTCOME_DIRECTIONS = ["improved", "regressed", "unchanged", "unknown"] as const;
+export const REFACTOR_KILL_LIST_KINDS = ["path", "relation", "symbol"] as const;
+export const REFACTOR_EXECUTION_EVIDENCE_KINDS = [
+  "acceptance_receipt",
+  "cutover_closure",
+  "merge_receipt",
+  "task_contract"
+] as const;
+export const REFACTOR_PROPOSAL_AUTHOR_SOURCES = ["cli", "manual", "mcp", "subagent"] as const;
+export const REFACTOR_PROPOSAL_AUTHOR_KINDS = ["cli", "developer", "mcp", "subagent"] as const;
+/**
+ * A refactor proposal is authored by an agent surface acting for itself, or by
+ * a human acting manually. `daemon`, `system`, `hook`, and `migration` kinds
+ * are ArchContext acting on its own behalf and can never author a proposal.
+ */
+export const REFACTOR_PROPOSAL_AUTHOR_PAIRS: Readonly<Record<RefactorProposalAuthorKind, readonly RefactorProposalAuthorSource[]>> = {
+  cli: ["cli"],
+  developer: ["manual"],
+  mcp: ["mcp"],
+  subagent: ["subagent"]
+};
+export const MODULE_DYNAMIC_INVOCATION_LEVELS = ["known", "none_observed", "possible", "unknown"] as const;
+export const MODULE_TESTS_COVERAGE_STATUSES = ["measured", "partial", "unknown"] as const;
+
+export type RefactorScale = (typeof REFACTOR_SCALES)[number];
+export type RefactorScaleReasonCode = (typeof REFACTOR_SCALE_REASON_CODES)[number];
+export type RefactorObservationKind = (typeof REFACTOR_OBSERVATION_KINDS)[number];
+export type RefactorResolutionDisposition = (typeof REFACTOR_RESOLUTION_DISPOSITIONS)[number];
+export type RefactorOutcomeOperator = (typeof REFACTOR_OUTCOME_OPERATORS)[number];
+export type RefactorOutcomeDirection = (typeof REFACTOR_OUTCOME_DIRECTIONS)[number];
+export type RefactorKillListKind = (typeof REFACTOR_KILL_LIST_KINDS)[number];
+export type RefactorExecutionEvidenceKind = (typeof REFACTOR_EXECUTION_EVIDENCE_KINDS)[number];
+export type RefactorProposalAuthorSource = (typeof REFACTOR_PROPOSAL_AUTHOR_SOURCES)[number];
+export type RefactorProposalAuthorKind = (typeof REFACTOR_PROPOSAL_AUTHOR_KINDS)[number];
+export type ModuleDynamicInvocationLevel = (typeof MODULE_DYNAMIC_INVOCATION_LEVELS)[number];
+export type ModuleTestsCoverageStatus = (typeof MODULE_TESTS_COVERAGE_STATUSES)[number];
+
+export type RefactorScopeV1 =
+  | { kind: "repository" }
+  | { kind: "node"; nodeId: string }
+  | { kind: "paths"; paths: string[] };
+
+export interface RefactorTargetOutcomeV1 {
+  outcomeId: string;
+  metric: string;
+  subjectSelectorId: string;
+  nodeId: string | null;
+  operator: RefactorOutcomeOperator;
+  value: number | null;
+  required: boolean;
+}
+
+export interface RefactorObservedOutcomeV1 {
+  outcomeId: string;
+  observedValue: number | null;
+  satisfied: boolean;
+  direction: RefactorOutcomeDirection;
+}
+
+export interface RefactorKillListEntryV1 {
+  kind: RefactorKillListKind;
+  selectorId: string;
+  required: boolean;
+}
+
+export interface ArchitectureTargetDeltaV1 {
+  interventionId: string;
+  trigger: string[];
+  thesis: string;
+  targetState: {
+    owners: Record<string, string>;
+    requiredRelations: string[];
+    removedConcepts: string[];
+  };
+  migrationState: {
+    active: boolean;
+    compatibilityContracts: string[];
+    cleanupBy?: string;
+    temporaryRelations: string[];
+  };
+  completionCriteria: RefactorTargetOutcomeV1[];
+  falsifiers: string[];
+  benefitLedger: {
+    benefits: string[];
+    costs: string[];
+    rollbackPoint: string;
+  };
+  unresolvedTargets: string[];
+  extensions?: Record<string, Json>;
+}
+
+export interface RefactorProposalV1 {
+  schemaVersion: typeof REFACTOR_PROPOSAL_SCHEMA_VERSION;
+  authoredBy: RecommendationAuthorV1;
+  intent: string;
+  scopePaths: string[];
+  targetDelta?: ArchitectureTargetDeltaV1;
+  targetOutcomes: RefactorTargetOutcomeV1[];
+  killList: RefactorKillListEntryV1[];
+  proposalDigest: string;
+  extensions?: Record<string, Json>;
+}
+
+export interface RefactorRequestV1 {
+  schemaVersion: typeof REFACTOR_REQUEST_SCHEMA_VERSION;
+  scope: RefactorScopeV1;
+  proposal?: RefactorProposalV1;
+  expectedHeadSha?: string;
+  expectedWorktreeDigest?: string;
+  task?: string;
+}
+
+/**
+ * The JSON ingress for `refactor verify`. `recommendationId` is the whole subject: a verification
+ * always re-measures whatever is at HEAD now, so there is no caller-supplied AFTER state and no
+ * outcome override — the recorded recommendation already carries the acceptance test, and letting
+ * a caller restate it would let the requester steer its own verdict.
+ *
+ * `expectedHeadSha` and `expectedWorktreeDigest` are claims about the state the caller believes it
+ * is verifying. A claim that no longer holds is refused rather than answered with fresh numbers
+ * under the old identity.
+ */
+export interface RefactorVerificationRequestV1 {
+  schemaVersion: typeof REFACTOR_VERIFICATION_REQUEST_SCHEMA_VERSION;
+  recommendationId: string;
+  expectedHeadSha?: string;
+  expectedWorktreeDigest?: string;
+  executionEvidenceRefs?: RefactorExecutionEvidenceRefV1[];
+}
+
+export interface ModuleStatisticsV1 {
+  nodeId: string;
+  nodeDigest: string;
+  parentNodeId: string | null;
+  footprintDeclared: boolean;
+  footprint: {
+    fileCount: number;
+    lineCount: number;
+    sourceFilesDigest: string;
+    includePatterns: string[];
+    excludePatterns: string[];
+  } | null;
+  surfaces: {
+    declaredEntrypoints: string[];
+    observedEntrypoints: string[];
+    lifecycleOwners: string[];
+    datastoreSubjects: string[];
+  };
+  dependencyGraph: {
+    internalEdgeCount: number;
+    inboundModuleEdges: number;
+    outboundModuleEdges: number;
+    fanIn: number;
+    fanOut: number;
+    stronglyConnectedComponentId: string | null;
+    cycleCount: number;
+    instability: number | null;
+    directionViolationCount: number | null;
+  } | null;
+  /**
+   * `callerCoverage` is a graph-boundary resolution ratio (the share of the
+   * module's inbound call boundary the index could resolve), not a test
+   * measurement, so it is independent of `coverageStatus`: a producer may know
+   * the boundary ratio while observing no test evidence at all, and it may know
+   * test files while the boundary stays unresolved. Only the 0-1 ratio bound is
+   * enforced; the two fields are never coupled (PRD 0.3-16).
+   */
+  tests: {
+    testFileCount: number | null;
+    observedTestEdges: number | null;
+    callerCoverage: number | null;
+    coverageStatus: ModuleTestsCoverageStatus;
+  };
+  uncertainty: {
+    unresolvedImports: number;
+    dynamicInvocation: ModuleDynamicInvocationLevel;
+    ambiguousOwnership: boolean;
+  };
+  moduleDigest: string;
+  extensions?: Record<string, Json>;
+}
+
+export interface ModuleStatisticsSnapshotV1 {
+  schemaVersion: typeof MODULE_STATISTICS_SCHEMA_VERSION;
+  repository: ArchitectureRepositoryIdentityV1;
+  worktree: ArchitectureWorktreeIdentityV1;
+  modelDigest: string;
+  codeFacts: {
+    provider: "codegraph";
+    version: string;
+    binaryDigest: string;
+    indexedWorktreeDigest: string | null;
+    coverage: EvidenceCoverageLevelV2;
+    truncated: boolean;
+    edgeLimit: number | null;
+    reasonCodes: RefactorScaleReasonCode[];
+  };
+  modules: ModuleStatisticsV1[];
+  repositorySummary: {
+    moduleCount: number;
+    undeclaredFootprintNodeCount: number;
+    ownedFileCount: number;
+    unownedFileCount: number;
+    multiplyOwnedFileCount: number;
+    crossModuleEdgeCount: number;
+    crossModuleCycleCount: number;
+    stronglyConnectedComponentCount: number;
+    unresolvedImportCount: number;
+    dynamicInvocationRiskCount: number;
+  };
+  createdAt: string;
+  snapshotDigest: string;
+  extensions?: Record<string, Json>;
+}
+
+export interface RefactorObservationV1 {
+  kind: RefactorObservationKind;
+  subjectSelectorId: string;
+  signalIds: string[];
+  metrics: Record<string, number | null>;
+}
+
+export interface RefactorAssessmentV1 {
+  schemaVersion: typeof REFACTOR_ASSESSMENT_SCHEMA_VERSION;
+  requestId: string;
+  statisticsSnapshotDigest: string;
+  modelDigest: string;
+  codeFactsDigest: string;
+  requestedScope: RefactorScopeV1;
+  proposalDigest: string | null;
+  observations: RefactorObservationV1[];
+  scale: RefactorScale | null;
+  scaleReasonCodes: RefactorScaleReasonCode[];
+  affectedNodeIds: string[];
+  majorChangeReasons: ArchitectureMajorChangeReasonCode[];
+  pressure: {
+    level: "low" | "medium" | "high";
+    score: number;
+    signalIds: string[];
+  };
+  confidence: {
+    level: "low" | "medium" | "high";
+    callerCoverage: number | null;
+    testsObserved: boolean | null;
+    rollbackObserved: boolean | null;
+    unresolvedEvidence: string[];
+  };
+  createdAt: string;
+  assessmentDigest: string;
+  extensions?: Record<string, Json>;
+}
+
+export interface RefactorResidualV1 {
+  code: string;
+  subject: string;
+  severity: Severity;
+}
+
+export interface RefactorExecutionEvidenceRefV1 {
+  kind: RefactorExecutionEvidenceKind;
+  locator: string;
+  sha256: string;
+}
+
+export interface RefactorResolutionEvidenceV1 {
+  schemaVersion: typeof REFACTOR_RESOLUTION_EVIDENCE_SCHEMA_VERSION;
+  recommendationId: string;
+  recommendationDigest: string;
+  beforeSnapshotDigest: string;
+  afterSnapshotDigest: string;
+  verifiedHeadSha: string;
+  verifiedWorktreeDigest: string;
+  expectedOutcomes: RefactorTargetOutcomeV1[];
+  observedOutcomes: RefactorObservedOutcomeV1[];
+  residuals: RefactorResidualV1[];
+  executionEvidenceRefs: RefactorExecutionEvidenceRefV1[];
+  disposition: RefactorResolutionDisposition;
+  verifiedAt: string;
+  resolutionDigest: string;
+  extensions?: Record<string, Json>;
+}
+
+export interface RecommendationV3FingerprintInputV1 {
+  category: RecommendationCategory;
+  subjectSelectorId: string;
+  practiceId: string | null;
+  payload: Record<string, Json>;
+}
+
+/**
+ * Digest exclusion rule for every helper below: drop the record's own digest
+ * field, its top-level `extensions`, and its timestamps. Nested `extensions`
+ * (for example `modules[i].extensions`) stay inside the hashed content, so a
+ * nested annotation changes the digest. The single exception is the derived
+ * `targetDelta` identity below: ArchContext fills `unresolvedTargets` after the
+ * agent authored the proposal, so `refactorProposalDigest` hashes the delta
+ * under the same exclusions as `architectureTargetDeltaInterventionId`
+ * (`interventionId`, `unresolvedTargets`, `extensions`) and the agent-authored
+ * identity survives assessment. `authoredBy` stays hashed at the top level:
+ * the no-self-authored gate must be digest-bound.
+ */
+export function refactorProposalDigest(proposal: RefactorProposalV1): string {
+  const { proposalDigest: _proposalDigest, extensions: _extensions, ...hashable } = proposal;
+  return digestJson({
+    ...hashable,
+    ...(hashable.targetDelta ? { targetDelta: authoredTargetDelta(hashable.targetDelta) } : {})
+  } as unknown as Json);
+}
+
+export function architectureTargetDeltaInterventionId(delta: ArchitectureTargetDeltaV1): string {
+  const digest = digestJson(authoredTargetDelta(delta) as unknown as Json);
+  return `intervention.${digest.slice(DIGEST_PREFIX_LENGTH, DIGEST_PREFIX_LENGTH + 16)}`;
+}
+
+export function moduleStatisticsDigest(module: ModuleStatisticsV1): string {
+  const { moduleDigest: _moduleDigest, extensions: _extensions, ...hashable } = module;
+  return digestJson(hashable as unknown as Json);
+}
+
+export function moduleStatisticsSnapshotDigest(snapshot: ModuleStatisticsSnapshotV1): string {
+  const { snapshotDigest: _snapshotDigest, createdAt: _createdAt, extensions: _extensions, ...hashable } = snapshot;
+  return digestJson(hashable as unknown as Json);
+}
+
+export function refactorAssessmentDigest(assessment: RefactorAssessmentV1): string {
+  const {
+    assessmentDigest: _assessmentDigest,
+    requestId: _requestId,
+    createdAt: _createdAt,
+    extensions: _extensions,
+    ...hashable
+  } = assessment;
+  return digestJson(hashable as unknown as Json);
+}
+
+export function refactorResolutionEvidenceDigest(evidence: RefactorResolutionEvidenceV1): string {
+  const {
+    resolutionDigest: _resolutionDigest,
+    verifiedAt: _verifiedAt,
+    extensions: _extensions,
+    ...hashable
+  } = evidence;
+  return digestJson(hashable as unknown as Json);
+}
+
+/**
+ * Canonical fingerprint input for a v3 recommendation. It deliberately drops
+ * `assessmentDigest` and `baselineSnapshotDigest` so that re-detecting the same
+ * structural fact at a new HEAD dedups against the previous recommendation and
+ * drives `relations.regressesFrom` instead of creating an unrelated record.
+ */
+export function recommendationV3FingerprintInput(
+  recommendation: Pick<RecommendationV3, "category" | "subjectSelectorId" | "practiceId" | "payload">
+): RecommendationV3FingerprintInputV1 {
+  return {
+    category: recommendation.category,
+    subjectSelectorId: recommendation.subjectSelectorId,
+    practiceId: recommendation.practiceId ?? null,
+    payload: fingerprintPayloadSubset(recommendation.category, recommendation.payload)
+  };
+}
+
+export function refactorProposalInvariantIssues(proposal: RefactorProposalV1, prefix = "proposal"): string[] {
+  const issues = [
+    ...sortedUniqueIssues(`${prefix}.scopePaths`, proposal.scopePaths),
+    ...digestIssues(`${prefix}.proposalDigest`, proposal.proposalDigest),
+    ...outcomeIssues(`${prefix}.targetOutcomes`, proposal.targetOutcomes)
+  ];
+  if (proposal.schemaVersion !== REFACTOR_PROPOSAL_SCHEMA_VERSION) issues.push(`${prefix}.schemaVersion is invalid`);
+  if (proposal.intent.trim() === "") issues.push(`${prefix}.intent must not be empty`);
+  if (proposal.scopePaths.length === 0) issues.push(`${prefix}.scopePaths must contain at least one path`);
+  for (const path of proposal.scopePaths) {
+    if (!isRepoRelativePosixPath(path)) issues.push(`${prefix}.scopePaths must be repo-relative POSIX paths: ${path}`);
+  }
+  issues.push(...refactorProposalAuthorIssues(proposal.authoredBy, prefix));
+  issues.push(...sortedUniqueIssues(`${prefix}.killList.selectorId`, proposal.killList.map((entry) => entry.selectorId)));
+  if (refactorProposalDigest(proposal) !== proposal.proposalDigest) {
+    issues.push(`${prefix}.proposalDigest must bind the authored proposal payload`);
+  }
+  if (proposal.targetDelta) issues.push(...architectureTargetDeltaInvariantIssues(proposal.targetDelta, `${prefix}.targetDelta`));
+  return issues;
+}
+
+export function architectureTargetDeltaInvariantIssues(delta: ArchitectureTargetDeltaV1, prefix = "targetDelta"): string[] {
+  const issues = [
+    ...sortedUniqueIssues(`${prefix}.unresolvedTargets`, delta.unresolvedTargets),
+    ...outcomeIssues(`${prefix}.completionCriteria`, delta.completionCriteria)
+  ];
+  if (delta.thesis.trim() === "") issues.push(`${prefix}.thesis must not be empty`);
+  if (delta.trigger.length === 0) issues.push(`${prefix}.trigger must state at least one trigger`);
+  if (delta.falsifiers.length === 0) issues.push(`${prefix}.falsifiers must state at least one falsifier`);
+  if (delta.completionCriteria.length === 0) issues.push(`${prefix}.completionCriteria must contain at least one outcome`);
+  if (delta.benefitLedger.rollbackPoint.trim() === "") issues.push(`${prefix}.benefitLedger.rollbackPoint must not be empty`);
+  if (architectureTargetDeltaInterventionId(delta) !== delta.interventionId) {
+    issues.push(`${prefix}.interventionId must be derived from the authored delta`);
+  }
+  return issues;
+}
+
+export function refactorRequestInvariantIssues(request: RefactorRequestV1, prefix = "request"): string[] {
+  const issues: string[] = [];
+  if (request.schemaVersion !== REFACTOR_REQUEST_SCHEMA_VERSION) issues.push(`${prefix}.schemaVersion is invalid`);
+  if (request.scope.kind === "node" && request.scope.nodeId.trim() === "") issues.push(`${prefix}.scope.nodeId must not be empty`);
+  if (request.scope.kind === "paths") {
+    issues.push(...sortedUniqueIssues(`${prefix}.scope.paths`, request.scope.paths));
+    if (request.scope.paths.length === 0) issues.push(`${prefix}.scope.paths must contain at least one path`);
+    for (const path of request.scope.paths) {
+      if (!isRepoRelativePosixPath(path)) issues.push(`${prefix}.scope.paths must be repo-relative POSIX paths: ${path}`);
+    }
+  }
+  if (request.proposal) issues.push(...refactorProposalInvariantIssues(request.proposal, `${prefix}.proposal`));
+  return issues;
+}
+
+/**
+ * Validates a `refactor verify` request before anything measures on its behalf.
+ *
+ * Top-level keys are closed to `REFACTOR_VERIFICATION_REQUEST_KEYS`. Every ingress rebuilds the
+ * request from the declared fields, so a typo (`expectedWorktreeDigset`) would otherwise be
+ * dropped in silence and the caller's freshness claim would simply cease to exist — the request
+ * would be answered under a weaker precondition than the one it stated.
+ *
+ * `executionEvidenceRefs` are checked under exactly the rules that bind them into the ledger:
+ * three declared keys and nothing else, a kind from the frozen vocabulary, and a bare SHA-256.
+ * An extra key would ride a cast into a record whose envelope promises no raw bodies, and the
+ * resolution-evidence validator only ever inspects `locator` and `sha256`, so it would never see
+ * it. Refusing here is the only place that key is still visible.
+ */
+export function refactorVerificationRequestInvariantIssues(
+  request: RefactorVerificationRequestV1,
+  prefix = "request"
+): string[] {
+  const issues: string[] = [];
+  const unknownKeys = Object.keys(request as unknown as Record<string, unknown>)
+    .filter((key) => !(REFACTOR_VERIFICATION_REQUEST_KEYS as readonly string[]).includes(key))
+    .sort();
+  if (unknownKeys.length > 0) issues.push(`${prefix} has unsupported key(s): ${unknownKeys.join(", ")}`);
+  if (request.schemaVersion !== REFACTOR_VERIFICATION_REQUEST_SCHEMA_VERSION) issues.push(`${prefix}.schemaVersion is invalid`);
+  if (typeof request.recommendationId !== "string" || request.recommendationId.trim() === "") {
+    issues.push(`${prefix}.recommendationId must be a non-empty string`);
+  }
+  if (request.expectedHeadSha !== undefined && !GIT_HEAD_SHA_PATTERN.test(request.expectedHeadSha)) {
+    issues.push(`${prefix}.expectedHeadSha must be a 40-hex Git commit sha`);
+  }
+  if (request.expectedWorktreeDigest !== undefined) {
+    issues.push(...digestIssues(`${prefix}.expectedWorktreeDigest`, request.expectedWorktreeDigest));
+  }
+  if (request.executionEvidenceRefs !== undefined) {
+    if (!Array.isArray(request.executionEvidenceRefs)) {
+      issues.push(`${prefix}.executionEvidenceRefs must be an array`);
+      return issues;
+    }
+    request.executionEvidenceRefs.forEach((ref, index) => {
+      const label = `${prefix}.executionEvidenceRefs[${index}]`;
+      if (!ref || typeof ref !== "object" || Array.isArray(ref)) {
+        issues.push(`${label} must be an object`);
+        return;
+      }
+      const extras = Object.keys(ref).filter((key) => key !== "kind" && key !== "locator" && key !== "sha256");
+      if (extras.length > 0) issues.push(`${label} has unsupported key(s): ${[...extras].sort().join(", ")}`);
+      if (!(REFACTOR_EXECUTION_EVIDENCE_KINDS as readonly string[]).includes(ref.kind)) {
+        issues.push(`${label}.kind must be one of ${REFACTOR_EXECUTION_EVIDENCE_KINDS.join(", ")}`);
+      }
+      if (typeof ref.locator !== "string" || ref.locator.trim() === "") {
+        issues.push(`${label}.locator must be a non-empty string`);
+      } else if (!REFACTOR_EXECUTION_EVIDENCE_LOCATOR_PATTERN.test(ref.locator)) {
+        issues.push(`${label}.locator ${REFACTOR_EXECUTION_EVIDENCE_LOCATOR_RULE}`);
+      }
+      if (typeof ref.sha256 !== "string" || !BARE_SHA256_PATTERN.test(ref.sha256)) {
+        issues.push(`${label}.sha256 must be a bare SHA-256 hex digest`);
+      }
+    });
+  }
+  return issues;
+}
+
+export function moduleStatisticsInvariantIssues(module: ModuleStatisticsV1, prefix = "module"): string[] {
+  const issues = [...digestIssues(`${prefix}.moduleDigest`, module.moduleDigest), ...digestIssues(`${prefix}.nodeDigest`, module.nodeDigest)];
+  if (module.nodeId.trim() === "") issues.push(`${prefix}.nodeId must not be empty`);
+  if (module.footprintDeclared === (module.footprint === null)) {
+    issues.push(`${prefix}.footprint must be present exactly when footprintDeclared is true`);
+  }
+  if (module.footprint) {
+    issues.push(
+      ...digestIssues(`${prefix}.footprint.sourceFilesDigest`, module.footprint.sourceFilesDigest),
+      ...nonNegativeIntegerIssues(`${prefix}.footprint.fileCount`, module.footprint.fileCount),
+      ...nonNegativeIntegerIssues(`${prefix}.footprint.lineCount`, module.footprint.lineCount)
+    );
+  }
+  if (module.dependencyGraph) {
+    const graph = module.dependencyGraph;
+    issues.push(
+      ...nonNegativeIntegerIssues(`${prefix}.dependencyGraph.internalEdgeCount`, graph.internalEdgeCount),
+      ...nonNegativeIntegerIssues(`${prefix}.dependencyGraph.inboundModuleEdges`, graph.inboundModuleEdges),
+      ...nonNegativeIntegerIssues(`${prefix}.dependencyGraph.outboundModuleEdges`, graph.outboundModuleEdges),
+      ...nonNegativeIntegerIssues(`${prefix}.dependencyGraph.fanIn`, graph.fanIn),
+      ...nonNegativeIntegerIssues(`${prefix}.dependencyGraph.fanOut`, graph.fanOut),
+      ...nonNegativeIntegerIssues(`${prefix}.dependencyGraph.cycleCount`, graph.cycleCount),
+      ...nonNegativeIntegerIssues(`${prefix}.dependencyGraph.directionViolationCount`, graph.directionViolationCount),
+      ...ratioIssues(`${prefix}.dependencyGraph.instability`, graph.instability)
+    );
+  }
+  issues.push(
+    ...nonNegativeIntegerIssues(`${prefix}.tests.testFileCount`, module.tests.testFileCount),
+    ...nonNegativeIntegerIssues(`${prefix}.tests.observedTestEdges`, module.tests.observedTestEdges),
+    ...ratioIssues(`${prefix}.tests.callerCoverage`, module.tests.callerCoverage),
+    ...nonNegativeIntegerIssues(`${prefix}.uncertainty.unresolvedImports`, module.uncertainty.unresolvedImports)
+  );
+  if (moduleStatisticsDigest(module) !== module.moduleDigest) {
+    issues.push(`${prefix}.moduleDigest must bind the measured module payload`);
+  }
+  return issues;
+}
+
+export function moduleStatisticsSnapshotInvariantIssues(snapshot: ModuleStatisticsSnapshotV1, prefix = "snapshot"): string[] {
+  const issues = [
+    ...digestIssues(`${prefix}.snapshotDigest`, snapshot.snapshotDigest),
+    ...digestIssues(`${prefix}.modelDigest`, snapshot.modelDigest),
+    ...sortedUniqueIssues(`${prefix}.codeFacts.reasonCodes`, snapshot.codeFacts.reasonCodes),
+    ...sortedUniqueIssues(`${prefix}.modules.nodeId`, snapshot.modules.map((module) => module.nodeId)),
+    ...snapshot.modules.flatMap((module, index) => moduleStatisticsInvariantIssues(module, `${prefix}.modules[${index}]`))
+  ];
+  if (snapshot.schemaVersion !== MODULE_STATISTICS_SCHEMA_VERSION) issues.push(`${prefix}.schemaVersion is invalid`);
+  if (snapshot.codeFacts.coverage === "unknown") {
+    if (!snapshot.codeFacts.truncated) issues.push(`${prefix}.codeFacts.truncated must be true when coverage is unknown`);
+    for (const [index, module] of snapshot.modules.entries()) {
+      if (module.dependencyGraph !== null) {
+        issues.push(`${prefix}.modules[${index}].dependencyGraph must be null when codeFacts.coverage is unknown`);
+      }
+    }
+  }
+  if (snapshot.codeFacts.coverage !== "unknown") {
+    if (snapshot.codeFacts.indexedWorktreeDigest === null) {
+      issues.push(`${prefix}.codeFacts.indexedWorktreeDigest must be present when coverage is ${snapshot.codeFacts.coverage}`);
+    } else if (snapshot.codeFacts.indexedWorktreeDigest !== snapshot.worktree.worktreeDigest) {
+      issues.push(`${prefix}.codeFacts.indexedWorktreeDigest must match the measured worktreeDigest`);
+    }
+  }
+  issues.push(...nonNegativeIntegerIssues(`${prefix}.codeFacts.edgeLimit`, snapshot.codeFacts.edgeLimit));
+  for (const [field, value] of Object.entries(snapshot.repositorySummary)) {
+    issues.push(...nonNegativeIntegerIssues(`${prefix}.repositorySummary.${field}`, value));
+  }
+  if (snapshot.repositorySummary.moduleCount !== snapshot.modules.length) {
+    issues.push(`${prefix}.repositorySummary.moduleCount must equal the module count`);
+  }
+  const undeclared = snapshot.modules.filter((module) => !module.footprintDeclared).length;
+  if (snapshot.repositorySummary.undeclaredFootprintNodeCount !== undeclared) {
+    issues.push(`${prefix}.repositorySummary.undeclaredFootprintNodeCount must equal the undeclared footprint module count`);
+  }
+  if (moduleStatisticsSnapshotDigest(snapshot) !== snapshot.snapshotDigest) {
+    issues.push(`${prefix}.snapshotDigest must bind the measured snapshot payload`);
+  }
+  return issues;
+}
+
+export function refactorAssessmentInvariantIssues(assessment: RefactorAssessmentV1, prefix = "assessment"): string[] {
+  const issues = [
+    ...digestIssues(`${prefix}.assessmentDigest`, assessment.assessmentDigest),
+    ...digestIssues(`${prefix}.statisticsSnapshotDigest`, assessment.statisticsSnapshotDigest),
+    ...digestIssues(`${prefix}.modelDigest`, assessment.modelDigest),
+    ...digestIssues(`${prefix}.codeFactsDigest`, assessment.codeFactsDigest),
+    ...sortedUniqueIssues(`${prefix}.affectedNodeIds`, assessment.affectedNodeIds),
+    ...sortedUniqueIssues(`${prefix}.scaleReasonCodes`, assessment.scaleReasonCodes),
+    ...sortedUniqueIssues(`${prefix}.majorChangeReasons`, assessment.majorChangeReasons)
+  ];
+  if (assessment.schemaVersion !== REFACTOR_ASSESSMENT_SCHEMA_VERSION) issues.push(`${prefix}.schemaVersion is invalid`);
+  if (assessment.proposalDigest !== null) issues.push(...digestIssues(`${prefix}.proposalDigest`, assessment.proposalDigest));
+  if ((assessment.scale === null) !== (assessment.proposalDigest === null)) {
+    issues.push(`${prefix}.scale must be null exactly when proposalDigest is null`);
+  }
+  if (assessment.scale === "architecture" && assessment.majorChangeReasons.length === 0) {
+    issues.push(`${prefix}.architecture scale requires at least one majorChangeReason`);
+  }
+  const allowedReasons = new Set<string>(ARCHITECTURE_MAJOR_CHANGE_REASON_CODES);
+  for (const reason of assessment.majorChangeReasons) {
+    if (!allowedReasons.has(reason)) issues.push(`${prefix}.majorChangeReasons contains unsupported reason: ${reason}`);
+  }
+  for (const [index, observation] of assessment.observations.entries()) {
+    if (observation.subjectSelectorId.trim() === "") issues.push(`${prefix}.observations[${index}].subjectSelectorId must not be empty`);
+    issues.push(...sortedUniqueIssues(`${prefix}.observations[${index}].signalIds`, observation.signalIds));
+  }
+  issues.push(...ratioIssues(`${prefix}.confidence.callerCoverage`, assessment.confidence.callerCoverage));
+  if (!Number.isInteger(assessment.pressure.score) || assessment.pressure.score < 0 || assessment.pressure.score > 100) {
+    issues.push(`${prefix}.pressure.score must be an integer between 0 and 100`);
+  }
+  issues.push(...sortedUniqueIssues(`${prefix}.pressure.signalIds`, assessment.pressure.signalIds));
+  if (refactorAssessmentDigest(assessment) !== assessment.assessmentDigest) {
+    issues.push(`${prefix}.assessmentDigest must bind the assessed payload`);
+  }
+  return issues;
+}
+
+export function refactorResolutionEvidenceInvariantIssues(
+  evidence: RefactorResolutionEvidenceV1,
+  prefix = "resolutionEvidence"
+): string[] {
+  const issues = [
+    ...digestIssues(`${prefix}.resolutionDigest`, evidence.resolutionDigest),
+    ...digestIssues(`${prefix}.recommendationDigest`, evidence.recommendationDigest),
+    ...digestIssues(`${prefix}.beforeSnapshotDigest`, evidence.beforeSnapshotDigest),
+    ...digestIssues(`${prefix}.afterSnapshotDigest`, evidence.afterSnapshotDigest),
+    ...outcomeIssues(`${prefix}.expectedOutcomes`, evidence.expectedOutcomes),
+    ...sortedUniqueIssues(`${prefix}.observedOutcomes.outcomeId`, evidence.observedOutcomes.map((outcome) => outcome.outcomeId))
+  ];
+  if (evidence.schemaVersion !== REFACTOR_RESOLUTION_EVIDENCE_SCHEMA_VERSION) issues.push(`${prefix}.schemaVersion is invalid`);
+  const observedById = new Map(evidence.observedOutcomes.map((outcome) => [outcome.outcomeId, outcome]));
+  for (const expected of evidence.expectedOutcomes) {
+    if (!observedById.has(expected.outcomeId)) issues.push(`${prefix}.observedOutcomes is missing outcome ${expected.outcomeId}`);
+  }
+  for (const ref of evidence.executionEvidenceRefs) {
+    if (!/^[a-f0-9]{64}$/.test(ref.sha256)) issues.push(`${prefix}.executionEvidenceRefs.sha256 must be a bare SHA-256 hex digest`);
+    if (ref.locator.trim() === "") issues.push(`${prefix}.executionEvidenceRefs.locator must not be empty`);
+  }
+  for (const expected of evidence.expectedOutcomes) {
+    const observed = observedById.get(expected.outcomeId);
+    if (!observed) continue;
+    const recomputed = outcomeSatisfied(expected, observed.observedValue);
+    if (observed.satisfied !== recomputed) {
+      issues.push(
+        `${prefix}.observedOutcomes ${expected.outcomeId} claims satisfied=${observed.satisfied} but ${expected.metric} ${expected.operator} ${expected.value} against ${observed.observedValue} is ${recomputed}`
+      );
+    }
+  }
+  if (evidence.disposition !== "stale") {
+    const required = evidence.expectedOutcomes.filter((outcome) => outcome.required);
+    const observedRequired = required
+      .map((outcome) => {
+        const observed = observedById.get(outcome.outcomeId);
+        return observed ? { outcome, satisfied: outcomeSatisfied(outcome, observed.observedValue) } : undefined;
+      })
+      .filter(isPresent);
+    const regressed = evidence.observedOutcomes.some((outcome) => outcome.direction === "regressed");
+    const satisfiedCount = observedRequired.filter((entry) => entry.satisfied).length;
+    if (regressed && evidence.disposition !== "regressed") {
+      issues.push(`${prefix}.disposition must be regressed when any observed outcome regressed`);
+    }
+    if (!regressed && required.length > 0) {
+      if (satisfiedCount === required.length && evidence.disposition !== "resolved") {
+        issues.push(`${prefix}.disposition must be resolved when every required outcome is satisfied`);
+      }
+      if (satisfiedCount === 0 && evidence.disposition !== "not_improved") {
+        issues.push(`${prefix}.disposition must be not_improved when no required outcome is satisfied`);
+      }
+      if (satisfiedCount > 0 && satisfiedCount < required.length && evidence.disposition !== "partially_resolved") {
+        issues.push(`${prefix}.disposition must be partially_resolved when only some required outcomes are satisfied`);
+      }
+    }
+  }
+  if (refactorResolutionEvidenceDigest(evidence) !== evidence.resolutionDigest) {
+    issues.push(`${prefix}.resolutionDigest must bind the verified payload`);
+  }
+  return issues;
+}
+
+/**
+ * Guards the one invariant the `RecommendationV3` union cannot enforce at
+ * runtime: that `payload` matches `category`. A non-object or mismatched
+ * payload yields issues instead of throwing. Every other field is trusted to
+ * match its declared type; structural validation of untrusted ingress is the
+ * job of the JSON Schemas, not of this validator.
+ *
+ * The fingerprint hash itself stays owned by `recommendationFingerprint()` in
+ * `packages/core/recommendation-engine`: contracts must not import core, and
+ * re-deriving the hash here would fork it into two definitions. This validator
+ * therefore checks the fingerprint's shape, not its value.
+ */
+export function recommendationV3InvariantIssues(recommendation: RecommendationV3, prefix = "recommendation"): string[] {
+  const issues = [
+    ...sortedUniqueIssues(`${prefix}.evidenceBindingIds`, recommendation.evidenceBindingIds),
+    ...digestIssues(`${prefix}.fingerprint`, recommendation.fingerprint)
+  ];
+  if (recommendation.schemaVersion !== RECOMMENDATION_V3_SCHEMA_VERSION) issues.push(`${prefix}.schemaVersion is invalid`);
+  if (!(RECOMMENDATION_CATEGORIES as readonly string[]).includes(recommendation.category)) {
+    issues.push(`${prefix}.category is unsupported: ${recommendation.category}`);
+    return issues;
+  }
+  if (recommendation.subjectSelectorId.trim() === "") issues.push(`${prefix}.subjectSelectorId must not be empty`);
+  if (recommendation.authoredBy.id.trim() === "") issues.push(`${prefix}.authoredBy.id must not be empty`);
+  const shapeIssues = recommendationPayloadShapeIssues(recommendation.category, recommendation.payload, prefix);
+  issues.push(...shapeIssues);
+  if (recommendation.category === "practice" && !recommendation.practiceId) {
+    issues.push(`${prefix}.practiceId is required for practice recommendations`);
+  }
+  if (recommendation.category === "structural_observation") {
+    if (recommendation.authoredBy.source !== "daemon") {
+      issues.push(`${prefix}.structural_observation must be authored by the daemon`);
+    }
+    if (recommendation.authoredBy.kind !== "daemon") {
+      issues.push(`${prefix}.structural_observation must be authored by the daemon actor kind`);
+    }
+    if (recommendation.enforcement !== "advisory") {
+      issues.push(`${prefix}.structural_observation enforcement must be advisory`);
+    }
+  }
+  if (recommendation.category === "refactor_proposal") {
+    if (!isRefactorProposalAuthorSource(recommendation.authoredBy.source)) {
+      issues.push(`${prefix}.refactor_proposal must not be authored by ${recommendation.authoredBy.source}`);
+    }
+    issues.push(...refactorProposalAuthorIssues(recommendation.authoredBy, prefix));
+    if (shapeIssues.length === 0) {
+      const payload = recommendation.payload as RefactorProposalPayloadV1;
+      const expected = payload.scale === "architecture" ? "complete" : "checkpoint";
+      if (recommendation.enforcement !== expected) {
+        issues.push(`${prefix}.refactor_proposal with scale ${payload.scale} requires ${expected} enforcement`);
+      }
+      issues.push(
+        ...digestIssues(`${prefix}.payload.proposalDigest`, payload.proposalDigest),
+        ...sortedUniqueIssues(`${prefix}.payload.affectedNodeIds`, payload.affectedNodeIds),
+        ...sortedUniqueIssues(`${prefix}.payload.majorChangeReasons`, payload.majorChangeReasons)
+      );
+    }
+  }
+  return issues;
+}
+
+export function refactorScanInvariantIssues(input: {
+  snapshot: ModuleStatisticsSnapshotV1;
+  assessment: RefactorAssessmentV1;
+  proposal?: RefactorProposalV1;
+}): string[] {
+  const issues = [
+    ...moduleStatisticsSnapshotInvariantIssues(input.snapshot),
+    ...refactorAssessmentInvariantIssues(input.assessment),
+    ...(input.proposal ? refactorProposalInvariantIssues(input.proposal) : [])
+  ];
+  if (input.assessment.statisticsSnapshotDigest !== input.snapshot.snapshotDigest) {
+    issues.push("assessment.statisticsSnapshotDigest must reference the measured snapshot");
+  }
+  if (input.assessment.modelDigest !== input.snapshot.modelDigest) {
+    issues.push("assessment.modelDigest must match the snapshot modelDigest");
+  }
+  const proposalDigest = input.proposal ? input.proposal.proposalDigest : null;
+  if (input.assessment.proposalDigest !== proposalDigest) {
+    issues.push("assessment.proposalDigest must reference the submitted proposal");
+  }
+  const unresolved = input.proposal?.targetDelta?.unresolvedTargets ?? [];
+  if (unresolved.length > 0 && input.assessment.scale !== "insufficient_evidence") {
+    issues.push("assessment.scale must be insufficient_evidence while targetDelta.unresolvedTargets is non-empty");
+  }
+  if (unresolved.length > 0 && !input.assessment.scaleReasonCodes.includes("target-unresolved")) {
+    issues.push("assessment.scaleReasonCodes must include target-unresolved while targets stay unresolved");
+  }
+  return issues;
+}
+
+export function refactorVerifyInvariantIssues(
+  afterSnapshot: ModuleStatisticsSnapshotV1,
+  evidence: RefactorResolutionEvidenceV1
+): string[] {
+  const issues = [
+    ...moduleStatisticsSnapshotInvariantIssues(afterSnapshot, "afterSnapshot"),
+    ...refactorResolutionEvidenceInvariantIssues(evidence)
+  ];
+  if (evidence.afterSnapshotDigest !== afterSnapshot.snapshotDigest) {
+    issues.push("resolutionEvidence.afterSnapshotDigest must reference the re-measured snapshot");
+  }
+  if (evidence.verifiedHeadSha !== afterSnapshot.worktree.headSha) {
+    issues.push("resolutionEvidence.verifiedHeadSha must match the re-measured worktree HEAD");
+  }
+  if (evidence.verifiedWorktreeDigest !== afterSnapshot.worktree.worktreeDigest) {
+    issues.push("resolutionEvidence.verifiedWorktreeDigest must match the re-measured worktree digest");
+  }
+  if (afterSnapshot.codeFacts.coverage !== "complete" && evidence.disposition === "resolved") {
+    issues.push("resolutionEvidence.disposition must not be resolved while after-snapshot coverage is incomplete");
+  }
+  const indexCoversWorktree =
+    afterSnapshot.codeFacts.indexedWorktreeDigest !== null
+    && afterSnapshot.codeFacts.indexedWorktreeDigest === afterSnapshot.worktree.worktreeDigest;
+  if (!indexCoversWorktree && evidence.disposition === "resolved") {
+    issues.push("resolutionEvidence.disposition must not be resolved while the after-snapshot index does not cover the verified worktree");
+  }
+  return issues;
+}
+
+function authoredTargetDelta(delta: ArchitectureTargetDeltaV1): Omit<ArchitectureTargetDeltaV1, "interventionId" | "unresolvedTargets" | "extensions"> {
+  const {
+    interventionId: _interventionId,
+    unresolvedTargets: _unresolvedTargets,
+    extensions: _extensions,
+    ...authored
+  } = delta;
+  return authored;
+}
+
+function isRefactorProposalAuthorSource(source: string): source is RefactorProposalAuthorSource {
+  return (REFACTOR_PROPOSAL_AUTHOR_SOURCES as readonly string[]).includes(source);
+}
+
+function isRefactorProposalAuthorKind(kind: string): kind is RefactorProposalAuthorKind {
+  return (REFACTOR_PROPOSAL_AUTHOR_KINDS as readonly string[]).includes(kind);
+}
+
+function refactorProposalAuthorIssues(author: RecommendationAuthorV1, prefix: string): string[] {
+  const issues: string[] = [];
+  if (author.id.trim() === "") issues.push(`${prefix}.authoredBy.id must not be empty`);
+  if (!isRefactorProposalAuthorSource(author.source)) {
+    issues.push(`${prefix}.authoredBy.source must not be ${author.source}; refactor proposals are agent or human authored`);
+  }
+  if (!isRefactorProposalAuthorKind(author.kind)) {
+    issues.push(`${prefix}.authoredBy.kind must not be ${author.kind}; refactor proposals are agent or human authored`);
+    return issues;
+  }
+  if (isRefactorProposalAuthorSource(author.source) && !REFACTOR_PROPOSAL_AUTHOR_PAIRS[author.kind].includes(author.source)) {
+    issues.push(`${prefix}.authoredBy.kind ${author.kind} is not compatible with source ${author.source}`);
+  }
+  return issues;
+}
+
+function outcomeSatisfied(expected: RefactorTargetOutcomeV1, observedValue: number | null): boolean {
+  switch (expected.operator) {
+    case "absent":
+      return observedValue === null || observedValue === 0;
+    case "present":
+      return observedValue !== null && observedValue !== 0;
+    case "equals":
+      return observedValue !== null && expected.value !== null && observedValue === expected.value;
+    case "greater_than":
+      return observedValue !== null && expected.value !== null && observedValue > expected.value;
+    case "less_than":
+      return observedValue !== null && expected.value !== null && observedValue < expected.value;
+  }
+}
+
+function recommendationPayloadShapeIssues(
+  category: RecommendationCategory,
+  payload: RecommendationPayloadV1,
+  prefix: string
+): string[] {
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+    return [`${prefix}.payload must be an object for category ${category}`];
+  }
+  const record = payload as unknown as Record<string, unknown>;
+  const required = REQUIRED_PAYLOAD_FIELDS[category];
+  const missing = required.filter((field) => !(field in record));
+  return missing.length === 0 ? [] : [`${prefix}.payload does not match category ${category}; missing ${missing.sort().join(", ")}`];
+}
+
+function nonNegativeIntegerIssues(label: string, value: number | null): string[] {
+  if (value === null) return [];
+  return Number.isInteger(value) && value >= 0 ? [] : [`${label} must be a non-negative integer`];
+}
+
+function ratioIssues(label: string, value: number | null): string[] {
+  if (value === null) return [];
+  return Number.isFinite(value) && value >= 0 && value <= 1 ? [] : [`${label} must be a ratio between 0 and 1`];
+}
+
+const REQUIRED_PAYLOAD_FIELDS: Readonly<Record<RecommendationCategory, readonly string[]>> = {
+  practice: ["baselineDigest", "practiceId"],
+  refactor_proposal: [
+    "affectedNodeIds",
+    "assessmentDigest",
+    "baselineSnapshotDigest",
+    "killList",
+    "majorChangeReasons",
+    "proposalDigest",
+    "scale",
+    "targetOutcomes"
+  ],
+  structural_observation: ["affectedNodeIds", "assessmentDigest", "baselineSnapshotDigest", "derivedOutcomes", "kind"]
+};
+
+function fingerprintPayloadSubset(category: RecommendationCategory, payload: RecommendationPayloadV1): Record<string, Json> {
+  if (category === "practice") {
+    return { baselineDigest: (payload as PracticeRecommendationPayloadV1).baselineDigest };
+  }
+  if (category === "structural_observation") {
+    const observation = payload as StructuralObservationPayloadV1;
+    return { kind: observation.kind, affectedNodeIds: [...observation.affectedNodeIds].sort() };
+  }
+  const proposal = payload as RefactorProposalPayloadV1;
+  return {
+    proposalDigest: proposal.proposalDigest,
+    scale: proposal.scale,
+    affectedNodeIds: [...proposal.affectedNodeIds].sort(),
+    majorChangeReasons: [...proposal.majorChangeReasons].sort()
+  };
+}
+
+function outcomeIssues(label: string, outcomes: readonly RefactorTargetOutcomeV1[]): string[] {
+  const issues = sortedUniqueIssues(`${label}.outcomeId`, outcomes.map((outcome) => outcome.outcomeId));
+  for (const outcome of outcomes) {
+    const valueless = outcome.operator === "absent" || outcome.operator === "present";
+    if (valueless && outcome.value !== null) issues.push(`${label} operator ${outcome.operator} must not carry a value`);
+    if (!valueless && outcome.value === null) issues.push(`${label} operator ${outcome.operator} requires a value`);
+    if (outcome.metric.trim() === "") issues.push(`${label} metric must not be empty`);
+  }
+  return issues;
+}
+
+function digestIssues(label: string, value: string): string[] {
+  return SHA256_DIGEST_PATTERN.test(value) ? [] : [`${label} must be a sha256:<64-hex> digest`];
+}
+
+function isPresent<T>(value: T | undefined): value is T {
+  return value !== undefined;
+}
+
+function sortedUniqueIssues(label: string, values: readonly string[]): string[] {
+  const expected = [...new Set(values)].sort();
+  return expected.length === values.length && expected.every((value, index) => value === values[index])
+    ? []
+    : [`${label} must be sorted and unique`];
+}

package/src/schema.ts

@@ -28,7 +28,11 @@ export type ArchContextErrorCode =
   | "AC_USER_CONFIRMATION_REQUIRED"
   | "AC_ENTITLEMENT_REQUIRED"
   | "AC_ATTESTATION_REJECTED"
-  | "AC_TUNNEL_SCOPE_DENIED";
+  | "AC_TUNNEL_SCOPE_DENIED"
+  | "AC_MODEL_ADOPTION_REQUIRED"
+  | "AC_REFACTOR_STALE"
+  | "AC_REFACTOR_EVIDENCE_REQUIRED"
+  | "AC_REFACTOR_PROPOSAL_UNAUTHORED";
 
 export interface ArchContextError {
   code: ArchContextErrorCode;
@@ -65,7 +69,11 @@ export const ERROR_CATALOG: Record<ArchContextErrorCode, Omit<ArchContextError,
   AC_USER_CONFIRMATION_REQUIRED: { code: "AC_USER_CONFIRMATION_REQUIRED", severity: "warning", retryable: true, action: "show-human-decision" },
   AC_ENTITLEMENT_REQUIRED: { code: "AC_ENTITLEMENT_REQUIRED", severity: "error", retryable: false, action: "login-or-subscribe" },
   AC_ATTESTATION_REJECTED: { code: "AC_ATTESTATION_REJECTED", severity: "error", retryable: false, action: "review-again" },
-  AC_TUNNEL_SCOPE_DENIED: { code: "AC_TUNNEL_SCOPE_DENIED", severity: "error", retryable: false, action: "reduce-scope" }
+  AC_TUNNEL_SCOPE_DENIED: { code: "AC_TUNNEL_SCOPE_DENIED", severity: "error", retryable: false, action: "reduce-scope" },
+  AC_MODEL_ADOPTION_REQUIRED: { code: "AC_MODEL_ADOPTION_REQUIRED", severity: "error", retryable: false, action: "adopt-architecture-model" },
+  AC_REFACTOR_STALE: { code: "AC_REFACTOR_STALE", severity: "warning", retryable: true, action: "rerun-refactor-scan" },
+  AC_REFACTOR_EVIDENCE_REQUIRED: { code: "AC_REFACTOR_EVIDENCE_REQUIRED", severity: "error", retryable: false, action: "run-refactor-verify" },
+  AC_REFACTOR_PROPOSAL_UNAUTHORED: { code: "AC_REFACTOR_PROPOSAL_UNAUTHORED", severity: "error", retryable: false, action: "attach-authoring-actor" }
 };
 
 export function okEnvelope<T extends Json>(requestId: string, data: T): JsonEnvelope<T> {