diff --git a/.github/workflows/integration-candidate-prepare.yml b/.github/workflows/integration-candidate-prepare.yml
index 2de0f77302..a61de085f0 100644
--- a/.github/workflows/integration-candidate-prepare.yml
+++ b/.github/workflows/integration-candidate-prepare.yml
@@ -1,4 +1,5 @@
name: Prepare integration candidates
+run-name: Prepare integration ${{ inputs.request_key || github.event.client_payload.request_key || 'manual' }}
on:
repository_dispatch:
@@ -9,6 +10,10 @@ on:
description: Bounded versioned request from an explicitly enrolled integration controller.
required: true
type: string
+ request_key:
+ description: Optional canonical request digest for explicit controller reconciliation.
+ required: false
+ type: string
permissions:
contents: read
@@ -39,12 +44,17 @@ jobs:
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
env:
INTEGRATION_REQUEST: ${{ inputs.request || github.event.client_payload.request }}
+ INTEGRATION_REQUEST_KEY: ${{ inputs.request_key || github.event.client_payload.request_key }}
GH_TOKEN: ${{ github.token }}
with:
retries: 0
script: |
const fs = require('node:fs');
- const {canonical, gitRunner, prepare} = require('./.github/scripts/integration-materialize.cjs');
+ const {canonical, digest, gitRunner, prepare} = require('./.github/scripts/integration-materialize.cjs');
+ if (process.env.INTEGRATION_REQUEST_KEY &&
+ digest(canonical(JSON.parse(process.env.INTEGRATION_REQUEST))) !== process.env.INTEGRATION_REQUEST_KEY) {
+ throw new Error('Controller request key differs from the exact bounded request');
+ }
const receipt = await prepare({
github, context,
requestText: process.env.INTEGRATION_REQUEST,
diff --git a/changelog.d/added-integration-candidate-engine.md b/changelog.d/added-integration-candidate-engine.md
new file mode 100644
index 0000000000..e520c0f0ab
--- /dev/null
+++ b/changelog.d/added-integration-candidate-engine.md
@@ -0,0 +1 @@
+- Add independent default-OFF integration execution enrollment, versioned private candidate provenance and actual runner accounting, designated-executor authority, bounded preparation admission, and exact protected-prefix promotion guards without replacing normal review, trust, CI, hold, or native-queue authority.
diff --git a/dashboard/openapi.json b/dashboard/openapi.json
index e5823f55d9..c87d673e75 100644
--- a/dashboard/openapi.json
+++ b/dashboard/openapi.json
@@ -97,16 +97,30 @@
}
}
},
+ "/api/integration-orchestration/execution-identity": {
+ "post": {
+ "tags": ["System"],
+ "summary": "Prepare create-only local execution identity (owner only)",
+ "description": "Creates or reads the private local installation identity and durable execution journal. Returns a designated executor ID and explicit disabled status. This does not enroll an executor, grant permissions, change configuration, dispatch CI or enable promotion. Cloned identity and automatic failover are unsupported.",
+ "responses": {
+ "200": {"description": "Local executor identity and explicit no-activation limits"},
+ "403": {"description": "Owner role required"},
+ "503": {"description": "Private durable identity or journal unavailable"}
+ }
+ }
+ },
"/api/config/integration-orchestration": {
"put": {
"tags": ["System"],
"summary": "Replace bounded integration orchestration configuration (owner only)",
- "description": "Full off|advisory|enforce configuration with exact repository/base scopes, static execution/admission budgets, bounded lease/window/age/retries and optional pinned workflow contracts. JSON durations use nanoseconds. Disabling is independent of evidence-store availability and never releases authoritative claims/native entries.",
+ "description": "Full off|advisory|enforce configuration with independent execution opt-in, exact repository/base scopes, static budgets, bounded lease/window/age/retries and pinned producer/actor/authority profiles. JSON durations use nanoseconds. Execution changes require expected_execution compare-and-swap. Enforced Hive authority must be verifiably revoked at its shared forge epoch before OFF/advisory or authority handover. Execution-only updates never release authoring reservations; rollback retains evidence and unknown mutation outcomes and never releases authoritative claims/native entries.",
"requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object"}}}},
"responses": {
"200": {"description": "Validated effective configuration"},
"400": {"description": "Invalid mode, scope, contract or bounds"},
"403": {"description": "Owner role required"},
+ "409": {"description": "Old Hive authority epoch not verifiably revoked"},
+ "412": {"description": "Execution profile changed or expected_execution missing/stale"},
"500": {"description": "Configuration could not be persisted"},
"503": {"description": "Enforcement ledger unavailable; disable remains permitted"}
}
diff --git a/src/cmd/hive/boot.go b/src/cmd/hive/boot.go
index e8621d5aeb..9b8f9e215f 100644
--- a/src/cmd/hive/boot.go
+++ b/src/cmd/hive/boot.go
@@ -92,9 +92,11 @@ type boot struct {
// rebuilt client after that; forgeStateOnce guards the build. Held in
// an atomic because the dashboard's count wiring reads it late, from
// the metrics collector goroutine (#13376).
- forgeState atomic.Pointer[forgestate.Store]
- forgeStateOnce sync.Once
- requestRelays *requestRelaySupervisor
+ forgeState atomic.Pointer[forgestate.Store]
+ forgeStateOnce sync.Once
+ requestRelays *requestRelaySupervisor
+ integrationEligibility automerge.IntegrationEligibilityGate
+ integrationPreparationEligibility automerge.IntegrationEligibilityGate
// bootConfig
startTime time.Time
diff --git a/src/cmd/hive/main.go b/src/cmd/hive/main.go
index fc4f7aa4ba..95bb09c5a8 100644
--- a/src/cmd/hive/main.go
+++ b/src/cmd/hive/main.go
@@ -2057,6 +2057,37 @@ func (b *boot) bootAgentsWith(deps bootAgentsDeps) {
// Resolved lazily: bootDashboard has not run yet, so b.dashSrv is nil
// here (see lateContributorNudgeSink).
autoMergeOpts.ContributorNudge = lateContributorNudgeSink{hub: func() *dashboard.ContributeWSHub { return b.dashSrv.ContributeHub() }}
+ autoMergeOpts.IntegrationExecution = func(ctx context.Context, repo string, pr *gh.PullRequest, gate automerge.IntegrationEligibilityGate) (automerge.IntegrationExecutionDecision, error) {
+ if b.dashSrv != nil {
+ return b.dashSrv.IntegrationExecutionRoute(ctx, repo, pr, gate)
+ }
+ execution := b.cfg.IntegrationOrchestration.Execution.Effective()
+ if execution.Mode == config.IntegrationEnforce {
+ if _, enrolled := execution.Scope(repo, pr.GetBase().GetRef()); enrolled {
+ return automerge.IntegrationExecutionDecision{Authority: "hold", Reason: "integration execution initializes before any selected-destination writer"}, nil
+ }
+ }
+ return automerge.IntegrationExecutionDecision{}, nil
+ }
+ autoMergeOpts.IntegrationAdmission = func(ctx context.Context, repo string, pr *gh.PullRequest) (string, error) {
+ if b.dashSrv != nil {
+ return b.dashSrv.IntegrationNativeAdmission(ctx, repo, pr)
+ }
+ return "", nil
+ }
+ autoMergeOpts.IntegrationFilesObserved = func(repo, head string, files []string) {
+ if b.dashSrv != nil {
+ b.dashSrv.IntegrationObserveFiles(repo, head, files)
+ }
+ }
+ autoMergeOpts.NativeMergeQueue = func() automerge.NativeMergeQueuePolicy {
+ q := b.cfg.AutoMerge.NativeMergeQueue
+ return automerge.NativeMergeQueuePolicy{Enabled: q.Enabled, Repos: q.RepoSet(), Bases: q.BaseSet(),
+ SkipCurrentBaseGate: q.SkipCurrentBaseGate, ProbeTTL: q.EffectiveProbeTTL()}
+ }
+ autoMergeOpts.IntegrationSelfAllowed = func() bool {
+ return b.cfg.AutoMerge.SelfAuthoredAutoMergeAllowed(b.cfg.ACMMLevel)
+ }
// commitGreen's required-checks gate (self-merge sweep, see
// automerge_sweep.go): install the operator-declared
@@ -2231,6 +2262,20 @@ func (b *boot) bootAgentsWith(deps bootAgentsDeps) {
return joinDone(relaysDone, sweepDone)
}, b.logger)
b.armRequestRelays(b.ghClient)
+ b.integrationEligibility = func(ctx context.Context, repo, base string, number int, head string) (*gh.PullRequest, string, error) {
+ client := b.currentGitHubClient()
+ if client == nil {
+ return nil, "live normal-policy GitHub client unavailable", github.ErrNoGitHubClient
+ }
+ return automerge.New(client, autoMergeOpts).IntegrationEligibility(ctx, repo, base, number, head)
+ }
+ b.integrationPreparationEligibility = func(ctx context.Context, repo, base string, number int, head string) (*gh.PullRequest, string, error) {
+ client := b.currentGitHubClient()
+ if client == nil {
+ return nil, "live normal-policy GitHub client unavailable", github.ErrNoGitHubClient
+ }
+ return automerge.New(client, autoMergeOpts).IntegrationPreparationEligibility(ctx, repo, base, number, head)
+ }
// Opt-in mint credential: when mint.enabled, build a Minter from the config
// (signing key + issuer + TTL) and attach it so each per-agent token refresh
@@ -2391,6 +2436,7 @@ func (b *boot) bootDashboard() { b.bootDashboardWith(defaultBootDashboardDeps())
// persistence enables injected; see bootDashboardDeps.
func (b *boot) bootDashboardWith(deps bootDashboardDeps) {
b.dashSrv = deps.newServer(b.cfg.Dashboard.Port, b.cfg.Dashboard.AuthToken, b.logger)
+ b.dashSrv.SetIntegrationExecutionEvaluators(b.integrationPreparationEligibility, b.integrationEligibility)
worksource.SetRunStageAccessor(b.dashSrv.RunStageAccessor())
b.dashSrv.SetWritebackGate(b.writebackGate())
b.dashSrv.SetHotspotSource(hotspotDashSource{store: hotspotStore()})
diff --git a/src/cmd/hive/main_eval_cycle.go b/src/cmd/hive/main_eval_cycle.go
index 557b640da0..e15fd672f6 100644
--- a/src/cmd/hive/main_eval_cycle.go
+++ b/src/cmd/hive/main_eval_cycle.go
@@ -949,6 +949,13 @@ func runEvalCycle(
if err := dashSrv.ReconcileIntegration(ctx); err != nil {
logger.Warn("integration observations incomplete", "error", err)
}
+ if cfg.IntegrationOrchestration.Execution.Effective().Mode != config.IntegrationOff {
+ go func() {
+ if err := dashSrv.ReconcileIntegrationExecution(ctx); err != nil {
+ logger.Warn("integration execution bounded reconciliation incomplete", "error", err)
+ }
+ }()
+ }
kickActionable = dashSrv.IntegrationKickAdmission(kickActionable)
sched.SetLastActionable(kickActionable)
diff --git a/src/cmd/hive/main_sweeps.go b/src/cmd/hive/main_sweeps.go
index dc4516166c..3e43093484 100644
--- a/src/cmd/hive/main_sweeps.go
+++ b/src/cmd/hive/main_sweeps.go
@@ -815,6 +815,7 @@ func runAutoMergeSweepIfDue(ctx context.Context, ghClient *github.Client, cfg *c
defer sweepSpan.End()
opts := automerge.Options{
IntegrationAdmission: dashSrv.IntegrationNativeAdmission,
+ IntegrationExecution: dashSrv.IntegrationExecutionRoute,
IntegrationFilesObserved: dashSrv.IntegrationObserveFiles,
Logger: logger,
MergerAuthorizer: trustedMergerFunc(cfg),
diff --git a/src/docs/integration-orchestration.md b/src/docs/integration-orchestration.md
index d32a71cabb..7642cd3a39 100644
--- a/src/docs/integration-orchestration.md
+++ b/src/docs/integration-orchestration.md
@@ -5,14 +5,15 @@ and GitHub's native queue. It is not a merge engine and does not activate either
authority. Every existing CI, review, trust, DCO, coverage, soak, hold and
current-base guard remains authoritative. Nothing deploys automatically.
-## Experimental execution: protocol foundation, not an activated engine
+## Exact protected-promotion protocol
-The existing authoring layer above remains distinct from future Hive-owned
-candidate execution. Neither `mode: enforce` nor upgrading Hive authorizes a
-new destination writer. There is currently **no installed Hive candidate
-producer, execution controller, execution opt-in, or tracker execution region**.
-The low-level promotion protocol described here does not claim those pieces
-exist. OFF and ADVISORY do not call it; no existing merge lane calls it.
+The authoring layer remains distinct from separately opted-in Hive-owned
+candidate execution. Neither the parent `mode: enforce` nor upgrading Hive
+authorizes a new destination writer. The source includes the trusted producer,
+execution controller, independent configuration and inline tracker captions
+described below. Source availability is not a deployed or qualified executor.
+Execution OFF and ADVISORY never dispatch or promote; existing merge lanes
+retain their normal gates and route enrolled execution subjects explicitly.
The first protocol is `integration-first-parent-v1`, intentionally limited to
preserving-history merge commits on GitHub. For a tested step `S`, its ordered
@@ -24,9 +25,10 @@ destinations without a compatible producer are unsupported, not bypassed.
GitHub documents an actual compare-and-swap:
[`updateRefs` with `RefUpdate.beforeOid`, `afterOid`, and `force:false`](https://docs.github.com/en/graphql/reference/git#updaterefs).
-All listed updates are atomic. The initial adapter updates one destination
-while conditionally keeping the same-repository author ref at its exact old
-head. If the author pushes before that transaction, neither ref update applies.
+All listed updates are atomic. The controller updates one destination while
+conditionally keeping the same-repository author ref and registered authority
+epoch at their exact old commits. If the author pushes or authority is revoked
+before that transaction, none of the ref updates applies.
This no-op comparison is not an author-branch rewrite or persistent lock.
The provider must accept the conditional no-op under its actual rules; refusal
blocks promotion and never removes the head fence. Fork heads cannot participate
@@ -35,17 +37,18 @@ promotion protocol, not silently trusted from a prior REST read.
It does not use REST `UpdateRef(force:true)`, a read followed by a write, or the
PR merge API's author-head fence as a destination fence. Its stable mutation
claim binds protocol, repository/base, expected destination, tested commit/tree,
-author head/repository/ref, subject, policy and generation through the existing
+author head/repository/ref, authority epoch, subject, policy and generation through the existing
effects boundary.
`clientMutationId` binds acknowledgement; it is **not** provider idempotency.
The resolved repository identity must also match the enrolled name: a redirect
after a repository rename/transfer is not authority to write a different scope.
A durable boundary and non-nil live eligibility guard are mandatory. The
-transport refuses a no-op boundary. The future controller must supply exclusive
+transport refuses a no-op boundary. The opt-in controller supplies exclusive
destination authority, exact complete trusted CI, review, trust, DCO, coverage,
-soak, release and hold checks. This callback is not yet a production wiring of
-those gates. Provider branch rules remain authoritative and rejection does not
+soak, release and hold checks through the original full boot-policy evaluator.
+Its read-only probes isolate tracker/preparation state and disable planner
+writes. Provider branch rules remain authoritative and rejection does not
permit a fallback, force update or privilege expansion. Destination CAS does
not atomically snapshot GitHub's independently mutable PR/review/hold fields
other than the separately fenced same-repository source ref:
@@ -69,10 +72,11 @@ lineage reconciliation; the transport does not guess that it was promoted.
### Execution feasibility gates
-Before any future execution opt-in can pass server validation:
+Before production execution may be enabled and qualified:
-1. A versioned trusted CI producer must be installed and verified on the trusted
- base. Existing `v2-ci.yml` has no dispatch trigger; existing `v2-tests.yml`
+1. The source producer must be installed and verified on the trusted
+ base with its exact reviewed workflow/action closure. Ordinary `v2-ci.yml`
+ dispatch is not a candidate producer; ordinary `v2-tests.yml`
manual runs are not candidate attestations and include scheduled/manual
soft-failure behavior. Merely dispatching either does not supply combined
validation. The current direct-path artifact consumer is single-PR/event
@@ -95,7 +99,7 @@ Before any future execution opt-in can pass server validation:
5. Native-config-selected repositories are reserved to the native authority
unless a narrower **landed** selection contract proves otherwise. Native
detection errors are unknown, not permission for a Hive writer. Existing
- default-branch preparation and its tracker reference rail are unchanged.
+ default-branch preparation and its inline tracker rails are unchanged.
6. Accounting must cover the entire candidate attempt cohort. The current
ledger size and bounded historical pagination limits remain real scale
blockers; missing history is neither zero cost nor growth permission.
@@ -121,7 +125,7 @@ feasibility; durable candidate identities and parallel bounded dispatch;
live-gated exact promotion and recovery; opt-in cached execution diagnostics;
and comparative benchmarks. Existing authoring admission and preparation are
reused, not replaced. This sequence is an engineering decomposition, not a
-claim that the strategy is optimal or already implemented.
+claim that the strategy is optimal or empirically qualified.
The evidence behind these choices is deliberately qualified:
@@ -350,11 +354,12 @@ Their distinct concurrency groups do not cancel another reusable technical
workflow in the same caller run. Candidate code never runs in issue/release
writers; no repository secrets may be inherited by a candidate caller.
-These call seams and the producer verifier are source support, not an installed
-producer, execution controller, runtime opt-in, protection migration or
-execution-readiness claim. Existing authoring enforce mode does not activate
-them. The current eleven-context destination contract still needs genuine
-candidate-aware producers; author-head green statuses must not be copied.
+These call seams and the producer verifier are used by the separately opted-in
+controller below. Their source availability is not runtime activation,
+protection migration or execution-readiness proof. Existing authoring enforce
+mode does not activate execution. Every actual required destination context
+still needs a genuine compatible candidate-aware producer; author-head green
+statuses must not be copied.
The producer identity protocol uses
[GitHub OIDC claims](https://docs.github.com/en/actions/reference/security/oidc)
@@ -373,8 +378,9 @@ reviewed workflow/action closure, real successful finalizer and required
technical jobs, immutable artifact identity/digest and complete observations.
Signed issuance must fall within the independently observed finalizer interval;
a historical attestation is not a currently valid bearer login or live
-promotion authorization. Rotation/durable verification history and the actual
-isolated provider execution remain required lifecycle work.
+promotion authorization. Verified historical signatures and pinned key material
+are archived privately for durable replay; an actual isolated provider execution
+remains an operator qualification requirement.
Executing untrusted candidate code from a default-ref dispatch can expose that
ref's Actions-cache namespace even with a read-only GitHub token. The intended
@@ -417,8 +423,8 @@ bounded work-in-progress, anti-starvation and invalidation/failed-execution cost
not skipping validation. The bounded authoring/admission layer supplies neither ML prioritization,
custom batching, batch bisection nor another merge authority. Native group
observations only describe groups GitHub created. The separately opt-in
-candidate producer source described below constructs exact speculative prefixes;
-it is not an installed promotion controller.
+candidate producer constructs exact speculative prefixes; only the separately
+enrolled and qualified controller below can promote them.
There is no automatic live pilot, adaptive concurrency growth, runner
procurement or claim of 5,000 merged PRs/day. That is an empirical capacity
@@ -511,9 +517,9 @@ commit/tree/workflow closure. Their source tests include changed attempts,
partial publication and mismatched producers/subjects; they do not prove an
installed provider execution. Actual job observations include materialization
and finalizer overhead, not just local recorder time. Durable verification/key
-history, controller wiring and shared promotion authority handover are still
-required. Existing
-eleven protected-branch contexts do not automatically become satisfied by
+history and controller wiring are implemented in source; deployment, shared
+authority enrollment/handover and real qualification remain operator steps.
+Existing protected-branch contexts do not automatically become satisfied by
prefixed reusable jobs. No copied DCO/review greens, branch-rule bypass,
signature/linear-history downgrade or unproved conditional no-op is permitted.
Protection-compatible exact-commit promotion must be verified using the actual
@@ -539,3 +545,125 @@ deployed runtime, desired mode and effective writer are distinct facts.
| Preserve documented promoted prefixes; invalidate changed dependent subjects | [Zuul speculative execution](https://zuul-ci.org/docs/zuul/latest/gating.html) and GitHub merge-group semantics; provider behavior is not Hive parity | Prefix identity stable across observer/lease generations; never recast A+B proof as B-only |
| Fixed bounded admission before adaptation | Little's-law capacity accounting describes average WIP, not tail latency or fairness | Assigned-job wall minutes, shared-job dedup, unknown completeness, aging/fairness and explicit limits |
| Trusted control, isolated technical jobs/finalizers | GitHub trigger/cache/OIDC contracts; provider receipts and protections still need isolated verification | No candidate checkout in privileged/finalizer jobs; exact job-bound identities, no skipped writer permissions, ambiguous claims never retried blindly |
+## Opt-in candidate execution controller
+
+The separate `integration_orchestration.execution` configuration defaults to
+**off**. Source delivery is not deployment, published-image verification,
+runtime enablement, protected-provider qualification, or a throughput receipt.
+The existing authoring layer and preparation/native queue authorities remain
+separate. No existing convergence flag enables this controller.
+
+The controller journals exact ordered recipes and their canonical work/DAG
+generations before preparation, observes the installed materializer and
+candidate workflows, archives verified producer signatures privately, and
+accounts actual assigned-runner jobs across run attempts. It discovers bounded
+workflow cohorts; absent, duplicated, truncated, stale, or unowned observations
+remain unknown. Duplicate deliveries and historical attempts consume accounting
+budget and are never treated as free. Shared physical jobs are deduplicated.
+Canceled execution counts; queued/skipped jobs are not execution. A restart
+retains job facts and signed evidence but rebuilds accounting completeness.
+
+Verified terminal receipts are reused only while actual discovery confirms the
+same completed run/attempt. Oldest-observed pending prefixes rotate through a
+bounded read budget without changing stored prefix order. A partially published
+recipe cannot become a wholly passed recipe: valid prefix receipts survive
+independently, and the unpublished tail remains rejected/unresolved.
+
+## Authority and promotion limits
+
+Hive authority supports an explicitly designated installation executor and
+observer-only enrolled peers. Its create-only private installation identity
+does not register or grant permissions. An immutable forge authority record,
+exact epoch, actual GitHub App installation, and identical reviewed producer
+profile are prerequisites. Copied identities/credentials, automatic takeover,
+TTL stealing, and independent legacy writers are not supported. A local
+filesystem lock is not cross-hive fencing.
+
+Preparation dispatch is durably journaled before the RPC. Confirmed non-applied
+refusals alone permit bounded retry after cooldown; unknown outcomes do not.
+Repository-dispatch/bootstrap overhead is **not exactly once**. This protocol
+does not authorize legacy Actions reruns or solve crash ambiguity for an RPC
+that cannot consume a fence. CI-reporting observations remain detection and
+owner-action-required, not recovery permission.
+
+Promotion uses only the exact tested prefix commit/tree, the exact current
+predecessor, and documented actually merged earlier prefixes. Fresh promotion
+rechecks unique candidate run/claim/latest attempt, canonical work/DAG/scope,
+the complete original merge lane, current heads/base, reviews/holds and provider
+policy. Its atomic mutation fences destination, author branch and authority
+epoch together. No copied green status, squash/rebase substitute, native
+fallback, or unsupported protection bypass is permitted.
+
+The initial supported provider profile is deliberately conservative. Resolved
+ruleset/classic protection and bypass metadata must be readable and supported;
+ambiguous permission/404 responses, native merge-queue rules on a Hive
+destination, or unsupported bypass/merge policy refuse qualification. A real
+one-member isolated protected probe must demonstrate the exact actor, technical
+context compatibility, no-op reference-fence behavior, actual CAS and exact PR
+merge acknowledgement. A configured qualification ID is not a receipt.
+An ambiguous crash/reconciled destination without a durable successful provider
+RPC acknowledgement cannot qualify the actor; it requires a new isolated probe.
+Multi-member empirical scale remains a separate operator-approved experiment.
+
+Native authority uses only ordinary Hive enqueue admission and existing cached
+native observations. GitHub owns native promotion, group composition and build
+windows. Hive cannot jump the queue or control unsupported GitHub concurrency.
+
+## Configuration and safe rollback
+
+Settings → Features exposes an independent execution mode and a bounded profile
+JSON editor in the existing integration subsection. Explicit repository/base
+allowlists, actual actor/App/workflow IDs, policy/workflow hashes, executor/epoch
+and qualification pins, and validated member/job/minute/attempt/time bounds are
+required. Durations in that JSON editor are nanoseconds. Configuration updates
+compare `expected_execution` against the loaded profile; stale updates fail
+instead of silently replacing another owner's enrollment.
+
+**Advisory** may observe but cannot block, dispatch or promote. **Enforce** may
+use only authoritative permitted constraints and requires the parent authoring
+observer enrolled for every identical repository/base. Static finite budgets
+come first; missing telemetry freezes growth, not safety-network execution.
+This implementation does not automatically change live concurrency or enable
+an adaptive pilot.
+
+The initial controller is deliberately bounded, not throughput-qualified: its
+fallback turn is three minutes, event nudges coalesce to at most one per minute,
+and each turn visits at most two enrolled scopes and promotes at most one
+exact step per visited Hive scope. These source limits are real performance
+constraints, not measured 5,000/day capacity. Eligibility probes rotate bounded
+windows past older unready PRs; repository/base turns rotate independently.
+Declared expected jobs/minutes are conservative admission reservations to be
+reviewed against the actual qualified producer fanout and measured cohorts,
+not provider-enforced execution quotas or permission to guess runner capacity.
+Already admitted work may exceed an estimate; actual observed spend remains
+charged and freezes further admission at the configured bounds.
+
+Before exclusive activation, operators must deploy a verified image, stop or
+upgrade/enroll every participating legacy writer, register one executor,
+install and verify the narrowly scoped App/workflow/producer policy, run the
+isolated protected qualification, and independently inspect actual source,
+image, runtime mode, effective writer, cohort completeness and fresh gates.
+No such live action follows automatically from merging source.
+
+Before releasing an enforced Hive scope to off/advisory or another authority,
+move its shared forge authority ref away from the old epoch and verify that
+revocation. The configuration endpoint requires a live revocation observation,
+cancels its bounded controller, and releases only this layer's scoped admission
+reservations. Unknown effects, signed evidence and mutation audit remain.
+An outage is not proof of revocation, and revocation does not deduplicate an
+already ambiguous preparation RPC. Operator handover must account for that
+explicit limitation before allowing another executor.
+
+The activity monitor adds bounded cached, archive-free captions to matching
+actual root/nested PR rows only. Exact repository, PR, full author head and base
+must match; a proof for A+B does not become A's proof. Captions distinguish stale
+unknown observations and technical success from live merge permission. Existing
+stages, sorting/filtering/tree, inline preparation rails and native queue region
+remain unchanged; there is no second gold/reference panel or new poller.
+
+There is **no claim of 5,000/day or a live candidate benchmark** from source CI,
+fixture timings, the pre-existing merge stream, or a disabled controller.
+Production measurement must separately report actual candidate/cohort identities,
+runner execution cost including cancellation/bootstrap, author-review versus
+integration receipts, outcomes/latency, and completeness over fixed windows.
+Published image and current runtime provenance remain unknown until measured.
diff --git a/src/pkg/config/integration_execution.go b/src/pkg/config/integration_execution.go
new file mode 100644
index 0000000000..13750512f0
--- /dev/null
+++ b/src/pkg/config/integration_execution.go
@@ -0,0 +1,202 @@
+package config
+
+import (
+ "fmt"
+ "math"
+ "strings"
+ "time"
+)
+
+const (
+ MaxIntegrationExecutionCandidates = 8
+ MaxIntegrationExecutionJobs = 100
+ MaxIntegrationExecutionPriority = 10
+ MaxIntegrationExecutionMinutes = 10000
+ MinIntegrationExecutionInterval = time.Minute
+ MaxIntegrationExecutionInterval = time.Hour
+ MaxIntegrationExecutionWindow = 24 * time.Hour
+)
+
+// IntegrationExecutionConfig is independent of authoring admission. Its zero
+// value is OFF; no legacy convergence flag enables a promotion writer.
+type IntegrationExecutionConfig struct {
+ Mode string `yaml:"mode,omitempty" json:"mode"`
+ Scopes []IntegrationExecutionScope `yaml:"scopes,omitempty" json:"scopes"`
+ MaxActive int `yaml:"max_active,omitempty" json:"max_active"`
+ MaxRunnerMinutes float64 `yaml:"max_runner_minutes,omitempty" json:"max_runner_minutes"`
+ MaxJobs int `yaml:"max_jobs,omitempty" json:"max_jobs"`
+ MaxAttempts int `yaml:"max_attempts,omitempty" json:"max_attempts"`
+ ObservationAge time.Duration `yaml:"observation_age,omitempty" json:"observation_age"`
+ Window time.Duration `yaml:"window,omitempty" json:"window"`
+ Cooldown time.Duration `yaml:"cooldown,omitempty" json:"cooldown"`
+}
+
+// IntegrationExecutionScope pins the installed provider/profile and explicit
+// designated executor. Native scopes admit/observe only: GitHub retains control.
+type IntegrationExecutionScope struct {
+ Repo string `yaml:"repo" json:"repo"`
+ Base string `yaml:"base" json:"base"`
+ Authority string `yaml:"authority" json:"authority"`
+ RepositoryID int64 `yaml:"repository_id" json:"repository_id"`
+ RequestActorID int64 `yaml:"request_actor_id" json:"request_actor_id"`
+ CandidateActorID int64 `yaml:"candidate_actor_id" json:"candidate_actor_id"`
+ ProducerAppID int64 `yaml:"producer_app_id" json:"producer_app_id"`
+ PromotionAppID int64 `yaml:"promotion_app_id" json:"promotion_app_id"`
+ PromotionInstallationID int64 `yaml:"promotion_installation_id" json:"promotion_installation_id"`
+ MaterializerID int64 `yaml:"materializer_id" json:"materializer_id"`
+ CandidateWorkflowID int64 `yaml:"candidate_workflow_id" json:"candidate_workflow_id"`
+ DefaultBranch string `yaml:"default_branch" json:"default_branch"`
+ Policy string `yaml:"policy" json:"policy"`
+ WorkflowTree string `yaml:"workflow_tree" json:"workflow_tree"`
+ RequiredJobs []string `yaml:"required_jobs" json:"required_jobs"`
+ ExecutorID string `yaml:"executor_id" json:"executor_id"`
+ AuthorityRef string `yaml:"authority_ref" json:"authority_ref"`
+ AuthorityCommit string `yaml:"authority_commit" json:"authority_commit"`
+ QualificationID string `yaml:"qualification_id" json:"qualification_id"`
+ MaxMembers int `yaml:"max_members" json:"max_members"`
+ ExpectedJobs int `yaml:"expected_jobs" json:"expected_jobs"`
+ ExpectedMinutes float64 `yaml:"expected_minutes" json:"expected_minutes"`
+ Purpose string `yaml:"purpose,omitempty" json:"purpose,omitempty"`
+ QualifiedBase string `yaml:"qualified_base,omitempty" json:"qualified_base,omitempty"`
+}
+
+func (c IntegrationExecutionConfig) Effective() IntegrationExecutionConfig {
+ if c.Mode == "" {
+ c.Mode = IntegrationOff
+ }
+ return c
+}
+
+func executionDigest(value string, length int) bool {
+ return len(value) == length && strings.Trim(value, "0123456789abcdef") == "" && strings.Trim(value, "0") != ""
+}
+
+func executionBranch(value string) bool {
+ if value == "" || value == "@" || strings.HasSuffix(value, ".") ||
+ strings.ContainsAny(value, " ~^:?*[\\") || strings.Contains(value, "..") || strings.Contains(value, "@{") {
+ return false
+ }
+ for _, part := range strings.Split(value, "/") {
+ if part == "" || strings.HasPrefix(part, ".") || strings.HasSuffix(part, ".lock") {
+ return false
+ }
+ }
+ for _, character := range value {
+ if character < ' ' || character == '\x7f' {
+ return false
+ }
+ }
+ return true
+}
+
+func executionRepository(value string) bool {
+ parts := strings.Split(value, "/")
+ if len(parts) != 2 {
+ return false
+ }
+ for _, part := range parts {
+ if part == "" || part == "." || part == ".." {
+ return false
+ }
+ for _, character := range part {
+ if character >= 'a' && character <= 'z' || character >= 'A' && character <= 'Z' ||
+ character >= '0' && character <= '9' || strings.ContainsRune("-_.", character) {
+ continue
+ }
+ return false
+ }
+ }
+ return true
+}
+
+func (c IntegrationExecutionConfig) Validate() error {
+ c = c.Effective()
+ if c.Mode != IntegrationOff && c.Mode != IntegrationAdvisory && c.Mode != IntegrationEnforce {
+ return fmt.Errorf("integration execution mode must be off, advisory or enforce")
+ }
+ if c.Mode == IntegrationOff && len(c.Scopes) == 0 {
+ if c.MaxActive != 0 || c.MaxJobs != 0 || c.MaxAttempts != 0 || c.MaxRunnerMinutes != 0 ||
+ c.ObservationAge != 0 || c.Window != 0 || c.Cooldown != 0 {
+ return fmt.Errorf("unscoped OFF execution must use zero bounds; retain explicit scopes and valid bounds when rolling back")
+ }
+ return nil
+ }
+ if len(c.Scopes) == 0 || len(c.Scopes) > MaxIntegrationScopes ||
+ c.MaxActive < 1 || c.MaxActive > MaxIntegrationExecutionCandidates ||
+ c.MaxJobs < 1 || c.MaxJobs > MaxIntegrationExecutionJobs ||
+ c.MaxAttempts < 1 || c.MaxAttempts > DefaultIntegrationMaxAttempts ||
+ math.IsNaN(c.MaxRunnerMinutes) || math.IsInf(c.MaxRunnerMinutes, 0) || c.MaxRunnerMinutes <= 0 ||
+ c.MaxRunnerMinutes > MaxIntegrationExecutionMinutes ||
+ c.ObservationAge < MinIntegrationExecutionInterval || c.ObservationAge > MaxIntegrationExecutionInterval ||
+ c.Window < MinIntegrationExecutionInterval || c.Window > MaxIntegrationExecutionWindow ||
+ c.Cooldown < MinIntegrationExecutionInterval || c.Cooldown > MaxIntegrationExecutionInterval {
+ return fmt.Errorf("integration execution requires explicit bounded scopes, concurrency, retry, runner/job budgets and observation intervals")
+ }
+ seen := map[string]bool{}
+ for _, scope := range c.Scopes {
+ key := strings.ToLower(scope.Repo) + "#" + scope.Base
+ if !executionRepository(scope.Repo) || !executionBranch(scope.Base) ||
+ seen[key] || scope.Authority != "hive" && scope.Authority != "native" ||
+ scope.MaxMembers < 1 || scope.MaxMembers > MaxIntegrationExecutionCandidates ||
+ scope.ExpectedJobs < 1 || scope.ExpectedJobs > c.MaxJobs ||
+ math.IsNaN(scope.ExpectedMinutes) || math.IsInf(scope.ExpectedMinutes, 0) ||
+ scope.ExpectedMinutes <= 0 || scope.ExpectedMinutes > c.MaxRunnerMinutes {
+ return fmt.Errorf("integration execution scope/budget invalid or duplicated")
+ }
+ seen[key] = true
+ if scope.RepositoryID <= 0 || !executionDigest(scope.ExecutorID, 64) ||
+ !strings.HasPrefix(scope.AuthorityRef, "refs/heads/hive-integration-authority/") ||
+ !executionBranch(strings.TrimPrefix(scope.AuthorityRef, "refs/heads/")) ||
+ !executionDigest(scope.AuthorityCommit, 40) {
+ return fmt.Errorf("execution admission requires an explicit designated executor and immutable forge epoch, including native admission")
+ }
+ if scope.Purpose != "" && scope.Purpose != "qualification" {
+ return fmt.Errorf("execution purpose must be production (empty) or explicit isolated qualification")
+ }
+ if scope.Purpose == "qualification" {
+ if scope.Authority != "hive" || !strings.HasPrefix(scope.Base, "hive-integration-qualification/") ||
+ !executionBranch(scope.QualifiedBase) || scope.QualifiedBase == scope.Base ||
+ scope.MaxMembers != 1 || c.MaxActive != 1 {
+ return fmt.Errorf("qualification requires an explicitly enrolled isolated branch, production comparison base and single-member single-slot bounds")
+ }
+ } else if scope.QualifiedBase != "" {
+ return fmt.Errorf("production execution cannot select a qualification comparison base")
+ }
+ if scope.Authority == "native" {
+ continue
+ }
+ if scope.RepositoryID <= 0 || scope.RequestActorID <= 0 || scope.CandidateActorID <= 0 ||
+ scope.PromotionAppID <= 0 || scope.PromotionInstallationID <= 0 ||
+ scope.ProducerAppID <= 0 || scope.MaterializerID <= 0 || scope.CandidateWorkflowID <= 0 ||
+ !executionBranch(scope.DefaultBranch) || !executionDigest(scope.Policy, 64) ||
+ !executionDigest(scope.WorkflowTree, 40) || !executionDigest(scope.ExecutorID, 64) ||
+ !strings.HasPrefix(scope.AuthorityRef, "refs/heads/hive-integration-authority/") ||
+ !executionBranch(strings.TrimPrefix(scope.AuthorityRef, "refs/heads/")) ||
+ !executionDigest(scope.AuthorityCommit, 40) || scope.QualificationID == "" ||
+ len(scope.RequiredJobs) == 0 || len(scope.RequiredJobs) > scope.ExpectedJobs {
+ return fmt.Errorf("hive execution requires qualified installed workflows, designated executor and immutable authority epoch")
+ }
+
+ names := map[string]bool{}
+ for _, name := range scope.RequiredJobs {
+ if strings.TrimSpace(name) == "" || names[name] {
+ return fmt.Errorf("integration execution required jobs must be unique nonempty qualified names")
+ }
+ names[name] = true
+ }
+ }
+ return nil
+}
+
+func (c IntegrationExecutionConfig) Scope(repo, base string) (IntegrationExecutionScope, bool) {
+ if c.Effective().Mode == IntegrationOff || c.Validate() != nil {
+ return IntegrationExecutionScope{}, false
+ }
+
+ for _, scope := range c.Scopes {
+ if strings.EqualFold(scope.Repo, repo) && scope.Base == base {
+ return scope, true
+ }
+ }
+ return IntegrationExecutionScope{}, false
+}
diff --git a/src/pkg/config/integration_execution_profile.go b/src/pkg/config/integration_execution_profile.go
new file mode 100644
index 0000000000..e0c3764e77
--- /dev/null
+++ b/src/pkg/config/integration_execution_profile.go
@@ -0,0 +1,21 @@
+package config
+
+import (
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+)
+
+// ProviderProfileDigest binds the complete technical/actor profile shared by
+// an isolated qualification and its production destination. Destination,
+// enrollment epoch and explicit scheduling bounds are not producer identity.
+func (s IntegrationExecutionScope) ProviderProfileDigest() string {
+ raw, _ := json.Marshal(struct {
+ RepositoryID, RequestActorID, CandidateActorID, ProducerAppID, PromotionAppID, PromotionInstallationID, MaterializerID, CandidateWorkflowID int64
+ DefaultBranch, Policy, WorkflowTree string
+ RequiredJobs []string
+ }{s.RepositoryID, s.RequestActorID, s.CandidateActorID, s.ProducerAppID, s.PromotionAppID,
+ s.PromotionInstallationID, s.MaterializerID, s.CandidateWorkflowID, s.DefaultBranch, s.Policy, s.WorkflowTree, s.RequiredJobs})
+ digest := sha256.Sum256(raw)
+ return hex.EncodeToString(digest[:])
+}
diff --git a/src/pkg/config/integration_execution_test.go b/src/pkg/config/integration_execution_test.go
new file mode 100644
index 0000000000..5053c182b6
--- /dev/null
+++ b/src/pkg/config/integration_execution_test.go
@@ -0,0 +1,112 @@
+package config
+
+import (
+ "math"
+ "strings"
+ "testing"
+ "time"
+)
+
+func executionConfigFixture() IntegrationExecutionConfig {
+ return IntegrationExecutionConfig{
+ Mode: IntegrationEnforce, MaxActive: 2, MaxJobs: 10, MaxAttempts: 1,
+ MaxRunnerMinutes: 100, ObservationAge: time.Minute, Window: time.Hour, Cooldown: time.Minute,
+ Scopes: []IntegrationExecutionScope{{
+ Repo: "o/r", Base: "v5", Authority: "hive", RepositoryID: 1, RequestActorID: 2, CandidateActorID: 3,
+ ProducerAppID: 4, MaterializerID: 5, CandidateWorkflowID: 6, DefaultBranch: "v5",
+ PromotionAppID: 7, PromotionInstallationID: 8,
+ Policy: strings.Repeat("a", 64), WorkflowTree: strings.Repeat("b", 40), RequiredJobs: []string{"tests"},
+ ExecutorID: strings.Repeat("c", 64), AuthorityRef: "refs/heads/hive-integration-authority/v5",
+ AuthorityCommit: strings.Repeat("d", 40), QualificationID: "qualification",
+ MaxMembers: 2, ExpectedJobs: 2, ExpectedMinutes: 10,
+ }},
+ }
+}
+
+func TestIntegrationExecutionDefaultsAndExplicitScopes(t *testing.T) {
+ var zero IntegrationExecutionConfig
+ if zero.Effective().Mode != IntegrationOff || zero.Validate() != nil {
+ t.Fatal("zero execution must remain OFF")
+ }
+ if _, ok := zero.Scope("o/r", "v5"); ok {
+ t.Fatal("OFF enrolled a writer")
+ }
+ c := executionConfigFixture()
+ if err := c.Validate(); err != nil {
+ t.Fatal(err)
+ }
+ if _, ok := c.Scope("O/R", "v5"); !ok {
+ t.Fatal("repository case should not change enrollment")
+ }
+ if _, ok := c.Scope("o/r", "V5"); ok {
+ t.Fatal("base enrollment must preserve case")
+ }
+ if _, ok := c.Scope("o/other", "v5"); ok {
+ t.Fatal("implicit repository enrollment")
+ }
+ c.Mode = IntegrationOff
+ if err := c.Validate(); err != nil {
+ t.Fatal("rollback should retain valid configured scopes:", err)
+ }
+ if _, ok := c.Scope("o/r", "v5"); ok {
+ t.Fatal("rollback retained a writer")
+ }
+ c.Mode, c.Scopes[0].Authority = IntegrationAdvisory, "native"
+ if err := c.Validate(); err != nil {
+ t.Fatal("native admission must retain designated executor enrollment:", err)
+ }
+}
+
+func TestIntegrationExecutionRejectsUnboundedOrUnqualifiedConfiguration(t *testing.T) {
+ for _, test := range []struct {
+ name string
+ change func(*IntegrationExecutionConfig)
+ }{
+ {"mode", func(c *IntegrationExecutionConfig) { c.Mode = "on" }},
+ {"scopes", func(c *IntegrationExecutionConfig) { c.Scopes = nil }},
+ {"active", func(c *IntegrationExecutionConfig) { c.MaxActive = MaxIntegrationExecutionCandidates + 1 }},
+ {"jobs", func(c *IntegrationExecutionConfig) { c.MaxJobs = 0 }},
+ {"attempts", func(c *IntegrationExecutionConfig) { c.MaxAttempts = DefaultIntegrationMaxAttempts + 1 }},
+ {"nan", func(c *IntegrationExecutionConfig) { c.MaxRunnerMinutes = math.NaN() }},
+ {"infinity", func(c *IntegrationExecutionConfig) { c.MaxRunnerMinutes = math.Inf(1) }},
+ {"minutes", func(c *IntegrationExecutionConfig) { c.MaxRunnerMinutes = MaxIntegrationExecutionMinutes + 1 }},
+ {"age", func(c *IntegrationExecutionConfig) { c.ObservationAge = time.Second }},
+ {"window", func(c *IntegrationExecutionConfig) { c.Window = MaxIntegrationExecutionWindow + time.Second }},
+ {"cooldown", func(c *IntegrationExecutionConfig) { c.Cooldown = 0 }},
+ {"repository-path", func(c *IntegrationExecutionConfig) { c.Scopes[0].Repo = "../r" }},
+ {"repository-query", func(c *IntegrationExecutionConfig) { c.Scopes[0].Repo = "o/r?query" }},
+ {"branch", func(c *IntegrationExecutionConfig) { c.Scopes[0].Base = "bad/\x01branch" }},
+ {"branch-lock", func(c *IntegrationExecutionConfig) { c.Scopes[0].Base = "v5.lock" }},
+ {"branch-dot", func(c *IntegrationExecutionConfig) { c.Scopes[0].Base = "." }},
+ {"duplicate", func(c *IntegrationExecutionConfig) { c.Scopes = append(c.Scopes, c.Scopes[0]) }},
+ {"authority", func(c *IntegrationExecutionConfig) { c.Scopes[0].Authority = "direct-fallback" }},
+ {"actor", func(c *IntegrationExecutionConfig) { c.Scopes[0].CandidateActorID = 0 }},
+ {"workflow", func(c *IntegrationExecutionConfig) { c.Scopes[0].MaterializerID = 0 }},
+ {"members", func(c *IntegrationExecutionConfig) { c.Scopes[0].MaxMembers = 0 }},
+ {"expected-jobs", func(c *IntegrationExecutionConfig) { c.Scopes[0].ExpectedJobs = 0 }},
+ {"expected-minutes", func(c *IntegrationExecutionConfig) { c.Scopes[0].ExpectedMinutes = math.NaN() }},
+ {"policy", func(c *IntegrationExecutionConfig) { c.Scopes[0].Policy = strings.Repeat("0", 64) }},
+ {"closure", func(c *IntegrationExecutionConfig) { c.Scopes[0].WorkflowTree = "short" }},
+ {"executor", func(c *IntegrationExecutionConfig) { c.Scopes[0].ExecutorID = "" }},
+ {"authority-ref", func(c *IntegrationExecutionConfig) { c.Scopes[0].AuthorityRef = "refs/heads/v5" }},
+ {"authority-oid", func(c *IntegrationExecutionConfig) { c.Scopes[0].AuthorityCommit = "" }},
+ {"qualification", func(c *IntegrationExecutionConfig) { c.Scopes[0].QualificationID = "" }},
+ {"job-names", func(c *IntegrationExecutionConfig) { c.Scopes[0].RequiredJobs = []string{"tests", "tests"} }},
+ {"blank-job", func(c *IntegrationExecutionConfig) { c.Scopes[0].RequiredJobs = []string{" "} }},
+ } {
+ t.Run(test.name, func(t *testing.T) {
+ c := executionConfigFixture()
+ test.change(&c)
+ if c.Validate() == nil {
+ t.Fatalf("accepted unsafe execution config: %+v", c)
+ }
+ if _, ok := c.Scope("o/r", "v5"); ok {
+ t.Fatal("invalid configuration enrolled a scope")
+ }
+ })
+ }
+ c := IntegrationExecutionConfig{MaxActive: -1}
+ if c.Validate() == nil {
+ t.Fatal("OFF silently accepted nonsensical explicit unscoped bounds")
+ }
+}
diff --git a/src/pkg/config/integration_orchestration.go b/src/pkg/config/integration_orchestration.go
index 1d2f9dfecc..c7f101a692 100644
--- a/src/pkg/config/integration_orchestration.go
+++ b/src/pkg/config/integration_orchestration.go
@@ -29,18 +29,19 @@ const (
// IntegrationOrchestrationConfig controls admission, never merge authority.
// Scopes must name exact repository/base pairs; an empty list enrolls nothing.
type IntegrationOrchestrationConfig struct {
- Mode string `yaml:"mode,omitempty" json:"mode"`
- Scopes []IntegrationScope `yaml:"scopes,omitempty" json:"scopes"`
- LeaseTTL time.Duration `yaml:"lease_ttl,omitempty" json:"lease_ttl"`
- Window time.Duration `yaml:"window,omitempty" json:"window"`
- MaxActive int `yaml:"max_active,omitempty" json:"max_active"`
- MaxRunnerMinutes float64 `yaml:"max_runner_minutes,omitempty" json:"max_runner_minutes"`
- MaxJobs int `yaml:"max_jobs,omitempty" json:"max_jobs"`
- MaxAttempts int `yaml:"max_attempts,omitempty" json:"max_attempts"`
- MaxObservationAge time.Duration `yaml:"max_observation_age,omitempty" json:"max_observation_age"`
- AdmissionRunnerMinutes float64 `yaml:"admission_runner_minutes,omitempty" json:"admission_runner_minutes"`
- AdmissionJobs int `yaml:"admission_jobs,omitempty" json:"admission_jobs"`
- Policies []IntegrationPolicy `yaml:"policies,omitempty" json:"policies"`
+ Mode string `yaml:"mode,omitempty" json:"mode"`
+ Scopes []IntegrationScope `yaml:"scopes,omitempty" json:"scopes"`
+ LeaseTTL time.Duration `yaml:"lease_ttl,omitempty" json:"lease_ttl"`
+ Window time.Duration `yaml:"window,omitempty" json:"window"`
+ MaxActive int `yaml:"max_active,omitempty" json:"max_active"`
+ MaxRunnerMinutes float64 `yaml:"max_runner_minutes,omitempty" json:"max_runner_minutes"`
+ MaxJobs int `yaml:"max_jobs,omitempty" json:"max_jobs"`
+ MaxAttempts int `yaml:"max_attempts,omitempty" json:"max_attempts"`
+ MaxObservationAge time.Duration `yaml:"max_observation_age,omitempty" json:"max_observation_age"`
+ AdmissionRunnerMinutes float64 `yaml:"admission_runner_minutes,omitempty" json:"admission_runner_minutes"`
+ AdmissionJobs int `yaml:"admission_jobs,omitempty" json:"admission_jobs"`
+ Policies []IntegrationPolicy `yaml:"policies,omitempty" json:"policies"`
+ Execution IntegrationExecutionConfig `yaml:"execution,omitempty" json:"execution"`
}
// IntegrationPolicy pins an already-reviewed workflow blob and its exact jobs.
@@ -103,6 +104,23 @@ func (c IntegrationOrchestrationConfig) Effective() IntegrationOrchestrationConf
func (c IntegrationOrchestrationConfig) Validate() error {
c = c.Effective()
+ if err := c.Execution.Validate(); err != nil {
+ return err
+ }
+ if c.Execution.Effective().Mode == IntegrationEnforce {
+ for _, execution := range c.Execution.Scopes {
+ observed := false
+ for _, authoring := range c.Scopes {
+ if strings.EqualFold(authoring.Repo, execution.Repo) && authoring.Base == execution.Base {
+ observed = true
+ break
+ }
+ }
+ if c.Mode == IntegrationOff || !observed {
+ return fmt.Errorf("enforced execution requires its exact destination's existing authoring/CI observer in advisory or enforce mode")
+ }
+ }
+ }
if len(c.Scopes) > MaxIntegrationScopes || len(c.Policies) > MaxIntegrationScopes || c.AdmissionJobs < 1 || c.AdmissionJobs > c.MaxJobs ||
math.IsNaN(c.AdmissionRunnerMinutes) || math.IsInf(c.AdmissionRunnerMinutes, 0) ||
c.AdmissionRunnerMinutes <= 0 || c.AdmissionRunnerMinutes > c.MaxRunnerMinutes {
diff --git a/src/pkg/config/testdata/agent_runtime_golden.json b/src/pkg/config/testdata/agent_runtime_golden.json
index 515346e124..5ee4c4fb08 100644
--- a/src/pkg/config/testdata/agent_runtime_golden.json
+++ b/src/pkg/config/testdata/agent_runtime_golden.json
@@ -756,7 +756,18 @@
"max_observation_age": 0,
"admission_runner_minutes": 0,
"admission_jobs": 0,
- "policies": null
+ "policies": null,
+ "execution": {
+ "mode": "",
+ "scopes": null,
+ "max_active": 0,
+ "max_runner_minutes": 0,
+ "max_jobs": 0,
+ "max_attempts": 0,
+ "observation_age": 0,
+ "window": 0,
+ "cooldown": 0
+ }
},
"sla": {
"targets": {}
diff --git a/src/pkg/convergence/integration/execution_admission.go b/src/pkg/convergence/integration/execution_admission.go
new file mode 100644
index 0000000000..f03595db93
--- /dev/null
+++ b/src/pkg/convergence/integration/execution_admission.go
@@ -0,0 +1,198 @@
+package integration
+
+import (
+ "fmt"
+ "sort"
+ "time"
+
+ "github.com/hivecommons/hive/pkg/config"
+ "github.com/hivecommons/hive/pkg/forgestate"
+)
+
+type ExecutionMember struct {
+ PR int
+ Head string
+ WorkKey string
+ Eligible bool
+ DependenciesKnown bool
+ DependenciesSatisfied bool
+ ScopeKnown bool
+ ReadyAt time.Time
+ Priority int
+ IntentGeneration uint64
+ PlanRevision int
+}
+
+// ExecutionAdmissionInput is obtained outside the ledger lock from real live
+// guards, authoritative ownership, qualified workflow cohorts and current refs.
+type ExecutionAdmissionInput struct {
+ Repo, Base, BaseSHA string
+ ExecutorID string
+ AuthorityVerified bool
+ QualificationVerified bool
+ NativeSelected bool
+ Members []ExecutionMember
+ Cost Cost
+ Now time.Time
+}
+
+type ExecutionAdmissionDecision struct {
+ Allowed bool `json:"allowed"`
+ WouldBlock bool `json:"would_block"`
+ Reason string `json:"reason"`
+ EffectiveWriter string `json:"effective_writer"`
+ Plan *ExecutionPlan `json:"plan,omitempty"`
+}
+
+func executionBlocked(cfg config.IntegrationExecutionConfig, reason string) ExecutionAdmissionDecision {
+ return ExecutionAdmissionDecision{Allowed: cfg.Effective().Mode != config.IntegrationEnforce,
+ WouldBlock: true, Reason: reason, EffectiveWriter: "observer"}
+}
+
+// PlanExecution reserves only the new layer's bounded CI work. It does not
+// assume disjoint files are independent or acquire file-exclusive locks.
+func (s *Store) PlanExecution(cfg config.IntegrationExecutionConfig, in ExecutionAdmissionInput) (ExecutionAdmissionDecision, error) {
+ cfg = cfg.Effective()
+ if cfg.Mode == config.IntegrationOff {
+ return ExecutionAdmissionDecision{Allowed: true, Reason: "execution OFF; existing flow unchanged", EffectiveWriter: "legacy"}, nil
+ }
+ if err := cfg.Validate(); err != nil {
+ return executionBlocked(cfg, err.Error()), err
+ }
+ scope, enrolled := cfg.Scope(in.Repo, in.Base)
+ if !enrolled {
+ return ExecutionAdmissionDecision{Allowed: true, Reason: "destination not enrolled", EffectiveWriter: "legacy"}, nil
+ }
+ if scope.Authority == "native" {
+ if !in.NativeSelected {
+ return executionBlocked(cfg, "native-selected scope has no native authority; no direct fallback"), nil
+ }
+ if !in.Cost.Complete {
+ return executionBlocked(cfg, "native admission observations incomplete; no queue/build-window control claimed"), nil
+ }
+ if !executionCostKnown(in.Cost) || in.Cost.Running >= cfg.MaxActive ||
+ in.Cost.Running+scope.ExpectedJobs > cfg.MaxJobs || *in.Cost.RunnerMinutes+scope.ExpectedMinutes > cfg.MaxRunnerMinutes {
+ return executionBlocked(cfg, "native Hive admission budget exhausted; GitHub controls active queue groups"), nil
+ }
+ return ExecutionAdmissionDecision{Allowed: true, Reason: "bounded Hive enqueue admission; GitHub retains queue/promotion authority", EffectiveWriter: "github-native"}, nil
+ }
+ if in.NativeSelected {
+ return executionBlocked(cfg, "native selection forbids Hive promotion fallback"), nil
+ }
+ if in.ExecutorID != scope.ExecutorID || !in.AuthorityVerified {
+ return executionBlocked(cfg, "not the registered designated executor; observer-only, no TTL takeover"), nil
+ }
+ if !in.QualificationVerified {
+ return executionBlocked(cfg, "actual actor/branch-protection qualification unavailable"), nil
+ }
+ if in.Now.IsZero() || !fullSHA(in.BaseSHA) {
+ return executionBlocked(cfg, "current exact destination unknown"), nil
+ }
+ if !executionCostKnown(in.Cost) {
+ return executionBlocked(cfg, "authoritative job telemetry incomplete; growth frozen, unknown is not zero"), nil
+ }
+
+ eligible := make([]ExecutionMember, 0, len(in.Members))
+ for _, member := range in.Members {
+ if member.Eligible && member.DependenciesKnown && member.DependenciesSatisfied &&
+ member.ScopeKnown && member.WorkKey != "" && member.PR > 0 && fullSHA(member.Head) && !member.ReadyAt.IsZero() {
+ if member.IntentGeneration == 0 {
+ continue
+ }
+ eligible = append(eligible, member)
+ }
+ }
+ // Priority can move a member by at most the configured priority bounds in
+ // minutes. Waiting age continues to grow; no unbounded priority lane exists.
+ sort.SliceStable(eligible, func(i, j int) bool {
+ priority := func(value int) int {
+ if value < 0 {
+ return 0
+ }
+ if value > config.MaxIntegrationExecutionPriority {
+ return config.MaxIntegrationExecutionPriority
+ }
+ return value
+ }
+ a := eligible[i].ReadyAt.Add(-time.Duration(priority(eligible[i].Priority)) * time.Minute)
+ b := eligible[j].ReadyAt.Add(-time.Duration(priority(eligible[j].Priority)) * time.Minute)
+ if a.Equal(b) {
+ return eligible[i].PR < eligible[j].PR
+ }
+ return a.Before(b)
+ })
+ if len(eligible) == 0 {
+ return executionBlocked(cfg, "no live eligible approved/known-scope members"), nil
+ }
+ if len(eligible) > scope.MaxMembers {
+ eligible = eligible[:scope.MaxMembers]
+ }
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ unlock, err := s.writerLock()
+ if err != nil {
+ return executionBlocked(cfg, "execution journal unavailable"), err
+ }
+ defer unlock()
+ state := s.executionData()
+ reserved, activeJobs, active := 0.0, 0, 0
+ for _, plan := range state.plans {
+ if plan.ReservationsReleased {
+ continue
+ }
+ if plan.State == Unknown || plan.State == Waiting || plan.State == Running {
+ // Bounds are global across the explicitly enrolled destinations, not
+ // independently reusable in every repository. Removed scopes retain
+ // observed cost but no longer reserve new-layer admission slots.
+ profile, enrolled := cfg.Scope(plan.Recipe.Repo, plan.Recipe.Base)
+ if !enrolled {
+ continue
+ }
+ active += len(plan.Recipe.Members)
+ activeJobs += len(plan.Recipe.Members) * profile.ExpectedJobs
+ reserved += float64(len(plan.Recipe.Members)) * profile.ExpectedMinutes
+ }
+ }
+ capacity := 0
+ for capacity < len(eligible) {
+ demand := capacity + 1
+ if active+demand > cfg.MaxActive || in.Cost.Running+activeJobs+demand*scope.ExpectedJobs > cfg.MaxJobs ||
+ *in.Cost.RunnerMinutes+reserved+float64(demand)*scope.ExpectedMinutes > cfg.MaxRunnerMinutes {
+ break
+ }
+ capacity++
+ }
+ if capacity == 0 {
+ return executionBlocked(cfg, "static candidate/job/runner-minute budget exhausted; no adaptive or live-pilot growth"), nil
+ }
+ eligible = eligible[:capacity]
+ recipe := ExecutionRecipe{Repo: scope.Repo, Base: scope.Base, BaseSHA: in.BaseSHA, Policy: scope.Policy, WorkflowTree: scope.WorkflowTree}
+ keys := make([]string, 0, len(eligible))
+ bindings := make([]ExecutionWorkBinding, 0, len(eligible))
+ for _, member := range eligible {
+ recipe.Members = append(recipe.Members, forgestate.IntegrationCandidateMember{PR: member.PR, Head: member.Head})
+ keys = append(keys, member.WorkKey)
+ bindings = append(bindings, ExecutionWorkBinding{Key: member.WorkKey, IntentGeneration: member.IntentGeneration, PlanRevision: member.PlanRevision})
+ }
+ if err := recipe.Validate(); err != nil {
+ return executionBlocked(cfg, err.Error()), err
+ }
+ if _, exists := state.plans[recipe.ID()]; exists {
+ return executionBlocked(cfg, "exact recipe already owned/observed; ambiguous requests are not redispatched"), nil
+ }
+ plan := ExecutionPlan{Recipe: recipe, Generation: 1, CreatedAt: in.Now, ObservedAt: in.Now,
+ State: Waiting, Reason: "qualified exact-prefix preparation admitted", WorkKeys: keys,
+ ExecutorID: in.ExecutorID, AuthorityCommit: scope.AuthorityCommit, Attempt: 1, AttemptAt: in.Now, WorkBindings: bindings}
+ decision := ExecutionAdmissionDecision{Allowed: true, Reason: plan.Reason, EffectiveWriter: "hive-designated", Plan: &plan}
+ if cfg.Mode == config.IntegrationAdvisory {
+ decision.Reason, decision.EffectiveWriter = "advisory only: would prepare; no dispatch/promotion", "observer"
+ return decision, nil
+ }
+
+ err = s.appendLocked(Event{Version: SchemaVersion, ID: "execution/plan/" + recipe.ID(), At: in.Now,
+ Execution: &ExecutionEvent{Version: ExecutionSchemaVersion, Plan: &plan}})
+ if err != nil {
+ return executionBlocked(cfg, fmt.Sprintf("durable admission failed: %v", err)), err
+ }
+ return decision, nil
+}
diff --git a/src/pkg/convergence/integration/execution_admission_test.go b/src/pkg/convergence/integration/execution_admission_test.go
new file mode 100644
index 0000000000..d97c061e12
--- /dev/null
+++ b/src/pkg/convergence/integration/execution_admission_test.go
@@ -0,0 +1,190 @@
+package integration
+
+import (
+ "crypto/rand"
+ "encoding/hex"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/hivecommons/hive/pkg/config"
+)
+
+func executionFixturePath(t *testing.T) string {
+ t.Helper()
+ var nonce [16]byte
+ if _, err := rand.Read(nonce[:]); err != nil {
+ t.Fatal(err)
+ }
+ directory := ".execution-fixture-" + hex.EncodeToString(nonce[:])
+ if err := os.Mkdir(directory, 0700); err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() {
+ if err := os.RemoveAll(directory); err != nil {
+ t.Error(err)
+ }
+ })
+ return filepath.Join(directory, "ledger.jsonl")
+}
+
+func executionAdmissionFixture(t *testing.T) (*Store, config.IntegrationExecutionConfig, ExecutionAdmissionInput) {
+ t.Helper()
+ store, err := OpenExecution(executionFixturePath(t))
+ if err != nil {
+ t.Fatal(err)
+ }
+ now := time.Date(2026, 10, 31, 3, 0, 0, 0, time.UTC)
+ minutes := 0.0
+ cfg := config.IntegrationExecutionConfig{
+ Mode: config.IntegrationEnforce, MaxActive: 2, MaxJobs: 10, MaxAttempts: 1,
+ MaxRunnerMinutes: 100, ObservationAge: time.Minute, Window: time.Hour, Cooldown: time.Minute,
+ Scopes: []config.IntegrationExecutionScope{{
+ Repo: "o/r", Base: "v5", Authority: "hive", RepositoryID: 1, RequestActorID: 2, CandidateActorID: 3,
+ ProducerAppID: 4, MaterializerID: 5, CandidateWorkflowID: 6, DefaultBranch: "v5",
+ PromotionAppID: 7, PromotionInstallationID: 8,
+ Policy: strings.Repeat("a", 64), WorkflowTree: strings.Repeat("b", 40), RequiredJobs: []string{"tests"},
+ ExecutorID: strings.Repeat("c", 64), AuthorityRef: "refs/heads/hive-integration-authority/v5",
+ AuthorityCommit: strings.Repeat("d", 40), QualificationID: "qualification",
+ MaxMembers: 2, ExpectedJobs: 2, ExpectedMinutes: 10,
+ }},
+ }
+ in := ExecutionAdmissionInput{
+ Repo: "o/r", Base: "v5", BaseSHA: strings.Repeat("e", 40), Now: now, ExecutorID: cfg.Scopes[0].ExecutorID,
+ AuthorityVerified: true, QualificationVerified: true, Cost: Cost{Complete: true, RunnerMinutes: &minutes},
+ Members: []ExecutionMember{
+ {PR: 1, Head: strings.Repeat("1", 40), WorkKey: "o/r#10", Eligible: true, ScopeKnown: true,
+ DependenciesKnown: true, DependenciesSatisfied: true, ReadyAt: now.Add(-time.Hour), IntentGeneration: 1, PlanRevision: 1},
+ {PR: 2, Head: strings.Repeat("2", 40), WorkKey: "o/r#20", Eligible: true, ScopeKnown: true,
+ DependenciesKnown: true, DependenciesSatisfied: true, ReadyAt: now.Add(-time.Minute), Priority: 10000, IntentGeneration: 1, PlanRevision: 1},
+ },
+ }
+ return store, cfg, in
+}
+
+func TestExecutionAdmissionFittingPrefixDurabilityAndNoRedispatch(t *testing.T) {
+ store, cfg, in := executionAdmissionFixture(t)
+ cfg.MaxActive = 1
+ decision, err := store.PlanExecution(cfg, in)
+ if err != nil || !decision.Allowed || decision.Plan == nil {
+ t.Fatalf("admission: %+v %v", decision, err)
+ }
+ if len(decision.Plan.Recipe.Members) != 1 || decision.Plan.Recipe.Members[0].PR != 1 {
+ t.Fatalf("capacity should select a fitting aged prefix, not stall or accept unbounded priority: %+v", decision)
+ }
+ replayed, err := OpenExecution(store.path)
+ if err != nil || len(replayed.ExecutionSnapshot().Plans) != 1 {
+ t.Fatalf("durable plan: %v", err)
+ }
+ decision, err = replayed.PlanExecution(cfg, in)
+ if err != nil || decision.Allowed || decision.Plan != nil {
+ t.Fatalf("duplicate/reserved admission: %+v %v", decision, err)
+ }
+ legacy, err := Open(store.path)
+ if err == nil || legacy != nil {
+ t.Fatal("legacy proof store read execution partition")
+ }
+}
+
+func TestExecutionAdmissionOffAndAdvisoryNeverReserveOrBlock(t *testing.T) {
+ for _, mode := range []string{config.IntegrationOff, config.IntegrationAdvisory} {
+ store, cfg, in := executionAdmissionFixture(t)
+ cfg.Mode = mode
+ decision, err := store.PlanExecution(cfg, in)
+ if err != nil || !decision.Allowed || len(store.ExecutionSnapshot().Plans) != 0 {
+ t.Fatalf("%s changed durable admission: %+v %v", mode, decision, err)
+ }
+ in.AuthorityVerified = false
+ decision, err = store.PlanExecution(cfg, in)
+ if err != nil || !decision.Allowed {
+ t.Fatalf("%s blocked legacy: %+v %v", mode, decision, err)
+ }
+ }
+}
+
+func TestExecutionAdmissionRejectsMissingAuthorityEligibilityAndTelemetry(t *testing.T) {
+ for _, test := range []struct {
+ name string
+ change func(*ExecutionAdmissionInput)
+ }{
+ {"observer", func(in *ExecutionAdmissionInput) { in.ExecutorID = "another-installation" }},
+ {"authority", func(in *ExecutionAdmissionInput) { in.AuthorityVerified = false }},
+ {"qualification", func(in *ExecutionAdmissionInput) { in.QualificationVerified = false }},
+ {"native", func(in *ExecutionAdmissionInput) { in.NativeSelected = true }},
+ {"head", func(in *ExecutionAdmissionInput) { in.BaseSHA = "" }},
+ {"clock", func(in *ExecutionAdmissionInput) { in.Now = time.Time{} }},
+ {"cohort", func(in *ExecutionAdmissionInput) { in.Cost.Complete = false }},
+ {"minutes", func(in *ExecutionAdmissionInput) { in.Cost.RunnerMinutes = nil }},
+ {"eligibility", func(in *ExecutionAdmissionInput) { in.Members = nil }},
+ {"scope", func(in *ExecutionAdmissionInput) {
+ for i := range in.Members {
+ in.Members[i].ScopeKnown = false
+ }
+ }},
+ {"dependency", func(in *ExecutionAdmissionInput) {
+ for i := range in.Members {
+ in.Members[i].DependenciesSatisfied = false
+ }
+ }},
+ } {
+ t.Run(test.name, func(t *testing.T) {
+ store, cfg, in := executionAdmissionFixture(t)
+ test.change(&in)
+ decision, err := store.PlanExecution(cfg, in)
+ if err != nil || decision.Allowed || !decision.WouldBlock || decision.Reason == "" {
+ t.Fatalf("unsafe admission: %+v %v", decision, err)
+ }
+ if len(store.ExecutionSnapshot().Plans) != 0 {
+ t.Fatal("blocked admission persisted a reservation")
+ }
+ })
+ }
+}
+
+func TestExecutionAdmissionGlobalSlotsAndNativeLimits(t *testing.T) {
+ store, cfg, in := executionAdmissionFixture(t)
+ cfg.MaxActive = 1
+ second := cfg.Scopes[0]
+ second.Repo = "o/other"
+ cfg.Scopes = append(cfg.Scopes, second)
+ if decision, err := store.PlanExecution(cfg, in); err != nil || decision.Plan == nil {
+ t.Fatalf("first: %+v %v", decision, err)
+ }
+
+ in.Repo = second.Repo
+ if decision, err := store.PlanExecution(cfg, in); err != nil || decision.Allowed {
+ t.Fatalf("reused global slots: %+v %v", decision, err)
+ }
+ cfg.Scopes[1].Authority = "native"
+ in.NativeSelected = true
+ if decision, err := store.PlanExecution(cfg, in); err != nil || !decision.Allowed || decision.EffectiveWriter != "github-native" {
+ t.Fatalf("native admission replaced queue authority: %+v %v", decision, err)
+ }
+ in.Cost.Complete = false
+ if decision, _ := store.PlanExecution(cfg, in); decision.Allowed {
+ t.Fatal("native unknown telemetry was treated as zero")
+ }
+}
+
+func TestExecutionAdmissionInvalidUnenrolledAndNativeJobBudget(t *testing.T) {
+ store, cfg, in := executionAdmissionFixture(t)
+ invalid := cfg
+ invalid.Mode = "unexpected"
+ if _, err := store.PlanExecution(invalid, in); err == nil {
+ t.Fatal("invalid configuration authorized execution")
+ }
+ outside := in
+ outside.Repo = "o/unlisted"
+ if decision, err := store.PlanExecution(cfg, outside); err != nil || !decision.Allowed || decision.EffectiveWriter != "legacy" {
+ t.Fatalf("unenrolled destination changed behavior: %+v %v", decision, err)
+ }
+ cfg.Scopes[0].Authority = "native"
+ cfg.MaxJobs = 2
+ in.Cost.Jobs, in.Cost.Running = 1, 1
+ in.NativeSelected = true
+ if decision, err := store.PlanExecution(cfg, in); err != nil || decision.Allowed {
+ t.Fatalf("native Hive admission exceeded assigned-job bound: %+v %v", decision, err)
+ }
+}
diff --git a/src/pkg/convergence/integration/execution_archive.go b/src/pkg/convergence/integration/execution_archive.go
new file mode 100644
index 0000000000..7440ac4416
--- /dev/null
+++ b/src/pkg/convergence/integration/execution_archive.go
@@ -0,0 +1,210 @@
+package integration
+
+import (
+ "bytes"
+ "crypto/rsa"
+ "crypto/sha256"
+ "crypto/x509"
+ "encoding/hex"
+ "encoding/json"
+ "fmt"
+ "reflect"
+ "strconv"
+ "time"
+
+ "github.com/golang-jwt/jwt/v5"
+ "github.com/hivecommons/hive/pkg/forgestate"
+)
+
+const (
+ executionArchiveMaxPayload = 256 << 10
+ executionArchiveMaxToken = 16 << 10
+ executionArchiveIssuer = "https://token.actions.githubusercontent.com"
+ executionArchiveSkew = 2 * time.Minute
+ executionArchiveMaxLifetime = time.Hour
+ executionArchiveMaxKey = 16 << 10
+ executionArchiveMaxChecks = 100
+)
+
+func archivedID(value any, expected int64) bool {
+ switch typed := value.(type) {
+ case string:
+ return typed == strconv.FormatInt(expected, 10)
+ case json.Number:
+ return typed.String() == strconv.FormatInt(expected, 10)
+ default:
+ return false
+ }
+}
+
+// validateArchivedIdentity rechecks already validated private history without
+// fetching a current JWKS (which may have retired the historical key). It never
+// upgrades arbitrary caller-supplied keys into new trusted issuer observations.
+func validateArchivedIdentity(a ExecutionArchive, repo string, runID int64, attempt int) error {
+ if a.Role != "candidate" && a.Role != "materializer" || a.Issuer != executionArchiveIssuer ||
+ a.KeyID == "" || a.VerifiedAt.IsZero() || len(a.Payload) == 0 || len(a.Payload) > executionArchiveMaxPayload ||
+ len(a.Token) == 0 || len(a.Token) > executionArchiveMaxToken || a.ArtifactID <= 0 ||
+ a.WorkflowID <= 0 || a.SuiteID <= 0 || len(a.CheckIDs) == 0 || len(a.CheckIDs) > executionArchiveMaxChecks || a.FinalizerCheckID <= 0 ||
+ len(a.SigningKeySPKI) == 0 || len(a.SigningKeySPKI) > executionArchiveMaxKey ||
+ a.RepositoryID <= 0 || a.ActorID <= 0 || a.JobStartedAt.IsZero() || a.JobCompletedAt.Before(a.JobStartedAt) ||
+ !fullSHA(a.WorkflowSHA) || a.WorkflowPath == "" || a.Ref == "" || a.Event == "" {
+ return fmt.Errorf("incomplete private verified producer history")
+ }
+ checks := map[int64]bool{}
+ for _, id := range a.CheckIDs {
+ if id <= 0 || checks[id] {
+ return fmt.Errorf("archived check cohort invalid/duplicated")
+ }
+ checks[id] = true
+ }
+ if !checks[a.FinalizerCheckID] {
+ return fmt.Errorf("archived finalizer absent from actual check cohort")
+ }
+ keyDigest := sha256.Sum256(a.SigningKeySPKI)
+ if hex.EncodeToString(keyDigest[:]) != a.SigningKeySHA256 {
+ return fmt.Errorf("archived signer key digest changed")
+ }
+ parsed, err := x509.ParsePKIXPublicKey(a.SigningKeySPKI)
+ if err != nil {
+ return err
+ }
+ key, ok := parsed.(*rsa.PublicKey)
+ if !ok || key.N.BitLen() < 2048 || key.N.BitLen() > 8192 {
+ return fmt.Errorf("unsupported archived producer key")
+ }
+ claims := jwt.MapClaims{}
+ token, err := jwt.ParseWithClaims(a.Token, claims, func(token *jwt.Token) (any, error) {
+ if token.Header["kid"] != a.KeyID {
+ return nil, fmt.Errorf("archived issuer key identity changed")
+ }
+ return key, nil
+ }, jwt.WithValidMethods([]string{jwt.SigningMethodRS256.Alg()}), jwt.WithoutClaimsValidation(), jwt.WithJSONNumber())
+ if err != nil || token == nil || !token.Valid {
+ return fmt.Errorf("archived producer signature invalid: %v", err)
+ }
+ payloadDigest := sha256.Sum256(a.Payload)
+ audience := "hive-integration-producer-v1/"
+ if a.Role == "materializer" {
+ audience = "hive-integration-materializer-v1/"
+ }
+ audiences, err := claims.GetAudience()
+ if err != nil || len(audiences) != 1 || audiences[0] != audience+hex.EncodeToString(payloadDigest[:]) ||
+ claims["iss"] != a.Issuer || claims["repository"] != repo ||
+ !archivedID(claims["repository_id"], a.RepositoryID) || !archivedID(claims["actor_id"], a.ActorID) ||
+ !archivedID(claims["run_id"], runID) || !archivedID(claims["run_attempt"], int64(attempt)) ||
+ !archivedID(claims["check_run_id"], a.FinalizerCheckID) ||
+ claims["workflow_ref"] != repo+"/"+a.WorkflowPath+"@"+a.Ref || claims["workflow_sha"] != a.WorkflowSHA ||
+ claims["ref"] != a.Ref || claims["event_name"] != a.Event || claims["runner_environment"] != "github-hosted" ||
+ claims["environment"] != nil && claims["environment"] != "" {
+ return fmt.Errorf("archived producer identity/digest binding changed")
+ }
+ issued, err := claims.GetIssuedAt()
+ if err != nil || issued == nil || issued.Before(a.JobStartedAt.Add(-executionArchiveSkew)) ||
+ issued.After(a.JobCompletedAt.Add(executionArchiveSkew)) {
+ return fmt.Errorf("archived signed issuance outside actual finalizer interval")
+ }
+ notBefore, nbfErr := claims.GetNotBefore()
+ expires, expErr := claims.GetExpirationTime()
+ if nbfErr != nil || expErr != nil || notBefore == nil || expires == nil ||
+ notBefore.Before(issued.Add(-executionArchiveSkew)) || notBefore.After(issued.Add(executionArchiveSkew)) ||
+ !expires.After(issued.Time) || expires.Sub(issued.Time) > executionArchiveMaxLifetime {
+ return fmt.Errorf("archived historical token lifetime changed")
+ }
+ return nil
+}
+
+func validateExecutionArchive(proof ExecutionProof) error {
+ a := *proof.Archive
+ if a.Role != "candidate" || a.WorkflowSHA != proof.Subject.Prefixes[len(proof.Subject.Prefixes)-1].Commit ||
+ a.Ref != "refs/tags/hive-integration/"+proof.Subject.ID || a.Event != "workflow_dispatch" {
+ return fmt.Errorf("archived candidate role/subject binding changed")
+ }
+ return validateExecutionArchiveBody(proof)
+}
+
+func validateMaterializationArchive(plan ExecutionPlan) error {
+ var receipt struct {
+ Schema int `json:"schema"`
+ Protocol string `json:"protocol"`
+ Request struct {
+ Schema int `json:"schema"`
+ Protocol string `json:"protocol"`
+ Engine string `json:"engine"`
+ Repo string `json:"repo"`
+ Base string `json:"base"`
+ BaseSHA string `json:"baseSHA"`
+ Policy string `json:"policy"`
+ Generation int64 `json:"generation"`
+ Members []forgestate.IntegrationCandidateMember `json:"members"`
+ CreatedAt string `json:"createdAt"`
+ } `json:"request"`
+ Prepared []struct {
+ Subject forgestate.IntegrationCandidateSubject `json:"subject"`
+ Publication string `json:"publication"`
+ Dispatch string `json:"dispatch"`
+ Ownership forgestate.IntegrationDispatchClaim `json:"ownership"`
+ } `json:"prepared"`
+ PreparedBy forgestate.IntegrationPreparationSource `json:"preparedBy"`
+ }
+ if err := json.Unmarshal(plan.Materialization.Payload, &receipt); err != nil {
+ return err
+ }
+ request := receipt.Request
+ _, digest, err := forgestate.CanonicalIntegrationPreparation(request)
+ if err != nil || digest != plan.RequestDigest ||
+ receipt.Schema != 1 || receipt.Protocol != "integration-materializer-receipt-v1" ||
+ request.Schema != 1 || request.Protocol != "integration-prefix-v1" || request.Engine != "hive" ||
+ request.Repo != plan.Recipe.Repo || request.Base != plan.Recipe.Base ||
+ request.BaseSHA != plan.Recipe.BaseSHA || request.Policy != plan.Recipe.Policy ||
+ request.Generation != int64(plan.Attempt) || request.CreatedAt != plan.AttemptAt.UTC().Format(time.RFC3339Nano) ||
+ !reflect.DeepEqual(request.Members, plan.Recipe.Members) ||
+ receipt.PreparedBy.RequestDigest != plan.RequestDigest || receipt.PreparedBy.SourceSHA != plan.Materialization.WorkflowSHA {
+ return fmt.Errorf("archived materializer changed exact durable request")
+ }
+ prepared := []forgestate.IntegrationCandidateSubject{}
+ for index, entry := range receipt.Prepared {
+ subject := entry.Subject
+ if index >= len(request.Members) || !reflect.DeepEqual(subject.Members, request.Members[:index+1]) ||
+ subject.Repo != request.Repo || subject.Base != request.Base || subject.BaseSHA != request.BaseSHA ||
+ subject.Policy != request.Policy || subject.WorkflowTree != plan.Recipe.WorkflowTree ||
+ len(subject.Prefixes) != index+1 || subject.PreparedBy != receipt.PreparedBy {
+ return fmt.Errorf("archived materializer changed immutable prefix chain")
+ }
+ if entry.Publication == "accepted" {
+ prepared = append(prepared, subject)
+ }
+ }
+ if len(prepared) != len(plan.Prepared) {
+ return fmt.Errorf("archived publication count changed")
+ }
+ for index := range prepared {
+ if !prepared[index].SameCore(plan.Prepared[index]) {
+ return fmt.Errorf("archived published subject changed")
+ }
+ }
+ return nil
+}
+func validateExecutionArchiveBody(proof ExecutionProof) error {
+ a := *proof.Archive
+ if err := validateArchivedIdentity(a, proof.Subject.Repo, proof.RunID, proof.Attempt); err != nil {
+ return err
+ }
+ var payload struct {
+ Schema int `json:"schema"`
+ Protocol string `json:"protocol"`
+ Subject forgestate.IntegrationCandidateSubject `json:"subject"`
+ RunID string `json:"runID"`
+ Attempt string `json:"runAttempt"`
+ Outcomes struct{ CI, Tests, Security string } `json:"outcomes"`
+ }
+ if err := json.NewDecoder(bytes.NewReader(a.Payload)).Decode(&payload); err != nil {
+ return err
+ }
+ if payload.Schema != 1 || payload.Protocol != "integration-producer-receipt-v1" ||
+ !payload.Subject.SameCore(proof.Subject) || payload.RunID != strconv.FormatInt(proof.RunID, 10) ||
+ payload.Attempt != strconv.Itoa(proof.Attempt) ||
+ proof.State == Passed && (payload.Outcomes.CI != "success" || payload.Outcomes.Tests != "success" || payload.Outcomes.Security != "success") {
+ return fmt.Errorf("archived payload changed exact candidate/outcome binding")
+ }
+ return nil
+}
diff --git a/src/pkg/convergence/integration/execution_archive_test.go b/src/pkg/convergence/integration/execution_archive_test.go
new file mode 100644
index 0000000000..0671ce5899
--- /dev/null
+++ b/src/pkg/convergence/integration/execution_archive_test.go
@@ -0,0 +1,214 @@
+package integration
+
+import (
+ "crypto/rand"
+ "crypto/rsa"
+ "crypto/sha256"
+ "crypto/x509"
+ "encoding/hex"
+ "encoding/json"
+ "strconv"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/golang-jwt/jwt/v5"
+ "github.com/hivecommons/hive/pkg/forgestate"
+)
+
+func executionSignedArchive(t *testing.T, proof ExecutionProof, key *rsa.PrivateKey) *ExecutionArchive {
+ t.Helper()
+ payload, err := json.Marshal(map[string]any{
+ "schema": 1, "protocol": "integration-producer-receipt-v1", "subject": proof.Subject,
+ "runID": strconv.FormatInt(proof.RunID, 10), "runAttempt": strconv.Itoa(proof.Attempt),
+ "outcomes": map[string]string{"ci": "success", "tests": "success", "security": "success"},
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ spki, err := x509.MarshalPKIXPublicKey(&key.PublicKey)
+ if err != nil {
+ t.Fatal(err)
+ }
+ keyHash := sha256.Sum256(spki)
+ last := proof.Subject.Prefixes[len(proof.Subject.Prefixes)-1]
+ archive := &ExecutionArchive{
+ Role: "candidate", Issuer: executionArchiveIssuer, KeyID: "historical-key", SigningKeySPKI: spki,
+ SigningKeySHA256: hex.EncodeToString(keyHash[:]), VerifiedAt: proof.ObservedAt,
+ Payload: payload, ArtifactID: 1, WorkflowID: 2, SuiteID: 3, CheckIDs: []int64{4, 5}, FinalizerCheckID: 5,
+ RepositoryID: 6, ActorID: 7, WorkflowSHA: last.Commit, WorkflowPath: ".github/workflows/integration-candidate.yml",
+ Ref: "refs/tags/hive-integration/" + proof.Subject.ID, Event: "workflow_dispatch",
+ JobStartedAt: proof.ObservedAt.Add(-time.Minute), JobCompletedAt: proof.ObservedAt,
+ }
+ executionSignArchive(t, archive, key, proof.Subject.Repo, proof.RunID, proof.Attempt)
+ return archive
+}
+
+func executionSignArchive(t *testing.T, archive *ExecutionArchive, key *rsa.PrivateKey, repo string, runID int64, attempt int) {
+ t.Helper()
+ payloadHash := sha256.Sum256(archive.Payload)
+ audience := "hive-integration-producer-v1/"
+ if archive.Role == "materializer" {
+ audience = "hive-integration-materializer-v1/"
+ }
+ claims := jwt.MapClaims{
+ "iss": archive.Issuer, "aud": audience + hex.EncodeToString(payloadHash[:]),
+ "repository": repo, "repository_id": strconv.FormatInt(archive.RepositoryID, 10), "actor_id": strconv.FormatInt(archive.ActorID, 10),
+ "run_id": strconv.FormatInt(runID, 10), "run_attempt": strconv.Itoa(attempt), "check_run_id": strconv.FormatInt(archive.FinalizerCheckID, 10),
+ "workflow_ref": repo + "/" + archive.WorkflowPath + "@" + archive.Ref, "workflow_sha": archive.WorkflowSHA,
+ "ref": archive.Ref, "event_name": archive.Event, "runner_environment": "github-hosted",
+ "iat": archive.VerifiedAt.Add(-30 * time.Second).Unix(), "nbf": archive.VerifiedAt.Add(-30 * time.Second).Unix(),
+ "exp": archive.VerifiedAt.Add(30 * time.Minute).Unix(),
+ }
+ token := jwt.NewWithClaims(jwt.SigningMethodRS256, claims)
+ token.Header["kid"] = archive.KeyID
+ signed, err := token.SignedString(key)
+ if err != nil {
+ t.Fatal(err)
+ }
+ archive.Token = signed
+}
+
+func TestExecutionMaterializerPrivateReplayAndPartialPrefix(t *testing.T) {
+ store, cfg, in := executionAdmissionFixture(t)
+ admitted, err := store.PlanExecution(cfg, in)
+ if err != nil || admitted.Plan == nil {
+ t.Fatalf("plan: %+v %v", admitted, err)
+ }
+ plan := *admitted.Plan
+ request := map[string]any{"schema": 1, "protocol": "integration-prefix-v1", "engine": "hive",
+ "repo": plan.Recipe.Repo, "base": plan.Recipe.Base, "baseSHA": plan.Recipe.BaseSHA, "policy": plan.Recipe.Policy,
+ "generation": int64(plan.Attempt), "members": plan.Recipe.Members, "createdAt": plan.AttemptAt.UTC().Format(time.RFC3339Nano)}
+ _, plan.RequestDigest, err = forgestate.CanonicalIntegrationPreparation(request)
+ if err != nil {
+ t.Fatal(err)
+ }
+ subject := executionProofFixture().Subject
+ subject.Repo, subject.Base, subject.BaseSHA, subject.Policy, subject.WorkflowTree = plan.Recipe.Repo, plan.Recipe.Base, plan.Recipe.BaseSHA, plan.Recipe.Policy, plan.Recipe.WorkflowTree
+ subject.Members = plan.Recipe.Members[:1]
+ subject.PreparedBy = forgestate.IntegrationPreparationSource{SourceSHA: cfg.Scopes[0].WorkflowTree, RequestDigest: plan.RequestDigest, GitVersion: "git fixture"}
+ plan.Prepared = []forgestate.IntegrationCandidateSubject{subject}
+ receipt := map[string]any{"schema": 1, "protocol": "integration-materializer-receipt-v1", "request": request, "preparedBy": subject.PreparedBy,
+ "prepared": []any{map[string]any{"subject": subject, "publication": "accepted", "dispatch": "accepted"}}}
+ payload, err := json.Marshal(receipt)
+ if err != nil {
+ t.Fatal(err)
+ }
+ key, err := rsa.GenerateKey(rand.Reader, 2048)
+ if err != nil {
+ t.Fatal(err)
+ }
+ proof := executionProofFixture()
+ archive := executionSignedArchive(t, proof, key)
+ archive.Role, archive.Payload, archive.WorkflowSHA, archive.WorkflowPath, archive.Ref, archive.Event =
+ "materializer", payload, subject.PreparedBy.SourceSHA, ".github/workflows/integration-candidate-prepare.yml", "refs/heads/v5", "repository_dispatch"
+ plan.MaterializerRunID, plan.MaterializerAttempt, plan.Materialization = 20, 1, archive
+ executionSignArchive(t, archive, key, plan.Recipe.Repo, 20, 1)
+ plan.Generation++
+ if err := store.AppendExecution("partial-materialization", in.Now, ExecutionEvent{Version: ExecutionSchemaVersion, Plan: &plan}); err != nil {
+ t.Fatal(err)
+ }
+ reopened, err := OpenExecution(store.path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ saved, ok := reopened.ExecutionPlan(plan.Recipe.ID())
+ if !ok || saved.Materialization == nil || len(saved.Prepared) != 1 || len(saved.Recipe.Members) != 2 {
+ t.Fatal("lost partial prefix/private request archive")
+ }
+ for _, test := range []struct {
+ name string
+ change func(*ExecutionPlan)
+ }{
+ {"request", func(p *ExecutionPlan) { p.RequestDigest = strings.Repeat("f", 64) }},
+ {"generation", func(p *ExecutionPlan) { p.Attempt++ }},
+ {"scope", func(p *ExecutionPlan) { p.Recipe.Base = "other" }},
+ {"head", func(p *ExecutionPlan) { p.Recipe.Members[0].Head = strings.Repeat("f", 40) }},
+ {"prefix", func(p *ExecutionPlan) { p.Prepared[0].Prefixes[0].Tree = strings.Repeat("f", 40) }},
+ {"publication", func(p *ExecutionPlan) { p.Prepared = nil }},
+ {"payload", func(p *ExecutionPlan) { p.Materialization.Payload = []byte("{") }},
+ } {
+ t.Run(test.name, func(t *testing.T) {
+ changed := cloneExecution(saved)
+ test.change(&changed)
+ if err := validateMaterializationArchive(changed); err == nil {
+ t.Fatal("accepted altered materializer request/prefix history")
+ }
+ })
+ }
+}
+
+func TestExecutionArchivedProducerHistoricalReplayAndIsolation(t *testing.T) {
+ key, err := rsa.GenerateKey(rand.Reader, 2048)
+ if err != nil {
+ t.Fatal(err)
+ }
+ store, err := OpenExecution(executionFixturePath(t))
+ if err != nil {
+ t.Fatal(err)
+ }
+ proof := executionProofFixture()
+ proof.State, proof.JobCompleteness = Passed, "complete"
+ proof.Archive = executionSignedArchive(t, proof, key)
+ if err := validateExecutionArchive(proof); err != nil {
+ t.Fatalf("valid historical archive: %v", err)
+ }
+ if err := store.AppendExecution("passed", proof.ObservedAt, ExecutionEvent{Version: ExecutionSchemaVersion, Proof: &proof}); err != nil {
+ t.Fatal(err)
+ }
+ replayed, err := OpenExecution(store.path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ saved, ok := replayed.ExecutionProof(proof.Subject.ID, proof.RunID, proof.Attempt)
+ if !ok || saved.State != Passed || saved.Archive == nil {
+ t.Fatalf("lost archived proof: %+v", saved)
+ }
+ saved.Archive.SigningKeySPKI[0] ^= 1
+ untouched, _ := replayed.ExecutionProof(proof.Subject.ID, proof.RunID, proof.Attempt)
+ if err := validateExecutionArchive(untouched); err != nil {
+ t.Fatalf("private archive alias escaped: %v", err)
+ }
+ public, err := json.Marshal(replayed.ExecutionSnapshot())
+ if err != nil || strings.Contains(string(public), proof.Archive.Token) || strings.Contains(string(public), "signing_key_spki") {
+ t.Fatal("private signature/key leaked in public ledger projection")
+ }
+ for _, test := range []struct {
+ name string
+ change func(*ExecutionProof)
+ }{
+ {"role", func(p *ExecutionProof) { p.Archive.Role = "materializer" }},
+ {"issuer", func(p *ExecutionProof) { p.Archive.Issuer = "https://invalid.example" }},
+ {"key-id", func(p *ExecutionProof) { p.Archive.KeyID = "rotated" }},
+ {"key-digest", func(p *ExecutionProof) { p.Archive.SigningKeySHA256 = strings.Repeat("0", 64) }},
+ {"key-encoding", func(p *ExecutionProof) {
+ p.Archive.SigningKeySPKI = []byte("invalid")
+ sum := sha256.Sum256(p.Archive.SigningKeySPKI)
+ p.Archive.SigningKeySHA256 = hex.EncodeToString(sum[:])
+ }},
+ {"payload", func(p *ExecutionProof) { p.Archive.Payload = append(p.Archive.Payload, ' ') }},
+ {"signature", func(p *ExecutionProof) { p.Archive.Token = "invalid" }},
+ {"run", func(p *ExecutionProof) { p.RunID++ }},
+ {"attempt", func(p *ExecutionProof) { p.Attempt++ }},
+ {"repo", func(p *ExecutionProof) { p.Subject.Repo = "other/repo" }},
+ {"head", func(p *ExecutionProof) { p.Subject.Members[0].Head = strings.Repeat("3", 40) }},
+ {"tree", func(p *ExecutionProof) { p.Subject.Prefixes[0].Tree = strings.Repeat("3", 40) }},
+ {"commit", func(p *ExecutionProof) { p.Subject.Prefixes[0].Commit = strings.Repeat("3", 40) }},
+ {"missing-finalizer", func(p *ExecutionProof) { p.Archive.FinalizerCheckID = 99 }},
+ {"duplicate-check", func(p *ExecutionProof) { p.Archive.CheckIDs = []int64{5, 5} }},
+ {"interval", func(p *ExecutionProof) {
+ p.Archive.JobStartedAt = p.ObservedAt.Add(time.Hour)
+ p.Archive.JobCompletedAt = p.Archive.JobStartedAt
+ }},
+ {"ref", func(p *ExecutionProof) { p.Archive.Ref = "refs/heads/v5" }},
+ {"event", func(p *ExecutionProof) { p.Archive.Event = "push" }},
+ } {
+ t.Run(test.name, func(t *testing.T) {
+ changed := cloneExecution(proof)
+ test.change(&changed)
+ if err := validateExecutionArchive(changed); err == nil {
+ t.Fatal("accepted changed historical producer/subject binding")
+ }
+ })
+ }
+}
diff --git a/src/pkg/convergence/integration/execution_cost.go b/src/pkg/convergence/integration/execution_cost.go
new file mode 100644
index 0000000000..8f4b57d289
--- /dev/null
+++ b/src/pkg/convergence/integration/execution_cost.go
@@ -0,0 +1,38 @@
+package integration
+
+import (
+ "fmt"
+ "math"
+ "time"
+)
+
+func executionCostKnown(observed Cost) bool {
+ return observed.Complete && observed.RunnerMinutes != nil && *observed.RunnerMinutes >= 0 &&
+ !math.IsNaN(*observed.RunnerMinutes) && !math.IsInf(*observed.RunnerMinutes, 0) &&
+ observed.Jobs >= 0 && observed.Running >= 0 && observed.Running <= observed.Jobs
+}
+
+// ExecutionCohortCost reuses assigned-runner accounting while unioning durable
+// observers. A default-branch bootstrap can be seen by both ledgers; physical
+// repo/job/attempt keys, not observer ownership, determine execution spend.
+func ExecutionCohortCost(repo, base string, from, through time.Time, coverage []Coverage, cohorts ...[]Job) Cost {
+ complete := len(coverage) > 0
+ for _, observed := range coverage {
+ complete = complete && observed.Complete && !observed.From.After(from) && !observed.Through.Before(through)
+ }
+ jobs := map[string]Job{}
+ for _, cohort := range cohorts {
+ for _, job := range cohort {
+ old, exists := jobs[job.Key()]
+ if exists && (old.Repo != job.Repo || old.Head != job.Head || old.RunID != job.RunID) {
+ complete = false
+ continue
+ }
+ if !exists || job.ObservedAt.After(old.ObservedAt) {
+ jobs[job.Key()] = job
+ }
+ }
+ }
+ return cost(jobs, Coverage{Repo: repo, Base: base, From: from, Through: through, Complete: complete,
+ Reason: fmt.Sprintf("actual deduplicated workflow cohorts; complete=%t", complete)}, repo, base, from, through)
+}
diff --git a/src/pkg/convergence/integration/execution_cost_test.go b/src/pkg/convergence/integration/execution_cost_test.go
new file mode 100644
index 0000000000..ec9dabaa71
--- /dev/null
+++ b/src/pkg/convergence/integration/execution_cost_test.go
@@ -0,0 +1,43 @@
+package integration
+
+import (
+ "math"
+ "testing"
+ "time"
+)
+
+func TestExecutionCostUsesPhysicalAssignedJobsAndExplicitCompleteness(t *testing.T) {
+ through := executionProofFixture().ObservedAt
+ from := through.Add(-time.Minute)
+ coverage := []Coverage{{Repo: "o/r", Base: "v5", From: from, Through: through, Complete: true}}
+ job := Job{Repo: "o/r", Base: "v5", ID: 1, RunID: 10, Attempt: 1, Head: "head", RunnerID: 9, Status: "completed",
+ Conclusion: "cancelled", StartedAt: through.Add(-2 * time.Minute), CompletedAt: through, ObservedAt: through}
+ shared := ExecutionCohortCost("o/r", "v5", from, through, coverage, []Job{job}, []Job{job})
+ if !shared.Complete || shared.RunnerMinutes == nil || *shared.RunnerMinutes != 1 || shared.Jobs != 1 {
+ t.Fatalf("double-counted shared/canceled/window-clipped execution: %+v", shared)
+ }
+ conflicting := job
+ conflicting.Head = "other"
+ ambiguous := ExecutionCohortCost("o/r", "v5", from, through, coverage, []Job{job}, []Job{conflicting})
+ if ambiguous.Complete || ambiguous.RunnerMinutes != nil {
+ t.Fatal("conflicting physical identity became complete")
+ }
+ unknown := ExecutionCohortCost("o/r", "v5", from, through, nil, []Job{job})
+ if unknown.Complete || unknown.RunnerMinutes != nil || unknown.ObservedRunnerMinutes != 1 {
+ t.Fatal("missing cohort became zero/complete")
+ }
+ later := job
+ later.ObservedAt = through.Add(time.Second)
+ if got := ExecutionCohortCost("o/r", "v5", from, through, coverage, []Job{job}, []Job{later}); !got.Complete {
+ t.Fatal("consistent newer physical observation rejected")
+ }
+ for _, value := range []float64{-1, math.Inf(1), math.NaN()} {
+ if executionCostKnown(Cost{Complete: true, RunnerMinutes: &value}) {
+ t.Fatal("nonfinite/negative cost authorized growth")
+ }
+ }
+ zero := 0.0
+ if executionCostKnown(Cost{Complete: true, RunnerMinutes: &zero, Jobs: 0, Running: 1}) {
+ t.Fatal("inconsistent running cohort authorized growth")
+ }
+}
diff --git a/src/pkg/convergence/integration/execution_identity.go b/src/pkg/convergence/integration/execution_identity.go
new file mode 100644
index 0000000000..99cf7ca5ab
--- /dev/null
+++ b/src/pkg/convergence/integration/execution_identity.go
@@ -0,0 +1,90 @@
+package integration
+
+import (
+ "crypto/ed25519"
+ "crypto/rand"
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "fmt"
+ "os"
+ "path/filepath"
+)
+
+const executionIdentityMaxBytes = 4096
+
+type executionPrivateIdentity struct {
+ Version int `json:"version"`
+ Key []byte `json:"key"`
+}
+
+// ExecutionIdentity is installation-local, not a configurable hive name.
+// Cloning this private state/credential is not a supported HA/failover model.
+type ExecutionIdentity struct {
+ ID string
+ PublicKey []byte
+}
+
+func OpenExecutionIdentity(path string) (ExecutionIdentity, error) {
+ if err := os.MkdirAll(filepath.Dir(path), 0700); err != nil {
+ return ExecutionIdentity{}, err
+ }
+ file, err := os.OpenFile(path, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0600)
+ if err == nil {
+ _, key, generationErr := ed25519.GenerateKey(rand.Reader)
+ if generationErr != nil {
+ _ = file.Close()
+ return ExecutionIdentity{}, generationErr
+ }
+ body, encodeErr := json.Marshal(executionPrivateIdentity{Version: ExecutionSchemaVersion, Key: key})
+ if encodeErr == nil {
+ _, encodeErr = file.Write(append(body, '\n'))
+ }
+ if encodeErr == nil {
+ encodeErr = file.Sync()
+ }
+ closeErr := file.Close()
+ if encodeErr != nil {
+ return ExecutionIdentity{}, encodeErr
+ }
+ if closeErr != nil {
+ return ExecutionIdentity{}, closeErr
+ }
+ directory, openErr := os.Open(filepath.Dir(path))
+ if openErr != nil {
+ return ExecutionIdentity{}, openErr
+ }
+ syncErr := directory.Sync()
+ _ = directory.Close()
+ if syncErr != nil {
+ return ExecutionIdentity{}, syncErr
+ }
+ } else if !os.IsExist(err) {
+ return ExecutionIdentity{}, err
+ }
+ stat, err := os.Lstat(path)
+ if err != nil {
+ return ExecutionIdentity{}, err
+ }
+ if stat.Mode().Perm()&0077 != 0 || !stat.Mode().IsRegular() || stat.Size() > executionIdentityMaxBytes {
+ return ExecutionIdentity{}, fmt.Errorf("execution identity requires a private bounded regular file")
+ }
+ body, err := os.ReadFile(path)
+ if err != nil {
+ return ExecutionIdentity{}, err
+ }
+ var identity executionPrivateIdentity
+ if err := json.Unmarshal(body, &identity); err != nil {
+ return ExecutionIdentity{}, err
+ }
+ if identity.Version != ExecutionSchemaVersion || len(identity.Key) != ed25519.PrivateKeySize {
+ return ExecutionIdentity{}, fmt.Errorf("invalid execution identity; do not overwrite or automatically steal ownership")
+ }
+ key := ed25519.PrivateKey(identity.Key)
+ public, ok := key.Public().(ed25519.PublicKey)
+ if !ok {
+ return ExecutionIdentity{}, fmt.Errorf("execution identity public key unavailable")
+ }
+ sum := sha256.Sum256(public)
+ return ExecutionIdentity{ID: hex.EncodeToString(sum[:]), PublicKey: append([]byte(nil), public...)}, nil
+}
diff --git a/src/pkg/convergence/integration/execution_lifecycle_test.go b/src/pkg/convergence/integration/execution_lifecycle_test.go
new file mode 100644
index 0000000000..a886b7159a
--- /dev/null
+++ b/src/pkg/convergence/integration/execution_lifecycle_test.go
@@ -0,0 +1,109 @@
+package integration
+
+import (
+ "github.com/hivecommons/hive/pkg/config"
+ "testing"
+ "time"
+)
+
+func TestExecutionReservationReleaseRetainsAmbiguityAndScopedAudit(t *testing.T) {
+ store, cfg, in := executionAdmissionFixture(t)
+ admitted, err := store.PlanExecution(cfg, in)
+ if err != nil || admitted.Plan == nil {
+ t.Fatalf("plan: %+v %v", admitted, err)
+ }
+ plan := *admitted.Plan
+ plan.State, plan.DispatchOutcome, plan.RequestDigest = Unknown, "unknown", cfg.Scopes[0].Policy
+ plan.Generation++
+ if err := store.AppendExecution("ambiguous", in.Now, ExecutionEvent{Version: ExecutionSchemaVersion, Plan: &plan}); err != nil {
+ t.Fatal(err)
+ }
+ if err := store.ReleaseExecutionReservations([]config.IntegrationExecutionScope{{Repo: "other/repo", Base: "v5"}}, in.Now); err != nil {
+ t.Fatal(err)
+ }
+ current, _ := store.ExecutionPlan(plan.Recipe.ID())
+ if current.ReservationsReleased {
+ t.Fatal("released another scope")
+ }
+ if err := store.ReleaseExecutionReservations(cfg.Scopes, in.Now.Add(time.Minute)); err != nil {
+ t.Fatal(err)
+ }
+ reopened, err := OpenExecution(store.path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ current, _ = reopened.ExecutionPlan(plan.Recipe.ID())
+ if !current.ReservationsReleased || current.State != Unknown || current.DispatchOutcome != "unknown" || current.RequestDigest != plan.RequestDigest {
+ t.Fatalf("release erased ambiguity/evidence: %+v", current)
+ }
+ if _, err := reopened.ResumeExecution(cfg, plan.Recipe.ID(), in.Cost, in.Now.Add(24*time.Hour)); err == nil {
+ t.Fatal("TTL/cooldown stole an ambiguous request")
+ }
+}
+
+func TestExecutionSafeResumeOnlyKnownNotAppliedAndBounded(t *testing.T) {
+ store, cfg, in := executionAdmissionFixture(t)
+ cfg.MaxAttempts = 2
+ admitted, err := store.PlanExecution(cfg, in)
+ if err != nil || admitted.Plan == nil {
+ t.Fatalf("plan: %+v %v", admitted, err)
+ }
+
+ plan, err := store.ResumeExecution(cfg, admitted.Plan.Recipe.ID(), in.Cost, in.Now)
+ if err != nil || plan.Attempt != 1 {
+ t.Fatalf("unissued resume: %+v %v", plan, err)
+ }
+ plan.State, plan.DispatchOutcome = Rejected, "not-applied"
+ plan.Generation++
+ if err := store.AppendExecution("refused", in.Now, ExecutionEvent{Version: ExecutionSchemaVersion, Plan: &plan}); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := store.ResumeExecution(cfg, plan.Recipe.ID(), in.Cost, in.Now); err == nil {
+ t.Fatal("ignored cooldown")
+ }
+ unknown := in.Cost
+ unknown.Complete = false
+ if _, err := store.ResumeExecution(cfg, plan.Recipe.ID(), unknown, in.Now.Add(time.Minute)); err == nil {
+ t.Fatal("resumed without actual accounting")
+ }
+ changed := cfg
+ changed.Scopes = append([]config.IntegrationExecutionScope(nil), cfg.Scopes...)
+ changed.Scopes[0].ExecutorID = cfg.Scopes[0].Policy
+ if _, err := store.ResumeExecution(changed, plan.Recipe.ID(), in.Cost, in.Now.Add(time.Minute)); err == nil {
+ t.Fatal("resumed across executor handover")
+ }
+ resumed, err := store.ResumeExecution(cfg, plan.Recipe.ID(), in.Cost, in.Now.Add(time.Minute))
+ if err != nil || resumed.Attempt != 2 || resumed.RequestDigest != "" || resumed.ReservationsReleased {
+ t.Fatalf("bounded resume: %+v %v", resumed, err)
+ }
+ resumed.State, resumed.DispatchOutcome = Rejected, "not-applied"
+ resumed.Generation++
+ if err := store.AppendExecution("refused-again", resumed.ObservedAt, ExecutionEvent{Version: ExecutionSchemaVersion, Plan: &resumed}); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := store.ResumeExecution(cfg, plan.Recipe.ID(), in.Cost, in.Now.Add(time.Hour)); err == nil {
+ t.Fatal("ignored attempt bound")
+ }
+}
+
+func TestExecutionResumeRefusesMissingPlanDisabledProfileAndSpentBudget(t *testing.T) {
+ store, cfg, in := executionAdmissionFixture(t)
+ if _, err := store.ResumeExecution(cfg, "missing", in.Cost, in.Now); err == nil {
+ t.Fatal("resumed nonexistent recipe")
+ }
+ admitted, err := store.PlanExecution(cfg, in)
+ if err != nil || admitted.Plan == nil {
+ t.Fatalf("plan: %+v %v", admitted, err)
+ }
+ disabled := cfg
+ disabled.Mode = config.IntegrationAdvisory
+ if _, err := store.ResumeExecution(disabled, admitted.Plan.Recipe.ID(), in.Cost, in.Now); err == nil {
+ t.Fatal("advisory resumed dispatch")
+ }
+ spent := cfg.MaxRunnerMinutes
+ cost := in.Cost
+ cost.RunnerMinutes = &spent
+ if _, err := store.ResumeExecution(cfg, admitted.Plan.Recipe.ID(), cost, in.Now); err == nil {
+ t.Fatal("resumed past global minute budget")
+ }
+}
diff --git a/src/pkg/convergence/integration/execution_qualification_test.go b/src/pkg/convergence/integration/execution_qualification_test.go
new file mode 100644
index 0000000000..54f0d7d092
--- /dev/null
+++ b/src/pkg/convergence/integration/execution_qualification_test.go
@@ -0,0 +1,93 @@
+package integration
+
+import (
+ "crypto/rand"
+ "crypto/rsa"
+ "fmt"
+ "strings"
+ "testing"
+)
+
+func TestExecutionQualificationRequiresActualPromotionAndSignedProofLineage(t *testing.T) {
+ store, cfg, in := executionAdmissionFixture(t)
+ proof := executionProofFixture()
+ proof.Subject.Base = "hive-integration-qualification/fixture"
+ proof.State = Passed
+ key, err := rsa.GenerateKey(rand.Reader, 2048)
+ if err != nil {
+ t.Fatal(err)
+ }
+ proof.Archive = executionSignedArchive(t, proof, key)
+ last := proof.Subject.Prefixes[len(proof.Subject.Prefixes)-1]
+ qualification := ExecutionQualification{ID: "actual-probe", Repo: "o/r", Base: "v5", ProbeBase: proof.Subject.Base,
+ ExecutorID: cfg.Scopes[0].ExecutorID, AuthorityCommit: cfg.Scopes[0].AuthorityCommit, RequestActorID: 2,
+ Policy: proof.Subject.Policy, WorkflowTree: proof.Subject.WorkflowTree, ProtectionDigest: strings.Repeat("a", 64),
+ ProfileDigest: strings.Repeat("b", 64), SubjectID: proof.Subject.ID, TestedSHA: last.Commit, MutationKey: "fenced-promotion", ObservedAt: in.Now}
+ event := ExecutionEvent{Version: ExecutionSchemaVersion, Qualification: &qualification}
+ if err := store.AppendExecution("without-promotion", in.Now, event); err == nil {
+ t.Fatal("qualified a configured boolean")
+ }
+ promotion := ExecutionPromotion{Repo: "o/r", Base: proof.Subject.Base, SubjectID: proof.Subject.ID, ProviderAcknowledged: true,
+ ExpectedSHA: proof.Subject.BaseSHA, TestedSHA: last.Commit, AuthorityCommit: qualification.AuthorityCommit,
+ MutationKey: qualification.MutationKey, State: "applied", PR: 1, Head: proof.Subject.Members[0].Head, Attempt: 1, ObservedAt: in.Now}
+ unacknowledged, err := OpenExecution(executionFixturePath(t))
+ if err != nil {
+ t.Fatal(err)
+ }
+ reconciled := promotion
+ reconciled.ProviderAcknowledged = false
+ for _, observed := range []ExecutionEvent{
+ {Version: ExecutionSchemaVersion, Proof: &proof},
+ {Version: ExecutionSchemaVersion, Promotion: &reconciled},
+ } {
+ if err := unacknowledged.AppendExecution(fmt.Sprintf("unacknowledged-%t", observed.Proof != nil), in.Now, observed); err != nil {
+ t.Fatal(err)
+ }
+ }
+ if err := unacknowledged.AppendExecution("reconciliation-is-not-qualification", in.Now, event); err == nil {
+ t.Fatal("an observed destination without successful provider RPC qualified an unproven actor")
+ }
+ if err := store.AppendExecution("actual-promotion", in.Now, ExecutionEvent{Version: ExecutionSchemaVersion, Promotion: &promotion}); err != nil {
+ t.Fatal(err)
+ }
+ if err := store.AppendExecution("without-proof", in.Now, event); err == nil {
+ t.Fatal("qualified without trusted technical lineage")
+ }
+ if err := store.AppendExecution("actual-proof", in.Now, ExecutionEvent{Version: ExecutionSchemaVersion, Proof: &proof}); err != nil {
+ t.Fatal(err)
+ }
+ if err := store.AppendExecution("actual-qualification", in.Now, event); err != nil {
+ t.Fatal(err)
+ }
+ promotion.State = "unknown"
+ if err := store.AppendExecution("late-ambiguous-promotion", in.Now, ExecutionEvent{Version: ExecutionSchemaVersion, Promotion: &promotion}); err != nil {
+ t.Fatal(err)
+ }
+ replayed, err := OpenExecution(store.path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ snapshot := replayed.ExecutionSnapshot()
+ if len(snapshot.Qualifications) != 1 || len(snapshot.Promotions) != 1 || snapshot.Promotions[0].State != "applied" {
+ t.Fatal("late ambiguity erased applied durable qualification lineage")
+ }
+ for _, test := range []struct {
+ name string
+ change func(*ExecutionQualification)
+ }{
+ {"same-base", func(q *ExecutionQualification) { q.ProbeBase = q.Base }},
+ {"not-isolated", func(q *ExecutionQualification) { q.ProbeBase = "topic" }},
+ {"wrong-promotion", func(q *ExecutionQualification) { q.MutationKey = "other" }},
+ {"wrong-subject", func(q *ExecutionQualification) { q.SubjectID = strings.Repeat("e", 64) }},
+ {"wrong-policy", func(q *ExecutionQualification) { q.Policy = strings.Repeat("e", 64) }},
+ {"wrong-tested", func(q *ExecutionQualification) { q.TestedSHA = strings.Repeat("e", 40) }},
+ } {
+ t.Run(test.name, func(t *testing.T) {
+ q := qualification
+ test.change(&q)
+ if err := replayed.AppendExecution("invalid-"+test.name, in.Now, ExecutionEvent{Version: ExecutionSchemaVersion, Qualification: &q}); err == nil {
+ t.Fatal("accepted unbound qualification")
+ }
+ })
+ }
+}
diff --git a/src/pkg/convergence/integration/execution_release.go b/src/pkg/convergence/integration/execution_release.go
new file mode 100644
index 0000000000..d72249025b
--- /dev/null
+++ b/src/pkg/convergence/integration/execution_release.go
@@ -0,0 +1,38 @@
+package integration
+
+import (
+ "fmt"
+ "github.com/hivecommons/hive/pkg/config"
+ "time"
+)
+
+// ReleaseExecutionReservations changes only admission reservations, retaining
+// unknown transport outcomes, exact evidence, issuer history and mutation audit.
+func (s *Store) ReleaseExecutionReservations(scopes []config.IntegrationExecutionScope, now time.Time) error {
+ selected := map[string]bool{}
+ for _, scope := range scopes {
+ selected[scopeKey(scope.Repo, scope.Base)] = true
+ }
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ unlock, err := s.writerLock()
+ if err != nil {
+ return err
+ }
+ defer unlock()
+ for _, current := range s.executionData().plans {
+ if !selected[scopeKey(current.Recipe.Repo, current.Recipe.Base)] || current.ReservationsReleased {
+ continue
+ }
+ plan := cloneExecution(current)
+ plan.ReservationsReleased, plan.ObservedAt = true, now
+ plan.Generation++
+ plan.Reason = "operator released only execution admission reservation; outcome/evidence audit retained"
+ if err := s.appendLocked(Event{Version: SchemaVersion,
+ ID: fmt.Sprintf("execution/release/%s/%d", plan.Recipe.ID(), plan.Generation), At: now,
+ Execution: &ExecutionEvent{Version: ExecutionSchemaVersion, Plan: &plan}}); err != nil {
+ return err
+ }
+ }
+ return nil
+}
diff --git a/src/pkg/convergence/integration/execution_resume.go b/src/pkg/convergence/integration/execution_resume.go
new file mode 100644
index 0000000000..72ba931551
--- /dev/null
+++ b/src/pkg/convergence/integration/execution_resume.go
@@ -0,0 +1,70 @@
+package integration
+
+import (
+ "fmt"
+ "time"
+
+ "github.com/hivecommons/hive/pkg/config"
+)
+
+// ResumeExecution permits only an unissued plan or a definitely-not-applied
+// request. Pending/unknown effects never become stealable after TTL/cooldown.
+func (s *Store) ResumeExecution(cfg config.IntegrationExecutionConfig, id string, observed Cost, now time.Time) (ExecutionPlan, error) {
+ cfg = cfg.Effective()
+ if cfg.Mode != config.IntegrationEnforce || cfg.Validate() != nil || !executionCostKnown(observed) {
+ return ExecutionPlan{}, fmt.Errorf("safe resume requires current enforce profile and complete actual accounting")
+ }
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ unlock, err := s.writerLock()
+ if err != nil {
+ return ExecutionPlan{}, err
+ }
+ defer unlock()
+ state := s.executionData()
+ plan, exists := state.plans[id]
+ if !exists {
+ return ExecutionPlan{}, fmt.Errorf("safe resume plan missing")
+ }
+ scope, enrolled := cfg.Scope(plan.Recipe.Repo, plan.Recipe.Base)
+ if !enrolled || scope.ExecutorID != plan.ExecutorID || scope.AuthorityCommit != plan.AuthorityCommit {
+ return ExecutionPlan{}, fmt.Errorf("safe resume authority changed")
+ }
+ unissued := plan.RequestDigest == "" && plan.State == Waiting
+ retry := plan.State == Rejected && plan.DispatchOutcome == "not-applied" &&
+ plan.Attempt < cfg.MaxAttempts && now.Sub(plan.ObservedAt) >= cfg.Cooldown
+ if !unissued && !retry {
+ return ExecutionPlan{}, fmt.Errorf("request is not definitely unissued/not-applied; no blind retry")
+ }
+ active, jobs, reserved := len(plan.Recipe.Members), len(plan.Recipe.Members)*scope.ExpectedJobs,
+ float64(len(plan.Recipe.Members))*scope.ExpectedMinutes
+ for otherID, other := range state.plans {
+ if otherID == id || other.ReservationsReleased || other.State != Unknown && other.State != Waiting && other.State != Running {
+ continue
+ }
+ profile, enrolled := cfg.Scope(other.Recipe.Repo, other.Recipe.Base)
+ if !enrolled {
+ continue
+ }
+ active += len(other.Recipe.Members)
+ jobs += len(other.Recipe.Members) * profile.ExpectedJobs
+ reserved += float64(len(other.Recipe.Members)) * profile.ExpectedMinutes
+ }
+ if active > cfg.MaxActive || observed.Running+jobs > cfg.MaxJobs ||
+ *observed.RunnerMinutes+reserved > cfg.MaxRunnerMinutes {
+ return ExecutionPlan{}, fmt.Errorf("safe resume global static budget exhausted")
+ }
+ if retry {
+ plan.Attempt++
+ }
+ plan.Generation++
+ plan.AttemptAt, plan.ObservedAt = now, now
+ plan.State, plan.Reason, plan.DispatchOutcome = Waiting, "bounded definitely-not-applied/unissued resume reserved", ""
+ plan.ReservationsReleased = false
+ plan.Materialization, plan.Prepared = nil, nil
+ plan.MaterializerRunID, plan.MaterializerAttempt = 0, 0
+ plan.RequestDigest, plan.MutationKey = "", ""
+ err = s.appendLocked(Event{Version: SchemaVersion, ID: fmt.Sprintf("execution/resume/%s/%d", id, plan.Generation), At: now,
+ Execution: &ExecutionEvent{Version: ExecutionSchemaVersion, Plan: &plan}})
+ return cloneExecution(plan), err
+}
diff --git a/src/pkg/convergence/integration/execution_store.go b/src/pkg/convergence/integration/execution_store.go
new file mode 100644
index 0000000000..ac06f3373c
--- /dev/null
+++ b/src/pkg/convergence/integration/execution_store.go
@@ -0,0 +1,362 @@
+package integration
+
+import (
+ "encoding/json"
+ "fmt"
+ "sort"
+ "strings"
+ "time"
+
+ "github.com/hivecommons/hive/pkg/config"
+)
+
+func (s *Store) executionData() *executionState {
+ if s.execution == nil {
+ s.execution = &executionState{
+ plans: map[string]ExecutionPlan{}, proofs: map[string]ExecutionProof{},
+ invalidations: map[string]ExecutionInvalidation{}, promotions: map[string]ExecutionPromotion{},
+ statuses: map[string]ExecutionStatus{},
+ eligibility: map[string]ExecutionEligibility{},
+ qualifications: map[string]ExecutionQualification{},
+ }
+ }
+ return s.execution
+}
+
+func validExecutionState(state State) bool {
+ switch state {
+ case Unknown, Waiting, Running, Passed, Rejected, Superseded:
+ return true
+ default:
+ return false
+ }
+}
+
+func (s *Store) validateExecution(e ExecutionEvent) error {
+ if e.Version != ExecutionSchemaVersion {
+ return fmt.Errorf("unknown candidate execution schema")
+ }
+ count := 0
+ for _, present := range []bool{e.Plan != nil, e.Proof != nil, e.Invalidate != nil, e.Promotion != nil, e.Status != nil, e.Eligibility != nil, e.Qualification != nil} {
+ if present {
+ count++
+ }
+ }
+ if count != 1 {
+ return fmt.Errorf("execution event requires exactly one typed observation")
+ }
+ if q := e.Qualification; q != nil {
+ if q.ID == "" || q.Repo == "" || q.Base == "" || q.Base == q.ProbeBase ||
+ !strings.HasPrefix(q.ProbeBase, "hive-integration-qualification/") ||
+ !executionHash(q.ExecutorID) || !executionObject(q.AuthorityCommit) ||
+ q.RequestActorID <= 0 || !executionHash(q.Policy) || !executionObject(q.WorkflowTree) ||
+ !executionHash(q.ProtectionDigest) || !executionHash(q.ProfileDigest) || !executionHash(q.SubjectID) ||
+ !executionObject(q.TestedSHA) || q.MutationKey == "" || q.ObservedAt.IsZero() {
+ return fmt.Errorf("qualification requires an observed exact protected isolated promotion, not a configured boolean")
+ }
+ if s.execution == nil {
+ return fmt.Errorf("qualification has no observed promotion/proof lineage")
+ }
+ promotion, exists := s.execution.promotions[q.MutationKey]
+ if !exists || promotion.State != "applied" || !promotion.ProviderAcknowledged || promotion.Repo != q.Repo ||
+ promotion.Base != q.ProbeBase || promotion.SubjectID != q.SubjectID ||
+ promotion.TestedSHA != q.TestedSHA || promotion.AuthorityCommit != q.AuthorityCommit {
+ return fmt.Errorf("qualification is not bound to its actual applied isolated promotion")
+ }
+ verified := false
+ for _, proof := range s.execution.proofs {
+ if proof.Subject.ID == q.SubjectID && proof.Subject.Repo == q.Repo && proof.Subject.Base == q.ProbeBase &&
+ proof.Subject.Policy == q.Policy && proof.Subject.WorkflowTree == q.WorkflowTree &&
+ proof.State == Passed && proof.Archive != nil &&
+ proof.Subject.Prefixes[len(proof.Subject.Prefixes)-1].Commit == q.TestedSHA {
+ verified = true
+ break
+ }
+ }
+ if !verified {
+ return fmt.Errorf("qualification lacks exact trusted producer evidence")
+ }
+ }
+ if eligible := e.Eligibility; eligible != nil {
+ if eligible.Repo == "" || eligible.Base == "" || eligible.PR <= 0 || !executionObject(eligible.Head) ||
+ eligible.ReadyAt.IsZero() || eligible.ObservedAt.Before(eligible.ReadyAt) ||
+ eligible.Source != "normal-automerge-lane-v1" && eligible.Source != "normal-lane-preparation-v1" {
+ return fmt.Errorf("invalid exact normal-lane eligibility observation")
+ }
+ }
+ if p := e.Plan; p != nil {
+ if err := p.Recipe.Validate(); err != nil {
+ return err
+ }
+ if p.Generation == 0 || p.CreatedAt.IsZero() || p.ObservedAt.Before(p.CreatedAt) ||
+ p.AttemptAt.Before(p.CreatedAt) || p.AttemptAt.After(p.ObservedAt) ||
+ !validExecutionState(p.State) || p.Priority < 0 || p.Priority > config.MaxIntegrationExecutionPriority ||
+ p.Attempt < 1 || p.Attempt > config.DefaultIntegrationMaxAttempts ||
+ !executionHash(p.ExecutorID) || !executionObject(p.AuthorityCommit) || len(p.WorkKeys) != len(p.Recipe.Members) ||
+ len(p.WorkBindings) != len(p.WorkKeys) || p.RequestDigest != "" && !executionHash(p.RequestDigest) {
+ return fmt.Errorf("invalid bounded execution plan")
+ }
+ keys := map[string]bool{}
+ for index, key := range p.WorkKeys {
+ if key == "" || keys[key] {
+ return fmt.Errorf("execution requires unique canonical member work keys")
+ }
+ keys[key] = true
+ if p.WorkBindings[index].Key != key || p.WorkBindings[index].IntentGeneration == 0 ||
+ p.WorkBindings[index].PlanRevision < 0 {
+ return fmt.Errorf("invalid exact approved-work generation binding")
+ }
+ }
+ if p.Materialization != nil {
+ if p.Materialization.Role != "materializer" {
+ return fmt.Errorf("candidate receipt cannot attest materialization")
+ }
+ if err := validateArchivedIdentity(*p.Materialization, p.Recipe.Repo, p.MaterializerRunID, p.MaterializerAttempt); err != nil {
+ return err
+ }
+ if err := validateMaterializationArchive(*p); err != nil {
+ return err
+ }
+ } else if len(p.Prepared) != 0 {
+ return fmt.Errorf("published subjects require private verified materializer history")
+ }
+ if s.execution != nil {
+ if old, exists := s.execution.plans[p.Recipe.ID()]; exists && old.Generation == p.Generation {
+ a, _ := json.Marshal(old)
+ b, _ := json.Marshal(p)
+ if string(a) != string(b) {
+ return fmt.Errorf("execution plan generation reused")
+ }
+ }
+ }
+ }
+ if p := e.Proof; p != nil {
+ subject := p.Subject
+ recipe := ExecutionRecipe{Repo: subject.Repo, Base: subject.Base, BaseSHA: subject.BaseSHA,
+ Policy: subject.Policy, WorkflowTree: subject.WorkflowTree, Members: subject.Members}
+ if err := recipe.Validate(); err != nil {
+ return err
+ }
+ if subject.Schema != 1 || subject.Protocol != "integration-prefix-v1" || subject.Engine != "hive" ||
+ !executionHash(subject.ID) ||
+ len(subject.Prefixes) != len(subject.Members) || p.RunID <= 0 || p.Attempt < 1 ||
+ p.ObservedAt.IsZero() || !validExecutionState(p.State) || p.Source != "github-actions-oidc-v1" {
+ return fmt.Errorf("invalid exact execution proof identity")
+ }
+ for _, prefix := range subject.Prefixes {
+ if !executionObject(prefix.Commit) || !executionObject(prefix.Tree) {
+ return fmt.Errorf("invalid tested execution objects")
+ }
+ }
+ if p.Archive != nil {
+ if err := validateExecutionArchive(*p); err != nil {
+ return err
+ }
+ } else if p.State == Passed {
+ return fmt.Errorf("passed execution requires durable verified provenance")
+ }
+ if s.execution != nil {
+ for _, old := range s.execution.proofs {
+ if strings.EqualFold(old.Subject.Repo, subject.Repo) && old.RunID == p.RunID &&
+ old.Attempt == p.Attempt && !old.Subject.SameCore(subject) {
+ return fmt.Errorf("workflow attempt changed immutable candidate core")
+ }
+ }
+ }
+ }
+ if i := e.Invalidate; i != nil && (i.Repo == "" || i.Base == "" || i.Revision == 0 || i.Reason == "") {
+ return fmt.Errorf("invalid execution invalidation lineage")
+ }
+ if p := e.Promotion; p != nil {
+ if p.Repo == "" || p.Base == "" || p.SubjectID == "" || p.MutationKey == "" ||
+ p.PR <= 0 || !executionObject(p.Head) || p.Attempt < 1 || p.Attempt > config.DefaultIntegrationMaxAttempts || p.ObservedAt.IsZero() ||
+ !executionObject(p.ExpectedSHA) || !executionObject(p.TestedSHA) || !executionObject(p.AuthorityCommit) ||
+ p.State != "requested" && p.State != "applied" && p.State != "unknown" && p.State != "rejected" {
+ return fmt.Errorf("invalid fenced promotion observation")
+ }
+ }
+ if status := e.Status; status != nil && (status.Repo == "" || status.Base == "" || status.ObservedAt.IsZero() || status.Reason == "") {
+ return fmt.Errorf("invalid execution runtime status")
+ }
+ return nil
+}
+
+func executionInvalidationKey(i ExecutionInvalidation) string {
+ return fmt.Sprintf("%s/%d", scopeKey(i.Repo, i.Base), i.PR)
+}
+
+func invalidationAffects(i ExecutionInvalidation, p ExecutionProof) bool {
+ if !strings.EqualFold(i.Repo, p.Subject.Repo) || i.Base != p.Subject.Base {
+ return false
+ }
+ if i.PR == 0 {
+ return i.Policy == "" || i.Policy != p.Subject.Policy
+ }
+ for _, member := range p.Subject.Members {
+ if member.PR == i.PR {
+ return i.Head == "" || i.Head != member.Head
+ }
+ }
+ return false
+}
+
+func (s *Store) applyExecution(event Event) {
+ state := s.executionData()
+ e := event.Execution
+ if q := e.Qualification; q != nil {
+ if old, exists := state.qualifications[q.ID]; !exists || q.ObservedAt.After(old.ObservedAt) {
+ state.qualifications[q.ID] = *q
+ }
+ }
+ if eligible := e.Eligibility; eligible != nil {
+ if old, exists := state.eligibility[eligible.Key()]; !exists || !eligible.ObservedAt.Before(old.ObservedAt) {
+ next := *eligible
+ if exists && old.Head == next.Head && old.WorkKey == next.WorkKey {
+ next.ReadyAt = old.ReadyAt
+ }
+ state.eligibility[next.Key()] = next
+ }
+ }
+ if p := e.Plan; p != nil {
+ id := p.Recipe.ID()
+ if old, exists := state.plans[id]; !exists || p.Generation > old.Generation {
+ state.plans[id] = cloneExecution(*p)
+ }
+ }
+ if p := e.Proof; p != nil {
+ next := cloneExecution(*p)
+ next.ObservedState = p.State
+ for _, old := range state.proofs {
+ if strings.EqualFold(old.Subject.Repo, next.Subject.Repo) && old.RunID == next.RunID && old.Attempt > next.Attempt {
+ next.State, next.InvalidatedBy, next.Reason = Superseded, old.Key(), "newer workflow attempt already observed"
+ }
+ }
+ for key, old := range state.proofs {
+ if strings.EqualFold(old.Subject.Repo, next.Subject.Repo) && old.RunID == next.RunID && old.Attempt < next.Attempt {
+ old.State, old.InvalidatedBy, old.Reason = Superseded, event.ID, "authoritative workflow attempt superseded"
+ state.proofs[key] = old
+ }
+ }
+ for key, invalidation := range state.invalidations {
+ if invalidationAffects(invalidation, next) && next.EligibilityRevision < invalidation.Revision {
+ next.State, next.InvalidatedBy, next.Reason = Superseded, key, invalidation.Reason
+ }
+ }
+ old, exists := state.proofs[next.Key()]
+ if !exists || next.ObservedAt.After(old.ObservedAt) ||
+ next.ObservedAt.Equal(old.ObservedAt) && evidenceStateRank(next.State) > evidenceStateRank(old.State) {
+ if exists && old.State == Superseded && next.EligibilityRevision <= old.EligibilityRevision {
+ next.State, next.InvalidatedBy, next.Reason = Superseded, old.InvalidatedBy, old.Reason
+ }
+ state.proofs[next.Key()] = next
+ }
+ }
+ if i := e.Invalidate; i != nil {
+ key := executionInvalidationKey(*i)
+ old, exists := state.invalidations[key]
+ if !exists || i.Revision > old.Revision {
+ state.invalidations[key] = *i
+ for id, proof := range state.proofs {
+ if invalidationAffects(*i, proof) && proof.EligibilityRevision < i.Revision {
+ proof.State, proof.InvalidatedBy, proof.Reason = Superseded, event.ID, i.Reason
+ state.proofs[id] = proof
+ }
+ }
+ }
+ }
+ if p := e.Promotion; p != nil {
+ old, exists := state.promotions[p.MutationKey]
+ if !exists || old.State != "applied" {
+ state.promotions[p.MutationKey] = *p
+ }
+ }
+ if status := e.Status; status != nil {
+ key := scopeKey(status.Repo, status.Base)
+ if old, exists := state.statuses[key]; !exists || !status.ObservedAt.Before(old.ObservedAt) {
+ state.statuses[key] = *status
+ }
+ }
+}
+
+func cloneExecution[T any](value T) T {
+ data, _ := json.Marshal(value)
+ var out T
+ _ = json.Unmarshal(data, &out)
+ return out
+}
+
+func (s *Store) AppendExecution(id string, at time.Time, observation ExecutionEvent) error {
+ return s.Append(Event{Version: SchemaVersion, ID: id, At: at, Execution: &observation})
+}
+
+// ExecutionSnapshot omits private receipt bytes/tokens/keys from API projections.
+func (s *Store) ExecutionSnapshot() ExecutionSnapshot {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ out := ExecutionSnapshot{Version: ExecutionSchemaVersion, Plans: []ExecutionPlan{}, Proofs: []ExecutionProof{},
+ Invalidations: []ExecutionInvalidation{}, Promotions: []ExecutionPromotion{}, Statuses: []ExecutionStatus{}, Eligibility: []ExecutionEligibility{}, Qualifications: []ExecutionQualification{}}
+ if s.execution == nil {
+ return out
+ }
+ for _, plan := range s.execution.plans {
+ plan = cloneExecution(plan)
+ plan.Materialization = nil
+ out.Plans = append(out.Plans, plan)
+ }
+ for _, proof := range s.execution.proofs {
+ proof = cloneExecution(proof)
+ proof.Archive = nil
+ out.Proofs = append(out.Proofs, proof)
+ }
+ for _, invalidation := range s.execution.invalidations {
+ out.Invalidations = append(out.Invalidations, invalidation)
+ }
+ for _, promotion := range s.execution.promotions {
+ out.Promotions = append(out.Promotions, promotion)
+ }
+ for _, status := range s.execution.statuses {
+ out.Statuses = append(out.Statuses, status)
+ }
+ for _, eligible := range s.execution.eligibility {
+ out.Eligibility = append(out.Eligibility, eligible)
+ }
+ for _, qualified := range s.execution.qualifications {
+ out.Qualifications = append(out.Qualifications, qualified)
+ }
+ sort.Slice(out.Plans, func(i, j int) bool { return out.Plans[i].Recipe.ID() < out.Plans[j].Recipe.ID() })
+ sort.Slice(out.Proofs, func(i, j int) bool { return out.Proofs[i].Key() < out.Proofs[j].Key() })
+ sort.Slice(out.Statuses, func(i, j int) bool {
+ return scopeKey(out.Statuses[i].Repo, out.Statuses[i].Base) < scopeKey(out.Statuses[j].Repo, out.Statuses[j].Base)
+ })
+ sort.Slice(out.Eligibility, func(i, j int) bool { return out.Eligibility[i].Key() < out.Eligibility[j].Key() })
+ sort.Slice(out.Qualifications, func(i, j int) bool { return out.Qualifications[i].ID < out.Qualifications[j].ID })
+ return out
+}
+
+func (s *Store) ExecutionProof(subject string, runID int64, attempt int) (ExecutionProof, bool) {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ if s.execution != nil {
+ for _, proof := range s.execution.proofs {
+ if proof.Subject.ID == subject && proof.RunID == runID && proof.Attempt == attempt {
+ return cloneExecution(proof), true
+ }
+
+ }
+ }
+ return ExecutionProof{}, false
+}
+
+// ExecutionPlan returns private producer history for reconciliation, never an
+// HTTP projection. Public snapshots deliberately strip that history.
+func (s *Store) ExecutionPlan(id string) (ExecutionPlan, bool) {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ if s.execution != nil {
+ plan, exists := s.execution.plans[id]
+ if exists {
+ return cloneExecution(plan), true
+ }
+ }
+ return ExecutionPlan{}, false
+}
diff --git a/src/pkg/convergence/integration/execution_store_test.go b/src/pkg/convergence/integration/execution_store_test.go
new file mode 100644
index 0000000000..84e8e21849
--- /dev/null
+++ b/src/pkg/convergence/integration/execution_store_test.go
@@ -0,0 +1,209 @@
+package integration
+
+import (
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/hivecommons/hive/pkg/forgestate"
+)
+
+func executionProofFixture() ExecutionProof {
+ now := time.Date(2026, 10, 31, 3, 0, 0, 0, time.UTC)
+ return ExecutionProof{
+ Subject: forgestate.IntegrationCandidateSubject{
+ Schema: 1, Protocol: "integration-prefix-v1", Engine: "hive", Repo: "o/r", Base: "v5",
+ BaseSHA: strings.Repeat("a", 40), Policy: strings.Repeat("b", 64),
+ WorkflowTree: strings.Repeat("c", 40), Generation: 1, ID: strings.Repeat("d", 64),
+ Members: []forgestate.IntegrationCandidateMember{{PR: 1, Head: strings.Repeat("e", 40)}},
+ Prefixes: []forgestate.IntegrationCandidatePrefix{{Commit: strings.Repeat("f", 40), Tree: strings.Repeat("1", 40)}},
+ },
+ State: Running, ObservedAt: now, RunID: 10, Attempt: 1, Source: "github-actions-oidc-v1",
+ }
+}
+
+func TestExecutionJournalOutOfOrderAttemptInvalidationAndReplay(t *testing.T) {
+ path := executionFixturePath(t)
+ store, err := OpenExecution(path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ p := executionProofFixture()
+ add := func(id string, p ExecutionProof) {
+ t.Helper()
+ if err := store.AppendExecution(id, p.ObservedAt, ExecutionEvent{Version: ExecutionSchemaVersion, Proof: &p}); err != nil {
+ t.Fatal(err)
+ }
+ }
+ add("attempt1", p)
+ add("attempt1", p)
+ newer := cloneExecution(p)
+ newer.Attempt, newer.ObservedAt = 2, p.ObservedAt.Add(time.Minute)
+ add("attempt2", newer)
+ p.ObservedAt = p.ObservedAt.Add(2 * time.Minute)
+ add("late1", p)
+ old, ok := store.ExecutionProof(p.Subject.ID, 10, 1)
+ if !ok || old.State != Superseded {
+ t.Fatalf("late stale attempt revived: %+v", old)
+ }
+ invalidation := ExecutionInvalidation{Repo: "o/r", Base: "v5", PR: 1, Revision: 1, Reason: "review withdrawn at unchanged head"}
+ if err := store.AppendExecution("withdraw", newer.ObservedAt, ExecutionEvent{Version: ExecutionSchemaVersion, Invalidate: &invalidation}); err != nil {
+ t.Fatal(err)
+ }
+ current, ok := store.ExecutionProof(p.Subject.ID, 10, 2)
+ if !ok || current.State != Superseded || current.ObservedState != Running {
+ t.Fatalf("withdrawal lost technical/eligibility distinction: %+v", current)
+ }
+ newer.ObservedAt = newer.ObservedAt.Add(3 * time.Minute)
+ add("stale-eligibility", newer)
+ current, _ = store.ExecutionProof(p.Subject.ID, 10, 2)
+ if current.State != Superseded {
+ t.Fatal("old eligibility revision revived a held proof")
+ }
+ newer.EligibilityRevision = 1
+ newer.ObservedAt = newer.ObservedAt.Add(time.Minute)
+ add("fresh-eligibility", newer)
+ replay, err := OpenExecution(path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ current, _ = replay.ExecutionProof(p.Subject.ID, 10, 2)
+ if current.State != Running || current.EligibilityRevision != 1 {
+ t.Fatalf("fresh exact revision replay: %+v", current)
+ }
+ copyProof, _ := replay.ExecutionProof(p.Subject.ID, 10, 2)
+ copyProof.Subject.Members[0].Head = "mutated by caller"
+ current, _ = replay.ExecutionProof(p.Subject.ID, 10, 2)
+ if current.Subject.Members[0].Head != p.Subject.Members[0].Head {
+ t.Fatal("private store alias escaped")
+ }
+}
+
+func TestExecutionRejectsMalformedObservationAndPartitionMixing(t *testing.T) {
+ for _, test := range []struct {
+ name string
+ change func(*ExecutionProof)
+ }{
+ {"unsigned-pass", func(p *ExecutionProof) { p.State = Passed }},
+ {"source", func(p *ExecutionProof) { p.Source = "artifact-assertion" }},
+ {"id", func(p *ExecutionProof) { p.Subject.ID = strings.Repeat("0", 64) }},
+ {"zero-head", func(p *ExecutionProof) { p.Subject.Members[0].Head = strings.Repeat("0", 40) }},
+ {"object", func(p *ExecutionProof) { p.Subject.Prefixes[0].Commit = "short" }},
+ {"state", func(p *ExecutionProof) { p.State = "green-ish" }},
+ {"run", func(p *ExecutionProof) { p.RunID = 0 }},
+ {"attempt", func(p *ExecutionProof) { p.Attempt = 0 }},
+ } {
+ t.Run(test.name, func(t *testing.T) {
+ store, err := OpenExecution(executionFixturePath(t))
+ if err != nil {
+ t.Fatal(err)
+ }
+ proof := executionProofFixture()
+ test.change(&proof)
+ if err := store.AppendExecution("bad", proof.ObservedAt, ExecutionEvent{Version: ExecutionSchemaVersion, Proof: &proof}); err == nil {
+ t.Fatal("accepted invalid execution proof")
+ }
+ })
+ }
+ store, err := OpenExecution(executionFixturePath(t))
+ if err != nil {
+ t.Fatal(err)
+ }
+ proof := executionProofFixture()
+ if err := store.AppendExecution("wrong-version", proof.ObservedAt, ExecutionEvent{Version: 999, Proof: &proof}); err == nil {
+ t.Fatal("accepted future schema")
+ }
+ if err := store.AppendExecution("no-observation", proof.ObservedAt, ExecutionEvent{Version: ExecutionSchemaVersion}); err == nil {
+ t.Fatal("accepted empty event")
+ }
+ if err := store.Append(Event{Version: SchemaVersion, ID: "v1-release", At: proof.ObservedAt, Release: "*"}); err == nil {
+ t.Fatal("execution journal accepted legacy admission mutation")
+ }
+ if err := store.AppendExecution("core", proof.ObservedAt, ExecutionEvent{Version: ExecutionSchemaVersion, Proof: &proof}); err != nil {
+ t.Fatal(err)
+ }
+ proof.Subject.BaseSHA = strings.Repeat("2", 40)
+ if err := store.AppendExecution("same-attempt-other-core", proof.ObservedAt, ExecutionEvent{Version: ExecutionSchemaVersion, Proof: &proof}); err == nil {
+ t.Fatal("one workflow attempt changed its immutable subject")
+ }
+}
+
+func TestExecutionEligibilityAgingAndPublicPrivateProjection(t *testing.T) {
+ store, _, in := executionAdmissionFixture(t)
+ eligible := ExecutionEligibility{Repo: "o/r", Base: "v5", PR: 1, Head: in.Members[0].Head,
+ WorkKey: "o/r#10", ReadyAt: in.Now, ObservedAt: in.Now, Source: "normal-automerge-lane-v1"}
+ for i := range 2 {
+ eligible.ObservedAt = in.Now.Add(time.Duration(i) * time.Minute)
+ eligible.ReadyAt = eligible.ObservedAt
+ if err := store.AppendExecution("eligible-"+eligible.ObservedAt.String(), eligible.ObservedAt,
+ ExecutionEvent{Version: ExecutionSchemaVersion, Eligibility: &eligible}); err != nil {
+ t.Fatal(err)
+ }
+ }
+ snapshot := store.ExecutionSnapshot()
+ if len(snapshot.Eligibility) != 1 || snapshot.Eligibility[0].ReadyAt != in.Now {
+ t.Fatalf("waiting age reset: %+v", snapshot.Eligibility)
+ }
+ store.mu.Lock()
+ store.executionData().proofs["private"] = ExecutionProof{Archive: &ExecutionArchive{Token: "private-token", Payload: []byte("private-payload")}}
+ store.executionData().plans["private"] = ExecutionPlan{Materialization: &ExecutionArchive{Token: "private-materializer"}}
+ store.mu.Unlock()
+ raw, err := json.Marshal(store.ExecutionSnapshot())
+ if err != nil || strings.Contains(string(raw), "private-token") || strings.Contains(string(raw), "private-materializer") {
+ t.Fatalf("private receipt escaped projection: %s %v", raw, err)
+ }
+}
+
+func TestExecutionIdentityDurablePrivateAndNoAutomaticRepair(t *testing.T) {
+ path := executionFixturePath(t) + ".identity"
+ first, err := OpenExecutionIdentity(path)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ second, err := OpenExecutionIdentity(path)
+ if err != nil || first.ID != second.ID || len(first.ID) != 64 {
+ t.Fatalf("identity changed: %+v %+v %v", first, second, err)
+ }
+ if err := os.Chmod(path, 0644); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := OpenExecutionIdentity(path); err == nil {
+ t.Fatal("public identity private state accepted")
+ }
+ if err := os.Chmod(path, 0600); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(path, []byte("{"), 0600); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := OpenExecutionIdentity(path); err == nil {
+ t.Fatal("corrupt identity was regenerated/taken over")
+ }
+ body, err := os.ReadFile(path)
+ if err != nil || string(body) != "{" {
+ t.Fatal("corrupt identity was overwritten")
+ }
+}
+
+func TestExecutionIdentityRejectsInvalidParentAndFuturePrivateState(t *testing.T) {
+ path := executionFixturePath(t) + ".identity"
+ if err := os.WriteFile(path, []byte("existing regular file"), 0600); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := OpenExecutionIdentity(filepath.Join(path, "child")); err == nil {
+ t.Fatal("identity accepted a file as parent")
+ }
+ if _, err := OpenExecutionIdentity(""); err == nil {
+ t.Fatal("identity accepted empty path")
+ }
+ if err := os.WriteFile(path, []byte(`{"version":999,"key":"AA=="}`), 0600); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := OpenExecutionIdentity(path); err == nil {
+ t.Fatal("future/corrupt private identity was accepted or automatically repaired")
+ }
+}
diff --git a/src/pkg/convergence/integration/execution_types.go b/src/pkg/convergence/integration/execution_types.go
new file mode 100644
index 0000000000..0c3b83e41b
--- /dev/null
+++ b/src/pkg/convergence/integration/execution_types.go
@@ -0,0 +1,247 @@
+package integration
+
+import (
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "fmt"
+ "strings"
+ "time"
+
+ "github.com/hivecommons/hive/pkg/config"
+ "github.com/hivecommons/hive/pkg/forgestate"
+)
+
+const ExecutionSchemaVersion = 2
+
+func executionObject(value string) bool {
+ return fullSHA(value) && value == strings.ToLower(value) && strings.Trim(value, "0") != ""
+}
+
+func executionHash(value string) bool {
+ return len(value) == sha256.Size*2 && strings.Trim(value, "0123456789abcdef") == "" && strings.Trim(value, "0") != ""
+}
+
+// ExecutionRecipe is a planned ordered subject, not a proof or a lease. Its ID
+// excludes the observer generation; changing any ordered head/base/policy does
+// not borrow a previous candidate's evidence.
+type ExecutionRecipe struct {
+ Repo string `json:"repo"`
+ Base string `json:"base"`
+ BaseSHA string `json:"base_sha"`
+ Policy string `json:"policy"`
+ WorkflowTree string `json:"workflow_tree"`
+ Members []forgestate.IntegrationCandidateMember `json:"members"`
+}
+
+func (r ExecutionRecipe) ID() string {
+ data, _ := json.Marshal(r)
+ sum := sha256.Sum256(data)
+ return "integration-recipe-v2/" + hex.EncodeToString(sum[:])
+}
+
+func (r ExecutionRecipe) Validate() error {
+ if r.Repo == "" || r.Base == "" || !executionObject(r.BaseSHA) || !executionObject(r.WorkflowTree) ||
+ !executionHash(r.Policy) || len(r.Members) == 0 || len(r.Members) > config.MaxIntegrationExecutionCandidates {
+ return fmt.Errorf("invalid exact execution recipe")
+ }
+ members, heads := map[int]bool{}, map[string]bool{}
+ for _, member := range r.Members {
+ if member.PR < 1 || !executionObject(member.Head) || members[member.PR] || heads[member.Head] {
+ return fmt.Errorf("invalid ordered execution member")
+ }
+ members[member.PR], heads[member.Head] = true, true
+ }
+ return nil
+}
+
+type ExecutionPlan struct {
+ Recipe ExecutionRecipe `json:"recipe"`
+ Generation uint64 `json:"generation"`
+ CreatedAt time.Time `json:"created_at"`
+ ObservedAt time.Time `json:"observed_at"`
+ State State `json:"state"`
+ Reason string `json:"reason"`
+ Priority int `json:"priority"`
+ WorkKeys []string `json:"work_keys"`
+ ExecutorID string `json:"executor_id"`
+ AuthorityCommit string `json:"authority_commit"`
+ RequestDigest string `json:"request_digest,omitempty"`
+ MaterializerRunID int64 `json:"materializer_run_id,omitempty"`
+ MaterializerAttempt int `json:"materializer_attempt,omitempty"`
+ JobCompleteness string `json:"job_completeness,omitempty"`
+ Prepared []forgestate.IntegrationCandidateSubject `json:"prepared"`
+ MutationKey string `json:"mutation_key,omitempty"`
+ Attempt int `json:"attempt"`
+ AttemptAt time.Time `json:"attempt_at"`
+ DispatchOutcome string `json:"dispatch_outcome,omitempty"`
+ WorkBindings []ExecutionWorkBinding `json:"work_bindings"`
+ ReservationsReleased bool `json:"reservations_released"`
+ Materialization *ExecutionArchive `json:"materialization,omitempty"`
+}
+
+type ExecutionWorkBinding struct {
+ Key string `json:"key"`
+ IntentGeneration uint64 `json:"intent_generation"`
+ PlanRevision int `json:"plan_revision"`
+}
+
+// ExecutionArchive is private durable validation history. The caller must
+// populate it only after authoritative cohort, signature and subject validation;
+// a JWT or an artifact assertion alone cannot create a Passed observation.
+type ExecutionArchive struct {
+ Role string `json:"role"`
+ Issuer string `json:"issuer"`
+ KeyID string `json:"key_id"`
+ SigningKeySPKI []byte `json:"signing_key_spki"`
+ SigningKeySHA256 string `json:"signing_key_sha256"`
+ VerifiedAt time.Time `json:"verified_at"`
+ Payload []byte `json:"payload"`
+ Token string `json:"token"`
+ ArtifactID int64 `json:"artifact_id"`
+ ArtifactDigest string `json:"artifact_digest"`
+ WorkflowID int64 `json:"workflow_id"`
+ SuiteID int64 `json:"suite_id"`
+ CheckIDs []int64 `json:"check_ids"`
+ FinalizerCheckID int64 `json:"finalizer_check_id"`
+ RepositoryID int64 `json:"repository_id"`
+ ActorID int64 `json:"actor_id"`
+ WorkflowSHA string `json:"workflow_sha"`
+ WorkflowPath string `json:"workflow_path"`
+ Ref string `json:"ref"`
+ Event string `json:"event"`
+ JobStartedAt time.Time `json:"job_started_at"`
+ JobCompletedAt time.Time `json:"job_completed_at"`
+}
+
+type ExecutionProof struct {
+ Subject forgestate.IntegrationCandidateSubject `json:"subject"`
+ State State `json:"state"`
+ ObservedState State `json:"observed_state"`
+ ObservedAt time.Time `json:"observed_at"`
+ Source string `json:"source"`
+ RunID int64 `json:"run_id"`
+ Attempt int `json:"attempt"`
+ Archive *ExecutionArchive `json:"archive,omitempty"`
+ EligibilityRevision uint64 `json:"eligibility_revision"`
+ InvalidatedBy string `json:"invalidated_by,omitempty"`
+ Reason string `json:"reason"`
+ JobCompleteness string `json:"job_completeness,omitempty"`
+}
+
+func (p ExecutionProof) Key() string {
+ return fmt.Sprintf("%s/%d/%d/%s", strings.ToLower(p.Subject.Repo), p.RunID, p.Attempt, p.Subject.ID)
+}
+
+type ExecutionInvalidation struct {
+ Repo string `json:"repo"`
+ Base string `json:"base"`
+ PR int `json:"pr,omitempty"`
+ Head string `json:"head,omitempty"`
+ Policy string `json:"policy,omitempty"`
+ Revision uint64 `json:"revision"`
+ Reason string `json:"reason"`
+}
+
+type ExecutionPromotion struct {
+ ProviderAcknowledged bool `json:"provider_acknowledged"`
+ Repo string `json:"repo"`
+ Base string `json:"base"`
+ SubjectID string `json:"subject_id"`
+ ExpectedSHA string `json:"expected_sha"`
+ TestedSHA string `json:"tested_sha"`
+ AuthorityCommit string `json:"authority_commit"`
+ MutationKey string `json:"mutation_key"`
+ State string `json:"state"`
+ Reason string `json:"reason"`
+ PR int `json:"pr"`
+ Head string `json:"head"`
+ Attempt int `json:"attempt"`
+ ObservedAt time.Time `json:"observed_at"`
+}
+
+type ExecutionStatus struct {
+ Repo string `json:"repo"`
+ Base string `json:"base"`
+ ExecutorID string `json:"executor_id"`
+ DesiredMode string `json:"desired_mode"`
+ EffectiveWriter string `json:"effective_writer"`
+ Reason string `json:"reason"`
+ SourceVersion string `json:"source_version"`
+ RuntimeVersion string `json:"runtime_version"`
+ ObservedAt time.Time `json:"observed_at"`
+}
+
+// ExecutionEligibility records author/lane admission separately from combined
+// CI provenance. It expires as scheduling input and never authorizes promotion.
+type ExecutionEligibility struct {
+ Repo string `json:"repo"`
+ Base string `json:"base"`
+ PR int `json:"pr"`
+ Head string `json:"head"`
+ WorkKey string `json:"work_key,omitempty"`
+ IntentGeneration uint64 `json:"intent_generation"`
+ PlanRevision int `json:"plan_revision"`
+ ScopeKnown bool `json:"scope_known"`
+ DependenciesKnown bool `json:"dependencies_known"`
+ DependenciesSatisfied bool `json:"dependencies_satisfied"`
+ ReadyAt time.Time `json:"ready_at"`
+ ObservedAt time.Time `json:"observed_at"`
+ Source string `json:"source"`
+}
+
+type ExecutionQualification struct {
+ ID string `json:"id"`
+ Repo string `json:"repo"`
+ Base string `json:"base"`
+ ProbeBase string `json:"probe_base"`
+ ExecutorID string `json:"executor_id"`
+ AuthorityCommit string `json:"authority_commit"`
+ RequestActorID int64 `json:"request_actor_id"`
+ Policy string `json:"policy"`
+ WorkflowTree string `json:"workflow_tree"`
+ ProtectionDigest string `json:"protection_digest"`
+ ProfileDigest string `json:"profile_digest"`
+ SubjectID string `json:"subject_id"`
+ TestedSHA string `json:"tested_sha"`
+ MutationKey string `json:"mutation_key"`
+ ObservedAt time.Time `json:"observed_at"`
+}
+
+func (e ExecutionEligibility) Key() string {
+ return fmt.Sprintf("%s/%d", scopeKey(e.Repo, e.Base), e.PR)
+}
+
+// ExecutionEvent uses a separately opened execution-v2 journal. It never writes
+// these subjects into convergence's single-PR BaseSHA proof or the v1 partition.
+type ExecutionEvent struct {
+ Version int `json:"version"`
+ Plan *ExecutionPlan `json:"plan,omitempty"`
+ Proof *ExecutionProof `json:"proof,omitempty"`
+ Invalidate *ExecutionInvalidation `json:"invalidate,omitempty"`
+ Promotion *ExecutionPromotion `json:"promotion,omitempty"`
+ Status *ExecutionStatus `json:"status,omitempty"`
+ Eligibility *ExecutionEligibility `json:"eligibility,omitempty"`
+ Qualification *ExecutionQualification `json:"qualification,omitempty"`
+}
+
+type ExecutionSnapshot struct {
+ Version int `json:"version"`
+ Plans []ExecutionPlan `json:"plans"`
+ Proofs []ExecutionProof `json:"proofs"`
+ Invalidations []ExecutionInvalidation `json:"invalidations"`
+ Promotions []ExecutionPromotion `json:"promotions"`
+ Statuses []ExecutionStatus `json:"statuses"`
+ Eligibility []ExecutionEligibility `json:"eligibility"`
+ Qualifications []ExecutionQualification `json:"qualifications"`
+}
+
+type executionState struct {
+ plans map[string]ExecutionPlan
+ proofs map[string]ExecutionProof
+ invalidations map[string]ExecutionInvalidation
+ promotions map[string]ExecutionPromotion
+ statuses map[string]ExecutionStatus
+ eligibility map[string]ExecutionEligibility
+ qualifications map[string]ExecutionQualification
+}
diff --git a/src/pkg/convergence/integration/execution_validation_test.go b/src/pkg/convergence/integration/execution_validation_test.go
new file mode 100644
index 0000000000..9c3e05e5f1
--- /dev/null
+++ b/src/pkg/convergence/integration/execution_validation_test.go
@@ -0,0 +1,59 @@
+package integration
+
+import (
+ "strings"
+ "testing"
+)
+
+func TestExecutionTypedPlanAndRuntimeObservationValidation(t *testing.T) {
+ store, cfg, in := executionAdmissionFixture(t)
+ admitted, err := store.PlanExecution(cfg, in)
+ if err != nil || admitted.Plan == nil {
+ t.Fatalf("plan: %+v %v", admitted, err)
+ }
+ for _, test := range []struct {
+ name string
+ change func(*ExecutionPlan)
+ }{
+ {"recipe", func(p *ExecutionPlan) { p.Recipe.BaseSHA = "short" }},
+ {"member", func(p *ExecutionPlan) { p.Recipe.Members[0].PR = 0 }},
+ {"duplicate-head", func(p *ExecutionPlan) { p.Recipe.Members[1].Head = p.Recipe.Members[0].Head }},
+ {"generation", func(p *ExecutionPlan) { p.Generation = 0 }},
+ {"work-count", func(p *ExecutionPlan) { p.WorkKeys = nil }},
+ {"work-key", func(p *ExecutionPlan) { p.WorkKeys[0] = "" }},
+ {"duplicate-work-key", func(p *ExecutionPlan) { p.WorkKeys[1] = p.WorkKeys[0] }},
+ {"binding", func(p *ExecutionPlan) { p.WorkBindings[0].IntentGeneration = 0 }},
+ {"negative-plan-revision", func(p *ExecutionPlan) { p.WorkBindings[0].PlanRevision = -1 }},
+ {"request", func(p *ExecutionPlan) { p.RequestDigest = "short" }},
+ {"unsigned-prepared", func(p *ExecutionPlan) { p.Prepared = append(p.Prepared, executionProofFixture().Subject) }},
+ {"reused-generation", func(p *ExecutionPlan) { p.Reason = "different payload same generation" }},
+ } {
+ t.Run(test.name, func(t *testing.T) {
+ plan := cloneExecution(*admitted.Plan)
+ test.change(&plan)
+ if err := store.AppendExecution("invalid-"+test.name, in.Now, ExecutionEvent{Version: ExecutionSchemaVersion, Plan: &plan}); err == nil {
+ t.Fatal("accepted invalid plan")
+ }
+ })
+ }
+ status := ExecutionStatus{Repo: "o/r", Base: "v5", ObservedAt: in.Now, DesiredMode: "enforce", EffectiveWriter: "observer", Reason: "actual provider not qualified"}
+ if err := store.AppendExecution("status", in.Now, ExecutionEvent{Version: ExecutionSchemaVersion, Status: &status}); err != nil {
+ t.Fatal(err)
+ }
+ if err := store.AppendExecution("two-kinds", in.Now, ExecutionEvent{Version: ExecutionSchemaVersion, Status: &status, Plan: admitted.Plan}); err == nil {
+ t.Fatal("accepted ambiguous typed event")
+ }
+ invalidStatus := status
+ invalidStatus.Reason = ""
+ if err := store.AppendExecution("bad-status", in.Now, ExecutionEvent{Version: ExecutionSchemaVersion, Status: &invalidStatus}); err == nil {
+ t.Fatal("accepted undocumented writer state")
+ }
+ bad := ExecutionInvalidation{Repo: "o/r", Base: "v5", Revision: 0, Reason: "policy changed"}
+ if err := store.AppendExecution("bad-invalidation", in.Now, ExecutionEvent{Version: ExecutionSchemaVersion, Invalidate: &bad}); err == nil {
+ t.Fatal("accepted unversioned invalidation")
+ }
+ promotion := ExecutionPromotion{Repo: "o/r", Base: "v5", SubjectID: strings.Repeat("d", 64), MutationKey: "key", State: "green-ish"}
+ if err := store.AppendExecution("bad-promotion", in.Now, ExecutionEvent{Version: ExecutionSchemaVersion, Promotion: &promotion}); err == nil {
+ t.Fatal("accepted invalid promotion")
+ }
+}
diff --git a/src/pkg/convergence/integration/store.go b/src/pkg/convergence/integration/store.go
index b981b347a3..a7f49f0a66 100644
--- a/src/pkg/convergence/integration/store.go
+++ b/src/pkg/convergence/integration/store.go
@@ -36,6 +36,8 @@ type Store struct {
integrated map[string]IntegrationReceipt
poison error
offset int64
+ execution *executionState
+ executionOnly bool
}
func (s *Store) HasEvent(id string) bool {
@@ -154,9 +156,19 @@ func (s *Store) ForFailure(repo, head string, suite, check int64) []Evidence {
}
func Open(path string) (*Store, error) {
+ return openStore(path, false)
+}
+
+// OpenExecution reuses the bounded fsync/replay journal but isolates v2
+// candidate execution from the v1 admission/evidence file for safe rollback.
+func OpenExecution(path string) (*Store, error) {
+ return openStore(path, true)
+}
+
+func openStore(path string, executionOnly bool) (*Store, error) {
s := &Store{path: path, seen: map[string]string{}, intents: map[string]Intent{},
evidence: map[string]Evidence{}, jobs: map[string]Job{}, coverage: map[string]Coverage{},
- reservations: map[string]Reservation{}, memberChanges: map[string]Event{}, groupChanges: map[string]Event{}, integrated: map[string]IntegrationReceipt{}, drifts: map[string]Drift{}}
+ reservations: map[string]Reservation{}, memberChanges: map[string]Event{}, groupChanges: map[string]Event{}, integrated: map[string]IntegrationReceipt{}, drifts: map[string]Drift{}, executionOnly: executionOnly}
_, err := os.Stat(path)
if os.IsNotExist(err) {
return s, nil
@@ -188,7 +200,7 @@ func (s *Store) validate(e Event) error {
return fmt.Errorf("event identity reused with different content")
}
n := 0
- for _, yes := range []bool{e.Intent != nil, e.Evidence != nil, e.Job != nil, e.Coverage != nil, e.Reservation != nil, e.Release != "", e.Invalidate != "", e.MemberChange != nil, e.Integrated != nil, e.GroupChange != nil, e.PolicySet != nil, e.Drift != nil} {
+ for _, yes := range []bool{e.Intent != nil, e.Evidence != nil, e.Job != nil, e.Coverage != nil, e.Reservation != nil, e.Release != "", e.Invalidate != "", e.MemberChange != nil, e.Integrated != nil, e.GroupChange != nil, e.PolicySet != nil, e.Drift != nil, e.Execution != nil} {
if yes {
n++
}
@@ -196,6 +208,15 @@ func (s *Store) validate(e Event) error {
if n != 1 {
return fmt.Errorf("event must carry exactly one observation")
}
+ if e.Execution != nil {
+ if !s.executionOnly {
+ return fmt.Errorf("execution v2 requires its own journal partition")
+ }
+ return s.validateExecution(*e.Execution)
+ }
+ if s.executionOnly && e.Job == nil && e.Coverage == nil && e.Integrated == nil {
+ return fmt.Errorf("v1 admission/evidence cannot be written into execution v2")
+ }
if change := e.MemberChange; change != nil && (change.Repo == "" || change.PR <= 0) {
return fmt.Errorf("invalid member change")
}
@@ -304,6 +325,10 @@ func (s *Store) apply(e Event) {
return
}
s.seen[e.ID] = eventDigest(e)
+ if e.Execution != nil {
+ s.applyExecution(e)
+ return
+ }
if drift := e.Drift; drift != nil {
if previous, found := s.drifts[drift.Key]; !found || drift.ObservedAt.After(previous.ObservedAt) {
next := *drift
diff --git a/src/pkg/convergence/integration/types.go b/src/pkg/convergence/integration/types.go
index 2159dcaea5..b69f511de6 100644
--- a/src/pkg/convergence/integration/types.go
+++ b/src/pkg/convergence/integration/types.go
@@ -235,6 +235,7 @@ type Event struct {
GroupChange *GroupChange `json:"group_change,omitempty"`
PolicySet *PolicySet `json:"policy_set,omitempty"`
Drift *Drift `json:"drift,omitempty"`
+ Execution *ExecutionEvent `json:"execution,omitempty"`
}
type GroupChange struct {
diff --git a/src/pkg/convergence/mutation/executor.go b/src/pkg/convergence/mutation/executor.go
index 0921094fbe..554800256b 100644
--- a/src/pkg/convergence/mutation/executor.go
+++ b/src/pkg/convergence/mutation/executor.go
@@ -23,6 +23,10 @@ func JournalingEnabled(mode string) bool { return proof.RecordingEnabled(mode) }
// reports, never withholds.
func FencingEnabled(mode string) bool { return proof.EnforcementEnabled(mode) }
+// DefinitelyNotApplied distinguishes a confirmed pre-effect refusal from an
+// ambiguous transport failure. It does not infer non-application from absence.
+func DefinitelyNotApplied(err error) bool { return errors.Is(err, effects.ErrNotApplied) }
+
// EffectFunc performs the one external effect and returns bounded provenance
// of the applied result (e.g. the created PR URL). An error means the effect
// outcome is UNCERTAIN — it may or may not have taken place externally — and
diff --git a/src/pkg/dashboard/integration_execution.go b/src/pkg/dashboard/integration_execution.go
new file mode 100644
index 0000000000..dac6f47ce8
--- /dev/null
+++ b/src/pkg/dashboard/integration_execution.go
@@ -0,0 +1,150 @@
+package dashboard
+
+import (
+ "context"
+ "fmt"
+ "path/filepath"
+ "strings"
+ "time"
+
+ gh "github.com/google/go-github/v72/github"
+ "github.com/hivecommons/hive/pkg/config"
+ "github.com/hivecommons/hive/pkg/convergence/integration"
+ "github.com/hivecommons/hive/pkg/convergence/mutation"
+ ghpkg "github.com/hivecommons/hive/pkg/github"
+ "github.com/hivecommons/hive/pkg/github/automerge"
+)
+
+func (s *Server) SetIntegrationExecutionEvaluators(prepare, promote automerge.IntegrationEligibilityGate) {
+ s.integration.mu.Lock()
+ defer s.integration.mu.Unlock()
+ s.integration.executionEvaluator = promote
+ s.integration.executionPreparationEvaluator = prepare
+}
+
+func (s *Server) integrationExecutionStore() (*integration.Store, error) {
+ s.integration.executionOnce.Do(func() {
+ path := s.integration.executionPath
+ if path == "" {
+ path = filepath.Join(filepath.Dir(taskLeasesFile), "integration-execution-v2.jsonl")
+ }
+ s.integration.executionStore, s.integration.executionErr = integration.OpenExecution(path)
+ if s.integration.executionErr == nil {
+ s.integration.executionIdentity, s.integration.executionErr =
+ integration.OpenExecutionIdentity(path + ".identity")
+ }
+ if s.integration.executionErr == nil {
+ ledger, err := mutation.OpenLedgerScoped(path+".claims", 1, mutation.TargetWriterScope)
+ if err != nil {
+ s.integration.executionErr = err
+ return
+ }
+ journal, err := mutation.OpenJournal(path + ".mutations")
+ if err != nil {
+ s.integration.executionErr = err
+ return
+ }
+ s.integration.executionBoundary = &mutation.Boundary{
+ Holder: s.integration.executionIdentity.ID, TTL: integrationReconcileTimeout,
+ Executor: mutation.Executor{Ledger: ledger, Journal: journal, Mode: "enforce"},
+ Mode: func() string {
+ if s.integrationConfig().Execution.Effective().Mode == config.IntegrationEnforce {
+ return "enforce"
+ }
+ return "off"
+ },
+ }
+ s.integration.executionVerifier = ghpkg.NewIntegrationProducerVerifier()
+ }
+ })
+ return s.integration.executionStore, s.integration.executionErr
+}
+
+func executionEnrolledScope(cfg config.IntegrationExecutionConfig, repo, base string) (config.IntegrationExecutionScope, bool) {
+ for _, scope := range cfg.Scopes {
+ if strings.EqualFold(scope.Repo, repo) && scope.Base == base {
+ return scope, true
+ }
+ }
+ return config.IntegrationExecutionScope{}, false
+}
+
+// IntegrationExecutionRoute runs only after a normal merge lane has passed its
+// existing gates. Relays pass a nil live evaluator: they route but cannot create
+// a false author/review receipt from their narrower contributor-only check.
+func (s *Server) IntegrationExecutionRoute(_ context.Context, repo string, pr *gh.PullRequest, gate automerge.IntegrationEligibilityGate) (automerge.IntegrationExecutionDecision, error) {
+ cfg := s.integrationConfig().Execution.Effective()
+ if cfg.Mode == config.IntegrationOff || pr == nil {
+ return automerge.IntegrationExecutionDecision{}, nil
+ }
+ scope, enrolled := executionEnrolledScope(cfg, repo, pr.GetBase().GetRef())
+ if !enrolled {
+ return automerge.IntegrationExecutionDecision{}, nil
+ }
+ block := func(reason string, err error) (automerge.IntegrationExecutionDecision, error) {
+ if cfg.Mode != config.IntegrationEnforce {
+ if err != nil {
+ s.webhookLogger().Warn("advisory integration execution unavailable; existing flow unaffected", "reason", reason, "error", err)
+ }
+ return automerge.IntegrationExecutionDecision{}, nil
+ }
+ return automerge.IntegrationExecutionDecision{Authority: "hold", Reason: reason}, err
+ }
+ if err := cfg.Validate(); err != nil {
+ return block("integration execution configuration invalid; no fallback", err)
+ }
+ if scope.Authority == "native" {
+ if cfg.Mode == config.IntegrationAdvisory {
+ return automerge.IntegrationExecutionDecision{}, nil
+ }
+ return automerge.IntegrationExecutionDecision{Authority: "native",
+ Reason: "integration native authority selected; only ordinary bounded enqueue admission is permitted"}, nil
+ }
+ if s.nativeQueueScopeAllowed(scope.Repo, scope.Base) {
+ return block("native authority selected; Hive execution has no direct fallback", nil)
+ }
+ store, err := s.integrationExecutionStore()
+ if err != nil {
+ return block("integration execution durable identity/ledger unavailable", err)
+ }
+ if gate != nil {
+ now := time.Now()
+ eligible := integration.ExecutionEligibility{Repo: scope.Repo, Base: scope.Base,
+ PR: pr.GetNumber(), Head: pr.GetHead().GetSHA(), ReadyAt: now, ObservedAt: now,
+ Source: "normal-automerge-lane-v1"}
+ if intents, intentErr := s.integrationStore(); intentErr == nil {
+ ambiguous := false
+ var intent integration.Intent
+ for _, current := range intents.Intents() {
+ if strings.EqualFold(current.Repo, repo) && current.Base == scope.Base && current.Head == eligible.Head {
+ if intent.Key != "" && intent.Key != current.Key {
+ ambiguous = true
+ break
+ }
+ intent = current
+ }
+ }
+ if intent.Key != "" && !ambiguous {
+ input := s.integrationInput(intent.Key, scope.Repo, scope.Base, now)
+ eligible.WorkKey, eligible.IntentGeneration, eligible.PlanRevision = intent.Key, intent.Generation, intent.PlanRevision
+ eligible.ScopeKnown = intent.ScopeKnown
+ eligible.DependenciesKnown = !input.PlanRequired || input.PlanApproved
+ eligible.DependenciesSatisfied = eligible.DependenciesKnown
+ for _, prerequisite := range intent.Prerequisites {
+ dependency, exists := input.Dependencies[prerequisite.Key]
+ eligible.DependenciesKnown = eligible.DependenciesKnown && exists && dependency.Known
+ eligible.DependenciesSatisfied = eligible.DependenciesSatisfied && exists && dependency.Known && dependency.Satisfied
+ }
+ }
+ }
+ if err := store.AppendExecution(fmt.Sprintf("execution/eligible/%s/%d", eligible.Key(), now.UnixNano()), now,
+ integration.ExecutionEvent{Version: integration.ExecutionSchemaVersion, Eligibility: &eligible}); err != nil {
+ return block("integration normal-lane receipt unavailable; no fallback", err)
+ }
+ }
+ if cfg.Mode == config.IntegrationAdvisory {
+ return automerge.IntegrationExecutionDecision{}, nil
+ }
+ return automerge.IntegrationExecutionDecision{Authority: "hive",
+ Reason: "integration-execution: normal gates passed; exact qualified-prefix authority owns promotion"}, nil
+}
diff --git a/src/pkg/dashboard/integration_execution_admission.go b/src/pkg/dashboard/integration_execution_admission.go
new file mode 100644
index 0000000000..7130eb6c22
--- /dev/null
+++ b/src/pkg/dashboard/integration_execution_admission.go
@@ -0,0 +1,107 @@
+package dashboard
+
+import (
+ "context"
+ "fmt"
+ "time"
+
+ gh "github.com/google/go-github/v72/github"
+ "github.com/hivecommons/hive/pkg/config"
+ "github.com/hivecommons/hive/pkg/convergence/integration"
+)
+
+func (s *Server) integrationExecutionNativeAdmission(ctx context.Context, repo string, pr *gh.PullRequest) (string, error) {
+ cfg := s.integrationConfig().Execution.Effective()
+ if cfg.Mode != config.IntegrationEnforce || pr == nil {
+ return "", nil
+ }
+ scope, enrolled := executionEnrolledScope(cfg, repo, pr.GetBase().GetRef())
+ if !enrolled || scope.Authority != "native" {
+ return "", nil
+ }
+ if err := cfg.Validate(); err != nil {
+ return "execution native admission configuration unavailable", err
+ }
+ if s.deps == nil || s.deps.GHClient == nil {
+ return "execution native forge authority client unavailable", nil
+ }
+ now := time.Now()
+ owned, err := s.integrationExecutionStore()
+ if err != nil {
+ return "execution native actual workflow accounting unavailable", err
+ }
+ authority, err := s.deps.GHClient.ReadIntegrationExecutionAuthority(ctx, scope, s.integration.executionIdentity.ID)
+ if err != nil || !authority {
+ return "execution native designated executor unverified; observer-only, no fallback/takeover", err
+ }
+ s.nativeQueueTracker.mu.Lock()
+ queued, known := s.nativeQueueTracker.observations[nativeQueueScopeKey(scope.Repo, scope.Base)]
+ s.nativeQueueTracker.mu.Unlock()
+ if !known || queued.Stale || !queued.EntriesComplete || now.Sub(queued.ObservedAt) > cfg.ObservationAge {
+ return "execution native exact queue cohort unknown/stale; admission growth frozen", nil
+ }
+ if len(queued.Entries) >= cfg.MaxActive {
+ return "execution native bounded Hive enqueue cohort is full; no queue jumping", nil
+ }
+ accounted := s.integrationExecutionCost(cfg, owned, now)
+ if !accounted.Complete || accounted.RunnerMinutes == nil {
+ return "execution native actual workflow cohort incomplete; unknown is not zero", nil
+ }
+ if accounted.Running+scope.ExpectedJobs > cfg.MaxJobs ||
+ *accounted.RunnerMinutes+scope.ExpectedMinutes > cfg.MaxRunnerMinutes {
+ return "execution native static Hive enqueue budget exhausted; no GitHub group/build-window control", nil
+ }
+ return "", nil
+}
+
+func (s *Server) integrationExecutionCost(cfg config.IntegrationExecutionConfig, store *integration.Store, now time.Time) integration.Cost {
+ legacy, err := s.integrationStore()
+ if err != nil {
+ return integration.Cost{Reason: "existing authoritative workflow accounting unavailable: " + err.Error()}
+ }
+ total := 0.0
+ out := integration.Cost{Complete: true, RunnerMinutes: &total, Reason: "actual author/native and owned integration workflow cohorts"}
+ oldSnapshot, ownSnapshot := legacy.Snapshot(now), store.Snapshot(now)
+ coverage := oldSnapshot.Coverage
+ for _, scope := range cfg.Scopes {
+ through := time.Time{}
+ for _, observed := range coverage {
+ if observed.Repo == scope.Repo && observed.Base == scope.Base {
+ through = observed.Through
+ }
+ }
+ if through.IsZero() || through.After(now) || now.Sub(through) > cfg.ObservationAge {
+ out.Complete = false
+ out.Reason = fmt.Sprintf("%s#%s author/native workflow cohort stale/unknown", scope.Repo, scope.Base)
+ through = now
+ }
+ cohorts := []integration.Coverage{}
+ for _, sources := range [][]integration.Coverage{oldSnapshot.Coverage, ownSnapshot.Coverage} {
+ found := false
+ for _, observed := range sources {
+ if observed.Repo == scope.Repo && observed.Base == scope.Base {
+ cohorts = append(cohorts, observed)
+ found = true
+ }
+ }
+ if !found {
+ cohorts = append(cohorts, integration.Coverage{})
+ }
+ }
+ accounted := integration.ExecutionCohortCost(scope.Repo, scope.Base, through.Add(-cfg.Window), through,
+ cohorts, oldSnapshot.Jobs, ownSnapshot.Jobs)
+ if !accounted.Complete || accounted.RunnerMinutes == nil {
+ out.Complete = false
+ out.Reason = fmt.Sprintf("%s#%s authoritative job coverage incomplete; growth frozen", scope.Repo, scope.Base)
+ } else {
+ total += *accounted.RunnerMinutes
+ }
+ out.Jobs += accounted.Jobs
+ out.Running += accounted.Running
+ out.ObservedRunnerMinutes += accounted.ObservedRunnerMinutes
+ }
+ if !out.Complete {
+ out.RunnerMinutes = nil
+ }
+ return out
+}
diff --git a/src/pkg/dashboard/integration_execution_config.go b/src/pkg/dashboard/integration_execution_config.go
new file mode 100644
index 0000000000..325c923846
--- /dev/null
+++ b/src/pkg/dashboard/integration_execution_config.go
@@ -0,0 +1,90 @@
+package dashboard
+
+import (
+ "context"
+ "fmt"
+ "github.com/hivecommons/hive/pkg/config"
+ "github.com/hivecommons/hive/pkg/convergence/integration"
+ "net/http"
+ "reflect"
+ "strings"
+ "time"
+)
+
+func executionConfigEqual(a, b config.IntegrationExecutionConfig) bool {
+ a, b = a.Effective(), b.Effective()
+ if a.Mode == config.IntegrationOff && b.Mode == config.IntegrationOff && len(a.Scopes) == 0 && len(b.Scopes) == 0 {
+ return true
+ }
+ return reflect.DeepEqual(a, b)
+}
+
+func executionParentChanged(a, b config.IntegrationOrchestrationConfig) bool {
+ a.Execution, b.Execution = config.IntegrationExecutionConfig{}, config.IntegrationExecutionConfig{}
+ return !reflect.DeepEqual(a, b)
+}
+
+func executionReleasedScopes(previous, next config.IntegrationExecutionConfig) []config.IntegrationExecutionScope {
+ out := []config.IntegrationExecutionScope{}
+ for _, old := range previous.Scopes {
+ current, enrolled := executionEnrolledScope(next.Effective(), old.Repo, old.Base)
+ if next.Effective().Mode != config.IntegrationEnforce || !enrolled || !reflect.DeepEqual(current, old) {
+ out = append(out, old)
+ }
+ }
+ return out
+}
+
+func (s *Server) executionHandoverGuard(ctx context.Context, previous, next config.IntegrationExecutionConfig) error {
+ if previous.Effective().Mode != config.IntegrationEnforce {
+ return nil
+ }
+ for _, old := range executionReleasedScopes(previous, next) {
+ if old.Authority != "hive" {
+ continue
+ }
+ current, enrolled := executionEnrolledScope(next, old.Repo, old.Base)
+ if next.Effective().Mode == config.IntegrationEnforce && enrolled &&
+ current.Authority == old.Authority && current.ExecutorID == old.ExecutorID &&
+ current.AuthorityRef == old.AuthorityRef && current.AuthorityCommit == old.AuthorityCommit &&
+ current.ProviderProfileDigest() == old.ProviderProfileDigest() {
+ continue // Scheduling bounds alone do not hand promotion authority away.
+ }
+ if s.deps == nil || s.deps.GHClient == nil {
+ return fmt.Errorf("revoke old forge authority epoch before releasing Hive promotion authority; live reader unavailable")
+ }
+ parts := strings.SplitN(old.Repo, "/", 2)
+ ref, _, err := s.deps.GHClient.GoGitHub().Git.GetRef(ctx, parts[0], parts[1], strings.TrimPrefix(old.AuthorityRef, "refs/"))
+ if err != nil {
+ return fmt.Errorf("old authority revocation is unknown: %w", err)
+ }
+ if ref.GetObject().GetSHA() == old.AuthorityCommit || ref.GetObject().GetSHA() == "" {
+ return fmt.Errorf("revoke exact old shared forge epoch before OFF/advisory/removal/authority handover; config alone cannot fence a paused provider sender")
+ }
+ }
+ return nil
+}
+
+func (s *Server) handleIntegrationExecutionIdentity(w http.ResponseWriter, r *http.Request) {
+ if !requireOwnerRole(w, r) {
+ return
+ }
+ _, err := s.integrationExecutionStore()
+ if err != nil {
+ jsonError(w, "execution identity unavailable: "+err.Error(), http.StatusServiceUnavailable)
+ return
+ }
+ jsonResponse(w, map[string]any{"executor_id": s.integration.executionIdentity.ID,
+ "model": "designated-single-executor-no-failover", "enabled": false,
+ "detail": "local create-only identity only; no registration, permissions, workflow dispatch or configuration enabled"})
+}
+
+func executionPublicProjection(store *integration.Store, cfg config.IntegrationExecutionConfig, now time.Time) map[string]any {
+ return map[string]any{"schema_version": integration.ExecutionSchemaVersion, "ledger": store.ExecutionSnapshot(),
+ "desired_mode": cfg.Effective().Mode, "runtime_mode": cfg.Effective().Mode,
+ "runtime_version": versionHash, "source_version": "unknown", "published_image": "unknown",
+ "authority_model": "enrolled-participants designated-single-executor; no cloned identity, automatic failover or legacy Actions exactly-once",
+ "unregistered_legacy_writers": "not fenced by a local configuration; stop/upgrade/enroll all participants before exclusive activation",
+ "telemetry": "actual controlled producer/bootstrap plus author/native jobs, physical keys deduplicated; missing cohort is unknown",
+ "observed_at": now}
+}
diff --git a/src/pkg/dashboard/integration_execution_config_test.go b/src/pkg/dashboard/integration_execution_config_test.go
new file mode 100644
index 0000000000..9b0f4c6671
--- /dev/null
+++ b/src/pkg/dashboard/integration_execution_config_test.go
@@ -0,0 +1,77 @@
+package dashboard
+
+import (
+ "context"
+ "github.com/hivecommons/hive/pkg/config"
+ "github.com/hivecommons/hive/pkg/forgestate"
+ ghpkg "github.com/hivecommons/hive/pkg/github"
+ "testing"
+ "time"
+)
+
+func TestExecutionDefaultOffNeverInitializesWriterAndTrackerUnknownIsNotGreen(t *testing.T) {
+ s := newTestServer()
+ if err := s.ReconcileIntegrationExecution(context.Background()); err != nil {
+ t.Fatal(err)
+ }
+ if s.stageTrackerIntegrationExecution() != nil || s.integration.executionStore != nil || s.integration.executionIdentity.ID != "" {
+ t.Fatal("OFF opened execution identity/ledger or changed tracker")
+ }
+ s.deps = &Dependencies{Config: &config.Config{IntegrationOrchestration: config.IntegrationOrchestrationConfig{
+ Execution: config.IntegrationExecutionConfig{Mode: config.IntegrationAdvisory, ObservationAge: time.Minute}}}}
+ view := s.stageTrackerIntegrationExecution()
+ if view == nil || view.Mode != "advisory" || view.Telemetry.Complete || view.Telemetry.RunnerMinutes != nil || view.SourceVersion != "unknown" || view.PublishedImage != "unknown" {
+ t.Fatalf("unobserved runtime became green: %+v", view)
+ }
+}
+
+func TestExecutionProfileCASAndScopedReleaseSelection(t *testing.T) {
+ parent := config.IntegrationOrchestrationConfig{Mode: config.IntegrationAdvisory}
+ onlyExecution := parent
+ onlyExecution.Execution.Mode = config.IntegrationAdvisory
+ if executionParentChanged(parent, onlyExecution) {
+ t.Fatal("execution-only update would release authoring reservations")
+ }
+ if !executionConfigEqual(config.IntegrationExecutionConfig{}, config.IntegrationExecutionConfig{Mode: config.IntegrationOff}) {
+ t.Fatal("zero OFF changed identity")
+ }
+ before := config.IntegrationExecutionConfig{Mode: config.IntegrationEnforce, Scopes: []config.IntegrationExecutionScope{
+ {Repo: "o/r", Base: "v5", Authority: "hive", AuthorityCommit: "old"}, {Repo: "o/other", Base: "v5", Authority: "native"}}}
+ after := before
+ after.Scopes = append([]config.IntegrationExecutionScope(nil), before.Scopes...)
+ if !executionConfigEqual(before, after) || len(executionReleasedScopes(before, after)) != 0 {
+ t.Fatal("unchanged profile released reservations")
+ }
+ after.Scopes[0].AuthorityCommit = "new"
+ if executionConfigEqual(before, after) {
+ t.Fatal("CAS ignored authority epoch")
+ }
+ released := executionReleasedScopes(before, after)
+ if len(released) != 1 || released[0].Repo != "o/r" {
+ t.Fatalf("release escaped own changed scope: %+v", released)
+ }
+ after.Mode = config.IntegrationOff
+ if len(executionReleasedScopes(before, after)) != 2 {
+ t.Fatal("rollback retained new-layer reservations")
+ }
+ s := newTestServer()
+ if err := s.executionHandoverGuard(context.Background(), before, after); err == nil {
+ t.Fatal("missing forge reader became proven revocation")
+ }
+}
+
+func TestExecutionAccountingCacheRequiresActualCompleteJobsAndIsBounded(t *testing.T) {
+ s := newTestServer()
+ now := time.Now()
+ s.rememberExecutionCost("o/r", ghpkg.IntegrationCandidateObservation{RunID: 1, Attempt: 1, JobCompleteness: "unknown"}, now)
+ if len(s.integration.executionCostObservations) != 0 {
+ t.Fatal("unknown cohort became zero-cost complete")
+ }
+ for index := 1; index <= integrationExecutionMaxCostCache+1; index++ {
+ s.rememberExecutionCost("o/r", ghpkg.IntegrationCandidateObservation{RunID: int64(index), Attempt: 1, JobCompleteness: "complete",
+ Jobs: []forgestate.IntegrationRunnerJob{{RunID: int64(index), Attempt: 1, JobID: int64(index), Status: "completed"}}}, now)
+ }
+ if len(s.integration.executionCostObservations) > integrationExecutionMaxCostCache {
+ t.Fatal("accounting cache grew without bound")
+ }
+}
diff --git a/src/pkg/dashboard/integration_execution_controller.go b/src/pkg/dashboard/integration_execution_controller.go
new file mode 100644
index 0000000000..713211efe6
--- /dev/null
+++ b/src/pkg/dashboard/integration_execution_controller.go
@@ -0,0 +1,420 @@
+package dashboard
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "reflect"
+ "sort"
+ "strings"
+ "time"
+
+ gh "github.com/google/go-github/v72/github"
+ "github.com/hivecommons/hive/pkg/config"
+ "github.com/hivecommons/hive/pkg/convergence/integration"
+ "github.com/hivecommons/hive/pkg/convergence/mutation"
+ ghpkg "github.com/hivecommons/hive/pkg/github"
+)
+
+const (
+ integrationExecutionScopesPerCycle = 2
+ integrationExecutionPreparationMembers = 8
+ integrationExecutionProtocol = "integration-prefix-v1"
+ integrationExecutionPreparingSource = "normal-lane-preparation-v1"
+)
+
+// ReconcileIntegrationExecution is independent of the legacy convergence flag.
+// Its short lock reserves a bounded worker turn, never a remote-I/O section.
+func (s *Server) ReconcileIntegrationExecution(ctx context.Context) error {
+ cfg := s.integrationConfig().Execution.Effective()
+ if cfg.Mode == config.IntegrationOff {
+ return nil
+ }
+ if err := cfg.Validate(); err != nil {
+ return err
+ }
+ now := time.Now()
+ s.integration.mu.Lock()
+ if s.integration.executionReconciling || now.Sub(s.integration.executionLastReconcile) < integrationReconcileInterval {
+ s.integration.mu.Unlock()
+ return nil
+ }
+ s.integration.executionReconciling, s.integration.executionLastReconcile = true, now
+ offset := s.integration.executionScopeOffset
+ s.integration.executionScopeOffset = (offset + integrationExecutionScopesPerCycle) % len(cfg.Scopes)
+ s.integration.mu.Unlock()
+ defer func() { s.integration.mu.Lock(); s.integration.executionReconciling = false; s.integration.mu.Unlock() }()
+ ctx, cancel := context.WithTimeout(ctx, integrationReconcileTimeout)
+ defer cancel()
+ s.integration.mu.Lock()
+ s.integration.executionCancel = cancel
+ s.integration.mu.Unlock()
+ store, err := s.integrationExecutionStore()
+ if err != nil {
+ return err
+ }
+ defer func() { s.refreshExecutionTracker(store, cfg, time.Now()) }()
+ if s.deps == nil || s.deps.GHClient == nil || s.deps.GHClient.GoGitHub() == nil {
+ return fmt.Errorf("integration execution observer has no live GitHub client")
+ }
+ reads := integrationReconcileMaxRuns
+ var problems []error
+ for index := 0; index < len(cfg.Scopes) && index < integrationExecutionScopesPerCycle; index++ {
+ scope := cfg.Scopes[(offset+index)%len(cfg.Scopes)]
+ if err := s.reconcileIntegrationExecutionScope(ctx, store, cfg, scope, now, &reads); err != nil {
+ problems = append(problems, fmt.Errorf("%s#%s: %w", scope.Repo, scope.Base, err))
+ }
+ }
+ return errors.Join(problems...)
+}
+
+func (s *Server) reconcileIntegrationExecutionScope(ctx context.Context, store *integration.Store, cfg config.IntegrationExecutionConfig, scope config.IntegrationExecutionScope, now time.Time, reads *int) error {
+ status := integration.ExecutionStatus{Repo: scope.Repo, Base: scope.Base,
+ ExecutorID: s.integration.executionIdentity.ID, DesiredMode: cfg.Mode,
+ EffectiveWriter: "observer", SourceVersion: "unknown", RuntimeVersion: versionHash, ObservedAt: now}
+ if scope.Authority == "native" {
+ status.Reason = "native selection unavailable/unobserved; no direct fallback or new poller"
+ s.nativeQueueTracker.mu.Lock()
+ observed, known := s.nativeQueueTracker.observations[nativeQueueScopeKey(scope.Repo, scope.Base)]
+ s.nativeQueueTracker.mu.Unlock()
+ fresh := known && !observed.Stale && observed.EntriesComplete && !observed.ObservedAt.IsZero() && now.Sub(observed.ObservedAt) <= cfg.ObservationAge
+ if fresh && s.nativeQueueScopeAllowed(scope.Repo, scope.Base) && cfg.Mode == config.IntegrationEnforce {
+ status.EffectiveWriter, status.Reason = "github-native", "GitHub owns promotion and build windows; designated Hive admission uses existing native observations"
+ }
+ coverage := integration.Coverage{Repo: scope.Repo, Base: scope.Base, From: now.Add(-cfg.Window - cfg.ObservationAge), Through: now,
+ Complete: true, Source: "execution-native-no-owned-producer-v2",
+ Reason: "native profile cannot dispatch Hive producers; actual native jobs remain in authoritative author/native cohort"}
+ if err := store.Append(integration.Event{Version: integration.SchemaVersion,
+ ID: fmt.Sprintf("execution/coverage/%s/%s/%d", scope.Repo, scope.Base, now.UnixNano()), At: now, Coverage: &coverage}); err != nil {
+ return err
+ }
+ return appendExecutionStatus(store, status)
+ }
+ if s.nativeQueueScopeAllowed(scope.Repo, scope.Base) {
+ status.Reason = "native authority selected; Hive execution/promotion fallback forbidden"
+ return appendExecutionStatus(store, status)
+ }
+ observationErr := s.observeExecutionPlans(ctx, store, cfg, scope, now, reads)
+ authority, err := s.deps.GHClient.ReadIntegrationExecutionAuthority(ctx, scope, s.integration.executionIdentity.ID)
+ if err != nil || !authority {
+ status.Reason = "designated executor/immutable forge authority unavailable; no takeover"
+ _ = appendExecutionStatus(store, status)
+ return err
+ }
+ digest, qualified, err := s.integrationExecutionQualified(ctx, store, scope)
+ if err != nil || !qualified {
+ status.Reason = "actual protected actor/profile qualification unavailable"
+ _ = appendExecutionStatus(store, status)
+ return err
+ }
+ if cfg.Mode == config.IntegrationEnforce {
+ if promoted, err := s.promoteExecutionReady(ctx, store, cfg, scope, digest, now); err != nil || promoted {
+ status.Reason = "exact protected promotion reconciled; next admission waits for fresh destination/telemetry"
+ if err != nil {
+ status.Reason = err.Error()
+ }
+ status.EffectiveWriter = "hive-designated"
+ _ = appendExecutionStatus(store, status)
+ return err
+ }
+ }
+ if observationErr != nil {
+ status.Reason = "actual producer/job cohort incomplete; growth frozen: " + observationErr.Error()
+ _ = appendExecutionStatus(store, status)
+ return observationErr
+ }
+ if err := s.refreshExecutionEligibility(ctx, store, scope, now); err != nil {
+ status.Reason = "normal lane authoring admission unknown: " + err.Error()
+ _ = appendExecutionStatus(store, status)
+ return err
+ }
+ if cfg.Mode == config.IntegrationEnforce {
+ for _, projected := range store.ExecutionSnapshot().Plans {
+ plan, exists := store.ExecutionPlan(projected.Recipe.ID())
+ if !exists || plan.Recipe.Repo != scope.Repo || plan.Recipe.Base != scope.Base ||
+ plan.ExecutorID != scope.ExecutorID || plan.AuthorityCommit != scope.AuthorityCommit {
+ continue
+ }
+ unissued := plan.RequestDigest == "" && plan.State == integration.Waiting
+ retry := plan.State == integration.Rejected && plan.DispatchOutcome == "not-applied" &&
+ plan.Attempt < cfg.MaxAttempts && now.Sub(plan.ObservedAt) >= cfg.Cooldown
+ if !unissued && !retry {
+ continue
+ }
+ budget := s.integrationExecutionCost(cfg, store, now)
+ if !budget.Complete || budget.RunnerMinutes == nil {
+ break
+ }
+ resumed, err := store.ResumeExecution(cfg, plan.Recipe.ID(), budget, now)
+ if err != nil {
+ status.Reason = err.Error()
+ _ = appendExecutionStatus(store, status)
+ return nil
+ }
+ return s.dispatchExecutionPreparation(ctx, store, cfg, scope, resumed, digest, now)
+ }
+ }
+ baseSHA, err := s.executionDestination(ctx, scope.Repo, scope.Base)
+ if err != nil {
+ return err
+ }
+ input := integration.ExecutionAdmissionInput{Repo: scope.Repo, Base: scope.Base, BaseSHA: baseSHA,
+ ExecutorID: s.integration.executionIdentity.ID, AuthorityVerified: authority,
+ QualificationVerified: qualified, Cost: s.integrationExecutionCost(cfg, store, now), Now: now}
+ for _, eligible := range store.ExecutionSnapshot().Eligibility {
+ if eligible.Repo == scope.Repo && eligible.Base == scope.Base && now.Sub(eligible.ObservedAt) <= cfg.ObservationAge {
+ input.Members = append(input.Members, integration.ExecutionMember{
+ PR: eligible.PR, Head: eligible.Head, WorkKey: eligible.WorkKey, Eligible: true,
+ DependenciesKnown: eligible.DependenciesKnown, DependenciesSatisfied: eligible.DependenciesSatisfied,
+ ScopeKnown: eligible.ScopeKnown, ReadyAt: eligible.ReadyAt,
+ IntentGeneration: eligible.IntentGeneration, PlanRevision: eligible.PlanRevision,
+ })
+ }
+ }
+ decision, err := store.PlanExecution(cfg, input)
+ status.Reason, status.EffectiveWriter = decision.Reason, decision.EffectiveWriter
+ if err == nil && cfg.Mode == config.IntegrationEnforce && decision.Plan != nil {
+ err = s.dispatchExecutionPreparation(ctx, store, cfg, scope, *decision.Plan, digest, now)
+ if err != nil {
+ status.Reason = err.Error()
+ }
+ }
+ _ = appendExecutionStatus(store, status)
+ return err
+}
+
+func appendExecutionStatus(store *integration.Store, status integration.ExecutionStatus) error {
+ return store.AppendExecution(fmt.Sprintf("execution/status/%s/%s/%d", status.Repo, status.Base, status.ObservedAt.UnixNano()),
+ status.ObservedAt, integration.ExecutionEvent{Version: integration.ExecutionSchemaVersion, Status: &status})
+}
+
+func (s *Server) executionDestination(ctx context.Context, repo, base string) (string, error) {
+ parts := strings.SplitN(repo, "/", 2)
+ if len(parts) != 2 {
+ return "", fmt.Errorf("execution destination repository invalid")
+ }
+ ref, _, err := s.deps.GHClient.GoGitHub().Git.GetRef(ctx, parts[0], parts[1], "heads/"+base)
+ if err != nil {
+ return "", err
+ }
+ if ref.GetObject().GetSHA() == "" {
+ return "", fmt.Errorf("execution current destination unknown")
+ }
+ return ref.GetObject().GetSHA(), nil
+}
+
+func (s *Server) integrationExecutionQualified(ctx context.Context, store *integration.Store, scope config.IntegrationExecutionScope) (string, bool, error) {
+ if err := s.deps.GHClient.VerifyIntegrationPromotionActor(scope.PromotionAppID, scope.PromotionInstallationID); err != nil {
+ return "", false, err
+ }
+ digest, err := s.deps.GHClient.ReadIntegrationProtectionDigestForActor(ctx, scope.Repo, scope.Base, scope.PromotionAppID)
+ if err != nil {
+ return "", false, err
+ }
+ if scope.Purpose == "qualification" {
+ comparison, err := s.deps.GHClient.ReadIntegrationProtectionDigestForActor(ctx, scope.Repo, scope.QualifiedBase, scope.PromotionAppID)
+ if err != nil {
+ return "", false, err
+ }
+ // This only permits the isolated one-member probe, not production.
+ return digest, digest == comparison, nil
+ }
+ for _, observed := range store.ExecutionSnapshot().Qualifications {
+ if observed.ID == scope.QualificationID && observed.Repo == scope.Repo && observed.Base == scope.Base &&
+ observed.ExecutorID == scope.ExecutorID && observed.RequestActorID == scope.RequestActorID &&
+ observed.ProfileDigest == scope.ProviderProfileDigest() &&
+ observed.Policy == scope.Policy && observed.WorkflowTree == scope.WorkflowTree && observed.ProtectionDigest == digest {
+ return digest, true, nil
+ }
+ }
+ return digest, false, nil
+}
+
+func (s *Server) refreshExecutionEligibility(ctx context.Context, store *integration.Store, scope config.IntegrationExecutionScope, now time.Time) error {
+ s.integration.mu.Lock()
+ gate := s.integration.executionPreparationEvaluator
+ s.integration.mu.Unlock()
+ if gate == nil {
+ return fmt.Errorf("complete normal boot lane preparation evaluator unavailable")
+ }
+ parts := strings.SplitN(scope.Repo, "/", 2)
+ prs, response, err := s.deps.GHClient.GoGitHub().PullRequests.List(ctx, parts[0], parts[1],
+ &gh.PullRequestListOptions{State: "open", Base: scope.Base, Sort: "created", Direction: "asc",
+ ListOptions: gh.ListOptions{PerPage: integrationReconcilePageSize}})
+ if err != nil {
+ return err
+ }
+ if response != nil && response.NextPage != 0 {
+ return fmt.Errorf("open eligible member discovery truncated")
+ }
+ // Older canonical work retains its scheduling age across observations.
+ sort.SliceStable(prs, func(i, j int) bool { return prs[i].GetCreatedAt().Before(prs[j].GetCreatedAt().Time) })
+ for _, candidate := range s.executionEligibilityTurn(scope, prs) {
+ pr, _, err := gate(ctx, scope.Repo, scope.Base, candidate.GetNumber(), candidate.GetHead().GetSHA())
+ if err != nil {
+ return err
+ }
+ if pr == nil {
+ continue
+ }
+ if err := s.recordExecutionEligibility(store, scope, pr, integrationExecutionPreparingSource, now); err != nil {
+ return err
+ }
+ }
+ return nil
+}
+
+func (s *Server) executionEligibilityTurn(scope config.IntegrationExecutionScope, prs []*gh.PullRequest) []*gh.PullRequest {
+ if len(prs) == 0 {
+ return nil
+ }
+ key := strings.ToLower(scope.Repo) + "#" + scope.Base
+ s.integration.mu.Lock()
+ if s.integration.executionEligibilityOffsets == nil {
+ s.integration.executionEligibilityOffsets = map[string]int{}
+ }
+ if _, known := s.integration.executionEligibilityOffsets[key]; !known &&
+ len(s.integration.executionEligibilityOffsets) >= config.MaxIntegrationScopes {
+ s.integration.executionEligibilityOffsets = map[string]int{}
+ }
+ offset := s.integration.executionEligibilityOffsets[key] % len(prs)
+ count := min(len(prs), integrationExecutionPreparationMembers)
+ s.integration.executionEligibilityOffsets[key] = (offset + count) % len(prs)
+ s.integration.mu.Unlock()
+ out := make([]*gh.PullRequest, 0, count)
+ for index := range count {
+ out = append(out, prs[(offset+index)%len(prs)])
+ }
+ return out
+}
+
+func (s *Server) recordExecutionEligibility(store *integration.Store, scope config.IntegrationExecutionScope, pr *gh.PullRequest, source string, now time.Time) error {
+ eligible := integration.ExecutionEligibility{Repo: scope.Repo, Base: scope.Base,
+ PR: pr.GetNumber(), Head: pr.GetHead().GetSHA(), ReadyAt: now, ObservedAt: now, Source: source}
+ intents, err := s.integrationStore()
+ if err != nil {
+ return err
+ }
+ var intent integration.Intent
+ for _, current := range intents.Intents() {
+ if strings.EqualFold(current.Repo, scope.Repo) && current.Base == scope.Base && current.Head == eligible.Head {
+ if intent.Key != "" && intent.Key != current.Key {
+ return fmt.Errorf("ambiguous canonical execution work")
+ }
+ intent = current
+ }
+ }
+ if intent.Key != "" {
+ input := s.integrationInput(intent.Key, scope.Repo, scope.Base, now)
+ eligible.WorkKey, eligible.IntentGeneration, eligible.PlanRevision = intent.Key, intent.Generation, intent.PlanRevision
+ eligible.ScopeKnown = intent.ScopeKnown && intent.PlanRevision == input.PlanRevision
+ eligible.DependenciesKnown = input.PlanApproved && input.PlanRevision == intent.PlanRevision
+ eligible.DependenciesSatisfied = eligible.DependenciesKnown
+ for _, prerequisite := range intent.Prerequisites {
+ dependency, exists := input.Dependencies[prerequisite.Key]
+ eligible.DependenciesKnown = eligible.DependenciesKnown && exists && dependency.Known
+ eligible.DependenciesSatisfied = eligible.DependenciesSatisfied && exists && dependency.Known && dependency.Satisfied
+ }
+
+ }
+ return store.AppendExecution(fmt.Sprintf("execution/eligible/%s/%d", eligible.Key(), now.UnixNano()), now,
+ integration.ExecutionEvent{Version: integration.ExecutionSchemaVersion, Eligibility: &eligible})
+}
+
+func executionPreparationRequest(plan integration.ExecutionPlan) ghpkg.IntegrationPreparationRequest {
+ return ghpkg.IntegrationPreparationRequest{Schema: 1, Protocol: integrationExecutionProtocol, Engine: "hive",
+ Repo: plan.Recipe.Repo, Base: plan.Recipe.Base, BaseSHA: plan.Recipe.BaseSHA, Policy: plan.Recipe.Policy,
+ Generation: int64(plan.Attempt), Members: plan.Recipe.Members, CreatedAt: plan.AttemptAt.UTC().Format(time.RFC3339Nano)}
+}
+
+func (s *Server) executionLiveAuthority(ctx context.Context, cfg config.IntegrationExecutionConfig, scope config.IntegrationExecutionScope, digest string) error {
+ if s.nativeQueueScopeAllowed(scope.Repo, scope.Base) {
+ return fmt.Errorf("native selection forbids Hive execution/promotion fallback")
+ }
+ current := s.integrationConfig().Execution.Effective()
+ liveScope, exists := executionEnrolledScope(current, scope.Repo, scope.Base)
+ if current.Mode != config.IntegrationEnforce || !exists || current.Validate() != nil ||
+ !reflect.DeepEqual(liveScope, scope) || !reflect.DeepEqual(current, cfg) {
+ return fmt.Errorf("live execution mode/profile changed")
+ }
+ verified, err := s.deps.GHClient.ReadIntegrationExecutionAuthority(ctx, scope, s.integration.executionIdentity.ID)
+ if err != nil {
+ return err
+ }
+ if !verified {
+ return fmt.Errorf("shared designated execution authority changed")
+ }
+ liveDigest, qualified, err := s.integrationExecutionQualified(ctx, s.integration.executionStore, scope)
+ if err != nil {
+ return err
+ }
+ if !qualified || liveDigest != digest {
+ return fmt.Errorf("live protection/actor qualification changed")
+ }
+ return nil
+}
+
+func (s *Server) dispatchExecutionPreparation(ctx context.Context, store *integration.Store, cfg config.IntegrationExecutionConfig, scope config.IntegrationExecutionScope, plan integration.ExecutionPlan, protection string, now time.Time) error {
+ request := executionPreparationRequest(plan)
+ raw, digest, err := ghpkg.EncodeIntegrationPreparation(request)
+ if err != nil {
+ return err
+ }
+ plan.RequestDigest, plan.MutationKey = digest, "preparation/"+digest
+ plan.Generation++
+ plan.ObservedAt = now
+ plan.State, plan.Reason = integration.Unknown, "durable pre-effect preparation intent; no timeout/TTL redispatch"
+ if err := appendExecutionPlan(store, plan); err != nil {
+ return err
+ }
+ _, dispatchErr := s.deps.GHClient.DispatchIntegrationPreparation(ctx, request, raw, digest, plan.ExecutorID,
+ plan.AuthorityCommit, s.integration.executionBoundary, func(ctx context.Context) error {
+ if err := s.executionLiveAuthority(ctx, cfg, scope, protection); err != nil {
+ return err
+ }
+ base, err := s.executionDestination(ctx, scope.Repo, scope.Base)
+ if err != nil {
+ return err
+ }
+ if base != plan.Recipe.BaseSHA {
+ return fmt.Errorf("preparation destination moved")
+ }
+ if err := s.executionLiveWork(plan, time.Now()); err != nil {
+ return err
+ }
+ for _, member := range plan.Recipe.Members {
+ s.integration.mu.Lock()
+ gate := s.integration.executionPreparationEvaluator
+ s.integration.mu.Unlock()
+ if gate == nil {
+ return fmt.Errorf("live full preparation evaluator unavailable")
+ }
+ if pr, reason, err := gate(ctx, scope.Repo, scope.Base, member.PR, member.Head); err != nil || pr == nil {
+ return fmt.Errorf("preparation live member %d refused (%s): %w", member.PR, reason, err)
+ }
+ }
+ return nil
+ })
+ plan.Generation++
+ plan.ObservedAt = time.Now()
+ switch {
+ case dispatchErr == nil:
+ plan.State, plan.Reason = integration.Waiting, "transport accepted; actual materializer observation pending"
+ plan.DispatchOutcome = "accepted"
+ case mutation.DefinitelyNotApplied(dispatchErr):
+ plan.State, plan.Reason = integration.Rejected, "definitely not applied; owner-first repair before bounded retry: "+dispatchErr.Error()
+ plan.DispatchOutcome = "not-applied"
+ default:
+ plan.State, plan.Reason = integration.Unknown, "preparation outcome ambiguous; observer-only, no TTL steal/blind repeat: "+dispatchErr.Error()
+ plan.DispatchOutcome = "unknown"
+ }
+ if err := appendExecutionPlan(store, plan); err != nil {
+ return err
+ }
+ return dispatchErr
+}
+
+func appendExecutionPlan(store *integration.Store, plan integration.ExecutionPlan) error {
+ return store.AppendExecution(fmt.Sprintf("execution/plan/%s/%d", plan.Recipe.ID(), plan.Generation), plan.ObservedAt,
+ integration.ExecutionEvent{Version: integration.ExecutionSchemaVersion, Plan: &plan})
+}
diff --git a/src/pkg/dashboard/integration_execution_fairness_test.go b/src/pkg/dashboard/integration_execution_fairness_test.go
new file mode 100644
index 0000000000..68d9c32cd9
--- /dev/null
+++ b/src/pkg/dashboard/integration_execution_fairness_test.go
@@ -0,0 +1,48 @@
+package dashboard
+
+import (
+ "fmt"
+ "testing"
+
+ gh "github.com/google/go-github/v72/github"
+ "github.com/hivecommons/hive/pkg/config"
+)
+
+func TestExecutionEligibilityRotatesPastUnreadyMembersIndependently(t *testing.T) {
+ s := newTestServer()
+ scope := config.IntegrationExecutionScope{Repo: "o/r", Base: "v5"}
+ prs := make([]*gh.PullRequest, 2*integrationExecutionPreparationMembers)
+ for index := range prs {
+ prs[index] = &gh.PullRequest{Number: gh.Ptr(index + 1)}
+ }
+ seen := map[int]bool{}
+ for range 2 {
+ turn := s.executionEligibilityTurn(scope, prs)
+ if len(turn) != integrationExecutionPreparationMembers {
+ t.Fatalf("unbounded/incomplete probe turn: %d", len(turn))
+ }
+ for _, pr := range turn {
+ if seen[pr.GetNumber()] {
+ t.Fatal("an unready older cohort starved later members")
+ }
+ seen[pr.GetNumber()] = true
+ }
+ }
+ if len(seen) != len(prs) {
+ t.Fatal("bounded turns did not cover the discovered cohort")
+ }
+ scope.Base = "other"
+ if got := s.executionEligibilityTurn(scope, prs)[0].GetNumber(); got != 1 {
+ t.Fatalf("another destination inherited the first destination's cursor: %d", got)
+ }
+ if len(s.executionEligibilityTurn(scope, nil)) != 0 {
+ t.Fatal("empty cohort generated work")
+ }
+ for index := range config.MaxIntegrationScopes + 2 {
+ scope.Base = fmt.Sprintf("scope-%d", index)
+ s.executionEligibilityTurn(scope, prs)
+ }
+ if len(s.integration.executionEligibilityOffsets) > config.MaxIntegrationScopes {
+ t.Fatal("configuration churn grew discovery cursors without bounds")
+ }
+}
diff --git a/src/pkg/dashboard/integration_execution_observation_cache.go b/src/pkg/dashboard/integration_execution_observation_cache.go
new file mode 100644
index 0000000000..dbaa2883ca
--- /dev/null
+++ b/src/pkg/dashboard/integration_execution_observation_cache.go
@@ -0,0 +1,110 @@
+package dashboard
+
+import (
+ "context"
+ "fmt"
+ gh "github.com/google/go-github/v72/github"
+ "github.com/hivecommons/hive/pkg/config"
+ "github.com/hivecommons/hive/pkg/convergence/integration"
+ ghpkg "github.com/hivecommons/hive/pkg/github"
+ "sort"
+ "time"
+)
+
+const (
+ integrationExecutionMaxRunAttempts = 100
+ integrationExecutionMaxCostCache = 512
+)
+
+type executionCostObservation struct {
+ ObservedAt time.Time
+ Terminal bool
+}
+
+func executionTerminalMaterializer(plan integration.ExecutionPlan, run *gh.WorkflowRun) bool {
+ return plan.Materialization != nil && plan.JobCompleteness == "complete" &&
+ plan.MaterializerRunID == run.GetID() && plan.MaterializerAttempt == run.GetRunAttempt() &&
+ run.GetStatus() == "completed" && run.GetHeadSHA() == plan.Materialization.WorkflowSHA &&
+ !run.GetUpdatedAt().Time.After(plan.Materialization.VerifiedAt)
+}
+
+func executionTerminalCandidate(proof integration.ExecutionProof, run *gh.WorkflowRun) bool {
+ return proof.Archive != nil && proof.JobCompleteness == "complete" &&
+ proof.RunID == run.GetID() && proof.Attempt == run.GetRunAttempt() &&
+ run.GetStatus() == "completed" &&
+ !run.GetUpdatedAt().Time.After(proof.Archive.VerifiedAt) &&
+ (proof.ObservedState == integration.Passed && run.GetConclusion() == "success" ||
+ proof.ObservedState == integration.Rejected && run.GetConclusion() != "success")
+}
+
+func executionCostObservationKey(repo string, runID int64, attempt int) string {
+ return fmt.Sprintf("%s/%d/%d", repo, runID, attempt)
+}
+
+func (s *Server) rememberExecutionCost(repo string, observed ghpkg.IntegrationCandidateObservation, now time.Time) {
+ if observed.JobCompleteness != "complete" {
+ return
+ }
+ terminal := len(observed.Jobs) > 0
+ for _, job := range observed.Jobs {
+ terminal = terminal && job.Status == "completed"
+ }
+ s.integration.mu.Lock()
+ defer s.integration.mu.Unlock()
+ if s.integration.executionCostObservations == nil {
+ s.integration.executionCostObservations = map[string]executionCostObservation{}
+ }
+ if len(s.integration.executionCostObservations) >= integrationExecutionMaxCostCache {
+ oldestKey, oldest := "", now
+ for key, current := range s.integration.executionCostObservations {
+ if oldestKey == "" || current.ObservedAt.Before(oldest) {
+ oldestKey, oldest = key, current.ObservedAt
+ }
+ }
+ delete(s.integration.executionCostObservations, oldestKey)
+ }
+ s.integration.executionCostObservations[executionCostObservationKey(repo, observed.RunID, observed.Attempt)] =
+ executionCostObservation{ObservedAt: now, Terminal: terminal}
+}
+
+// Completeness is deliberately rebuilt after restart. Persisted physical job
+// facts remain; an empty in-memory cache is not evidence that a missed attempt
+// or duplicate delivery consumed zero runner time.
+func (s *Server) reconcileExecutionCostHistory(ctx context.Context, store *integration.Store, scope config.IntegrationExecutionScope, runs []*gh.WorkflowRun, now time.Time, budget *int) error {
+ type pending struct {
+ run *gh.WorkflowRun
+ attempt int
+ observedAt time.Time
+ }
+ missing := []pending{}
+ s.integration.mu.Lock()
+ for _, run := range runs {
+ if run.GetRunAttempt() < 1 || run.GetRunAttempt() > integrationExecutionMaxRunAttempts {
+ s.integration.mu.Unlock()
+ return fmt.Errorf("actual run attempt history outside bounded accounting; owner reconciliation required")
+ }
+ for attempt := 1; attempt <= run.GetRunAttempt(); attempt++ {
+ last, known := s.integration.executionCostObservations[executionCostObservationKey(scope.Repo, run.GetID(), attempt)]
+ if !known || !last.Terminal && last.ObservedAt.Before(now) {
+ missing = append(missing, pending{run, attempt, last.ObservedAt})
+ }
+ }
+ }
+ s.integration.mu.Unlock()
+ sort.SliceStable(missing, func(i, j int) bool { return missing[i].observedAt.Before(missing[j].observedAt) })
+ for _, current := range missing {
+ if *budget <= 0 {
+ return fmt.Errorf("bounded actual duplicate/attempt job accounting incomplete; unknown is not zero")
+ }
+ *budget--
+ observed, err := s.deps.GHClient.ReadIntegrationExecutionJobs(ctx, scope.Repo, current.run.GetWorkflowID(), current.run.GetID(), current.attempt, now)
+ if appendErr := appendExecutionJobs(store, scope, current.run.GetHeadSHA(), "producer-attempt-accounting", nil, observed, now); appendErr != nil {
+ return appendErr
+ }
+ s.rememberExecutionCost(scope.Repo, observed, now)
+ if err != nil {
+ return err
+ }
+ }
+ return nil
+}
diff --git a/src/pkg/dashboard/integration_execution_observations.go b/src/pkg/dashboard/integration_execution_observations.go
new file mode 100644
index 0000000000..bba140ea2a
--- /dev/null
+++ b/src/pkg/dashboard/integration_execution_observations.go
@@ -0,0 +1,370 @@
+package dashboard
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "sort"
+ "strings"
+ "time"
+
+ gh "github.com/google/go-github/v72/github"
+ "github.com/hivecommons/hive/pkg/config"
+ "github.com/hivecommons/hive/pkg/convergence/integration"
+ "github.com/hivecommons/hive/pkg/forgestate"
+ ghpkg "github.com/hivecommons/hive/pkg/github"
+)
+
+const (
+ integrationExecutionMaterializerPath = ".github/workflows/integration-candidate-prepare.yml"
+ integrationExecutionCandidatePath = ".github/workflows/integration-candidate.yml"
+ integrationExecutionMaterializerFinalizer = "integration materializer receipt"
+ integrationExecutionCandidateFinalizer = "integration producer receipt"
+)
+
+func executionRunsNamed(runs []*gh.WorkflowRun, name string) []*gh.WorkflowRun {
+ out := []*gh.WorkflowRun{}
+ for _, run := range runs {
+ if run != nil && run.GetDisplayTitle() == name {
+ out = append(out, run)
+ }
+ }
+ return out
+}
+
+func (s *Server) observeExecutionPlans(ctx context.Context, store *integration.Store, cfg config.IntegrationExecutionConfig, scope config.IntegrationExecutionScope, now time.Time, budget *int) error {
+ from := now.Add(-cfg.Window - cfg.ObservationAge)
+ plans := []integration.ExecutionPlan{}
+ knownRequests, knownCandidates := map[string]bool{}, map[string]bool{}
+ for _, projected := range store.ExecutionSnapshot().Plans {
+ plan, exists := store.ExecutionPlan(projected.Recipe.ID())
+ if !exists {
+ continue
+ }
+ if plan.RequestDigest != "" {
+ knownRequests["Prepare integration "+plan.RequestDigest] = true
+ }
+ for _, subject := range plan.Prepared {
+ if subject.Claim != nil {
+ knownCandidates["Integration "+subject.ID+" "+subject.Claim.Owner.Nonce] = true
+ }
+ }
+ if plan.Recipe.Repo != scope.Repo || plan.Recipe.Base != scope.Base {
+ continue
+ }
+ active := plan.State == integration.Unknown || plan.State == integration.Waiting || plan.State == integration.Running
+ if !active && plan.CreatedAt.Before(from) {
+ continue
+ }
+ if active && plan.CreatedAt.Before(from) {
+ from = plan.CreatedAt.Add(-time.Minute)
+ }
+ plans = append(plans, plan)
+ }
+ complete, reason := true, "all durable owned producer/bootstrap episodes observed"
+ var materializers, candidates []*gh.WorkflowRun
+ var discoveryErr error
+ materializers, discoveryErr = s.deps.GHClient.ReadIntegrationExecutionRuns(ctx, scope.Repo, scope.MaterializerID, from)
+ if discoveryErr == nil {
+ candidates, discoveryErr = s.deps.GHClient.ReadIntegrationExecutionRuns(ctx, scope.Repo, scope.CandidateWorkflowID, from)
+ }
+ if discoveryErr != nil {
+ complete, reason = false, discoveryErr.Error()
+ }
+ // Unknown producer deliveries are never assumed free. This also exposes
+ // bootstrap/dispatch duplicates instead of claiming exactly-once execution.
+ for _, cohort := range []struct {
+ runs []*gh.WorkflowRun
+ known map[string]bool
+ }{
+ {materializers, knownRequests}, {candidates, knownCandidates},
+ } {
+ counts := map[string]int{}
+ for _, run := range cohort.runs {
+ counts[run.GetDisplayTitle()]++
+ }
+ for _, run := range cohort.runs {
+ if !cohort.known[run.GetDisplayTitle()] || counts[run.GetDisplayTitle()] != 1 {
+ complete, reason = false, "unowned/ambiguous installed producer run requires owner reconciliation"
+ }
+ }
+ }
+ sort.SliceStable(plans, func(i, j int) bool { return plans[i].ObservedAt.Before(plans[j].ObservedAt) })
+ for _, plan := range plans {
+ if plan.RequestDigest == "" {
+ continue
+ } // durable plan, no pre-effect intent yet
+ matches := executionRunsNamed(materializers, "Prepare integration "+plan.RequestDigest)
+ if plan.DispatchOutcome == "not-applied" && len(matches) == 0 && discoveryErr == nil {
+ continue
+ }
+ if discoveryErr != nil || len(matches) != 1 {
+ complete, reason = false, "preparation has no unique actual run; no absence-based redispatch"
+ continue
+ }
+ run := matches[0]
+ if !executionTerminalMaterializer(plan, run) {
+ if *budget <= 0 {
+ complete, reason = false, "bounded run observation budget exhausted"
+ break
+ }
+ *budget--
+ observed, err := s.deps.GHClient.ReadIntegrationMaterializerObservation(ctx, ghpkg.IntegrationMaterializerExpectation{
+ Request: executionPreparationRequest(plan), RequestDigest: plan.RequestDigest,
+ DefaultBranch: scope.DefaultBranch, EventName: "repository_dispatch", WorkflowTree: scope.WorkflowTree,
+ RepositoryID: scope.RepositoryID, ActorID: scope.RequestActorID, WorkflowID: scope.MaterializerID,
+ CheckAppID: scope.ProducerAppID, RunID: run.GetID(), Attempt: run.GetRunAttempt(),
+ }, s.integration.executionVerifier, now)
+ if jobErr := appendExecutionJobs(store, scope, run.GetHeadSHA(), "materializer", []string{plan.Recipe.ID()}, observed.Evidence, now); jobErr != nil {
+ return jobErr
+ }
+ if observed.Evidence.JobCompleteness != "complete" {
+ complete, reason = false, "actual bootstrap job cohort incomplete"
+ }
+ s.rememberExecutionCost(scope.Repo, observed.Evidence, now)
+ plan.Generation++
+ plan.JobCompleteness = observed.Evidence.JobCompleteness
+ plan.ObservedAt, plan.MaterializerRunID, plan.MaterializerAttempt = now, run.GetID(), run.GetRunAttempt()
+ if err != nil {
+ plan.State, plan.Reason = integration.Unknown, "materializer provenance unresolved: "+err.Error()
+ complete, reason = false, plan.Reason
+ } else {
+ plan.State, plan.Reason = integration.State(observed.Evidence.State), observed.Evidence.Detail
+ if observed.Evidence.State == "passed" {
+ archive, archiveErr := executionArchive(scope, observed.Evidence, "materializer",
+ observed.Receipt.PreparedBy.SourceSHA, "refs/heads/"+scope.DefaultBranch, "repository_dispatch")
+ if archiveErr != nil {
+ return archiveErr
+ }
+ plan.Materialization, plan.Prepared = archive, []forgestate.IntegrationCandidateSubject{}
+ for _, prepared := range observed.Receipt.Prepared {
+ if prepared.Publication == "accepted" {
+ plan.Prepared = append(plan.Prepared, prepared.Subject)
+ }
+ }
+ plan.State, plan.Reason = integration.Waiting, "materialization verified; exact candidate workflows pending"
+ if len(plan.Prepared) == 0 {
+ plan.State, plan.Reason = integration.Rejected, "trusted materializer produced no accepted prefix"
+ }
+ }
+ }
+ if err := appendExecutionPlan(store, plan); err != nil {
+ return err
+ }
+ }
+ allTerminal, allPassed := len(plan.Prepared) > 0, len(plan.Prepared) > 0
+ subjects := append([]forgestate.IntegrationCandidateSubject(nil), plan.Prepared...)
+ lastObserved := map[string]time.Time{}
+ for _, proof := range store.ExecutionSnapshot().Proofs {
+ if proof.ObservedAt.After(lastObserved[proof.Subject.ID]) {
+ lastObserved[proof.Subject.ID] = proof.ObservedAt
+ }
+ }
+ sort.SliceStable(subjects, func(i, j int) bool {
+ return lastObserved[subjects[i].ID].Before(lastObserved[subjects[j].ID])
+ })
+ for _, subject := range subjects {
+ if subject.Claim == nil {
+ complete, reason, allTerminal = false, "candidate has no verified initial claim", false
+ continue
+ }
+ matches := executionRunsNamed(candidates, "Integration "+subject.ID+" "+subject.Claim.Owner.Nonce)
+ if len(matches) != 1 {
+ complete, reason, allTerminal = false, "candidate run absent/duplicated; owner action required, no rerun", false
+ continue
+ }
+ run := matches[0]
+ proof, cached := store.ExecutionProof(subject.ID, run.GetID(), run.GetRunAttempt())
+ if cached && executionTerminalCandidate(proof, run) {
+ allTerminal = allTerminal && (proof.ObservedState == integration.Passed || proof.ObservedState == integration.Rejected)
+ allPassed = allPassed && proof.ObservedState == integration.Passed
+ continue
+ }
+ if *budget <= 0 {
+ complete, reason, allTerminal = false, "bounded candidate observation budget exhausted", false
+ break
+ }
+ *budget--
+ proof, cohortComplete, err := s.observeExecutionCandidate(ctx, store, scope, subject, run.GetID(), run.GetRunAttempt(), now)
+ if err != nil {
+ complete, reason = false, err.Error()
+ }
+ complete = complete && cohortComplete
+ allTerminal = allTerminal && (proof.State == integration.Passed || proof.State == integration.Rejected)
+ allPassed = allPassed && proof.State == integration.Passed
+ }
+ if len(plan.Prepared) > 0 {
+ plan.Generation++
+ plan.State = integration.Running
+ if allTerminal {
+ plan.State = integration.Rejected
+ if allPassed && len(plan.Prepared) == len(plan.Recipe.Members) {
+ plan.State = integration.Passed
+ }
+ }
+ plan.Reason = "actual exact-prefix technical workflow observations; author eligibility remains separate"
+ if allTerminal && len(plan.Prepared) != len(plan.Recipe.Members) {
+ plan.Reason = "only a strict prefix was published; recipe tail rejected, valid prefix receipts retained independently"
+ }
+ if err := appendExecutionPlan(store, plan); err != nil {
+ return err
+ }
+ }
+ }
+ allRuns := append(append([]*gh.WorkflowRun(nil), materializers...), candidates...)
+ if err := s.reconcileExecutionCostHistory(ctx, store, scope, allRuns, now, budget); err != nil {
+ complete, reason = false, err.Error()
+ }
+ coverage := integration.Coverage{Repo: scope.Repo, Base: scope.Base, From: from, Through: now,
+ Complete: complete, Source: "execution-owned-actions-cohort-v2", Reason: reason}
+ if err := store.Append(integration.Event{Version: integration.SchemaVersion,
+ ID: fmt.Sprintf("execution/coverage/%s/%s/%d", scope.Repo, scope.Base, now.UnixNano()), At: now, Coverage: &coverage}); err != nil {
+ return err
+ }
+ if !complete {
+ return fmt.Errorf("%s", reason)
+ }
+ return nil
+}
+
+func executionArchive(scope config.IntegrationExecutionScope, observed ghpkg.IntegrationCandidateObservation, role, workflowSHA, ref, event string) (*integration.ExecutionArchive, error) {
+ path, finalizer, actor := integrationExecutionCandidatePath, integrationExecutionCandidateFinalizer, scope.CandidateActorID
+ if role == "materializer" {
+ path, finalizer, actor = integrationExecutionMaterializerPath, integrationExecutionMaterializerFinalizer, scope.RequestActorID
+ }
+ archive := &integration.ExecutionArchive{Role: role, Issuer: observed.Identity.Issuer, KeyID: observed.Identity.KeyID,
+ SigningKeySPKI: observed.Identity.SigningKeySPKI, SigningKeySHA256: observed.Identity.SigningKeySHA256,
+ VerifiedAt: observed.Identity.VerifiedAt, Payload: observed.Payload, Token: observed.Token,
+ ArtifactID: observed.ArtifactID, ArtifactDigest: observed.ArtifactDigest, WorkflowID: observed.WorkflowID,
+ SuiteID: observed.SuiteID, CheckIDs: observed.CheckIDs, FinalizerCheckID: observed.Identity.FinalizerCheckRunID,
+ RepositoryID: scope.RepositoryID, ActorID: actor, WorkflowSHA: workflowSHA, WorkflowPath: path, Ref: ref, Event: event}
+ found := false
+ for _, job := range observed.Jobs {
+ if job.Name == finalizer {
+ if found {
+ return nil, fmt.Errorf("actual isolated finalizer job ambiguous")
+ }
+ found, archive.JobStartedAt, archive.JobCompletedAt = true, job.StartedAt, job.CompletedAt
+ }
+ }
+ if !found {
+ return nil, fmt.Errorf("actual isolated finalizer interval unavailable")
+ }
+ return archive, nil
+}
+
+func appendExecutionJobs(store *integration.Store, scope config.IntegrationExecutionScope, head, role string, subjects []string, observed ghpkg.IntegrationCandidateObservation, now time.Time) error {
+ for _, actual := range observed.Jobs {
+ job := integration.Job{Repo: scope.Repo, Base: scope.Base, ID: actual.JobID, RunID: actual.RunID,
+ Attempt: actual.Attempt, Head: head, Workflow: role, RunnerID: actual.RunnerID, Status: actual.Status,
+ Conclusion: actual.Conclusion, StartedAt: actual.StartedAt, CompletedAt: actual.CompletedAt,
+ ObservedAt: actual.ObservedAt, Candidates: subjects}
+ if err := store.Append(integration.Event{Version: integration.SchemaVersion,
+ ID: fmt.Sprintf("execution/job/%s/%d", job.Key(), now.UnixNano()), At: now, Job: &job}); err != nil {
+ return err
+ }
+ }
+ return nil
+}
+
+func (s *Server) observeExecutionCandidate(ctx context.Context, store *integration.Store, scope config.IntegrationExecutionScope, subject forgestate.IntegrationCandidateSubject, runID int64, attempt int, now time.Time) (integration.ExecutionProof, bool, error) {
+ observed, err := s.deps.GHClient.ReadIntegrationCandidateObservation(ctx, ghpkg.IntegrationCandidateExpectation{
+ Subject: subject, RepositoryID: scope.RepositoryID, ActorID: scope.CandidateActorID,
+ WorkflowID: scope.CandidateWorkflowID, CheckAppID: scope.ProducerAppID,
+ RunID: runID, Attempt: attempt, RequiredJobs: scope.RequiredJobs,
+ }, s.integration.executionVerifier, now)
+ last := subject.Prefixes[len(subject.Prefixes)-1]
+ if jobErr := appendExecutionJobs(store, scope, last.Commit, "candidate", []string{subject.ID}, observed, now); jobErr != nil {
+ return integration.ExecutionProof{}, false, jobErr
+ }
+ proof := integration.ExecutionProof{Subject: subject, State: integration.State(observed.State), ObservedAt: now,
+ Source: "github-actions-oidc-v1", RunID: runID, Attempt: attempt, Reason: observed.Detail, JobCompleteness: observed.JobCompleteness}
+ s.rememberExecutionCost(scope.Repo, observed, now)
+ if err != nil {
+ proof.State, proof.Reason = integration.Unknown, err.Error()
+ }
+ if observed.Identity.VerifiedAt.IsZero() == false && len(observed.Payload) > 0 {
+ archive, archiveErr := executionArchive(scope, observed, "candidate", last.Commit, "refs/tags/hive-integration/"+subject.ID, "workflow_dispatch")
+ if archiveErr != nil {
+ return proof, false, archiveErr
+ }
+ proof.Archive = archive
+ }
+ // Preserve invalidation until a complete live promotion evaluation restores
+ // eligibility; a repeated artifact observation is not a review receipt.
+ if old, exists := store.ExecutionProof(subject.ID, runID, attempt); exists {
+ proof.EligibilityRevision = old.EligibilityRevision
+ }
+ if appendErr := store.AppendExecution(fmt.Sprintf("execution/proof/%s/%d", proof.Key(), now.UnixNano()), now,
+ integration.ExecutionEvent{Version: integration.ExecutionSchemaVersion, Proof: &proof}); appendErr != nil {
+ return proof, false, appendErr
+ }
+ persisted, _ := store.ExecutionProof(subject.ID, runID, attempt)
+ return persisted, observed.JobCompleteness == "complete", err
+}
+
+func (s *Server) observeIntegrationExecutionWebhook(event, delivery string, body []byte, now time.Time) error {
+ cfg := s.integrationConfig().Execution.Effective()
+ if cfg.Mode == config.IntegrationOff {
+ return nil
+ }
+ var payload integrationWebhookPayload
+ if err := json.Unmarshal(body, &payload); err != nil {
+ return err
+ }
+ enrolled := false
+ for _, scope := range cfg.Scopes {
+ if strings.EqualFold(scope.Repo, payload.Repository.FullName) {
+ enrolled = true
+ break
+ }
+ }
+ if !enrolled {
+ return nil
+ }
+ store, err := s.integrationExecutionStore()
+ if err != nil {
+ return err
+ }
+ if store.HasEvent("execution/github/" + delivery) {
+ return nil
+ }
+ if (event == "pull_request" || event == "pull_request_review") && payload.PullRequest != nil && !payload.PullRequest.GetMerged() {
+ pr := payload.PullRequest
+ invalidation := integration.ExecutionInvalidation{Repo: payload.Repository.FullName,
+ Base: pr.GetBase().GetRef(), PR: pr.GetNumber(), Revision: uint64(now.UnixNano()), Reason: "live head/member/hold/review changed"}
+ if payload.Action == "synchronize" {
+ invalidation.Head = pr.GetHead().GetSHA()
+ }
+ if err := store.AppendExecution("execution/github/"+delivery, now,
+ integration.ExecutionEvent{Version: integration.ExecutionSchemaVersion, Invalidate: &invalidation}); err != nil {
+ return err
+ }
+ }
+ policyChanged := event == "branch_protection_rule" || event == "repository_ruleset"
+ if policyChanged {
+ for _, scope := range cfg.Scopes {
+ if !strings.EqualFold(scope.Repo, payload.Repository.FullName) {
+ continue
+ }
+ id := "execution/github/" + delivery + "/policy/" + scope.Base
+ if store.HasEvent(id) {
+ continue
+ }
+ invalidation := integration.ExecutionInvalidation{Repo: scope.Repo, Base: scope.Base, Revision: uint64(now.UnixNano()),
+ Reason: "actual protection/ruleset event changed eligibility; exact live policy revalidation required"}
+ if err := store.AppendExecution(id, now, integration.ExecutionEvent{Version: integration.ExecutionSchemaVersion, Invalidate: &invalidation}); err != nil {
+ return err
+ }
+ }
+ }
+ if policyChanged || event == "workflow_run" || event == "workflow_job" || event == "pull_request" || event == "pull_request_review" || event == "push" {
+ s.integration.mu.Lock()
+ if now.Sub(s.integration.executionLastNudge) >= config.MinIntegrationExecutionInterval {
+ s.integration.executionLastReconcile = time.Time{}
+ s.integration.executionLastNudge = now
+ }
+ s.integration.mu.Unlock()
+ }
+ return nil
+}
diff --git a/src/pkg/dashboard/integration_execution_promotion.go b/src/pkg/dashboard/integration_execution_promotion.go
new file mode 100644
index 0000000000..8a8650ac92
--- /dev/null
+++ b/src/pkg/dashboard/integration_execution_promotion.go
@@ -0,0 +1,311 @@
+package dashboard
+
+import (
+ "context"
+ "fmt"
+ "sort"
+ "strings"
+ "time"
+
+ "github.com/hivecommons/hive/pkg/config"
+ "github.com/hivecommons/hive/pkg/convergence/integration"
+ "github.com/hivecommons/hive/pkg/convergence/mutation"
+ "github.com/hivecommons/hive/pkg/forgestate"
+ ghpkg "github.com/hivecommons/hive/pkg/github"
+ "github.com/hivecommons/hive/pkg/github/automerge"
+)
+
+const integrationExecutionPromotionGeneration = 1
+
+func executionPredecessor(subject forgestate.IntegrationCandidateSubject) string {
+ if len(subject.Prefixes) == 1 {
+ return subject.BaseSHA
+ }
+ return subject.Prefixes[len(subject.Prefixes)-2].Commit
+}
+
+func executionTechnicalPassed(proof integration.ExecutionProof) bool {
+ return proof.Archive != nil && (proof.State == integration.Passed ||
+ proof.State == integration.Superseded && proof.ObservedState == integration.Passed)
+}
+
+func (s *Server) promoteExecutionReady(ctx context.Context, store *integration.Store, cfg config.IntegrationExecutionConfig, scope config.IntegrationExecutionScope, protection string, now time.Time) (bool, error) {
+ snapshot := store.ExecutionSnapshot()
+ proofs := snapshot.Proofs
+ sort.SliceStable(proofs, func(i, j int) bool {
+ if len(proofs[i].Subject.Members) == len(proofs[j].Subject.Members) {
+ return proofs[i].ObservedAt.Before(proofs[j].ObservedAt)
+ }
+ return len(proofs[i].Subject.Members) < len(proofs[j].Subject.Members)
+ })
+ base, err := s.executionDestination(ctx, scope.Repo, scope.Base)
+ if err != nil {
+ return false, err
+ }
+ for _, projection := range proofs {
+ subject := projection.Subject
+ if subject.Repo != scope.Repo || subject.Base != scope.Base ||
+ subject.Policy != scope.Policy || subject.WorkflowTree != scope.WorkflowTree {
+ continue
+ }
+ proof, exists := store.ExecutionProof(subject.ID, projection.RunID, projection.Attempt)
+ if !exists || !executionTechnicalPassed(proof) {
+ continue
+ }
+ last := subject.Prefixes[len(subject.Prefixes)-1]
+ member := subject.Members[len(subject.Members)-1]
+ key := "promotion/" + subject.ID + "/" + executionPredecessor(subject) + "/" + scope.AuthorityCommit
+ var previous *integration.ExecutionPromotion
+ for index := range snapshot.Promotions {
+ if snapshot.Promotions[index].MutationKey == key {
+ previous = &snapshot.Promotions[index]
+ break
+ }
+ }
+ if previous != nil && previous.State == "applied" {
+ if scope.Purpose == "qualification" {
+ if err := s.recordExecutionQualification(ctx, store, scope, protection, *previous, now); err != nil {
+ return false, err
+ }
+ }
+ continue
+ }
+ // A crash after CAS is reconciled with exactly the same journalled
+ // subject, never a new unbound promotion or a different tested tree.
+ reconciling := previous != nil && (previous.State == "unknown" || previous.State == "requested") && base == last.Commit
+ if base != executionPredecessor(subject) && !reconciling {
+ continue
+ }
+ if previous != nil && previous.State == "rejected" &&
+ (previous.Attempt >= cfg.MaxAttempts || now.Sub(previous.ObservedAt) < cfg.Cooldown) {
+ continue
+ }
+ if !reconciling {
+ if err := s.verifyExecutionPredecessors(ctx, store, subject); err != nil {
+ continue
+ }
+ }
+ parts := strings.SplitN(scope.Repo, "/", 2)
+ pr, _, err := s.deps.GHClient.GoGitHub().PullRequests.Get(ctx, parts[0], parts[1], member.PR)
+ if err != nil {
+ return false, err
+ }
+ if pr.GetHead().GetSHA() != member.Head || pr.GetBase().GetRef() != scope.Base ||
+ !strings.EqualFold(pr.GetHead().GetRepo().GetFullName(), scope.Repo) {
+ continue
+ }
+ promotion := integration.ExecutionPromotion{Repo: scope.Repo, Base: scope.Base, SubjectID: subject.ID,
+ ExpectedSHA: executionPredecessor(subject), TestedSHA: last.Commit, AuthorityCommit: scope.AuthorityCommit,
+ MutationKey: key, State: "requested", PR: member.PR, Head: member.Head, Attempt: 1, ObservedAt: now,
+ Reason: "durable exact-subject promotion intent; actual protected CAS not yet acknowledged"}
+ if previous != nil {
+ promotion.Attempt = previous.Attempt
+ if previous.State == "rejected" {
+ promotion.Attempt++
+ }
+ }
+ if err := appendExecutionPromotion(store, promotion); err != nil {
+ return false, err
+ }
+ request := ghpkg.IntegrationPromotion{Repo: scope.Repo, Base: scope.Base, ExpectedSHA: promotion.ExpectedSHA,
+ TestedSHA: last.Commit, TestedTree: last.Tree, AuthorHead: member.Head,
+ HeadRepo: pr.GetHead().GetRepo().GetFullName(), HeadRef: pr.GetHead().GetRef(),
+ SubjectID: subject.ID, Policy: scope.Policy, Generation: integrationExecutionPromotionGeneration,
+ AuthorityRef: scope.AuthorityRef, AuthorityCommit: scope.AuthorityCommit}
+ result, acknowledged, promoteErr := s.deps.GHClient.PromoteIntegrationStepWithAcknowledgement(ctx, request, s.integration.executionBoundary,
+ func(ctx context.Context, exact ghpkg.IntegrationPromotion) error {
+ return s.executionPromotionGuard(ctx, store, cfg, scope, protection, proof, exact)
+ })
+ promotion.ObservedAt = time.Now()
+ promotion.ProviderAcknowledged = acknowledged
+ switch {
+ case promoteErr == nil && result.Provenance == last.Commit:
+ promotion.State, promotion.Reason = "applied", "actual protected atomic destination+author-head+authority-epoch CAS acknowledged/reconciled"
+ case mutation.DefinitelyNotApplied(promoteErr):
+ promotion.State, promotion.Reason = "rejected", "live guard definitely refused before effect: "+promoteErr.Error()
+ default:
+ promotion.State, promotion.Reason = "unknown", "promotion outcome unknown; only exact fenced reconciliation permitted"
+ if promoteErr != nil {
+ promotion.Reason += ": " + promoteErr.Error()
+ }
+ }
+ if err := appendExecutionPromotion(store, promotion); err != nil {
+ return true, err
+ }
+ if promotion.State == "applied" {
+ if scope.Purpose == "qualification" {
+ if err := s.recordExecutionQualification(ctx, store, scope, protection, promotion, time.Now()); err != nil {
+ return true, err
+ }
+ }
+ return true, nil
+ }
+ if promotion.State == "unknown" {
+ return true, promoteErr
+ }
+ // An unrelated held member does not freeze independent ready work.
+ }
+ return false, nil
+}
+
+func appendExecutionPromotion(store *integration.Store, promotion integration.ExecutionPromotion) error {
+ return store.AppendExecution(fmt.Sprintf("execution/promotion/%s/%s/%d", promotion.MutationKey, promotion.State, promotion.ObservedAt.UnixNano()),
+ promotion.ObservedAt, integration.ExecutionEvent{Version: integration.ExecutionSchemaVersion, Promotion: &promotion})
+}
+
+func (s *Server) verifyExecutionPredecessors(ctx context.Context, store *integration.Store, subject forgestate.IntegrationCandidateSubject) error {
+ snapshot := store.ExecutionSnapshot()
+ parts := strings.SplitN(subject.Repo, "/", 2)
+ for index := 0; index+1 < len(subject.Members); index++ {
+ member, prefix := subject.Members[index], subject.Prefixes[index]
+ known := false
+ for _, applied := range snapshot.Promotions {
+ if applied.State == "applied" && applied.Repo == subject.Repo && applied.Base == subject.Base &&
+ applied.PR == member.PR && applied.Head == member.Head && applied.TestedSHA == prefix.Commit {
+ for _, observed := range snapshot.Proofs {
+ if observed.Subject.ID == applied.SubjectID && observed.Subject.Policy == subject.Policy &&
+ observed.Subject.WorkflowTree == subject.WorkflowTree && len(observed.Subject.Members) == index+1 &&
+ observed.Subject.Prefixes[index] == prefix && observed.ObservedState == integration.Passed {
+ known = true
+ break
+ }
+ }
+ }
+ }
+ if !known {
+ return fmt.Errorf("prefix predecessor %d lacks exact documented applied/provenance lineage", member.PR)
+ }
+ pr, _, err := s.deps.GHClient.GoGitHub().PullRequests.Get(ctx, parts[0], parts[1], member.PR)
+ if err != nil {
+ return err
+ }
+ if !pr.GetMerged() || pr.GetMergeCommitSHA() != prefix.Commit {
+ return fmt.Errorf("prefix predecessor %d is not an actually merged exact known step", member.PR)
+ }
+ }
+ return nil
+}
+
+func (s *Server) executionPromotionGuard(ctx context.Context, store *integration.Store, cfg config.IntegrationExecutionConfig, scope config.IntegrationExecutionScope, protection string, proof integration.ExecutionProof, request ghpkg.IntegrationPromotion) error {
+ if err := s.executionLiveAuthority(ctx, cfg, scope, protection); err != nil {
+ return err
+ }
+ parts := strings.SplitN(scope.Repo, "/", 2)
+ repository, _, err := s.deps.GHClient.GoGitHub().Repositories.Get(ctx, parts[0], parts[1])
+ if err != nil {
+ return err
+ }
+ if !repository.GetAllowMergeCommit() {
+ return fmt.Errorf("repository disallows the exact tested merge-commit protocol; no squash/rebase substitution")
+ }
+ last := proof.Subject.Prefixes[len(proof.Subject.Prefixes)-1]
+ runs, err := s.deps.GHClient.ReadIntegrationExecutionCandidateRuns(ctx, scope.Repo, scope.CandidateWorkflowID, last.Commit)
+ if err != nil {
+ return err
+ }
+ if proof.Subject.Claim == nil {
+ return fmt.Errorf("candidate has no exact dispatch claim")
+ }
+ matches := executionRunsNamed(runs, "Integration "+proof.Subject.ID+" "+proof.Subject.Claim.Owner.Nonce)
+ if len(matches) != 1 || matches[0].GetID() != proof.RunID || matches[0].GetRunAttempt() != proof.Attempt {
+ return fmt.Errorf("exact candidate run/claim is absent, duplicated or superseded; no promotion")
+ }
+ refreshed, _, err := s.observeExecutionCandidate(ctx, store, scope, proof.Subject, proof.RunID, proof.Attempt, time.Now())
+ if err != nil {
+ return err
+ }
+ if !executionTechnicalPassed(refreshed) {
+ return fmt.Errorf("exact candidate/attempt no longer has trusted passed evidence")
+ }
+ if err := s.verifyExecutionPredecessors(ctx, store, proof.Subject); err != nil {
+ return err
+ }
+ base, err := s.executionDestination(ctx, scope.Repo, scope.Base)
+ if err != nil {
+ return err
+ }
+ if base != request.ExpectedSHA {
+ return fmt.Errorf("exact candidate predecessor moved")
+ }
+ s.integration.mu.Lock()
+ gate := s.integration.executionEvaluator
+ s.integration.mu.Unlock()
+ if gate == nil {
+ return fmt.Errorf("complete normal boot lane promotion evaluator unavailable")
+ }
+ member := proof.Subject.Members[len(proof.Subject.Members)-1]
+ if err := s.executionPromotionWork(store, proof.Subject, time.Now()); err != nil {
+ return err
+ }
+ evidence := automerge.IntegrationBaseEvidence{Repo: scope.Repo, Base: scope.Base, PR: member.PR,
+ Head: member.Head, ExpectedSHA: request.ExpectedSHA, TestedSHA: request.TestedSHA, SubjectID: proof.Subject.ID,
+ Verify: func(ctx context.Context) error {
+ current, err := s.executionDestination(ctx, scope.Repo, scope.Base)
+ if err != nil {
+ return err
+ }
+ if current != request.ExpectedSHA {
+ return fmt.Errorf("combined tested parent is not the actual current base")
+ }
+ live, exists := store.ExecutionProof(proof.Subject.ID, proof.RunID, proof.Attempt)
+ if !exists || !executionTechnicalPassed(live) || !live.Subject.SameCore(proof.Subject) {
+ return fmt.Errorf("combined immutable tested subject changed")
+ }
+ return nil
+ }}
+ current, reason, err := gate(automerge.WithIntegrationBaseEvidence(ctx, evidence), scope.Repo, scope.Base, member.PR, member.Head)
+ if err != nil {
+ return err
+ }
+ if current == nil {
+ return fmt.Errorf("normal live policy refused exact promotion: %s", reason)
+ }
+ if err := s.executionLiveAuthority(ctx, cfg, scope, protection); err != nil {
+ return err
+ }
+ // Review/hold/head observations invalidate eligibility, not the immutable
+ // technical payload. Restore only after this complete live evaluation.
+ revision := refreshed.EligibilityRevision
+ for _, invalidation := range store.ExecutionSnapshot().Invalidations {
+ if invalidation.Repo == scope.Repo && invalidation.Base == scope.Base && invalidation.Revision > revision {
+ revision = invalidation.Revision
+ }
+ }
+ refreshed.State, refreshed.EligibilityRevision, refreshed.ObservedAt = integration.Passed, revision, time.Now()
+ refreshed.InvalidatedBy, refreshed.Reason = "", "trusted exact candidate plus freshly revalidated complete normal lane/base/authority guards"
+ return store.AppendExecution(fmt.Sprintf("execution/revalidated/%s/%d", refreshed.Key(), refreshed.ObservedAt.UnixNano()),
+ refreshed.ObservedAt, integration.ExecutionEvent{Version: integration.ExecutionSchemaVersion, Proof: &refreshed})
+}
+
+func (s *Server) recordExecutionQualification(ctx context.Context, store *integration.Store, scope config.IntegrationExecutionScope, protection string, promotion integration.ExecutionPromotion, now time.Time) error {
+ if !promotion.ProviderAcknowledged {
+ return fmt.Errorf("isolated state was reconciled without a durable successful provider acknowledgement; actor compatibility unproven, new isolated probe required")
+ }
+ for _, qualified := range store.ExecutionSnapshot().Qualifications {
+ if qualified.ID == scope.QualificationID {
+ return nil
+ }
+ }
+ parts := strings.SplitN(scope.Repo, "/", 2)
+ pr, _, err := s.deps.GHClient.GoGitHub().PullRequests.Get(ctx, parts[0], parts[1], promotion.PR)
+ if err != nil {
+ return err
+ }
+ if !pr.GetMerged() || pr.GetMergeCommitSHA() != promotion.TestedSHA {
+ return fmt.Errorf("isolated protected CAS applied, but actual exact PR merge acknowledgement still pending; not production qualification")
+ }
+ current, qualified, err := s.integrationExecutionQualified(ctx, store, scope)
+ if err != nil {
+ return err
+ }
+ if !qualified || current != protection {
+ return fmt.Errorf("isolated/production protection profile changed after probe")
+ }
+ receipt := integration.ExecutionQualification{ID: scope.QualificationID, Repo: scope.Repo,
+ Base: scope.QualifiedBase, ProbeBase: scope.Base, ExecutorID: scope.ExecutorID,
+ AuthorityCommit: scope.AuthorityCommit, RequestActorID: scope.RequestActorID, Policy: scope.Policy,
+ WorkflowTree: scope.WorkflowTree, ProtectionDigest: protection, ProfileDigest: scope.ProviderProfileDigest(),
+ SubjectID: promotion.SubjectID, TestedSHA: promotion.TestedSHA, MutationKey: promotion.MutationKey, ObservedAt: now}
+ return store.AppendExecution("execution/qualification/"+receipt.ID, now,
+ integration.ExecutionEvent{Version: integration.ExecutionSchemaVersion, Qualification: &receipt})
+}
diff --git a/src/pkg/dashboard/integration_execution_repair.go b/src/pkg/dashboard/integration_execution_repair.go
new file mode 100644
index 0000000000..ded8f90651
--- /dev/null
+++ b/src/pkg/dashboard/integration_execution_repair.go
@@ -0,0 +1,62 @@
+package dashboard
+
+import (
+ "context"
+ "fmt"
+ "github.com/hivecommons/hive/pkg/github"
+ "sort"
+ "strings"
+ "time"
+)
+
+func (s *Server) executionFailureOwner(repo string, failure *github.WebhookCIFailure) (*github.CIFailurePR, *github.IntegrationFailureContext, string) {
+ cfg := s.integrationConfig().Execution.Effective()
+ store, err := s.integrationExecutionStore()
+ if err != nil {
+ return nil, nil, ""
+ }
+ proofs := store.ExecutionSnapshot().Proofs
+ sort.SliceStable(proofs, func(i, j int) bool { return proofs[i].ObservedAt.After(proofs[j].ObservedAt) })
+ now := time.Now()
+ for _, projection := range proofs {
+ subject := projection.Subject
+ scope, enrolled := cfg.Scope(repo, subject.Base)
+ if !enrolled || scope.Authority != "hive" || !strings.EqualFold(subject.Repo, repo) || len(subject.Prefixes) == 0 ||
+ subject.Prefixes[len(subject.Prefixes)-1].Commit != failure.HeadSHA || projection.ObservedAt.After(now) || now.Sub(projection.ObservedAt) > cfg.ObservationAge {
+ continue
+ }
+ proof, ok := store.ExecutionProof(subject.ID, projection.RunID, projection.Attempt)
+ if !ok || proof.Archive == nil {
+ continue
+ }
+ bound := failure.SuiteID > 0 && failure.SuiteID == proof.Archive.SuiteID
+ for _, id := range proof.Archive.CheckIDs {
+ bound = bound || failure.CheckRunID > 0 && failure.CheckRunID == id
+ }
+ if !bound {
+ continue
+ }
+ member := subject.Members[len(subject.Members)-1]
+ parts := strings.SplitN(repo, "/", 2)
+ if len(parts) != 2 {
+ return nil, nil, ""
+ }
+ ctx, cancel := context.WithTimeout(context.Background(), integrationReconcileTimeout)
+ pr, _, err := s.deps.GHClient.GoGitHub().PullRequests.Get(ctx, parts[0], parts[1], member.PR)
+ cancel()
+ if err != nil || pr.GetState() != "open" || pr.GetHead().GetSHA() != member.Head || pr.GetBase().GetRef() != subject.Base {
+ continue
+ }
+ evidence := &github.IntegrationFailureContext{CandidateID: subject.ID, TestedSHA: failure.HeadSHA,
+ TestedTree: subject.Prefixes[len(subject.Prefixes)-1].Tree, BaseSHA: subject.BaseSHA, Policy: subject.Policy,
+ Producer: fmt.Sprintf("%s#%d@%s", proof.Archive.WorkflowPath, proof.Archive.WorkflowID, proof.Archive.WorkflowSHA),
+ Attempt: proof.Attempt, RunID: proof.RunID, SuiteID: proof.Archive.SuiteID, Source: proof.Source}
+ for _, m := range subject.Members {
+ evidence.Members = append(evidence.Members, fmt.Sprintf("%d:%s", m.PR, m.Head))
+ }
+ ref := &github.CIFailurePR{Number: member.PR, Author: pr.GetUser().GetLogin(), Title: pr.GetTitle(), URL: pr.GetHTMLURL(), BaseRef: subject.Base,
+ HiveAuthored: s.deps.GHClient.IsHiveAuthorLogin(pr.GetUser().GetLogin())}
+ return ref, evidence, member.Head
+ }
+ return nil, nil, ""
+}
diff --git a/src/pkg/dashboard/integration_execution_tracker.go b/src/pkg/dashboard/integration_execution_tracker.go
new file mode 100644
index 0000000000..5e5a699394
--- /dev/null
+++ b/src/pkg/dashboard/integration_execution_tracker.go
@@ -0,0 +1,134 @@
+package dashboard
+
+import (
+ "github.com/hivecommons/hive/pkg/config"
+ "github.com/hivecommons/hive/pkg/convergence/integration"
+ "github.com/hivecommons/hive/pkg/forgestate"
+ "sort"
+ "time"
+)
+
+type IntegrationExecutionTracker struct {
+ Version int `json:"version"`
+ Mode string `json:"mode"`
+ RuntimeVersion string `json:"runtime_version"`
+ SourceVersion string `json:"source_version"`
+ PublishedImage string `json:"published_image"`
+ ObservedAt time.Time `json:"observed_at"`
+ ObservationAgeSeconds float64 `json:"observation_age_seconds"`
+ Telemetry integration.Cost `json:"telemetry"`
+ Statuses []integration.ExecutionStatus `json:"statuses"`
+ Candidates []IntegrationExecutionTrackerCandidate `json:"candidates"`
+}
+
+type IntegrationExecutionTrackerCandidate struct {
+ Kind string `json:"kind"`
+ SubjectID string `json:"subject_id"`
+ Repo string `json:"repo"`
+ Base string `json:"base"`
+ BaseSHA string `json:"base_sha"`
+ Members []forgestate.IntegrationCandidateMember `json:"members"`
+ TestedCommit string `json:"tested_commit,omitempty"`
+ TestedTree string `json:"tested_tree,omitempty"`
+ State integration.State `json:"state"`
+ RunID int64 `json:"run_id,omitempty"`
+ Attempt int `json:"attempt"`
+ Reason string `json:"reason"`
+ ObservedAt time.Time `json:"observed_at"`
+}
+
+func (s *Server) refreshExecutionTracker(store *integration.Store, cfg config.IntegrationExecutionConfig, now time.Time) {
+ snapshot := store.ExecutionSnapshot()
+ view := &IntegrationExecutionTracker{Version: integration.ExecutionSchemaVersion, Mode: cfg.Effective().Mode,
+ RuntimeVersion: versionHash, SourceVersion: "unknown", PublishedImage: "unknown", ObservedAt: now,
+ ObservationAgeSeconds: cfg.ObservationAge.Seconds(),
+ Telemetry: s.integrationExecutionCost(cfg, store, now),
+ Candidates: []IntegrationExecutionTrackerCandidate{}}
+ for _, status := range snapshot.Statuses {
+ if _, enrolled := cfg.Scope(status.Repo, status.Base); enrolled {
+ view.Statuses = append(view.Statuses, status)
+ }
+ }
+ latest := map[string]integration.ExecutionProof{}
+ for _, proof := range snapshot.Proofs {
+ scope, enrolled := cfg.Scope(proof.Subject.Repo, proof.Subject.Base)
+ if !enrolled || scope.Authority != "hive" || scope.Policy != proof.Subject.Policy || scope.WorkflowTree != proof.Subject.WorkflowTree {
+ continue
+ }
+ old, exists := latest[proof.Subject.ID]
+ if !exists || proof.Attempt > old.Attempt || proof.Attempt == old.Attempt && proof.ObservedAt.After(old.ObservedAt) {
+ latest[proof.Subject.ID] = proof
+ }
+ }
+ for _, proof := range latest {
+ subject := proof.Subject
+ last := subject.Prefixes[len(subject.Prefixes)-1]
+ view.Candidates = append(view.Candidates, IntegrationExecutionTrackerCandidate{
+ Kind: "candidate", SubjectID: subject.ID, Repo: subject.Repo, Base: subject.Base,
+ BaseSHA: subject.BaseSHA, Members: subject.Members, TestedCommit: last.Commit, TestedTree: last.Tree,
+ State: proof.State, RunID: proof.RunID, Attempt: proof.Attempt, Reason: proof.Reason, ObservedAt: proof.ObservedAt})
+ }
+ for _, plan := range snapshot.Plans {
+ scope, enrolled := cfg.Scope(plan.Recipe.Repo, plan.Recipe.Base)
+ if !enrolled || scope.Authority != "hive" || scope.Policy != plan.Recipe.Policy || scope.WorkflowTree != plan.Recipe.WorkflowTree || len(plan.Prepared) > 0 {
+ continue
+ }
+ view.Candidates = append(view.Candidates, IntegrationExecutionTrackerCandidate{
+ Kind: "preparation", SubjectID: plan.Recipe.ID(), Repo: plan.Recipe.Repo, Base: plan.Recipe.Base,
+ BaseSHA: plan.Recipe.BaseSHA, Members: plan.Recipe.Members, State: plan.State,
+ RunID: plan.MaterializerRunID, Attempt: plan.Attempt, Reason: plan.Reason, ObservedAt: plan.ObservedAt})
+ }
+ rank := func(state integration.State) int {
+ if state == integration.Unknown || state == integration.Waiting || state == integration.Running {
+ return 0
+ }
+ if state == integration.Passed {
+ return 1
+ }
+ return 2
+ }
+ sort.SliceStable(view.Candidates, func(i, j int) bool {
+ a, b := view.Candidates[i], view.Candidates[j]
+ if rank(a.State) != rank(b.State) {
+ return rank(a.State) < rank(b.State)
+ }
+ if !a.ObservedAt.Equal(b.ObservedAt) {
+ return a.ObservedAt.After(b.ObservedAt)
+ }
+ return a.SubjectID < b.SubjectID
+ })
+ if len(view.Candidates) > config.MaxIntegrationExecutionCandidates {
+ view.Candidates = view.Candidates[:config.MaxIntegrationExecutionCandidates]
+ }
+ s.integration.mu.Lock()
+ s.integration.executionTracker = view
+ s.integration.executionTrackerConfig = cfg
+ s.integration.mu.Unlock()
+}
+
+func (s *Server) stageTrackerIntegrationExecution() *IntegrationExecutionTracker {
+ cfg := s.integrationConfig().Execution.Effective()
+ if cfg.Mode == config.IntegrationOff {
+ return nil
+ }
+ s.integration.mu.Lock()
+ defer s.integration.mu.Unlock()
+ if s.integration.executionTracker != nil && executionConfigEqual(cfg, s.integration.executionTrackerConfig) {
+ view := *s.integration.executionTracker
+ view.Statuses = append([]integration.ExecutionStatus(nil), view.Statuses...)
+ view.Candidates = append([]IntegrationExecutionTrackerCandidate(nil), view.Candidates...)
+ for index := range view.Candidates {
+ view.Candidates[index].Members = append([]forgestate.IntegrationCandidateMember(nil), view.Candidates[index].Members...)
+ }
+ if view.Telemetry.RunnerMinutes != nil {
+ minutes := *view.Telemetry.RunnerMinutes
+ view.Telemetry.RunnerMinutes = &minutes
+ }
+ return &view
+ }
+ return &IntegrationExecutionTracker{Version: integration.ExecutionSchemaVersion, Mode: cfg.Mode,
+ RuntimeVersion: versionHash, SourceVersion: "unknown", PublishedImage: "unknown",
+ ObservationAgeSeconds: cfg.ObservationAge.Seconds(),
+ Telemetry: integration.Cost{Reason: "runtime cohort not yet observed; unknown is not zero"},
+ Candidates: []IntegrationExecutionTrackerCandidate{}}
+}
diff --git a/src/pkg/dashboard/integration_execution_ui_test.go b/src/pkg/dashboard/integration_execution_ui_test.go
new file mode 100644
index 0000000000..57f7ffc1f9
--- /dev/null
+++ b/src/pkg/dashboard/integration_execution_ui_test.go
@@ -0,0 +1,63 @@
+package dashboard
+
+import (
+ "os"
+ "os/exec"
+ "strings"
+ "testing"
+)
+
+func TestIntegrationExecutionCaptionPreservesExactRowsAndOff(t *testing.T) {
+ node, err := exec.LookPath("node")
+ if err != nil {
+ t.Skip("node unavailable")
+ }
+ source, err := os.ReadFile("static-src/js/tracker-integration-execution.js")
+ if err != nil {
+ t.Fatal(err)
+ }
+ script := `
+const assert = require('node:assert/strict');
+function esc(value){return String(value).replaceAll('&','&').replaceAll('<','<').replaceAll('"','"');}
+` + string(source) + `
+const now=Date.parse('2026-10-31T04:00:00Z');
+const item={kind:'pr',repo:'o/r',number:2,head:'bbb',base_ref:'v5',stage:60};
+const original=JSON.stringify(item);
+const candidate={kind:'candidate',repo:'o/r',base:'v5',subject_id:'subject',state:'passed',observed_at:new Date(now).toISOString(),members:[{pr:1,head:'aaa'},{pr:2,head:'bbb'}],tested_commit:'exact'};
+const data={integration_execution:{mode:'enforce',observed_at:new Date(now).toISOString(),observation_age_seconds:60,candidates:[candidate]}};
+stageTrackerExecutionSync(null,now);
+assert.equal(stageTrackerExecutionHtml(item),'');
+stageTrackerExecutionSync(data,now);
+assert.match(stageTrackerExecutionHtml(item),/Integration CI passed/);
+assert.match(stageTrackerExecutionHtml(item),/live merge guards still required/);
+assert.equal(stageTrackerExecutionHtml({...item,number:1,head:'aaa'}),'','AB proof must not become A proof');
+assert.equal(stageTrackerExecutionHtml({...item,head:'changed'}),'');
+assert.equal(stageTrackerExecutionHtml({...item,base_ref:'other'}),'');
+assert.equal(stageTrackerExecutionHtml({...item,base_ref:''}),'','unknown scope must not borrow a prefix receipt');
+assert.equal(stageTrackerExecutionHtml({...item,kind:'issue'}),'');
+assert.equal(JSON.stringify(item),original,'caption must not alter row/stage/order/filter facts');
+stageTrackerExecutionSync(data,now+61000);
+assert.match(stageTrackerExecutionHtml(item),/unknown \(stale observation\)/);
+stageTrackerExecutionSync({integration_execution:{...data.integration_execution,mode:'advisory'}},now);
+assert.match(stageTrackerExecutionHtml(item),/advisory, no writer/);
+stageTrackerExecutionSync({integration_execution:{...data.integration_execution,mode:'off'}},now);
+assert.equal(stageTrackerExecutionHtml(item),'');
+candidate.reason='';
+stageTrackerExecutionSync(data,now);
+assert.ok(!stageTrackerExecutionHtml(item).includes('