archctx-contracts 0.6.3 → 0.7.1

package/src/refactor.ts

@@ -42,6 +42,7 @@ export const REFACTOR_VERIFICATION_REQUEST_KEYS = [
   "executionEvidenceRefs",
   "expectedHeadSha",
   "expectedWorktreeDigest",
+  "importNodeLimit",
   "recommendationId",
   "schemaVersion"
 ] as const;
@@ -62,6 +63,7 @@ export const REFACTOR_SCALES = [
 ] as const;
 export const REFACTOR_SCALE_REASON_CODES = [
   "caller-coverage-unknown",
+  "code-facts-import-limit",
   "code-facts-missing",
   "code-facts-truncated",
   "major-change-detected",
@@ -198,6 +200,11 @@ export interface RefactorRequestV1 {
   expectedHeadSha?: string;
   expectedWorktreeDigest?: string;
   task?: string;
+  /**
+   * The most CodeGraph import nodes the scan reads. Omitted means the runtime default. A larger
+   * index gives partial coverage with `code-facts-import-limit`, never `code-facts-truncated`.
+   */
+  importNodeLimit?: number;
 }
 
 /**
@@ -216,6 +223,11 @@ export interface RefactorVerificationRequestV1 {
   expectedHeadSha?: string;
   expectedWorktreeDigest?: string;
   executionEvidenceRefs?: RefactorExecutionEvidenceRefV1[];
+  /**
+   * The most CodeGraph import nodes the re-measure reads. Omitted means the limit the recorded
+   * baseline snapshot was measured with, so BEFORE and AFTER read the same import population.
+   */
+  importNodeLimit?: number;
 }
 
 export interface ModuleStatisticsV1 {
@@ -281,8 +293,18 @@ export interface ModuleStatisticsSnapshotV1 {
     binaryDigest: string;
     indexedWorktreeDigest: string | null;
     coverage: EvidenceCoverageLevelV2;
+    /**
+     * True only when the read is shorter than the population the index reported. A read cut by
+     * `edgeLimit` is not truncated: it reports `code-facts-import-limit` instead.
+     */
     truncated: boolean;
+    /** The import-node read limit the scan applied. */
     edgeLimit: number | null;
+    /**
+     * Import nodes the index reported, or `null` when no index gave a count. Absent on snapshots
+     * recorded before the field existed.
+     */
+    importNodeCount?: number | null;
     reasonCodes: RefactorScaleReasonCode[];
   };
   modules: ModuleStatisticsV1[];
@@ -303,11 +325,100 @@ export interface ModuleStatisticsSnapshotV1 {
   extensions?: Record<string, Json>;
 }
 
+/**
+ * The fixed per-observation bound on sampled evidence entries (edges, violations, paths,
+ * unresolved imports). It bounds entry *count* only: a path or a specifier has no fixed byte
+ * size, so this bound alone does not keep a recording event under the ledger's persisted-JSON
+ * ceiling. The recording planner enforces that separately, by measuring the event it would
+ * persist and shrinking every sample to one shared smaller limit until the event fits.
+ */
+export const REFACTOR_OBSERVATION_EVIDENCE_LIMIT = 20;
+/**
+ * The fixed bound on every id list inside evidence (`memberNodeIds`, `constraintIds`,
+ * `candidateOwnerNodeIds`). Each list is the sorted prefix of its population and carries the true
+ * size beside it (`metrics.memberCount`, `constraintCount`, `candidateOwnerCount`). It is no
+ * smaller than `REFACTOR_OBSERVATION_EVIDENCE_LIMIT`, so the constraints named by a violation
+ * sample — the smallest ids, since violations sort by constraint first — are always listed.
+ */
+export const REFACTOR_EVIDENCE_ID_LIST_LIMIT = 32;
+/** An import specifier is a module reference, not code: one line, bounded like a locator. */
+export const REFACTOR_EVIDENCE_SPECIFIER_MAX_LENGTH = 512;
+
+/**
+ * One observed file-level import edge, as bounded metadata only: two repo-relative paths, the
+ * line the import sits on, the specifier verbatim and the owning nodes. Never a source body.
+ * `toPath` carries no line: an import names a module, not a position inside it.
+ */
+export interface RefactorEvidenceImportEdgeV1 {
+  fromPath: string;
+  /** 1-based line of the import statement in `fromPath`; `null` when the code index reported none. */
+  fromLine: number | null;
+  toPath: string;
+  specifier: string;
+  fromNodeId: string;
+  toNodeId: string;
+}
+
+export interface RefactorEvidenceDirectionViolationV1 extends RefactorEvidenceImportEdgeV1 {
+  constraintId: string;
+}
+
+export interface RefactorEvidencePathV1 {
+  path: string;
+  /**
+   * Declared nodes that bear on this path, per kind: for `ownership-ambiguous` every node that
+   * claims it; for `unowned-paths` the nodes that own another tracked file in the same directory;
+   * for `undeclared-footprint` the nodes that currently own the entrypoint path the node declares.
+   */
+  candidateOwnerNodeIds: string[];
+  /** How many candidate owners exist; `candidateOwnerNodeIds` is its sorted, bounded prefix. */
+  candidateOwnerCount: number;
+}
+
+export interface RefactorEvidenceUnresolvedImportV1 {
+  fromPath: string;
+  fromLine: number | null;
+  specifier: string;
+}
+
+/** A bounded sample: `totalCount` is the population, `truncated` says the list is a prefix of it. */
+interface RefactorEvidenceSampleV1 {
+  totalCount: number;
+  truncated: boolean;
+}
+
+/**
+ * Typed evidence per observation kind: the concrete items behind the observation's metrics, so a
+ * reader can see *why* it exists without re-running the measurement. Samples are sorted, bounded
+ * by `REFACTOR_OBSERVATION_EVIDENCE_LIMIT`, and derived from the same measurement as the snapshot;
+ * id lists are sorted prefixes bounded by `REFACTOR_EVIDENCE_ID_LIST_LIMIT`.
+ *
+ * `memberNodeIds` is the prefix of the component's members; its population is the observation's
+ * `metrics.memberCount`.
+ */
+export type RefactorObservationEvidenceV1 =
+  | ({ kind: "cycle"; memberNodeIds: string[]; edges: RefactorEvidenceImportEdgeV1[] } & RefactorEvidenceSampleV1)
+  | ({
+    kind: "direction-violation";
+    constraintIds: string[];
+    /** How many distinct constraints the module violates; `constraintIds` is its bounded prefix. */
+    constraintCount: number;
+    violations: RefactorEvidenceDirectionViolationV1[];
+  } & RefactorEvidenceSampleV1)
+  | ({ kind: "ownership-ambiguous" | "undeclared-footprint" | "unowned-paths"; paths: RefactorEvidencePathV1[] } & RefactorEvidenceSampleV1)
+  | ({
+    kind: "evidence-gap";
+    coverage: EvidenceCoverageLevelV2;
+    reasonCodes: RefactorScaleReasonCode[];
+    unresolvedImports: RefactorEvidenceUnresolvedImportV1[];
+  } & RefactorEvidenceSampleV1);
+
 export interface RefactorObservationV1 {
   kind: RefactorObservationKind;
   subjectSelectorId: string;
   signalIds: string[];
   metrics: Record<string, number | null>;
+  evidence: RefactorObservationEvidenceV1;
 }
 
 export interface RefactorAssessmentV1 {
@@ -505,6 +616,9 @@ export function refactorRequestInvariantIssues(request: RefactorRequestV1, prefi
     }
   }
   if (request.proposal) issues.push(...refactorProposalInvariantIssues(request.proposal, `${prefix}.proposal`));
+  if (request.importNodeLimit !== undefined && !(Number.isInteger(request.importNodeLimit) && request.importNodeLimit >= 1)) {
+    issues.push(`${prefix}.importNodeLimit must be a positive integer`);
+  }
   return issues;
 }
 
@@ -541,6 +655,9 @@ export function refactorVerificationRequestInvariantIssues(
   if (request.expectedWorktreeDigest !== undefined) {
     issues.push(...digestIssues(`${prefix}.expectedWorktreeDigest`, request.expectedWorktreeDigest));
   }
+  if (request.importNodeLimit !== undefined && !(Number.isInteger(request.importNodeLimit) && request.importNodeLimit >= 1)) {
+    issues.push(`${prefix}.importNodeLimit must be a positive integer`);
+  }
   if (request.executionEvidenceRefs !== undefined) {
     if (!Array.isArray(request.executionEvidenceRefs)) {
       issues.push(`${prefix}.executionEvidenceRefs must be an array`);
@@ -633,6 +750,15 @@ export function moduleStatisticsSnapshotInvariantIssues(snapshot: ModuleStatisti
     }
   }
   issues.push(...nonNegativeIntegerIssues(`${prefix}.codeFacts.edgeLimit`, snapshot.codeFacts.edgeLimit));
+  const importNodeCount = snapshot.codeFacts.importNodeCount ?? null;
+  issues.push(...nonNegativeIntegerIssues(`${prefix}.codeFacts.importNodeCount`, importNodeCount));
+  if (snapshot.codeFacts.reasonCodes.includes("code-facts-import-limit")) {
+    const { edgeLimit } = snapshot.codeFacts;
+    if (snapshot.codeFacts.coverage !== "partial") issues.push(`${prefix}.codeFacts.coverage must be partial when the import limit was reached`);
+    if (edgeLimit === null || (importNodeCount !== null && importNodeCount <= edgeLimit)) {
+      issues.push(`${prefix}.codeFacts.importNodeCount must exceed edgeLimit when the import limit was reached`);
+    }
+  }
   for (const [field, value] of Object.entries(snapshot.repositorySummary)) {
     issues.push(...nonNegativeIntegerIssues(`${prefix}.repositorySummary.${field}`, value));
   }
@@ -674,6 +800,7 @@ export function refactorAssessmentInvariantIssues(assessment: RefactorAssessment
   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(...refactorObservationEvidenceIssues(observation, `${prefix}.observations[${index}]`));
   }
   issues.push(...ratioIssues(`${prefix}.confidence.callerCoverage`, assessment.confidence.callerCoverage));
   if (!Number.isInteger(assessment.pressure.score) || assessment.pressure.score < 0 || assessment.pressure.score > 100) {
@@ -686,6 +813,136 @@ export function refactorAssessmentInvariantIssues(assessment: RefactorAssessment
   return issues;
 }
 
+/** The one ordering for evidence edges: path, line, target, specifier, then owners. */
+export function compareRefactorEvidenceImportEdges(left: RefactorEvidenceImportEdgeV1, right: RefactorEvidenceImportEdgeV1): number {
+  return compareText(left.fromPath, right.fromPath)
+    || compareLine(left.fromLine, right.fromLine)
+    || compareText(left.toPath, right.toPath)
+    || compareText(left.specifier, right.specifier)
+    || compareText(left.fromNodeId, right.fromNodeId)
+    || compareText(left.toNodeId, right.toNodeId);
+}
+
+export function compareRefactorEvidenceDirectionViolations(
+  left: RefactorEvidenceDirectionViolationV1,
+  right: RefactorEvidenceDirectionViolationV1
+): number {
+  return compareText(left.constraintId, right.constraintId) || compareRefactorEvidenceImportEdges(left, right);
+}
+
+export function compareRefactorEvidenceUnresolvedImports(
+  left: RefactorEvidenceUnresolvedImportV1,
+  right: RefactorEvidenceUnresolvedImportV1
+): number {
+  return compareText(left.fromPath, right.fromPath)
+    || compareLine(left.fromLine, right.fromLine)
+    || compareText(left.specifier, right.specifier);
+}
+
+/**
+ * Validates one observation's evidence against the observation it explains: matching kind, the
+ * fixed sample and id-list bounds, an honest `truncated` flag and id-list counts, the canonical
+ * order, repo-relative paths, positive lines and one-line bounded specifiers. Where a metric counts exactly the evidence population,
+ * `totalCount` must equal it, so the sample can never describe a different measurement.
+ */
+export function refactorObservationEvidenceIssues(observation: RefactorObservationV1, prefix = "observation"): string[] {
+  const evidence = observation.evidence as RefactorObservationEvidenceV1 | undefined;
+  const label = `${prefix}.evidence`;
+  if (!evidence || typeof evidence !== "object") return [`${label} is required`];
+  if (evidence.kind !== observation.kind) return [`${label}.kind must equal the observation kind ${observation.kind}`];
+  const issues: string[] = [];
+  const sample = (entries: readonly unknown[], field: string): void => {
+    if (entries.length > REFACTOR_OBSERVATION_EVIDENCE_LIMIT) {
+      issues.push(`${label}.${field} must hold at most ${REFACTOR_OBSERVATION_EVIDENCE_LIMIT} entries`);
+    }
+    if (!Number.isInteger(evidence.totalCount) || evidence.totalCount < entries.length) {
+      issues.push(`${label}.totalCount must be an integer no smaller than the ${field} length`);
+    }
+    if (evidence.truncated !== evidence.totalCount > entries.length) {
+      issues.push(`${label}.truncated must be true exactly when totalCount exceeds the ${field} length`);
+    }
+  };
+  const ordered = <T>(entries: readonly T[], field: string, compare: (left: T, right: T) => number): void => {
+    for (let index = 1; index < entries.length; index += 1) {
+      if (compare(entries[index - 1]!, entries[index]!) >= 0) {
+        issues.push(`${label}.${field} must be sorted and unique`);
+        return;
+      }
+    }
+  };
+  const edgeIssues = (edge: RefactorEvidenceImportEdgeV1, field: string): void => {
+    issues.push(...repoPathIssues(`${label}.${field}.fromPath`, edge.fromPath), ...repoPathIssues(`${label}.${field}.toPath`, edge.toPath));
+    issues.push(...lineIssues(`${label}.${field}.fromLine`, edge.fromLine), ...specifierIssues(`${label}.${field}.specifier`, edge.specifier));
+    if (edge.fromNodeId.trim() === "" || edge.toNodeId.trim() === "") issues.push(`${label}.${field} node ids must not be empty`);
+  };
+  // An id list is the sorted prefix of a population of `count`: exactly min(count, limit) long.
+  const idList = (ids: readonly string[], count: unknown, field: string, countField: string): void => {
+    issues.push(...sortedUniqueIssues(`${label}.${field}`, ids));
+    if (!Number.isInteger(count) || (count as number) < 0) {
+      issues.push(`${label}.${countField} must be a non-negative integer`);
+    } else if (ids.length !== Math.min(count as number, REFACTOR_EVIDENCE_ID_LIST_LIMIT)) {
+      issues.push(`${label}.${field} must hold min(${countField}, ${REFACTOR_EVIDENCE_ID_LIST_LIMIT}) entries`);
+    }
+  };
+  switch (evidence.kind) {
+    case "cycle": {
+      sample(evidence.edges, "edges");
+      ordered(evidence.edges, "edges", compareRefactorEvidenceImportEdges);
+      idList(evidence.memberNodeIds, observation.metrics.memberCount, "memberNodeIds", "metrics.memberCount");
+      // Membership is checkable only against the complete member list.
+      const complete = evidence.memberNodeIds.length === observation.metrics.memberCount;
+      for (const edge of evidence.edges) {
+        edgeIssues(edge, "edges");
+        if (complete && (!evidence.memberNodeIds.includes(edge.fromNodeId) || !evidence.memberNodeIds.includes(edge.toNodeId))) {
+          issues.push(`${label}.edges must stay inside the component's member nodes`);
+        }
+      }
+      break;
+    }
+    case "direction-violation":
+      sample(evidence.violations, "violations");
+      ordered(evidence.violations, "violations", compareRefactorEvidenceDirectionViolations);
+      idList(evidence.constraintIds, evidence.constraintCount, "constraintIds", "constraintCount");
+      for (const violation of evidence.violations) {
+        edgeIssues(violation, "violations");
+        if (!evidence.constraintIds.includes(violation.constraintId)) issues.push(`${label}.violations must name a listed constraintId`);
+      }
+      if (evidence.totalCount !== observation.metrics.directionViolationCount) {
+        issues.push(`${label}.totalCount must equal metrics.directionViolationCount`);
+      }
+      break;
+    case "ownership-ambiguous":
+    case "undeclared-footprint":
+    case "unowned-paths":
+      sample(evidence.paths, "paths");
+      ordered(evidence.paths, "paths", (left, right) => compareText(left.path, right.path));
+      for (const entry of evidence.paths) {
+        issues.push(...repoPathIssues(`${label}.paths.path`, entry.path));
+        idList(entry.candidateOwnerNodeIds, entry.candidateOwnerCount, "paths.candidateOwnerNodeIds", "paths.candidateOwnerCount");
+      }
+      if (evidence.kind === "unowned-paths" && evidence.totalCount !== observation.metrics.unownedFileCount) {
+        issues.push(`${label}.totalCount must equal metrics.unownedFileCount`);
+      }
+      break;
+    case "evidence-gap":
+      sample(evidence.unresolvedImports, "unresolvedImports");
+      ordered(evidence.unresolvedImports, "unresolvedImports", compareRefactorEvidenceUnresolvedImports);
+      issues.push(...sortedUniqueIssues(`${label}.reasonCodes`, evidence.reasonCodes));
+      for (const entry of evidence.unresolvedImports) {
+        issues.push(...repoPathIssues(`${label}.unresolvedImports.fromPath`, entry.fromPath));
+        issues.push(...lineIssues(`${label}.unresolvedImports.fromLine`, entry.fromLine));
+        issues.push(...specifierIssues(`${label}.unresolvedImports.specifier`, entry.specifier));
+      }
+      if (evidence.totalCount !== observation.metrics.unresolvedImportCount) {
+        issues.push(`${label}.totalCount must equal metrics.unresolvedImportCount`);
+      }
+      break;
+    default:
+      issues.push(`${label}.kind is unsupported`);
+  }
+  return [...new Set(issues)];
+}
+
 export function refactorResolutionEvidenceInvariantIssues(
   evidence: RefactorResolutionEvidenceV1,
   prefix = "resolutionEvidence"
@@ -787,6 +1044,18 @@ export function recommendationV3InvariantIssues(recommendation: RecommendationV3
     if (recommendation.enforcement !== "advisory") {
       issues.push(`${prefix}.structural_observation enforcement must be advisory`);
     }
+    if (shapeIssues.length === 0) {
+      // The payload is self-contained: the observation's metrics, signals and evidence travel with
+      // it, so the same evidence rules bind a recorded record and a fresh assessment.
+      const payload = recommendation.payload as StructuralObservationPayloadV1;
+      issues.push(
+        ...sortedUniqueIssues(`${prefix}.payload.signalIds`, payload.signalIds),
+        ...refactorObservationEvidenceIssues(
+          { kind: payload.kind, subjectSelectorId: recommendation.subject, signalIds: payload.signalIds, metrics: payload.metrics, evidence: payload.evidence },
+          `${prefix}.payload`
+        )
+      );
+    }
   }
   if (recommendation.category === "refactor_proposal") {
     if (!isRefactorProposalAuthorSource(recommendation.authoredBy.source)) {
@@ -953,7 +1222,16 @@ const REQUIRED_PAYLOAD_FIELDS: Readonly<Record<RecommendationCategory, readonly
     "scale",
     "targetOutcomes"
   ],
-  structural_observation: ["affectedNodeIds", "assessmentDigest", "baselineSnapshotDigest", "derivedOutcomes", "kind"]
+  structural_observation: [
+    "affectedNodeIds",
+    "assessmentDigest",
+    "baselineSnapshotDigest",
+    "derivedOutcomes",
+    "evidence",
+    "kind",
+    "metrics",
+    "signalIds"
+  ]
 };
 
 function fingerprintPayloadSubset(category: RecommendationCategory, payload: RecommendationPayloadV1): Record<string, Json> {
@@ -984,6 +1262,32 @@ function outcomeIssues(label: string, outcomes: readonly RefactorTargetOutcomeV1
   return issues;
 }
 
+function compareText(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+/** An unknown line sorts before every known one, so the order is total. */
+function compareLine(left: number | null, right: number | null): number {
+  return (left ?? 0) - (right ?? 0);
+}
+
+function repoPathIssues(label: string, path: string): string[] {
+  return typeof path === "string" && isRepoRelativePosixPath(path) ? [] : [`${label} must be a repo-relative POSIX path`];
+}
+
+function lineIssues(label: string, line: number | null): string[] {
+  return line === null || (Number.isInteger(line) && line >= 1) ? [] : [`${label} must be null or a positive integer`];
+}
+
+function specifierIssues(label: string, specifier: string): string[] {
+  return typeof specifier === "string"
+    && specifier.length > 0
+    && specifier.length <= REFACTOR_EVIDENCE_SPECIFIER_MAX_LENGTH
+    && !/[\u0000-\u001f\u007f]/.test(specifier)
+    ? []
+    : [`${label} must be a single-line specifier of 1-${REFACTOR_EVIDENCE_SPECIFIER_MAX_LENGTH} characters`];
+}
+
 function digestIssues(label: string, value: string): string[] {
   return SHA256_DIGEST_PATTERN.test(value) ? [] : [`${label} must be a sha256:<64-hex> digest`];
 }

package/src/schema.ts

@@ -15,12 +15,14 @@ export type ArchContextErrorCode =
   | "AC_RUNTIME_UNAVAILABLE"
   | "AC_RUNTIME_VERSION_UNSUPPORTED"
   | "AC_CODEGRAPH_UNAVAILABLE"
+  | "AC_CODE_FACTS_UNAVAILABLE"
   | "AC_INDEX_STALE"
   | "AC_CONTEXT_STALE"
   | "AC_SCHEMA_INVALID"
   | "AC_POLICY_VIOLATION"
   | "AC_PATH_DENIED"
   | "AC_PRECONDITION_FAILED"
+  | "AC_PROJECTION_APPLY_COMMITTED"
   | "AC_CAPABILITY_UNSUPPORTED"
   | "AC_INTERVENTION_REQUIRED"
   | "AC_PROOF_REQUIRED"
@@ -32,7 +34,8 @@ export type ArchContextErrorCode =
   | "AC_MODEL_ADOPTION_REQUIRED"
   | "AC_REFACTOR_STALE"
   | "AC_REFACTOR_EVIDENCE_REQUIRED"
-  | "AC_REFACTOR_PROPOSAL_UNAUTHORED";
+  | "AC_REFACTOR_PROPOSAL_UNAUTHORED"
+  | "AC_REFACTOR_RUN_TOO_LARGE";
 
 export interface ArchContextError {
   code: ArchContextErrorCode;
@@ -41,6 +44,8 @@ export interface ArchContextError {
   retryable: boolean;
   action: string;
   reasonCode?: string;
+  /** Machine-readable facts a caller needs to act on this error, never parsed from `message`. */
+  details?: { [key: string]: Json };
 }
 
 export interface JsonEnvelope<T extends Json = Json> {
@@ -56,12 +61,14 @@ export const ERROR_CATALOG: Record<ArchContextErrorCode, Omit<ArchContextError,
   AC_RUNTIME_UNAVAILABLE: { code: "AC_RUNTIME_UNAVAILABLE", severity: "error", retryable: true, action: "start-or-reconnect-runtime" },
   AC_RUNTIME_VERSION_UNSUPPORTED: { code: "AC_RUNTIME_VERSION_UNSUPPORTED", severity: "error", retryable: true, action: "upgrade-archctx-runtime" },
   AC_CODEGRAPH_UNAVAILABLE: { code: "AC_CODEGRAPH_UNAVAILABLE", severity: "error", retryable: true, action: "run-diagnostics" },
+  AC_CODE_FACTS_UNAVAILABLE: { code: "AC_CODE_FACTS_UNAVAILABLE", severity: "error", retryable: true, action: "codegraph-init" },
   AC_INDEX_STALE: { code: "AC_INDEX_STALE", severity: "warning", retryable: true, action: "sync-codefacts" },
   AC_CONTEXT_STALE: { code: "AC_CONTEXT_STALE", severity: "warning", retryable: true, action: "prepare-task-again" },
   AC_SCHEMA_INVALID: { code: "AC_SCHEMA_INVALID", severity: "error", retryable: false, action: "repair-model" },
   AC_POLICY_VIOLATION: { code: "AC_POLICY_VIOLATION", severity: "error", retryable: false, action: "revise-plan" },
   AC_PATH_DENIED: { code: "AC_PATH_DENIED", severity: "critical", retryable: false, action: "do-not-bypass" },
   AC_PRECONDITION_FAILED: { code: "AC_PRECONDITION_FAILED", severity: "warning", retryable: true, action: "rebuild-plan" },
+  AC_PROJECTION_APPLY_COMMITTED: { code: "AC_PROJECTION_APPLY_COMMITTED", severity: "error", retryable: false, action: "readback-committed-projection-apply" },
   AC_CAPABILITY_UNSUPPORTED: { code: "AC_CAPABILITY_UNSUPPORTED", severity: "error", retryable: false, action: "stay-within-single-repository" },
   AC_INTERVENTION_REQUIRED: { code: "AC_INTERVENTION_REQUIRED", severity: "error", retryable: false, action: "enter-intervention-sop" },
   AC_PROOF_REQUIRED: { code: "AC_PROOF_REQUIRED", severity: "warning", retryable: false, action: "execute-proof-point" },
@@ -73,19 +80,28 @@ export const ERROR_CATALOG: Record<ArchContextErrorCode, Omit<ArchContextError,
   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" }
+  AC_REFACTOR_PROPOSAL_UNAUTHORED: { code: "AC_REFACTOR_PROPOSAL_UNAUTHORED", severity: "error", retryable: false, action: "attach-authoring-actor" },
+  // Not retryable: the run's size is a pure function of the measured tree, so the same call at the
+  // same HEAD fails the same way. The read-only `refactor scan` still answers, with `recordable: false`.
+  AC_REFACTOR_RUN_TOO_LARGE: { code: "AC_REFACTOR_RUN_TOO_LARGE", severity: "error", retryable: false, action: "use-read-only-refactor-scan" }
 };
 
 export function okEnvelope<T extends Json>(requestId: string, data: T): JsonEnvelope<T> {
   return { schemaVersion: "archcontext.envelope/v1", ok: true, requestId, data };
 }
 
-export function errorEnvelope(requestId: string, code: ArchContextErrorCode, message: string, reasonCode?: string): JsonEnvelope {
+export function errorEnvelope(
+  requestId: string,
+  code: ArchContextErrorCode,
+  message: string,
+  reasonCode?: string,
+  details?: { [key: string]: Json }
+): JsonEnvelope {
   return {
     schemaVersion: "archcontext.envelope/v1",
     ok: false,
     requestId,
-    error: { ...ERROR_CATALOG[code], message, ...(reasonCode ? { reasonCode } : {}) }
+    error: { ...ERROR_CATALOG[code], message, ...(reasonCode ? { reasonCode } : {}), ...(details ? { details } : {}) }
   };
 }
 

package/src/validator.ts

@@ -11,6 +11,7 @@ export interface ValidationResult {
 }
 
 type JsonSchema = {
+  $id?: string;
   $ref?: string;
   $defs?: Record<string, JsonSchema>;
   type?: string | string[];
@@ -20,6 +21,8 @@ type JsonSchema = {
   required?: string[];
   properties?: Record<string, JsonSchema>;
   items?: JsonSchema;
+  contains?: JsonSchema;
+  minContains?: number;
   oneOf?: JsonSchema[];
   anyOf?: JsonSchema[];
   allOf?: JsonSchema[];
@@ -37,26 +40,60 @@ type JsonSchema = {
   maximum?: number;
 };
 
-export function validateJsonSchema(schema: JsonSchema, value: Json): ValidationResult {
+/**
+ * Loads the schema document whose `$id` is the given absolute URI (no fragment). A non-local
+ * `$ref` — one that does not start with `#` — resolves against the enclosing document's `$id` and
+ * is read through this resolver; without one, every such reference is reported as unresolved
+ * instead of being skipped, so a published schema can never pass on a reference it did not check.
+ */
+export type JsonSchemaResolver = (uri: string) => JsonSchema | undefined;
+
+export interface ValidateJsonSchemaOptions {
+  resolveSchema?: JsonSchemaResolver;
+}
+
+/**
+ * A resolver over a fixed set of schema documents, keyed by their `$id`. Every document must carry
+ * a unique absolute `$id`; the set is the whole universe a validation may reference.
+ */
+export function jsonSchemaResolver(documents: readonly JsonSchema[]): JsonSchemaResolver {
+  const byId = new Map<string, JsonSchema>();
+  for (const document of documents) {
+    if (typeof document.$id !== "string" || document.$id.length === 0) throw new Error("json-schema-resolver-document-missing-id");
+    const id = new URL(document.$id).href;
+    if (byId.has(id)) throw new Error(`json-schema-resolver-duplicate-id: ${id}`);
+    byId.set(id, document);
+  }
+  return (uri) => byId.get(uri);
+}
+
+export function validateJsonSchema(schema: JsonSchema, value: Json, options: ValidateJsonSchemaOptions = {}): ValidationResult {
   const issues: ValidationIssue[] = [];
-  visit(schema, value, "$", issues, schema);
+  visit(schema, value, "$", issues, schema, options.resolveSchema);
   return { valid: issues.length === 0, issues };
 }
 
-function visit(schema: JsonSchema, value: Json, path: string, issues: ValidationIssue[], root: JsonSchema): void {
+/** `root` is the document the current subschema belongs to; local `#/...` references resolve inside it. */
+function visit(
+  schema: JsonSchema,
+  value: Json,
+  path: string,
+  issues: ValidationIssue[],
+  root: JsonSchema,
+  resolveSchema: JsonSchemaResolver | undefined
+): void {
   if (schema.$ref) {
-    if (!schema.$ref.startsWith("#/")) return;
-    const resolved = resolveLocalRef(root, schema.$ref);
-    if (!resolved) {
+    const target = resolveRef(root, resolveSchema, schema.$ref);
+    if (!target) {
       issues.push({ path, message: `unresolved schema reference ${schema.$ref}` });
       return;
     }
-    visit(resolved, value, path, issues, root);
+    visit(target.schema, value, path, issues, target.root, resolveSchema);
   }
   if (schema.oneOf) {
     const matched = schema.oneOf.filter((candidate) => {
       const candidateIssues: ValidationIssue[] = [];
-      visit(candidate, value, path, candidateIssues, root);
+      visit(candidate, value, path, candidateIssues, root, resolveSchema);
       return candidateIssues.length === 0;
     }).length;
     if (matched !== 1) {
@@ -67,21 +104,21 @@ function visit(schema: JsonSchema, value: Json, path: string, issues: Validation
   if (schema.anyOf) {
     const matched = schema.anyOf.some((candidate) => {
       const candidateIssues: ValidationIssue[] = [];
-      visit(candidate, value, path, candidateIssues, root);
+      visit(candidate, value, path, candidateIssues, root, resolveSchema);
       return candidateIssues.length === 0;
     });
     if (!matched) issues.push({ path, message: "expected at least one matching schema" });
   }
-  for (const candidate of schema.allOf ?? []) visit(candidate, value, path, issues, root);
+  for (const candidate of schema.allOf ?? []) visit(candidate, value, path, issues, root, resolveSchema);
   if (schema.if) {
     const conditionIssues: ValidationIssue[] = [];
-    visit(schema.if, value, path, conditionIssues, root);
+    visit(schema.if, value, path, conditionIssues, root, resolveSchema);
     const branch = conditionIssues.length === 0 ? schema.then : schema.else;
-    if (branch) visit(branch, value, path, issues, root);
+    if (branch) visit(branch, value, path, issues, root, resolveSchema);
   }
   if (schema.not) {
     const candidateIssues: ValidationIssue[] = [];
-    visit(schema.not, value, path, candidateIssues, root);
+    visit(schema.not, value, path, candidateIssues, root, resolveSchema);
     if (candidateIssues.length === 0) issues.push({ path, message: "matched forbidden schema" });
   }
   if (schema.const !== undefined && JSON.stringify(value) !== JSON.stringify(schema.const)) {
@@ -118,7 +155,16 @@ function visit(schema: JsonSchema, value: Json, path: string, issues: Validation
     if (schema.uniqueItems && new Set(value.map(canonicalize)).size !== value.length) {
       issues.push({ path, message: "expected unique items" });
     }
-    if (schema.items) value.forEach((item, index) => visit(schema.items!, item, `${path}[${index}]`, issues, root));
+    if (schema.items) value.forEach((item, index) => visit(schema.items!, item, `${path}[${index}]`, issues, root, resolveSchema));
+    if (schema.contains) {
+      const minContains = schema.minContains ?? 1;
+      const matched = value.filter((item, index) => {
+        const candidateIssues: ValidationIssue[] = [];
+        visit(schema.contains!, item, `${path}[${index}]`, candidateIssues, root, resolveSchema);
+        return candidateIssues.length === 0;
+      }).length;
+      if (matched < minContains) issues.push({ path, message: `expected at least ${minContains} items matching contains` });
+    }
   }
   if (value !== null && typeof value === "object" && !Array.isArray(value)) {
     const objectValue = value as Record<string, Json>;
@@ -126,7 +172,7 @@ function visit(schema: JsonSchema, value: Json, path: string, issues: Validation
       if (!(key in objectValue)) issues.push({ path: `${path}.${key}`, message: "required" });
     }
     for (const [key, child] of Object.entries(schema.properties ?? {})) {
-      if (key in objectValue) visit(child, objectValue[key], `${path}.${key}`, issues, root);
+      if (key in objectValue) visit(child, objectValue[key], `${path}.${key}`, issues, root, resolveSchema);
     }
     if (schema.additionalProperties === false && schema.properties) {
       for (const key of Object.keys(objectValue)) {
@@ -136,7 +182,33 @@ function visit(schema: JsonSchema, value: Json, path: string, issues: Validation
   }
 }
 
+function resolveRef(
+  root: JsonSchema,
+  resolveSchema: JsonSchemaResolver | undefined,
+  ref: string
+): { schema: JsonSchema; root: JsonSchema } | undefined {
+  if (ref.startsWith("#")) {
+    const schema = resolveLocalRef(root, ref);
+    return schema ? { schema, root } : undefined;
+  }
+  if (!resolveSchema || typeof root.$id !== "string") return undefined;
+  let absolute: URL;
+  try {
+    absolute = new URL(ref, root.$id);
+  } catch {
+    return undefined;
+  }
+  const fragment = absolute.hash;
+  absolute.hash = "";
+  const document = resolveSchema(absolute.href);
+  if (!document) return undefined;
+  if (fragment === "" || fragment === "#") return { schema: document, root: document };
+  const schema = resolveLocalRef(document, fragment);
+  return schema ? { schema, root: document } : undefined;
+}
+
 function resolveLocalRef(root: JsonSchema, ref: string): JsonSchema | undefined {
+  if (ref === "#") return root;
   if (!ref.startsWith("#/")) return undefined;
   let current: unknown = root;
   for (const rawSegment of ref.slice(2).split("/")) {