Fleet controller lifecycle contract
Status: WP1 deliverable for plan.md. This records the current (pre-WP2+) behavior of the three attempt implementations described in plan.md §1, as a single reference with an owning regression test per fact. It changes no behavior. Every test name below was verified to exist with go test -list '.*' ./handler ./store ./etcdstore . | grep -i fleet (or, for the four names this WP adds, a direct go test -list match) on v2/api at the branch head. "None" in the test column is itself a finding: it means the audit found no regression pinning that fact, not that the fact is false.
1. Routes × backend
Paths are /api/v1/fleet/... unless noted. "PG" is the live legacy path (plan.md §1.1); PG V3 (fleet.RunnerAttempt, handler/fleet_attempts.go) is unrouted and out of scope for this table except where named explicitly. Fleet-adjacent routes outside plan.md §1.2's /api/v1/fleet/... scope are not listed: etcd GET/PUT /api/v1/apps/{id}/fleet-target (etcd_fleet_runtime.go:145,150) and the PG authority-only /api/v1/apps/{id}/external-deployments/{begin,resume,admit} (main.go:2173-2175).
| Route | Backend | Handler | Store/aggregate | Credential boundary | Owning regression test |
|---|---|---|---|---|---|
POST validate | PG | ValidateFleetDocument | none (pure parse) | none (unauthenticated-safe; controlScopeForRequest maps it to api:read) | TestValidateFleetDocumentReturnsTypedInvalidReport |
POST validate | etcd | absent | — | — | none — absence is structural (no registration in etcd_fleet_runtime.go:144-176); no test requests this path on etcd |
GET github | PG | FleetGitHubStatus | githubapp.Client.Status | api:read | none — thin coverage; only reachable indirectly through TestFleetAuthorityOnlySecurityConfigurationAndRouterAllowlist's allowlist check, which does not call this path |
GET github | etcd | absent | — | — | none — absence is structural (no registration in etcd_fleet_runtime.go:144-176); no test requests this path on etcd |
GET node-pools | PG | FleetInventory | loadFleetInventory (filesystem) | api:read | TestFleetInventoryRequiresReadScopeAndRedactsConfigPath |
GET node-pools | etcd | etcdFleetInventory | same | api:read | TestEtcdFleetCapabilitiesIncludeNativeFleetFields (capability only); no direct route test |
POST node-pools/{pool}/plan | PG | PlanFleetCapacity | signed op fleet.capacity-plan | api:write | TestFleetCapacityPlanHTTPUsesSignedAcceptanceBeforeInventory |
POST node-pools/{pool}/plan | etcd | etcdFleetPlan | same op kind, V3OperationStore.Accept | api:write | TestEtcdFleetRuntimeProcess (full-process HTTP exercise) |
GET plans | PG | ListFleetPlans | ListOperations(kind=fleet.capacity-plan) | api:read | none — the route is only asserted to be registered (not 404) by TestFleetAuthorityOnlySecurityConfigurationAndRouterAllowlist; no test checks its response |
GET plans | etcd | etcdFleetPlans | same | api:read | TestEtcdFleetRuntimeProcess |
GET plans/{id}/reconciliations | PG | ListFleetReconciliations | ListOperations(kind=fleet.reconciliation,ref=plan) | api:read, or fleet:operate CI bound to attemptId (fleetRunnerReconciliationReadNeedsAttemptID) | TestFleetRunnerReconciliationReadRequiresBoundAttemptAndFiltersRecords |
POST plans/{id}/reconciliations | PG | RecordFleetReconciliation | signed op fleet.reconciliation, typed FleetReconciliationAdmission | fleet:operate + bound GitHub Actions identity (requireFleetOperateScope) | TestFleetReconciliationHTTPUsesTypedAtomicAcceptance, TestFleetWorkloadEvidenceRequiresActiveCurrentAttemptLease |
GET/POST plans/{id}/reconciliations | etcd | fleetRunner.ListReconciliations / .Reconcile → acceptFleetReconciliation | /v3/fleet-reconciliations/<plan>/<op> | fleet:operate | TestV3FleetReconciliationAcceptanceReplayAndPhaseEvidenceEtcd, TestV3FleetReconciliationRefusesWrongAttemptPhaseAndEvidenceEtcd |
GET/POST plans/{id}/attempts[...] | PG (legacy) | handler/fleet_runner.go: ListFleetRunnerAttempts, StartFleetRunnerAttempt, GetFleetRunnerAttempt, HeartbeatFleetRunnerAttempt, AdvanceFleetRunnerAttempt, CancelFleetRunnerAttempt | store/fleet_runner_attempts.go (plan.md §1.1) | fleet:operate + exact bound GitHub Actions run (fleetRunnerPrincipalOwnsAttempt) | TestFleetRunnerAttemptHTTPUsesCompoundSignedAcceptance, TestFleetRunnerStartRequiresExactDispatchAndOIDCProvenance, TestFleetRunnerMutationRequiresBoundCurrentGitHubRun, TestFleetRunnerAttemptLifecycle (store), TestFleetRunnerHeartbeatReplaySameSequence (new, D12) |
GET/POST plans/{id}/attempts[...] | etcd | handler.EtcdFleetRunnerHandler (fleet_etcd_attempts.go) | etcdstore/v3_fleet_runner_attempt.go | fleet:operate, scope per route via etcdManagedTokenAuth | TestEtcdFleetRunnerHTTPAdmissionAndEvidenceGate, TestV3FleetRunnerAttemptAcceptanceReplayAndRevisionCASEtcd, TestV3FleetRunnerAttemptAllowsOneVerifiedRecoverySuccessorEtcd |
POST plans/{id}/github/pull-request | PG | CreateFleetGitHubPullRequest | signed op fleet.github.pull-request | api:write-equivalent via requireFleetGitHubPlan | TestFleetGitHubReceiptUsesSignedAtomicAcceptance |
POST plans/{id}/github/pull-request | etcd | etcdFleetGitHubPullRequest | /v3/operations via AcceptFleetGitHubPullRequest-style aggregate | same | TestV3FleetGitHubPullRequestReservationAcceptsAndReplaysEtcd, TestEtcdFleetGitHubPullRequestProcess |
POST plans/{id}/github/dispatch | PG | DispatchFleetGitHubApply | MarkFleetGitHubDispatchSubmitting, FinishFleetGitHubDispatch (store/fleet_github_dispatches.go) | same | TestDispatchPreSubmitFailureLeavesSubmitting (new; pins only the §1.6 defect branch) — no test exercises the happy path through this handler |
POST plans/{id}/github/dispatch | etcd | etcdFleetGitHubDispatch → acceptEtcdFleetGitHubDispatch | /v3/fleet-github-dispatch-preparations, /v3/fleet-runner-dispatches | same | TestEtcdFleetGitHubDispatchProcess, TestV3FleetGitHubDispatchPreparationPersistsOpaqueNonceBeforeBindingEtcd, TestV3FleetGitHubDispatchPreparationRetainsRawNonceEtcd (new, D10) |
POST plans/{id}/github/{prepare,prepare/reset,execute,rerun} | PG, external-Mac lane only | PrepareFleetGitHubApply, ResetFleetGitHubPreparation, ExecuteFleetGitHubApply, RerunFleetGitHubApply | store/fleet_github_dispatches.go (approval_envelope_sha256<>'' gate on rerun, store/fleet_github_dispatches.go:88) | same, plus owner-signed approval envelope | TestFleetGitHubDispatchRerunGenerationsAndPreparedResetAreFenced, TestFinishFleetGitHubDispatchIsImmutableOrIdentical — both at the store layer; no HTTP-level test drives these four handlers |
POST plans/{id}/github/{prepare,...} | etcd | absent | — | — | none — absence is structural (no registration in etcd_fleet_runtime.go:144-176); no test requests this path on etcd |
POST plans/{id}/github/reconcile | PG, general router only (absent from authority-only allowlist, plan.md §1.2) | ReconcileFleetGitHubReservation | resolveFleetGitHubOperation / finishFleetGitHubReservation | same | TestFleetGitHubVerifiedNoWriteCompletionIsIdempotent (route, handler/fleet_github_acceptance_integration_test.go); TestReconcileAbandonedPlanIsConflictNotServerError (abandoned plan → 409 fleet_target_holder_abandoned, handler/fleet_github_presubmit_test.go) |
POST plans/{id}/github/reconcile | etcd | absent | — | — | none — absence is structural (no registration in etcd_fleet_runtime.go:144-176); no test requests this path on etcd |
Re-checked 2026-10-04 with go test -list '.*' from v2/api (., ./handler, ./store, ./etcdstore) after WP2-WP14 landed: no test was added for any of the rows above that name "none". The owning-test column is "none" for POST validate (etcd), GET github (PG and etcd), GET plans (PG), POST plans/{id}/github/{prepare,...} (etcd) and POST plans/{id}/github/reconcile (etcd). These remain findings, not claims that the behavior is correct.
1b. Phases, approval rule and error codes (plan.md §1, WP1)
This table adds the three facts §1's table has no room for: which phases a route can read or advance, the exact authorization/signed-acceptance chain (not just the credential boundary's scope name), and every HTTP status/error-code pair the route can return. It is keyed to the same rows as §1, in the same order. It changes no behavior and does not touch §1's owning-test citations.
No environment-reviewer or independent-review gate exists anywhere in this surface (proposal.md §1.5, "Not enforced"; confirmed by grep -rln 'reviewer\|RequiredReviewer\|EnvironmentProtection' handler/ store/ etcdstore/ excluding tests, which returns no files). No per-row note repeats this.
Shared baselines, cited by letter instead of repeating per row:
- A — authentication/scope, every route. PG: 401
authenticated_principal_required, 403insufficient_scope(requireControlScope,handler/handler.go:301-312;requireFleetOperateScope,handler/handler.go:317-328). etcd: 401unauthorized, 403insufficient_scope(etcdManagedTokenAuth,etcd_source_validation.go:148-168). - B —
requireFleetGitHubPlan, every PGgithub/*route. 503fleet_github_not_configured(handler/fleet_github.go:979), 503fleet_plan_store_unavailable(:983), 400invalid_fleet_plan_id(:991), 404fleet_plan_not_found(:996), 500fleet_plan_read_failed(:1000). Requires scopeapi:write(:974). - C — signed-acceptance surface, every route that queues through
h.pipeline/writeOperationAcceptanceError. 410idempotency_window_expired, 409idempotency_key_reused, 409legacy_idempotency_ambiguous, 409operation_admission_rejected, 503operation_acceptance_indeterminate, 503operation_acceptance_unavailable, 500operation_acceptance_failed, 503snapshot_execution_unavailable, 503evidence_reserve_exhausted(handler/control_protocol.go:174-227). Two further error families are reachable only from this surface when the queued operation kind isfleet.runner-attemptorfleet.reconciliation(store.FleetRunnerAttemptAdmissionError/store.FleetReconciliationAdmissionError,control_protocol.go:185-201); they are listed under the attempts/reconciliations rows below, never under capacity-plan/pull-request/dispatch/rerun, whose operation kinds cannot produce them.
| Route | Backend | Phases | Approval rule | Error codes |
|---|---|---|---|---|
POST validate | PG | None — pure parse/validate; no attempt or reconciliation phase is read or written. | Router-level only: controlScopeForRequest maps this exact path to api:read (main.go:1836), enforced by the global auth middleware before ValidateFleetDocument runs; the handler (handler/fleet.go:43) makes no further scope or signed-acceptance check. | Baseline A (from the router middleware) + 400 invalid_validation_request (:46), 400 validation_document_required (:50), 400 validation_document_too_large (:54). |
POST validate | etcd | — | — | — |
GET github | PG | None. | In-handler requireControlScope(w, r, ScopeAPIRead) (handler/fleet_github.go:30). No signed acceptance — pure read of cached GitHub App status. | Baseline A. h.fleetGitHubConfigError/h.fleetGitHub==nil are reported as 200-OK status payloads (:34-41), not error codes. |
GET github | etcd | — | — | — |
GET node-pools | PG | None. | In-handler requireControlScope(w, r, ScopeAPIRead) (handler/fleet.go:105). | Baseline A + 500 fleet_config_read_failed (:110). |
GET node-pools | etcd | None. | Router middleware etcdManagedTokenAuth(cfg, identities, ScopeAPIRead) (etcd_fleet_runtime.go:141,144) — scope is checked before the handler runs, not inside it. | Baseline A + 503 fleet_config_read_failed (etcd_fleet_runtime.go:319). Note: PG returns 500 for the identical failure; etcd returns 503 — a genuine cross-backend status discrepancy, not just presentation. |
POST node-pools/{pool}/plan | PG | None — a capacity plan is a standalone fleet.capacity-plan operation with no phase field; it precedes any attempt. | In-handler requireControlScope(w, r, ScopeAPIWrite) (handler/fleet.go:147). Signed acceptance: yes — queued as a signed model.Operation via h.pipeline.QueueOperation, replay-checked through resolveFleetCapacityPlanReplay/ResolveEnqueue (:190,250-266). | Baseline A, C + 400 invalid_fleet_plan_request (×4: :157,161,167,174,181), 503 fleet_plan_store_unavailable (:152), 503 fleet_config_read_failed (:200), 409 fleet_not_configured (:204), 409 fleet_config_invalid (:208), 404 fleet_node_pool_not_found (:213), 400 fleet_plan_unsafe (:222). The kind is fleet.capacity-plan, so neither of C's two admission-error families is reachable here. |
POST node-pools/{pool}/plan | etcd | None. | Router/in-handler mix: non-GET requires a non-CI managed api:write principal — principal.CI != nil is explicitly rejected (etcd_fleet_runtime.go:435-438). Idempotency-Key-based signed acceptance via store.OperationAcceptance/operations.Accept (:505-512). | Baseline A-equivalent (401 unauthorized/403 insufficient_scope, :432,436) + 400 invalid_fleet_plan_request (:422,443,448), 400 invalid_idempotency_key (:427), 409 idempotency_key_reused (:462), 503 fleet_config_read_failed (:475), 409 fleet_not_configured (:479), 404 fleet_node_pool_not_found (:484), 400 fleet_plan_unsafe (:489), 500 fleet_plan_signing_failed (:498), 503 authority_unavailable (:453), 500 operation_acceptance_failed (:510, fingerprint failure); plus writeEtcdFleetAcceptanceError (:554-567): 410 operation_replay_expired (:556), 409 idempotency_key_reused (:560), 503 operation_acceptance_indeterminate (:564), 503 operation_acceptance_failed (:567, default). |
GET plans | PG | None. | In-handler requireControlScope(w, r, ScopeAPIRead) (handler/fleet.go:269). | Baseline A + 503 fleet_plan_store_unavailable (:273), 500 fleet_plan_read_failed (:279). |
GET plans | etcd | None. | Router middleware etcdManagedTokenAuth(cfg, identities, ScopeAPIRead) (etcd_fleet_runtime.go:141,153). | Baseline A + 503 fleet_plan_read_failed (etcd_fleet_runtime.go:355). |
GET plans/{id}/reconciliations | PG | Read-only. Returns stored fleet.reconciliation checkpoints (each carries the phase it attests); no transition. | requireFleetReadScope = api:read or fleet:operate (handler/fleet.go:292, handler/fleet_attempts.go:349-353). A principal that lacks api:read (i.e. a bound fleet:operate runner) is additionally required to supply attemptId and must own that attempt via fleetRunnerPrincipalOwnsAttempt (fleetRunnerReconciliationReadNeedsAttemptID, handler/fleet.go:319-341,369-371); an api:read principal reads unfiltered. | Baseline A + 503 fleet_reconciliation_store_unavailable (:296), 400 invalid_fleet_plan_id (:301), 404 fleet_plan_not_found (:306), 500 fleet_plan_read_failed (:311), 403 fleet_plan_read_forbidden (:314), 403 fleet_runner_attempt_binding_conflict (:321,340), 400 invalid_fleet_runner_attempt_id (:325), 404 fleet_runner_attempt_not_found (:330), 500 fleet_runner_attempt_read_failed (:334), 500 fleet_reconciliation_read_failed (:344). |
POST plans/{id}/reconciliations | PG | Reads attempt.CurrentPhase (when AttemptID is given) and requires request.Phase == attempt.CurrentPhase (handler/fleet.go:468; store-side re-check store/fleet_reconciliation_acceptance.go:134). Ordering is enforced against the 9-phase canonical predecessor chain (ValidateFleetReconciliationAdmissionTransition, store/fleet_reconciliation_acceptance.go:191-233) even for PG-legacy non-drain attempts, which carve out infrastructure_applied as a valid first phase with no predecessor (:220-229) to match the 6-phase legacy start (D3/D4). | requireFleetOperateScope = exact fleet:operate (handler/fleet.go:379, handler/handler.go:317-328). Signed acceptance is mandatory: store.FleetReconciliationAdmission{RequireActiveAttempt:true,...} (:455-459) is enforced inside the PG transaction by enforceFleetReconciliationAdmission, which takes pg_advisory_xact_lock(hashtextextended('norn:fleet-attempt:'+planID)) then FOR UPDATEs the attempt row (store/fleet_reconciliation_acceptance.go:84-140). | Baseline A, C + 503 fleet_reconciliation_store_unavailable (handler/fleet.go:386), 400 invalid_fleet_plan_id (:384), 404 fleet_plan_not_found (:389), 500 fleet_plan_read_failed (:393), 403 fleet_plan_read_forbidden (:397), 409 fleet_plan_invalid (:402), 400 invalid_fleet_reconciliation (:407,412), 400 invalid_idempotency_key (:417), 404 fleet_runner_attempt_not_found (:428), 500 fleet_runner_attempt_read_failed (:432), 409/403 fleet_runner_attempt_binding_conflict (:436,440,469), 503 operation_acceptance_unavailable (:446); plus the FleetReconciliationAdmissionError family (mapped 409, or 403 for identity mismatch, control_protocol.go:194-201): fleet_plan_not_found, fleet_plan_invalid, fleet_reconciliation_attempt_not_found, fleet_reconciliation_attempt_binding_mismatch, fleet_reconciliation_attempt_not_current, fleet_reconciliation_identity_mismatch(→403), fleet_reconciliation_attempt_required, fleet_reconciliation_out_of_order (store/fleet_reconciliation_acceptance.go:97-148). |
GET/POST plans/{id}/reconciliations | etcd | ListReconciliations: read-only. Reconcile: reads item.CurrentPhase implicitly via the same FleetReconciliationAdmission{RequireActiveAttempt:true} struct, enforced by the etcd equivalent admission check before the op is queued (handler/fleet_etcd_attempts.go:418). | Stricter than PG on reads: there is no generic api:read path. Every read or write requires a bound fleet:operate CI workload token whose intent-derived binding matches this exact plan — apply intent must match the live dispatch binding's RunID/ApprovedHeadSHA, recover intent must match an existing attempt's identity (readablePlan, handler/fleet_etcd_attempts.go:269-295, used by both List/Get/ListReconciliations). Reconcile additionally requires the named AttemptID to resolve and match the caller's identity (:407-411) before queuing signed acceptance. | Baseline A + 503 fleet_runner_attempt_store_unavailable (:49/shared plan() helper), 400 invalid_fleet_plan_id (:54), 404 fleet_plan_not_found (:59), 503 fleet_plan_read_failed (:63), 409 fleet_plan_invalid (:68), 403 fleet_runner_oidc_required (:78), 403 fleet_plan_read_forbidden (:293), 503 fleet_reconciliation_read_failed (:468); Reconcile additionally: 400 invalid_fleet_reconciliation (:399,404), 403 fleet_runner_attempt_identity_mismatch (:409), 400 invalid_idempotency_key (:415), 409 idempotency_key_reused (:421), plus baseline C and the FleetReconciliationAdmissionError family (same codes as the PG row). |
GET/POST plans/{id}/attempts[...] | PG (legacy) | See §1c — six sub-operations (List/Get/Start/Heartbeat/Advance/Cancel), each with distinct phase behavior. | See §1c. | See §1c. |
GET/POST plans/{id}/attempts[...] | etcd | See §1c. | See §1c. | See §1c. |
POST plans/{id}/github/pull-request | PG | None — phase-independent; operates on the fleet.github.pull-request reservation/receipt, not the 9-phase list. | Baseline B (api:write) + requireMatchingFleetEnvironment (handler/fleet_github.go:55,914-933). Signed acceptance: yes, via ensureFleetGitHubReservation/finishFleetGitHubReservation (queued fleet.github.pull-request operation). | Baseline A, B, C + 409 fleet_plan_invalid (:52), 409 fleet_github_pull_request_in_progress (:71), 500 fleet_github_receipt_failed (:95,103,111,125), 409 fleet_github_plan_stale (:98), 409 fleet_github_pull_request_refused (:106,114), 502 fleet_github_pull_request_failed (:118), plus fleet_config_read_failed/fleet_config_invalid/fleet_environment_mismatch from requireMatchingFleetEnvironment (:917,922,930). |
POST plans/{id}/github/pull-request | etcd | None. | Non-CI managed api:write principal (principal.CI != nil rejected, etcd_fleet_github_pull_request.go:41-44) — no requireFleetGitHubPlan-equivalent scope widening. Signed acceptance via acceptEtcdFleetGitHubPullRequest (:157-173). | Baseline A-equivalent + 503 fleet_github_not_configured (:37), 400 invalid_fleet_plan_id (:47), 404 fleet_plan_not_found (:52), 409 fleet_plan_invalid (:56,62), 503 operation_acceptance_indeterminate (:74), 409 fleet_github_pull_request_reservation_unavailable (:77), 503 fleet_github_receipt_failed (:81,86,92), 409 fleet_github_pull_request_terminal (:101), 502 fleet_github_pull_request_unproven (:106,111,129,134), 500 fleet_github_receipt_failed (:115,138,143). |
POST plans/{id}/github/dispatch | PG | None — phase-independent; operates on the fleet_github_dispatches state machine (prepared→submitting→dispatched), not the 9-phase list. | Baseline B + externalMacFleetDispatch(h.cfg) must be false (this route refuses the external-Mac lane, :727-730) + requireMatchingFleetEnvironment. Signed acceptance via ensureFleetGitHubReservation for fleet.github.apply-dispatch (:850). | Baseline A, B, C + 409 fleet_github_prepare_required (:728), 400 invalid_fleet_github_dispatch (:733), 409 fleet_plan_invalid (:738), 409 fleet_github_destructive_ack_required (:743), 409 fleet_github_dispatch_binding_mismatch (:763,821), 500 fleet_github_receipt_failed (:759,785,805,813,817,840,874,895), 409 fleet_github_dispatch_in_progress (:774,858), 409 fleet_github_dispatch_ambiguous (:836,847), 409 fleet_github_plan_not_ready (:794,863), 502 fleet_github_dispatch_failed (:798,870). This route also contains the pre-existing §5 defect: ErrDispatchPreSubmit (:867) calls a delete that is a no-op against the row it just fenced, leaving it submitting. |
POST plans/{id}/github/dispatch | etcd | None. | Non-CI managed api:write principal (etcd_fleet_github_dispatch.go:48). Signed acceptance via acceptEtcdFleetGitHubDispatch (:179-193). | Baseline A-equivalent + 503 fleet_github_not_configured (:44), 400 invalid_fleet_plan_id (:54), 400 invalid_fleet_github_dispatch (:61,66), 404 fleet_plan_not_found (:71), 409 fleet_plan_invalid (:75,81), 409 fleet_github_destructive_ack_required (:86), 503 fleet_github_not_configured (:91, config env), 503 fleet_github_dispatch_preparation_unavailable (:97,132), 409 fleet_github_dispatch_binding_mismatch (:101,136), 503 fleet_github_receipt_failed (:105,109,150), 503 fleet_github_dispatch_unavailable (:115), 502 fleet_github_plan_unproven (:122), 503 operation_acceptance_indeterminate (:129), 502 fleet_github_dispatch_unproven (:146). |
POST plans/{id}/github/{prepare,prepare/reset,execute,rerun} | PG, external-Mac lane only | None — phase-independent; same dispatch state machine as above, plus rerun_submitting. | Baseline B + externalMacFleetDispatch(h.cfg) must be true for all four (:326,404,449,580). Execute and Rerun additionally require an owner-signed approval envelope digest: Execute binds ApprovalEnvelopeSHA256 on first use and compares it by constant-time equality thereafter (:502-511); Rerun requires that digest to already be bound and match (:619). Reset requires explicit caller acknowledgement confirmLostNonce:true (:409-411) and only touches a provably pre-submit, unapproved row (:433). This is caller-supplied evidence, not a server-side reviewer step. | Baseline A, B. Prepare: 409 fleet_github_prepare_not_required(:327), 400 invalid_fleet_github_dispatch(:332), 409 fleet_plan_invalid(:337), 409 fleet_github_destructive_ack_required(:342), 409 fleet_github_dispatch_in_progress(:351), 409 fleet_github_dispatch_binding_mismatch(:359), 500 fleet_github_receipt_failed(:369,383,388), 409 fleet_github_plan_not_ready(:374), 502 fleet_github_dispatch_failed(:378). Reset: 409 fleet_github_prepare_not_required(:405), 400 invalid_fleet_github_dispatch(:410), 409 fleet_github_dispatch_in_progress(:419), 500 fleet_github_receipt_failed(:430,438), 409 fleet_github_dispatch_ambiguous(:434); success is 204 with no body. Execute (+ baseline C via ensureFleetGitHubReservation at :541): 409 fleet_github_prepare_not_required(:450), 400 invalid_fleet_github_dispatch(:455,459), 409 fleet_plan_invalid(:464), 409 fleet_github_destructive_ack_required(:469), 409 fleet_github_dispatch_in_progress(:478), 409 fleet_github_prepare_required(:485), 409 fleet_github_dispatch_binding_mismatch(:493,499,505,509,516), 409 fleet_github_dispatch_ambiguous(:527,538), 500 fleet_github_receipt_failed(:489,531,556,564), 502 fleet_github_dispatch_failed(:560). Rerun (+ baseline C via ensureFleetGitHubReservation at :662): 409 fleet_github_rerun_not_allowed(:581,612,639,651,656), 400 invalid_fleet_github_dispatch(:586), 409 fleet_plan_invalid(:591), 409 fleet_github_destructive_ack_required(:596), 409 fleet_github_dispatch_in_progress(:605,670), 409 fleet_github_dispatch_binding_mismatch(:620), 409 fleet_github_dispatch_ambiguous(:627,677), 500 fleet_github_receipt_failed(:616,632,682), 500 fleet_runner_attempt_read_failed(:647), 502 fleet_github_dispatch_failed(:659). |
POST plans/{id}/github/{prepare,...} | etcd | — | — | — |
POST plans/{id}/github/reconcile | PG, general router only | None — re-proves (never advances) a pull-request or dispatch reservation that is already queued. | Baseline B. No distinct signed-acceptance struct of its own; it re-drives the same fleet.github.pull-request/fleet.github.apply-dispatch reservation via finishFleetGitHubReservation (:247) once GitHub's state is re-observed. | Baseline A, B + 400 invalid_fleet_github_reconcile (:145,150), 409 fleet_github_reconcile_in_progress (:159), 404 fleet_github_reservation_not_found (:170), 409 fleet_plan_invalid (:190), 409 fleet_github_reconcile_ambiguous (:197,220), 409 fleet_github_dispatch_binding_mismatch (:205), 500 fleet_github_receipt_failed (:237,241,249), 409 fleet_target_holder_abandoned when the bind fails because the plan is abandoned, plus fleet_config_read_failed/fleet_config_invalid/fleet_environment_mismatch from requireMatchingFleetEnvironment when kind=apply-dispatch. |
POST plans/{id}/github/reconcile | etcd | — | — | — |
1c. Runner-attempt sub-operations (plans/{id}/attempts[...]), by backend
The attempts route group covers six sub-operations per backend. lifecycle.Phases/lifecycle.NextPhase (fleet/lifecycle/phases.go) are confirmed as the single source for phase shape on both backends — no inline duplicate phase lists remain in handler/fleet_runner.go or handler/fleet_attempts.go.
| Sub-op | Backend | Phases | Approval rule | Error codes |
|---|---|---|---|---|
| List | PG | Read-only; returns each attempt's stored CurrentPhase as-is. | requireControlScope(ScopeAPIRead) (handler/fleet_runner.go:35). No per-attempt ownership check — any api:read principal sees all attempts on the plan. | Baseline A + 500 fleet_runner_attempt_read_failed (:44); plan lookup: 503 fleet_runner_attempt_store_unavailable (:410), 400 invalid_fleet_plan_id (:414), 404 fleet_plan_not_found (:419), 500 fleet_plan_read_failed (:423). |
| Get | PG | Read-only. | fleetRunnerCanReadAttempt = api:read or fleetRunnerPrincipalOwnsAttempt (exact fleet:operate + bound GitHub Actions identity match: provider, stable actor tuple or legacy subject, RunnerAttemptID, WorkflowURL) (:716-735). | Baseline A + 403 fleet_runner_attempt_binding_conflict (:253), 400 invalid_fleet_runner_attempt_id (:436), 404 fleet_runner_attempt_not_found (:441), 500 fleet_runner_attempt_read_failed (:445), plus plan-lookup codes as List. |
| Start | PG | Initial phase = firstIncompleteFleetRunnerPhase: first phase in lifecycle.Phases(PostgresLegacy, requiresDrain) lacking succeeded evidence — the 6-phase list from infrastructure_applied when non-drain, else the 9-phase canonical list from prechange_verified (D3/D4, :757-776, drain from fleetPlanRequiresDrain, handler/fleet.go:621). A resume/recovery call unconditionally inherits the predecessor's CurrentPhase (:163). | requireFleetOperateScope = exact fleet:operate (:58). Compound signed binding: validateFleetRunnerDispatchBinding (:582-641) must match the stored GitHub dispatch binding's nonce hash, commit/plan SHA, and (external-Mac lane) exact ApprovalEnvelopeSHA256/ConsumptionReceiptSHA256 (:593-599). | Baseline A + 409 fleet_github_dispatch_in_progress(:72), 400 invalid_fleet_runner_attempt(:78,82), 400 invalid_fleet_runner_timing_classification(:87), 403 fleet_runner_dispatch_required(:94), 500 fleet_runner_dispatch_read_failed(:98), 409 fleet_runner_dispatch_pending(:104), 403 fleet_runner_dispatch_binding_mismatch(:109), 500 fleet_runner_attempt_read_failed(:114), 409 fleet_runner_attempt_binding_conflict(:129,143,150,157), 409 fleet_runner_retry_required(:138,198), 409 fleet_runner_resume_conflict(:173), 409 fleet_runner_attempt_exists(:186,230), 500 fleet_runner_attempt_store_failed(:189,233), 409 fleet_runner_plan_already_complete(:205). |
| Heartbeat | PG | Reads attempt.CurrentPhase; request.Phase must equal it (:279). No transition — the SQL UPDATE only touches sequence/heartbeat columns (store/fleet_runner_attempts.go:115-128). | requireFleetOperateScope + fleetRunnerPrincipalOwnsAttempt (:261,270). | Baseline A + 403 fleet_runner_attempt_binding_conflict(:271), 400 invalid_fleet_runner_heartbeat(:276,280), 409 fleet_runner_attempt_revision_conflict(:285,298), 409 fleet_runner_heartbeat_out_of_order(:293), 500 fleet_runner_attempt_update_failed(:302). |
| Advance | PG | Reads attempt.CurrentPhase, must equal request.ExpectedPhase (:337); next phase via lifecycle.NextPhase(PostgresLegacy,...) (:346), terminal at complete. The store UPDATE additionally requires a matching succeeded fleet.reconciliation row for the fromPhase+attemptId (store/fleet_runner_attempts.go:151-156) — evidence-gated, not a bare row check. | requireFleetOperateScope + fleetRunnerPrincipalOwnsAttempt (:310,319). | Baseline A + 403 fleet_runner_attempt_binding_conflict(:320), 400 invalid_fleet_runner_advance(:325,329), 409 fleet_runner_phase_conflict(:338,348), 500 fleet_plan_read_failed(:343), 409 fleet_runner_advance_unproven(:353), 500 fleet_runner_attempt_update_failed(:357). |
| Cancel | PG | No phase transition; sets terminal status canceled only, CurrentPhase untouched. Runner self-cancel only — there is no operator-cancel path on this route (:374-376). | requireFleetOperateScope + fleetRunnerPrincipalOwnsAttempt (:365,377). | Baseline A + 403 fleet_runner_attempt_binding_conflict(:378), 400 invalid_fleet_runner_cancel(:383,387), 409 fleet_runner_cancel_not_allowed(:397), 500 fleet_runner_attempt_update_failed(:401). |
| List | etcd | Read-only; filtered to attempts the caller's bound identity owns (always filtered — unlike PG, there is no unfiltered api:read view). | h.workload = fleet:operate (Allows, not exact) + managed-token + CI non-nil (requireFleetRunnerPrincipal, handler/fleet_attempts.go:355-365) + plan-binding match on CI intent (apply→dispatch binding, recover→attempt list) (readablePlan, handler/fleet_etcd_attempts.go:269-295). | Baseline A + 503 fleet_runner_attempt_store_unavailable(:49), 400 invalid_fleet_plan_id(:54), 404 fleet_plan_not_found(:59), 503 fleet_plan_read_failed(:63), 409 fleet_plan_invalid(:68), 403 fleet_runner_oidc_required(:78), 403 fleet_plan_read_forbidden(:293), 503 fleet_runner_attempt_read_failed(:304). |
| Get | etcd | Read-only. | h.workload gate plus inline per-attempt identity match (RunnerAttemptID+WorkflowURL, :262-265) — no separately named ownership function, unlike PG's fleetRunnerPrincipalOwnsAttempt. | Workload/plan codes as List + 400 invalid_fleet_runner_attempt_id(:250), 404 fleet_runner_attempt_not_found(:255), 503 fleet_runner_attempt_read_failed(:259), 403 fleet_runner_attempt_identity_mismatch(:263). |
| Start (Create) | etcd | Initial phase is hardcoded prechange_verified (fleetInitialPhase, etcdstore/v3_fleet_runner_attempt.go:525-530) unless a single-predecessor, non-drain recovery, which inherits the predecessor's CurrentPhase (:207-209) — D3 lives here explicitly. D4: lifecycle.Phases(V3,_) is always the 9-phase canonical list regardless of drain. | h.workload gate (as List) + mandatory signed/typed admission: store.FleetRunnerAttemptAdmission built at handler/fleet_etcd_attempts.go:115, sealed through acceptFleetRunnerAttempt (etcdstore/v3_fleet_runner_attempt.go:98-259) — this is the compound-acceptance equivalent of PG's dispatch-binding validation. | Baseline A + 400 invalid_fleet_runner_attempt(:108), 403 fleet_runner_attempt_identity_mismatch(:112), 503 fleet_runner_attempt_read_failed(:118), 409 fleet_runner_attempt_binding_conflict(:135), 409 fleet_runner_attempt_external_stop_unproven(:145,158), 409 fleet_runner_attempt_dispatch_mismatch(:152), 400 invalid_idempotency_key(:169), 409 idempotency_key_reused(:175), 500 fleet_runner_attempt_store_failed(:201); store-side, mapped 409 (403 for *_identity_mismatch/*_dispatch_mismatch, control_protocol.go:185-192): fleet_plan_not_found(etcdstore:119), fleet_plan_invalid(:122), fleet_runner_attempt_dispatch_mismatch(:129,136,139), fleet_runner_attempt_identity_mismatch(:142), fleet_runner_attempt_lineage_invalid(:160), fleet_runner_attempt_identity_conflict(:171), fleet_runner_attempt_binding_mismatch(:174), fleet_runner_attempt_resume_invalid(:179), fleet_runner_attempt_stale(:184,258), fleet_runner_attempt_resume_required(:187), fleet_runner_attempt_recovery_limit(:190), fleet_runner_attempt_complete(:193), fleet_runner_attempt_external_stop_unproven(:197). |
| Heartbeat | etcd | Reads item.CurrentPhase; request.Phase must equal it (:329). No transition — direct CAS write, not queued through the signed-acceptance pipeline. | h.workload + inline per-attempt identity match (same gate as Get). | Workload/plan codes as Get + 409 fleet_runner_attempt_stale(:330, also covers bare ErrNotFound/admission-error mapping at :374-376), 503 fleet_runner_attempt_store_failed(:378). |
| Advance | etcd | Reads item.CurrentPhase == request.ExpectedPhase (:343); next via lifecycle.NextPhase(V3,...) (:347) — always the 9-phase canonical list (D4). The store additionally requires hasSignedFleetReconciliationEvidence — a signed reconciliation operation matching phase/attempt/commit/plan (etcdstore:373,427-469) — a stronger evidence gate than PG's row-exists check. | h.workload gate (same as Heartbeat). | Workload/plan codes as Get + 409 fleet_runner_attempt_stale(:344), 409 fleet_reconciliation_evidence_required(etcdstore:378, mapped 409 unless fleet_reconciliation_identity_mismatch, control_protocol.go:194-201). |
| Cancel | etcd | No transition; sets canceled only, CurrentPhase untouched. No explicit self-cancel-only comment (unlike PG), but the h.workload ownership gate has the same practical effect. | h.workload gate (same as Heartbeat/Advance). | Workload/plan codes as Get + 409 fleet_runner_attempt_stale(:362), 503 fleet_runner_attempt_store_failed(:378). |
2. Phases (plan.md §1.3)
| Fact | Source | Owning test |
|---|---|---|
| Canonical 9-phase list | fleetReconciliationPhases (handler/fleet.go:35) | TestFleetRunnerPhaseAdvanceIsOrderedAndTerminal |
| etcd canonical copy | fleetValidPhase (etcdstore/v3_fleet_runner_attempt.go:505) | TestV3FleetRunnerAdvanceRequiresSignedCurrentPhaseEvidenceEtcd |
PG legacy no-drain, 6 phases, starts at infrastructure_applied | fleetRunnerPhases(false) (handler/fleet_runner.go:759) | TestFleetRunnerPhaseAdvanceIsOrderedAndTerminal |
| V3 advance over all 9 phases | nextFleetReconciliationPhase (handler/fleet_attempts.go:394) | TestFleetRunnerAttemptAcceptanceRestartsDestructiveRecoveryAtPrechange |
| Drain predicate, 3 copies, 2 number-decoding shapes (int/int64/float64 vs float64/json.Number) | handler/fleet.go:630, store/fleet_reconciliation_acceptance.go:234, etcdstore/v3_fleet_runner_attempt.go:513 | TestFleetReconciliationCompleteRequiresDrainForReplacement; etcd side covered by TestV3FleetReconciliationAcceptanceReplayAndPhaseEvidenceEtcd |
3. D1–D12 (plan.md §1.6): preserved PG-vs-etcd differences
| # | Behavior | Owning test (current behavior) |
|---|---|---|
| D1 | Start request shape (RunnerAttemptStartRequest vs RunnerAttemptCreateRequest) | TestFleetRunnerStartValidation (PG); TestFleetRunnerAttemptAcceptanceFingerprintsResumeTimeoutAndRejectsTypedRawNonce (PG V3, same shape as etcd) |
| D2 | Signed attempt creation: no (PG legacy) / yes (PG V3, etcd) | structural; see §1 table handler columns |
| D3 | Initial phase differs by profile | PG legacy only: TestFleetRunnerPhaseAdvanceIsOrderedAndTerminal (no-drain table); PG V3 provider_applying and etcd prechange_verified initial phases: none directly |
| D4 | Non-drain phase count (6 vs 9) | PG legacy only: TestFleetRunnerPhaseAdvanceIsOrderedAndTerminal; the 9-phase V3/etcd walk is not pinned for non-drain plans |
| D5 | Recovery limit: unlimited (PG) vs one (etcd) | TestFleetRunnerAttemptLifecycle (two sequential PG recoveries succeed); TestV3FleetRunnerAttemptAllowsOneVerifiedRecoverySuccessorEtcd |
| D6 | Predecessor stop proof: none (PG) vs required (etcd) | TestFleetRunnerAttemptLifecycle (PG recovers with no stop evidence argument); TestV3FleetRunnerAttemptAllowsOneVerifiedRecoverySuccessorEtcd (etcd); TestFleetRunnerPredecessorStopEvidenceRejectsForgedOrStaleProof pins only the pure store validator |
| D7 | Predecessor becomes canceled (PG) vs failed (etcd) | TestFleetRunnerAttemptLifecycle (asserts canceled); TestV3FleetRunnerAttemptAllowsOneVerifiedRecoverySuccessorEtcd (asserts failed) |
| D8 | Expiry written on read (PG) vs projected (etcd) | TestFleetRunnerLegacyReadWritesExpiry (new); TestFleetRunnerAttemptReadsProjectExpiryWithoutMutation |
| D9 | Advance evidence: atomic SQL (PG) / non-atomic handler read (PG V3) / atomic CAS (etcd) | TestFleetRunnerAttemptLifecycle (PG EXISTS gate); TestV3FleetRunnerAdvanceRacesReconciliationCASAtomicallyEtcd |
| D10 | Raw dispatch nonce at rest: never (PG) vs yes (etcd) | TestFleetRunnerAttemptNeverSerializesDispatchNonce (PG struct has no field); TestV3FleetGitHubDispatchPreparationRetainsRawNonceEtcd (new) |
| D11 | Rerun/prepare/execute/reconcile routes: PG only | structural (route registrations, §1 table); no test asserts their absence on etcd |
| D12 | Heartbeat replay: same sequence + revision-1 returns current (PG, strict on etcd) | TestFleetRunnerHeartbeatReplaySameSequence (new, PG); etcd strictness (handler/fleet_etcd_attempts.go:329, etcdstore/v3_fleet_runner_attempt.go:355): none — no etcd test sends a replayed sequence |
4. Dead legacy code (plan.md §1.1)
RetryFleetRunnerAttempt, FailFleetRunnerAttempt and InsertFleetReconciliation (store/fleet_runner_attempts.go:169-310) have no production caller — the live PG path reaches these states through the signed checkpoint/acceptance path instead. They remain exercised only by tests (TestFleetRunnerAttemptLifecycle calls RetryFleetRunnerAttempt and InsertFleetReconciliation; TestFleetRunnerPilotRunMigrationRoundTrip calls FailFleetRunnerAttempt). This plan does not fence them and WP2+ must not remove their test coverage without first confirming they stay dead.
5. Pre-existing defect (plan.md §1.6, H4/M6)
In DispatchFleetGitHubApply, MarkFleetGitHubDispatchSubmitting runs at handler/fleet_github.go:857, immediately before the one permitted GitHub POST. If that POST then fails with githubapp.ErrDispatchPreSubmit, the handler calls DeletePreparedFleetGitHubDispatch (fleet_github.go:867-869). That delete matches only dispatch_state='prepared' AND run_id=0 (store/fleet_github_dispatches.go:128), so against the submitting row it just fenced it is a no-op: no error, zero rows affected. The row is left submitting with run_id=0. The only store function that resets a submitting row to prepared is ResetFleetGitHubDispatchPreSubmit, which exists for the distinct external-Mac execute lane (handler/fleet_github.go:~555) and is never called from this path. Later calls therefore observe an ambiguous dispatch (fleet_github_dispatch_ambiguous) until the WP2.2 abandon path resolves it.
This is recorded, not fixed, per decision H4 (plan.md §5): "Leave behavior unchanged. Pinned by TestDispatchPreSubmitFailureLeavesSubmitting." That test (new, this WP) reproduces the exact store-call sequence above and asserts the row stays submitting. It pins the store semantics only: it does not drive DispatchFleetGitHubApply (whose *githubapp.Client field has no test seam), so a handler-only switch to ResetFleetGitHubDispatchPreSubmit would not fail it. Whoever makes that fix must update this test and add a handler-level check in the same change (WP6's HTTP-boundary suite is the natural home).
6. Same-plan concurrent executor gap (Q11, plan.md §5)
On the PG legacy path, recovering a source attempt (RecoverFleetRunnerAttempt, store/fleet_runner_attempts.go:316) cancels a still-live source "superseded by verified recovery workflow" without any proof that the source's GitHub run has actually stopped (plan.md §1.4, "Recovery" row). It only requires the caller's authority-consumption tuple to match (authorityMetadataMatches, handler/fleet_runner.go:549). A second, still-running executor from the superseded run can therefore keep mutating provider state concurrently with the new recovery attempt, with no lineage check preventing it (validateFleetRunnerAttemptLineage on PG legacy is a no-op; it only derives the root — plan.md §1.4, "Lineage validation").
There is no current regression test that could pin a fix here, because there is nothing to pin: this is an absence of a check, not a behavior. Decision Q11 (plan.md §5) accepts a provisional default — once a plan's target is registered (WP3+), legacy recovery is refused unless the source attempt's GitHub run is proven completed via the WP5 observers (fleet_target_recovery_requires_stopped_source). Unregistered targets keep today's unchecked behavior; this contract records that gap so later work does not treat it as newly introduced.
7. Executor lane (ADR 0010, plan-5-7.md, WP E0)
This section is the contract for the controller-run executor lane. Nothing here describes shipped behavior yet: each row names the work package that makes it true, and the pinned shapes live in fleet/executor/shapes.go and contract/control-v1.openapi.yaml (cross-checked by contract/executor_contract_test.go). Existing rows in sections 1-6 are unchanged. Baselines A and C of section 1b apply to every route below.
7a. New routes
| Route | Backends | Scope / principal | Phases | Ledger kind | Owner WP |
|---|---|---|---|---|---|
POST resources/{name}/converge (rescan; no body, Idempotency-Key) | PG authority-only, etcd | non-CI platform:operate, or executor (exact fleet:execute) | none; never starts an attempt; records a plan only when the verified tip has no admissible converge plan | fleet.capacity-plan (action: converge) | E4a, E6 |
POST plans/{id}/converge/approve | both | platform:operate, non-CI, Idempotency-Key | none | fleet.converge.approve | E4a (route), E2 (fixtures) |
POST resources/{name}/execution-mode | both | admin, non-CI, Idempotency-Key, fence Free | none | fleet.resource.execution-mode | E4b |
POST plans/{id}/credential-grants | both | executor principal: managed token, exact fleet:execute, CI==nil | plan; V3 preflight with a live owned attempt at provider_applying, including recovery; recover with a live recovery attempt; else phase == currentPhase exactly (7b) | fleet.credential-grant | E5 |
POST plans/{id}/preflight-completions | V3 | executor principal, same device as its live attempt and latest unexpired preflight grant | provider_applying; required before any do-write grant at that phase | fleet.preflight-complete | E5 |
POST executor/stop-attestations | both | executor principal, same device as the source attempt | source attempt non-terminal or expired | fleet.executor.stop-attestation | E5 |
Existing routes with executor-lane behavior:
| Route | Change | Owner WP |
|---|---|---|
POST plans/{id}/attempts and heartbeat/advance/checkpoint/cancel | Lane chosen by principal (ADR 0010, "Validators and lanes"). The executor principal sends FleetExecutorAttemptStartRequest (executor.AttemptStartRequest), owns attempts whose principal_subject is managed-device:<deviceId> and runnerAttemptId is executor:<dropletId>:<invocationId>:<planId>, through a separate branch of fleetRunnerPrincipalOwnsAttempt. Start acquires and binds the fence and inserts the attempt in one transaction (CreateFleetExecutorAttempt; etcd equivalent). Every GitHub-lane validator and the CI branch are unchanged. | E2, E2e |
POST targets/{id}/fence/release, POST targets/abandon-plan | Optional admin providerEvidence: an admin assertion, not proof; the server also requires the holder's executor device revoked and the matching dropletId. For executor-lane holders a valid stop attestation or providerEvidence replaces GitHub observers, which can never prove an executor attempt; the 30 minute age gate (H5) still applies. | E5 |
GET resources[/{name}] | executionMode, extended approvalPolicy, new blockers, approve_converge, resumeApproved. | E4b |
New scope: fleet:execute. It is granted only alone, only to platform fleet-executor (7 day token), never via OIDC. The router's generic scope matcher must not widen it: FleetPlanRunnerScopedPath keeps matching only attempt and reconciliation paths, and the new routes face the generic check (E6).
7b. Phases
Grant phases are the pseudo-phases plan (before any attempt) and recover (live recovery attempt, union of types), and otherwise real lifecycle phase names equal to the attempt's currentPhase; there is no alias. Executor plans never drain, so PG executor attempts walk the legacy no-drain list (section 2, D3/D4: infrastructure_applied first, and the provider apply runs inside it) and etcd executor attempts walk the canonical list (prechange_verified, then provider_applying, where the provider apply runs). The per-backend type table is executor.GrantTypes and ADR 0010. Advance and checkpoint rules of section 1c are unchanged.
7c. Error codes
| Status | Code | Raised by |
|---|---|---|
| 400 | invalid_fleet_executor_request | all new routes, malformed body |
| 409 | fleet_converge_approval_required | attempt start, plan needs approve and none matches |
| 409 | fleet_converge_commit_mismatch | approve for a commit other than the plan's |
| 409 | fleet_converge_approval_consumed | second recovery against one resume approve |
| 409 | fleet_plan_not_converge | approve or executor start on a non-converge plan |
| 409 | fleet_execution_mode_not_controller | executor start on a github resource |
| 409 | fleet_execution_mode_fence_held | mode switch while the fence is held |
| 409 | fleet_executor_trigger_unverified | VerifyProtectedCommit failed at attempt start |
| 409 | fleet_executor_plan_not_newest | plan is not the newest desired revision |
| 409 | fleet_executor_stop_attestation_invalid | other device, droplet or machine; same invocation; stale; or same-boot facts not all true |
| 409 | fleet_credential_grant_attempt_required | attempt-scoped phase without a live owned attempt |
| 409 | fleet_credential_grant_phase_mismatch | phase is not the attempt's current phase |
| 403 | fleet_credential_type_not_allowed | type not in the phase table |
| 400 | fleet_provider_evidence_invalid | malformed or stale providerEvidence |
| 409 | fleet_executor_device_active | providerEvidence while the holder's executor device is not revoked |
| 409 | fleet_provider_evidence_required | executor-lane release or abandon without attestation or evidence |
Reused unchanged: fleet_target_execution_occupied (the loop treats it as "busy, retry"), fleet_plan_revalidation_required (the loop rescans), fleet_target_unregistered, fleet_target_holder_abandoned, fleet_target_recovery_requires_stopped_source, insufficient_scope (403, wrong or non-exact principal) and baselines A and C.
7d. D13-D18: executor-lane differences (extends section 3)
| # | Difference | Owning test |
|---|---|---|
| D13 | Attempt identity: github-actions:<repo>:<run>:<attempt> vs executor:<dropletId>:<invocationId>:<planId>; workflowUrl is norn-executor://..., not https; sourceDispatchRunId 0; principal_subject managed-device:<deviceId> | fleet/executor TestAttemptIdentityRoundTripAndMetadata, TestLaneIdentifiersAreDisjoint; E2 CIBranchUnchanged |
| D14 | Fence holder nonce: GitHub dispatch nonce hash vs sha256("executor-lane:" + planID); no dispatch row, nonce, claim or submit | fleet/executor TestHolderNonceIsStableHex; E2 LanesShareFence |
| D15 | Stop proof: GitHub run completed (observers) vs stop attestation (self-attestation) or admin providerEvidence (assertion) | fleet/executor TestStopAttestationDecision; E2 RecoveryRequiresAttestationOrEvidence, CloneDropletAttestationRejected; E5 AttestationSameDropletOnly |
| D16 | Principal: bound GitHub Actions identity with fleet:operate vs managed token with exact fleet:execute and CI==nil | E1 TestExecutorPrincipalRequiresManagedTokenAndExactScope |
| D18 | Grant phase table: PG legacy no-drain grants the provider apply at infrastructure_applied; etcd at provider_applying | fleet/executor TestGrantPhasesAreRealLifecyclePhases, TestGrantTypeTable |
| D17 | Trigger check: OIDC ref_protected vs VerifyProtectedCommit (protected flag, successful validate.yml push run, descendant of last applied) at the watcher and at attempt start | E3 RequiresProtectedFlag, RequiresValidatePushSuccessAtSHA |
Same-plan concurrent executors remain a section 6 concern: the executor lane takes the fence row FOR UPDATE in the same transaction as the attempt insert, so Q11 does not apply to it.