archctx-contracts 0.8.0 → 0.9.0

package/fixtures/invalid/projection-pr-verification-unrendered-equivalence.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": "archcontext.projection-pr-verification/v1",
+  "base": "origin/main",
+  "baseSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "headSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+  "mergeBase": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "changedPaths": ["docs/architecture/modules/capability-app.md", "src/app.ts"],
+  "nonGeneratedPaths": ["src/app.ts"],
+  "humanEditedPaths": [],
+  "generatedOnly": false,
+  "renderEquivalent": true,
+  "differingPaths": [],
+  "projectionStatus": "noop",
+  "verdict": "touches-non-generated"
+}

package/fixtures/invalid/projection-publish-run-foreign-branch.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": "archcontext.projection-publish-run/v1",
+  "result": "published",
+  "remote": "origin",
+  "base": "main",
+  "branch": "main",
+  "baseSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "publishedCommit": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+  "pushed": true,
+  "pullRequest": null,
+  "publisher": "none",
+  "files": ["docs/architecture/modules/capability-app.md"],
+  "projectionStatus": "applied",
+  "humanActions": [],
+  "error": null,
+  "startedAt": "2026-10-20T08:00:00.000Z",
+  "finishedAt": "2026-10-20T08:00:09.000Z",
+  "iterations": 1
+}

package/fixtures/valid/archctx-capabilities.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "archcontext.capabilities/v1",
-  "package": { "name": "archctx", "version": "0.8.0" },
+  "package": { "name": "archctx", "version": "0.9.0" },
   "protocols": {
     "projectionRequest": "archcontext.projection-request/v1",
     "projectionResult": "archcontext.projection-result/v2",
@@ -10,5 +10,5 @@
     "architectureDocs": "archcontext.docs-renderer/v6",
     "agentContext": "archcontext.agent-context-renderer/v1"
   },
-  "features": ["architecture-change-capabilities-v1", "architecture-debt-v1", "architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "capability-dependencies-declared-v1", "capability-dependencies-v1", "changeset-entity-operations-v1", "changeset-ownership-delta-v1", "code-facts-unavailable-error-v1", "docs-anchors-v1", "flow-selector-check-v1", "module-statistics-v1", "native-context-export-v1", "projection-apply-readback-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-apply-replay-restore-v1", "projection-apply-replay-v1", "projection-architecture-debt-v1", "projection-capability-isolation-v1", "projection-change-classification-v1", "projection-check-freshness-v1", "projection-freshness-v1", "projection-manifest-contract-v3", "projection-observed-major-change-acceptance-v1", "projection-orphan-review-v1", "projection-preview-v1", "projection-prior-committed-applies-v1", "projection-protocol-v2", "projection-snapshot-v1", "recommendation-scan-decision-v1", "recommendation-v3", "refactor-assessment-v1", "refactor-observation-evidence-v1", "refactor-resolution-v1", "refactor-scan-limits-v1", "refactor-scan-untracked-count-v1"]
+  "features": ["architecture-change-capabilities-v1", "architecture-debt-v1", "architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "capability-dependencies-declared-v1", "capability-dependencies-v1", "changeset-entity-operations-v1", "changeset-ownership-delta-v1", "code-facts-unavailable-error-v1", "docs-anchors-v1", "flow-selector-check-v1", "module-statistics-v1", "native-context-export-v1", "projection-apply-readback-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-apply-replay-restore-v1", "projection-apply-replay-v1", "projection-architecture-debt-v1", "projection-capability-isolation-v1", "projection-change-classification-v1", "projection-check-freshness-v1", "projection-freshness-v1", "projection-manifest-contract-v3", "projection-observed-major-change-acceptance-v1", "projection-orphan-review-v1", "projection-preview-v1", "projection-prior-committed-applies-v1", "projection-protocol-v2", "projection-publish-v1", "projection-snapshot-v1", "projection-verify-pr-v1", "recommendation-scan-decision-v1", "recommendation-v3", "refactor-assessment-v1", "refactor-observation-evidence-v1", "refactor-resolution-v1", "refactor-scan-limits-v1", "refactor-scan-untracked-count-v1"]
 }

package/fixtures/valid/product-version-manifest.json

@@ -2,7 +2,7 @@
   "schemaVersion": "archcontext.product-version-manifest/v1",
   "product": {
     "name": "archctx",
-    "version": "0.8.0",
+    "version": "0.9.0",
     "distribution": "one-package"
   },
   "packageManager": "bun@1.4.3",
@@ -12,25 +12,25 @@
   "surfaces": {
     "cli": {
       "packageName": "@archcontext/surfaces",
-      "version": "0.8.0",
+      "version": "0.9.0",
       "entrypoint": "archctx"
     },
     "daemon": {
       "packageName": "@archcontext/local-runtime",
-      "version": "0.8.0",
+      "version": "0.9.0",
       "entrypoint": "archctx daemon start",
       "rpcSchemaVersion": "archcontext.runtime-rpc/v2"
     },
     "mcp": {
       "packageName": "@archcontext/surfaces",
-      "version": "0.8.0",
+      "version": "0.9.0",
       "entrypoint": "archctx mcp",
       "transport": "stdio"
     }
   },
   "schemas": {
     "schemaSetVersion": "2026-06-25.al0-ledger",
-    "contractsPackageVersion": "0.8.0",
+    "contractsPackageVersion": "0.9.0",
     "reviewChallenge": "archcontext.review-challenge/v2",
     "attestation": "archcontext.attestation/v2",
     "deviceIdentity": "archcontext.device-identity/v1",

package/fixtures/valid/projection-pr-verification.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": "archcontext.projection-pr-verification/v1",
+  "base": "origin/main",
+  "baseSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "headSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+  "mergeBase": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "changedPaths": ["docs/architecture/.projection-manifest.json", "docs/architecture/modules/capability-app.md"],
+  "nonGeneratedPaths": [],
+  "humanEditedPaths": [],
+  "generatedOnly": true,
+  "renderEquivalent": true,
+  "differingPaths": [],
+  "projectionStatus": "noop",
+  "verdict": "generated-only-render-equivalent"
+}

package/fixtures/valid/projection-publish-run.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": "archcontext.projection-publish-run/v1",
+  "result": "published",
+  "remote": "origin",
+  "base": "main",
+  "branch": "archctx/projection",
+  "baseSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "publishedCommit": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+  "pushed": true,
+  "pullRequest": { "url": "https://github.com/example/repo/pull/12", "number": 12 },
+  "publisher": "gh",
+  "files": ["docs/architecture/.projection-manifest.json", "docs/architecture/modules/capability-app.md"],
+  "projectionStatus": "applied",
+  "humanActions": [],
+  "error": null,
+  "startedAt": "2026-10-20T08:00:00.000Z",
+  "finishedAt": "2026-10-20T08:00:09.000Z",
+  "iterations": 1
+}

package/fixtures/valid/projection-publish-status.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": "archcontext.projection-publish-status/v1",
+  "remote": "origin",
+  "base": "main",
+  "branch": "archctx/projection",
+  "worktreePath": "/Users/example/Library/Application Support/ArchContext/repositories/repo.0123456789abcdef/projection-writer/0123456789abcdef/worktree",
+  "running": null,
+  "lastProcessedSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "lastSuccessfulSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "lastRun": {
+    "schemaVersion": "archcontext.projection-publish-run/v1",
+    "result": "failed",
+    "remote": "origin",
+    "base": "main",
+    "branch": "archctx/projection",
+    "baseSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "publishedCommit": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+    "pushed": true,
+    "pullRequest": null,
+    "publisher": "gh",
+    "files": ["docs/architecture/modules/capability-app.md"],
+    "projectionStatus": "applied",
+    "humanActions": [],
+    "error": { "code": "AC_PRECONDITION_FAILED", "reasonCode": "projection-publisher-failed", "message": "gh publisher failed: gh pr list failed: not logged in" },
+    "startedAt": "2026-10-20T08:00:00.000Z",
+    "finishedAt": "2026-10-20T08:00:09.000Z",
+    "iterations": 1
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archctx-contracts",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",

package/schemas/runtime/archctx-capabilities.schema.json

@@ -43,7 +43,7 @@
         "type": "string",
         "pattern": "^[a-z0-9]+(-[a-z0-9]+)*-v[0-9]+$",
         "description": "One feature flag: a lowercase kebab-case name that ends in a version suffix (-v1, -v2, ...). The pattern is open, so a validator built from this schema accepts flags that a later archctx adds. A consumer must ignore a flag it does not know. examples lists the flags this schema version knows.",
-        "examples": ["architecture-change-capabilities-v1", "architecture-debt-v1", "architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "capability-dependencies-declared-v1", "capability-dependencies-v1", "changeset-entity-operations-v1", "changeset-ownership-delta-v1", "code-facts-unavailable-error-v1", "docs-anchors-v1", "flow-selector-check-v1", "module-statistics-v1", "native-context-export-v1", "projection-apply-readback-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-apply-replay-restore-v1", "projection-apply-replay-v1", "projection-architecture-debt-v1", "projection-capability-isolation-v1", "projection-change-classification-v1", "projection-check-freshness-v1", "projection-freshness-v1", "projection-manifest-contract-v3", "projection-observed-major-change-acceptance-v1", "projection-orphan-review-v1", "projection-preview-v1", "projection-prior-committed-applies-v1", "projection-protocol-v2", "projection-snapshot-v1", "recommendation-scan-decision-v1", "recommendation-v3", "refactor-assessment-v1", "refactor-observation-evidence-v1", "refactor-resolution-v1", "refactor-scan-limits-v1", "refactor-scan-untracked-count-v1"]
+        "examples": ["architecture-change-capabilities-v1", "architecture-debt-v1", "architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "capability-dependencies-declared-v1", "capability-dependencies-v1", "changeset-entity-operations-v1", "changeset-ownership-delta-v1", "code-facts-unavailable-error-v1", "docs-anchors-v1", "flow-selector-check-v1", "module-statistics-v1", "native-context-export-v1", "projection-apply-readback-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-apply-replay-restore-v1", "projection-apply-replay-v1", "projection-architecture-debt-v1", "projection-capability-isolation-v1", "projection-change-classification-v1", "projection-check-freshness-v1", "projection-freshness-v1", "projection-manifest-contract-v3", "projection-observed-major-change-acceptance-v1", "projection-orphan-review-v1", "projection-preview-v1", "projection-prior-committed-applies-v1", "projection-protocol-v2", "projection-publish-v1", "projection-snapshot-v1", "projection-verify-pr-v1", "recommendation-scan-decision-v1", "recommendation-v3", "refactor-assessment-v1", "refactor-observation-evidence-v1", "refactor-resolution-v1", "refactor-scan-limits-v1", "refactor-scan-untracked-count-v1"]
       }
     }
   }

package/schemas/runtime/native-model-issue.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archctx.repoharness.com/schemas/runtime/native-model-issue.schema.json",
+  "title": "NativeModelIssue",
+  "description": "A native model schema or reference issue. Source paths are optional for callers that do not supply parsed record paths.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["entityId", "field", "invariant"],
+  "properties": {
+    "entityId": { "type": "string" },
+    "field": { "type": "string" },
+    "invariant": { "type": "string" },
+    "path": {
+      "type": "string",
+      "description": "The repository-relative path of the parsed source file that holds this record. It is not derived from the entity ID."
+    }
+  }
+}

package/schemas/runtime/projection-pr-verification.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archcontext.dev/schemas/runtime/projection-pr-verification.schema.json",
+  "title": "ProjectionPrVerificationV1",
+  "description": "Result of `archctx projection verify-pr --base <ref>` for the checked-out pull request head. A path is generated only when it is the projection manifest, a manifest target path or an agent-context target path at HEAD or at the merge base; for mixed-ownership targets the text outside the generated regions must also be unchanged. A diff with any other change is answered from the diff alone, with no render. generated-only-render-equivalent proves that the generated files and generated regions at HEAD equal a fresh render there and that no text outside those regions changed; it says nothing about whether the rendered content is desirable. The envelope is ok for every valid evaluation. Consumers detect it through the projection-verify-pr-v1 capability.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "base", "baseSha", "headSha", "mergeBase", "changedPaths", "nonGeneratedPaths", "humanEditedPaths", "generatedOnly", "renderEquivalent", "differingPaths", "projectionStatus", "verdict"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.projection-pr-verification/v1" },
+    "base": { "type": "string", "minLength": 1 },
+    "baseSha": { "$ref": "#/$defs/sha" },
+    "headSha": { "$ref": "#/$defs/sha" },
+    "mergeBase": { "$ref": "#/$defs/sha" },
+    "changedPaths": { "$ref": "#/$defs/paths", "description": "Paths changed between the merge base and HEAD, without rename detection, sorted." },
+    "nonGeneratedPaths": { "$ref": "#/$defs/paths", "description": "Changed paths that are not generated outputs: not the projection manifest, not a manifest target path and not an agent-context target path at HEAD or at the merge base, plus every humanEditedPaths entry." },
+    "humanEditedPaths": { "$ref": "#/$defs/paths", "description": "Mixed-ownership targets (manifest ownership mixed, and every agent-context target) whose text outside the generated regions differs between the merge base and HEAD, whose regions cannot be delimited, or which were added or deleted. They are also in nonGeneratedPaths and are never rendered." },
+    "generatedOnly": { "type": "boolean", "description": "True when the diff is non-empty and every changed path is a generated output with no change outside its generated regions." },
+    "renderEquivalent": { "type": ["boolean", "null"], "description": "Whether the generated files and regions at HEAD equal a fresh render (a check status of noop). Null when no render ran." },
+    "differingPaths": { "$ref": "#/$defs/paths", "description": "Paths the check would change at HEAD." },
+    "projectionStatus": { "type": ["string", "null"] },
+    "verdict": { "enum": ["generated-only-not-render-equivalent", "generated-only-render-equivalent", "no-changes", "touches-non-generated"] }
+  },
+  "allOf": [
+    { "if": { "properties": { "verdict": { "const": "generated-only-render-equivalent" } } }, "then": { "properties": { "generatedOnly": { "const": true }, "renderEquivalent": { "const": true }, "nonGeneratedPaths": { "maxItems": 0 }, "humanEditedPaths": { "maxItems": 0 } } } },
+    { "if": { "properties": { "verdict": { "const": "generated-only-not-render-equivalent" } } }, "then": { "properties": { "generatedOnly": { "const": true }, "renderEquivalent": { "const": false }, "nonGeneratedPaths": { "maxItems": 0 }, "humanEditedPaths": { "maxItems": 0 } } } },
+    { "if": { "properties": { "verdict": { "const": "touches-non-generated" } } }, "then": { "properties": { "generatedOnly": { "const": false }, "renderEquivalent": { "type": "null" }, "nonGeneratedPaths": { "minItems": 1 } } } },
+    { "if": { "properties": { "verdict": { "const": "no-changes" } } }, "then": { "properties": { "generatedOnly": { "const": false }, "renderEquivalent": { "type": "null" }, "changedPaths": { "maxItems": 0 }, "humanEditedPaths": { "maxItems": 0 } } } }
+  ],
+  "$defs": {
+    "sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+    "paths": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+  }
+}

package/schemas/runtime/projection-publish-run.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archcontext.dev/schemas/runtime/projection-publish-run.schema.json",
+  "title": "ProjectionPublishRunV1",
+  "description": "One run of `archctx projection publish` (the envelope data, and the writer state's lastRun). The writer keeps one rolling archctx/* branch equal to the base tip plus exactly one commit that touches generated projection outputs only. Every result except failed is an ok envelope. Consumers detect it through the projection-publish-v1 capability.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "result", "remote", "base", "branch", "baseSha", "publishedCommit", "pushed", "pullRequest", "publisher", "files", "projectionStatus", "humanActions", "error", "startedAt", "finishedAt", "iterations"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.projection-publish-run/v1" },
+    "result": { "enum": ["already-processed", "busy", "failed", "human-action-required", "published", "up-to-date"] },
+    "remote": { "type": "string", "minLength": 1 },
+    "base": { "type": "string", "minLength": 1 },
+    "branch": { "type": "string", "pattern": "^archctx/.+", "description": "The rolling branch. The writer never pushes to any ref outside archctx/." },
+    "baseSha": { "oneOf": [{ "$ref": "#/$defs/sha" }, { "type": "null" }], "description": "The base tip this run evaluated; null when the run stopped before resolving one." },
+    "publishedCommit": { "oneOf": [{ "$ref": "#/$defs/sha" }, { "type": "null" }], "description": "The rolling branch tip that carries this base's projection, pushed by this run or an earlier one." },
+    "pushed": { "type": "boolean", "description": "True only when this run moved the remote rolling branch." },
+    "pullRequest": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "url": { "type": "string", "minLength": 1 },
+            "number": { "type": "integer", "minimum": 1 }
+          }
+        },
+        { "type": "null" }
+      ]
+    },
+    "publisher": { "enum": ["command", "gh", "none"] },
+    "files": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "description": "Repository-relative generated paths the published commit changes, sorted. Paths only, never contents." },
+    "projectionStatus": { "type": ["string", "null"], "description": "ProjectionResultV2.status of the apply this run made, or null without one." },
+    "humanActions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["reasonCode"],
+        "properties": {
+          "reasonCode": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+          "path": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "error": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["code", "message"],
+          "properties": {
+            "code": { "type": "string", "pattern": "^AC_[A-Z0-9_]+$" },
+            "reasonCode": { "type": "string", "minLength": 1 },
+            "message": { "type": "string" }
+          }
+        },
+        { "type": "null" }
+      ]
+    },
+    "startedAt": { "type": "string", "minLength": 1 },
+    "finishedAt": { "type": "string", "minLength": 1 },
+    "iterations": { "type": "integer", "minimum": 0, "maximum": 3, "description": "Base tips evaluated in this run; above 1 when the base moved while the run worked." },
+    "holderPid": { "type": "integer", "minimum": 1, "description": "Present on busy: the pid of the live writer that holds the lock." }
+  },
+  "allOf": [
+    { "if": { "properties": { "result": { "const": "failed" } } }, "then": { "properties": { "error": { "type": "object" } } }, "else": { "properties": { "error": { "type": "null" } } } },
+    { "if": { "properties": { "result": { "const": "busy" } } }, "then": { "required": ["holderPid"] }, "else": { "not": { "required": ["holderPid"] } } },
+    { "if": { "properties": { "result": { "const": "published" } } }, "then": { "properties": { "publishedCommit": { "$ref": "#/$defs/sha" }, "baseSha": { "$ref": "#/$defs/sha" } } } }
+  ],
+  "$defs": {
+    "sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }
+  }
+}

package/schemas/runtime/projection-publish-status.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archcontext.dev/schemas/runtime/projection-publish-status.schema.json",
+  "title": "ProjectionPublishStatusV1",
+  "description": "Read-only result of `archctx projection publish-status`: the projection writer state for one (remote, base), shared by every checkout of the repository. Consumers detect it through the projection-publish-v1 capability.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "remote", "base", "branch", "worktreePath", "running", "lastProcessedSha", "lastSuccessfulSha", "lastRun"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.projection-publish-status/v1" },
+    "remote": { "type": "string", "minLength": 1 },
+    "base": { "type": "string", "minLength": 1 },
+    "branch": { "oneOf": [{ "type": "string", "pattern": "^archctx/.+" }, { "type": "null" }], "description": "The rolling branch of the last locked run, or null before the first." },
+    "worktreePath": { "type": "string", "minLength": 1, "description": "The writer-owned worktree; run `codegraph init <worktreePath>` once when code facts are required." },
+    "running": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["pid", "startedAt"],
+          "properties": {
+            "pid": { "type": "integer", "minimum": 1 },
+            "startedAt": { "type": "string" }
+          }
+        },
+        { "type": "null" }
+      ]
+    },
+    "lastProcessedSha": { "oneOf": [{ "$ref": "#/$defs/sha" }, { "type": "null" }], "description": "The last base tip a run evaluated." },
+    "lastSuccessfulSha": { "oneOf": [{ "$ref": "#/$defs/sha" }, { "type": "null" }], "description": "The last base tip a run published or found up to date." },
+    "lastRun": { "oneOf": [{ "$ref": "projection-publish-run.schema.json" }, { "type": "null" }] }
+  },
+  "$defs": {
+    "sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }
+  }
+}

package/src/failure.ts

@@ -23,6 +23,16 @@ export interface FailureEnvelope<C extends FailureCode = FailureCode> {
   error: StrictFailure<C>;
 }
 type Policy = { code: FailureCode; message: string; fields?: readonly string[]; action?: string; facts?: Readonly<Record<string, string>>; native?: boolean; recovery?: boolean; journalRecovery?: boolean; retryable?: boolean };
+/** Closed repository diagnostics. Messages contain no process output or filesystem paths. */
+export const CODE_FACTS_ISSUE_MESSAGES = Object.freeze({
+  "not-initialized": "CodeGraph repository status is not initialized",
+  "version-mismatch": "CodeGraph repository status version mismatch",
+  "project-path-mismatch": "CodeGraph repository project path mismatch",
+  "index-incomplete": "CodeGraph repository index is not complete and compatible",
+  "extraction-version-mismatch": "CodeGraph repository extraction version mismatch",
+  "worktree-mismatch": "CodeGraph repository worktree mismatch",
+  "pending-source-changes": "CodeGraph repository index has pending or unreported source changes"
+});
 /** Each reason has a closed fact vocabulary. No source text or recovery binding is a summary fact. */
 const policies: Record<string, Policy> = {
   "git-worktree-required": { code: "AC_REPO_NOT_FOUND", message: "This operation requires a Git worktree.", fields: ["checks"] },
@@ -33,6 +43,7 @@ const policies: Record<string, Policy> = {
   "projection-manifest-invalid": { code: "AC_PRECONDITION_FAILED", message: "The committed projection manifest violates its contract." },
   "projection-footprint-uncovered": { code: "AC_PRECONDITION_FAILED", message: "Declared source footprints lack a projection target." },
   "index-missing": { code: "AC_CODE_FACTS_UNAVAILABLE", message: "Required code facts have no available index. Run codegraph init." },
+  "code-facts-not-ready": { code: "AC_CODE_FACTS_NOT_READY", message: "Repository code facts are not ready. Run archctx doctor --json and follow the reported action.", facts: { issues: "codeFactsIssues" } },
   "checkpoint-input-invalid": { code: "AC_SCHEMA_INVALID", message: "Checkpoint arguments violate the declared input schema.", fields: ["issueCount"], action: "correct-command-arguments" },
   "cli-input-invalid": { code: "AC_SCHEMA_INVALID", message: "Command arguments violate the declared input contract.", action: "correct-command-arguments" },
   "complete-input-invalid": { code: "AC_SCHEMA_INVALID", message: "Completion input violates the caller authority contract.", action: "correct-command-arguments" },
@@ -41,7 +52,7 @@ const policies: Record<string, Policy> = {
   "runtime-version-unsupported": { code: "AC_RUNTIME_VERSION_UNSUPPORTED", message: "The connected runtime version is unsupported." },
   "rpc-timeout": { code: "RPC_TIMEOUT", message: "The runtime RPC deadline elapsed without a response; a mutation outcome is unknown.", fields: ["method", "timeoutMs", "elapsedMs", "mutationOutcome"], action: "reconcile-before-retry" },
   "rpc-aborted": { code: "RPC_ABORTED", message: "The runtime RPC caller aborted without a response; a mutation outcome is unknown.", fields: ["method", "timeoutMs", "elapsedMs", "mutationOutcome"], action: "reconcile-before-retry" },
-  "failure-unclassified": { code: "AC_UNCLASSIFIED_FAILURE", message: "The operation failed without a classified cause. Inspect local diagnostics before retrying.", action: "inspect-diagnostics" },
+  "failure-unclassified": { code: "AC_UNCLASSIFIED_FAILURE", message: "The operation failed without a classified cause. Run archctx doctor --json before retrying.", action: "inspect-diagnostics" },
 };
 // C1 policies are selected at explicit producer branches, never from diagnostic text.
 Object.assign(policies, {
@@ -278,7 +289,7 @@ for (const policy of Object.values(policies)) {
 }
 export const FAILURE_POLICIES: Readonly<Record<string, Readonly<Policy>>> = Object.freeze(policies);
 const catalogDefaults = Object.fromEntries(Object.entries(ERROR_CATALOG).map(([code, value]) => [code, Object.freeze({ severity: value.severity, retryable: value.retryable, action: value.action })])) as Readonly<Record<ArchContextErrorCode, Readonly<Pick<StrictFailure, "severity" | "retryable" | "action">>>>;
-const actions = new Set([...Object.values(catalogDefaults).map(value => value.action), "correct-command-arguments", "inspect-diagnostics", "reconcile-before-retry", ...Object.values(policies).flatMap(policy => policy.action ? [policy.action] : [])]);
+const actions = new Set([...Object.values(catalogDefaults).map(value => value.action), "correct-command-arguments", "inspect-diagnostics", "reconcile-before-retry", "install-compatible-codegraph", ...Object.values(policies).flatMap(policy => policy.action ? [policy.action] : [])]);
 const bytes = (value: string) => new TextEncoder().encode(value).byteLength;
 const record = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
 const finiteNonnegative = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value >= 0;
@@ -400,6 +411,20 @@ const localEnums: Readonly<Record<string, readonly string[]>> = {
   ]
 };
 function localFactValue(rule: string, value: unknown): Json {
+  if (rule === "codeFactsIssues") {
+    if (!Array.isArray(value)) throw new Error("Code facts issues must be a list");
+    const length = Object.getOwnPropertyDescriptor(value, "length")?.value;
+    if (!Number.isSafeInteger(length) || length < 1 || length > 32 || Reflect.ownKeys(value).length !== length + 1) throw new Error("Code facts issues exceed their closed budget");
+    return Array.from({ length }, (_, index) => {
+      const entry = Object.getOwnPropertyDescriptor(value, String(index));
+      if (!entry || !("value" in entry)) throw new Error("Code facts issues must use own data");
+      const fields = dataRecord(entry.value);
+      const code = fields.code?.value, message = fields.message?.value;
+      if (Object.keys(fields).length !== 2 || typeof code !== "string" || !Object.hasOwn(CODE_FACTS_ISSUE_MESSAGES, code)
+        || message !== CODE_FACTS_ISSUE_MESSAGES[code as keyof typeof CODE_FACTS_ISSUE_MESSAGES]) throw new Error("Unknown code facts diagnostic");
+      return { code, message };
+    });
+  }
   if (rule === "commandSuggestion" && (value === null || (typeof value === "string" && bytes(value) <= 1024 && /^archctx (recommendations |refactor verify )[^\r\n]*$/.test(value)))) return value;
   if (rule === "publicConfirmationToken" && typeof value === "string" && bytes(value) <= 1024 && /^public:github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+:[a-f0-9]{40}:[A-Za-z0-9_.:-]+$/.test(value)) return value;
   if (rule === "diagnosticPaths" || rule === "diagnosticCommands") {
@@ -568,7 +593,7 @@ function nativeFactsFor(policy: Policy, input: unknown): {[key: string]: Json} {
     if (type === "diagnostic") { const s = text(value); if (bytes(s) > 256) { omit(s); return undefined; } return s; }
     const item = dataRecord(value);
     if (type === "issues") {
-      if (Object.keys(item).length !== 3 || !["entityId", "field", "invariant"].every(key => Object.hasOwn(item, key))) throw new Error("Native issue schema is invalid");
+      if (!["entityId", "field", "invariant"].every(key => Object.hasOwn(item, key)) || Object.keys(item).some(key => !["entityId", "field", "invariant", "path"].includes(key))) throw new Error("Native issue schema is invalid");
       const clean = Object.fromEntries(Object.entries(item).map(([key, data]) => [key, text(data.value)]));
       if (Object.values(clean).some(v => bytes(v) > 256)) { omit(clean); return undefined; }
       return clean;
@@ -616,12 +641,21 @@ function nativeFactsFor(policy: Policy, input: unknown): {[key: string]: Json} {
     }
     result[key] = values;
   }
+  const sourceIssues = Array.isArray(result.issues) ? result.issues as Array<Record<string, Json>> : [];
+  // Legacy issues without source paths keep any explicit path supplied by the caller.
+  const summarizePath = sourceIssues.some(issue => typeof issue.path === "string");
   const counts = () => {
     if (!Number.isSafeInteger(omitted) || !Number.isSafeInteger(characters)) throw new Error("Native diagnostic counts exceed schema");
     if (omitted) result.omittedDiagnosticCount = omitted;
     if (characters) result.omittedDiagnosticCharacters = characters;
   };
   const fits = () => {
+    // Derive the summary from surviving whole issues, including after budget omission.
+    if (summarizePath) {
+      const path = sourceIssues[0]?.path;
+      if (typeof path === "string" && sourceIssues.every(issue => issue.path === path)) result.path = path;
+      else delete result.path;
+    }
     counts();
     const base = catalogDefaults[policy.code as ArchContextErrorCode];
     const error = {code: policy.code, message: policy.message, severity: base.severity, retryable: policy.retryable ?? base.retryable, action: policy.action ?? base.action, reasonCode: Object.entries(policies).find(([, p]) => p === policy)?.[0], details: result};

package/src/index.ts

@@ -11,6 +11,7 @@ export * from "./ports";
 export * from "./practices";
 export * from "./projection";
 export * from "./projection-recovery";
+export * from "./projection-writer";
 export * from "./projection-manifest";
 export * from "./product-version";
 export * from "./refactor";

package/src/native-context.ts

@@ -149,7 +149,7 @@ export function nativeByteCompare(left: string, right: string): number {
 
 type SchemaDocument = Parameters<typeof validateJsonSchema>[0];
 export interface NativeContextSchemas { node: SchemaDocument; relation: SchemaDocument; flow: SchemaDocument }
-export interface NativeModelIssue { entityId: string; field: string; invariant: string }
+export interface NativeModelIssue { entityId: string; field: string; invariant: string; path?: string }
 
 /** Fixed canonical documents are supplied by the bundled reader, never by repository input. */
 export function nativeContextSchemaResolver(schemas: NativeContextSchemas): JsonSchemaResolver {
@@ -162,10 +162,14 @@ export function nativeAllowedNodeKinds(schemas: NativeContextSchemas): string[]
   return [...kinds] as string[];
 }
 
-/** Complete native shape/reference validation; no filesystem, symbols, runtime or mutation. */
-export function nativeContextModelIssues(model: NativeContextModel, schemas: NativeContextSchemas): NativeModelIssue[] {
+/** Complete native shape/reference validation; optional paths bind parsed records, never IDs. */
+export function nativeContextModelIssues(model: NativeContextModel, schemas: NativeContextSchemas, recordPaths?: ReadonlyMap<NativeModelRecord, string>): NativeModelIssue[] {
   const issues: NativeModelIssue[] = [];
-  const add = (entityId: string, field: string, invariant: string) => issues.push({ entityId, field, invariant });
+  const add = (record: NativeModelRecord | string, field: string, invariant: string) => {
+    const entityId = typeof record === "string" ? record : typeof record.id === "string" ? record.id : "(undeclared)";
+    const path = typeof record === "string" ? undefined : recordPaths?.get(record);
+    issues.push({ entityId, field, invariant, ...(path === undefined ? {} : { path }) });
+  };
   const resolveSchema = nativeContextSchemaResolver(schemas);
   const ids = new Set<string>();
   for (const [kind, records] of [["node", model.nodes], ["relation", model.relations], ["flow", model.flows]] as const) {
@@ -182,46 +186,45 @@ export function nativeContextModelIssues(model: NativeContextModel, schemas: Nat
         const item = pending.pop()!;
         const value = item.value;
         if (item.exit) { active.delete(value as object); done.add(value as object); continue; }
-        if (typeof value === "number" && !Number.isFinite(value)) { add(id, item.field, "non-json-number"); jsonInvalid = true; break; }
+        if (typeof value === "number" && !Number.isFinite(value)) { add(record, item.field, "non-json-number"); jsonInvalid = true; break; }
         if (value === null || typeof value !== "object") continue;
-        if (active.has(value)) { add(id, item.field, "non-json-cycle"); jsonInvalid = true; break; }
+        if (active.has(value)) { add(record, item.field, "non-json-cycle"); jsonInvalid = true; break; }
         if (done.has(value)) continue;
         const prototype = Object.getPrototypeOf(value);
-        if (Array.isArray(value) ? prototype !== Array.prototype : prototype !== Object.prototype) { add(id, item.field, "non-json-prototype"); jsonInvalid = true; break; }
+        if (Array.isArray(value) ? prototype !== Array.prototype : prototype !== Object.prototype) { add(record, item.field, "non-json-prototype"); jsonInvalid = true; break; }
         active.add(value); pending.push({ value, field: item.field, exit: true });
         for (const [key, child] of Object.entries(value)) pending.push({ value: child, field: `${item.field}.${key}` });
       }
       if (jsonInvalid) continue;
       const schema = kind === "node" ? schemas.node : kind === "relation" ? schemas.relation : schemas.flow;
-      for (const issue of validateJsonSchema(schema, record, { resolveSchema }).issues) add(id, issue.path, issue.message);
-      if (ids.has(id)) add(id, "id", "duplicate-entity-id");
+      for (const issue of validateJsonSchema(schema, record, { resolveSchema }).issues) add(record, issue.path, issue.message);
+      if (ids.has(id)) add(record, "id", "duplicate-entity-id");
       ids.add(id);
     }
   }
   // Invalid shapes cannot safely participate in reference validation.
   if (issues.length > 0) return issues;
   for (const kind of ["nodes", "relations", "flows"] as const) {
-    const expected = new Set(model[kind].map(entity => entity.id as string));
-    for (const id of expected) if (!Object.hasOwn(model.sourcePaths[kind], id)) add(id, `sourcePaths.${kind}`, "source-path-index-incomplete");
+    const expected = new Map(model[kind].map(entity => [entity.id as string, entity]));
+    for (const [id, entity] of expected) if (!Object.hasOwn(model.sourcePaths[kind], id)) add(entity, `sourcePaths.${kind}`, "source-path-index-incomplete");
     for (const [id, path] of Object.entries(model.sourcePaths[kind])) {
       if (!expected.has(id)) add(id, `sourcePaths.${kind}`, "source-path-index-unknown-entity");
-      if (!isNativeContextPath(path)) add(id, `sourcePaths.${kind}`, "path-unsafe");
+      if (!isNativeContextPath(path)) add(expected.get(id) ?? id, `sourcePaths.${kind}`, "path-unsafe");
     }
   }
   const nodes = new Map(model.nodes.map(node => [node.id as string, node]));
   const checked = new Set<string>();
   for (const node of model.nodes) {
-    const id = node.id as string;
     const chain = new Set<string>();
     let cursor: NativeModelRecord | undefined = node;
     while (cursor) {
       const current = cursor.id as string;
-      if (chain.has(current)) { add(id, "parent", "parent-cycle"); break; }
+      if (chain.has(current)) { add(node, "parent", "parent-cycle"); break; }
       if (checked.has(current)) break;
       chain.add(current);
       if (cursor.parent === undefined) break;
       const parent = nodes.get(cursor.parent as string);
-      if (!parent) { add(current, "parent", "parent-node-missing"); break; }
+      if (!parent) { add(cursor, "parent", "parent-node-missing"); break; }
       cursor = parent;
     }
     for (const current of chain) checked.add(current);
@@ -229,48 +232,47 @@ export function nativeContextModelIssues(model: NativeContextModel, schemas: Nat
   const selectors = new Set<string>();
   for (const node of model.nodes) {
     const source = node.source as { include?: string[]; exclude?: string[]; entrypoints?: Array<{ id: string; path: string; symbols: Array<{ name: string; sinks: Array<{ id: string; path: string; symbol: string }> }> }> } | undefined;
-    for (const path of [...source?.include ?? [], ...source?.exclude ?? []]) if (!isNativeContextPath(path)) add(node.id as string, "source", "path-unsafe");
+    for (const path of [...source?.include ?? [], ...source?.exclude ?? []]) if (!isNativeContextPath(path)) add(node, "source", "path-unsafe");
     for (const entry of source?.entrypoints ?? []) {
-      if (!isNativeContextPath(entry.path)) add(node.id as string, "source.entrypoints.path", "path-unsafe");
+      if (!isNativeContextPath(entry.path)) add(node, "source.entrypoints.path", "path-unsafe");
       for (const symbol of entry.symbols) {
         for (const sink of symbol.sinks) {
-          if (!isNativeContextPath(sink.path)) add(node.id as string, "source.entrypoints.symbols.sinks.path", "path-unsafe");
+          if (!isNativeContextPath(sink.path)) add(node, "source.entrypoints.symbols.sinks.path", "path-unsafe");
           const selector = JSON.stringify([entry.id, symbol.name, sink.id]);
-          if (selectors.has(selector)) add(node.id as string, "source.entrypoints.symbols.sinks.id", "selector-ambiguous");
+          if (selectors.has(selector)) add(node, "source.entrypoints.symbols.sinks.id", "selector-ambiguous");
           selectors.add(selector);
         }
       }
     }
   }
   for (const relation of model.relations) {
-    for (const field of ["source", "target", "via"] as const) if (relation[field] !== undefined && !nodes.has(relation[field] as string)) add(relation.id as string, field, "relation-node-missing");
+    for (const field of ["source", "target", "via"] as const) if (relation[field] !== undefined && !nodes.has(relation[field] as string)) add(relation, field, "relation-node-missing");
   }
   for (const flow of model.flows) {
-    const id = flow.id as string;
-    if (nodes.get(flow.capabilityId as string)?.kind !== "capability") add(id, "capabilityId", "flow-capability-missing");
+    if (nodes.get(flow.capabilityId as string)?.kind !== "capability") add(flow, "capabilityId", "flow-capability-missing");
     if (flow.applicability !== "required") continue;
     const participants = flow.participants as Array<{ id: string; nodeId: string }>;
     const participantIds = new Set<string>();
     for (const participant of participants) {
-      if (participantIds.has(participant.id)) add(id, "participants.id", "participant-id-ambiguous");
+      if (participantIds.has(participant.id)) add(flow, "participants.id", "participant-id-ambiguous");
       participantIds.add(participant.id);
-      if (!nodes.has(participant.nodeId)) add(id, "participants.nodeId", "participant-node-missing");
+      if (!nodes.has(participant.nodeId)) add(flow, "participants.nodeId", "participant-node-missing");
     }
     const definitions = new Map<string, string>();
     const outcomes = flow.outcomes as Array<{ id: string; steps: NativeModelRecord[]; terminal: { participant: string } }>;
     const outcomeIds = new Set<string>();
     for (const outcome of outcomes) {
-      if (outcomeIds.has(outcome.id)) add(id, "outcomes.id", "outcome-id-ambiguous");
+      if (outcomeIds.has(outcome.id)) add(flow, "outcomes.id", "outcome-id-ambiguous");
       outcomeIds.add(outcome.id);
-      if (!participantIds.has(outcome.terminal.participant)) add(id, "outcomes.terminal", "terminal-participant-missing");
+      if (!participantIds.has(outcome.terminal.participant)) add(flow, "outcomes.terminal", "terminal-participant-missing");
     }
     for (const step of [...flow.steps as NativeModelRecord[], ...outcomes.flatMap(outcome => outcome.steps)]) {
-      if (!participantIds.has(step.from as string) || !participantIds.has(step.to as string)) add(id, "steps", "step-participant-missing");
+      if (!participantIds.has(step.from as string) || !participantIds.has(step.to as string)) add(flow, "steps", "step-participant-missing");
       const definition = canonicalize(step);
-      if (definitions.has(step.id as string) && definitions.get(step.id as string) !== definition) add(id, "steps.id", "step-definition-ambiguous");
+      if (definitions.has(step.id as string) && definitions.get(step.id as string) !== definition) add(flow, "steps.id", "step-definition-ambiguous");
       definitions.set(step.id as string, definition);
       const selector = step.evidence as { entrypointId: string; sourceSymbol: string; sinkId: string };
-      if (!selectors.has(JSON.stringify([selector.entrypointId, selector.sourceSymbol, selector.sinkId]))) add(id, "steps.evidence", "selector-missing");
+      if (!selectors.has(JSON.stringify([selector.entrypointId, selector.sourceSymbol, selector.sinkId]))) add(flow, "steps.evidence", "selector-missing");
     }
   }
   return issues;

package/src/ports.ts

@@ -121,6 +121,8 @@ export interface SourceSelector {
 }
 
 export interface CodeFactsPort {
+  /** Read-only compatibility check before the existing incremental sync. No retry or rebuild. */
+  assertCanSync?(workspaceRoot: string): void;
   ensureReady(workspace: WorkspaceRef): Promise<CodeFactsSnapshot>;
   sync(input: { workspace: WorkspaceRef; changedPaths?: string[] }): Promise<CodeFactsSnapshot>;
   buildTaskContext(input: { task: string; maxSymbols: number; includeSource: boolean; changedPaths?: string[] }): Promise<NormalizedCodeContext>;
@@ -148,6 +150,8 @@ export interface ModelValidationResult {
    * `appliesTo` id with no node. Omitted when empty.
    */
   referenceErrors?: string[];
+  /** Node schema errors with their file paths. Only a write to that node can repair them. */
+  nodeSchemaErrors?: { path: string; error: string }[];
   /** Problems that do not invalidate the model, such as an ignored legacy setting. Omitted when empty. */
   warnings?: string[];
   modelDigest: string;
@@ -811,7 +815,7 @@ export interface ReviewCheckoutGitPort {
 }
 
 export interface NonLocalEgressChannel {
-  channel: "context7" | "agent-audit" | "github-issue-publishing" | "npm-update-check" | "codegraph-telemetry";
+  channel: "context7" | "agent-audit" | "github-issue-publishing" | "npm-update-check" | "projection-publishing" | "codegraph-telemetry";
   destination: string;
   trigger: string;
   data: string;

package/src/product-version.ts

@@ -1,5 +1,5 @@
 export const ARCHCONTEXT_PRODUCT_NAME = "archctx";
-export const ARCHCONTEXT_PRODUCT_VERSION = "0.8.0";
+export const ARCHCONTEXT_PRODUCT_VERSION = "0.9.0";
 export const ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.4.3";
 export const ARCHCONTEXT_NODE_RANGE = ">=22.22 <26";
 export const LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v2";

package/src/projection-writer.ts

@@ -0,0 +1,116 @@
+import type { ProjectionHumanActionReasonCode } from "./projection";
+
+/**
+ * Projection writer mode (issue #379, ADR-0048): `archctx projection publish` keeps one rolling
+ * pull request branch (`archctx/...`) equal to the base tip plus exactly one commit that touches
+ * generated projection outputs only, and `archctx projection verify-pr` lets downstream CI check
+ * such a pull request without trusting its author.
+ */
+export const PROJECTION_PUBLISH_RUN_SCHEMA_VERSION = "archcontext.projection-publish-run/v1" as const;
+export const PROJECTION_PUBLISH_STATUS_SCHEMA_VERSION = "archcontext.projection-publish-status/v1" as const;
+export const PROJECTION_PR_VERIFICATION_SCHEMA_VERSION = "archcontext.projection-pr-verification/v1" as const;
+
+/** The only ref namespace the writer ever pushes to. */
+export const PROJECTION_WRITER_BRANCH_PREFIX = "archctx/";
+export const PROJECTION_WRITER_DEFAULT_BRANCH = "archctx/projection";
+
+export const PROJECTION_PUBLISH_RESULTS = [
+  "already-processed",
+  "busy",
+  "failed",
+  "human-action-required",
+  "published",
+  "up-to-date"
+] as const;
+export const PROJECTION_PUBLISHERS = ["command", "gh", "none"] as const;
+export const PROJECTION_PR_VERDICTS = [
+  "generated-only-not-render-equivalent",
+  "generated-only-render-equivalent",
+  "no-changes",
+  "touches-non-generated"
+] as const;
+
+export type ProjectionPublishResult = (typeof PROJECTION_PUBLISH_RESULTS)[number];
+export type ProjectionPublisherKind = (typeof PROJECTION_PUBLISHERS)[number];
+export type ProjectionPrVerdict = (typeof PROJECTION_PR_VERDICTS)[number];
+
+export interface ProjectionPublishPullRequestV1 {
+  url?: string;
+  number?: number;
+}
+
+export interface ProjectionPublishHumanActionV1 {
+  reasonCode: ProjectionHumanActionReasonCode;
+  path?: string;
+}
+
+/** The `data` of `projection.publish`, and the writer state's `lastRun`. */
+export interface ProjectionPublishRunV1 {
+  schemaVersion: typeof PROJECTION_PUBLISH_RUN_SCHEMA_VERSION;
+  result: ProjectionPublishResult;
+  remote: string;
+  base: string;
+  branch: string;
+  /** The base tip this run evaluated; null when the run stopped before resolving one. */
+  baseSha: string | null;
+  /** The rolling branch tip that carries this base's projection, pushed by this run or an earlier one. */
+  publishedCommit: string | null;
+  /** True only when this run moved the remote rolling branch. */
+  pushed: boolean;
+  pullRequest: ProjectionPublishPullRequestV1 | null;
+  publisher: ProjectionPublisherKind;
+  /** Repository-relative generated paths the published commit changes, sorted. */
+  files: string[];
+  /** `ProjectionResultV2.status` of the apply this run made, or null without one. */
+  projectionStatus: string | null;
+  humanActions: ProjectionPublishHumanActionV1[];
+  error: { code: string; reasonCode?: string; message: string } | null;
+  startedAt: string;
+  finishedAt: string;
+  /** Base tips evaluated in this run; above 1 when the base moved while the run worked. */
+  iterations: number;
+  /** Present on `busy`: the pid of the live writer that holds the lock. */
+  holderPid?: number;
+}
+
+/** The `data` of `projection.publish-status`. Read-only. */
+export interface ProjectionPublishStatusV1 {
+  schemaVersion: typeof PROJECTION_PUBLISH_STATUS_SCHEMA_VERSION;
+  remote: string;
+  base: string;
+  branch: string | null;
+  worktreePath: string;
+  running: { pid: number; startedAt: string } | null;
+  lastProcessedSha: string | null;
+  lastSuccessfulSha: string | null;
+  lastRun: ProjectionPublishRunV1 | null;
+}
+
+/** The `data` of `projection.verify-pr`. */
+export interface ProjectionPrVerificationV1 {
+  schemaVersion: typeof PROJECTION_PR_VERIFICATION_SCHEMA_VERSION;
+  base: string;
+  baseSha: string;
+  headSha: string;
+  mergeBase: string;
+  changedPaths: string[];
+  /**
+   * Changed paths that are not generated: not the projection manifest, not a manifest target path
+   * and not an agent-context target path (at HEAD or at the merge base), plus every
+   * `humanEditedPaths` entry.
+   */
+  nonGeneratedPaths: string[];
+  /**
+   * Mixed-ownership targets (manifest `ownership: "mixed"` and every agent-context target) whose
+   * text outside the generated regions differs between the merge base and HEAD, whose regions
+   * cannot be delimited, or which are added or deleted. Never rendered.
+   */
+  humanEditedPaths: string[];
+  /** True when the diff is non-empty and every changed path is a generated output. */
+  generatedOnly: boolean;
+  /** Null when no render ran (an empty diff, or a diff that touches a non-generated path). */
+  renderEquivalent: boolean | null;
+  differingPaths: string[];
+  projectionStatus: string | null;
+  verdict: ProjectionPrVerdict;
+}

package/src/projection.ts

@@ -108,7 +108,9 @@ export const ARCHCTX_FEATURES = [
   "projection-preview-v1",
   "projection-prior-committed-applies-v1",
   "projection-protocol-v2",
+  "projection-publish-v1",
   "projection-snapshot-v1",
+  "projection-verify-pr-v1",
   "recommendation-scan-decision-v1",
   "recommendation-v3",
   "refactor-assessment-v1",

package/src/schema.ts

@@ -18,6 +18,7 @@ export type ArchContextErrorCode =
   | "AC_NODE_VERSION_UNSUPPORTED"
   | "AC_CODEGRAPH_UNAVAILABLE"
   | "AC_CODE_FACTS_UNAVAILABLE"
+  | "AC_CODE_FACTS_NOT_READY"
   | "AC_INDEX_STALE"
   | "AC_CONTEXT_STALE"
   | "AC_SCHEMA_INVALID"
@@ -68,6 +69,7 @@ export const ERROR_CATALOG: Record<ArchContextErrorCode, Omit<ArchContextError,
   AC_NODE_VERSION_UNSUPPORTED: { code: "AC_NODE_VERSION_UNSUPPORTED", severity: "error", retryable: false, action: "use-supported-node-version" },
   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_CODE_FACTS_NOT_READY: { code: "AC_CODE_FACTS_NOT_READY", severity: "error", retryable: false, action: "codegraph-index" },
   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" },