archctx-contracts 0.2.2 → 0.3.0

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);
 }

package/src/ports.ts

@@ -1,4 +1,4 @@
-import type { Json } from "./schema";
+import { digestJson, type Json } from "./schema";
 import type {
   AgentJobV1,
   ArchitectureEventSource,
@@ -266,38 +266,371 @@ export interface ModelInteropImporter {
 export type ExplorerVerificationStatus = "MATCHED" | "DRIFT" | "UNKNOWN" | "VERIFIED";
 export type ExplorerPressureLevel = "low" | "medium" | "high";
 
-export interface ExplorerNodeView {
+export interface ExplorerServiceContract {
+  schemaVersion: "archcontext.explorer-service/v1";
+  bindHost: "127.0.0.1";
+  protocol: "http-loopback";
+  optIn: true;
+  defaultEnabled: false;
+  tokenTtlSeconds: number;
+  readOnly: true;
+  allowedMethods: ["GET"];
+  egress: "none";
+}
+
+export const EXPLORER_VIEW_IDS = ["system-map", "task-impact", "drift-pressure", "data-flow", "external-integrations"] as const;
+export type ExplorerViewIdV2 = typeof EXPLORER_VIEW_IDS[number];
+export type ExplorerSemanticLevelV2 = "overview" | "context" | "detail";
+export type ExplorerOccurrenceRoleV2 = "subject" | "derived-group";
+export type ExplorerSubjectRefKindV2 =
+  | "architecture-entity"
+  | "architecture-relation"
+  | "architecture-constraint"
+  | "code-symbol";
+
+export interface ExplorerExpectedCursorV2 {
+  headSha: string;
+  worktreeDigest: string;
+  graphDigest: string;
+  observedFactsDigest?: string;
+}
+
+export interface ExplorerProjectionQueryV2 {
+  schemaVersion: "archcontext.explorer-projection-query/v2";
+  viewId: ExplorerViewIdV2;
+  semanticLevel?: ExplorerSemanticLevelV2;
+  taskSessionId?: string;
+  expectedCursor?: ExplorerExpectedCursorV2;
+  focus?: { subjectId: string };
+  expandedOccurrenceIds?: string[];
+  depth: 0 | 1 | 2;
+  budget: {
+    maxNodes: number;
+    maxRelations: number;
+  };
+}
+
+export interface ExplorerProjectionCursorV2 {
+  repository: ArchitectureRepositoryIdentityV1;
+  worktree: ArchitectureWorktreeIdentityV1;
+  authoritySource: "git" | "ledger";
+  authorityCursor: AuthorityCursorV1 | null;
+  evidenceAuthorityCursor: AuthorityCursorV1 | null;
+  inputManifestDigest: string;
+  compatibilityDigest: string;
+  graphDigest: string;
+  evidenceStateDigest: string;
+  observedFactsDigest: string;
+  viewDefinitionDigest: string;
+  compilerVersion: "archcontext.explorer-view-compiler/v1";
+  taskSessionDigest?: string;
+  observedAvailability: { status: "ready" | "unavailable"; reasonCode?: string };
+}
+
+export interface ProjectionInputManifestV1 {
+  schemaVersion: "archcontext.projection-input-manifest/v1";
+  repository: ArchitectureRepositoryIdentityV1;
+  worktree: ArchitectureWorktreeIdentityV1;
+  authoritySource: "git" | "ledger";
+  authorityCursor: AuthorityCursorV1 | null;
+  evidenceAuthorityCursor: AuthorityCursorV1 | null;
+  queryDigest: string;
+  graphDigest: string;
+  evidenceStateDigest: string;
+  observedFactsDigest: string;
+  observedAvailability: { status: "ready" | "unavailable"; reasonCode?: string };
+  bindingsDigest: string;
+  eventBacklinksDigest: string;
+  driftDigest: string | null;
+  pressureDigest: string | null;
+  taskSessionDigest: string | null;
+  readPlan: ProjectionReadPlanV1;
+  readSet: ProjectionReadSetV1;
+  inputDomains: Record<ProjectionInputDomainV1, ProjectionInputDomainStateV1>;
+  viewDefinitionDigest: string;
+  compilerVersion: "archcontext.explorer-view-compiler/v1";
+  tokenRequired: boolean;
+  compatibilityDigest: string;
+  manifestDigest: string;
+}
+
+export type ProjectionInputDomainV1 =
+  | "authority"
+  | "graph"
+  | "evidence"
+  | "observed"
+  | "bindings"
+  | "event-backlinks"
+  | "drift"
+  | "pressure"
+  | "task-session";
+
+export type ProjectionInputDomainStateV1 =
+  | { requirement: "required"; status: "ready"; digest: string }
+  | { requirement: "optional"; status: "ready"; digest: string }
+  | { requirement: "optional"; status: "unavailable"; digest: null; reasonCode: string }
+  | { requirement: "not-used"; status: "not-used"; digest: null };
+
+export const EXPLORER_VIEW_INPUT_REQUIREMENTS = {
+  "system-map": {
+    authority: "required", graph: "required", evidence: "required", observed: "required", bindings: "required",
+    "event-backlinks": "optional", drift: "optional", pressure: "optional", "task-session": "optional"
+  },
+  "task-impact": {
+    authority: "required", graph: "required", evidence: "required", observed: "required", bindings: "required",
+    "event-backlinks": "optional", drift: "optional", pressure: "optional", "task-session": "required"
+  },
+  "drift-pressure": {
+    authority: "required", graph: "required", evidence: "required", observed: "required", bindings: "required",
+    "event-backlinks": "optional", drift: "required", pressure: "required", "task-session": "optional"
+  },
+  "data-flow": {
+    authority: "required", graph: "required", evidence: "required", observed: "required", bindings: "required",
+    "event-backlinks": "optional", drift: "optional", pressure: "optional", "task-session": "optional"
+  },
+  "external-integrations": {
+    authority: "required", graph: "required", evidence: "required", observed: "required", bindings: "required",
+    "event-backlinks": "optional", drift: "optional", pressure: "optional", "task-session": "optional"
+  }
+} as const satisfies Record<ExplorerViewIdV2, Record<ProjectionInputDomainV1, ProjectionInputDomainStateV1["requirement"]>>;
+
+export const PROJECTION_READ_PLANNER_VERSION = "archcontext.projection-read-planner/v1" as const;
+export const EXPLORER_PROJECTION_CACHE_POLICY_SCHEMA_VERSION = "archcontext.explorer-cache-policy/v1" as const;
+
+export interface ExplorerProjectionCachePolicyV1 {
+  schemaVersion: typeof EXPLORER_PROJECTION_CACHE_POLICY_SCHEMA_VERSION;
+  maxEntriesPerScope: number;
+  maxBytesPerScope: number;
+  maxAgeMs: number;
+  maxPinnedEntriesPerScope: number;
+  maxPinTtlMs: number;
+}
+
+export interface ProjectionReadPlanV1 {
+  schemaVersion: "archcontext.projection-read-plan/v1";
+  plannerVersion: typeof PROJECTION_READ_PLANNER_VERSION;
+  kind: "overview-aggregate" | "bounded-context" | "focused-neighborhood";
+  source: "git-authority" | "verified-ledger-current";
+  queryDigest: string;
+  semanticLevel: ExplorerSemanticLevelV2;
+  focusSubjectId: string | null;
+  expandedKinds: string[];
+  depth: 0 | 1 | 2;
+  limits: {
+    maxEntities: number;
+    maxRelations: number;
+    maxConstraints: number;
+    maxBindings: number;
+    maxBacklinks: number;
+    maxGraphRows: number;
+  };
+  requiredDomains: ProjectionInputDomainV1[];
+  ordering: "canonical-id-asc";
+  truncation: "hard-limit-with-authoritative-totals";
+  planDigest: string;
+}
+
+export interface ProjectionReadSetV1 {
+  schemaVersion: "archcontext.projection-read-set/v1";
+  planDigest: string;
+  selectedGraphDigest: string;
+  authoritativeTotals: { entities: number; relations: number; constraints: number };
+  entityKindTotals: Array<{ kind: string; count: number }>;
+  rowsRead: { entities: number; relations: number; constraints: number; bindings: number; backlinks: number };
+  truncated: boolean;
+  readSetDigest: string;
+}
+
+export function explorerProjectionQueryDigestV2(query: ExplorerProjectionQueryV2): string {
+  return digestJson({
+    schemaVersion: query.schemaVersion,
+    viewId: query.viewId,
+    semanticLevel: query.semanticLevel ?? "context",
+    taskSessionId: query.taskSessionId ?? null,
+    focus: query.focus ?? null,
+    expandedOccurrenceIds: [...new Set(query.expandedOccurrenceIds ?? [])].sort(),
+    depth: query.depth,
+    budget: query.budget
+  } as unknown as Json);
+}
+
+export function canonicalProjectionReadPlanV1(
+  query: ExplorerProjectionQueryV2,
+  source: ProjectionReadPlanV1["source"]
+): ProjectionReadPlanV1 {
+  if (
+    query.schemaVersion !== "archcontext.explorer-projection-query/v2"
+    || !(EXPLORER_VIEW_IDS as readonly string[]).includes(query.viewId)
+    || !Number.isInteger(query.depth) || query.depth < 0 || query.depth > 2
+    || !Number.isInteger(query.budget.maxNodes) || query.budget.maxNodes < 1 || query.budget.maxNodes > 1_000
+    || !Number.isInteger(query.budget.maxRelations) || query.budget.maxRelations < 0 || query.budget.maxRelations > 5_000
+  ) {
+    throw new Error("explorer-projection-query-invalid");
+  }
+  const semanticLevel = query.semanticLevel ?? "context";
+  const kind: ProjectionReadPlanV1["kind"] = semanticLevel === "overview"
+    ? "overview-aggregate"
+    : query.focus
+      ? "focused-neighborhood"
+      : "bounded-context";
+  const maxEntities = query.budget.maxNodes;
+  const maxRelations = query.budget.maxRelations;
+  const maxConstraints = Math.max(1, Math.min(2_000, maxEntities * 2));
+  const maxBindings = Math.max(1, Math.min(4_000, maxEntities * 4));
+  const maxBacklinks = Math.max(1, Math.min(8_000, maxEntities * 8));
+  const requirements = EXPLORER_VIEW_INPUT_REQUIREMENTS[query.viewId];
+  const withoutDigest = {
+    schemaVersion: "archcontext.projection-read-plan/v1" as const,
+    plannerVersion: PROJECTION_READ_PLANNER_VERSION,
+    kind,
+    source,
+    queryDigest: explorerProjectionQueryDigestV2(query),
+    semanticLevel,
+    focusSubjectId: query.focus?.subjectId ?? null,
+    expandedKinds: [...new Set((query.expandedOccurrenceIds ?? []).flatMap((id) => {
+      const prefix = `occurrence.${query.viewId}.group.kind.`;
+      return id.startsWith(prefix) ? [id.slice(prefix.length)] : [];
+    }))].sort(),
+    depth: query.depth,
+    limits: {
+      maxEntities,
+      maxRelations,
+      maxConstraints,
+      maxBindings,
+      maxBacklinks,
+      maxGraphRows: maxEntities + maxRelations + maxConstraints
+    },
+    requiredDomains: (Object.entries(requirements) as Array<[ProjectionInputDomainV1, ProjectionInputDomainStateV1["requirement"]]>)
+      .filter(([, requirement]) => requirement === "required")
+      .map(([domain]) => domain)
+      .sort(),
+    ordering: "canonical-id-asc" as const,
+    truncation: "hard-limit-with-authoritative-totals" as const
+  };
+  return { ...withoutDigest, planDigest: digestJson(withoutDigest as unknown as Json) };
+}
+
+export interface ExplorerSubjectRefV2 {
+  kind: ExplorerSubjectRefKindV2;
   id: string;
+}
+
+export interface ExplorerOccurrenceProvenanceV2 {
+  declaredEntityIds: string[];
+  observedSymbolIds: string[];
+  evidenceBindingIds: string[];
+}
+
+export type ExplorerAuthorityStateV2 = "BOUND" | "UNBOUND_OBSERVED" | "DECLARED_UNOBSERVED" | "DERIVED";
+
+export interface ExplorerPressureEvaluationV2 {
+  evaluated: boolean;
+  level?: ExplorerPressureLevel;
+  score?: number;
+  signals: string[];
+  inputDigest?: string;
+}
+
+export interface ExplorerInspectorV2 {
+  summary?: string;
+  responsibility?: string;
+  constraints: Array<{ id: string; kind: string; severity?: string; summary?: string }>;
+  decisions: Array<{ eventId: string; title?: string; rationale?: string }>;
+  historyEvents: Array<{ eventId: string; title?: string; rationale?: string }>;
+  sourceSelectors: SourceSelector[];
+  evidenceBindingIds: string[];
+}
+
+export interface ExplorerBacklinksV2 {
+  appearsInViews: ExplorerViewIdV2[];
+  affectedByTaskSessionIds: string[];
+  constrainedByIds: string[];
+  evidencedByBindingIds: string[];
+  changedByEventIds: string[];
+  decidedByEventIds: string[];
+  incomingRelationIds: string[];
+  outgoingRelationIds: string[];
+}
+
+export interface ExplorerSubjectOccurrenceV2 {
+  occurrenceId: string;
+  role: "subject";
+  parentOccurrenceId?: string;
+  subjectRefs: ExplorerSubjectRefV2[];
   name: string;
   kind: string;
-  repositoryId?: string;
+  childrenCount: number;
+  expandable: boolean;
   verificationStatus: ExplorerVerificationStatus;
-  pressure: {
-    level: ExplorerPressureLevel;
-    score: number;
-    signals: string[];
-  };
+  authorityState: ExplorerAuthorityStateV2;
+  pressure: ExplorerPressureEvaluationV2;
   sourceSelectors: SourceSelector[];
+  provenance: ExplorerOccurrenceProvenanceV2;
+  inspector: ExplorerInspectorV2;
+  backlinks: ExplorerBacklinksV2;
 }
 
-export interface ExplorerRelationView {
-  id: string;
-  source: string;
-  target: string;
+export interface ExplorerDerivedGroupOccurrenceV2 {
+  occurrenceId: string;
+  role: "derived-group";
+  parentOccurrenceId?: string;
+  subjectRefs: [];
+  name: string;
+  kind: string;
+  childrenCount: number;
+  expandable: boolean;
+  verificationStatus: "UNKNOWN";
+  authorityState: "DERIVED";
+  pressure: ExplorerPressureEvaluationV2;
+  sourceSelectors: [];
+  provenance: ExplorerOccurrenceProvenanceV2;
+  derivation: {
+    ruleId: string;
+    inputDigest: string;
+    compilerVersion: "archcontext.explorer-view-compiler/v1";
+  };
+}
+
+export type ExplorerOccurrenceV2 = ExplorerSubjectOccurrenceV2 | ExplorerDerivedGroupOccurrenceV2;
+
+export interface ExplorerRelationOccurrenceV2 {
+  occurrenceId: string;
+  sourceOccurrenceId: string;
+  targetOccurrenceId: string;
   kind: string;
   verificationStatus: ExplorerVerificationStatus;
+  provenance: {
+    declaredRelationIds: string[];
+    observedEdgeIds: string[];
+    evidenceBindingIds: string[];
+  };
 }
 
-export interface ExplorerProjection {
-  schemaVersion: "archcontext.explorer-projection/v1";
-  generatedAt: string;
-  repository: RepositorySnapshot;
-  nodes: ExplorerNodeView[];
-  relations: ExplorerRelationView[];
-  landscape?: Json;
-  verification: Json[];
-  pressure: Json[];
-  interventions: Json[];
+export interface ExplorerProjectionV2 {
+  schemaVersion: "archcontext.explorer-projection/v2";
+  view: {
+    id: ExplorerViewIdV2;
+    title: string;
+    question: string;
+  };
+  availableViews: Array<{ id: ExplorerViewIdV2; enabled: boolean; reason?: string }>;
+  semanticLevel: ExplorerSemanticLevelV2;
+  breadcrumbs: Array<{ occurrenceId: string; label: string }>;
+  cursor: ExplorerProjectionCursorV2;
+  inputManifest: ProjectionInputManifestV1;
+  occurrences: ExplorerOccurrenceV2[];
+  relations: ExplorerRelationOccurrenceV2[];
+  page: {
+    budget: { maxNodes: number; maxRelations: number };
+    totalNodes: number;
+    totalRelations: number;
+    returnedNodes: number;
+    returnedRelations: number;
+    truncated: boolean;
+    omittedNodeCount: number;
+    omittedRelationCount: number;
+  };
+  projectionDigest: string;
   capabilities: {
     readOnly: true;
     mutationMode: "forbidden";
@@ -306,16 +639,50 @@ export interface ExplorerProjection {
   };
 }
 
-export interface ExplorerServiceContract {
-  schemaVersion: "archcontext.explorer-service/v1";
-  bindHost: "127.0.0.1";
-  protocol: "http-loopback";
-  optIn: true;
-  defaultEnabled: false;
-  tokenTtlSeconds: number;
-  readOnly: true;
-  allowedMethods: ["GET"];
-  egress: "none";
+export interface AuthorityCursorV1 {
+  schemaVersion: "archcontext.authority-cursor/v1";
+  repository: ArchitectureRepositoryIdentityV1;
+  worktree: ArchitectureWorktreeIdentityV1;
+  eventSequence: number;
+  eventId: string;
+  eventHash: string;
+  graphDigest: string;
+  evidenceStateDigest: string;
+}
+
+export type ExplorerDeltaClassV2 = "architecture-fact" | "evidence" | "projection";
+
+export type ExplorerDeltaFailureReasonV2 =
+  | "invalid-delta-query"
+  | "projection-cache-miss"
+  | "authority-event-missing"
+  | "authority-cursor-reversed"
+  | "projection-authority-mismatch"
+  | "projection-manifest-incompatible";
+
+export interface ExplorerDeltaQueryV2 {
+  schemaVersion: "archcontext.explorer-delta-query/v2";
+  base: { eventId: string; projectionDigest: string };
+  head: { eventId: string; projectionDigest: string };
+}
+
+export interface ExplorerDeltaChangeV2 {
+  deltaClass: ExplorerDeltaClassV2;
+  subjectId: string;
+  change: "added" | "removed" | "changed";
+  fields: string[];
+  verificationTransition?: { from: ExplorerVerificationStatus; to: ExplorerVerificationStatus };
+}
+
+export interface ExplorerProjectionDeltaV2 {
+  schemaVersion: "archcontext.explorer-projection-delta/v2";
+  base: AuthorityCursorV1 & { projectionDigest: string; inputManifestDigest: string };
+  head: AuthorityCursorV1 & { projectionDigest: string; inputManifestDigest: string };
+  factChanges: ExplorerDeltaChangeV2[];
+  evidenceChanges: ExplorerDeltaChangeV2[];
+  projectionChanges: ExplorerDeltaChangeV2[];
+  counts: Record<ExplorerDeltaClassV2, number>;
+  deltaDigest: string;
 }
 
 export interface RetrievalConfig {

package/src/product-version.ts

@@ -1,9 +1,9 @@
 export const ARCHCONTEXT_PRODUCT_NAME = "archctx";
-export const ARCHCONTEXT_PRODUCT_VERSION = "0.2.2";
+export const ARCHCONTEXT_PRODUCT_VERSION = "0.3.0";
 export const ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.3.10";
 export const ARCHCONTEXT_NODE_RANGE = ">=24 <26";
 export const LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v1";
-export const ARCHCONTEXT_SCHEMA_SET_VERSION = "2026-06-25.al0-ledger";
+export const ARCHCONTEXT_SCHEMA_SET_VERSION = "2026-07-11.explorer-view-v2";
 
 export interface ProductVersionManifest {
   schemaVersion: "archcontext.product-version-manifest/v1";
@@ -41,7 +41,7 @@ export interface ProductVersionManifest {
     sqliteMigrations: string;
     codeGraph: {
       packageName: "@colbymchenry/codegraph";
-      requiredVersion: "1.0.1";
+      requiredVersion: "1.4.0";
       adapter: "codegraph-cli";
     };
   };
@@ -97,10 +97,10 @@ export function productVersionManifest(): ProductVersionManifest {
         schemaVersion: LOCAL_RUNTIME_RPC_SCHEMA_VERSION,
         protocol: "http-loopback"
       },
-      sqliteMigrations: "0001_runtime_state..0004_changeset_journal",
+      sqliteMigrations: "0001_runtime_state..0012_explorer_projection_index",
       codeGraph: {
         packageName: "@colbymchenry/codegraph",
-        requiredVersion: "1.0.1",
+        requiredVersion: "1.4.0",
         adapter: "codegraph-cli"
       }
     }

package/src/schema.ts

@@ -36,6 +36,7 @@ export interface ArchContextError {
   severity: Severity;
   retryable: boolean;
   action: string;
+  reasonCode?: string;
 }
 
 export interface JsonEnvelope<T extends Json = Json> {
@@ -71,12 +72,12 @@ export function okEnvelope<T extends Json>(requestId: string, data: T): JsonEnve
   return { schemaVersion: "archcontext.envelope/v1", ok: true, requestId, data };
 }
 
-export function errorEnvelope(requestId: string, code: ArchContextErrorCode, message: string): JsonEnvelope {
+export function errorEnvelope(requestId: string, code: ArchContextErrorCode, message: string, reasonCode?: string): JsonEnvelope {
   return {
     schemaVersion: "archcontext.envelope/v1",
     ok: false,
     requestId,
-    error: { ...ERROR_CATALOG[code], message }
+    error: { ...ERROR_CATALOG[code], message, ...(reasonCode ? { reasonCode } : {}) }
   };
 }