archctx-contracts 0.2.0 → 0.2.2

package/schemas/runtime/practice-checkpoint.schema.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archctx.repoharness.com/schemas/runtime/practice-checkpoint.schema.json",
+  "title": "PracticeCheckpoint",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "taskSessionId",
+    "event",
+    "headSha",
+    "worktreeDigest",
+    "fresh",
+    "reasonCode",
+    "staleReasons",
+    "changedPaths",
+    "catalogDigest",
+    "contextDigest",
+    "practiceGuidanceDigest",
+    "delta",
+    "noOpDigest",
+    "resultDigest",
+    "hook",
+    "nextSnapshot"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.practice-checkpoint/v1" },
+    "taskSessionId": { "type": "string", "minLength": 1 },
+    "event": { "enum": ["manual", "post-edit", "post-write", "pre-complete"] },
+    "headSha": { "type": "string", "minLength": 1 },
+    "expectedHeadSha": { "type": "string", "minLength": 1 },
+    "worktreeDigest": { "type": "string", "pattern": "^sha256:" },
+    "expectedWorktreeDigest": { "type": "string", "pattern": "^sha256:" },
+    "fresh": { "type": "boolean" },
+    "reasonCode": { "enum": ["fresh", "stale-head", "stale-worktree", "stale-catalog", "no-baseline", "no-op"] },
+    "staleReasons": {
+      "type": "array",
+      "items": { "enum": ["fresh", "stale-head", "stale-worktree", "stale-catalog", "no-baseline", "no-op"] }
+    },
+    "changedPaths": { "type": "array", "items": { "type": "string" } },
+    "toolCallId": { "type": "string" },
+    "catalogDigest": { "type": "string", "pattern": "^sha256:" },
+    "previousCatalogDigest": { "type": "string", "pattern": "^sha256:" },
+    "contextDigest": { "type": "string", "pattern": "^sha256:" },
+    "previousContextDigest": { "type": "string", "pattern": "^sha256:" },
+    "practiceGuidanceDigest": { "type": "string", "pattern": "^sha256:" },
+    "previousPracticeGuidanceDigest": { "type": "string", "pattern": "^sha256:" },
+    "delta": { "$ref": "#/$defs/delta" },
+    "noOpDigest": { "type": "string", "pattern": "^sha256:" },
+    "resultDigest": { "type": "string", "pattern": "^sha256:" },
+    "hook": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["egress", "failOpen", "pathCount", "network"],
+      "properties": {
+        "egress": { "const": "none" },
+        "failOpen": { "const": true },
+        "pathCount": { "type": "integer", "minimum": 0 },
+        "network": { "const": "forbidden" },
+        "pathSummary": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["schemaVersion", "total", "source", "generated", "ignored", "binary", "deleted", "renameHints"],
+          "properties": {
+            "schemaVersion": { "const": "archcontext.checkpoint-path-summary/v1" },
+            "total": { "type": "integer", "minimum": 0 },
+            "source": { "type": "integer", "minimum": 0 },
+            "generated": { "type": "integer", "minimum": 0 },
+            "ignored": { "type": "integer", "minimum": 0 },
+            "binary": { "type": "integer", "minimum": 0 },
+            "deleted": { "type": "integer", "minimum": 0 },
+            "renameHints": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "coalesced": { "type": "boolean" },
+        "skippedAnalysis": { "type": "boolean" },
+        "coalescedEventCount": { "type": "integer", "minimum": 1 },
+        "coalesceKey": { "type": "string", "pattern": "^sha256:" },
+        "elapsedMs": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "nextSnapshot": { "$ref": "#/$defs/snapshot" }
+  },
+  "$defs": {
+    "delta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "added", "removed", "upgraded", "downgraded", "unchanged", "requiresProof"],
+      "properties": {
+        "schemaVersion": { "const": "archcontext.practice-delta/v1" },
+        "added": { "type": "array", "items": { "$ref": "#/$defs/match" } },
+        "removed": { "type": "array", "items": { "$ref": "#/$defs/match" } },
+        "upgraded": { "type": "array", "items": { "$ref": "#/$defs/match" } },
+        "downgraded": { "type": "array", "items": { "$ref": "#/$defs/match" } },
+        "unchanged": { "type": "array", "items": { "$ref": "#/$defs/match" } },
+        "requiresProof": { "type": "array", "items": { "$ref": "#/$defs/match" } }
+      }
+    },
+    "match": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["schemaVersion", "practiceId", "assetDigest", "enforcement", "confidence"],
+      "properties": {
+        "schemaVersion": { "const": "archcontext.practice-match/v1" },
+        "practiceId": { "type": "string" },
+        "assetDigest": { "type": "string", "pattern": "^sha256:" },
+        "enforcement": { "enum": ["advisory", "checkpoint", "complete"] },
+        "confidence": { "enum": ["low", "medium", "high"] }
+      }
+    },
+    "snapshot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "task", "headSha", "worktreeDigest", "contextDigest", "practiceGuidanceDigest", "catalogDigest", "matches"],
+      "properties": {
+        "schemaVersion": { "const": "archcontext.practice-checkpoint-snapshot/v1" },
+        "task": { "type": "string" },
+        "headSha": { "type": "string" },
+        "worktreeDigest": { "type": "string", "pattern": "^sha256:" },
+        "contextDigest": { "type": "string", "pattern": "^sha256:" },
+        "practiceGuidanceDigest": { "type": "string", "pattern": "^sha256:" },
+        "catalogDigest": { "type": "string", "pattern": "^sha256:" },
+        "matches": { "type": "array", "items": { "$ref": "#/$defs/match" } }
+      }
+    }
+  }
+}

package/schemas/runtime/practice-guidance.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archctx.repoharness.com/schemas/runtime/practice-guidance.schema.json",
+  "title": "PracticeGuidance",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "catalogDigest", "overlayDigest", "matches", "constraints", "decisions", "realConstraints", "unknowns", "requiredCheckpoints", "resources"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.practice-guidance/v1" },
+    "catalogDigest": { "type": "string", "pattern": "^sha256:" },
+    "overlayDigest": { "type": "string", "pattern": "^sha256:" },
+    "matches": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["schemaVersion", "practiceId", "assetDigest"],
+        "properties": {
+          "schemaVersion": { "const": "archcontext.practice-match/v1" },
+          "practiceId": { "type": "string" },
+          "assetDigest": { "type": "string", "pattern": "^sha256:" }
+        }
+      }
+    },
+    "constraints": { "type": "array", "items": { "type": "string" } },
+    "decisions": { "type": "array", "items": { "type": "string" } },
+    "realConstraints": { "type": "array", "items": { "type": "string" } },
+    "unknowns": { "type": "array", "items": { "type": "string" } },
+    "requiredCheckpoints": { "type": "array", "items": { "type": "string" } },
+    "resources": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["type", "uri", "digest"],
+        "properties": {
+          "type": { "const": "practice" },
+          "uri": { "type": "string" },
+          "digest": { "type": "string", "pattern": "^sha256:" }
+        }
+      }
+    }
+  }
+}

package/schemas/runtime/practice-match.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archctx.repoharness.com/schemas/runtime/practice-match.schema.json",
+  "title": "PracticeMatch",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "practiceId", "assetRevision", "assetDigest", "title", "category", "score", "confidence", "enforcement", "matchedBy", "evidence", "explanation", "sourceTrust"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.practice-match/v1" },
+    "practiceId": { "type": "string" },
+    "assetRevision": { "type": "integer", "minimum": 1 },
+    "assetDigest": { "type": "string", "pattern": "^sha256:" },
+    "title": { "type": "string" },
+    "category": { "type": "string" },
+    "score": { "type": "number", "minimum": 0, "maximum": 100 },
+    "confidence": { "type": "string", "enum": ["low", "medium", "high"] },
+    "enforcement": { "type": "string", "enum": ["advisory", "checkpoint", "complete"] },
+    "matchedBy": {
+      "type": "array",
+      "items": { "type": "string", "enum": ["retrieval", "scope", "signal", "predicate", "repo-policy"] }
+    },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "strength", "subject"],
+        "properties": {
+          "kind": { "type": "string" },
+          "strength": { "type": "string", "enum": ["heuristic", "declared", "observed", "verified"] },
+          "subject": { "type": "string" },
+          "digest": { "type": "string", "pattern": "^sha256:" },
+          "observedAt": { "type": "string" }
+        }
+      }
+    },
+    "explanation": { "type": "array", "items": { "type": "string" } },
+    "sourceTrust": { "type": "string", "enum": ["repo-authored", "curated-static", "external-dynamic"] },
+    "suppressedReason": { "type": "string" }
+  }
+}

package/schemas/runtime/product-version-manifest.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archcontext.dev/schemas/runtime/product-version-manifest.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "product", "packageManager", "engines", "surfaces", "schemas", "runtime"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.product-version-manifest/v1" },
+    "product": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version", "distribution"],
+      "properties": {
+        "name": { "const": "archctx" },
+        "version": { "$ref": "#/$defs/semver" },
+        "distribution": { "enum": ["one-package"] }
+      }
+    },
+    "packageManager": { "type": "string", "minLength": 1 },
+    "engines": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["node"],
+      "properties": {
+        "node": { "const": ">=24 <26" }
+      }
+    },
+    "surfaces": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["cli", "daemon", "mcp"],
+      "properties": {
+        "cli": { "$ref": "#/$defs/surface" },
+        "daemon": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["packageName", "version", "entrypoint", "rpcSchemaVersion"],
+          "properties": {
+            "packageName": { "type": "string", "minLength": 1 },
+            "version": { "$ref": "#/$defs/semver" },
+            "entrypoint": { "type": "string", "minLength": 1 },
+            "rpcSchemaVersion": { "const": "archcontext.runtime-rpc/v1" }
+          }
+        },
+        "mcp": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["packageName", "version", "entrypoint", "transport"],
+          "properties": {
+            "packageName": { "type": "string", "minLength": 1 },
+            "version": { "$ref": "#/$defs/semver" },
+            "entrypoint": { "type": "string", "minLength": 1 },
+            "transport": { "enum": ["stdio"] }
+          }
+        }
+      }
+    },
+    "schemas": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaSetVersion", "contractsPackageVersion", "reviewChallenge", "attestation", "deviceIdentity", "runnerIdentity"],
+      "properties": {
+        "schemaSetVersion": { "type": "string", "minLength": 1 },
+        "contractsPackageVersion": { "$ref": "#/$defs/semver" },
+        "reviewChallenge": { "const": "archcontext.review-challenge/v2" },
+        "attestation": { "const": "archcontext.attestation/v2" },
+        "deviceIdentity": { "const": "archcontext.device-identity/v1" },
+        "runnerIdentity": { "const": "archcontext.runner-identity/v1" }
+      }
+    },
+    "runtime": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["localRpc", "sqliteMigrations", "codeGraph"],
+      "properties": {
+        "localRpc": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["schemaVersion", "protocol"],
+          "properties": {
+            "schemaVersion": { "const": "archcontext.runtime-rpc/v1" },
+            "protocol": { "enum": ["http-loopback"] }
+          }
+        },
+        "sqliteMigrations": { "type": "string", "minLength": 1 },
+        "codeGraph": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["packageName", "requiredVersion", "adapter"],
+          "properties": {
+            "packageName": { "const": "@colbymchenry/codegraph" },
+            "requiredVersion": { "type": "string", "minLength": 1 },
+            "adapter": { "enum": ["codegraph-cli"] }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "semver": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$"
+    },
+    "surface": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["packageName", "version", "entrypoint"],
+      "properties": {
+        "packageName": { "type": "string", "minLength": 1 },
+        "version": { "$ref": "#/$defs/semver" },
+        "entrypoint": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archcontext.dev/schemas/runtime/projection-target.schema.json",
+  "title": "ProjectionTarget",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "targetId", "type", "scope", "path", "ownership", "generatedRegion", "rendererVersion", "format", "sourceDigest", "outputDigest"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.projection-target/v1" },
+    "targetId": { "type": "string", "pattern": "^projection_target\\.[a-zA-Z0-9_.-]+$" },
+    "type": {
+      "type": "string",
+      "enum": ["architecture-index", "entity-summary", "relation-summary", "decision-index", "architecture-changelog", "diagram-mermaid", "diagram-structurizr", "diagram-likec4", "agent-context"]
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": {
+        "kind": { "type": "string", "enum": ["repository", "entity", "relation", "decision", "diagram", "changelog"] },
+        "id": { "type": "string" },
+        "entityKind": { "type": "string" }
+      }
+    },
+    "path": {
+      "type": "string",
+      "minLength": 1,
+      "not": {
+        "anyOf": [
+          { "pattern": "^/" },
+          { "pattern": "\\\\" },
+          { "pattern": "(^|/)\\.\\.(/|$)" }
+        ]
+      }
+    },
+    "ownership": { "type": "string", "enum": ["generated", "mixed"] },
+    "generatedRegion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["startMarker", "endMarker"],
+      "properties": {
+        "startMarker": { "type": "string", "minLength": 1 },
+        "endMarker": { "type": "string", "minLength": 1 }
+      }
+    },
+    "rendererVersion": { "type": "string", "minLength": 1 },
+    "format": { "type": "string", "enum": ["markdown", "mermaid", "structurizr-json", "likec4"] },
+    "sourceDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "outputDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "extensions": { "type": "object", "additionalProperties": true }
+  }
+}

package/schemas/runtime/recommendation-feedback.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archcontext.dev/schemas/runtime/recommendation-feedback.schema.json",
+  "title": "RecommendationFeedback",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "feedbackId", "recommendationId", "runId", "action", "previousStatus", "nextStatus", "actor", "reason", "explicit", "implicitAcceptance", "repository", "worktree", "createdAt"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.recommendation-feedback/v1" },
+    "feedbackId": { "type": "string", "pattern": "^(recommendation_feedback|rec_feedback)\\.[a-zA-Z0-9_.-]+$" },
+    "recommendationId": { "type": "string", "pattern": "^(recommendation|rec)\\.[a-zA-Z0-9_.-]+$" },
+    "runId": { "type": "string", "pattern": "^(recommendation_run|rec_run)\\.[a-zA-Z0-9_.-]+$" },
+    "action": { "enum": ["acknowledge", "accept", "reject", "defer", "waive", "resolve"] },
+    "previousStatus": { "enum": ["open", "acknowledged", "accepted", "rejected", "deferred", "waived", "resolved", "superseded", "expired"] },
+    "nextStatus": { "enum": ["open", "acknowledged", "accepted", "rejected", "deferred", "waived", "resolved", "superseded", "expired"] },
+    "actor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "source"],
+      "properties": {
+        "kind": { "enum": ["developer", "daemon", "hook", "cli", "mcp", "subagent", "migration", "system"] },
+        "id": { "type": "string", "minLength": 1 },
+        "source": { "enum": ["cli", "mcp", "manual", "daemon", "system", "subagent"] }
+      }
+    },
+    "reason": { "type": "string", "minLength": 1 },
+    "explicit": { "const": true },
+    "implicitAcceptance": { "const": false },
+    "repository": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repositoryId", "storageRepositoryId"],
+      "properties": {
+        "repositoryId": { "type": "string" },
+        "storageRepositoryId": { "type": "string" }
+      }
+    },
+    "worktree": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["workspaceId", "storageWorkspaceId", "branch", "headSha", "worktreeDigest"],
+      "properties": {
+        "workspaceId": { "type": "string" },
+        "storageWorkspaceId": { "type": "string" },
+        "branch": { "type": "string" },
+        "headSha": { "type": "string" },
+        "worktreeDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
+      }
+    },
+    "createdAt": { "type": "string" },
+    "extensions": { "type": "object", "additionalProperties": true }
+  }
+}

package/schemas/runtime/recommendation-run.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archcontext.dev/schemas/runtime/recommendation-run.schema.json",
+  "title": "RecommendationRun",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "runId", "repository", "worktree", "trigger", "engineVersion", "catalogDigest", "inputDigest", "outputDigest", "policyMode", "status", "startedAt", "recommendationIds", "metrics"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.recommendation-run/v1" },
+    "runId": { "type": "string", "pattern": "^rec_run\\.[a-zA-Z0-9_-]+$" },
+    "repository": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repositoryId", "storageRepositoryId"],
+      "properties": {
+        "repositoryId": { "type": "string" },
+        "storageRepositoryId": { "type": "string" }
+      }
+    },
+    "worktree": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["workspaceId", "storageWorkspaceId", "branch", "headSha", "worktreeDigest"],
+      "properties": {
+        "workspaceId": { "type": "string" },
+        "storageWorkspaceId": { "type": "string" },
+        "branch": { "type": "string" },
+        "headSha": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+        "worktreeDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
+      }
+    },
+    "trigger": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["level", "source"],
+      "properties": {
+        "level": { "enum": ["L0", "L1", "L2", "L3", "L4"] },
+        "source": { "enum": ["prepare_task", "checkpoint", "plan_update", "apply_update", "complete_task", "git_hook", "yaml_import", "projection_reconcile", "migration", "manual"] }
+      }
+    },
+    "engineVersion": { "type": "string" },
+    "catalogDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "inputDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "outputDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "policyMode": { "enum": ["advisory", "checkpoint", "complete"] },
+    "status": { "enum": ["queued", "running", "succeeded", "failed", "superseded"] },
+    "startedAt": { "type": "string" },
+    "completedAt": { "type": "string" },
+    "recommendationIds": { "type": "array", "items": { "type": "string" } },
+    "metrics": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["matchCount", "evidenceBindingCount", "unboundEvidenceCount"],
+      "properties": {
+        "matchCount": { "type": "integer", "minimum": 0 },
+        "evidenceBindingCount": { "type": "integer", "minimum": 0 },
+        "unboundEvidenceCount": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "extensions": { "type": "object", "additionalProperties": true }
+  }
+}

package/schemas/runtime/recommendation.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archcontext.dev/schemas/runtime/recommendation.schema.json",
+  "title": "Recommendation",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "recommendationId", "runId", "fingerprint", "subject", "status", "confidence", "enforcement", "risk", "uncertainty", "evidenceBindingIds", "explanation", "createdAt", "updatedAt"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.recommendation/v2" },
+    "recommendationId": { "type": "string", "pattern": "^rec\\.[a-zA-Z0-9_.-]+$" },
+    "runId": { "type": "string", "pattern": "^rec_run\\.[a-zA-Z0-9_-]+$" },
+    "fingerprint": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "subject": { "type": "string" },
+    "practiceId": { "type": "string" },
+    "status": { "enum": ["open", "acknowledged", "accepted", "rejected", "deferred", "waived", "resolved", "superseded", "expired"] },
+    "confidence": { "enum": ["low", "medium", "high"] },
+    "enforcement": { "enum": ["advisory", "checkpoint", "complete"] },
+    "risk": { "enum": ["low", "medium", "high"] },
+    "uncertainty": { "enum": ["low", "medium", "high"] },
+    "evidenceBindingIds": { "type": "array", "items": { "type": "string", "pattern": "^binding\\.[a-zA-Z0-9_.-]+$" } },
+    "explanation": { "type": "array", "items": { "type": "string" } },
+    "createdAt": { "type": "string" },
+    "updatedAt": { "type": "string" },
+    "extensions": { "type": "object", "additionalProperties": true }
+  }
+}

package/schemas/runtime/retrieval-config.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archctx.repoharness.com/schemas/runtime/retrieval-config.schema.json",
+  "title": "RetrievalConfig",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "defaultMode", "lexical", "embedding", "decisionGate"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.retrieval-config/v1" },
+    "defaultMode": { "type": "string", "enum": ["lexical"] },
+    "lexical": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["enabled", "tokenizer"],
+      "properties": {
+        "enabled": { "const": true },
+        "tokenizer": { "type": "string", "enum": ["english-normalized+jieba-search"] }
+      }
+    },
+    "embedding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["enabled", "provider", "dimensions", "egress"],
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "provider": { "type": "string", "enum": ["local-deterministic", "local-provider"] },
+        "dimensions": { "type": "integer", "minimum": 1 },
+        "indexPath": { "type": "string" },
+        "egress": { "type": "string", "enum": ["forbidden"] }
+      }
+    },
+    "decisionGate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["minContextRecallLift", "minConstraintRecallLift", "maxIrrelevantRatio", "maxToolCallIncrease"],
+      "properties": {
+        "minContextRecallLift": { "type": "number", "minimum": 0 },
+        "minConstraintRecallLift": { "type": "number", "minimum": 0 },
+        "maxIrrelevantRatio": { "type": "number", "minimum": 0, "maximum": 1 },
+        "maxToolCallIncrease": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/schemas/runtime/retrieval-decision.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archctx.repoharness.com/schemas/runtime/retrieval-decision.schema.json",
+  "title": "RetrievalDecisionRecord",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "decidedAt", "baseline", "candidate", "thresholds", "decision", "evidenceDigest"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.retrieval-decision/v1" },
+    "decidedAt": { "type": "string" },
+    "baseline": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "contextRecall", "constraintRecall", "irrelevantRatio", "toolCalls"],
+      "properties": {
+        "mode": { "type": "string", "enum": ["lexical"] },
+        "contextRecall": { "type": "number", "minimum": 0, "maximum": 1 },
+        "constraintRecall": { "type": "number", "minimum": 0, "maximum": 1 },
+        "irrelevantRatio": { "type": "number", "minimum": 0, "maximum": 1 },
+        "toolCalls": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "candidate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "contextRecall", "constraintRecall", "irrelevantRatio", "toolCalls"],
+      "properties": {
+        "mode": { "type": "string", "enum": ["embedding"] },
+        "contextRecall": { "type": "number", "minimum": 0, "maximum": 1 },
+        "constraintRecall": { "type": "number", "minimum": 0, "maximum": 1 },
+        "irrelevantRatio": { "type": "number", "minimum": 0, "maximum": 1 },
+        "toolCalls": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "thresholds": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["minContextRecallLift", "minConstraintRecallLift", "maxIrrelevantRatio", "maxToolCallIncrease"],
+      "properties": {
+        "minContextRecallLift": { "type": "number", "minimum": 0 },
+        "minConstraintRecallLift": { "type": "number", "minimum": 0 },
+        "maxIrrelevantRatio": { "type": "number", "minimum": 0, "maximum": 1 },
+        "maxToolCallIncrease": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "decision": { "type": "string", "enum": ["enable-embedding", "keep-lexical"] },
+    "evidenceDigest": { "type": "string" }
+  }
+}