archctx-contracts 0.2.2 → 0.4.0

package/schemas/runtime/projection-result.schema.json

@@ -0,0 +1,162 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archcontext.dev/schemas/runtime/projection-result.schema.json",
+  "title": "ProjectionResultV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "requestId", "status", "inputSnapshot", "outputSnapshot", "affectedNodeIds", "files", "humanActions", "refreshSignals", "receiptDigest"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.projection-result/v1" },
+    "requestId": { "type": "string", "pattern": "^[a-zA-Z0-9_.:-]+$", "minLength": 1 },
+    "status": { "enum": ["adoption-required", "applied", "blocked", "human-action-required", "noop", "permanent-failure", "planned", "retryable-failure"] },
+    "inputSnapshot": { "$ref": "#/$defs/snapshot" },
+    "outputSnapshot": { "$ref": "#/$defs/snapshot" },
+    "affectedNodeIds": { "type": "array", "uniqueItems": true, "description": "Canonical wire order is lexicographic and is enforced by projectionResultInvariantIssues.", "items": { "type": "string", "minLength": 1 } },
+    "files": { "type": "array", "description": "Canonical wire order is by path and is enforced by projectionResultInvariantIssues.", "items": { "$ref": "#/$defs/file" } },
+    "humanActions": { "type": "array", "items": { "$ref": "#/$defs/humanAction" } },
+    "refreshSignals": { "type": "array", "description": "Canonical wire order is by signalId and cross-object receipt/snapshot bindings are enforced by projectionResultInvariantIssues.", "items": { "$ref": "#/$defs/refreshSignal" } },
+    "receiptDigest": { "$ref": "#/$defs/digest" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "enum": ["adoption-required", "human-action-required"] } }, "required": ["status"] },
+      "then": { "properties": { "humanActions": { "minItems": 1 } } },
+      "else": { "properties": { "humanActions": { "maxItems": 0 } } }
+    }
+  ],
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "nullableDigest": { "type": ["string", "null"], "pattern": "^sha256:[a-f0-9]{64}$" },
+    "snapshot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repositoryId", "workspaceId", "headSha", "baseHeadSha", "worktreeDigest", "sourceTreeDigest", "modelDigest", "codeGraphDigest", "indexedWorktreeDigest", "projectionInputDigest", "rendererVersion", "layoutVersion", "generatedFrom"],
+      "properties": {
+        "repositoryId": { "type": "string", "minLength": 1 },
+        "workspaceId": { "type": "string", "minLength": 1 },
+        "headSha": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+        "baseHeadSha": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+        "worktreeDigest": { "$ref": "#/$defs/digest" },
+        "sourceTreeDigest": { "$ref": "#/$defs/digest" },
+        "modelDigest": { "$ref": "#/$defs/digest" },
+        "codeGraphDigest": { "$ref": "#/$defs/digest" },
+        "indexedWorktreeDigest": { "$ref": "#/$defs/nullableDigest" },
+        "projectionInputDigest": { "$ref": "#/$defs/digest" },
+        "rendererVersion": { "const": "archcontext.docs-renderer/v2" },
+        "layoutVersion": { "const": "archcontext.docs-layout/v1" },
+        "generatedFrom": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["codeGraphPackage", "codeGraphVersion", "codeGraphBinaryDigest", "codeGraphStatus"],
+          "properties": {
+            "codeGraphPackage": { "const": "@colbymchenry/codegraph" },
+            "codeGraphVersion": { "const": "1.5.0" },
+            "codeGraphBinaryDigest": { "$ref": "#/$defs/digest" },
+            "codeGraphStatus": { "enum": ["ready", "unavailable"] }
+          }
+        }
+      }
+    },
+    "file": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "action", "preimageDigest", "outputDigest"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "not": { "anyOf": [{ "pattern": "^/" }, { "pattern": "\\\\" }, { "pattern": "(^|/)\\.\\.(/|$)" }] }
+        },
+        "action": { "enum": ["create", "delete", "unchanged", "update"] },
+        "preimageDigest": { "$ref": "#/$defs/nullableDigest" },
+        "outputDigest": { "$ref": "#/$defs/nullableDigest" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "action": { "const": "create" } }, "required": ["action"] },
+          "then": { "properties": { "preimageDigest": { "const": null }, "outputDigest": { "$ref": "#/$defs/digest" } } }
+        },
+        {
+          "if": { "properties": { "action": { "const": "delete" } }, "required": ["action"] },
+          "then": { "properties": { "preimageDigest": { "$ref": "#/$defs/digest" }, "outputDigest": { "const": null } } }
+        },
+        {
+          "if": { "properties": { "action": { "enum": ["unchanged", "update"] } }, "required": ["action"] },
+          "then": { "properties": { "preimageDigest": { "$ref": "#/$defs/digest" }, "outputDigest": { "$ref": "#/$defs/digest" } } }
+        }
+      ]
+    },
+    "humanAction": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reasonCode", "affectedNodeIds", "requestPayloadDigest"],
+      "properties": {
+        "reasonCode": { "enum": ["adoption-required", "manual-region-conflict", "target-collision", "unprovable-required-flow", "unresolved-major-change"] },
+        "affectedNodeIds": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "requestPayloadDigest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "digestSet": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["modelDigest", "sourceTreeDigest", "flowProofDigest", "projectionDigest"],
+      "properties": {
+        "modelDigest": { "$ref": "#/$defs/digest" },
+        "sourceTreeDigest": { "$ref": "#/$defs/digest" },
+        "flowProofDigest": { "$ref": "#/$defs/digest" },
+        "projectionDigest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "reasonCode": {
+      "enum": ["constraint-changed", "entrypoint-changed", "interface-changed", "lifecycle-changed", "node-added", "node-moved", "node-removed", "node-renamed", "ownership-changed", "relation-changed", "responsibility-changed", "risk-boundary-changed", "verified-flow-proof-changed"]
+    },
+    "refreshSignal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "signalId", "idempotencyKey", "mode", "repository", "worktree", "cause", "reasonCodes", "affectedNodeIds", "refreshTargets", "baseDigests", "resultingDigests", "projectionReceiptDigest"],
+      "properties": {
+        "schemaVersion": { "const": "archcontext.architecture-refresh-signal/v1" },
+        "signalId": { "$ref": "#/$defs/digest" },
+        "idempotencyKey": { "$ref": "#/$defs/digest" },
+        "mode": { "enum": ["human-action-required", "refresh-required"] },
+        "repository": { "type": "object", "additionalProperties": false, "required": ["repositoryId"], "properties": { "repositoryId": { "type": "string", "minLength": 1 } } },
+        "worktree": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["workspaceId", "headSha", "worktreeDigest"],
+          "properties": {
+            "workspaceId": { "type": "string", "minLength": 1 },
+            "headSha": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+            "worktreeDigest": { "$ref": "#/$defs/digest" }
+          }
+        },
+        "cause": { "enum": ["accepted-semantic-delta", "unresolved-major-candidate", "verified-flow-proof-delta"] },
+        "acceptedChange": { "$ref": "#/$defs/acceptedChange" },
+        "reasonCodes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/reasonCode" } },
+        "affectedNodeIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "refreshTargets": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["architecture-contract-context", "architecture-readiness", "architecture-request-index", "capability-context", "capability-index"] } },
+        "baseDigests": { "$ref": "#/$defs/digestSet" },
+        "resultingDigests": { "$ref": "#/$defs/digestSet" },
+        "projectionReceiptDigest": { "$ref": "#/$defs/digest" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "cause": { "const": "unresolved-major-candidate" } }, "required": ["cause"] },
+          "then": { "properties": { "mode": { "const": "human-action-required" } }, "not": { "required": ["acceptedChange"] } },
+          "else": { "properties": { "mode": { "const": "refresh-required" } }, "required": ["acceptedChange"] }
+        }
+      ]
+    },
+    "acceptedChange": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["changeSetId", "eventId", "reasonCodes", "affectedNodeIds"],
+      "properties": {
+        "changeSetId": { "type": "string", "minLength": 1 },
+        "eventId": { "type": "string", "minLength": 1 },
+        "reasonCodes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/reasonCode" } },
+        "affectedNodeIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+      }
+    }
+  }
+}

package/src/architecture.ts

@@ -0,0 +1,73 @@
+export interface ArchitectureSinkSelectorV2 {
+  id: string;
+  path: string;
+  symbol: string;
+}
+
+export interface ArchitectureEntrypointSymbolV2 {
+  name: string;
+  sinks: ArchitectureSinkSelectorV2[];
+}
+
+export interface ArchitectureEntrypointV2 {
+  id: string;
+  path: string;
+  symbols: ArchitectureEntrypointSymbolV2[];
+}
+
+export interface ArchitectureNodeSourceV2 {
+  include?: string[];
+  exclude?: string[];
+  entrypoints?: ArchitectureEntrypointV2[];
+}
+
+export interface ArchitectureFlowEvidenceSelectorV1 {
+  entrypointId: string;
+  sourceSymbol: string;
+  sinkId: string;
+}
+
+export interface ArchitectureFlowParticipantV1 {
+  id: string;
+  nodeId: string;
+}
+
+export interface ArchitectureFlowStepV1 {
+  id: string;
+  from: string;
+  to: string;
+  label: string;
+  evidence: ArchitectureFlowEvidenceSelectorV1;
+}
+
+export interface ArchitectureFlowOutcomeV1 {
+  id: string;
+  kind: "success" | "error";
+  label: string;
+  steps: ArchitectureFlowStepV1[];
+  terminal: {
+    participant: string;
+    label: string;
+  };
+}
+
+export type ArchitectureFlowV1 = ArchitectureRequiredFlowV1 | ArchitectureNotApplicableFlowV1;
+
+interface ArchitectureFlowBaseV1 {
+  schemaVersion: "archcontext.flow/v1";
+  id: string;
+  capabilityId: string;
+  name: string;
+}
+
+export interface ArchitectureRequiredFlowV1 extends ArchitectureFlowBaseV1 {
+  applicability: "required";
+  participants: ArchitectureFlowParticipantV1[];
+  steps: ArchitectureFlowStepV1[];
+  outcomes: ArchitectureFlowOutcomeV1[];
+}
+
+export interface ArchitectureNotApplicableFlowV1 extends ArchitectureFlowBaseV1 {
+  applicability: "not-applicable";
+  rationale: string;
+}

package/src/index.ts

@@ -1,9 +1,11 @@
 export * from "./control-plane-routes";
+export * from "./architecture";
 export * from "./external-docs";
 export * from "./github-governance";
 export * from "./ledger";
 export * from "./ports";
 export * from "./practices";
+export * from "./projection";
 export * from "./product-version";
 export * from "./schema";
 export * from "./validator";

package/src/ledger.ts

@@ -1,7 +1,7 @@
 import { digestJson, type Json } from "./schema";
 
 export const ARCHITECTURE_EVENT_SCHEMA_VERSION = "archcontext.architecture-event/v1" as const;
-export const ARCHITECTURE_SNAPSHOT_SCHEMA_VERSION = "archcontext.architecture-snapshot/v1" as const;
+export const ARCHITECTURE_SNAPSHOT_SCHEMA_VERSION = "archcontext.architecture-snapshot/v2" as const;
 export const EVIDENCE_ITEM_SCHEMA_VERSION = "archcontext.evidence-item/v2" as const;
 export const EVIDENCE_BINDING_SCHEMA_VERSION = "archcontext.evidence-binding/v1" as const;
 export const RECOMMENDATION_RUN_SCHEMA_VERSION = "archcontext.recommendation-run/v1" as const;
@@ -172,17 +172,25 @@ export interface ArchitectureEventV1 {
   extensions?: Record<string, Json>;
 }
 
-export interface ArchitectureSnapshotV1 {
+export interface ArchitectureSnapshotV2 {
   schemaVersion: typeof ARCHITECTURE_SNAPSHOT_SCHEMA_VERSION;
   snapshotId: string;
   repository: ArchitectureRepositoryIdentityV1;
   worktree: ArchitectureWorktreeIdentityV1;
   sourceMode: ArchitectureLedgerMode;
   eventCursor: {
+    eventCount: number;
+    lastEventSequence: number;
     lastEventId: string;
     lastEventHash: string;
   };
   graphDigest: string;
+  evidenceDigest: string;
+  stateDigest: string;
+  state: {
+    graph: Json;
+    evidence: EvidenceStateAtCursorV1;
+  };
   projectionDigest: string;
   entityCount: number;
   relationCount: number;
@@ -240,6 +248,120 @@ export interface EvidenceBindingV1 {
   extensions?: Record<string, Json>;
 }
 
+export type EvidenceLifecycleTargetV1 = "item" | "binding";
+export type EvidenceLifecycleActionV1 = "create" | "update" | "remove";
+
+export type EvidenceLifecycleOperationV1 =
+  | {
+      target: "item";
+      action: "create";
+      evidenceId: string;
+      value: EvidenceItemV2;
+    }
+  | {
+      target: "item";
+      action: "update";
+      evidenceId: string;
+      previousDigest: string;
+      value: EvidenceItemV2;
+    }
+  | {
+      target: "item";
+      action: "remove";
+      evidenceId: string;
+      previousDigest: string;
+      reasonCode: string;
+    }
+  | {
+      target: "binding";
+      action: "create";
+      bindingId: string;
+      value: EvidenceBindingV1;
+    }
+  | {
+      target: "binding";
+      action: "update";
+      bindingId: string;
+      previousDigest: string;
+      value: EvidenceBindingV1;
+    }
+  | {
+      target: "binding";
+      action: "remove";
+      bindingId: string;
+      previousDigest: string;
+      reasonCode: string;
+    };
+
+export interface EvidenceLifecycleTombstoneV1 {
+  target: EvidenceLifecycleTargetV1;
+  id: string;
+  previousDigest: string;
+  reasonCode: string;
+  removedByEventId: string;
+}
+
+export interface EvidenceStateAtCursorV1 {
+  schemaVersion: "archcontext.evidence-state-at-cursor/v1";
+  evidenceItems: EvidenceItemV2[];
+  evidenceBindings: EvidenceBindingV1[];
+  tombstones: EvidenceLifecycleTombstoneV1[];
+  stateDigest: string;
+}
+
+export type ArchitectureAffectedSubjectAuthorityClassV1 = "architecture-fact" | "evidence";
+export type ArchitectureAffectedSubjectKindV1 =
+  | "entity"
+  | "relation"
+  | "constraint"
+  | "evidence-item"
+  | "evidence-binding"
+  | "subject";
+export type ArchitectureAffectedSubjectOperationV1 = "create" | "update" | "remove" | "upsert" | "delete" | "reference";
+
+export interface ArchitectureAffectedSubjectV1 {
+  authorityClass: ArchitectureAffectedSubjectAuthorityClassV1;
+  subjectKind: ArchitectureAffectedSubjectKindV1;
+  subjectId: string;
+  operation: ArchitectureAffectedSubjectOperationV1;
+}
+
+export interface ArchitectureChangeFeedRecordV1 {
+  schemaVersion: "archcontext.architecture-change-feed-record/v1";
+  feedSequence: number;
+  repository: ArchitectureRepositoryIdentityV1;
+  worktree: ArchitectureWorktreeIdentityV1;
+  eventSequence: number;
+  eventId: string;
+  eventHash: string;
+  title?: string;
+  rationale?: string;
+  affectedSubjects: ArchitectureAffectedSubjectV1[];
+  subjectsDigest: string;
+  changedInputDigests: {
+    graphBefore: string;
+    graphAfter: string;
+    evidenceBefore: string;
+    evidenceAfter: string;
+  };
+  committedAt: string;
+}
+
+export interface ArchitectureChangeFeedBatchV1 {
+  schemaVersion: "archcontext.architecture-change-feed-batch/v1";
+  consumerId: string;
+  checkpoint: number;
+  records: ArchitectureChangeFeedRecordV1[];
+  hasMore: boolean;
+}
+
+export interface ArchitectureEventBacklinkV1 {
+  eventId: string;
+  subjectIds: string[];
+  title?: string;
+  rationale?: string;
+}
+
 export interface ArchitectureSubjectSelectorV1 {
   schemaVersion: typeof ARCHITECTURE_SUBJECT_SELECTOR_SCHEMA_VERSION;
   selectorId: string;
@@ -618,7 +740,7 @@ export function architectureEventHash(event: ArchitectureEventV1): string {
   return digestJson(hashable as unknown as Json);
 }
 
-export function architectureSnapshotDigest(snapshot: ArchitectureSnapshotV1): string {
+export function architectureSnapshotDigest(snapshot: ArchitectureSnapshotV2): string {
   const { snapshotId: _snapshotId, createdAt: _createdAt, extensions: _extensions, ...hashable } = snapshot;
   return digestJson(hashable as unknown as Json);
 }