@kungfu-tech/buildchain 3.0.9-alpha.8 → 4.0.0-alpha.0

package/architecture/v4-capability-state-machine-manifest.json

@@ -0,0 +1,480 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-v4-capability-state-machine-manifest",
+  "releaseLine": {
+    "branch": "dev/v4/v4.0",
+    "bootstrapAuthority": "architecture/v4-bootstrap-authority.json",
+    "productionAuthority": "v4-native",
+    "productionFallback": null,
+    "rollbackRef": "release/v3/v3.0",
+    "qualificationMode": "exact-n-minus-one-git-revision"
+  },
+  "dependencyLayers": [
+    { "id": "contracts", "mayDependOn": [], "providerSdkImports": "forbidden" },
+    {
+      "id": "rust-domain",
+      "mayDependOn": ["contracts"],
+      "providerSdkImports": "forbidden"
+    },
+    {
+      "id": "libnode-host",
+      "mayDependOn": ["contracts", "rust-domain"],
+      "providerSdkImports": "forbidden"
+    },
+    {
+      "id": "typescript-adapters",
+      "mayDependOn": ["contracts", "libnode-host"],
+      "providerSdkImports": "adapter-only"
+    },
+    {
+      "id": "workflows",
+      "mayDependOn": ["contracts", "typescript-adapters"],
+      "providerSdkImports": "adapter-only"
+    },
+    {
+      "id": "legacy-compatibility",
+      "mayDependOn": ["contracts", "typescript-adapters"],
+      "providerSdkImports": "adapter-only"
+    }
+  ],
+  "budgets": {
+    "authority": {
+      "hardCeilings": {
+        "writersPerStateMachine": 1,
+        "undeclaredAuthorities": 0,
+        "permanentDualWrites": 0,
+        "crossMachineMutableFiles": 0
+      }
+    },
+    "semanticState": {
+      "hardCeilings": {
+        "undeclaredStates": 0,
+        "undeclaredEvents": 0,
+        "bypassTransitions": 0
+      }
+    },
+    "boundary": {
+      "hardCeilings": {
+        "providerSdkImportsInContracts": 0,
+        "providerSdkImportsInRustDomain": 0,
+        "dependencyCycles": 0
+      }
+    },
+    "structural": {
+      "hardCeilings": {
+        "unownedSourceFiles": 0,
+        "unmappedCapabilities": 0,
+        "manualProjectionCopies": 0
+      }
+    },
+    "agentCognitive": {
+      "hardCeilings": {
+        "requiredDiscoveryCommands": 2,
+        "duplicateArchitectureExplanations": 0,
+        "implicitAuthorityDecisions": 0
+      }
+    },
+    "recoveryFault": {
+      "hardCeilings": {
+        "stateMachinesWithoutRecovery": 0,
+        "unboundedRetries": 0,
+        "unknownFailureClasses": 0
+      }
+    }
+  },
+  "capabilities": [
+    {
+      "id": "dev-delivery-warrant",
+      "owner": "Buildchain Dev delivery control plane",
+      "sourceInventoryId": "dev-delivery-warrant",
+      "surfaces": [
+        "cli:dev",
+        "export:./dev-delivery-warrant",
+        "workflow:dev-pr-auto-merge"
+      ],
+      "migrationPhase": "legacy-retired"
+    },
+    {
+      "id": "release-candidate-passport",
+      "owner": "Buildchain candidate evidence plane",
+      "sourceInventoryId": "release-candidate-passport",
+      "surfaces": [
+        "cli:candidate",
+        "export:./release-candidate",
+        "workflow:release-candidate-promote"
+      ],
+      "migrationPhase": "legacy-retired"
+    },
+    {
+      "id": "release-candidate-recovery",
+      "owner": "Buildchain promotion recovery plane",
+      "sourceInventoryId": "release-candidate-recovery",
+      "surfaces": [
+        "export:./release-candidate-recovery",
+        "workflow:buildchain-candidate-recovery-dogfood-failure"
+      ],
+      "migrationPhase": "legacy-retired"
+    },
+    {
+      "id": "stable-candidate-ledger",
+      "owner": "Buildchain stable release selection plane",
+      "sourceInventoryId": "stable-candidate-ledger",
+      "surfaces": [
+        "export:./stable-candidate-ledger",
+        "workflow:stable-candidate-patrol"
+      ],
+      "migrationPhase": "legacy-retired"
+    },
+    {
+      "id": "publish-transaction",
+      "owner": "Buildchain package and release publication plane",
+      "sourceInventoryId": "publish-transaction",
+      "surfaces": ["action:promote-buildchain-ref", "cli:release-transaction"],
+      "migrationPhase": "legacy-retired"
+    },
+    {
+      "id": "release-activation-transaction",
+      "owner": "Buildchain release activation plane",
+      "sourceInventoryId": "release-activation-transaction",
+      "surfaces": ["export:./release-activation-transaction"],
+      "migrationPhase": "legacy-retired"
+    },
+    {
+      "id": "publication-authority",
+      "owner": "Buildchain publication admission and qualification plane",
+      "sourceInventoryId": "publication-authority",
+      "surfaces": [
+        "export:./publication-authority",
+        "cli:verify-publication-admission"
+      ],
+      "migrationPhase": "legacy-retired"
+    },
+    {
+      "id": "github-governance-authority",
+      "owner": "Buildchain GitHub governance plane",
+      "sourceInventoryId": "github-governance-authority",
+      "surfaces": [
+        "export:./github-governance-authority",
+        "cli:release-governance"
+      ],
+      "migrationPhase": "legacy-retired"
+    },
+    {
+      "id": "release-passport-and-artifact-proof",
+      "owner": "Buildchain release trust plane",
+      "sourceInventoryId": "release-passport-and-artifact-proof",
+      "surfaces": ["export:./release-passport", "cli:verify-release-passport"],
+      "migrationPhase": "legacy-retired"
+    },
+    {
+      "id": "engineering-housekeeper",
+      "owner": "Buildchain engineering hygiene plane",
+      "sourceInventoryId": "engineering-housekeeper",
+      "surfaces": [
+        "export:./engineering-housekeeper",
+        "export:./engineering-housekeeper-github",
+        "workflow:engineering-housekeeper"
+      ],
+      "migrationPhase": "legacy-retired"
+    },
+    {
+      "id": "release-propagation-work-control",
+      "owner": "Buildchain downstream release propagation plane",
+      "sourceInventoryId": "release-propagation-work-control",
+      "surfaces": ["export:./release-propagation", "cli:release-propagation"],
+      "migrationPhase": "legacy-retired"
+    },
+    {
+      "id": "release-tail-provider-plane",
+      "owner": "Buildchain declarative release provider plane",
+      "sourceInventoryId": "release-tail-provider-plane",
+      "surfaces": [
+        "export:./release-tail-provider-plane",
+        "cli:release-tail",
+        "action:release-tail",
+        "workflow:release-tail"
+      ],
+      "migrationPhase": "legacy-retired"
+    }
+  ],
+  "stateMachines": [
+    {
+      "id": "dev-delivery-warrant",
+      "capabilityId": "dev-delivery-warrant",
+      "owner": "Buildchain Dev delivery control plane",
+      "writer": {
+        "runtime": "typescript-v4",
+        "authoritative": true,
+        "secondWriterBudget": 0
+      },
+      "schemas": ["kungfu.buildchain.dev-delivery-warrant/v1"],
+      "store": "rooted queue on the configured Git ref",
+      "states": [
+        "queued",
+        "selected",
+        "proving",
+        "waiting",
+        "blocked",
+        "merged",
+        "terminal-failure",
+        "dequeued",
+        "cancelled"
+      ],
+      "events": [
+        "submit",
+        "select",
+        "lease",
+        "renew",
+        "recover-expired",
+        "settle",
+        "cancel"
+      ],
+      "invariants": [
+        "one active fenced writer per protected base",
+        "expected-old queue root must match"
+      ],
+      "effects": [
+        "write Git-ref state commit",
+        "request GitHub merge-queue admission"
+      ],
+      "adapters": ["Git ref adapter", "GitHub pull-request adapter"],
+      "tests": [
+        "tests/dev-delivery-warrant.test.mjs",
+        "tests/dev-delivery-warrant-command.test.mjs"
+      ],
+      "recovery": [
+        "expired lease returns an eligible candidate without losing age"
+      ],
+      "migrationPhase": "legacy-retired",
+      "budgets": {
+        "undeclaredStates": 0,
+        "undeclaredEvents": 0,
+        "unboundedRetries": 0
+      }
+    },
+    {
+      "id": "stable-candidate-ledger",
+      "capabilityId": "stable-candidate-ledger",
+      "owner": "Buildchain stable release selection plane",
+      "writer": {
+        "runtime": "typescript-v4",
+        "authoritative": true,
+        "secondWriterBudget": 0
+      },
+      "schemas": ["kungfu-buildchain-stable-candidate-ledger"],
+      "store": "rooted ledger on the configured Git ref",
+      "states": ["soaking", "qualified", "revoked", "promoted"],
+      "events": ["register", "qualify", "hold", "revoke", "select", "promote"],
+      "invariants": [
+        "selection reads an exact rooted ledger",
+        "revoked candidates cannot promote"
+      ],
+      "effects": ["write ledger successor", "select an exact promotion source"],
+      "adapters": ["Git ref adapter", "GitHub Actions evidence adapter"],
+      "tests": [
+        "tests/stable-candidate-ledger.test.mjs",
+        "tests/stable-candidate-qualification.test.mjs"
+      ],
+      "recovery": ["expected-old conflict retries from provider readback"],
+      "migrationPhase": "legacy-retired",
+      "budgets": {
+        "undeclaredStates": 0,
+        "undeclaredEvents": 0,
+        "unboundedRetries": 0
+      }
+    },
+    {
+      "id": "publish-transaction",
+      "capabilityId": "publish-transaction",
+      "owner": "Buildchain package and release publication plane",
+      "writer": {
+        "runtime": "typescript-v4",
+        "authoritative": true,
+        "secondWriterBudget": 0
+      },
+      "schemas": [
+        "release transaction record",
+        "publish evidence",
+        "sealed publication bundle"
+      ],
+      "store": "release-state Git ref with local JSON and sealed evidence projections",
+      "states": [
+        "prepared",
+        "sealed",
+        "publishing",
+        "publish_failed",
+        "published",
+        "finalizing",
+        "complete",
+        "repair_required",
+        "abandoned",
+        "failed_permanently"
+      ],
+      "events": [
+        "seal",
+        "publish",
+        "publish-fail",
+        "finalize",
+        "complete",
+        "recover",
+        "abort"
+      ],
+      "invariants": [
+        "published bytes are never rebuilt during recovery",
+        "version-state expected-old must match"
+      ],
+      "effects": ["publish npm package", "write release refs and evidence"],
+      "adapters": ["npm adapter", "Git and GitHub adapter"],
+      "tests": [
+        "tests/publish-transaction.test.mjs",
+        "tests/promote-buildchain-ref-recovery.test.mjs"
+      ],
+      "recovery": [
+        "resume the exact sealed transaction or enter repair_required"
+      ],
+      "migrationPhase": "legacy-retired",
+      "budgets": {
+        "undeclaredStates": 0,
+        "undeclaredEvents": 0,
+        "unboundedRetries": 0
+      }
+    },
+    {
+      "id": "release-activation-transaction",
+      "capabilityId": "release-activation-transaction",
+      "owner": "Buildchain release activation plane",
+      "writer": {
+        "runtime": "typescript-v4",
+        "authoritative": true,
+        "secondWriterBudget": 0
+      },
+      "schemas": [
+        "kungfu-buildchain-release-activation-transaction/v1",
+        "kungfu-buildchain-release-activation-receipt-set/v1"
+      ],
+      "store": "rooted transaction plus immutable ordered receipt set",
+      "states": ["open", "complete", "aborted", "rolled-back"],
+      "events": ["record-phase", "abort", "rollback", "seal-receipts"],
+      "invariants": [
+        "activation phases remain ordered",
+        "completion binds the exact receipt set"
+      ],
+      "effects": ["activate an exact release", "record rollback evidence"],
+      "adapters": ["release provider adapters", "production readback adapter"],
+      "tests": ["tests/release-activation-transaction.test.mjs"],
+      "recovery": ["retry from the last immutable phase receipt or roll back"],
+      "migrationPhase": "legacy-retired",
+      "budgets": {
+        "undeclaredStates": 0,
+        "undeclaredEvents": 0,
+        "unboundedRetries": 0
+      }
+    },
+    {
+      "id": "release-propagation-work-control",
+      "capabilityId": "release-propagation-work-control",
+      "owner": "Buildchain downstream release propagation plane",
+      "writer": {
+        "runtime": "typescript-v4",
+        "authoritative": true,
+        "secondWriterBudget": 0
+      },
+      "schemas": [
+        "kungfu-buildchain-release-propagation-work",
+        "kungfu-buildchain-release-propagation-stage-receipt"
+      ],
+      "store": "rooted Work document with ordered immutable stage receipts",
+      "states": [
+        "paused",
+        "ready",
+        "retryable-failure",
+        "needs-decision",
+        "hard-safety-gate",
+        "complete"
+      ],
+      "events": ["claim", "record-stage", "repair", "complete"],
+      "invariants": [
+        "one Work authority owns continuation",
+        "stage receipts bind exact upstream and downstream roots"
+      ],
+      "effects": [
+        "open downstream delivery work",
+        "record deployment and readback"
+      ],
+      "adapters": ["GitHub delivery adapter", "Site deployment adapter"],
+      "tests": [
+        "tests/release-propagation.test.mjs",
+        "tests/release-propagation-work.test.mjs"
+      ],
+      "recovery": ["resume from the last retained stage receipt"],
+      "migrationPhase": "legacy-retired",
+      "budgets": {
+        "undeclaredStates": 0,
+        "undeclaredEvents": 0,
+        "unboundedRetries": 0
+      }
+    },
+    {
+      "id": "release-tail-provider-plane",
+      "capabilityId": "release-tail-provider-plane",
+      "owner": "Buildchain declarative release provider plane",
+      "writer": {
+        "runtime": "typescript-v4",
+        "authoritative": true,
+        "secondWriterBudget": 0
+      },
+      "schemas": [
+        "kungfu.buildchain.release-tail.transaction/v1",
+        "kungfu.buildchain.release-tail.effect/v1",
+        "kungfu.buildchain.release-tail.observation/v1",
+        "kungfu.buildchain.release-tail.receipt/v1"
+      ],
+      "store": "atomic rooted transaction checkpoint with observations and receipts",
+      "states": [
+        "preparing",
+        "prepared",
+        "publishing",
+        "committing",
+        "activating",
+        "reading-back",
+        "settling",
+        "complete",
+        "blocked",
+        "repair-required",
+        "terminal-failure"
+      ],
+      "events": ["plan", "readback", "apply", "retry", "settle"],
+      "invariants": [
+        "one transaction owns all four fixed capability effects",
+        "provider adapters cannot select state transitions or success",
+        "every mutation is bounded by pre-effect and post-effect readback"
+      ],
+      "effects": [
+        "publish sealed GitHub Release assets",
+        "commit a signed channel document",
+        "activate and read back a release",
+        "synthesize rooted released evidence"
+      ],
+      "adapters": [
+        "github-release-assets",
+        "signed-static-channel",
+        "site-release-activation",
+        "activation-receipt-projector"
+      ],
+      "tests": [
+        "tests/release-tail-provider-plane.test.mjs",
+        "tests/release-tail-provider-adapters.test.mjs"
+      ],
+      "recovery": [
+        "resume from the last atomic checkpoint and read provider state before retry"
+      ],
+      "migrationPhase": "legacy-retired",
+      "budgets": {
+        "undeclaredStates": 0,
+        "undeclaredEvents": 0,
+        "unboundedRetries": 0
+      }
+    }
+  ],
+  "exceptionLedger": "architecture/v4-exception-ledger.json"
+}

package/architecture/v4-capability-state-machine-manifest.schema.json

@@ -0,0 +1,202 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://buildchain.libkungfu.dev/schemas/v4-capability-state-machine-manifest-v1.schema.json",
+  "title": "Buildchain v4 Capability and State Machine Manifest",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "contract",
+    "releaseLine",
+    "dependencyLayers",
+    "budgets",
+    "capabilities",
+    "stateMachines",
+    "exceptionLedger"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "contract": {
+      "const": "kungfu-buildchain-v4-capability-state-machine-manifest"
+    },
+    "releaseLine": { "$ref": "#/$defs/releaseLine" },
+    "dependencyLayers": {
+      "type": "array",
+      "minItems": 5,
+      "items": { "$ref": "#/$defs/dependencyLayer" }
+    },
+    "budgets": { "$ref": "#/$defs/budgets" },
+    "capabilities": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/capability" }
+    },
+    "stateMachines": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/stateMachine" }
+    },
+    "exceptionLedger": { "const": "architecture/v4-exception-ledger.json" }
+  },
+  "$defs": {
+    "stringArray": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "releaseLine": {
+      "type": "object",
+      "required": [
+        "branch",
+        "bootstrapAuthority",
+        "productionAuthority",
+        "productionFallback",
+        "rollbackRef",
+        "qualificationMode"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "branch": { "const": "dev/v4/v4.0" },
+        "bootstrapAuthority": {
+          "const": "architecture/v4-bootstrap-authority.json"
+        },
+        "productionAuthority": { "const": "v4-native" },
+        "productionFallback": { "type": "null" },
+        "rollbackRef": { "const": "release/v3/v3.0" },
+        "qualificationMode": { "const": "exact-n-minus-one-git-revision" }
+      }
+    },
+    "dependencyLayer": {
+      "type": "object",
+      "required": ["id", "mayDependOn", "providerSdkImports"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "mayDependOn": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "providerSdkImports": { "enum": ["forbidden", "adapter-only"] }
+      }
+    },
+    "budgetDimension": {
+      "type": "object",
+      "required": ["hardCeilings"],
+      "additionalProperties": false,
+      "properties": {
+        "hardCeilings": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": { "type": "integer", "minimum": 0 }
+        }
+      }
+    },
+    "budgets": {
+      "type": "object",
+      "required": [
+        "authority",
+        "semanticState",
+        "boundary",
+        "structural",
+        "agentCognitive",
+        "recoveryFault"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "authority": { "$ref": "#/$defs/budgetDimension" },
+        "semanticState": { "$ref": "#/$defs/budgetDimension" },
+        "boundary": { "$ref": "#/$defs/budgetDimension" },
+        "structural": { "$ref": "#/$defs/budgetDimension" },
+        "agentCognitive": { "$ref": "#/$defs/budgetDimension" },
+        "recoveryFault": { "$ref": "#/$defs/budgetDimension" }
+      }
+    },
+    "capability": {
+      "type": "object",
+      "required": [
+        "id",
+        "owner",
+        "sourceInventoryId",
+        "surfaces",
+        "migrationPhase"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "owner": { "type": "string", "minLength": 1 },
+        "sourceInventoryId": { "type": "string", "minLength": 1 },
+        "surfaces": { "$ref": "#/$defs/stringArray" },
+        "migrationPhase": { "$ref": "#/$defs/migrationPhase" }
+      }
+    },
+    "migrationPhase": {
+      "enum": [
+        "legacy-authoritative",
+        "shadow",
+        "cutover-ready",
+        "rust-authoritative",
+        "legacy-retired"
+      ]
+    },
+    "stateMachine": {
+      "type": "object",
+      "required": [
+        "id",
+        "capabilityId",
+        "owner",
+        "writer",
+        "schemas",
+        "store",
+        "states",
+        "events",
+        "invariants",
+        "effects",
+        "adapters",
+        "tests",
+        "recovery",
+        "migrationPhase",
+        "budgets"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "capabilityId": { "type": "string", "minLength": 1 },
+        "owner": { "type": "string", "minLength": 1 },
+        "writer": {
+          "type": "object",
+          "required": ["runtime", "authoritative", "secondWriterBudget"],
+          "additionalProperties": false,
+          "properties": {
+            "runtime": { "type": "string", "minLength": 1 },
+            "authoritative": { "const": true },
+            "secondWriterBudget": { "const": 0 }
+          }
+        },
+        "schemas": { "$ref": "#/$defs/stringArray" },
+        "store": { "type": "string", "minLength": 1 },
+        "states": { "$ref": "#/$defs/stringArray" },
+        "events": { "$ref": "#/$defs/stringArray" },
+        "invariants": { "$ref": "#/$defs/stringArray" },
+        "effects": { "$ref": "#/$defs/stringArray" },
+        "adapters": { "$ref": "#/$defs/stringArray" },
+        "tests": { "$ref": "#/$defs/stringArray" },
+        "recovery": { "$ref": "#/$defs/stringArray" },
+        "migrationPhase": { "$ref": "#/$defs/migrationPhase" },
+        "budgets": {
+          "type": "object",
+          "required": [
+            "undeclaredStates",
+            "undeclaredEvents",
+            "unboundedRetries"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "undeclaredStates": { "const": 0 },
+            "undeclaredEvents": { "const": 0 },
+            "unboundedRetries": { "const": 0 }
+          }
+        }
+      }
+    }
+  }
+}