archctx-contracts 0.7.2 → 0.8.1

package/schemas/runtime/runtime-refactor-scan.schema.json

@@ -9,6 +9,7 @@
     "repository",
     "worktree",
     "requestId",
+    "namespace",
     "request",
     "trackedFileCount",
     "snapshot",
@@ -35,6 +36,11 @@
       "type": "string",
       "pattern": "^refactor_request\\.[a-f0-9]{16}$"
     },
+    "namespace": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(\\.[a-z0-9][a-z0-9-]*)+$",
+      "description": "The manifest product.id every refactor subject selector of this scan is scoped by (ADR-0046)."
+    },
     "request": {
       "$ref": "#/$defs/refactorRequest"
     },
@@ -389,6 +395,7 @@
           "required": [
             "kind",
             "memberNodeIds",
+            "directions",
             "edges",
             "totalCount",
             "truncated"
@@ -397,6 +404,80 @@
             "kind": {
               "const": "cycle"
             },
+            "memberNodeIds": {
+              "type": "array",
+              "minItems": 2,
+              "maxItems": 2,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "directions": {
+              "type": "array",
+              "minItems": 2,
+              "maxItems": 2,
+              "description": "[thin, thick] direction of the pair, each with its import-edge population and sampled count.",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "fromNodeId",
+                  "toNodeId",
+                  "totalCount",
+                  "sampledCount"
+                ],
+                "properties": {
+                  "fromNodeId": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "toNodeId": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "totalCount": {
+                    "type": "integer",
+                    "minimum": 1
+                  },
+                  "sampledCount": {
+                    "type": "integer",
+                    "minimum": 0
+                  }
+                }
+              }
+            },
+            "edges": {
+              "type": "array",
+              "maxItems": 20,
+              "items": {
+                "$ref": "#/$defs/evidenceImportEdge"
+              }
+            },
+            "totalCount": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "truncated": {
+              "type": "boolean"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "memberNodeIds",
+            "edges",
+            "totalCount",
+            "truncated"
+          ],
+          "properties": {
+            "kind": {
+              "const": "residual-cycle"
+            },
             "memberNodeIds": {
               "$ref": "#/$defs/evidenceIdList"
             },
@@ -576,6 +657,16 @@
             "null"
           ]
         },
+        "memberNodeIds": {
+          "type": "array",
+          "minItems": 2,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Present exactly for moduleDependencies.* metrics: the pair ends or the residual cycle members, sorted."
+        },
         "operator": {
           "enum": [
             "absent",
@@ -867,6 +958,7 @@
             "direction-violation",
             "evidence-gap",
             "ownership-ambiguous",
+            "residual-cycle",
             "undeclared-footprint",
             "unowned-paths"
           ]
@@ -981,6 +1073,26 @@
             }
           }
         },
+        {
+          "if": {
+            "properties": {
+              "kind": {
+                "const": "residual-cycle"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "evidence": {
+                "properties": {
+                  "kind": {
+                    "const": "residual-cycle"
+                  }
+                }
+              }
+            }
+          }
+        },
         {
           "if": {
             "properties": {
@@ -1719,6 +1831,7 @@
         "modelDigest",
         "codeFacts",
         "modules",
+        "moduleDependencies",
         "repositorySummary",
         "createdAt",
         "snapshotDigest"
@@ -1820,6 +1933,33 @@
             "$ref": "#/$defs/moduleStatistics"
           }
         },
+        "moduleDependencies": {
+          "type": "array",
+          "description": "Ordered cross-module dependency table, sorted by (fromNodeId, toNodeId).",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "fromNodeId",
+              "toNodeId",
+              "distinctFileEdgeCount"
+            ],
+            "properties": {
+              "fromNodeId": {
+                "type": "string",
+                "minLength": 1
+              },
+              "toNodeId": {
+                "type": "string",
+                "minLength": 1
+              },
+              "distinctFileEdgeCount": {
+                "type": "integer",
+                "minimum": 1
+              }
+            }
+          }
+        },
         "repositorySummary": {
           "type": "object",
           "additionalProperties": false,
@@ -2095,6 +2235,7 @@
       "required": [
         "kind",
         "subjectSelectorId",
+        "affectedNodeIds",
         "signalIds",
         "metrics",
         "evidence"
@@ -2106,6 +2247,7 @@
             "direction-violation",
             "evidence-gap",
             "ownership-ambiguous",
+            "residual-cycle",
             "undeclared-footprint",
             "unowned-paths"
           ]
@@ -2115,6 +2257,15 @@
           "minLength": 1,
           "pattern": "\\S"
         },
+        "affectedNodeIds": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Declared nodes the observation is about, sorted and unique; [] for a repository-wide fact."
+        },
         "signalIds": {
           "type": "array",
           "uniqueItems": true,
@@ -2210,6 +2361,26 @@
             }
           }
         },
+        {
+          "if": {
+            "properties": {
+              "kind": {
+                "const": "residual-cycle"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "evidence": {
+                "properties": {
+                  "kind": {
+                    "const": "residual-cycle"
+                  }
+                }
+              }
+            }
+          }
+        },
         {
           "if": {
             "properties": {

package/schemas/runtime/structural-observation-payload.schema.json

@@ -24,6 +24,7 @@
         "direction-violation",
         "evidence-gap",
         "ownership-ambiguous",
+        "residual-cycle",
         "undeclared-footprint",
         "unowned-paths"
       ]
@@ -138,6 +139,26 @@
         }
       }
     },
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "residual-cycle"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "evidence": {
+            "properties": {
+              "kind": {
+                "const": "residual-cycle"
+              }
+            }
+          }
+        }
+      }
+    },
     {
       "if": {
         "properties": {
@@ -344,6 +365,7 @@
           "required": [
             "kind",
             "memberNodeIds",
+            "directions",
             "edges",
             "totalCount",
             "truncated"
@@ -352,6 +374,80 @@
             "kind": {
               "const": "cycle"
             },
+            "memberNodeIds": {
+              "type": "array",
+              "minItems": 2,
+              "maxItems": 2,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "directions": {
+              "type": "array",
+              "minItems": 2,
+              "maxItems": 2,
+              "description": "[thin, thick] direction of the pair, each with its import-edge population and sampled count.",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "fromNodeId",
+                  "toNodeId",
+                  "totalCount",
+                  "sampledCount"
+                ],
+                "properties": {
+                  "fromNodeId": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "toNodeId": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "totalCount": {
+                    "type": "integer",
+                    "minimum": 1
+                  },
+                  "sampledCount": {
+                    "type": "integer",
+                    "minimum": 0
+                  }
+                }
+              }
+            },
+            "edges": {
+              "type": "array",
+              "maxItems": 20,
+              "items": {
+                "$ref": "#/$defs/evidenceImportEdge"
+              }
+            },
+            "totalCount": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "truncated": {
+              "type": "boolean"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "memberNodeIds",
+            "edges",
+            "totalCount",
+            "truncated"
+          ],
+          "properties": {
+            "kind": {
+              "const": "residual-cycle"
+            },
             "memberNodeIds": {
               "$ref": "#/$defs/evidenceIdList"
             },
@@ -531,6 +627,16 @@
             "null"
           ]
         },
+        "memberNodeIds": {
+          "type": "array",
+          "minItems": 2,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Present exactly for moduleDependencies.* metrics: the pair ends or the residual cycle members, sorted."
+        },
         "operator": {
           "enum": [
             "absent",

package/src/architecture-debt.ts

@@ -0,0 +1,115 @@
+import { digestJson, type ArchContextError, type Json } from "./schema";
+
+/** Measured architecture work, distinct from generated-file freshness and source byte stamps. */
+export const ARCHITECTURE_DEBT_SCHEMA_VERSION = "archcontext.architecture-debt/v1" as const;
+export const ARCHITECTURE_DEBT_KINDS = ["unowned-path", "ambiguous-owner", "undeclared-dependency", "flow-proof-failed", "stale-anchor", "practice-regression"] as const;
+export type ArchitectureDebtKind = typeof ARCHITECTURE_DEBT_KINDS[number];
+export const ARCHITECTURE_DEBT_CHECKS = ["ownership", "anchors", "dependencies", "flows", "practices"] as const;
+export type ArchitectureDebtCheck = typeof ARCHITECTURE_DEBT_CHECKS[number];
+
+export interface ArchitectureDebtItemV1 {
+  /** Content identity, independent of absolute root, branch, timestamps and source byte stamps. */
+  id: string;
+  kind: ArchitectureDebtKind;
+  /** Canonical producer identities. Empty for a source path with no owner. */
+  nodeIds: string[];
+  capabilityIds: string[];
+  paths: string[];
+  reasonCode: string;
+  action: string;
+  /** Bounded metadata only; never source bodies or arbitrary provider output. */
+  details: Record<string, string | number | string[]>;
+}
+
+export interface ArchitectureDebtCheckV1 {
+  check: ArchitectureDebtCheck;
+  coverage: "complete" | "partial" | "unknown";
+  reasonCodes: string[];
+}
+
+export interface ArchitectureDebtReportV1 {
+  schemaVersion: typeof ARCHITECTURE_DEBT_SCHEMA_VERSION;
+  scope: { kind: "repository" | "changed-paths"; changedPaths: string[]; capabilityIds: string[] };
+  /** A partial/unknown report with no items does not prove absence of debt. */
+  coverage: "complete" | "partial" | "unknown";
+  coverageReasonCodes: string[];
+  checks: ArchitectureDebtCheckV1[];
+  items: ArchitectureDebtItemV1[];
+  actionsRequired: string[];
+  /** Binds the entire debt report. Checkpoint's existing resultDigest binds practice guidance only. */
+  digest: string;
+}
+
+export interface ArchitectureDebtHookLogV1 {
+  schemaVersion: "archcontext.hook-log/v1";
+  event: string;
+  elapsedMs: number;
+  pathCount: number;
+  changedPathDigest: string;
+  reasonCode: string;
+  failOpen: boolean;
+  egress: "none";
+  network: "forbidden";
+}
+
+/** Hook-only observation; it never advances the practice baseline. */
+export interface ArchitectureDebtHookCheckpointV1 {
+  schemaVersion: "archcontext.hook-debt-checkpoint/v1";
+  debt: ArchitectureDebtReportV1;
+  hookLog: ArchitectureDebtHookLogV1;
+}
+
+/** Unavailable observation, never a clean debt report. Invalid arguments remain errors. */
+export interface ArchitectureDebtHookFailureV1 {
+  schemaVersion: "archcontext.hook-checkpoint-fail-open/v1";
+  accepted: false;
+  failOpen: true;
+  coverage: "unknown";
+  reasonCode: string;
+  error: ArchContextError;
+  event: string;
+  pathCount: number;
+  egress: "none";
+  network: "forbidden";
+  hookLog: ArchitectureDebtHookLogV1;
+}
+
+export function architectureDebtReportIssues(report: ArchitectureDebtReportV1): string[] {
+  const issues: string[] = [];
+  const sorted = (name: string, values: string[]) => {
+    if (values.some((v, i) => i > 0 && v <= values[i - 1]!)) issues.push(`${name} must be sorted and unique`);
+  };
+  if (report.schemaVersion !== ARCHITECTURE_DEBT_SCHEMA_VERSION) issues.push("unsupported schemaVersion");
+  const { digest, ...body } = report;
+  if (digest !== digestJson(body as unknown as Json)) issues.push("digest must bind the debt report");
+  sorted("items", report.items.map(item => item.id));
+  sorted("actionsRequired", report.actionsRequired);
+  sorted("coverageReasonCodes", report.coverageReasonCodes);
+  sorted("scope.changedPaths", report.scope.changedPaths);
+  sorted("scope.capabilityIds", report.scope.capabilityIds);
+  if (report.checks.length !== ARCHITECTURE_DEBT_CHECKS.length || ARCHITECTURE_DEBT_CHECKS.some((check, i) => report.checks[i]?.check !== check)) issues.push("checks must enumerate every producer in contract order");
+  const coverage = report.checks.every(check => check.coverage === "complete") ? "complete"
+    : report.checks.every(check => check.coverage === "unknown") ? "unknown" : "partial";
+  if (report.coverage !== coverage) issues.push("coverage must describe all checks");
+  const reasons = [...new Set(report.checks.flatMap(check => check.reasonCodes.map(reason => `${check.check}:${reason}`)))].sort();
+  if (JSON.stringify(reasons) !== JSON.stringify(report.coverageReasonCodes)) issues.push("coverageReasonCodes must describe check gaps");
+  for (const check of report.checks) {
+    sorted(`${check.check}.reasonCodes`, check.reasonCodes);
+    if ((check.coverage === "complete") !== (check.reasonCodes.length === 0)) issues.push(`${check.check} must name every coverage gap`);
+  }
+  if (report.coverage === "unknown" && report.items.length > 0) issues.push("unknown coverage cannot contain measured items");
+  const actions = [...new Set(report.items.map(item => item.action))].sort();
+  if (JSON.stringify(actions) !== JSON.stringify(report.actionsRequired)) issues.push("actionsRequired must name the measured debt actions");
+  for (const item of report.items) {
+    if (!ARCHITECTURE_DEBT_KINDS.includes(item.kind)) issues.push("unsupported debt kind");
+    if (!item.action || !item.reasonCode) issues.push("every item needs a reason and action");
+    sorted(`${item.id}.nodeIds`, item.nodeIds);
+    sorted(`${item.id}.capabilityIds`, item.capabilityIds);
+    sorted(`${item.id}.paths`, item.paths);
+    const strings = [item.action, item.reasonCode, ...item.nodeIds, ...item.capabilityIds, ...item.paths,
+      ...Object.values(item.details).flatMap(value => typeof value === "string" ? [value] : Array.isArray(value) ? value : [])];
+    if (strings.some(value => value.length === 0 || value.length > 1024)) issues.push(`${item.id} contains invalid metadata strings`);
+    if (new TextEncoder().encode(JSON.stringify(item.details)).byteLength > 4096) issues.push(`${item.id}.details exceeds metadata budget`);
+  }
+  return issues;
+}

package/src/changeset-recovery.ts

@@ -0,0 +1,49 @@
+import { digestJson, type Json } from "./schema";
+export const CHANGESET_RECOVERY_DETAILS_LIMIT_BYTES = 262144;
+export const CHANGESET_RECOVERY_READBACK = "runtimeStatus.changeSetRecovery.unresolvedJournals";
+function own(value: unknown, key: string): unknown {
+  if (!value || typeof value !== "object") throw new Error("Recovery metadata must be own data");
+  const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  if (!descriptor || !("value" in descriptor)) throw new Error("Recovery metadata cannot contain accessors");
+  return descriptor.value;
+}
+function record(value: unknown, fields: string[]): void {
+  if (!value || typeof value !== "object" || Array.isArray(value) || ![Object.prototype,null].includes(Object.getPrototypeOf(value))) throw new Error("Recovery metadata must be a plain record");
+  const keys = Reflect.ownKeys(value);
+  if (keys.length !== fields.length || keys.some(key=>typeof key !== "string" || !fields.includes(key))) throw new Error("Recovery metadata has unknown fields");
+}
+function journalsSnapshot(value: unknown): Json[] {
+  if (!Array.isArray(value)) throw new Error("Recovery journals must be an array");
+  const length = own(value,"length");
+  if (!Number.isSafeInteger(length) || (length as number) < 0 || Reflect.ownKeys(value).length !== (length as number)+1) throw new Error("Recovery journals must be dense own data");
+  return Array.from({length: length as number},(_,index)=>{
+    const journal=own(value,String(index));
+    const fields=["journalId","changeSetId","root","reason"];
+    record(journal,fields);
+    return Object.fromEntries(fields.map(key=>{
+      const item=own(journal,key);
+      if(typeof item!=="string") throw new Error("Recovery authority must be strings");
+      return [key,item];
+    }));
+  });
+}
+/** Complete authority is copied whole. Oversized authority remains available through existing status/health. */
+export function changeSetRecoveryDetails(journals: unknown): {[key:string]:Json} {
+  const unresolvedJournals=journalsSnapshot(journals);
+  const full={unresolvedJournals};
+  if(new TextEncoder().encode(JSON.stringify(full)).length<=CHANGESET_RECOVERY_DETAILS_LIMIT_BYTES) return full;
+  return {manualRecoveryRequired:true, authorityReadbackRequired:true, authorityReadback:CHANGESET_RECOVERY_READBACK, journalCount:unresolvedJournals.length, authorityDigest:digestJson(unresolvedJournals)};
+}
+export function changeSetRecoveryDetailsSnapshot(value:unknown): {[key:string]:Json} {
+  if(value && typeof value==="object" && Object.hasOwn(value,"unresolvedJournals")) {
+    record(value,["unresolvedJournals"]);
+    const full={unresolvedJournals:journalsSnapshot(own(value,"unresolvedJournals"))};
+    if(new TextEncoder().encode(JSON.stringify(full)).length>CHANGESET_RECOVERY_DETAILS_LIMIT_BYTES) throw new Error("Recovery authority exceeds budget");
+    return full;
+  }
+  const fields=["manualRecoveryRequired","authorityReadbackRequired","authorityReadback","journalCount","authorityDigest"];
+  record(value,fields);
+  const result=Object.fromEntries(fields.map(key=>[key,own(value,key)]));
+  if(result.manualRecoveryRequired!==true || result.authorityReadbackRequired!==true || result.authorityReadback!==CHANGESET_RECOVERY_READBACK || !Number.isSafeInteger(result.journalCount) || (result.journalCount as number)<0 || typeof result.authorityDigest!=="string" || !/^sha256:[a-f0-9]{64}$/.test(result.authorityDigest)) throw new Error("Invalid manual recovery authority reference");
+  return result as {[key:string]:Json};
+}

package/src/docs-anchors.ts

@@ -6,7 +6,7 @@
  */
 export const DOCS_ANCHORS_REPORT_SCHEMA_VERSION = "archcontext.docs-anchors/v1" as const;
 
-export const DOCS_ANCHOR_FINDING_KINDS = ["line-moved", "line-out-of-range", "missing-path", "missing-symbol"] as const;
+export const DOCS_ANCHOR_FINDING_KINDS = ["line-moved", "line-out-of-range", "missing-path", "missing-symbol", "unknown-selector"] as const;
 export type DocsAnchorFindingKind = (typeof DOCS_ANCHOR_FINDING_KINDS)[number];
 
 /** Why a citation was found but one of its checks could not run. */
@@ -111,6 +111,7 @@ function docsAnchorFindingIssues(finding: DocsAnchorFindingV1, prefix: string):
   const { citation } = finding;
   if (finding.kind === "missing-path" && citation.path === undefined) issues.push(`${prefix} missing-path must name citation.path`);
   if (finding.kind === "missing-symbol" && citation.symbol === undefined) issues.push(`${prefix} missing-symbol must name citation.symbol`);
+  if (finding.kind === "unknown-selector" && citation.symbol === undefined) issues.push(`${prefix} unknown-selector must name citation.symbol`);
   if (finding.kind === "line-out-of-range" && (citation.line === undefined || finding.lineCount === undefined)) {
     issues.push(`${prefix} line-out-of-range must name citation.line and lineCount`);
   }