From 182d74b7cc039a99be940e43cffaa6b86d3cd437 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Fri, 30 Oct 2026 21:09:21 -0400 Subject: [PATCH 1/4] =?UTF-8?q?=E2=9C=A8=20feat:=20fence=20integration=20p?= =?UTF-8?q?romotion=20with=20exact-tested=20destination=20CAS?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andy Anderson --- .../added-integration-promotion-protocol.md | 1 + src/docs/integration-orchestration.md | 131 +++++++ src/pkg/github/integration_promotion.go | 202 ++++++++++ src/pkg/github/integration_promotion_test.go | 352 ++++++++++++++++++ 4 files changed, 686 insertions(+) create mode 100644 changelog.d/added-integration-promotion-protocol.md create mode 100644 src/pkg/github/integration_promotion.go create mode 100644 src/pkg/github/integration_promotion_test.go diff --git a/changelog.d/added-integration-promotion-protocol.md b/changelog.d/added-integration-promotion-protocol.md new file mode 100644 index 0000000000..5b0726f74f --- /dev/null +++ b/changelog.d/added-integration-promotion-protocol.md @@ -0,0 +1 @@ +- Add an isolated Integration-aware promotion protocol foundation with exact tested commit/tree and ordered-parent verification, journaled destination compare-and-swap, live-guard fencing and conservative ambiguous-result reconciliation; execution remains unwired and disabled, with producer, permissions and protection prerequisites documented. diff --git a/src/docs/integration-orchestration.md b/src/docs/integration-orchestration.md index 27cbedde0e..f0a722bf2c 100644 --- a/src/docs/integration-orchestration.md +++ b/src/docs/integration-orchestration.md @@ -5,6 +5,137 @@ 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 + +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 first protocol is `integration-first-parent-v1`, intentionally limited to +preserving-history merge commits on GitHub. For a tested step `S`, its ordered +parents must be exactly `[expected destination, exact author head]`; its commit +OID and tree must equal the recorded tested OIDs. Promotion moves the destination +to **that existing commit**, not a newly generated squash/rebase/merge result +and not a merely similar tree. Linear-history-only or mandatory-signature +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. +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, subject, policy and generation through the existing effects boundary. +`clientMutationId` binds acknowledgement; it is **not** provider idempotency. + +A durable boundary and non-nil live eligibility guard are mandatory. The +transport refuses a no-op boundary. The future controller must supply 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 +permit a fallback, force update or privilege expansion. Destination CAS does +not atomically snapshot GitHub's independently mutable PR/review/hold fields: +their current freshness contract and any remaining race must be explicit, not +misrepresented as a multi-resource transaction. + +An ambiguous mutation is reconciled, never called successful from a timeout. +The exact tested destination proves application; the unchanged expected +destination permits only the same fenced retry. A different/unreadable +destination remains an explicit unresolved condition. There is no blind +TTL-expiry retry and no proof transfer to a changed head. A destination that +advanced after an ambiguous acknowledgement needs further authoritative +lineage reconciliation; the transport does not guess that it was promoted. + +### Execution feasibility gates + +Before any future execution opt-in can pass server validation: + +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` + 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 + bound and cannot be relabeled as a multi-member producer. +2. The actual installation must already have the permissions required by the + chosen trigger. Hive normally has Actions read and Checks read. A direct + workflow dispatch needs Actions write; it is not silently requested. A + repository-dispatch control plane is a separate API/provenance design, not + an interchangeable claim that an Actions-read App can dispatch workflows. +3. Candidate publication must not trigger unreviewed privileged `push` + workflows. Untrusted candidate code must run with read-only credentials, + no repository secrets, no privileged runner access and isolated disposable + execution. A successful trusted finalizer, exact run/attempt/job binding + and immutable artifact identity are necessary; an artifact name alone + does not establish its producer. +4. Every actual required context must have a genuine candidate-aware producer. + Author-head DCO/review receipts remain separate; copying their green + statuses onto a combined commit is forbidden. Required-context/provider + incompatibility blocks promotion rather than changing branch rules. +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. +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. + +### Parallel architecture and evidence criteria + +The execution target is parallel speculative prefixes from the outset: +`B -> S(A) -> S(A,B) -> S(A,B,C)`, with CI on each exact step allowed to +overlap. The one-step transport proves a protocol, **not** performance +completion. Passing later prefixes never authorizes a rejected predecessor. +Removing A invalidates A-dependent subjects and rebuilds B against the actual +destination; an A+B receipt cannot validate B alone. Other destinations and +new legally formed independent subjects can proceed within their own budgets. +Disjoint paths are not a semantic independence proof. + +The implementation sequence is trusted producer/permission/protection +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. + +The evidence behind these choices is deliberately qualified: + +| Decision | Source/result and limitation | Required comparison or regression | +| --- | --- | --- | +| Parallel prefixes and scoped predecessor rebuilds | [GitHub's documented native behavior](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue) and [Zuul dependent gating](https://zuul-ci.org/docs/zuul/latest/gating.html) test ordered speculative prefixes. This is a production design baseline, not Hive parity evidence. | A fails after A+B passes; rebuild B-only; preserve an exactly promoted prefix; prohibit old evidence resurrection. | +| No fixed batch-fill delay initially | [FSE 2023 parallel batch testing](https://arxiv.org/html/2308.13129), sections 2–6: historical simulation, nonlinear capacity effects, fixed batching can worsen latency when resources are plentiful. It assumes no merge conflicts and excludes compile time. | Idle arrivals, burst arrivals, full compile/setup time, text and semantic conflicts, and p50/p95 rather than averages alone. | +| Bounded adaptive window only after measured static operation | Zuul describes additive growth, failure shrink and per-destination windows. The paper's historical gains do not establish Hive's useful concurrency. | Sweep fixed windows first; measure wasted runner-minutes, failure recovery and marginal latency benefit; freeze growth on incomplete telemetry. | +| No test skipping, prediction or assumed content equivalence | The paper's batching/failure model is not a proof about a different combined Git subject. [Tide](https://docs.prow.k8s.io/docs/components/core/tide/) also requires current-base evidence and exposes missing requirements. | Changed base/member/order/policy, rerun attempts, cold restart, duplicate and reordered events, missing producers and authoritative live holds. | + +Proposed orchestration budgets are **hypotheses requiring benchmark approval**: +durable event-to-controller action p95 at most 250 ms on an idle process; +provider dispatch acceptance p95 at most 2 s excluding runner queueing; final +CI evidence received to promotion request p95 at most 2 s once every live gate +is satisfied; and idle eligible-to-dispatch p95 at most 3 s. Measure monotonic +internal spans and provider request spans separately; do not subtract slow +API calls, delayed event delivery, reviewer wait, runner wait or serial holds +from reported end-to-end latency. + +Compare identical workloads, CI definitions, runner type/count, cache state, +retry policy and failure distributions against GitHub's documented parallel +baseline. Report eligible-to-CI-start, complete-CI-to-promotion and end-to-end +p50/p95, integrations/minute, actual runner-minutes/successful integration, +invalidated/canceled execution and recovery. No safety-network job is canceled +to make the comparison look better. Native merge-size limits do not batch +native CI builds. A simulator and correctness CI are not a production benchmark. + +The stated 5,000/day target is about 3.47 integrations/minute **aggregate**, +not an achieved result or a single-repository promise. Little's law requires +about 35 in-flight candidates if mean CI is ten minutes at that rate, before +waste and headroom. Forty runner-minutes per successful integration at 70% +utilization needs about 199 simultaneous runner slots before speculative waste. +A non-overlapping 30-second per-destination hold caps that destination at two +integrations/minute regardless of controller speed. Reviewer availability, +API budgets, storage, policy holds and runner capacity must appear in the +capacity report rather than being hidden behind a fast dispatch measurement. + ## Configuration and rollback ```yaml diff --git a/src/pkg/github/integration_promotion.go b/src/pkg/github/integration_promotion.go new file mode 100644 index 0000000000..48137bddfa --- /dev/null +++ b/src/pkg/github/integration_promotion.go @@ -0,0 +1,202 @@ +package github + +import ( + "context" + "errors" + "fmt" + "strings" + + "github.com/hivecommons/hive/pkg/effects" +) + +const ( + IntegrationPromotionProtocol = "integration-first-parent-v1" + integrationPromotionMaxLabelBytes = 256 +) + +// IntegrationPromotion describes one exact, already-tested step. This initial +// protocol preserves both the preceding integration commit and the author head. +// It deliberately does not implement squash, rebase or tree-equivalent reuse. +type IntegrationPromotion struct { + Repo string + Base string + ExpectedSHA string + TestedSHA string + TestedTree string + AuthorHead string + SubjectID string + Policy string + Generation uint64 +} + +// IntegrationPromotionGuard must revalidate the destination's exclusive writer, +// exact evidence and every live member's eligibility. A ledger receipt alone is +// not authorization. The guard runs inside the existing effect boundary, +// immediately before the provider's atomic operation. +type IntegrationPromotionGuard func(context.Context, IntegrationPromotion) error + +var ErrIntegrationDestinationChanged = errors.New("integration destination changed; reconcile the candidate before retrying") + +func (p IntegrationPromotion) validate() error { + parts := strings.Split(p.Repo, "/") + if len(parts) != 2 || parts[0] == "" || parts[1] == "" || + strings.ContainsAny(p.Repo, " \t\r\n") || !integrationPromotionBranch(p.Base) || + !integrationPromotionOID(p.ExpectedSHA) || !integrationPromotionOID(p.TestedSHA) || + !integrationPromotionOID(p.TestedTree) || !integrationPromotionOID(p.AuthorHead) || + p.ExpectedSHA == p.TestedSHA || p.ExpectedSHA == p.AuthorHead || + p.SubjectID == "" || p.Policy == "" || p.Generation == 0 || + len(p.SubjectID) > integrationPromotionMaxLabelBytes || len(p.Policy) > integrationPromotionMaxLabelBytes || + strings.ContainsAny(p.SubjectID+p.Policy, "\r\n\x00") { + return fmt.Errorf("incomplete exact integration promotion") + } + return nil +} + +func integrationPromotionJournaled(boundary effects.Boundary) bool { + for { + switch b := boundary.(type) { + case effects.LoggingBoundary: + boundary = b.Next + case *effects.LoggingBoundary: + if b == nil { + return false + } + boundary = b.Next + case nil, effects.NoopBoundary, *effects.NoopBoundary: + return false + default: + _, reconciles := boundary.(effects.Reconciler) + _, looksUp := boundary.(effects.Lookup) + return reconciles && looksUp + } + } +} + +func integrationPromotionOID(value string) bool { + return integrationOID(value) && value == strings.ToLower(value) && strings.Trim(value, "0") != "" +} + +func integrationPromotionBranch(base string) bool { + if base == "" || base == "@" || strings.HasPrefix(base, "/") || + strings.HasSuffix(base, "/") || strings.HasSuffix(base, ".") || + strings.ContainsAny(base, " ~^:?*[\\\x00\t\r\n") || + strings.Contains(base, "..") || strings.Contains(base, "@{") { + return false + } + for _, character := range base { + if character < ' ' || character == '\x7f' { + return false + } + } + for _, component := range strings.Split(base, "/") { + if component == "" || strings.HasPrefix(component, ".") || strings.HasSuffix(component, ".lock") { + return false + } + } + return true +} + +func (p IntegrationPromotion) claim() effects.Claim { + return effects.Claim{ + Repo: p.Repo, Kind: effects.KindBranchUpdate, + Target: "refs/heads/" + p.Base, Actor: "integration-aware", + Inputs: map[string]string{ + "protocol": IntegrationPromotionProtocol, "expected_sha": p.ExpectedSHA, + "tested_sha": p.TestedSHA, "tested_tree": p.TestedTree, + "author_head": p.AuthorHead, "subject": p.SubjectID, + "policy": p.Policy, "generation": fmt.Sprint(p.Generation), + }, + } +} + +// PromoteIntegrationStep is a transport protocol, not an installed execution +// authority. Callers must explicitly opt in and supply a durable mutation +// boundary and the live guard; no current automerge lane calls this method. +// +// GitHub's updateRefs is atomic and checks beforeOid server-side. REST UpdateRef, +// a PR merge's expected author head, and createCommitOnBranch do not promote +// this existing tested commit with a destination compare-and-swap. +func (c *Client) PromoteIntegrationStep(ctx context.Context, p IntegrationPromotion, boundary effects.Boundary, guard IntegrationPromotionGuard) (effects.Result, error) { + if c == nil || c.client == nil { + return effects.Result{}, ErrNoGitHubClient + } + if err := p.validate(); err != nil { + return effects.Result{}, err + } + if boundary == nil || guard == nil { + return effects.Result{}, fmt.Errorf("integration promotion requires a mutation boundary and live eligibility guard") + } + if !integrationPromotionJournaled(boundary) { + return effects.Result{}, fmt.Errorf("integration promotion refuses an unjournaled mutation boundary") + } + owner, repo := c.splitRepo(p.Repo) + repository, _, err := c.client.Repositories.Get(ctx, owner, repo) + if err != nil { + return effects.Result{}, err + } + if repository.GetNodeID() == "" { + return effects.Result{}, fmt.Errorf("integration repository identity unavailable") + } + commit, _, err := c.client.Git.GetCommit(ctx, owner, repo, p.TestedSHA) + if err != nil { + return effects.Result{}, err + } + if commit.GetSHA() != p.TestedSHA || commit.GetTree().GetSHA() != p.TestedTree || + len(commit.Parents) != 2 || commit.Parents[0].GetSHA() != p.ExpectedSHA || + commit.Parents[1].GetSHA() != p.AuthorHead { + return effects.Result{}, fmt.Errorf("integration promotion requires the exact tested tree and ordered merge parents") + } + claim := p.claim() + apply := func(ctx context.Context) (effects.Result, error) { + if err := guard(ctx, p); err != nil { + return effects.Result{}, effects.NotApplied(err) + } + var out struct { + UpdateRefs *struct { + ClientMutationID string `json:"clientMutationId"` + } `json:"updateRefs"` + } + id := effects.StableDigest(claim.Repo, claim.Target, effects.StableInputs(claim.Inputs)) + err := c.graphQL(ctx, `mutation($input: UpdateRefsInput!) { + updateRefs(input: $input) { clientMutationId } +}`, map[string]any{"input": map[string]any{ + "repositoryId": repository.GetNodeID(), "clientMutationId": id, + "refUpdates": []map[string]any{{ + "name": "refs/heads/" + p.Base, "beforeOid": p.ExpectedSHA, + "afterOid": p.TestedSHA, "force": false, + }}, + }}, &out) + if err != nil { + return effects.Result{}, err + } + if out.UpdateRefs == nil || out.UpdateRefs.ClientMutationID != id { + return effects.Result{}, fmt.Errorf("integration promotion acknowledgement is incomplete; reconciliation required") + } + return effects.Result{Provenance: p.TestedSHA}, nil + } + out, err := effects.Execute(ctx, boundary, claim, apply) + if !errors.Is(err, effects.ErrNeedsReconciliation) { + return out, err + } + if _, ok := boundary.(effects.Reconciler); !ok { + return out, err + } + ref, _, readErr := c.client.Git.GetRef(ctx, owner, repo, "heads/"+p.Base) + if readErr != nil { + return out, fmt.Errorf("%w: %v", err, readErr) + } + state := effects.ExternalState{} + switch ref.GetObject().GetSHA() { + case p.TestedSHA: + state = effects.ExternalState{Applied: true, Provenance: p.TestedSHA} + case p.ExpectedSHA: + // A duplicate pending request cannot overwrite another destination: + // every attempt retains exactly the same server-side beforeOid. + default: + return out, ErrIntegrationDestinationChanged + } + if err := effects.Reconcile(ctx, boundary, claim, state); err != nil { + return out, err + } + return effects.Execute(ctx, boundary, claim, apply) +} diff --git a/src/pkg/github/integration_promotion_test.go b/src/pkg/github/integration_promotion_test.go new file mode 100644 index 0000000000..018b719f93 --- /dev/null +++ b/src/pkg/github/integration_promotion_test.go @@ -0,0 +1,352 @@ +package github + +import ( + "context" + "encoding/json" + "errors" + "net/http" + "net/http/httptest" + "strings" + "sync" + "sync/atomic" + "testing" + + "github.com/hivecommons/hive/pkg/effects" +) + +type integrationPromotionJournal struct { + unresolved bool + applied bool + fail bool + result effects.Result + claim effects.Claim +} + +func (j *integrationPromotionJournal) Execute(ctx context.Context, claim effects.Claim, apply func(context.Context) (effects.Result, error)) (effects.Result, error) { + j.claim = claim + if j.unresolved { + return effects.Result{}, effects.ErrNeedsReconciliation + } + if j.applied { + return j.result, nil + } + out, err := apply(ctx) + j.unresolved = err != nil && !errors.Is(err, effects.ErrNotApplied) + j.applied, j.result = err == nil, out + return out, err +} + +func (j *integrationPromotionJournal) Reconcile(_ context.Context, _ effects.Claim, state effects.ExternalState) error { + if j.fail { + return errors.New("journal unavailable") + } + j.unresolved, j.applied = false, state.Applied + j.result = effects.Result{Provenance: state.Provenance} + return nil +} + +func (j *integrationPromotionJournal) LookupApplied(context.Context, effects.Claim) (effects.Result, bool) { + return j.result, j.applied +} + +type integrationPromotionFixture struct { + request IntegrationPromotion + ref string + tree string + parents []string + repoID string + errorAt string + reply string + mu sync.Mutex + input map[string]any + writes atomic.Int32 +} + +func integrationPromotionRequest() IntegrationPromotion { + return IntegrationPromotion{ + Repo: "o/r", Base: "v5", ExpectedSHA: strings.Repeat("a", 40), + TestedSHA: strings.Repeat("b", 40), TestedTree: strings.Repeat("c", 40), + AuthorHead: strings.Repeat("d", 40), SubjectID: "subject-1", + Policy: "policy-1", Generation: 1, + } +} + +func promotionFixture() *integrationPromotionFixture { + p := integrationPromotionRequest() + return &integrationPromotionFixture{ + request: p, ref: p.ExpectedSHA, tree: p.TestedTree, + parents: []string{p.ExpectedSHA, p.AuthorHead}, repoID: "R_repository", + } +} + +func (f *integrationPromotionFixture) server(t *testing.T) *httptest.Server { + t.Helper() + return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + f.mu.Lock() + defer f.mu.Unlock() + if r.URL.Path == f.errorAt { + http.Error(w, "provider unavailable", http.StatusServiceUnavailable) + return + } + switch r.URL.Path { + case "/repos/o/r": + _ = json.NewEncoder(w).Encode(map[string]any{"node_id": f.repoID}) + case "/repos/o/r/git/commits/" + f.request.TestedSHA: + parents := make([]map[string]string, 0, len(f.parents)) + for _, parent := range f.parents { + parents = append(parents, map[string]string{"sha": parent}) + } + _ = json.NewEncoder(w).Encode(map[string]any{ + "sha": f.request.TestedSHA, "tree": map[string]string{"sha": f.tree}, "parents": parents, + }) + case "/repos/o/r/git/ref/heads/v5": + _ = json.NewEncoder(w).Encode(map[string]any{"object": map[string]string{"sha": f.ref}}) + case "/graphql": + f.writes.Add(1) + var body struct { + Query string `json:"query"` + Variables struct { + Input map[string]any `json:"input"` + } `json:"variables"` + } + if err := json.NewDecoder(r.Body).Decode(&body); err != nil { + t.Error(err) + w.WriteHeader(http.StatusBadRequest) + return + } + if !strings.Contains(body.Query, "updateRefs") || strings.Contains(body.Query, "createCommitOnBranch") { + t.Errorf("not the supported existing-object CAS mutation: %s", body.Query) + } + f.input = body.Variables.Input + if f.reply != "" { + _, _ = w.Write([]byte(f.reply)) + return + } + if f.ref != f.request.ExpectedSHA { + _, _ = w.Write([]byte(`{"errors":[{"type":"UNPROCESSABLE","message":"beforeOid mismatch"}]}`)) + return + } + f.ref = f.request.TestedSHA + _ = json.NewEncoder(w).Encode(map[string]any{"data": map[string]any{ + "updateRefs": map[string]any{"clientMutationId": f.input["clientMutationId"]}, + }}) + default: + t.Errorf("unexpected provider request %s %s", r.Method, r.URL.Path) + http.NotFound(w, r) + } + })) +} + +func TestIntegrationPromotionExactCASAndJournalReplay(t *testing.T) { + f := promotionFixture() + server := f.server(t) + defer server.Close() + c := testClient(t, server.URL) + journal := new(integrationPromotionJournal) + guards := 0 + guard := func(_ context.Context, got IntegrationPromotion) error { + guards++ + if got != f.request { + t.Fatal("live guard was not bound to the exact candidate") + } + return nil + } + for range 2 { + out, err := c.PromoteIntegrationStep(context.Background(), f.request, journal, guard) + if err != nil || out.Provenance != f.request.TestedSHA { + t.Fatalf("promotion: %+v %v", out, err) + } + } + if guards != 1 || f.writes.Load() != 1 { + t.Fatalf("replayed external effect: guards=%d mutations=%d", guards, f.writes.Load()) + } + f.mu.Lock() + defer f.mu.Unlock() + updates, ok := f.input["refUpdates"].([]any) + if !ok || len(updates) != 1 { + t.Fatalf("not a single bounded CAS: %#v", f.input) + } + update, ok := updates[0].(map[string]any) + if !ok || update["beforeOid"] != f.request.ExpectedSHA || + update["afterOid"] != f.request.TestedSHA || update["force"] != false || + update["name"] != "refs/heads/v5" || f.input["repositoryId"] != "R_repository" { + t.Fatalf("unsafe provider mutation: %#v", f.input) + } + if journal.claim.Kind != effects.KindBranchUpdate || journal.claim.Actor != "integration-aware" || + journal.claim.Inputs["subject"] != f.request.SubjectID || + journal.claim.Inputs["protocol"] != IntegrationPromotionProtocol { + t.Fatalf("missing mutation provenance: %+v", journal.claim) + } +} + +func TestIntegrationPromotionRefusesIncompleteOrChangedSubjects(t *testing.T) { + for _, test := range []struct { + name string + change func(*integrationPromotionFixture) + }{ + {"wrong-tree", func(f *integrationPromotionFixture) { f.tree = strings.Repeat("e", 40) }}, + {"reversed-parents", func(f *integrationPromotionFixture) { f.parents[0], f.parents[1] = f.parents[1], f.parents[0] }}, + {"wrong-parent-count", func(f *integrationPromotionFixture) { f.parents = f.parents[:1] }}, + {"unknown-repository", func(f *integrationPromotionFixture) { f.repoID = "" }}, + {"repository-read-failed", func(f *integrationPromotionFixture) { f.errorAt = "/repos/o/r" }}, + {"commit-read-failed", func(f *integrationPromotionFixture) { f.errorAt = "/repos/o/r/git/commits/" + f.request.TestedSHA }}, + } { + t.Run(test.name, func(t *testing.T) { + f := promotionFixture() + test.change(f) + server := f.server(t) + defer server.Close() + called := false + _, err := testClient(t, server.URL).PromoteIntegrationStep(context.Background(), f.request, new(integrationPromotionJournal), + func(context.Context, IntegrationPromotion) error { called = true; return nil }) + if err == nil || called || f.writes.Load() != 0 { + t.Fatalf("invalid subject reached promotion: err=%v guard=%v writes=%d", err, called, f.writes.Load()) + } + }) + } +} + +func TestIntegrationPromotionLiveGuardAndProviderFailures(t *testing.T) { + for _, reply := range []string{ + `{"data":{"updateRefs":null}}`, + `{"data":{"updateRefs":{"clientMutationId":"another-request"}}}`, + `{"errors":[{"type":"FORBIDDEN","message":"branch protection refused"}]}`, + } { + f := promotionFixture() + f.reply = reply + server := f.server(t) + c := testClient(t, server.URL) + journal := new(integrationPromotionJournal) + _, err := c.PromoteIntegrationStep(context.Background(), f.request, journal, + func(context.Context, IntegrationPromotion) error { return errors.New("live hold") }) + if err == nil || journal.unresolved || f.writes.Load() != 0 { + t.Fatalf("live hold was not a definite refusal: %v", err) + } + _, err = c.PromoteIntegrationStep(context.Background(), f.request, journal, + func(context.Context, IntegrationPromotion) error { return nil }) + if err == nil || !journal.unresolved || f.writes.Load() != 1 { + t.Fatalf("provider rejection/ambiguity became success: %v", err) + } + server.Close() + } +} + +func TestIntegrationPromotionDestinationMovesAfterLiveGuard(t *testing.T) { + f := promotionFixture() + server := f.server(t) + defer server.Close() + journal := new(integrationPromotionJournal) + other := strings.Repeat("e", 40) + _, err := testClient(t, server.URL).PromoteIntegrationStep(context.Background(), f.request, journal, + func(context.Context, IntegrationPromotion) error { + f.mu.Lock() + defer f.mu.Unlock() + f.ref = other + return nil + }) + if err == nil || !journal.unresolved || f.writes.Load() != 1 { + t.Fatalf("destination race was not refused: err=%v unresolved=%v", err, journal.unresolved) + } + f.mu.Lock() + defer f.mu.Unlock() + if f.ref != other { + t.Fatal("a read-then-write overwrote the competing destination") + } +} + +func TestIntegrationPromotionReconcilesWithoutBlindTTLRetry(t *testing.T) { + for _, state := range []string{"applied", "not-applied", "changed", "unavailable", "journal-failed"} { + t.Run(state, func(t *testing.T) { + f := promotionFixture() + journal := &integrationPromotionJournal{unresolved: true} + switch state { + case "applied": + f.ref = f.request.TestedSHA + case "changed": + f.ref = strings.Repeat("e", 40) + case "unavailable": + f.errorAt = "/repos/o/r/git/ref/heads/v5" + case "journal-failed": + journal.fail = true + } + server := f.server(t) + defer server.Close() + calls := 0 + out, err := testClient(t, server.URL).PromoteIntegrationStep(context.Background(), f.request, journal, + func(context.Context, IntegrationPromotion) error { calls++; return nil }) + wantSuccess := state == "applied" || state == "not-applied" + if (err == nil) != wantSuccess || wantSuccess && out.Provenance != f.request.TestedSHA { + t.Fatalf("reconciliation state=%s result=%+v err=%v", state, out, err) + } + wantCalls := 0 + if state == "not-applied" { + wantCalls = 1 + } + if calls != wantCalls || int(f.writes.Load()) != wantCalls { + t.Fatalf("unexpected blind retry: guards=%d writes=%d", calls, f.writes.Load()) + } + if state == "changed" && !errors.Is(err, ErrIntegrationDestinationChanged) { + t.Fatalf("changed destination lost explicit invalidation reason: %v", err) + } + }) + } +} + +func TestIntegrationPromotionInvalidRequestsHaveNoEffects(t *testing.T) { + for _, branch := range []string{"", "@", "/v5", "v5/", "v5.", "v5..next", ".hidden", "a/.hidden", "a.lock", "a//b", "v5@{1}", "a b", "a\x01b", "a\x7fb"} { + if integrationPromotionBranch(branch) { + t.Errorf("accepted invalid branch %q", branch) + } + } + if !integrationPromotionBranch("release/v5") { + t.Fatal("valid scoped branch rejected") + } + for _, change := range []func(*IntegrationPromotion){ + func(p *IntegrationPromotion) { p.Repo = "r" }, + func(p *IntegrationPromotion) { p.Base = "" }, + func(p *IntegrationPromotion) { p.ExpectedSHA = strings.Repeat("0", 40) }, + func(p *IntegrationPromotion) { p.TestedSHA = strings.Repeat("B", 40) }, + func(p *IntegrationPromotion) { p.TestedTree = "short" }, + func(p *IntegrationPromotion) { p.AuthorHead = p.ExpectedSHA }, + func(p *IntegrationPromotion) { p.TestedSHA = p.ExpectedSHA }, + func(p *IntegrationPromotion) { p.SubjectID = "" }, + func(p *IntegrationPromotion) { p.Policy = "" }, + func(p *IntegrationPromotion) { p.Policy = "policy\nsubject=another" }, + func(p *IntegrationPromotion) { p.SubjectID = strings.Repeat("x", integrationPromotionMaxLabelBytes+1) }, + func(p *IntegrationPromotion) { p.Generation = 0 }, + } { + p := integrationPromotionRequest() + change(&p) + if p.validate() == nil { + t.Errorf("accepted incomplete request: %+v", p) + } + } + var missing *Client + if _, err := missing.PromoteIntegrationStep(context.Background(), integrationPromotionRequest(), nil, nil); !errors.Is(err, ErrNoGitHubClient) { + t.Fatalf("nil client: %v", err) + } + server := promotionFixture().server(t) + defer server.Close() + c := testClient(t, server.URL) + p := integrationPromotionRequest() + guard := func(context.Context, IntegrationPromotion) error { return nil } + var missingLogging *effects.LoggingBoundary + for _, boundary := range []effects.Boundary{ + nil, effects.NoopBoundary{}, &effects.NoopBoundary{}, + effects.LoggingBoundary{}, &effects.LoggingBoundary{Next: effects.NoopBoundary{}}, missingLogging, + } { + if _, err := c.PromoteIntegrationStep(context.Background(), p, boundary, guard); err == nil { + t.Fatal("accepted missing/unfenced boundary") + } + if !integrationPromotionJournaled(effects.LoggingBoundary{Next: &effects.LoggingBoundary{Next: new(integrationPromotionJournal)}}) { + t.Fatal("a real journal wrapped in logging lost its capabilities") + } + } + if _, err := c.PromoteIntegrationStep(context.Background(), p, new(integrationPromotionJournal), nil); err == nil { + t.Fatal("accepted missing live guard") + } + p.SubjectID = "" + if _, err := c.PromoteIntegrationStep(context.Background(), p, new(integrationPromotionJournal), guard); err == nil { + t.Fatal("accepted invalid request") + } +} From 6269ed59fbac7d2b9f76a78e21f23788b19ee2d0 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Fri, 30 Oct 2026 21:20:05 -0400 Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=90=9B=20fix:=20require=20synced=20jo?= =?UTF-8?q?urnal=20execution=20for=20integration=20promotion?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andy Anderson --- src/crux/effects/effects.go | 20 +++++ src/crux/effects/execute_journaled_test.go | 41 +++++++++ src/docs/integration-orchestration.md | 12 +++ src/pkg/convergence/mutation/boundary.go | 31 +++++++ .../mutation/boundary_journaled_test.go | 83 +++++++++++++++++++ src/pkg/convergence/mutation/journal.go | 36 ++++++++ src/pkg/effects/alias_test.go | 8 ++ src/pkg/effects/effects.go | 23 ++--- src/pkg/github/integration_promotion.go | 11 ++- src/pkg/github/integration_promotion_test.go | 4 + 10 files changed, 255 insertions(+), 14 deletions(-) create mode 100644 src/crux/effects/execute_journaled_test.go create mode 100644 src/pkg/convergence/mutation/boundary_journaled_test.go diff --git a/src/crux/effects/effects.go b/src/crux/effects/effects.go index 67e5c3b7bc..05307999d6 100644 --- a/src/crux/effects/effects.go +++ b/src/crux/effects/effects.go @@ -188,6 +188,13 @@ type Boundary interface { Execute(ctx context.Context, claim Claim, effect func(context.Context) (Result, error)) (Result, error) } +// JournaledBoundary refuses to invoke effect without an active operation +// journal. Implementations freeze their effective mode for the whole operation; +// ordinary Boundary may deliberately pass effects through when journaling is off. +type JournaledBoundary interface { + ExecuteJournaled(ctx context.Context, claim Claim, effect func(context.Context) (Result, error)) (Result, error) +} + type NoopBoundary struct{} func (NoopBoundary) Execute(ctx context.Context, _ Claim, effect func(context.Context) (Result, error)) (Result, error) { @@ -294,6 +301,19 @@ type LoggingBoundary struct { func (b LoggingBoundary) Execute(ctx context.Context, claim Claim, effect func(context.Context) (Result, error)) (Result, error) { res, err := Execute(ctx, b.Next, claim, effect) + return b.record(claim, res, err) +} + +func (b LoggingBoundary) ExecuteJournaled(ctx context.Context, claim Claim, effect func(context.Context) (Result, error)) (Result, error) { + journaled, ok := b.Next.(JournaledBoundary) + if !ok { + return Result{}, fmt.Errorf("%w: mutation boundary cannot require journaling", ErrDenied) + } + res, err := journaled.ExecuteJournaled(ctx, claim, effect) + return b.record(claim, res, err) +} + +func (b LoggingBoundary) record(claim Claim, res Result, err error) (Result, error) { if err != nil && errors.Is(err, ErrDenied) && b.Logger != nil { b.Logger.Warn("mutation boundary denied external effect", "repo", claim.Repo, "kind", claim.Kind, "target", claim.Target, "error", err) diff --git a/src/crux/effects/execute_journaled_test.go b/src/crux/effects/execute_journaled_test.go new file mode 100644 index 0000000000..2bd9d3162a --- /dev/null +++ b/src/crux/effects/execute_journaled_test.go @@ -0,0 +1,41 @@ +package effects + +import ( + "context" + "errors" + "testing" +) + +type testJournaledBoundary struct { + calls int +} + +func (b *testJournaledBoundary) Execute(ctx context.Context, _ Claim, effect func(context.Context) (Result, error)) (Result, error) { + return effect(ctx) +} + +func (b *testJournaledBoundary) ExecuteJournaled(ctx context.Context, _ Claim, effect func(context.Context) (Result, error)) (Result, error) { + b.calls++ + return effect(ctx) +} + +func TestLoggingBoundaryJournalRequiredDelegation(t *testing.T) { + for _, next := range []Boundary{nil, NoopBoundary{}} { + boundary := LoggingBoundary{Next: next} + _, err := boundary.ExecuteJournaled(context.Background(), Claim{}, func(context.Context) (Result, error) { + t.Fatal("unjournaled effect ran") + return Result{}, nil + }) + if !errors.Is(err, ErrDenied) { + t.Fatalf("missing journal was not denied: %v", err) + } + } + next := new(testJournaledBoundary) + boundary := LoggingBoundary{Next: LoggingBoundary{Next: next}} + out, err := boundary.ExecuteJournaled(context.Background(), Claim{}, func(context.Context) (Result, error) { + return Result{Provenance: "exact-subject"}, nil + }) + if err != nil || out.Provenance != "exact-subject" || next.calls != 1 { + t.Fatalf("journal-required delegation: result=%+v err=%v calls=%d", out, err, next.calls) + } +} diff --git a/src/docs/integration-orchestration.md b/src/docs/integration-orchestration.md index f0a722bf2c..e816ca0c54 100644 --- a/src/docs/integration-orchestration.md +++ b/src/docs/integration-orchestration.md @@ -41,6 +41,13 @@ not atomically snapshot GitHub's independently mutable PR/review/hold fields: their current freshness contract and any remaining race must be explicit, not misrepresented as a multi-resource transaction. +The explicit `ExecuteJournaled` boundary contract refuses OFF/missing +persistence, freezes the effective mode once, syncs the journal intent before +the external effect and syncs its result before acknowledgment. Ordinary +`Execute` retains its existing OFF passthrough behavior; method availability +alone never establishes that journaling is active. The new sync requirement is +limited to explicitly journal-required operations, not added to legacy writes. + An ambiguous mutation is reconciled, never called successful from a timeout. The exact tested destination proves application; the unchanged expected destination permits only the same fenced retry. A different/unreadable @@ -88,6 +95,11 @@ The execution target is parallel speculative prefixes from the outset: `B -> S(A) -> S(A,B) -> S(A,B,C)`, with CI on each exact step allowed to overlap. The one-step transport proves a protocol, **not** performance completion. Passing later prefixes never authorizes a rejected predecessor. +This first transport also serializes destination advances: at two seconds per +advance, a 32-member ready prefix could add roughly 64 seconds for its last +member. A future single-CAS contiguous-prefix protocol needs its own verified +first-parent lineage, passing proof for every required step, and live guards +for every not-yet-promoted member; this adapter does not pretend to support it. Removing A invalidates A-dependent subjects and rebuilds B against the actual destination; an A+B receipt cannot validate B alone. Other destinations and new legally formed independent subjects can proceed within their own budgets. diff --git a/src/pkg/convergence/mutation/boundary.go b/src/pkg/convergence/mutation/boundary.go index ea1e2c6e04..cdc5beecac 100644 --- a/src/pkg/convergence/mutation/boundary.go +++ b/src/pkg/convergence/mutation/boundary.go @@ -42,6 +42,37 @@ type Boundary struct { StuckAfter time.Duration } +// ExecuteJournaled preserves legacy Execute's off-mode passthrough while +// providing an explicit fail-closed contract for new journal-required effects. +func (b *Boundary) ExecuteJournaled(ctx context.Context, claim effects.Claim, effect func(context.Context) (effects.Result, error)) (effects.Result, error) { + if b == nil { + return effects.Result{}, fmt.Errorf("%w: mutation journal unavailable", effects.ErrDenied) + } + frozen := *b + if b.Mode != nil { + frozen.Executor.Mode = b.Mode() + } + frozen.Mode = nil + if !JournalingEnabled(frozen.Executor.Mode) || frozen.Executor.Ledger == nil || frozen.Executor.Journal == nil || + frozen.Executor.Journal.path == "" { + return effects.Result{}, fmt.Errorf("%w: active persistent mutation journal required", effects.ErrDenied) + } + invoked := false + out, err := frozen.Execute(ctx, claim, func(ctx context.Context) (effects.Result, error) { + invoked = true + if err := frozen.Executor.Journal.syncPersistent(); err != nil { + return effects.Result{}, effects.NotApplied(fmt.Errorf("syncing mutation intent before effect: %w", err)) + } + return effect(ctx) + }) + if invoked || err == nil || out.Provenance != "" { + if syncErr := frozen.Executor.Journal.syncPersistent(); syncErr != nil { + return out, fmt.Errorf("mutation journal acknowledgement not synced: %w (execution: %v)", syncErr, err) + } + } + return out, err +} + func (b *Boundary) Execute(ctx context.Context, claim effects.Claim, effect func(context.Context) (effects.Result, error)) (effects.Result, error) { if b == nil { return effect(ctx) diff --git a/src/pkg/convergence/mutation/boundary_journaled_test.go b/src/pkg/convergence/mutation/boundary_journaled_test.go new file mode 100644 index 0000000000..0dbeefb50a --- /dev/null +++ b/src/pkg/convergence/mutation/boundary_journaled_test.go @@ -0,0 +1,83 @@ +package mutation + +import ( + "context" + "errors" + "testing" + + "github.com/hivecommons/hive/pkg/effects" +) + +func TestBoundaryJournalRequiredRefusesOffAndMissingState(t *testing.T) { + claim := effects.Claim{Repo: "o/r", Kind: effects.KindBranchUpdate, Target: "refs/heads/v5", Actor: "integration-aware"} + for _, state := range []string{"nil", "off", "missing-ledger", "missing-journal", "nonpersistent"} { + t.Run(state, func(t *testing.T) { + boundary := testBoundary(t, "enforce") + switch state { + case "nil": + boundary = nil + case "off": + boundary.Executor.Mode = "off" + case "missing-ledger": + boundary.Executor.Ledger = nil + case "missing-journal": + boundary.Executor.Journal = nil + case "nonpersistent": + boundary.Executor.Journal.path = "" + } + _, err := boundary.ExecuteJournaled(context.Background(), claim, func(context.Context) (effects.Result, error) { + t.Fatal("required journal was bypassed") + return effects.Result{}, nil + }) + if !errors.Is(err, effects.ErrDenied) { + t.Fatalf("state=%s did not fail closed: %v", state, err) + } + }) + } +} + +func TestBoundaryJournalRequiredFreezesModeAndReplays(t *testing.T) { + boundary := testBoundary(t, "enforce") + mode, reads, calls := "enforce", 0, 0 + boundary.Mode = func() string { + reads++ + return mode + } + claim := effects.Claim{Repo: "o/r", Kind: effects.KindBranchUpdate, Target: "refs/heads/v5", Actor: "integration-aware"} + apply := func(context.Context) (effects.Result, error) { + calls++ + mode = "off" + return effects.Result{Provenance: "tested-sha"}, nil + } + out, err := boundary.ExecuteJournaled(context.Background(), claim, apply) + if err != nil || out.Provenance != "tested-sha" || reads != 1 || calls != 1 { + t.Fatalf("mode was not frozen: result=%+v err=%v reads=%d calls=%d", out, err, reads, calls) + } + op, found := boundary.Executor.Journal.Get(boundaryEffect(claim).LogicalID()) + if !found || op.Status != StatusApplied || op.Result != "tested-sha" { + t.Fatalf("callback mode change lost the journal: %+v found=%v", op, found) + } + if _, err := boundary.ExecuteJournaled(context.Background(), claim, apply); !errors.Is(err, effects.ErrDenied) || calls != 1 { + t.Fatalf("off-mode journal-required effect ran: err=%v calls=%d", err, calls) + } + mode = "enforce" + reopened, err := OpenJournal(boundary.Executor.Journal.path) + if err != nil { + t.Fatal(err) + } + boundary.Executor.Journal = reopened + if _, err := boundary.ExecuteJournaled(context.Background(), claim, apply); err != nil || calls != 1 { + t.Fatalf("journal replay repeated the external effect: err=%v calls=%d", err, calls) + } +} + +func TestJournalRequiredSyncRefusesMissingState(t *testing.T) { + boundary := testBoundary(t, "enforce") + if err := boundary.Executor.Journal.syncPersistent(); err == nil { + t.Fatal("missing journal file was considered synced") + } + boundary.Executor.Journal.path = "" + if err := boundary.Executor.Journal.syncPersistent(); err == nil { + t.Fatal("empty journal path was considered synced") + } +} diff --git a/src/pkg/convergence/mutation/journal.go b/src/pkg/convergence/mutation/journal.go index f7adbcd18f..3b44649e45 100644 --- a/src/pkg/convergence/mutation/journal.go +++ b/src/pkg/convergence/mutation/journal.go @@ -610,3 +610,39 @@ func (j *Journal) persistLocked() error { } return os.Rename(tmpPath, j.path) } + +// syncPersistent is opt-in for journal-required effects. Keep legacy persistence +// unchanged, but sync both the latest snapshot and its renamed directory entry +// before these effects run and before acknowledging their result. +func (j *Journal) syncPersistent() error { + if j == nil || j.path == "" { + return fmt.Errorf("persistent mutation journal path required") + } + j.mu.Lock() + defer j.mu.Unlock() + unlock, err := j.lockAndRefreshLocked() + if err != nil { + return err + } + defer unlock() + file, err := os.Open(j.path) + if err != nil { + return fmt.Errorf("opening mutation journal to sync: %w", err) + } + if err := file.Sync(); err != nil { + _ = file.Close() + return fmt.Errorf("syncing mutation journal: %w", err) + } + if err := file.Close(); err != nil { + return err + } + directory, err := os.Open(filepath.Dir(j.path)) + if err != nil { + return err + } + defer directory.Close() + if err := directory.Sync(); err != nil { + return fmt.Errorf("syncing mutation journal directory: %w", err) + } + return nil +} diff --git a/src/pkg/effects/alias_test.go b/src/pkg/effects/alias_test.go index d70a62a334..33c165c2c9 100644 --- a/src/pkg/effects/alias_test.go +++ b/src/pkg/effects/alias_test.go @@ -25,4 +25,12 @@ func TestAliasesAreTheCruxTypes(t *testing.T) { if ErrDenied != cruxeffects.ErrDenied || KindBranchPush != cruxeffects.KindBranchPush { t.Fatal("alias values differ from the Crux leaf") } + var journaled JournaledBoundary = LoggingBoundary{} + var cruxJournaled cruxeffects.JournaledBoundary = journaled + if _, err := cruxJournaled.ExecuteJournaled(context.Background(), Claim{}, func(context.Context) (Result, error) { + t.Fatal("missing journal invoked an effect through the alias") + return Result{}, nil + }); !errors.Is(err, ErrDenied) { + t.Fatalf("journal-required alias lost the denial: %v", err) + } } diff --git a/src/pkg/effects/effects.go b/src/pkg/effects/effects.go index 0f57a8f096..a7066d3756 100644 --- a/src/pkg/effects/effects.go +++ b/src/pkg/effects/effects.go @@ -31,17 +31,18 @@ var ( ) type ( - Boundary = cruxeffects.Boundary - Claim = cruxeffects.Claim - Expirer = cruxeffects.Expirer - ExternalState = cruxeffects.ExternalState - LoggingBoundary = cruxeffects.LoggingBoundary - Lookup = cruxeffects.Lookup - NoopBoundary = cruxeffects.NoopBoundary - Reconciler = cruxeffects.Reconciler - Recorder = cruxeffects.Recorder - Result = cruxeffects.Result - Stats = cruxeffects.Stats + Boundary = cruxeffects.Boundary + JournaledBoundary = cruxeffects.JournaledBoundary + Claim = cruxeffects.Claim + Expirer = cruxeffects.Expirer + ExternalState = cruxeffects.ExternalState + LoggingBoundary = cruxeffects.LoggingBoundary + Lookup = cruxeffects.Lookup + NoopBoundary = cruxeffects.NoopBoundary + Reconciler = cruxeffects.Reconciler + Recorder = cruxeffects.Recorder + Result = cruxeffects.Result + Stats = cruxeffects.Stats ) var ( diff --git a/src/pkg/github/integration_promotion.go b/src/pkg/github/integration_promotion.go index 48137bddfa..3b990a0796 100644 --- a/src/pkg/github/integration_promotion.go +++ b/src/pkg/github/integration_promotion.go @@ -67,7 +67,8 @@ func integrationPromotionJournaled(boundary effects.Boundary) bool { default: _, reconciles := boundary.(effects.Reconciler) _, looksUp := boundary.(effects.Lookup) - return reconciles && looksUp + _, requiresJournal := boundary.(effects.JournaledBoundary) + return reconciles && looksUp && requiresJournal } } } @@ -174,7 +175,11 @@ func (c *Client) PromoteIntegrationStep(ctx context.Context, p IntegrationPromot } return effects.Result{Provenance: p.TestedSHA}, nil } - out, err := effects.Execute(ctx, boundary, claim, apply) + journaled, ok := boundary.(effects.JournaledBoundary) + if !ok { + return effects.Result{}, fmt.Errorf("integration promotion requires journaled execution") + } + out, err := journaled.ExecuteJournaled(ctx, claim, apply) if !errors.Is(err, effects.ErrNeedsReconciliation) { return out, err } @@ -198,5 +203,5 @@ func (c *Client) PromoteIntegrationStep(ctx context.Context, p IntegrationPromot if err := effects.Reconcile(ctx, boundary, claim, state); err != nil { return out, err } - return effects.Execute(ctx, boundary, claim, apply) + return journaled.ExecuteJournaled(ctx, claim, apply) } diff --git a/src/pkg/github/integration_promotion_test.go b/src/pkg/github/integration_promotion_test.go index 018b719f93..a1a9ae8c59 100644 --- a/src/pkg/github/integration_promotion_test.go +++ b/src/pkg/github/integration_promotion_test.go @@ -22,6 +22,10 @@ type integrationPromotionJournal struct { claim effects.Claim } +func (j *integrationPromotionJournal) ExecuteJournaled(ctx context.Context, claim effects.Claim, apply func(context.Context) (effects.Result, error)) (effects.Result, error) { + return j.Execute(ctx, claim, apply) +} + func (j *integrationPromotionJournal) Execute(ctx context.Context, claim effects.Claim, apply func(context.Context) (effects.Result, error)) (effects.Result, error) { j.claim = claim if j.unresolved { From 6ba38d4e37b13513d19baf453310ef7375d1ff43 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Fri, 30 Oct 2026 21:23:31 -0400 Subject: [PATCH 3/4] =?UTF-8?q?=F0=9F=90=9B=20fix:=20atomically=20fence=20?= =?UTF-8?q?candidate=20author=20head=20during=20promotion?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andy Anderson --- src/docs/integration-orchestration.md | 15 +++++-- src/pkg/github/integration_promotion.go | 15 ++++++- src/pkg/github/integration_promotion_test.go | 46 ++++++++++++++++++-- 3 files changed, 69 insertions(+), 7 deletions(-) diff --git a/src/docs/integration-orchestration.md b/src/docs/integration-orchestration.md index e816ca0c54..0b9c8c1912 100644 --- a/src/docs/integration-orchestration.md +++ b/src/docs/integration-orchestration.md @@ -24,11 +24,19 @@ 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. +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. +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 +in the same repository transaction and are explicitly unsupported by this first +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, subject, policy and generation through the existing effects boundary. +author head/repository/ref, subject, policy and generation through the existing +effects boundary. `clientMutationId` binds acknowledgement; it is **not** provider idempotency. A durable boundary and non-nil live eligibility guard are mandatory. The @@ -37,7 +45,8 @@ 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 permit a fallback, force update or privilege expansion. Destination CAS does -not atomically snapshot GitHub's independently mutable PR/review/hold fields: +not atomically snapshot GitHub's independently mutable PR/review/hold fields +other than the separately fenced same-repository source ref: their current freshness contract and any remaining race must be explicit, not misrepresented as a multi-resource transaction. diff --git a/src/pkg/github/integration_promotion.go b/src/pkg/github/integration_promotion.go index 3b990a0796..17614fb600 100644 --- a/src/pkg/github/integration_promotion.go +++ b/src/pkg/github/integration_promotion.go @@ -24,6 +24,8 @@ type IntegrationPromotion struct { TestedSHA string TestedTree string AuthorHead string + HeadRepo string + HeadRef string SubjectID string Policy string Generation uint64 @@ -37,10 +39,16 @@ type IntegrationPromotionGuard func(context.Context, IntegrationPromotion) error var ErrIntegrationDestinationChanged = errors.New("integration destination changed; reconcile the candidate before retrying") +var ErrIntegrationHeadFenceUnavailable = errors.New("integration atomic author-head fencing requires a same-repository branch") + func (p IntegrationPromotion) validate() error { + if !strings.EqualFold(p.HeadRepo, p.Repo) { + return ErrIntegrationHeadFenceUnavailable + } parts := strings.Split(p.Repo, "/") if len(parts) != 2 || parts[0] == "" || parts[1] == "" || strings.ContainsAny(p.Repo, " \t\r\n") || !integrationPromotionBranch(p.Base) || + !integrationPromotionBranch(p.HeadRef) || p.HeadRef == p.Base || !integrationPromotionOID(p.ExpectedSHA) || !integrationPromotionOID(p.TestedSHA) || !integrationPromotionOID(p.TestedTree) || !integrationPromotionOID(p.AuthorHead) || p.ExpectedSHA == p.TestedSHA || p.ExpectedSHA == p.AuthorHead || @@ -105,6 +113,7 @@ func (p IntegrationPromotion) claim() effects.Claim { "protocol": IntegrationPromotionProtocol, "expected_sha": p.ExpectedSHA, "tested_sha": p.TestedSHA, "tested_tree": p.TestedTree, "author_head": p.AuthorHead, "subject": p.SubjectID, + "head_repo": p.HeadRepo, "head_ref": p.HeadRef, "policy": p.Policy, "generation": fmt.Sprint(p.Generation), }, } @@ -114,7 +123,8 @@ func (p IntegrationPromotion) claim() effects.Claim { // authority. Callers must explicitly opt in and supply a durable mutation // boundary and the live guard; no current automerge lane calls this method. // -// GitHub's updateRefs is atomic and checks beforeOid server-side. REST UpdateRef, +// GitHub's updateRefs atomically checks the destination and a no-op author-ref +// fence server-side. Cross-repository fork refs cannot participate. REST UpdateRef, // a PR merge's expected author head, and createCommitOnBranch do not promote // this existing tested commit with a destination compare-and-swap. func (c *Client) PromoteIntegrationStep(ctx context.Context, p IntegrationPromotion, boundary effects.Boundary, guard IntegrationPromotionGuard) (effects.Result, error) { @@ -165,6 +175,9 @@ func (c *Client) PromoteIntegrationStep(ctx context.Context, p IntegrationPromot "refUpdates": []map[string]any{{ "name": "refs/heads/" + p.Base, "beforeOid": p.ExpectedSHA, "afterOid": p.TestedSHA, "force": false, + }, { + "name": "refs/heads/" + p.HeadRef, "beforeOid": p.AuthorHead, + "afterOid": p.AuthorHead, "force": false, }}, }}, &out) if err != nil { diff --git a/src/pkg/github/integration_promotion_test.go b/src/pkg/github/integration_promotion_test.go index a1a9ae8c59..ba972cfcee 100644 --- a/src/pkg/github/integration_promotion_test.go +++ b/src/pkg/github/integration_promotion_test.go @@ -56,6 +56,7 @@ func (j *integrationPromotionJournal) LookupApplied(context.Context, effects.Cla type integrationPromotionFixture struct { request IntegrationPromotion ref string + headRef string tree string parents []string repoID string @@ -71,6 +72,7 @@ func integrationPromotionRequest() IntegrationPromotion { Repo: "o/r", Base: "v5", ExpectedSHA: strings.Repeat("a", 40), TestedSHA: strings.Repeat("b", 40), TestedTree: strings.Repeat("c", 40), AuthorHead: strings.Repeat("d", 40), SubjectID: "subject-1", + HeadRepo: "o/r", HeadRef: "feature/member-1", Policy: "policy-1", Generation: 1, } } @@ -79,6 +81,7 @@ func promotionFixture() *integrationPromotionFixture { p := integrationPromotionRequest() return &integrationPromotionFixture{ request: p, ref: p.ExpectedSHA, tree: p.TestedTree, + headRef: p.AuthorHead, parents: []string{p.ExpectedSHA, p.AuthorHead}, repoID: "R_repository", } } @@ -126,7 +129,7 @@ func (f *integrationPromotionFixture) server(t *testing.T) *httptest.Server { _, _ = w.Write([]byte(f.reply)) return } - if f.ref != f.request.ExpectedSHA { + if f.ref != f.request.ExpectedSHA || f.headRef != f.request.AuthorHead { _, _ = w.Write([]byte(`{"errors":[{"type":"UNPROCESSABLE","message":"beforeOid mismatch"}]}`)) return } @@ -167,8 +170,8 @@ func TestIntegrationPromotionExactCASAndJournalReplay(t *testing.T) { f.mu.Lock() defer f.mu.Unlock() updates, ok := f.input["refUpdates"].([]any) - if !ok || len(updates) != 1 { - t.Fatalf("not a single bounded CAS: %#v", f.input) + if !ok || len(updates) != 2 { + t.Fatalf("not a bounded destination/head CAS: %#v", f.input) } update, ok := updates[0].(map[string]any) if !ok || update["beforeOid"] != f.request.ExpectedSHA || @@ -176,8 +179,15 @@ func TestIntegrationPromotionExactCASAndJournalReplay(t *testing.T) { update["name"] != "refs/heads/v5" || f.input["repositoryId"] != "R_repository" { t.Fatalf("unsafe provider mutation: %#v", f.input) } + head, ok := updates[1].(map[string]any) + if !ok || head["name"] != "refs/heads/"+f.request.HeadRef || + head["beforeOid"] != f.request.AuthorHead || head["afterOid"] != f.request.AuthorHead || head["force"] != false { + t.Fatalf("missing atomic author-head fence: %#v", f.input) + } if journal.claim.Kind != effects.KindBranchUpdate || journal.claim.Actor != "integration-aware" || journal.claim.Inputs["subject"] != f.request.SubjectID || + journal.claim.Inputs["head_repo"] != f.request.HeadRepo || + journal.claim.Inputs["head_ref"] != f.request.HeadRef || journal.claim.Inputs["protocol"] != IntegrationPromotionProtocol { t.Fatalf("missing mutation provenance: %+v", journal.claim) } @@ -258,6 +268,28 @@ func TestIntegrationPromotionDestinationMovesAfterLiveGuard(t *testing.T) { } } +func TestIntegrationPromotionAuthorHeadMovesAfterLiveGuard(t *testing.T) { + f := promotionFixture() + server := f.server(t) + defer server.Close() + journal := new(integrationPromotionJournal) + _, err := testClient(t, server.URL).PromoteIntegrationStep(context.Background(), f.request, journal, + func(context.Context, IntegrationPromotion) error { + f.mu.Lock() + defer f.mu.Unlock() + f.headRef = strings.Repeat("e", 40) + return nil + }) + if err == nil || !journal.unresolved || f.writes.Load() != 1 { + t.Fatalf("author head race was not refused: err=%v unresolved=%v", err, journal.unresolved) + } + f.mu.Lock() + defer f.mu.Unlock() + if f.ref != f.request.ExpectedSHA { + t.Fatal("moved author head did not atomically prevent destination promotion") + } +} + func TestIntegrationPromotionReconcilesWithoutBlindTTLRetry(t *testing.T) { for _, state := range []string{"applied", "not-applied", "changed", "unavailable", "journal-failed"} { t.Run(state, func(t *testing.T) { @@ -297,6 +329,11 @@ func TestIntegrationPromotionReconcilesWithoutBlindTTLRetry(t *testing.T) { } func TestIntegrationPromotionInvalidRequestsHaveNoEffects(t *testing.T) { + fork := integrationPromotionRequest() + fork.HeadRepo = "fork/r" + if !errors.Is(fork.validate(), ErrIntegrationHeadFenceUnavailable) { + t.Fatal("fork head lost its explicit unsupported atomic-fence reason") + } for _, branch := range []string{"", "@", "/v5", "v5/", "v5.", "v5..next", ".hidden", "a/.hidden", "a.lock", "a//b", "v5@{1}", "a b", "a\x01b", "a\x7fb"} { if integrationPromotionBranch(branch) { t.Errorf("accepted invalid branch %q", branch) @@ -308,6 +345,9 @@ func TestIntegrationPromotionInvalidRequestsHaveNoEffects(t *testing.T) { for _, change := range []func(*IntegrationPromotion){ func(p *IntegrationPromotion) { p.Repo = "r" }, func(p *IntegrationPromotion) { p.Base = "" }, + func(p *IntegrationPromotion) { p.HeadRepo = "fork/r" }, + func(p *IntegrationPromotion) { p.HeadRef = p.Base }, + func(p *IntegrationPromotion) { p.HeadRef = "" }, func(p *IntegrationPromotion) { p.ExpectedSHA = strings.Repeat("0", 40) }, func(p *IntegrationPromotion) { p.TestedSHA = strings.Repeat("B", 40) }, func(p *IntegrationPromotion) { p.TestedTree = "short" }, From cb02d52e75da65fe7ad1d3d3f692848a8a66323a Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Fri, 30 Oct 2026 21:44:45 -0400 Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=90=9B=20fix:=20bind=20promotion=20to?= =?UTF-8?q?=20the=20resolved=20repository=20scope?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andy Anderson --- src/docs/integration-orchestration.md | 2 + src/pkg/github/integration_promotion.go | 23 +++++-- src/pkg/github/integration_promotion_test.go | 66 +++++++++++++++----- 3 files changed, 71 insertions(+), 20 deletions(-) diff --git a/src/docs/integration-orchestration.md b/src/docs/integration-orchestration.md index 0b9c8c1912..df2c85890b 100644 --- a/src/docs/integration-orchestration.md +++ b/src/docs/integration-orchestration.md @@ -38,6 +38,8 @@ claim binds protocol, repository/base, expected destination, tested commit/tree, author head/repository/ref, 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 diff --git a/src/pkg/github/integration_promotion.go b/src/pkg/github/integration_promotion.go index 17614fb600..b1c88a9cb0 100644 --- a/src/pkg/github/integration_promotion.go +++ b/src/pkg/github/integration_promotion.go @@ -45,9 +45,7 @@ func (p IntegrationPromotion) validate() error { if !strings.EqualFold(p.HeadRepo, p.Repo) { return ErrIntegrationHeadFenceUnavailable } - parts := strings.Split(p.Repo, "/") - if len(parts) != 2 || parts[0] == "" || parts[1] == "" || - strings.ContainsAny(p.Repo, " \t\r\n") || !integrationPromotionBranch(p.Base) || + if !integrationPromotionRepo(p.Repo) || !integrationPromotionBranch(p.Base) || !integrationPromotionBranch(p.HeadRef) || p.HeadRef == p.Base || !integrationPromotionOID(p.ExpectedSHA) || !integrationPromotionOID(p.TestedSHA) || !integrationPromotionOID(p.TestedTree) || !integrationPromotionOID(p.AuthorHead) || @@ -60,6 +58,23 @@ func (p IntegrationPromotion) validate() error { return nil } +func integrationPromotionRepo(repo string) bool { + parts := strings.Split(repo, "/") + if len(parts) != 2 || parts[0] == "" || parts[1] == "" || parts[1] == "." || parts[1] == ".." { + return false + } + for i, part := range parts { + for _, character := range part { + if character >= 'a' && character <= 'z' || character >= 'A' && character <= 'Z' || + character >= '0' && character <= '9' || character == '-' || i == 1 && (character == '.' || character == '_') { + continue + } + return false + } + } + return true +} + func integrationPromotionJournaled(boundary effects.Boundary) bool { for { switch b := boundary.(type) { @@ -145,7 +160,7 @@ func (c *Client) PromoteIntegrationStep(ctx context.Context, p IntegrationPromot if err != nil { return effects.Result{}, err } - if repository.GetNodeID() == "" { + if repository.GetNodeID() == "" || !strings.EqualFold(repository.GetFullName(), p.Repo) { return effects.Result{}, fmt.Errorf("integration repository identity unavailable") } commit, _, err := c.client.Git.GetCommit(ctx, owner, repo, p.TestedSHA) diff --git a/src/pkg/github/integration_promotion_test.go b/src/pkg/github/integration_promotion_test.go index ba972cfcee..c68f9bb64b 100644 --- a/src/pkg/github/integration_promotion_test.go +++ b/src/pkg/github/integration_promotion_test.go @@ -54,17 +54,18 @@ func (j *integrationPromotionJournal) LookupApplied(context.Context, effects.Cla } type integrationPromotionFixture struct { - request IntegrationPromotion - ref string - headRef string - tree string - parents []string - repoID string - errorAt string - reply string - mu sync.Mutex - input map[string]any - writes atomic.Int32 + request IntegrationPromotion + ref string + headRef string + tree string + parents []string + repoID string + repoName string + errorAt string + reply string + mu sync.Mutex + input map[string]any + writes atomic.Int32 } func integrationPromotionRequest() IntegrationPromotion { @@ -82,7 +83,7 @@ func promotionFixture() *integrationPromotionFixture { return &integrationPromotionFixture{ request: p, ref: p.ExpectedSHA, tree: p.TestedTree, headRef: p.AuthorHead, - parents: []string{p.ExpectedSHA, p.AuthorHead}, repoID: "R_repository", + parents: []string{p.ExpectedSHA, p.AuthorHead}, repoID: "R_repository", repoName: p.Repo, } } @@ -97,7 +98,7 @@ func (f *integrationPromotionFixture) server(t *testing.T) *httptest.Server { } switch r.URL.Path { case "/repos/o/r": - _ = json.NewEncoder(w).Encode(map[string]any{"node_id": f.repoID}) + _ = json.NewEncoder(w).Encode(map[string]any{"node_id": f.repoID, "full_name": f.repoName}) case "/repos/o/r/git/commits/" + f.request.TestedSHA: parents := make([]map[string]string, 0, len(f.parents)) for _, parent := range f.parents { @@ -129,11 +130,35 @@ func (f *integrationPromotionFixture) server(t *testing.T) *httptest.Server { _, _ = w.Write([]byte(f.reply)) return } - if f.ref != f.request.ExpectedSHA || f.headRef != f.request.AuthorHead { - _, _ = w.Write([]byte(`{"errors":[{"type":"UNPROCESSABLE","message":"beforeOid mismatch"}]}`)) + updates, ok := f.input["refUpdates"].([]any) + if !ok { + http.Error(w, "missing ref updates", http.StatusBadRequest) return } - f.ref = f.request.TestedSHA + refs := map[string]string{ + "refs/heads/" + f.request.Base: f.ref, + "refs/heads/" + f.request.HeadRef: f.headRef, + } + for _, raw := range updates { + update, valid := raw.(map[string]any) + name, named := update["name"].(string) + current, exists := refs[name] + if !valid || !named || !exists || current != update["beforeOid"] || update["force"] != false { + _, _ = w.Write([]byte(`{"errors":[{"type":"UNPROCESSABLE","message":"beforeOid mismatch"}]}`)) + return + } + } + for _, raw := range updates { + update, _ := raw.(map[string]any) + name, _ := update["name"].(string) + after, valid := update["afterOid"].(string) + if !valid { + http.Error(w, "invalid target", http.StatusBadRequest) + return + } + refs[name] = after + } + f.ref, f.headRef = refs["refs/heads/"+f.request.Base], refs["refs/heads/"+f.request.HeadRef] _ = json.NewEncoder(w).Encode(map[string]any{"data": map[string]any{ "updateRefs": map[string]any{"clientMutationId": f.input["clientMutationId"]}, }}) @@ -202,6 +227,7 @@ func TestIntegrationPromotionRefusesIncompleteOrChangedSubjects(t *testing.T) { {"reversed-parents", func(f *integrationPromotionFixture) { f.parents[0], f.parents[1] = f.parents[1], f.parents[0] }}, {"wrong-parent-count", func(f *integrationPromotionFixture) { f.parents = f.parents[:1] }}, {"unknown-repository", func(f *integrationPromotionFixture) { f.repoID = "" }}, + {"renamed-repository", func(f *integrationPromotionFixture) { f.repoName = "another/repository" }}, {"repository-read-failed", func(f *integrationPromotionFixture) { f.errorAt = "/repos/o/r" }}, {"commit-read-failed", func(f *integrationPromotionFixture) { f.errorAt = "/repos/o/r/git/commits/" + f.request.TestedSHA }}, } { @@ -329,6 +355,14 @@ func TestIntegrationPromotionReconcilesWithoutBlindTTLRetry(t *testing.T) { } func TestIntegrationPromotionInvalidRequestsHaveNoEffects(t *testing.T) { + for _, repo := range []string{"r", "o/r/extra", "o/r?query", "o/r#fragment", "o/r%2fother", "../r", "o/..", "o/.", "o/r\x01"} { + if integrationPromotionRepo(repo) { + t.Errorf("accepted ambiguous repository %q", repo) + } + } + if !integrationPromotionRepo("Owner/repo.name_1") { + t.Fatal("valid repository rejected") + } fork := integrationPromotionRequest() fork.HeadRepo = "fork/r" if !errors.Is(fork.validate(), ErrIntegrationHeadFenceUnavailable) {