archctx-contracts 0.8.1 → 0.9.1

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.1" },
+  "package": { "name": "archctx", "version": "0.9.1" },
   "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.1",
+    "version": "0.9.1",
     "distribution": "one-package"
   },
   "packageManager": "bun@1.4.3",
@@ -12,25 +12,25 @@
   "surfaces": {
     "cli": {
       "packageName": "@archcontext/surfaces",
-      "version": "0.8.1",
+      "version": "0.9.1",
       "entrypoint": "archctx"
     },
     "daemon": {
       "packageName": "@archcontext/local-runtime",
-      "version": "0.8.1",
+      "version": "0.9.1",
       "entrypoint": "archctx daemon start",
       "rpcSchemaVersion": "archcontext.runtime-rpc/v2"
     },
     "mcp": {
       "packageName": "@archcontext/surfaces",
-      "version": "0.8.1",
+      "version": "0.9.1",
       "entrypoint": "archctx mcp",
       "transport": "stdio"
     }
   },
   "schemas": {
     "schemaSetVersion": "2026-06-25.al0-ledger",
-    "contractsPackageVersion": "0.8.1",
+    "contractsPackageVersion": "0.9.1",
     "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.1",
+  "version": "0.9.1",
   "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/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/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/ports.ts

@@ -815,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.1";
+export const ARCHCONTEXT_PRODUCT_VERSION = "0.9.1";
 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

@@ -146,6 +146,8 @@ export function stableYaml(value: Json, indent = 0): string {
     if (value.length === 0) return "[]\n";
     return value
       .map((item) => {
+        // The stable reader accepts flow sequences, but not compact nested block sequences.
+        if (Array.isArray(item)) return `${pad}- ${canonicalize(item)}\n`;
         if (item !== null && typeof item === "object") {
           return `${pad}- ${stableYaml(item, indent + 2).trimStart()}`;
         }