@kungfu-tech/buildchain 3.0.9-alpha.0 → 3.0.9-alpha.10

package/bin/buildchain.mjs

@@ -1378,12 +1378,20 @@ async function handleDevCommand(args) {
       runScript("dev-delivery-warrant.mjs", devArgs);
       return;
     }
+    if (subcommand === "authority") {
+      runScript("dev-delivery-authority.mjs", devArgs);
+      return;
+    }
     if (subcommand === "proof") {
       runScript("dev-delivery-proof.mjs", devArgs);
       return;
     }
+    if (subcommand === "two-phase") {
+      runScript("dev-delivery-two-phase.mjs", devArgs);
+      return;
+    }
     if (subcommand !== "merge-queue") {
-      throw new Error("usage: buildchain dev <pr-admit|merge-queue|warrant|proof> [options]");
+      throw new Error("usage: buildchain dev <pr-admit|merge-queue|warrant|authority|proof|two-phase> [options]");
     }
     runScript("dev-merge-queue.mjs", devArgs);
     return;

package/contracts/dev-delivery-authority-v2.schema.json

@@ -0,0 +1,253 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://buildchain.libkungfu.dev/schemas/dev-delivery-authority-v2.schema.json",
+  "title": "Buildchain Dev Delivery Authority State v2",
+  "description": "Opt-in durable state separating bounded qualification-only leases from one exclusive merge_group Landing Warrant.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "contract",
+    "authorityMode",
+    "repository",
+    "protectedBase",
+    "generation",
+    "qualificationCounter",
+    "landingCounter",
+    "policy",
+    "qualificationLeases",
+    "landingWarrant",
+    "candidates",
+    "migration",
+    "updatedAt",
+    "stateRoot"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "contract": { "const": "kungfu-buildchain-dev-delivery-authority" },
+    "authorityMode": { "const": "bounded-qualification-landing" },
+    "repository": {
+      "type": "string",
+      "pattern": "^[^/\\s]+/[^/\\s]+$"
+    },
+    "protectedBase": {
+      "type": "string",
+      "pattern": "^dev/v[0-9]+/v[0-9]+\\.[0-9]+$"
+    },
+    "generation": { "type": "integer", "minimum": 0 },
+    "qualificationCounter": { "type": "integer", "minimum": 0 },
+    "landingCounter": { "type": "integer", "minimum": 0 },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "maxQualificationLeases",
+        "qualificationLeaseSeconds",
+        "landingLeaseSeconds"
+      ],
+      "properties": {
+        "maxQualificationLeases": { "type": "integer", "minimum": 1 },
+        "qualificationLeaseSeconds": { "type": "integer", "minimum": 1 },
+        "landingLeaseSeconds": { "type": "integer", "minimum": 1 },
+        "maxLandingOvertakes": { "type": "integer", "minimum": 0 },
+        "maxQualificationAttempts": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "qualificationLeases": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/qualificationLease" }
+    },
+    "landingWarrant": {
+      "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/landingWarrant" }]
+    },
+    "candidates": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/candidate" }
+    },
+    "migration": {
+      "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/migration" }]
+    },
+    "updatedAt": { "type": "string", "format": "date-time" },
+    "stateRoot": { "$ref": "#/$defs/root" }
+  },
+  "$defs": {
+    "root": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "sha": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{40}$"
+    },
+    "qualificationLease": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "authority",
+        "mergeGroupAdmission",
+        "candidateId",
+        "token",
+        "generation",
+        "issuedAt",
+        "expiresAt"
+      ],
+      "properties": {
+        "schema": {
+          "const": "kungfu.buildchain.dev-delivery-qualification-lease/v1"
+        },
+        "authority": { "const": "qualification-only" },
+        "mergeGroupAdmission": { "const": false },
+        "candidateId": { "$ref": "#/$defs/root" },
+        "token": { "$ref": "#/$defs/root" },
+        "generation": { "type": "integer", "minimum": 1 },
+        "issuedAt": { "type": "string", "format": "date-time" },
+        "heartbeatAt": { "type": "string", "format": "date-time" },
+        "expiresAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "landingWarrant": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "authority",
+        "mergeGroupAdmission",
+        "candidateId",
+        "token",
+        "generation",
+        "issuedAt",
+        "expiresAt"
+      ],
+      "properties": {
+        "schema": {
+          "const": "kungfu.buildchain.dev-delivery-landing-warrant/v1"
+        },
+        "authority": { "const": "merge-group-admission" },
+        "mergeGroupAdmission": { "const": true },
+        "candidateId": { "$ref": "#/$defs/root" },
+        "token": { "$ref": "#/$defs/root" },
+        "generation": { "type": "integer", "minimum": 1 },
+        "issuedAt": { "type": "string", "format": "date-time" },
+        "heartbeatAt": { "type": "string", "format": "date-time" },
+        "expiresAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "qualification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["evidenceRoot", "qualifiedAt"],
+      "properties": {
+        "evidenceRoot": { "$ref": "#/$defs/root" },
+        "qualifiedAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "terminal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["outcome", "evidenceRoot", "reason", "settledAt"],
+      "properties": {
+        "outcome": {
+          "enum": ["merged", "terminal-failure", "dequeued", "cancelled"]
+        },
+        "evidenceRoot": { "$ref": "#/$defs/root" },
+        "reason": { "type": "string" },
+        "settledAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "migration": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "legacyContract", "legacyStateRoot", "migratedAt"],
+      "properties": {
+        "schema": {
+          "const": "kungfu.buildchain.dev-delivery-authority-migration/v1"
+        },
+        "legacyContract": {
+          "const": "kungfu-buildchain-dev-delivery-warrant-queue"
+        },
+        "legacyStateRoot": { "$ref": "#/$defs/root" },
+        "migratedAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "candidate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "repository",
+        "protectedBase",
+        "pullRequestNumber",
+        "assignmentRoot",
+        "initiativeRoot",
+        "sourceIdentityRoot",
+        "deliveryClass",
+        "candidateId",
+        "sourceHead",
+        "sourcePatchRoot",
+        "sourceProofRoot",
+        "planRoot",
+        "closureRoot",
+        "dependencyRoot",
+        "toolchainRoot",
+        "enqueuedAt",
+        "updatedAt",
+        "status",
+        "qualification",
+        "terminal"
+      ],
+      "properties": {
+        "repository": { "type": "string" },
+        "protectedBase": { "type": "string" },
+        "pullRequestNumber": { "type": "integer", "minimum": 1 },
+        "assignmentRoot": { "$ref": "#/$defs/root" },
+        "initiativeRoot": { "$ref": "#/$defs/root" },
+        "sourceIdentityRoot": { "$ref": "#/$defs/root" },
+        "deliveryClass": {
+          "enum": [
+            "non-native-fast",
+            "native-proof-required",
+            "cross-platform",
+            "release"
+          ]
+        },
+        "identitySemantics": { "const": "chained-attempt-v2" },
+        "predecessorCandidateId": { "$ref": "#/$defs/root" },
+        "candidateId": { "$ref": "#/$defs/root" },
+        "sourceHead": { "$ref": "#/$defs/sha" },
+        "sourcePatchRoot": { "$ref": "#/$defs/root" },
+        "sourceProofRoot": { "$ref": "#/$defs/root" },
+        "planRoot": { "$ref": "#/$defs/root" },
+        "closureRoot": { "$ref": "#/$defs/root" },
+        "dependencyRoot": { "$ref": "#/$defs/root" },
+        "toolchainRoot": { "$ref": "#/$defs/root" },
+        "qualificationDomains": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/root" }
+        },
+        "qualificationAttempts": { "type": "integer", "minimum": 0 },
+        "landingOvertakes": { "type": "integer", "minimum": 0 },
+        "enqueuedAt": { "type": "string", "format": "date-time" },
+        "updatedAt": { "type": "string", "format": "date-time" },
+        "status": {
+          "enum": [
+            "queued",
+            "qualifying",
+            "qualified",
+            "landing",
+            "merged",
+            "terminal-failure",
+            "dequeued",
+            "cancelled"
+          ]
+        },
+        "qualification": {
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/qualification" }]
+        },
+        "terminal": {
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/terminal" }]
+        }
+      }
+    }
+  }
+}

package/contracts/fixtures/kfd-adopter-release-v1/kfd-4-perspective.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "contract": "kfd-4-observer-perspective",
+  "standard": "kfd-4",
+  "id": "buildchain-release-maintainer-view",
+  "observer": { "id": "buildchain-release-maintainer", "kind": "human" },
+  "acceptedFacts": [
+    { "sourceId": "kungfu-systems/buildchain@{{SOURCE_SHA}}", "sourceKind": "repository" }
+  ],
+  "projectionPolicy": {
+    "policyVersion": "1",
+    "causalDominance": true,
+    "tieBreaker": "source-coordinate"
+  },
+  "verification": { "result": "pass" }
+}

package/contracts/fixtures/kfd-adopter-release-v1/kfd-4-replay.json

@@ -0,0 +1,57 @@
+{
+  "schemaVersion": 1,
+  "contract": "kfd-4-perspective-replay",
+  "standard": "kfd-4",
+  "replayId": "buildchain-release-product-contrast",
+  "mode": "contrastive",
+  "sourceViews": [
+    {
+      "id": "maintainer",
+      "kind": "observer-view",
+      "coordinate": "git://kungfu-systems/buildchain@{{SOURCE_SHA}}",
+      "observer": "buildchain-release-maintainer",
+      "perspective": "release-integrity",
+      "acceptedFactCut": "git://kungfu-systems/buildchain@{{SOURCE_SHA}}",
+      "naturalObjects": ["release"],
+      "consequences": ["published artifact"],
+      "knownGaps": []
+    },
+    {
+      "id": "consumer",
+      "kind": "observer-view",
+      "coordinate": "npm://@kungfu-tech/buildchain@{{SOURCE_SHA}}",
+      "observer": "buildchain-release-consumer",
+      "perspective": "artifact-consumption",
+      "acceptedFactCut": "artifact://published-package",
+      "naturalObjects": ["installed package"],
+      "consequences": ["local build execution"],
+      "knownGaps": ["consumer runtime state"]
+    }
+  ],
+  "replayObserver": {
+    "id": "buildchain",
+    "kind": "service",
+    "purpose": "retain source and artifact fact boundaries"
+  },
+  "reconstruction": {
+    "policyVersion": "1",
+    "sharedContext": "same source-bound release",
+    "preservedElements": ["observer", "accepted-fact-cut", "evidence-boundary"],
+    "declaredLoss": ["consumer runtime state"],
+    "degradedState": "none"
+  },
+  "contrast": {
+    "dimensions": ["evidence-boundary"],
+    "mismatches": [
+      {
+        "sourceViewIds": ["maintainer", "consumer"],
+        "observation": "source and installed artifact evidence have different custody",
+        "primitiveSignal": "inconclusive"
+      }
+    ]
+  },
+  "verification": {
+    "result": "pass",
+    "evidence": ["evidence/projection-fsck.json"]
+  }
+}

package/contracts/fixtures/next-development-transition-v1/anchored-manual-waiting.json

@@ -0,0 +1,47 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-next-development-transition/v1",
+  "idempotencyKey": "sha256:cf805c1933cbc3e571c21af3ae030139bebafb08e2436b3c479c411b2cd2d22c",
+  "repository": "example/widget",
+  "completedAlpha": {
+    "outcome": "succeeded",
+    "version": "1.4.2-alpha.7",
+    "exactTag": "v1.4.2-alpha.7",
+    "releaseSha": "1111111111111111111111111111111111111111",
+    "treeSha": "2222222222222222222222222222222222222222",
+    "publicationRoot": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
+    "completedAt": "2026-08-11T01:00:00.000Z"
+  },
+  "completedAlphaRoot": "sha256:18e65c63aba0df789e0b0e68903733825d87e292b82bcb8fd3793ca45dca6266",
+  "alphaOutcome": "preserved-success",
+  "model": {
+    "strategy": "anchored",
+    "next": "manual"
+  },
+  "target": {
+    "version": null,
+    "anchor": null
+  },
+  "declaredPaths": ["package.json", "release.json"],
+  "adapter": {
+    "environmentVariable": "BUILDCHAIN_VERSION",
+    "sourcePaths": ["package.json"],
+    "derivedPaths": [],
+    "allowedChangePaths": ["package.json"],
+    "readOnlyPaths": ["release.json"],
+    "derivationStage": null,
+    "verificationStage": "lifecycle.verify"
+  },
+  "effectBounds": {
+    "allowedPaths": ["package.json"],
+    "refUpdates": [],
+    "forbiddenRefNamespaces": ["refs/heads/alpha/", "refs/tags/"]
+  },
+  "state": {
+    "status": "waiting-anchor",
+    "generation": 1,
+    "stateRoot": "sha256:4bbca86f960a7c1a10d76d01736422e3129f3f16d3e69e0800a0829201122dd4"
+  },
+  "materialization": null,
+  "transitions": []
+}

package/contracts/fixtures/next-development-transition-v1/semver-auto-planned.json

@@ -0,0 +1,47 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-next-development-transition/v1",
+  "idempotencyKey": "sha256:37ee52799584a989b059db060b7ce062feb56fbeff452033245046fdf3b21e78",
+  "repository": "example/widget",
+  "completedAlpha": {
+    "outcome": "succeeded",
+    "version": "1.4.2-alpha.7",
+    "exactTag": "v1.4.2-alpha.7",
+    "releaseSha": "1111111111111111111111111111111111111111",
+    "treeSha": "2222222222222222222222222222222222222222",
+    "publicationRoot": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
+    "completedAt": "2026-08-11T01:00:00.000Z"
+  },
+  "completedAlphaRoot": "sha256:18e65c63aba0df789e0b0e68903733825d87e292b82bcb8fd3793ca45dca6266",
+  "alphaOutcome": "preserved-success",
+  "model": {
+    "strategy": "semver",
+    "next": "auto"
+  },
+  "target": {
+    "version": "1.4.2-alpha.8",
+    "anchor": null
+  },
+  "declaredPaths": ["package.json"],
+  "adapter": {
+    "environmentVariable": "BUILDCHAIN_VERSION",
+    "sourcePaths": ["package.json"],
+    "derivedPaths": [],
+    "allowedChangePaths": ["package.json"],
+    "readOnlyPaths": [],
+    "derivationStage": null,
+    "verificationStage": "lifecycle.verify"
+  },
+  "effectBounds": {
+    "allowedPaths": ["package.json"],
+    "refUpdates": [],
+    "forbiddenRefNamespaces": ["refs/heads/alpha/", "refs/tags/"]
+  },
+  "state": {
+    "status": "planned",
+    "generation": 1,
+    "stateRoot": "sha256:4ef8ac1ff07cb14633994625e65a340acb3130ae56bbc88ee81504f09df3fa0f"
+  },
+  "materialization": null,
+  "transitions": []
+}

package/contracts/fixtures/next-development-transition-v1/version-model-cases.json

@@ -0,0 +1,40 @@
+{
+  "contract": "kungfu-buildchain-next-development-version-model-fixtures/v1",
+  "positive": [
+    {
+      "name": "semver-auto",
+      "model": { "strategy": "semver", "next": "auto" }
+    },
+    {
+      "name": "anchored-manual",
+      "model": { "strategy": "anchored", "next": "manual" }
+    }
+  ],
+  "negative": [
+    {
+      "name": "semver-manual",
+      "model": { "strategy": "semver", "next": "manual" },
+      "error": "version model must be semver/auto or anchored/manual"
+    },
+    {
+      "name": "anchored-auto",
+      "model": { "strategy": "anchored", "next": "auto" },
+      "error": "version model must be semver/auto or anchored/manual"
+    },
+    {
+      "name": "semver-auto-with-anchor",
+      "model": { "strategy": "semver", "next": "auto" },
+      "anchor": {
+        "manifestPath": "release.json",
+        "manifestRoot": "sha256:4444444444444444444444444444444444444444444444444444444444444444"
+      },
+      "error": "semver/auto must not declare an anchor"
+    },
+    {
+      "name": "anchored-manual-target-without-anchor",
+      "model": { "strategy": "anchored", "next": "manual" },
+      "targetVersion": "22.1.0",
+      "error": "anchored/manual targetVersion requires an anchor"
+    }
+  ]
+}

package/contracts/next-development-request-v1.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://buildchain.libkungfu.dev/schemas/next-development-request-v1.schema.json",
+  "title": "Buildchain Next-development Request v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contract", "repository", "completedAlpha", "recordedAt"],
+  "properties": {
+    "contract": {
+      "const": "kungfu-buildchain-next-development-request/v1"
+    },
+    "repository": {
+      "type": "string",
+      "pattern": "^[^/\\s]+/[^/\\s]+$"
+    },
+    "completedAlpha": { "$ref": "#/$defs/completedAlpha" },
+    "targetVersion": { "$ref": "#/$defs/semver" },
+    "anchor": { "$ref": "#/$defs/anchor" },
+    "recordedAt": { "type": "string", "format": "date-time" }
+  },
+  "$defs": {
+    "gitSha": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "root": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "semver": {
+      "type": "string",
+      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$"
+    },
+    "completedAlpha": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "outcome",
+        "version",
+        "exactTag",
+        "releaseSha",
+        "treeSha",
+        "publicationRoot",
+        "completedAt"
+      ],
+      "properties": {
+        "outcome": { "const": "succeeded" },
+        "version": {
+          "type": "string",
+          "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)-alpha\\.(0|[1-9][0-9]*)$"
+        },
+        "exactTag": { "type": "string", "minLength": 1 },
+        "releaseSha": { "$ref": "#/$defs/gitSha" },
+        "treeSha": { "$ref": "#/$defs/gitSha" },
+        "publicationRoot": { "$ref": "#/$defs/root" },
+        "completedAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "anchor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["manifestPath", "manifestRoot"],
+      "properties": {
+        "manifestPath": {
+          "type": "string",
+          "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))[^\\s]+$"
+        },
+        "manifestRoot": { "$ref": "#/$defs/root" }
+      }
+    }
+  }
+}