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

package/architecture/v4-delivery-warrant-shadow-fixtures.json

@@ -0,0 +1,227 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-v4-delivery-warrant-shadow-fixtures",
+  "canonicalization": "buildchain-canonical-json/v1",
+  "clock": "explicit-input-only",
+  "projection": [
+    "action-or-typed-error",
+    "expected-old-and-next-state-roots",
+    "receipt-root",
+    "generation-and-fencing-counter",
+    "active-pull-request",
+    "ordered-candidate-statuses"
+  ],
+  "traces": [
+    {
+      "id": "submission-selection-heartbeat-close",
+      "create": {
+        "repository": "kungfu-systems/buildchain",
+        "protectedBase": "dev/v4/v4.0",
+        "policy": { "agingSeconds": 300, "leaseSeconds": 600 },
+        "now": "2026-08-07T00:00:00Z"
+      },
+      "steps": [
+        {
+          "id": "submit-101",
+          "operation": "submit",
+          "pullRequestNumber": 101,
+          "now": "2026-08-07T00:00:01Z"
+        },
+        {
+          "id": "submit-102",
+          "operation": "submit",
+          "pullRequestNumber": 102,
+          "overrides": { "priority": "expedited" },
+          "now": "2026-08-07T00:00:02Z"
+        },
+        {
+          "id": "duplicate-101",
+          "operation": "submit",
+          "pullRequestNumber": 101,
+          "now": "2026-08-07T00:00:03Z"
+        },
+        {
+          "id": "select",
+          "operation": "select",
+          "saveWarrant": "selected",
+          "now": "2026-08-07T00:00:04Z"
+        },
+        {
+          "id": "renew",
+          "operation": "heartbeat",
+          "useWarrant": "selected",
+          "now": "2026-08-07T00:01:00Z"
+        },
+        {
+          "id": "close",
+          "operation": "close",
+          "useWarrant": "selected",
+          "outcome": "merged",
+          "reason": "exact merge group passed",
+          "now": "2026-08-07T00:02:00Z"
+        }
+      ],
+      "expectedLegacyProjectionRoot": "sha256:e01018e4797e98813454328aba2c0a04932885fcd6da7d216697c7961bc26f56"
+    },
+    {
+      "id": "lease-expiry-and-stale-fence",
+      "create": {
+        "repository": "kungfu-systems/buildchain",
+        "protectedBase": "dev/v4/v4.0",
+        "policy": { "agingSeconds": 300, "leaseSeconds": 60 },
+        "now": "2026-08-07T01:00:00Z"
+      },
+      "steps": [
+        {
+          "id": "submit",
+          "operation": "submit",
+          "pullRequestNumber": 120,
+          "now": "2026-08-07T01:00:01Z"
+        },
+        {
+          "id": "select-old",
+          "operation": "select",
+          "saveWarrant": "old",
+          "leaseSeconds": 60,
+          "now": "2026-08-07T01:00:02Z"
+        },
+        {
+          "id": "recover",
+          "operation": "recover-expired",
+          "now": "2026-08-07T01:02:00Z"
+        },
+        {
+          "id": "select-new",
+          "operation": "select",
+          "saveWarrant": "new",
+          "leaseSeconds": 60,
+          "now": "2026-08-07T01:02:01Z"
+        },
+        {
+          "id": "reject-old",
+          "operation": "heartbeat",
+          "useWarrant": "old",
+          "expectError": "stale-fencing-token",
+          "now": "2026-08-07T01:02:02Z"
+        }
+      ],
+      "expectedLegacyProjectionRoot": "sha256:3c39ba66a2329a22f3834c4212bda001b6d5c527dcb9fa8a1b3ca88a199a7d16"
+    },
+    {
+      "id": "settlement-idempotence",
+      "create": {
+        "repository": "kungfu-systems/buildchain",
+        "protectedBase": "dev/v4/v4.0",
+        "policy": { "agingSeconds": 300, "leaseSeconds": 600 },
+        "now": "2026-08-07T02:00:00Z"
+      },
+      "steps": [
+        {
+          "id": "not-applicable",
+          "operation": "settle-not-applicable",
+          "pullRequestNumber": 149,
+          "sourceHead": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "outcome": "merged",
+          "reason": "terminal before Warrant admission",
+          "now": "2026-08-07T02:00:01Z"
+        },
+        {
+          "id": "submit",
+          "operation": "submit",
+          "pullRequestNumber": 150,
+          "now": "2026-08-07T02:00:02Z"
+        },
+        {
+          "id": "select",
+          "operation": "select",
+          "saveWarrant": "active",
+          "now": "2026-08-07T02:00:03Z"
+        },
+        {
+          "id": "settle",
+          "operation": "settle-active",
+          "useWarrant": "active",
+          "saveSettlement": "terminal",
+          "outcome": "merged",
+          "reason": "exact merge group passed",
+          "now": "2026-08-07T02:01:00Z"
+        },
+        {
+          "id": "duplicate",
+          "operation": "settle-duplicate",
+          "useSettlement": "terminal",
+          "now": "2026-08-07T02:02:00Z"
+        }
+      ],
+      "expectedLegacyProjectionRoot": "sha256:b67669b2093105f3b4539ca5e4ba3d366bd7005a8781b5352377ae724d310d26"
+    },
+    {
+      "id": "queued-cancellation-idempotence",
+      "create": {
+        "repository": "kungfu-systems/buildchain",
+        "protectedBase": "dev/v4/v4.0",
+        "policy": { "agingSeconds": 300, "leaseSeconds": 600 },
+        "now": "2026-08-07T03:00:00Z"
+      },
+      "steps": [
+        {
+          "id": "submit",
+          "operation": "submit",
+          "pullRequestNumber": 151,
+          "now": "2026-08-07T03:00:01Z"
+        },
+        {
+          "id": "cancel",
+          "operation": "cancel-queued",
+          "pullRequestNumber": 151,
+          "observedSourceHead": "ffffffffffffffffffffffffffffffffffffffff",
+          "reason": "pull request closed",
+          "now": "2026-08-07T03:00:02Z"
+        },
+        {
+          "id": "duplicate",
+          "operation": "cancel-queued",
+          "pullRequestNumber": 151,
+          "observedSourceHead": "ffffffffffffffffffffffffffffffffffffffff",
+          "reason": "pull request closed",
+          "now": "2026-08-07T03:00:03Z"
+        }
+      ],
+      "expectedLegacyProjectionRoot": "sha256:128104385600c72af175a3ff6a58a4266ca7dcd59a5019adbd87ca7fd9bc65c9"
+    },
+    {
+      "id": "cas-response-loss-provider-conflict",
+      "create": {
+        "repository": "kungfu-systems/buildchain",
+        "protectedBase": "dev/v4/v4.0",
+        "policy": { "agingSeconds": 300, "leaseSeconds": 600 },
+        "now": "2026-08-07T04:00:00Z"
+      },
+      "steps": [
+        {
+          "id": "submit",
+          "operation": "submit",
+          "pullRequestNumber": 160,
+          "now": "2026-08-07T04:00:01Z"
+        },
+        {
+          "id": "accept-current",
+          "operation": "expected-old",
+          "expectedRoot": "submit"
+        },
+        {
+          "id": "reject-stale",
+          "operation": "expected-old",
+          "expectedRoot": "initial"
+        },
+        {
+          "id": "readback",
+          "operation": "response-loss-readback",
+          "committedRoot": "submit"
+        },
+        { "id": "provider-stop", "operation": "provider-conflict" }
+      ],
+      "expectedLegacyProjectionRoot": "sha256:e5082eab6504bab8ee382d43429594d0bbe1ee0353f78eb21b0ead03a4740887"
+    }
+  ]
+}

package/architecture/v4-delivery-warrant-shadow-fixtures.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://buildchain.libkungfu.dev/schemas/v4-delivery-warrant-shadow-fixtures-v1.schema.json",
+  "title": "Buildchain v4 Delivery Warrant Shadow Fixtures",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "contract",
+    "canonicalization",
+    "clock",
+    "projection",
+    "traces"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "contract": {
+      "const": "kungfu-buildchain-v4-delivery-warrant-shadow-fixtures"
+    },
+    "canonicalization": { "const": "buildchain-canonical-json/v1" },
+    "clock": { "const": "explicit-input-only" },
+    "projection": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "traces": {
+      "type": "array",
+      "minItems": 5,
+      "items": { "$ref": "#/$defs/trace" }
+    }
+  },
+  "$defs": {
+    "trace": {
+      "type": "object",
+      "required": ["id", "create", "steps", "expectedLegacyProjectionRoot"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "create": {
+          "type": "object",
+          "required": ["repository", "protectedBase", "policy", "now"],
+          "additionalProperties": false,
+          "properties": {
+            "repository": { "type": "string", "minLength": 3 },
+            "protectedBase": { "const": "dev/v4/v4.0" },
+            "policy": { "type": "object", "minProperties": 1 },
+            "now": { "type": "string", "format": "date-time" }
+          }
+        },
+        "steps": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["id", "operation"],
+            "minProperties": 2
+          }
+        },
+        "expectedLegacyProjectionRoot": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        }
+      }
+    }
+  }
+}

package/architecture/v4-exception-ledger.json

@@ -0,0 +1,5 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-v4-architecture-exception-ledger",
+  "exceptions": []
+}

package/architecture/v4-exception-ledger.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://buildchain.libkungfu.dev/schemas/v4-exception-ledger-v1.schema.json",
+  "title": "Buildchain v4 Architecture Exception Ledger",
+  "type": "object",
+  "required": ["schemaVersion", "contract", "exceptions"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "contract": {
+      "const": "kungfu-buildchain-v4-architecture-exception-ledger"
+    },
+    "exceptions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "status",
+          "owner",
+          "budgetDimension",
+          "scope",
+          "rationale",
+          "evidence",
+          "expiresAt",
+          "removalCondition"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "status": { "enum": ["active", "closed"] },
+          "owner": { "type": "string", "minLength": 1 },
+          "budgetDimension": {
+            "enum": [
+              "authority",
+              "semanticState",
+              "boundary",
+              "structural",
+              "agentCognitive",
+              "recoveryFault"
+            ]
+          },
+          "scope": { "type": "string", "minLength": 1 },
+          "rationale": { "type": "string", "minLength": 1 },
+          "evidence": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "expiresAt": { "type": "string", "format": "date-time" },
+          "removalCondition": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/architecture/v4-partial-mutation-recovery-qualification.json

@@ -0,0 +1,65 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-v4-partial-mutation-recovery-qualification-architecture",
+  "schemaAuthority": "contracts/v4-partial-mutation-recovery-v1.schema.json",
+  "fixtureAuthority": "contracts/fixtures/v4-partial-mutation-recovery-v1/shared.json",
+  "stageCapsulePredecessor": "architecture/v4-stage-capsule-resume-planner.json",
+  "activationPredecessor": "architecture/v4-release-activation-shadow-domain.json",
+  "journalPredecessor": "architecture/v4-provider-operation-journal-contract.json",
+  "mode": "production",
+  "productionAuthority": "v4-domain",
+  "classificationPriority": [
+    "escalate",
+    "compensate",
+    "reconcile",
+    "wait",
+    "retry",
+    "terminal-noop"
+  ],
+  "bindings": [
+    "source-root",
+    "policy-root",
+    "platform-root",
+    "stage-qualification-roots",
+    "activation-qualification-root",
+    "stage-resume-plan-root",
+    "activation-plan-root",
+    "activation-state-root",
+    "provider-operation-root",
+    "journal-state-root",
+    "compensation-boundary-root"
+  ],
+  "invariants": [
+    "confirmed operations are terminal noops and never enter next operations",
+    "every nonterminal operation maps to one bounded action and exact checkpoint",
+    "repeated evaluation of identical rooted evidence is byte-identical",
+    "missing corrupt conflicting expired or cross-boundary evidence fails closed",
+    "Stage Capsule rejection precedes all provider recovery planning",
+    "the planner emits zero external mutations and authorizes only bounded provider-adapter recovery"
+  ],
+  "implementations": {
+    "rustDomain": "crates/buildchain-v4-contracts/src/partial_mutation_recovery.rs",
+    "typescript": "packages/core/v4-partial-mutation-recovery-qualification.js"
+  },
+  "roots": [
+    "partial-mutation-recovery-checkpoint",
+    "partial-mutation-recovery-plan"
+  ],
+  "budgets": {
+    "schemaAuthorities": 1,
+    "recoveryPlanners": 1,
+    "typescriptProjections": 1,
+    "secondProductionWriters": 0,
+    "providerSdkImportsInContracts": 0,
+    "providerSdkImportsInRustDomain": 0,
+    "liveProviderMutations": 0,
+    "networkWrites": 0,
+    "credentialReads": 0,
+    "filesystemWrites": 0,
+    "ambientClockReads": 0,
+    "unboundedRetries": 0,
+    "productionWriteAuthorityChanges": 1,
+    "v3ConsumerBehaviorChanges": 0
+  },
+  "successor": "wave-3-reconciliation"
+}

package/architecture/v4-platform-stage-checkpoints.json

@@ -0,0 +1,97 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-v4-platform-stage-checkpoints",
+  "capsuleAuthority": "architecture/v4-stage-capsule-contract.json",
+  "storeAuthority": "architecture/v4-stage-capsule-store-contract.json",
+  "mode": "shadow-only",
+  "platforms": [
+    {
+      "id": "linux-x64",
+      "os": "linux",
+      "arch": "x64",
+      "runner": "ubuntu-24.04"
+    },
+    {
+      "id": "macos-arm64",
+      "os": "macos",
+      "arch": "arm64",
+      "runner": "macos-15"
+    },
+    {
+      "id": "windows-x64",
+      "os": "windows",
+      "arch": "x64",
+      "runner": "windows-2025"
+    }
+  ],
+  "stages": [
+    {
+      "id": "checkout-input",
+      "inputs": ["source-tree"],
+      "outputs": [{ "name": "source-layout", "path": "source/layout.json" }],
+      "environment": [],
+      "toolchains": ["git"],
+      "providerEffects": false
+    },
+    {
+      "id": "install",
+      "inputs": ["lockfile", "source-tree"],
+      "outputs": [
+        { "name": "dependency-layout", "path": "install/dependencies.json" }
+      ],
+      "environment": ["package-manager"],
+      "toolchains": ["node"],
+      "providerEffects": false
+    },
+    {
+      "id": "build",
+      "inputs": ["dependency-layout", "source-tree"],
+      "outputs": [{ "name": "build-output", "path": "build/output.bin" }],
+      "environment": ["build-profile"],
+      "toolchains": ["node"],
+      "providerEffects": false
+    },
+    {
+      "id": "verify",
+      "inputs": ["build-output", "source-tree"],
+      "outputs": [
+        { "name": "verification-report", "path": "verify/report.json" }
+      ],
+      "environment": ["verification-profile"],
+      "toolchains": ["node"],
+      "providerEffects": false
+    },
+    {
+      "id": "package",
+      "inputs": ["build-output", "source-tree", "verification-report"],
+      "outputs": [{ "name": "package-archive", "path": "package/archive.bin" }],
+      "environment": ["package-profile"],
+      "toolchains": ["node"],
+      "providerEffects": false
+    },
+    {
+      "id": "signing-preparation",
+      "inputs": ["package-archive", "source-tree"],
+      "outputs": [
+        { "name": "signing-request", "path": "signing/request.json" }
+      ],
+      "environment": ["signing-profile"],
+      "toolchains": ["node"],
+      "providerEffects": false
+    }
+  ],
+  "projections": {
+    "protectedWorkflow": ".github/workflows/verify.yml",
+    "generatedTemplate": "scripts/init-repo.mjs",
+    "agentGuidance": "AGENTS.md",
+    "manual": "docs/v4-stage-capsule.md"
+  },
+  "authority": {
+    "productionStageSkipping": false,
+    "providerEffects": false,
+    "credentials": false,
+    "ambientEnvironment": false,
+    "ambientClock": false,
+    "v3BehaviorChange": false
+  }
+}

package/architecture/v4-provider-operation-journal-contract.json

@@ -0,0 +1,113 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-v4-provider-operation-journal-architecture",
+  "schemaAuthority": "contracts/v4-provider-operation-journal-v1.schema.json",
+  "fixtureAuthority": "contracts/fixtures/v4-provider-operation-journal-v1/shared.json",
+  "mode": "production-journal",
+  "authority": {
+    "productionWriter": "v4-domain",
+    "productionWriterCount": 1,
+    "stateFoldAuthority": "rust-v4-core",
+    "stateFoldWriterCount": 1,
+    "typescript": "provider-adapter-and-conformance-plane",
+    "productionWriteChange": true
+  },
+  "implementations": {
+    "rustContract": "crates/buildchain-v4-contracts/src/provider_operation_journal.rs",
+    "rustFold": "crates/buildchain-v4-contracts/src/provider_operation_journal/fold.rs",
+    "rustReadback": "crates/buildchain-v4-contracts/src/provider_readback_idempotency.rs",
+    "typescript": "packages/core/v4-provider-operation-journal.js",
+    "typescriptReadback": "packages/core/v4-provider-readback-idempotency.js"
+  },
+  "activationDomain": {
+    "architecture": "architecture/v4-release-activation-shadow-domain.json",
+    "qualifiedInput": "buildchain-v4-release-activation-request/v1",
+    "journalConsumption": "sole-existing-provider-operation-journal-fold",
+    "confirmedResumeRule": "never-replay",
+    "uncertainResumeRule": "readback-before-any-retry",
+    "productionAuthority": "v4-domain",
+    "liveMutation": true
+  },
+  "roots": [
+    "provider-operation-identity",
+    "provider-operation-intent",
+    "provider-operation-attempt",
+    "provider-operation-observation",
+    "provider-operation-confirmation",
+    "provider-operation-reconciliation",
+    "provider-operation-journal",
+    "provider-operation-journal-state",
+    "provider-readback-sample",
+    "provider-readback-fold"
+  ],
+  "identityIncludes": [
+    "transactionRoot",
+    "capabilityId",
+    "subjectRoot",
+    "targetRoot",
+    "authorityRoot",
+    "policyRoot"
+  ],
+  "identityExcludes": [
+    "attemptOrdinal",
+    "providerRunId",
+    "providerRequestId",
+    "providerResourceId",
+    "credential",
+    "signedUrl",
+    "ambientClock",
+    "networkResponseBody",
+    "runnerPath",
+    "transportLocalId"
+  ],
+  "appendOnly": {
+    "sequence": "zero-based-contiguous",
+    "causalLink": "priorEntryRoot",
+    "retryIdentity": "operationRoot",
+    "attemptIdentity": "entryRoot",
+    "observationEvidence": "non-empty-sorted-root-set"
+  },
+  "readbackAdapters": {
+    "providers": ["github-release", "npm-publication", "oci-manifest"],
+    "inputAuthority": "provider-shaped-responses-with-fixture-conformance",
+    "outputAuthority": "provider-neutral-rooted-observation-samples",
+    "duplicateHandling": "deduplicate-by-sample-root",
+    "ordering": "byte-sorted-sample-roots",
+    "typedStates": ["not-found", "eventually-visible", "already-applied"],
+    "typedFaults": [
+      "conflicting-provider-readback",
+      "malformed-provider-readback",
+      "provider-readback-root-mismatch",
+      "provider-readback-coordinate-mismatch"
+    ],
+    "emits": "provider-operation-observation-only",
+    "confirmationAuthority": "independent-journal-qualification",
+    "releaseStateAuthority": false
+  },
+  "foldRejects": [
+    "impossible-transition",
+    "non-contiguous-sequence",
+    "causal-link-mismatch",
+    "logical-operation-identity-drift",
+    "confirmation-without-rooted-success-observation",
+    "conflicting-terminal-confirmation",
+    "authority-root-escalation",
+    "observation-disposition-conflict"
+  ],
+  "budgets": {
+    "schemaAuthorities": 1,
+    "stateFoldWriters": 1,
+    "secondStateFoldWriters": 0,
+    "providerSdkImportsInContracts": 0,
+    "providerSdkImportsInRustDomain": 0,
+    "liveProviderMutations": 0,
+    "productionWriteAuthorityChanges": 1,
+    "v3ConsumerBehaviorChanges": 0
+  },
+  "successors": [
+    "provider-readback-idempotency-adapters",
+    "release-activation-shadow-domain",
+    "stable-candidate-publication-fencing-shadow",
+    "partial-mutation-recovery-qualification"
+  ]
+}