@kungfu-tech/buildchain 4.0.1-alpha.2 → 4.0.1-alpha.3

package/architecture/v4-delivery-authority-parity.json

@@ -0,0 +1,250 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-v4-delivery-authority-parity",
+  "sourceAuthority": {
+    "decision": "architecture/decisions/0003-two-phase-delivery-warrant.md",
+    "reference": "docs/dev-delivery-warrant.md",
+    "contract": "kungfu-buildchain-dev-delivery-warrant-queue",
+    "schemaVersion": 1
+  },
+  "target": {
+    "branch": "dev/v4/v4.0",
+    "singleFlightContract": "kungfu-buildchain-dev-delivery-warrant-queue",
+    "boundedAuthorityContract": "kungfu-buildchain-dev-delivery-authority",
+    "boundedAuthoritySchemaVersion": 2
+  },
+  "allowedDispositions": [
+    "implemented",
+    "superseded-equivalent",
+    "missing-before-closeout"
+  ],
+  "invariants": [
+    {
+      "id": "DA-01",
+      "claim": "Native delivery receives provisional authority before expensive execution and cannot use that phase as merge admission.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "packages/core/dev-delivery-warrant.js",
+        "scripts/dev-delivery-two-phase.mjs"
+      ],
+      "verificationEvidence": [
+        "tests/dev-delivery-two-phase.test.mjs",
+        "tests/dev-delivery-two-phase-run.test.mjs"
+      ],
+      "behavioralProof": "tests/v4-delivery-authority-parity.test.mjs#DA-01"
+    },
+    {
+      "id": "DA-02",
+      "claim": "The provisional Warrant heartbeats one exact token and generation, and stale or expired owners cannot renew or qualify.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "packages/core/dev-delivery-warrant.js",
+        "scripts/dev-delivery-native-run.mjs"
+      ],
+      "verificationEvidence": [
+        "tests/dev-delivery-two-phase.test.mjs",
+        "tests/dev-delivery-native-run.test.mjs"
+      ],
+      "behavioralProof": "tests/v4-delivery-authority-parity.test.mjs#DA-02"
+    },
+    {
+      "id": "DA-03",
+      "claim": "Native proof binds semantic source, exact source head, qualified base, affected closure, dependency and toolchain roots, environment, heartbeat receipt, and shard evidence; PR-controlled native code and its complete readable process ancestry receive no controller or provider write credentials, the recursively enumerated transfer is an exact regular-file-only closed set staged separately from candidate evidence, an independent hosted heartbeat runner chains durable state and receipt roots through native and seal completion, and only a live-readback-proven distinct GitHub-hosted finalizer job and runner may verify the latest state, revalidate bytes, recompute canonical failure evidence, qualify, or settle the exact bound failure.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "packages/core/dev-delivery-native-proof.js",
+        "packages/core/dev-delivery-execution-failure.js",
+        "packages/core/dev-delivery-execution-transfer.js",
+        "packages/core/dev-delivery-process-boundary.js",
+        "packages/core/dev-delivery-provider-heartbeat.js",
+        "scripts/dev-delivery-native-run.mjs",
+        "scripts/dev-delivery-process-boundary.mjs",
+        "scripts/dev-delivery-provider-heartbeat.mjs",
+        ".github/workflows/dev-pr-auto-merge.yml"
+      ],
+      "verificationEvidence": [
+        "tests/dev-delivery-two-phase.test.mjs",
+        "tests/dev-delivery-native-run.test.mjs",
+        "tests/dev-delivery-process-boundary.test.mjs",
+        "tests/dev-delivery-process-boundary-negative.test.mjs",
+        "tests/dev-delivery-provider-heartbeat.test.mjs",
+        "tests/build-surface.test.mjs"
+      ],
+      "behavioralProof": "tests/v4-delivery-authority-parity.test.mjs#DA-03"
+    },
+    {
+      "id": "DA-04",
+      "claim": "Interruption resumes only from a live qualified fence or a proof whose complete attributed base delta remains disjoint; ambiguity or overlap revalidates.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "packages/core/dev-delivery-native-proof.js",
+        "scripts/dev-delivery-two-phase-resume.mjs"
+      ],
+      "verificationEvidence": [
+        "tests/dev-delivery-two-phase.test.mjs",
+        "tests/dev-delivery-two-phase-run.test.mjs"
+      ],
+      "behavioralProof": "tests/v4-delivery-authority-parity.test.mjs#DA-04"
+    },
+    {
+      "id": "DA-05",
+      "claim": "Native success upgrades the same fence atomically to qualified authority and records exact proof and reuse roots without minting a second token.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "packages/core/dev-delivery-native-proof.js",
+        "packages/core/dev-delivery-warrant.js"
+      ],
+      "verificationEvidence": ["tests/dev-delivery-two-phase.test.mjs"],
+      "behavioralProof": "tests/v4-delivery-authority-parity.test.mjs#DA-05"
+    },
+    {
+      "id": "DA-06",
+      "claim": "Expiry does not imply worker termination; an expired provisional holder remains exclusive until exact fenced terminal settlement, and duplicate settlement is idempotent.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "packages/core/dev-delivery-warrant.js",
+        "packages/core/dev-delivery-warrant-settlement.js"
+      ],
+      "verificationEvidence": [
+        "tests/dev-delivery-warrant.test.mjs",
+        "tests/dev-delivery-two-phase.test.mjs"
+      ],
+      "behavioralProof": "tests/v4-delivery-authority-parity.test.mjs#DA-06"
+    },
+    {
+      "id": "DA-07",
+      "claim": "GitHub merge_group and the protected Project Cut remain final integration authority; a Warrant alone never mutates branch protection or proves landing.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "packages/core/dev-delivery-proof.js",
+        "scripts/dev-pr-delivery-warrant.mjs",
+        ".github/workflows/dev-pr-auto-merge.yml"
+      ],
+      "verificationEvidence": [
+        "tests/dev-delivery-warrant.test.mjs",
+        "tests/dev-pr-auto-merge.test.mjs"
+      ],
+      "behavioralProof": "tests/v4-delivery-authority-parity.test.mjs#DA-07"
+    },
+    {
+      "id": "DA-08",
+      "claim": "Bounded mode issues no more than the configured Qualification Leases and only across disjoint rooted safety domains; unknown or overlapping domains serialize.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "packages/core/dev-delivery-authority-qualification.js",
+        "packages/core/dev-delivery-authority-state.js"
+      ],
+      "verificationEvidence": ["tests/dev-delivery-authority.test.mjs"],
+      "behavioralProof": "tests/v4-delivery-authority-parity.test.mjs#DA-08"
+    },
+    {
+      "id": "DA-09",
+      "claim": "Qualification authority cannot admit merge_group; a new Landing requires complete verified-native qualification, its public admission API derives provider identity only from live GitHub readback, and exactly one exclusive Landing Warrant binds the candidate, source head, token, generation, state root, protected base, merge-group head, and verified provider attempt.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "packages/core/dev-delivery-authority-landing.js",
+        "packages/core/dev-delivery-landing-admission-core.js",
+        "packages/core/dev-delivery-authority-qualification.js",
+        "contracts/dev-delivery-authority-v2.schema.json"
+      ],
+      "verificationEvidence": ["tests/dev-delivery-authority.test.mjs"],
+      "behavioralProof": "tests/v4-delivery-authority-parity.test.mjs#DA-09"
+    },
+    {
+      "id": "DA-10",
+      "claim": "Landing is fair under bounded overtaking, including strict FIFO at zero, and never exposes more than one landing writer under contention.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "packages/core/dev-delivery-authority-qualification.js",
+        "packages/core/dev-delivery-authority-landing.js"
+      ],
+      "verificationEvidence": ["tests/dev-delivery-authority.test.mjs"],
+      "behavioralProof": "tests/v4-delivery-authority-parity.test.mjs#DA-10"
+    },
+    {
+      "id": "DA-11",
+      "claim": "Every Landing admission derives the provider attempt through non-injectable live GitHub readback, and every admitted heartbeat carries that exact persisted attempt and renews only through the public GitHub workflow run-attempt and job readback; qualification expiry releases only qualification capacity, while every Landing Warrant remains exclusive until an independent terminal verifier reads the immutable historical attempt endpoint and returns fresh rooted evidence bound to state, fence, generation, candidate, admitted source head, provider run, provider job, and protected-base containment without depending on a mutable run projection, referenced-workflow inference, or the synchronized current PR head; runtime sealing enforces the published repository, protected-base, numeric identity, completed-state, run-conclusion, job-conclusion, pull-request-state, merged-flag, containment, and outcome schema, and every resulting settlement is deterministic and idempotent.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "packages/core/dev-delivery-authority-qualification.js",
+        "packages/core/dev-delivery-authority-landing.js",
+        "packages/core/dev-delivery-landing-admission-core.js",
+        "packages/core/dev-delivery-landing-readback.js"
+      ],
+      "verificationEvidence": ["tests/dev-delivery-authority.test.mjs"],
+      "behavioralProof": "tests/v4-delivery-authority-parity.test.mjs#DA-11"
+    },
+    {
+      "id": "DA-12",
+      "claim": "Expected-old state roots and non-force Git ref advancement serialize admission and prevent partial or competing writes from becoming two durable authorities.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "scripts/dev-delivery-authority.mjs",
+        "scripts/dev-delivery-warrant.mjs"
+      ],
+      "verificationEvidence": [
+        "tests/dev-delivery-authority.test.mjs",
+        "tests/dev-delivery-warrant-command.test.mjs"
+      ],
+      "behavioralProof": "tests/v4-delivery-authority-parity.test.mjs#DA-12"
+    },
+    {
+      "id": "DA-13",
+      "claim": "One-shot v1 migration preserves the rooted legacy state and exact active fence while representing phase-less and qualified v1 compatibility honestly; compatibility-only evidence cannot acquire v2 native proof authority or mint a new Landing Warrant.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "packages/core/dev-delivery-authority-state.js",
+        "scripts/dev-delivery-authority.mjs"
+      ],
+      "verificationEvidence": ["tests/dev-delivery-authority.test.mjs"],
+      "behavioralProof": "tests/v4-delivery-authority-parity.test.mjs#DA-13"
+    },
+    {
+      "id": "DA-14",
+      "claim": "Historical v1 queue bytes and native proofs remain readable, phase-less active-owner handoff uses exact legacy-safe bindings without a native command contract, and unbound or compatibility-only legacy proof cannot acquire new exact reuse or Landing authority.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "packages/core/dev-delivery-warrant.js",
+        "packages/core/dev-delivery-native-proof.js",
+        ".github/workflows/dev-pr-auto-merge.yml"
+      ],
+      "verificationEvidence": [
+        "tests/dev-delivery-authority.test.mjs",
+        "tests/dev-delivery-two-phase.test.mjs"
+      ],
+      "behavioralProof": "tests/v4-delivery-authority-parity.test.mjs#DA-14"
+    },
+    {
+      "id": "DA-15",
+      "claim": "The supported CLI, Node exports including independent Landing terminal readback, schema, documentation, generated references, and byte-exact generated site schema expose bounded v2 authority consistently, while the native template and Buildchain public v4-alpha caller truthfully remain single-flight v1 and do not advertise v2 Landing execution; matching stable and alpha contract locks preserve that explicit boundary.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "bin/buildchain.mjs",
+        "package.json",
+        "packages/core/dev-delivery-landing-readback.js",
+        "packages/core/dev-delivery-contract-surface.js",
+        "contracts/dev-delivery-authority-v2.schema.json",
+        "docs/dev-delivery-warrant.md",
+        "docs/dev-delivery-qualification-landing-adr.md",
+        "templates/native-dev-delivery.yml",
+        ".github/workflows/buildchain-dev-delivery.yml",
+        ".buildchain/contract-lock.json",
+        ".buildchain/alpha-contract-lock.json"
+      ],
+      "verificationEvidence": [
+        "tests/dev-delivery-authority.test.mjs",
+        "tests/dev-pr-auto-merge.test.mjs",
+        "tests/build-surface.test.mjs"
+      ],
+      "behavioralProof": "tests/v4-delivery-authority-parity.test.mjs#DA-15"
+    },
+    {
+      "id": "DA-16",
+      "claim": "Independent review, protected merge into dev/v4/v4.0, and exact post-merge readback are required external closeout evidence and are not established by local tests.",
+      "disposition": "missing-before-closeout",
+      "implementationEvidence": [],
+      "verificationEvidence": []
+    }
+  ],
+  "matrixRoot": "sha256:5be5abf70b982374f32a1400d4ec7c830017a0473d03165e831a506c94c8b881"
+}

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

@@ -61,7 +61,7 @@
           "now": "2026-08-07T00:02:00Z"
         }
       ],
-      "expectedLegacyProjectionRoot": "sha256:e01018e4797e98813454328aba2c0a04932885fcd6da7d216697c7961bc26f56"
+      "expectedLegacyProjectionRoot": "sha256:d360d0c66dde487b9020b1b0e90d0c7a3e0777bdfbac72f9ac40602bbe419826"
     },
     {
       "id": "lease-expiry-and-stale-fence",
@@ -76,36 +76,59 @@
           "id": "submit",
           "operation": "submit",
           "pullRequestNumber": 120,
+          "overrides": {
+            "environmentRoot": "sha256:9999999999999999999999999999999999999999999999999999999999999999",
+            "nativeCommandContract": {
+              "schema": "kungfu.buildchain.native-command-contract/v1",
+              "runner": "bash-lc",
+              "command": "node --test tests/v4-warrant-shadow-plan.test.mjs",
+              "commandRoot": "sha256:4d9a03536802c46fe254f247b7236925aec49d789e5e9ac7b2dceac08d7cefab"
+            }
+          },
           "now": "2026-08-07T01:00:01Z"
         },
+        {
+          "id": "submit-successor",
+          "operation": "submit",
+          "pullRequestNumber": 121,
+          "now": "2026-08-07T01:00:02Z"
+        },
         {
           "id": "select-old",
           "operation": "select",
           "saveWarrant": "old",
           "leaseSeconds": 60,
-          "now": "2026-08-07T01:00:02Z"
+          "now": "2026-08-07T01:00:03Z"
         },
         {
           "id": "recover",
           "operation": "recover-expired",
           "now": "2026-08-07T01:02:00Z"
         },
+        {
+          "id": "close-expired",
+          "operation": "close",
+          "useWarrant": "old",
+          "outcome": "terminal-failure",
+          "reason": "fenced native worker stop proved",
+          "now": "2026-08-07T01:02:01Z"
+        },
         {
           "id": "select-new",
           "operation": "select",
           "saveWarrant": "new",
           "leaseSeconds": 60,
-          "now": "2026-08-07T01:02:01Z"
+          "now": "2026-08-07T01:02:02Z"
         },
         {
           "id": "reject-old",
           "operation": "heartbeat",
           "useWarrant": "old",
           "expectError": "stale-fencing-token",
-          "now": "2026-08-07T01:02:02Z"
+          "now": "2026-08-07T01:02:03Z"
         }
       ],
-      "expectedLegacyProjectionRoot": "sha256:3c39ba66a2329a22f3834c4212bda001b6d5c527dcb9fa8a1b3ca88a199a7d16"
+      "expectedLegacyProjectionRoot": "sha256:64065e071d1099cb2187b57ba111fc444c95dc958dc6f97dc912e40c1738a081"
     },
     {
       "id": "settlement-idempotence",
@@ -153,7 +176,7 @@
           "now": "2026-08-07T02:02:00Z"
         }
       ],
-      "expectedLegacyProjectionRoot": "sha256:b67669b2093105f3b4539ca5e4ba3d366bd7005a8781b5352377ae724d310d26"
+      "expectedLegacyProjectionRoot": "sha256:4f8a9030750600b2f87f627c33d63147ae33a1612c6a5022fb21474ad6118015"
     },
     {
       "id": "queued-cancellation-idempotence",

package/bin/buildchain.mjs

@@ -1385,12 +1385,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;