diff --git a/.github/scripts/embedded-storage-test-shards.txt b/.github/scripts/embedded-storage-test-shards.txt index 439186a24..96250f443 100644 --- a/.github/scripts/embedded-storage-test-shards.txt +++ b/.github/scripts/embedded-storage-test-shards.txt @@ -528,6 +528,7 @@ 15 15 TestEmbeddedDependencyEditorAcceptsAnExternalTarget 15 15 TestEmbeddedDependencyEditorRefusesSelfDependencyWithTheProbeSkipped 15 15 TestEmbeddedDependencyEditorRepeatsWithinOneRequestCollapse +15 15 TestEmbeddedDependencyEditorSameTypeReAddWithChangedThreadMintsOneVersion 15 15 TestEmbeddedIssueOperationsUpdateLabelPatchOrdering 15 15 TestEmbeddedMigrateConsent_BehindAndDirtyWorkingSetReconcileRecovers 15 15 TestEmbeddedMigrateSelfHealsAfterMidPassFault_4566 diff --git a/backend/conformance/batch_apply_contract.go b/backend/conformance/batch_apply_contract.go index 5bb9e7056..49ed97a4f 100644 --- a/backend/conformance/batch_apply_contract.go +++ b/backend/conformance/batch_apply_contract.go @@ -6,6 +6,7 @@ import ( "errors" "fmt" "reflect" + "strings" "testing" "github.com/steveyegge/beads/internal/types" @@ -1525,10 +1526,11 @@ func RunBatchApplyNormalizesTheWaitsForGate(t *testing.T, ctx context.Context, f // regression for HIGH-2: a waits-for DepAddItem must only acquire // metadata.spawner_id when the caller explicitly named a spawner // (HasSpawner=true, which bd create --graph sets when the plan declares -// edges[].spawner_key/spawner_id). An edge with no named spawner must keep -// its gate-only metadata untouched — stamping it unconditionally from the -// resolved target caused unnecessary rewrite/version churn when gc -// re-applies the same edge (see CHANGELOG.md). +// edges[].spawner_key/spawner_id, as does an embedder lowering such a plan +// onto this role). An edge with no named spawner must keep its gate-only +// metadata untouched — stamping it unconditionally from the resolved target +// caused unnecessary rewrite/version churn when gc re-applies the same edge +// (see CHANGELOG.md). func RunBatchApplyStampsSpawnerIDOnlyWhenNamed(t *testing.T, ctx context.Context, fixture BatchApplyFixture) { t.Helper() spawner := fixture.IssuePrefix + "-spawner-named" @@ -1578,6 +1580,157 @@ func RunBatchApplyStampsSpawnerIDOnlyWhenNamed(t *testing.T, ctx context.Context } } +// RunBatchApplyCarriesThreadIDOntoTheStoredEdge pins DepAddItem.ThreadID +// (the 2026-10 Opus-review HIGH-2 finding): a conversation-threading id named +// on a dep_add item must land on the stored dependency row's own thread_id +// column, and an item that names none must store none. ThreadID is a plain +// column read independently of HasSpawner/Metadata, so this is its own case +// rather than a clause folded onto the spawner one above. +// +// Wired onto the http leg this exercises BOTH halves of the wire at once: the +// client's applyDepAddItemBody encode (batchapplier.go) and the server's +// applyDepAddItemMembers decode (internal/httpapi/batch_apply.go) must each +// carry the field, because either one silently dropping it leaves the stored +// column blank and fails the assertion below. +func RunBatchApplyCarriesThreadIDOntoTheStoredEdge(t *testing.T, ctx context.Context, fixture BatchApplyFixture) { + t.Helper() + source := fixture.IssuePrefix + "-thread-source" + target := fixture.IssuePrefix + "-thread-target" + batchApplySeedIssue(t, ctx, fixture, source, types.StatusOpen) + batchApplySeedIssue(t, ctx, fixture, target, types.StatusOpen) + + const thread = "thread-conv-1" + batchApplyMust(t, ctx, fixture, publicops.ApplyBatchRequest{ + Actor: "apply-writer", + Items: []publicops.ApplyItem{ + {Kind: publicops.ItemDepAdd, DepAdd: &publicops.DepAddItem{ + Source: publicops.Ref{ID: source}, Target: publicops.Ref{ID: target}, + Type: publicops.DepBlocks, ThreadID: thread, + }}, + }, + }) + if got := batchApplyEdgeThreadID(t, ctx, fixture, source, target); got != thread { + t.Errorf("stored edge thread_id = %q, want %q", got, thread) + } + + source2 := fixture.IssuePrefix + "-thread-none-source" + target2 := fixture.IssuePrefix + "-thread-none-target" + batchApplySeedIssue(t, ctx, fixture, source2, types.StatusOpen) + batchApplySeedIssue(t, ctx, fixture, target2, types.StatusOpen) + batchApplyMust(t, ctx, fixture, publicops.ApplyBatchRequest{ + Actor: "apply-writer", + Items: []publicops.ApplyItem{ + batchApplyDepAdd(publicops.Ref{ID: source2}, publicops.Ref{ID: target2}, publicops.DepBlocks, ""), + }, + }) + if got := batchApplyEdgeThreadID(t, ctx, fixture, source2, target2); got != "" { + t.Errorf("an edge naming no thread must not stamp thread_id, got %q", got) + } +} + +// RunBatchApplyCarriesThreadIDOntoAnExistingEdge pins DepAddItem.ThreadID on +// the re-add arm: a dep_add naming an edge that already exists with the same +// type is the idempotent re-add, and a thread it names still has to reach the +// stored row. That arm once compared and rewrote metadata alone, so a +// thread-only re-add was a silent no-op and a re-add moving both landed the +// metadata and dropped the thread — on the very path gc re-applies its plans +// through. +// +// The steps run on ONE edge, each from the state the step before it left: a +// thread-only re-add puts a thread on an edge that had none, a re-add moving +// the gate and the thread lands both, and a re-add naming no thread keeps the +// stored one, because an empty ThreadID names no thread rather than asking for +// none. +func RunBatchApplyCarriesThreadIDOntoAnExistingEdge(t *testing.T, ctx context.Context, fixture BatchApplyFixture) { + t.Helper() + source := fixture.IssuePrefix + "-rethread-source" + spawner := fixture.IssuePrefix + "-rethread-spawner" + batchApplySeedIssue(t, ctx, fixture, source, types.StatusOpen) + batchApplySeedIssue(t, ctx, fixture, spawner, types.StatusOpen) + + add := func(gate, thread string) { + t.Helper() + batchApplyMust(t, ctx, fixture, publicops.ApplyBatchRequest{ + Actor: "apply-writer", + Items: []publicops.ApplyItem{ + {Kind: publicops.ItemDepAdd, DepAdd: &publicops.DepAddItem{ + Source: publicops.Ref{ID: source}, Target: publicops.Ref{ID: spawner}, + Type: publicops.DepWaitsFor, Metadata: `{"gate":"` + gate + `"}`, ThreadID: thread, + }}, + }, + }) + } + assertEdge := func(step, wantGate, wantThread string) { + t.Helper() + assertBatchApplyEdgeCount(t, ctx, fixture, source, spawner, 1) + stored := batchApplyEdgeMetadata(t, ctx, fixture, source, spawner) + var meta types.WaitsForMeta + if err := json.Unmarshal([]byte(stored), &meta); err != nil { + t.Fatalf("%s: stored waits-for metadata %q is not a gate object: %v", step, stored, err) + } + if meta.Gate != wantGate { + t.Errorf("%s: stored gate = %q (metadata %q), want %q", step, meta.Gate, stored, wantGate) + } + if got := batchApplyEdgeThreadID(t, ctx, fixture, source, spawner); got != wantThread { + t.Errorf("%s: stored edge thread_id = %q, want %q", step, got, wantThread) + } + } + + add(types.WaitsForAllChildren, "") + assertEdge("the first add, naming no thread", types.WaitsForAllChildren, "") + + add(types.WaitsForAllChildren, "thread-conv-1") + assertEdge("a re-add moving the thread alone", types.WaitsForAllChildren, "thread-conv-1") + + add(types.WaitsForAnyChildren, "thread-conv-2") + assertEdge("a re-add moving the gate and the thread", types.WaitsForAnyChildren, "thread-conv-2") + + add(types.WaitsForAnyChildren, "") + assertEdge("a re-add naming no thread", types.WaitsForAnyChildren, "thread-conv-2") +} + +// RunBatchApplyRefusesAThreadIDLongerThanItsColumn pins the bound on +// DepAddItem.ThreadID: one longer than the thread_id column holds is +// ErrValidation and writes no edge, on every leg alike. The http leg's decode +// refused it as a typed 400 while the local legs carried it to the write, where +// it failed as whatever storage error the column raised, mid-transaction — two +// error classes for one request. The shared plan bounds it now, before any +// database work. +// +// The positive half is the same edge with a thread exactly at the bound, which +// lands whole; without it, a role refusing every thread id satisfies the +// refusal. +func RunBatchApplyRefusesAThreadIDLongerThanItsColumn(t *testing.T, ctx context.Context, fixture BatchApplyFixture) { + t.Helper() + source := fixture.IssuePrefix + "-longthread-source" + target := fixture.IssuePrefix + "-longthread-target" + batchApplySeedIssue(t, ctx, fixture, source, types.StatusOpen) + batchApplySeedIssue(t, ctx, fixture, target, types.StatusOpen) + + request := func(thread string) publicops.ApplyBatchRequest { + return publicops.ApplyBatchRequest{ + Actor: "apply-writer", + Items: []publicops.ApplyItem{ + {Kind: publicops.ItemDepAdd, DepAdd: &publicops.DepAddItem{ + Source: publicops.Ref{ID: source}, Target: publicops.Ref{ID: target}, + Type: publicops.DepBlocks, ThreadID: thread, + }}, + }, + } + } + tooLong := strings.Repeat("t", types.MaxFieldLen+1) + if _, err := fixture.BatchApplier.ApplyBatch(ctx, request(tooLong)); !errors.Is(err, publicops.ErrValidation) { + t.Fatalf("a %d-character thread_id: error = %v, want ErrValidation", len(tooLong), err) + } + assertBatchApplyEdgeCount(t, ctx, fixture, source, target, 0) + + atBound := strings.Repeat("t", types.MaxFieldLen) + batchApplyMust(t, ctx, fixture, request(atBound)) + if got := batchApplyEdgeThreadID(t, ctx, fixture, source, target); got != atBound { + t.Errorf("a %d-character thread_id stored as %d characters, want it whole", len(atBound), len(got)) + } +} + // RunBatchApplySplicesAForwardMetadataRef pins the one exception to the // backward-only rule (CreateItem.MetadataRefs): "IT IS THE ONE PLACE A KEY MAY // REACH FORWARD … Every id is minted before any splice is applied, so the @@ -2241,6 +2394,20 @@ func batchApplyEdgeMetadata(t *testing.T, ctx context.Context, fixture BatchAppl return blob } +// batchApplyEdgeThreadID reads the stored thread_id column of one edge, which +// is where DepAddItem.ThreadID has to be visible — a plain column, independent +// of the type-specific Metadata blob batchApplyEdgeMetadata reads. +func batchApplyEdgeThreadID(t *testing.T, ctx context.Context, fixture BatchApplyFixture, source, target string) string { + t.Helper() + var value string + const query = "SELECT COALESCE(thread_id, '') FROM dependencies WHERE issue_id = ?" + + " AND COALESCE(depends_on_issue_id, depends_on_wisp_id, depends_on_external) = ?" + if err := fixture.QueryScalar(ctx, query, []any{source, target}, &value); err != nil { + t.Fatalf("reading edge thread_id for %s -> %s: %v", source, target, err) + } + return value +} + // batchApplyMetadataKey reads the WHOLE metadata blob off a row and reports one // key's raw bytes. The whole blob is read rather than a JSON path extract, // because that is what lets a case see an absent key and a null one as the diff --git a/backend/conformance/dependency_editor_contract.go b/backend/conformance/dependency_editor_contract.go index df2aacb75..e037e9dbe 100644 --- a/backend/conformance/dependency_editor_contract.go +++ b/backend/conformance/dependency_editor_contract.go @@ -531,6 +531,96 @@ func RunDependencyEditorSameTypeReAddWithIdenticalMetadataIsANoOp(t *testing.T, } } +// RunDependencyEditorSameTypeReAddWithChangedThreadMintsOneVersion is the +// thread_id twin of +// RunDependencyEditorSameTypeReAddWithChangedMetadataMintsOneVersion. The row +// carries a thread as well as metadata, and the source issue's version snapshot +// carries each edge's thread_id, so a same-type re-add naming a thread the row +// does not carry is a real mutation on the same terms as a metadata change: +// the leaf updates the row in place, journals the replacement edge, and mints +// EXACTLY ONE version (#5898 leg 2). The re-add arm once compared metadata +// alone, which read that re-add as change-free and dropped the thread. +// +// The metadata is identical across every write, so the thread is the only +// thing that moves. A last re-add names no thread, and is the change-free +// no-op: an empty thread names none rather than asking for none, which is +// what keeps the callers that never carry a thread from erasing one. +// +// It drives the writes through fixture.AddDependency for the reason the +// metadata case gives: publicops.DependencyEdge carries no thread either. +func RunDependencyEditorSameTypeReAddWithChangedThreadMintsOneVersion(t *testing.T, ctx context.Context, fixture DependencyEditorFixture) { + t.Helper() + if fixture.AddDependency == nil { + t.Skip("fixture has no AddDependency hook: a thread is not settable through publicops.DependencyEdge") + } + fixture.SetJournalEnabled(true) + t.Cleanup(func() { fixture.SetJournalEnabled(false) }) + fixture.SetVersionedHistoryEnabled(true) + t.Cleanup(func() { fixture.SetVersionedHistoryEnabled(false) }) + source := fixture.IssuePrefix + "-idemthread-source" + target := fixture.IssuePrefix + "-idemthread-target" + seedDependencyEditorIssue(t, ctx, fixture, source) + seedDependencyEditorIssue(t, ctx, fixture, target) + + const metadata = `{"note":"v1"}` + add := func(thread, refusal string) { + t.Helper() + dep := &types.Dependency{IssueID: source, DependsOnID: target, Type: types.DepBlocks, Metadata: metadata, ThreadID: thread} + if err := fixture.AddDependency(ctx, dep, "writer"); err != nil { + t.Fatalf("%s: %v", refusal, err) + } + assertDependencyEdgeTypedCount(t, ctx, fixture, "dependencies", source, target, string(types.DepBlocks), 1) + assertDependencyEditorEventCount(t, ctx, fixture, "events", source, types.EventDependencyAdded, 1) + } + storedThread := func() string { + t.Helper() + var thread string + if err := fixture.QueryScalar(ctx, + "SELECT COALESCE(thread_id, '') FROM dependencies WHERE issue_id = ? AND COALESCE(depends_on_issue_id, depends_on_wisp_id, depends_on_external) = ?", + []any{source, target}, &thread); err != nil { + t.Fatalf("read stored thread_id for %s -> %s: %v", source, target, err) + } + return thread + } + journalCount := func() int { + t.Helper() + var count int + if err := fixture.QueryScalar(ctx, + "SELECT COUNT(*) FROM bd_events_journal WHERE issue_id = ? AND op = ?", + []any{source, string(storeops.EventDepAdd)}, &count); err != nil { + t.Fatalf("count bd_events_journal dep_add rows for %s: %v", source, err) + } + return count + } + + add("", "AddDependency first") + assertDependencyEditorJournalCountIsOne(t, ctx, fixture, source, string(storeops.EventDepAdd)) + + versionsBefore := countDependencyEditorIssueVersions(t, ctx, fixture, source) + add("thread-conv-1", "re-adding the same edge with a new thread refused") + if got := storedThread(); got != "thread-conv-1" { + t.Errorf("stored thread_id = %q, want %q: the re-add must persist the new thread, not keep the old", got, "thread-conv-1") + } + if got := journalCount(); got != 2 { + t.Errorf("bd_events_journal dep_add rows for %s = %d, want 2: the thread-changed re-add must journal its own replacement-edge entry", source, got) + } + if delta := countDependencyEditorIssueVersions(t, ctx, fixture, source) - versionsBefore; delta != 1 { + t.Errorf("issue_versions rows for %s went %d -> %d (delta %d), want a delta of 1: the thread genuinely changed, so the re-add is a real mutation of the source issue and must mint exactly one version (#5898 leg 2)", source, versionsBefore, versionsBefore+delta, delta) + } + + versionsBefore = countDependencyEditorIssueVersions(t, ctx, fixture, source) + add("", "re-adding the same edge naming no thread refused") + if got := storedThread(); got != "thread-conv-1" { + t.Errorf("stored thread_id after a re-add naming no thread = %q, want %q kept", got, "thread-conv-1") + } + if got := journalCount(); got != 2 { + t.Errorf("bd_events_journal dep_add rows for %s = %d after a change-free re-add, want 2 still", source, got) + } + if delta := countDependencyEditorIssueVersions(t, ctx, fixture, source) - versionsBefore; delta != 0 { + t.Errorf("issue_versions rows for %s went %d -> %d (delta %d) on a re-add naming no thread, want a delta of 0: it keeps the stored thread, so nothing changed (#5898 R3)", source, versionsBefore, versionsBefore+delta, delta) + } +} + // RunDependencyEditorRepeatsWithinOneRequestCollapse pins the clause that // answers a request naming ONE PAIR TWICE. The same-type re-add rule is stated // for the pair rather than for the call, so the second occurrence inside a diff --git a/backend/conformance/role_bundle_cases.go b/backend/conformance/role_bundle_cases.go index 55385d9b7..b74a615a8 100644 --- a/backend/conformance/role_bundle_cases.go +++ b/backend/conformance/role_bundle_cases.go @@ -45,6 +45,9 @@ var roleContractCases = []roleContract{ RunBatchApplyAcceptsAnExternalEdgeTarget, RunBatchApplyNormalizesTheWaitsForGate, RunBatchApplyStampsSpawnerIDOnlyWhenNamed, + RunBatchApplyCarriesThreadIDOntoTheStoredEdge, + RunBatchApplyCarriesThreadIDOntoAnExistingEdge, + RunBatchApplyRefusesAThreadIDLongerThanItsColumn, RunBatchApplySplicesAForwardMetadataRef, RunBatchApplySplicesASelfMetadataRef, RunBatchApplyRefusesAMetadataRefNoItemDeclares, @@ -260,6 +263,7 @@ var roleContractCases = []roleContract{ RunDependencyEditorSameTypeReAddIsIdempotent, RunDependencyEditorSameTypeReAddWithChangedMetadataMintsOneVersion, RunDependencyEditorSameTypeReAddWithIdenticalMetadataIsANoOp, + RunDependencyEditorSameTypeReAddWithChangedThreadMintsOneVersion, RunDependencyEditorRepeatsWithinOneRequestCollapse, RunDependencyEditorAttributesItsEventsToTheActor, RunDependencyEditorRetypeRefusalLeavesTheOriginalEdge, diff --git a/engdocs/design/http-divergence-ledger.md b/engdocs/design/http-divergence-ledger.md index 78bbb101b..9815c30b1 100644 --- a/engdocs/design/http-divergence-ledger.md +++ b/engdocs/design/http-divergence-ledger.md @@ -47,7 +47,7 @@ the behavior. ## Summary -264 rows: 207 refuse, 33 degrade, 24 retired. +264 rows: 205 refuse, 33 degrade, 26 retired. ## Whole-behavior divergences (D9 ledger) @@ -134,8 +134,8 @@ Role-request fields on the served writes that the v0 wire publishes no member fo | W-CreateRequest.Issue | refuse | `CreateRequest.Issue` | a create whose Issue populates any member outside the wire's twenty refuses, naming the member | createIssue publishes the whole create VOCABULARY — id, title, description, design, acceptance_criteria, notes, status, issue_type, priority, assignee, owner, estimated_minutes, external_ref, due_at, defer_until, sender, metadata, labels, ephemeral, no_history — and deliberately not the rest of a types.Issue: the creation time (created_at), because a caller-supplied creation time makes the row disagree with the journal entry that records it and re-dating history is what an import is for; and spec_id, await_*, mol_type, wisp_type, work_type, storage_class, source_*, pinned, is_template and the event quartet, which this surface publishes on no operation, read or write. ONE row rather than one per member for W-BatchCreateItem.Issue's reason — the reason is one reason — and exhaustiveness is held by the same REFLECTION over types.Issue, sharing the role-ignored table with the batch so the two operations cannot disagree about what the ROLE drops. Issue.Comments and Issue.Dependencies are not in this population: the role itself refuses them, so a local create fails too and this is validation rather than divergence. created_by is published on no create shape either, but every one of them STAMPS it from the request's actor (internal/httpapi's create.go, batch_create.go and batch_apply.go) — the local front doors' own rule, since the role copies the member rather than stamping it. So a CreatedBy that names the actor, which is what every CLI create sends, arrives as written, and only one naming someone else refuses: the stamp would silently replace it. A server that predates the stamp stores an empty created_by for that one member | D8 row 16 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the in-repo divergence ledger, engdocs/design/http-divergence-ledger.md, for the discipline | | W-CreateItem.Issue | refuse | `CreateItem.Issue` | a create ITEM whose Issue populates any member outside the wire's twenty refuses, naming the member | ApplyCreateItem publishes exactly createIssue's create vocabulary — id, title, description, design, acceptance_criteria, notes, status, issue_type, priority, assignee, owner, estimated_minutes, external_ref, due_at, defer_until, sender, metadata, labels, ephemeral, no_history — and deliberately not the rest of a types.Issue, for the reasons W-CreateRequest.Issue gives in full. It is a row of its OWN rather than a citation of that one because the operations are different: a caller auditing why their PLAN refuses must not be sent to a row about a single create, and the two can diverge the day either vocabulary moves. The partition itself is SHARED — one carried table, one role-ignored table, held against types.Issue by the same reflection — so they cannot disagree about what the wire carries or about what the role drops. Issue.Comments and Issue.Dependencies are not in this population and are refused as validation on both sides: edges in this role are ITEMS, so a create item has nowhere to put one at all. Nor is a CreatedBy that names the request's actor: the server stamps every create item's created_by from the actor (W-CreateRequest.Issue), so that value arrives as written and only a CreatedBy naming someone else refuses | D8 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the in-repo divergence ledger, engdocs/design/http-divergence-ledger.md, for the discipline | | W-ApplyPatch.ParentID | refuse | `IssuePatch.ParentID` | a parent re-hang inside an update ITEM refuses, where the same member serves on updateIssue | ApplyPatchBody deliberately publishes no parent_id, and the absence is this operation's ONE-EDGE-ONE-SPELLING rule rather than a gap: a parent is a dep_add item of type parent-child, so the ORDER of every edge in a plan stays total and there is exactly one place an edge is written. The single patch has no ordering to express and publishes the member directly (W-IssuePatch.ParentID, retired by client wave ga-7i6by), which is why the same Go field is carried by one document and refused by the other. Refusing is not a loss of capability, only of spelling: a plan re-hangs a parent with a dep_add item, which is the atomic replacement in the position the caller declared it | D8 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the in-repo divergence ledger, engdocs/design/http-divergence-ledger.md, for the discipline | -| W-DepAddItem.HasSpawner | refuse | `DepAddItem.HasSpawner` | a waits-for edge ITEM that names its spawner refuses | ApplyDepAddItem publishes source, target, type and metadata and no spawner member, and the flag asks for a write only the ROLE can make: metadata's spawner_id, stamped from the resolved target once every id in the batch exists, because a target named by key has no id before then. Dropping the flag would store the edge's gate-only metadata, so an edge whose caller named a spawner would carry none. On every other edge type the role ignores the flag and stores the same row either way, so there it is dropped rather than refused. Upstream ask: a spawner member on ApplyDepAddItem, which retires this row | D8 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the in-repo divergence ledger, engdocs/design/http-divergence-ledger.md, for the discipline | -| W-DepAddItem.ThreadID | refuse | `DepAddItem.ThreadID` | associating an edge ITEM with a discussion thread refuses | ApplyDepAddItem publishes no thread member, and no operation on this surface does: W-CreateDependency.ThreadID refuses the same column on both create edges. Dropping it would store the edge with no thread, so a replies-to edge would lose the conversation it was written for. It is a row of its own rather than a citation of that one for W-CreateItem.Issue's reason: the operation is different | D8 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the in-repo divergence ledger, engdocs/design/http-divergence-ledger.md, for the discipline | +| W-DepAddItem.HasSpawner | retired | `DepAddItem.HasSpawner` | a waits-for edge ITEM that names its spawner used to refuse | RETIRED by issues.batchApply.depAddLineage (S5). ApplyDepAddItem now publishes `has_spawner` — the write this row said only the role could make, metadata's spawner_id stamped from the resolved target — gated on the capability rather than dropped: a caller on a server that has not advertised the token refuses locally before the dial (BatchApplier.refuseUnservedDepAddLineage), and a caller on a server that has sends the member exactly as given. The flag is sent, and gated, on a waits-for edge only, the one type the role reads it on. Off a waits-for edge it is the role's no-op, so the client drops it there without loss — the stored row is the same either way — rather than refusing a request the flag cannot change, or sending an older server a member it answers with a 400 | D8 refuse-not-drop (RETIRED) | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the in-repo divergence ledger, engdocs/design/http-divergence-ledger.md, for the discipline | +| W-DepAddItem.ThreadID | retired | `DepAddItem.ThreadID` | associating an edge ITEM with a discussion thread used to refuse | RETIRED with W-DepAddItem.HasSpawner (S5, issues.batchApply.depAddLineage). ApplyDepAddItem now publishes `thread_id` as a plain column on the stored edge, gated by the same capability and the same pre-dial refusal rather than dropped — a caller naming a thread on an unadvertising server is refused before the dial, never silently stored with no thread | D8 refuse-not-drop (RETIRED) | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the in-repo divergence ledger, engdocs/design/http-divergence-ledger.md, for the discipline | | W-IssuePatch.Labels | retired | `IssuePatch.Labels` | RETIRED — the whole ordered label edit crosses: `labels` replaces, `add_labels` adds, `remove_labels` removes | upstream #5510 published add_labels and remove_labels on IssuePatchBody and client wave ga-jpywb emits both, which is the retirement path this row named. The three travel as FLAT siblings where applyBatch nests them under one object, and the server assembles all three into ONE issueops.LabelPatch — so the algebra the role states (replace, then add, then remove; removal wins) is applied server-side and is never this client's to arrange. WHAT THE REFUSAL WAS PROTECTING is worth keeping after the refusal is gone: degrading an incremental edit onto the replace-only member would have meant reading the set, adding to it and writing it back, which silently drops any label another writer added in between. `bd label add` and every agent that tags work concurrently are exactly that caller, so the refusal was right for as long as the members did not exist — and it is the members that retire it, not a change of mind about the read-modify-write | D8 refuse-not-drop, open questions (tracked-refusal roadmap) | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the in-repo divergence ledger, engdocs/design/http-divergence-ledger.md, for the discipline | | W-CloseBatchRequest.ClaimNext | refuse | `CloseBatchRequest.ClaimNext` | folding an atomic claim-after-close onto a batch close refuses | batchCloseIssues publishes actor, force, items and session only — no claim_next member exists for this client to encode a ReadyRequest into, and none exists on the response for a claimed issue to decode back out of. Dropping the field silently would answer a caller's claim-after-close with a close that quietly never claimed anything; see W-CreateBatchRequest.Provenance for the same refuse-not-drop reasoning applied to an absent wire member. Deferred: S13 schedules ReadyLister (and with it, the ready-side plumbing a composed claim would need); no slice currently schedules claim_next itself | D8 refuse-not-drop | TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the in-repo divergence ledger, engdocs/design/http-divergence-ledger.md, for the discipline | | W-SweepRequest.ProtectLiveDependents | retired | `SweepRequest.ProtectLiveDependents` | protecting live structural dependents during a sweep used to refuse | RETIRED by the S4 wire extension that sends it. The gap was always the DOCUMENT's rather than a decision: the local Sweeper role carries a structural-dependent protection alongside the referenced-citation one, and apigen.SweepRequest had no protect_live_dependents member for this client to narrow onto, so sending `true` and silently dropping it would have run an UNPROTECTED sweep while the caller believed the structural guard was active. The spec now publishes `protect_live_dependents` (and SweepSkips.live_dependent on the response) behind its own behavior-capability token, issues.sweep.liveDependents, because it is a parameter added to an operation that already shipped. The client sends it only once the handshake advertises the token and refuses locally, before the dial, when it does not — see refuseUnservedSweep (sweeper.go) and W-SweepRequest.Limit for the sibling member closed the same way | D8 refuse-not-drop | TestSweepSendsTheS4MembersOnceTheServerAdvertisesThem | diff --git a/internal/httpapi/apigen/types.gen.go b/internal/httpapi/apigen/types.gen.go index f5cecef32..37e13b5f9 100644 --- a/internal/httpapi/apigen/types.gen.go +++ b/internal/httpapi/apigen/types.gen.go @@ -495,7 +495,12 @@ type ApplyCreateItem struct { // A WAITS-FOR EDGE IS NORMALIZED RATHER THAN STORED AS ASKED. An absent, empty or `{}` `metadata` on a `waits-for` edge is STORED as `{"gate":"all-children"}`, because a stored waits-for row must be self-describing: readers predating the gate's introduction do not default a missing one, so an empty gate is a row those readers get wrong. A metadata that names a gate keeps it, along with the spawner and also-blocks members a caller may carry, and a gate that is neither `all-children` nor `any-children` is a `400`. Nothing else about that member is interpreted. // // THERE IS NO TYPED `waits_for` MEMBER, and that is the shape rather than an omission: every measured caller already carries the gate as metadata, a typed spelling lowers to these same bytes, and the blob carries members a two-field typed member could not express. One spelling, and it is this one. +// +// `has_spawner` and `thread_id` require `issues.batchApply.depAddLineage`: a client naming either on a server that has not advertised the token refuses locally before the dial rather than sending bytes an older server would answer with its own `400` for an unknown member. type ApplyDepAddItem struct { + // HasSpawner Gated by `issues.batchApply.depAddLineage`. Ignored for every `type` but `waits-for`: on a `waits-for` edge, `true` stamps `metadata.spawner_id` with this item's `target` (the id `bd create --graph`'s spawner_key/spawner_id resolved to), so a reader learns which spawned row to watch without re-deriving it from the graph plan. Absent or `false` leaves `metadata` exactly as given. + HasSpawner *bool `json:"has_spawner,omitempty"` + // Metadata One metadata value: ANY JSON value — string, number, boolean, null, array or object — because typed values enter through the explicit JSON metadata path and persist in older rows. It is not a string, and a client must not decode it as one. // // Where a member of this type is OMITTED, the key is absent; where it is present holding `null`, the key exists and holds null. Those are different states and this surface reports both. @@ -515,6 +520,9 @@ type ApplyDepAddItem struct { // A KEY REACHES BACKWARD ONLY where the ref ADDRESSES a row — an `update.target`, a `close.target`, either endpoint of a `dep_add`. The one exception is `create.metadata_refs`, whose values may reach forward or name their own item's key; the operation's description says why. Target Ref `json:"target"` + // ThreadId Gated by `issues.batchApply.depAddLineage`. A plain column on the stored edge, separate from `metadata`'s blob — the graph-plan thread this edge belongs to, for a reader that groups edges by thread without parsing every edge's metadata. + ThreadId *string `json:"thread_id,omitempty"` + // Type The edge type, from the same OPEN vocabulary `Dependency.type` carries: checked for BEING a storable value, never for membership of a known-types list, so a workspace's own type passes. Type string `json:"type"` } @@ -548,6 +556,8 @@ type ApplyItem struct { // A WAITS-FOR EDGE IS NORMALIZED RATHER THAN STORED AS ASKED. An absent, empty or `{}` `metadata` on a `waits-for` edge is STORED as `{"gate":"all-children"}`, because a stored waits-for row must be self-describing: readers predating the gate's introduction do not default a missing one, so an empty gate is a row those readers get wrong. A metadata that names a gate keeps it, along with the spawner and also-blocks members a caller may carry, and a gate that is neither `all-children` nor `any-children` is a `400`. Nothing else about that member is interpreted. // // THERE IS NO TYPED `waits_for` MEMBER, and that is the shape rather than an omission: every measured caller already carries the gate as metadata, a typed spelling lowers to these same bytes, and the blob carries members a two-field typed member could not express. One spelling, and it is this one. + // + // `has_spawner` and `thread_id` require `issues.batchApply.depAddLineage`: a client naming either on a server that has not advertised the token refuses locally before the dial rather than sending bytes an older server would answer with its own `400` for an unknown member. DepAdd *ApplyDepAddItem `json:"dep_add,omitempty"` // Kind Which member below is read. A CLOSED set, unlike a dependency `type`: every value here is a verb this operation implements, and an unknown one is a request the server cannot execute rather than a workspace's own vocabulary. @@ -1037,7 +1047,7 @@ type ContextResponse struct { // OPTIONAL, and absent means only that this server does not disclose its filesystem layout — never that it has no workspace. A client MUST NOT require it, MUST NOT treat absence as an error, and has no use for the value beyond display: it is a path on the SERVER's filesystem, which the client cannot open. Identify the workspace by `project_id` and `database`, which are required. BeadsDir *string `json:"beads_dir,omitempty"` - // Capabilities The tokens this server advertises: the OPERATIONS it implements, derived from its route table, and the server-wide BEHAVIORS it enforces. v0's operation vocabulary is `ready.list`, `ready.count`, `issues.list`, `issues.query`, `issues.count`, `issues.get`, `issues.related`, `issues.create`, `issues.addComment`, `issues.batchClose`, `issues.claim`, `issues.claimNext`, `issues.release`, `issues.close`, `issues.reopen`, `issues.update`, `issues.sweep`, `issues.delete`, `issues.batchGet`, `issues.batchCreate`, `issues.batchApply`, `stats.get`, `config.list`, `config.get`, `config.set`, `config.unset`, `dependencies.cycles`, `dependencies.list`, `dependencies.count`, `dependencies.blocking`, `dependencies.tree`, `dependencies.add`, `dependencies.remove`, `memories.list`, `memories.get`, `memories.remember`, `memories.forget`, `events.list`, `events.watch`, `issues.casMetadata`; the behavior tokens are `project.enforce`, which announces that a `Bd-Project-Id` stamp for the wrong workspace is refused here rather than silently ignored, `issues.batchApplyLarge`, which announces that `POST /v0/beads/issues:batchApply` accepts the RAISED envelope — up to 1000 items (`ApplyBatchRequest.items.maxItems`), a 16 MiB body, and (for a request over 100 items) a run budget that EXTENDS to an operator-configured ceiling (`bd serve --large-apply-ceiling`, 5 minutes by default) — rather than the original 100-item, 4 MiB bound. The ceiling is a flat whole-run budget, not a value scaled by item count: a 101-item request and a 1000-item request both get the same extended budget. A request at or under 100 items is unaffected either way and keeps the server's ordinary deadline exactly as before. A client that checks for this token before sending a plan over 100 items learns whether THIS server accepts it without paying for a round trip an older server would refuse anyway, and `issues.list.sort`, which announces that `GET /v0/beads/issues` accepts the `sort` query parameter (two closed, pageable total orders — see that parameter) rather than silently answering `unknown_parameter`, and `issues.count.scope`, which announces that `GET /v0/beads/issues:count` accepts `parent`, `no_parent`, `exclude_type`, and `exclude_status` (see those parameters) rather than silently answering `unknown_parameter` for all four, `issues.sweep.wispsPlane`, which announces that `POST /v0/beads/issues:sweep` accepts the `wisps-plane` value of `tier` rather than silently answering `invalid_value`, `issues.sweep.liveDependents`, which announces that the same operation accepts `protect_live_dependents` and answers `skipped.live_dependent` rather than silently answering `unknown_parameter`, and `issues.sweep.limit`, which announces that it accepts `limit` and answers `remaining` rather than silently answering `unknown_parameter`. The list grows additively, and an operation never appears here unless it is fully implemented. This is how a client checks for an operation or a behavior — never the version string. + // Capabilities The tokens this server advertises: the OPERATIONS it implements, derived from its route table, and the server-wide BEHAVIORS it enforces. v0's operation vocabulary is `ready.list`, `ready.count`, `issues.list`, `issues.query`, `issues.count`, `issues.get`, `issues.related`, `issues.create`, `issues.addComment`, `issues.batchClose`, `issues.claim`, `issues.claimNext`, `issues.release`, `issues.close`, `issues.reopen`, `issues.update`, `issues.sweep`, `issues.delete`, `issues.batchGet`, `issues.batchCreate`, `issues.batchApply`, `stats.get`, `config.list`, `config.get`, `config.set`, `config.unset`, `dependencies.cycles`, `dependencies.list`, `dependencies.count`, `dependencies.blocking`, `dependencies.tree`, `dependencies.add`, `dependencies.remove`, `memories.list`, `memories.get`, `memories.remember`, `memories.forget`, `events.list`, `events.watch`, `issues.casMetadata`; the behavior tokens are `project.enforce`, which announces that a `Bd-Project-Id` stamp for the wrong workspace is refused here rather than silently ignored, `issues.batchApplyLarge`, which announces that `POST /v0/beads/issues:batchApply` accepts the RAISED envelope — up to 1000 items (`ApplyBatchRequest.items.maxItems`), a 16 MiB body, and (for a request over 100 items) a run budget that EXTENDS to an operator-configured ceiling (`bd serve --large-apply-ceiling`, 5 minutes by default) — rather than the original 100-item, 4 MiB bound. The ceiling is a flat whole-run budget, not a value scaled by item count: a 101-item request and a 1000-item request both get the same extended budget. A request at or under 100 items is unaffected either way and keeps the server's ordinary deadline exactly as before. A client that checks for this token before sending a plan over 100 items learns whether THIS server accepts it without paying for a round trip an older server would refuse anyway, and `issues.list.sort`, which announces that `GET /v0/beads/issues` accepts the `sort` query parameter (two closed, pageable total orders — see that parameter) rather than silently answering `unknown_parameter`, and `issues.count.scope`, which announces that `GET /v0/beads/issues:count` accepts `parent`, `no_parent`, `exclude_type`, and `exclude_status` (see those parameters) rather than silently answering `unknown_parameter` for all four, `issues.sweep.wispsPlane`, which announces that `POST /v0/beads/issues:sweep` accepts the `wisps-plane` value of `tier` rather than silently answering `invalid_value`, `issues.sweep.liveDependents`, which announces that the same operation accepts `protect_live_dependents` and answers `skipped.live_dependent` rather than silently answering `unknown_parameter`, `issues.sweep.limit`, which announces that it accepts `limit` and answers `remaining` rather than silently answering `unknown_parameter`, and `issues.batchApply.depAddLineage`, which announces that a `dep_add` item on `POST /v0/beads/issues:batchApply` accepts `has_spawner` and `thread_id` (see `ApplyDepAddItem`) rather than a `400` naming the member unknown. The list grows additively, and an operation never appears here unless it is fully implemented. This is how a client checks for an operation or a behavior — never the version string. // // THIS LIST IS BUILD-LEVEL, NOT WORKSPACE-LEVEL. It says which operations this binary serves, and for every entry but two that is the whole answer. `events.list` and `events.watch` are the exceptions: the durable events journal is a per-workspace setting that is OFF by default, so a server that advertises them may still refuse every request to both with 409 `events_journal_disabled` — correctly, because the operations exist and the workspace has no journal. A consumer of either MUST treat the capability as "this server speaks it" and the 409 as "not on this workspace", and must not read the capability as a promise that records will arrive. Capabilities []string `json:"capabilities"` diff --git a/internal/httpapi/batch_apply.go b/internal/httpapi/batch_apply.go index 16b9d4a63..723ce8615 100644 --- a/internal/httpapi/batch_apply.go +++ b/internal/httpapi/batch_apply.go @@ -102,7 +102,7 @@ var ( applyLabelPatchMembers = []string{"add", "remove", "replace"} applyMetadataPatchMembers = []string{"merge", "replace", "set", "unset"} applyCloseItemMembers = []string{"expected_version", "force", "reason", "session", "target"} - applyDepAddItemMembers = []string{"metadata", "source", "target", "type"} + applyDepAddItemMembers = []string{"has_spawner", "metadata", "source", "target", "thread_id", "type"} // applyItemKinds is the tag vocabulary, paired with the payload member each // value names. It is one map rather than a switch so the enum, the member @@ -831,6 +831,28 @@ func applyDepAddItem(prefix string, raw map[string]json.RawMessage) (*issueops.D if metadata, present := raw["metadata"]; present { item.Metadata = string(metadata) } + // has_spawner and thread_id are additive members gated client-side by + // issues.batchApply.depAddLineage (routes.go CapBatchApplyDepAddLineage): + // the server always understands them once wired, so there is no + // capability check here — the gate lives entirely in the client that + // decides whether to SEND them against an older server. + hasSpawner, res := applyBoolMember(raw, prefix, "has_spawner") + if res != nil { + return nil, res + } + item.HasSpawner = hasSpawner + threadID, res := applyTextMember(raw, prefix, "thread_id") + if res != nil { + return nil, res + } + // The document's minLength: 1. An ABSENT thread_id already names no thread + // (and a re-add keeps the stored one), so an empty one would only be a + // second spelling of it — refused, as an empty `type` is, rather than read. + if _, present := raw["thread_id"]; present && threadID == "" { + res := InvalidArgument(prefix+"thread_id", ReasonInvalidValue, "`thread_id` must not be empty; omit it to name no thread") + return nil, &res + } + item.ThreadID = threadID return item, nil } diff --git a/internal/httpapi/batch_apply_test.go b/internal/httpapi/batch_apply_test.go index a60c8ea54..824775f21 100644 --- a/internal/httpapi/batch_apply_test.go +++ b/internal/httpapi/batch_apply_test.go @@ -84,7 +84,7 @@ func TestApplyBatchForwardsEveryLevelOfTheDocumentedBody(t *testing.T) { "expected_version":"42"}}, {"kind":"dep_add","dep_add":{ "source":{"key":"root"},"target":{"id":"bd-7"},"type":"waits-for", - "metadata":{"gate":"any-children"}}} + "metadata":{"gate":"any-children"},"has_spawner":true,"thread_id":"th-plan"}} ] }`) if resp.StatusCode != http.StatusOK { @@ -240,6 +240,11 @@ func TestApplyBatchForwardsEveryLevelOfTheDocumentedBody(t *testing.T) { if depAdd.Metadata != `{"gate":"any-children"}` { t.Errorf("dep_add.metadata = %q, want the caller's bytes unaltered", depAdd.Metadata) } + // The lineage members reach the role as sent: issues.batchApply.depAddLineage + // gates whether a CLIENT sends them, and this server always reads them. + if !depAdd.HasSpawner || depAdd.ThreadID != "th-plan" { + t.Errorf("dep_add.has_spawner/thread_id = %v/%q, want true/%q", depAdd.HasSpawner, depAdd.ThreadID, "th-plan") + } } // TestApplyBatchAnswersWithTheLeanResult pins the response side: ids, a @@ -520,6 +525,29 @@ func TestApplyBatchRejectsTheShapesTheDocumentRefuses(t *testing.T) { } } +// TestApplyBatchRefusesAnEmptyThreadID pins the document's minLength: 1 on a +// dep_add item's thread_id. An absent member already names no thread, so an +// empty one is refused by name rather than read as a second spelling of it. +// The client never sends one (setItemString omits an empty value), so only a +// direct-wire caller reaches this. +func TestApplyBatchRefusesAnEmptyThreadID(t *testing.T) { + applier := &roleBatchApplier{} + ts := newApplyBatchServer(t, applier) + + resp := ts.claim(t, batchApplyPath, `{"actor":"alice","items":[{"kind":"dep_add","dep_add":{ + "source":{"id":"a"},"target":{"id":"b"},"type":"blocks","thread_id":""}}]}`) + if resp.StatusCode != http.StatusBadRequest { + t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp)) + } + body := decodeBody(t, resp) + if body["param"] != "items[0].dep_add.thread_id" || body["reason"] != "invalid_value" { + t.Errorf("param/reason = %v/%v, want items[0].dep_add.thread_id/invalid_value", body["param"], body["reason"]) + } + if len(applier.requests()) != 0 { + t.Errorf("the role was called for a refused request; nothing may reach it") + } +} + // TestApplyBatchRefusesMoreItemsThanTheRoleAccepts pins the cap at the edge, so // an over-long plan costs no database work. The number is the role's own // constant rather than a second copy of it. diff --git a/internal/httpapi/routes.go b/internal/httpapi/routes.go index 2dbd4f291..4c426275a 100644 --- a/internal/httpapi/routes.go +++ b/internal/httpapi/routes.go @@ -149,6 +149,18 @@ const CapIssuesSweepLiveDependents = "issues.sweep.liveDependents" // before sending the member to a server that may predate it. const CapIssuesSweepLimit = "issues.sweep.limit" +// CapBatchApplyDepAddLineage is the behavior capability that advertises +// ApplyDepAddItem's `has_spawner` and `thread_id` members (batch_apply.go): +// additive fields a `dep_add` item may carry alongside `source`, `target`, +// `type` and `metadata`. Like CapBatchApplyLarge it names members of an +// EXISTING operation (issues.batchApply already has its own per-operation +// token) rather than a route of its own, so it rides the same +// behaviorCapabilities list. An older server predating this token answers +// either member with `400 invalid_argument`/`unknown_parameter`. The client +// MUST check this token before sending either member to a server that may +// predate it; it refuses locally before the dial when the token is absent. +const CapBatchApplyDepAddLineage = "issues.batchApply.depAddLineage" + // customMethodTarget splits the custom method off the segment the router // matched, and reports the row that claims it. // @@ -899,6 +911,7 @@ func (r route) specPathOf() string { var behaviorCapabilities = []string{ CapProjectEnforce, CapBatchApplyLarge, CapIssuesListSort, CapIssuesCountScope, CapIssuesSweepWispsPlane, CapIssuesSweepLiveDependents, CapIssuesSweepLimit, + CapBatchApplyDepAddLineage, } // Capabilities lists what this build advertises in ContextResponse.capabilities: diff --git a/internal/httpapi/server_test.go b/internal/httpapi/server_test.go index 514190e91..6f787874c 100644 --- a/internal/httpapi/server_test.go +++ b/internal/httpapi/server_test.go @@ -636,7 +636,8 @@ func TestCapabilitiesAdvertiseEveryImplementedOperation(t *testing.T) { // same list. Both are spelled literally here to keep this an independent // oracle rather than a second call to the code under test. want = append(want, "project.enforce", "issues.batchApplyLarge", "issues.list.sort", "issues.count.scope", - "issues.sweep.wispsPlane", "issues.sweep.liveDependents", "issues.sweep.limit") + "issues.sweep.wispsPlane", "issues.sweep.liveDependents", "issues.sweep.limit", + "issues.batchApply.depAddLineage") slices.Sort(want) if !slices.Equal(got, want) { t.Errorf("capabilities = %v, want %v", got, want) diff --git a/internal/httpapi/spec/openapi.v0.yaml b/internal/httpapi/spec/openapi.v0.yaml index 784f24f22..456693a41 100644 --- a/internal/httpapi/spec/openapi.v0.yaml +++ b/internal/httpapi/spec/openapi.v0.yaml @@ -7969,9 +7969,13 @@ components: `issues.sweep.liveDependents`, which announces that the same operation accepts `protect_live_dependents` and answers `skipped.live_dependent` rather than silently answering - `unknown_parameter`, and `issues.sweep.limit`, which announces + `unknown_parameter`, `issues.sweep.limit`, which announces that it accepts `limit` and answers `remaining` rather than - silently answering `unknown_parameter`. The + silently answering `unknown_parameter`, and + `issues.batchApply.depAddLineage`, which announces that a + `dep_add` item on `POST /v0/beads/issues:batchApply` accepts + `has_spawner` and `thread_id` (see `ApplyDepAddItem`) rather than + a `400` naming the member unknown. The list grows additively, and an operation never appears here unless it is fully implemented. This is how a client checks for an operation or a behavior — never the version string. @@ -10301,6 +10305,12 @@ components: a typed spelling lowers to these same bytes, and the blob carries members a two-field typed member could not express. One spelling, and it is this one. + + + `has_spawner` and `thread_id` require `issues.batchApply.depAddLineage`: + a client naming either on a server that has not advertised the token + refuses locally before the dial rather than sending bytes an older + server would answer with its own `400` for an unknown member. properties: source: $ref: '#/components/schemas/Ref' @@ -10316,6 +10326,24 @@ components: a known-types list, so a workspace's own type passes. metadata: $ref: '#/components/schemas/MetadataValue' + has_spawner: + type: boolean + description: >- + Gated by `issues.batchApply.depAddLineage`. Ignored for every + `type` but `waits-for`: on a `waits-for` edge, `true` stamps + `metadata.spawner_id` with this item's `target` (the id `bd create + --graph`'s spawner_key/spawner_id resolved to), so a reader learns + which spawned row to watch without re-deriving it from the graph + plan. Absent or `false` leaves `metadata` exactly as given. + thread_id: + type: string + minLength: 1 + maxLength: 255 + description: >- + Gated by `issues.batchApply.depAddLineage`. A plain column on the + stored edge, separate from `metadata`'s blob — the graph-plan + thread this edge belongs to, for a reader that groups edges by + thread without parsing every edge's metadata. ApplyBatchResponse: type: object diff --git a/internal/httpapi/wireshape/testdata/golden.json b/internal/httpapi/wireshape/testdata/golden.json index 1dccd173c..1bff0651a 100644 --- a/internal/httpapi/wireshape/testdata/golden.json +++ b/internal/httpapi/wireshape/testdata/golden.json @@ -264,6 +264,12 @@ "type": "string", "required": true }, + { + "schema": "ApplyDepAddItem", + "member": "has_spawner", + "type": "boolean", + "required": false + }, { "schema": "ApplyDepAddItem", "member": "metadata", @@ -283,6 +289,12 @@ "type": "object", "required": true }, + { + "schema": "ApplyDepAddItem", + "member": "thread_id", + "type": "string", + "required": false + }, { "schema": "ApplyDepAddItem", "member": "type", diff --git a/internal/httpclient/BUILD.bazel b/internal/httpclient/BUILD.bazel index 702900172..f6cb1cbee 100644 --- a/internal/httpclient/BUILD.bazel +++ b/internal/httpclient/BUILD.bazel @@ -114,6 +114,7 @@ go_test( "required_served_tier_test.go", "roles_graph_cycles_test.go", "roles_test.go", + "served_batch_apply_large_test.go", "served_batch_apply_test.go", "served_batch_close_test.go", "served_batch_getter_test.go", @@ -181,6 +182,7 @@ go_test( "//internal/httpclient/wire", "//internal/storage", "//internal/storage/backends", + "//internal/storage/batchfixtures", "//internal/storage/domain", "//internal/storage/embeddeddolt", "//internal/storage/issueops", diff --git a/internal/httpclient/batchapplier.go b/internal/httpclient/batchapplier.go index dae4ed8f0..b39c12986 100644 --- a/internal/httpclient/batchapplier.go +++ b/internal/httpclient/batchapplier.go @@ -7,6 +7,7 @@ import ( "errors" "fmt" "reflect" + "slices" "strings" "github.com/steveyegge/beads/internal/httpapi/apigen" @@ -84,6 +85,9 @@ func (b *httpBatchApplier) ApplyBatch(ctx context.Context, req issueops.ApplyBat return issueops.ApplyBatchResult{}, invalid( "a batch apply carries %d items; the limit is %d per request", len(req.Items), issueops.MaxApplyBatchItems) } + if err := b.refuseUnservedDepAddLineage(ctx, req); err != nil { + return issueops.ApplyBatchResult{}, err + } body, err := applyBatchBody(req) if err != nil { @@ -96,6 +100,41 @@ func (b *httpBatchApplier) ApplyBatch(ctx context.Context, req issueops.ApplyBat return decodeApplyBatchResult(req, resp) } +// refuseUnservedDepAddLineage scans the whole plan once, before the dial, for +// a dep_add item naming ThreadID, or HasSpawner on a waits-for edge (the one +// type the role reads it on; see depAddNamesSpawner). Neither member is served +// unless the handshake snapshot advertises wire.CapBatchApplyDepAddLineage: +// an older server has never heard of either and would answer them with its +// generic unknown-member 400 at best, or (once a server DOES know the +// members but this gate were skipped) silently honor a field the caller +// never meant to send past an unupgraded fleet. So this checks the +// capability once for the whole request — never per item, and never after +// the dial. +func (b *httpBatchApplier) refuseUnservedDepAddLineage(ctx context.Context, req issueops.ApplyBatchRequest) error { + carriesLineage := false + for _, item := range req.Items { + if item.Kind == issueops.ItemDepAdd && depAddCarriesLineage(item.DepAdd) { + carriesLineage = true + break + } + } + if !carriesLineage { + return nil + } + snap, err := b.store.snapshot(ctx) + if err != nil { + return err + } + // snap is nil, nil whenever Store.snapshot has no transport AND no cached + // handshake (a Store built with a nil wire): nothing was ever advertised, + // so this falls straight through to the refusal below rather than + // dereferencing a nil *apigen.ContextResponse. + if snap != nil && slices.Contains(snap.Capabilities, wire.CapBatchApplyDepAddLineage) { + return nil + } + return b.store.unsupportedCapability("BatchApplier.ApplyBatch", wire.CapBatchApplyDepAddLineage) +} + // applyBatchBody projects the role's request onto the wire body. func applyBatchBody(req issueops.ApplyBatchRequest) (wire.ApplyBatchRequest, error) { items := make([]wire.ApplyItem, 0, len(req.Items)) @@ -368,15 +407,6 @@ func applyDepAddItemBody(item *issueops.DepAddItem) (*apigen.ApplyDepAddItem, er if item.Type == "" { return nil, invalid("a dep_add item names no edge type") } - // ApplyDepAddItem publishes neither member below, so each refuses where the - // role would store something the wire cannot say. The spawner flag only - // does that on a waits-for edge; the role ignores it on every other type. - switch { - case item.HasSpawner && item.Type == issueops.DepWaitsFor: - return nil, refuse(encode.OpApplyBatch, "W-DepAddItem.HasSpawner") - case item.ThreadID != "": - return nil, refuse(encode.OpApplyBatch, "W-DepAddItem.ThreadID") - } out := &apigen.ApplyDepAddItem{Source: source, Target: target, Type: string(item.Type)} // A BLANK blob is ABSENT, not malformed, and reading it any other way is a // real bug rather than strictness: the role's own rule is that an absent, @@ -390,9 +420,34 @@ func applyDepAddItemBody(item *issueops.DepAddItem) (*apigen.ApplyDepAddItem, er } out.Metadata = apigen.MetadataValue(blob) } + // HasSpawner and ThreadID are gated by CapBatchApplyDepAddLineage + // (checked in ApplyBatch, before the dial, over the whole request) — + // this projection only encodes what the gate already cleared, which is + // why HasSpawner is sent only where depAddNamesSpawner holds. + setItemBool(&out.HasSpawner, depAddNamesSpawner(item)) + setItemString(&out.ThreadId, item.ThreadID) return out, nil } +// depAddCarriesLineage reports whether a dep_add item names a member +// CapBatchApplyDepAddLineage gates: ThreadID on any edge, HasSpawner only +// where depAddNamesSpawner holds. Used to scan a whole request once before +// the dial, rather than discovering the gap one item at a time after bytes +// already left for the wire. +func depAddCarriesLineage(item *issueops.DepAddItem) bool { + return item != nil && (depAddNamesSpawner(item) || item.ThreadID != "") +} + +// depAddNamesSpawner reports whether a dep_add item's HasSpawner means +// anything: the role reads it on a waits-for edge only and ignores it on +// every other type. Off a waits-for edge the flag is therefore dropped, not +// sent, and never needs the capability — dropping it loses nothing the role +// would store, where refusing it would fail a mixed-version request the +// flag cannot change. +func depAddNamesSpawner(item *issueops.DepAddItem) bool { + return item.HasSpawner && item.Type == issueops.DepWaitsFor +} + // applyRefBody projects one ref, applying the exactly-one rule the schema // cannot state. // diff --git a/internal/httpclient/batchapplier_test.go b/internal/httpclient/batchapplier_test.go index 3607f59a6..a29e38033 100644 --- a/internal/httpclient/batchapplier_test.go +++ b/internal/httpclient/batchapplier_test.go @@ -12,10 +12,24 @@ import ( "github.com/steveyegge/beads/internal/httpapi/apigen" "github.com/steveyegge/beads/internal/httpclient/wire" + "github.com/steveyegge/beads/internal/storage" "github.com/steveyegge/beads/internal/types" "github.com/steveyegge/beads/issueops" ) +// applyRoleWithSnapshot is applyRole's twin for pinning exactly what the +// handshake advertises, the same idiom counts_test.go's +// countRoleWithSnapshot uses: passing a snapshot straight through New rather +// than accepting applyRole's bare stubStore default. +func applyRoleWithSnapshot(t *testing.T, w *stubWire, snap *apigen.ContextResponse) issueops.BatchApplier { + t.Helper() + applier, err := New(testTarget(t), w, snap).BatchApplier() + if err != nil { + t.Fatalf("BatchApplier(): %v", err) + } + return applier +} + // The batch-apply role's unit gates: what the client DECIDES before the dial, // and what it refuses to believe about the answer. // @@ -52,8 +66,12 @@ func applyOneCreate() issueops.ApplyBatchRequest { // The create item's issue vocabulary is EXACTLY the single create's, so the // partition tables are shared rather than copied and this drives the same sweep // against a different operation and a different ledger row. The patch's own -// excluded member — parent_id — is the second half, and the edge item's two — -// the spawner flag and the thread — are the third. +// excluded member — parent_id — is the second half. +// +// The edge item's spawner flag and thread were a third population here before +// issues.batchApply.depAddLineage: both are CARRIED now, gated on the +// capability rather than refused outright — see +// TestApplyBatchRefusesUnservedDepAddLineageBeforeDialing. func TestApplyBatchRefusesEveryMemberTheWireExcludes(t *testing.T) { t.Run("the create item's carried members are the wire's own", func(t *testing.T) { published := bodyMembers(t, reflect.TypeOf(apigen.ApplyCreateItem{})) @@ -164,34 +182,18 @@ func TestApplyBatchRefusesEveryMemberTheWireExcludes(t *testing.T) { } }) - t.Run("the edge item's two unpublished members refuse", func(t *testing.T) { - for _, test := range []struct { - member string - row string - set func(*issueops.DepAddItem) - }{ - {"HasSpawner", "W-DepAddItem.HasSpawner", func(item *issueops.DepAddItem) { item.HasSpawner = true }}, - {"ThreadID", "W-DepAddItem.ThreadID", func(item *issueops.DepAddItem) { item.ThreadID = "th-1" }}, - } { - t.Run(test.member, func(t *testing.T) { - item := &issueops.DepAddItem{ - Source: issueops.Ref{ID: "bd-1"}, Target: issueops.Ref{ID: "bd-2"}, Type: issueops.DepWaitsFor, - } - test.set(item) - w := &stubWire{} - _, err := applyRole(t, w).ApplyBatch(t.Context(), issueops.ApplyBatchRequest{ - Actor: "planner", - Items: []issueops.ApplyItem{{Kind: issueops.ItemDepAdd, DepAdd: item}}, - }) - assertRefusedBy(t, err, test.row) - if len(w.calls) != 0 { - t.Errorf("the refused member reached the wire: %v", w.calls) - } - }) - } - }) + // The edge item's HasSpawner/ThreadID used to refuse here + // (W-DepAddItem.HasSpawner on a waits-for edge, W-DepAddItem.ThreadID on + // any). Both are now CARRIED, gated by issues.batchApply.depAddLineage on + // the same edges — see + // TestApplyBatchRefusesUnservedDepAddLineageBeforeDialing for the pre-dial + // capability refusal this subtest retired in favor of. t.Run("a spawner flag on any other edge type is the role's no-op, and is not refused", func(t *testing.T) { + // applyRole's snapshot advertises no capability at all: the flag is + // gated only where the role reads it, so a blocks edge carrying it + // dials an older server rather than refusing — and drops the flag + // instead of sending a member that server would answer with a 400. w := &stubWire{} _, err := applyRole(t, w).ApplyBatch(t.Context(), issueops.ApplyBatchRequest{ Actor: "planner", @@ -202,8 +204,12 @@ func TestApplyBatchRefusesEveryMemberTheWireExcludes(t *testing.T) { if err != nil { t.Fatalf("a spawner flag on a blocks edge refused: %v", err) } - if got := w.lastApply.Items[0].DepAdd; got == nil || got.Type != string(issueops.DepBlocks) { - t.Errorf("the encoded edge = %+v, want the caller's blocks edge", got) + got := w.lastApply.Items[0].DepAdd + if got == nil || got.Type != string(issueops.DepBlocks) { + t.Fatalf("the encoded edge = %+v, want the caller's blocks edge", got) + } + if got.HasSpawner != nil { + t.Errorf("has_spawner = %v on a blocks edge, want it dropped: the role ignores it there", *got.HasSpawner) } }) @@ -997,3 +1003,91 @@ func TestTheApplyLabelPatchIsTheWholeEdit(t *testing.T) { t.Error("the clear invented an add member") } } + +// TestApplyBatchRefusesUnservedDepAddLineageBeforeDialing is the 2026-10 +// Opus-review HIGH-1 finding: refuseUnservedDepAddLineage (batchapplier.go) +// carried no coverage at all — deleting the function and its call site +// passed every test that existed before this one. +// +// A dep_add item naming ThreadID on any edge, or HasSpawner on a waits-for +// edge, dialed against a server that does not advertise +// CapBatchApplyDepAddLineage, must refuse BEFORE dialing with +// *storage.ErrUnsupported naming the capability. A plan that touches neither +// field must still dial normally against the SAME masked server: the gate +// scopes the two members, not the operation. (HasSpawner off a waits-for edge +// is the role's no-op and dials too — see +// TestApplyBatchRefusesEveryMemberTheWireExcludes.) +func TestApplyBatchRefusesUnservedDepAddLineageBeforeDialing(t *testing.T) { + masked := &apigen.ContextResponse{BdVersion: "1.2.3"} // no CapBatchApplyDepAddLineage + depAddPlan := func(item issueops.DepAddItem) issueops.ApplyBatchRequest { + return issueops.ApplyBatchRequest{ + Actor: "planner", + Items: []issueops.ApplyItem{{Kind: issueops.ItemDepAdd, DepAdd: &item}}, + } + } + + for _, tc := range []struct { + name string + item issueops.DepAddItem + }{ + { + name: "HasSpawner", + item: issueops.DepAddItem{ + Source: issueops.Ref{ID: "bd-1"}, Target: issueops.Ref{ID: "bd-2"}, + Type: "waits-for", HasSpawner: true, + }, + }, + { + name: "ThreadID", + item: issueops.DepAddItem{ + Source: issueops.Ref{ID: "bd-1"}, Target: issueops.Ref{ID: "bd-2"}, + Type: "waits-for", ThreadID: "t-1", + }, + }, + { + // Unlike HasSpawner, a thread is stored on every edge type. + name: "ThreadID on a blocks edge", + item: issueops.DepAddItem{ + Source: issueops.Ref{ID: "bd-1"}, Target: issueops.Ref{ID: "bd-2"}, + Type: "blocks", ThreadID: "t-1", + }, + }, + } { + t.Run(tc.name, func(t *testing.T) { + w := &stubWire{} + _, err := applyRoleWithSnapshot(t, w, masked).ApplyBatch(t.Context(), depAddPlan(tc.item)) + if err == nil { + t.Fatal("ApplyBatch returned no error, want a pre-dial capability refusal") + } + var unsup *storage.ErrUnsupported + if !errors.As(err, &unsup) { + t.Fatalf("errors.As to *storage.ErrUnsupported failed for %v", err) + } + if unsup.Capability != wire.CapBatchApplyDepAddLineage { + t.Errorf("Capability = %q, want %q", unsup.Capability, wire.CapBatchApplyDepAddLineage) + } + if len(w.calls) != 0 { + t.Errorf("dialed %d times, want 0: a pre-dial refusal must never reach the wire", len(w.calls)) + } + }) + } + + t.Run("neither field set still dials", func(t *testing.T) { + dependsOn := "bd-2" + w := &stubWire{applied: &apigen.ApplyBatchResponse{ + Keys: map[string]string{}, + Items: []apigen.ApplyItemResult{ + {Kind: "dep_add", IssueId: "bd-1", DependsOnId: &dependsOn, Changed: true, Revision: "0"}, + }, + }} + _, err := applyRoleWithSnapshot(t, w, masked).ApplyBatch(t.Context(), depAddPlan(issueops.DepAddItem{ + Source: issueops.Ref{ID: "bd-1"}, Target: issueops.Ref{ID: "bd-2"}, Type: "waits-for", + })) + if err != nil { + t.Fatalf("ApplyBatch with no lineage fields set: %v", err) + } + if len(w.calls) == 0 { + t.Error("the plan never reached the wire, want a dial: the gate scopes HasSpawner/ThreadID, not the operation") + } + }) +} diff --git a/internal/httpclient/counter.go b/internal/httpclient/counter.go index 8fe62e1ea..54b11c696 100644 --- a/internal/httpclient/counter.go +++ b/internal/httpclient/counter.go @@ -119,7 +119,11 @@ func (c httpCounter) refuseUnservedScope(ctx context.Context, op string, req iss if err != nil { return err } - if slices.Contains(snap.Capabilities, wire.CapCountScope) { + // snap is nil, nil whenever Store.snapshot has no transport AND no cached + // handshake (a Store built with a nil wire): nothing was ever advertised, + // so this falls straight through to the refusal below rather than + // dereferencing a nil *apigen.ContextResponse. + if snap != nil && slices.Contains(snap.Capabilities, wire.CapCountScope) { return nil } return c.store.unsupportedCapability(op, wire.CapCountScope) diff --git a/internal/httpclient/counts_test.go b/internal/httpclient/counts_test.go index af3c67793..ddfa84b1d 100644 --- a/internal/httpclient/counts_test.go +++ b/internal/httpclient/counts_test.go @@ -736,3 +736,46 @@ func TestCountScopeRefusesLocallyWhenTheServerLacksTheCapability(t *testing.T) { } }) } + +// TestCounterRefusesScopeGracefullyWithNoTransportAndNoSnapshot is the 2026-10 +// Opus-review LOW-6 finding: Store.snapshot returns (nil, nil) when a Store +// carries neither a wire NOR a cached handshake, and Store.Counter() — unlike +// Sweeper() and BatchApplier() — never calls roleWire first, so a Counter +// built this way is reachable through the ordinary public accessor. Before +// the nil guard in refuseUnservedScope, a scoped count against such a Counter +// paniced on snap.Capabilities rather than refusing. +// +// Passing a nil snapshot through New is the direct, minimal reproduction: +// Store.Counter() builds on whatever New was given, with no roleWire gate to +// go through first. +func TestCounterRefusesScopeGracefullyWithNoTransportAndNoSnapshot(t *testing.T) { + counter, err := New(testTarget(t), nil, nil).Counter() + if err != nil { + t.Fatalf("Counter(): %v", err) + } + + _, err = counter.Count(t.Context(), issueops.CountRequest{ParentID: "bd-1"}) + if err == nil { + t.Fatal("Count returned no error, want a graceful capability refusal rather than a panic") + } + var unsup *storage.ErrUnsupported + if !errors.As(err, &unsup) { + t.Fatalf("errors.As to *storage.ErrUnsupported failed for %v", err) + } + if unsup.Capability != wire.CapCountScope { + t.Errorf("Capability = %q, want %q", unsup.Capability, wire.CapCountScope) + } + + _, err = counter.CountByGroup(t.Context(), issueops.CountByGroupRequest{ + Filter: issueops.CountRequest{NoParent: true}, GroupBy: issueops.CountGroupStatus, + }) + if err == nil { + t.Fatal("CountByGroup returned no error, want a graceful capability refusal rather than a panic") + } + if !errors.As(err, &unsup) { + t.Fatalf("errors.As to *storage.ErrUnsupported failed for %v", err) + } + if unsup.Capability != wire.CapCountScope { + t.Errorf("Capability = %q, want %q", unsup.Capability, wire.CapCountScope) + } +} diff --git a/internal/httpclient/encode/ledger.go b/internal/httpclient/encode/ledger.go index 605226c27..f40002da3 100644 --- a/internal/httpclient/encode/ledger.go +++ b/internal/httpclient/encode/ledger.go @@ -759,7 +759,9 @@ func writeSideRows() []Row { // createIssue's own edge publishes `reverse` and `metadata` (its issue // HAS an id for a target to point back at, which a batch item does // not), so the client sends both there. Only ThreadID is refused on - // both, because no operation publishes a thread member. + // both, because neither create schema publishes a thread member — a + // batch apply's dep_add item does, which retired its own row + // (W-DepAddItem.ThreadID) but not these. createDependencyRow("Reverse", "an edge written from the target back to the new issue refuses ON A BATCH CREATE", "BatchCreateDependency carries target_id and type only; dropping Reverse would write the edge in the OPPOSITE direction from the one asked for, which is a different graph. createIssue's CreateIssueDependency DOES publish it, and the single-create path sends it"), createDependencyRow("Metadata", "typed edge metadata refuses ON A BATCH CREATE", @@ -834,21 +836,20 @@ func writeSideRows() []Row { PinnedBy: applyPin, }, { - ID: "W-DepAddItem.HasSpawner", Kind: KindRefuse, + ID: "W-DepAddItem.HasSpawner", Kind: KindRetired, Type: tyApplyDepAddItem, Field: "HasSpawner", - What: "a waits-for edge ITEM that names its spawner refuses", - Why: "ApplyDepAddItem publishes source, target, type and metadata and no spawner member, and the flag asks for a write only the ROLE can make: metadata's spawner_id, stamped from the resolved target once every id in the batch exists, because a target named by key has no id before then. " + - "Dropping the flag would store the edge's gate-only metadata, so an edge whose caller named a spawner would carry none. On every other edge type the role ignores the flag and stores the same row either way, so there it is dropped rather than refused. Upstream ask: a spawner member on ApplyDepAddItem, which retires this row", - SpecRow: "D8 refuse-not-drop", + What: "a waits-for edge ITEM that names its spawner used to refuse", + Why: "RETIRED by issues.batchApply.depAddLineage (S5). ApplyDepAddItem now publishes `has_spawner` — the write this row said only the role could make, metadata's spawner_id stamped from the resolved target — gated on the capability rather than dropped: a caller on a server that has not advertised the token refuses locally before the dial (BatchApplier.refuseUnservedDepAddLineage), and a caller on a server that has sends the member exactly as given. " + + "The flag is sent, and gated, on a waits-for edge only, the one type the role reads it on. Off a waits-for edge it is the role's no-op, so the client drops it there without loss — the stored row is the same either way — rather than refusing a request the flag cannot change, or sending an older server a member it answers with a 400", + SpecRow: "D8 refuse-not-drop (RETIRED)", PinnedBy: applyPin, }, { - ID: "W-DepAddItem.ThreadID", Kind: KindRefuse, + ID: "W-DepAddItem.ThreadID", Kind: KindRetired, Type: tyApplyDepAddItem, Field: "ThreadID", - What: "associating an edge ITEM with a discussion thread refuses", - Why: "ApplyDepAddItem publishes no thread member, and no operation on this surface does: W-CreateDependency.ThreadID refuses the same column on both create edges. Dropping it would store the edge with no thread, so a replies-to edge would lose the conversation it was written for. " + - "It is a row of its own rather than a citation of that one for W-CreateItem.Issue's reason: the operation is different", - SpecRow: "D8 refuse-not-drop", + What: "associating an edge ITEM with a discussion thread used to refuse", + Why: "RETIRED with W-DepAddItem.HasSpawner (S5, issues.batchApply.depAddLineage). ApplyDepAddItem now publishes `thread_id` as a plain column on the stored edge, gated by the same capability and the same pre-dial refusal rather than dropped — a caller naming a thread on an unadvertising server is refused before the dial, never silently stored with no thread", + SpecRow: "D8 refuse-not-drop (RETIRED)", PinnedBy: applyPin, }, { diff --git a/internal/httpclient/served_batch_apply_large_test.go b/internal/httpclient/served_batch_apply_large_test.go new file mode 100644 index 000000000..424dc41e9 --- /dev/null +++ b/internal/httpclient/served_batch_apply_large_test.go @@ -0,0 +1,155 @@ +//go:build cgo + +// Written fresh for OSS beads S5 (no bd-enterprise source copied). + +package httpclient + +import ( + "errors" + "testing" + + "github.com/steveyegge/beads/internal/storage/batchfixtures" + "github.com/steveyegge/beads/internal/types" + "github.com/steveyegge/beads/issueops" +) + +// TestServedBatchApplyShape356CommitsAtomically and +// TestServedBatchApplyShape356PlusAStaleGuardLeavesZeroRows are the http +// leg's half of slice S5's named trio ("a 356-item plan against a masked +// server refuses pre-dial; against the main server it commits atomically; an +// injected mid-plan failure leaves zero rows"). The masked-server half lives +// in internal/httpclient/wire (TestApplyBatchAt356ItemsWithoutTheCapabilityRefusesBeforeDialing): +// the item-count gate it exercises never looks past len(body.Items), so a +// synthetic plan there is behaviorally identical to a REAL +// batchfixtures.Shape356 plan for that one gate. These two cases are what a +// REALISTIC, heterogeneous 356-item plan (the design's primary measured +// shape: 102 creates with metadata, 136 blocks edges, 102 tracks-to-root +// edges, 16 assign updates) must still do once past that gate: commit every +// row in one transaction, or refuse the whole thing and leave none. +// +// Both drive the real in-process bd serve stack (newServedEnv), which +// unconditionally advertises issues.batchApplyLarge in its static +// behaviorCapabilities -- so neither needs the masked handshake the other +// case already covers; they are about the CONTENT this gate lets through, +// not the gate itself. + +// TestServedBatchApplyShape356CommitsAtomically applies the full 356-item +// shape once and asserts the whole plan actually landed: every create's key +// bound to a minted id, and the issues table holding exactly one row per +// create on top of the pre-seeded root -- proving the client's positional +// result-decoding and key-binding checks (decodeApplyBatchResult, +// checkApplyKeyBinding) hold up at this scale, not only on the handful-of- +// items plans the rest of served_batch_apply_test.go uses. +func TestServedBatchApplyShape356CommitsAtomically(t *testing.T) { + env := newServedEnv(t, "hbalg0") + ctx := t.Context() + + root := &types.Issue{Title: "root", Status: types.StatusOpen, Priority: 2, IssueType: types.TypeTask} + if err := env.createIssue(ctx, root, "tester"); err != nil { + t.Fatalf("seed root issue: %v", err) + } + + applier, err := env.subject.BatchApplier() + if err != nil { + t.Fatalf("BatchApplier(): %v", err) + } + + plan := batchfixtures.Shape356("tester", root.ID) + wantCreates := 0 + for _, item := range plan.Items { + if item.Kind == issueops.ItemCreate { + wantCreates++ + } + } + + result, err := applier.ApplyBatch(ctx, plan) + if err != nil { + t.Fatalf("ApplyBatch(%d items): %v", len(plan.Items), err) + } + if len(result.Items) != len(plan.Items) { + t.Fatalf("got %d item results, want %d (one per requested item)", len(result.Items), len(plan.Items)) + } + if len(result.Keys) != wantCreates { + t.Errorf("got %d bound keys, want %d (one per named create)", len(result.Keys), wantCreates) + } + + var createdRows int + if err := env.queryScalar(ctx, "SELECT COUNT(*) FROM issues WHERE id != ?", []any{root.ID}, &createdRows); err != nil { + t.Fatalf("count created rows: %v", err) + } + if createdRows != wantCreates { + t.Errorf("issues table holds %d non-root row(s) after a %d-item apply, want %d (every create must have landed, none dropped or duplicated)", + createdRows, len(plan.Items), wantCreates) + } +} + +// TestServedBatchApplyShape356PlusAStaleGuardLeavesZeroRows is the "injected +// mid-plan failure" half: the full 356-item shape, plus one more item at the +// tail guarding the PRE-EXISTING root issue with a deliberately stale +// ExpectedVersion. The root is never created or touched by any of the 356 +// shape items, so this guard takes the real precondition_failed round trip +// (not the static "guard on a row this same request already wrote" refusal +// RunBatchApplyRefusesExpectedVersionOnARowAnEarlierItemCreated/Touched pin +// elsewhere) -- proving, at realistic scale, both Requirement 2 (a batch +// item's ExpectedVersion rides the strict revision token and a server-side +// precondition_failed maps back to issueops.ErrVersionMismatch via +// errors.Is) and the "never chunk" ceiling: a 357-item ALL-OR-NOTHING +// request that fails on its last item must leave NONE of the other 356 +// rows behind, which a client that silently split the request into several +// smaller ones could not guarantee. +func TestServedBatchApplyShape356PlusAStaleGuardLeavesZeroRows(t *testing.T) { + env := newServedEnv(t, "hbalg1") + ctx := t.Context() + + root := &types.Issue{Title: "root", Status: types.StatusOpen, Priority: 2, IssueType: types.TypeTask} + if err := env.createIssue(ctx, root, "tester"); err != nil { + t.Fatalf("seed root issue: %v", err) + } + + applier, err := env.subject.BatchApplier() + if err != nil { + t.Fatalf("BatchApplier(): %v", err) + } + + plan := batchfixtures.Shape356("tester", root.ID) + staleVersion := int64(999999) + plan.Items = append(plan.Items, issueops.ApplyItem{ + Kind: issueops.ItemUpdate, + Update: &issueops.UpdateItem{ + Target: issueops.Ref{ID: root.ID}, + Patch: issueops.IssuePatch{Title: issueops.Field[string]{Set: true, Value: "clobbered"}}, + ExpectedVersion: &staleVersion, + }, + }) + lastIndex := len(plan.Items) - 1 + + _, err = applier.ApplyBatch(ctx, plan) + if !errors.Is(err, issueops.ErrVersionMismatch) { + t.Fatalf("a stale ExpectedVersion on a %d-item plan: error = %v, want ErrVersionMismatch", len(plan.Items), err) + } + var itemErr *issueops.ItemError + if !errors.As(err, &itemErr) { + t.Fatalf("error = %v, want the refusal wrapped in an *ItemError naming the item", err) + } + if itemErr.Index != lastIndex || itemErr.IssueID != root.ID { + t.Errorf("ItemError = %#v, want Index %d acting on %s", itemErr, lastIndex, root.ID) + } + + // Nothing from the 356-item shape landed: no creates, and the root's own + // title is untouched by the refused guard. + var createdRows int + if err := env.queryScalar(ctx, "SELECT COUNT(*) FROM issues WHERE id != ?", []any{root.ID}, &createdRows); err != nil { + t.Fatalf("count created rows: %v", err) + } + if createdRows != 0 { + t.Errorf("issues table holds %d non-root row(s) after a refused %d-item apply, want 0 (an all-or-nothing request must leave nothing behind)", + createdRows, len(plan.Items)) + } + var title string + if err := env.queryScalar(ctx, "SELECT title FROM issues WHERE id = ?", []any{root.ID}, &title); err != nil { + t.Fatalf("read back root title: %v", err) + } + if title != root.Title { + t.Errorf("root title = %q after a refused guard, want unchanged %q", title, root.Title) + } +} diff --git a/internal/httpclient/served_batch_apply_test.go b/internal/httpclient/served_batch_apply_test.go index f6c8a6257..d7fa20172 100644 --- a/internal/httpclient/served_batch_apply_test.go +++ b/internal/httpclient/served_batch_apply_test.go @@ -6,6 +6,8 @@ package httpclient import ( + "context" + "encoding/json" "errors" "strings" "testing" @@ -34,9 +36,11 @@ import ( // shared database would turn an id collision between two contracts into a // debugging session. -// applyParkBead owns this family's two parks: L-apply-ref's unparks when the -// wire grows a typed ref-key member on the problem document, and -// W-DepAddItem.HasSpawner's when ApplyDepAddItem publishes a spawner member. +// applyParkBead owns this family's one remaining park: L-apply-ref's unparks +// when the wire grows a typed ref-key member on the problem document. +// W-DepAddItem.HasSpawner's park UNPARKED under issues.batchApply.depAddLineage +// (S5) — ApplyDepAddItem now publishes a spawner member — and +// TestServedBatchApplyStampsSpawnerIDOnlyWhenNamed runs unskipped below. const applyParkBead = "ga-mijra" func newServedBatchApplyFixture(t *testing.T, prefix string) conformance.BatchApplyFixture { @@ -174,18 +178,6 @@ func TestServedBatchApplyNormalizesTheWaitsForGate(t *testing.T) { conformance.RunBatchApplyNormalizesTheWaitsForGate(t, t.Context(), newServedBatchApplyFixture(t, "hba1c")) } -// TestServedBatchApplyStampsSpawnerIDOnlyWhenNamed parks on the edge item's -// spawner flag. The case's second half, an edge that names no spawner, is what -// this wire writes for every waits-for edge; its first half is the item the -// client refuses. -func TestServedBatchApplyStampsSpawnerIDOnlyWhenNamed(t *testing.T) { - skipKnownDivergence(t, "W-DepAddItem.HasSpawner", applyParkBead, - "the case names a spawner on a waits-for edge (DepAddItem.HasSpawner), and ApplyDepAddItem publishes no "+ - "spawner member, so the client refuses the item rather than letting the server store the edge without "+ - "the spawner_id the role would stamp from its resolved target.") - conformance.RunBatchApplyStampsSpawnerIDOnlyWhenNamed(t, t.Context(), newServedBatchApplyFixture(t, "hba27")) -} - func TestServedBatchApplySplicesAForwardMetadataRef(t *testing.T) { conformance.RunBatchApplySplicesAForwardMetadataRef(t, t.Context(), newServedBatchApplyFixture(t, "hba1d")) } @@ -255,6 +247,43 @@ func TestServedBatchApplyRefusesAnUnusableRequest(t *testing.T) { conformance.RunBatchApplyRefusesAnUnusableRequest(t, t.Context(), newServedBatchApplyFixture(t, "hba26")) } +// TestServedBatchApplyStampsSpawnerIDOnlyWhenNamed wires the dep_add +// HasSpawner/ThreadID lineage conformance case onto the http leg (S5): a +// served default Config always advertises CapBatchApplyDepAddLineage (it is +// in httpapi's unconditional behaviorCapabilities), so this exercises the +// member on the WIRE, round-tripping through refuseUnservedDepAddLineage's +// pre-dial check (which never fires here, since the capability is present) +// and applyDepAddItemBody's encoding, server-side batch_apply.go decode, and +// the role's own StampWaitsForSpawnerID. +func TestServedBatchApplyStampsSpawnerIDOnlyWhenNamed(t *testing.T) { + conformance.RunBatchApplyStampsSpawnerIDOnlyWhenNamed(t, t.Context(), newServedBatchApplyFixture(t, "hba27")) +} + +// TestServedBatchApplyCarriesThreadIDOntoTheStoredEdge wires +// DepAddItem.ThreadID's round trip onto the http leg (S5, 2026-10 Opus-review +// HIGH-2): this is the ONE case that proves the field survives BOTH sides of +// the wire at once — the client's applyDepAddItemBody encode and the server's +// applyDepAddItemMembers decode — since either one dropping thread_id leaves +// the raw dependencies row's thread_id column blank and fails the assertion. +func TestServedBatchApplyCarriesThreadIDOntoTheStoredEdge(t *testing.T) { + conformance.RunBatchApplyCarriesThreadIDOntoTheStoredEdge(t, t.Context(), newServedBatchApplyFixture(t, "hba28")) +} + +// TestServedBatchApplyCarriesThreadIDOntoAnExistingEdge wires the re-add arm of +// the same round trip: a thread named on a dep_add whose edge already exists +// must cross the wire and reach the stored row, not stop at the server's +// change-free check. +func TestServedBatchApplyCarriesThreadIDOntoAnExistingEdge(t *testing.T) { + conformance.RunBatchApplyCarriesThreadIDOntoAnExistingEdge(t, t.Context(), newServedBatchApplyFixture(t, "hba29")) +} + +// TestServedBatchApplyRefusesAThreadIDLongerThanItsColumn wires the thread_id +// bound onto the http leg, where the server's decode refuses it before the +// role's plan would; both have to arrive as the same ErrValidation. +func TestServedBatchApplyRefusesAThreadIDLongerThanItsColumn(t *testing.T) { + conformance.RunBatchApplyRefusesAThreadIDLongerThanItsColumn(t, t.Context(), newServedBatchApplyFixture(t, "hba2a")) +} + // TestServedBatchApplyRefusesAMetadataRefWithoutNamingTheKey is the running pin // beside the park above: the same request, driven end to end, asserting // everything the contract asserts EXCEPT the key inside the member — the @@ -455,3 +484,212 @@ func TestServedBatchApplyAnswersEveryItemWithoutASnapshot(t *testing.T) { } } } + +// TestServedBatchApplyGcCloseWithMetadataIfMatch pins the first of DESIGN +// §3.8's two gc mappings (2026-10 Opus-review HIGH-3, no new bd surface): gc's +// RAW-transaction CloseWithMetadataIfMatch maps onto BatchApplier[update{Patch +// Metadata, ExpectedVersion}, close{}] in ONE request — see the BatchApplier +// package doc. +// +// It is atomic because the whole request is: the matching-version half lands +// both the metadata write and the close together, and the stale-version half +// below refuses the update, which refuses the request, so the close beside it +// never runs and NEITHER change lands. +func TestServedBatchApplyGcCloseWithMetadataIfMatch(t *testing.T) { + ctx := t.Context() + fixture := newServedBatchApplyFixture(t, "hbagc0") + + id := fixture.IssuePrefix + "-close-with-metadata" + if err := fixture.CreateIssue(ctx, &types.Issue{ID: id, Title: "closed with a metadata guard", Status: types.StatusOpen, Priority: 2, IssueType: types.TypeTask}, "apply-seed"); err != nil { + t.Fatalf("seeding %s: %v", id, err) + } + var version int64 + if err := fixture.QueryScalar(ctx, "SELECT row_lock FROM issues WHERE id = ?", []any{id}, &version); err != nil { + t.Fatalf("reading row_lock for %s: %v", id, err) + } + + _, err := fixture.BatchApplier.ApplyBatch(ctx, issueops.ApplyBatchRequest{ + Actor: "apply-writer", + Items: []issueops.ApplyItem{ + {Kind: issueops.ItemUpdate, Update: &issueops.UpdateItem{ + Target: issueops.Ref{ID: id}, + Patch: issueops.IssuePatch{Metadata: issueops.MetadataPatch{ + Merge: issueops.Field[json.RawMessage]{Set: true, Value: json.RawMessage(`{"closed_via":"gc"}`)}, + }}, + ExpectedVersion: &version, + }}, + {Kind: issueops.ItemClose, Close: &issueops.CloseItem{Target: issueops.Ref{ID: id}}}, + }, + }) + if err != nil { + t.Fatalf("CloseWithMetadataIfMatch with the current version: %v", err) + } + if got := batchApplyColumnDirect(t, ctx, &fixture, "status", id); got != string(types.StatusClosed) { + t.Errorf("status = %q, want %q", got, types.StatusClosed) + } + if got := batchApplyColumnDirect(t, ctx, &fixture, "metadata", id); !strings.Contains(got, "closed_via") { + t.Errorf("metadata = %q, want it to carry the merged key", got) + } + + // The stale half: the same shape, a version that is no longer current. The + // WHOLE request refuses and ZERO rows change — neither the metadata merge + // nor the close. + id2 := fixture.IssuePrefix + "-close-with-metadata-stale" + if err := fixture.CreateIssue(ctx, &types.Issue{ID: id2, Title: "a stale guard leaves zero changes", Status: types.StatusOpen, Priority: 2, IssueType: types.TypeTask}, "apply-seed"); err != nil { + t.Fatalf("seeding %s: %v", id2, err) + } + var version2 int64 + if err := fixture.QueryScalar(ctx, "SELECT row_lock FROM issues WHERE id = ?", []any{id2}, &version2); err != nil { + t.Fatalf("reading row_lock for %s: %v", id2, err) + } + stale := version2 - 1 + _, err = fixture.BatchApplier.ApplyBatch(ctx, issueops.ApplyBatchRequest{ + Actor: "apply-writer", + Items: []issueops.ApplyItem{ + {Kind: issueops.ItemUpdate, Update: &issueops.UpdateItem{ + Target: issueops.Ref{ID: id2}, + Patch: issueops.IssuePatch{Metadata: issueops.MetadataPatch{ + Merge: issueops.Field[json.RawMessage]{Set: true, Value: json.RawMessage(`{"closed_via":"gc"}`)}, + }}, + ExpectedVersion: &stale, + }}, + {Kind: issueops.ItemClose, Close: &issueops.CloseItem{Target: issueops.Ref{ID: id2}}}, + }, + }) + if !errors.Is(err, issueops.ErrVersionMismatch) { + t.Fatalf("a stale ExpectedVersion: error = %v, want ErrVersionMismatch", err) + } + if got := batchApplyColumnDirect(t, ctx, &fixture, "status", id2); got == string(types.StatusClosed) { + t.Error("the close landed despite the whole request refusing on the stale guard") + } + if got := batchApplyColumnDirect(t, ctx, &fixture, "metadata", id2); strings.Contains(got, "closed_via") { + t.Error("the metadata merge landed despite the whole request refusing on the stale guard") + } +} + +// batchApplyColumnDirect reads one issues column directly, for the two gc- +// mapping tests above: they are plain package tests rather than +// conformance.Run* cases (the composition is http-leg-only, DESIGN §3.8), so +// they cannot reach the conformance package's unexported batchApplyColumn. +func batchApplyColumnDirect(t *testing.T, ctx context.Context, fixture *conformance.BatchApplyFixture, column, id string) string { + t.Helper() + var value string + //nolint:gosec // G201: column is one of this file's own hardcoded names. + query := "SELECT COALESCE(" + column + ", '') FROM issues WHERE id = ?" + if err := fixture.QueryScalar(ctx, query, []any{id}, &value); err != nil { + t.Fatalf("reading issues.%s for %s: %v", column, id, err) + } + return value +} + +// TestServedBatchApplyGcApplyGraphPlan pins the second of DESIGN §3.8's two gc +// mappings (2026-10 Opus-review HIGH-3): gc's RAW RunInTransaction graph-build +// maps onto one BatchApplier request carrying every item kind the plan needs — +// a keyed create, a MetadataRefs splice, a dep_add edge, a parent-child +// dep_add edge, a waits-for edge naming its spawner by key and carrying a +// thread, and a trailing update for AssignAfterCreate — landing together as +// the one plan a caller composed. +func TestServedBatchApplyGcApplyGraphPlan(t *testing.T) { + ctx := t.Context() + fixture := newServedBatchApplyFixture(t, "hbagc1") + + epic := fixture.IssuePrefix + "-plan-epic" + task := fixture.IssuePrefix + "-plan-task" + blocker := fixture.IssuePrefix + "-plan-blocker" + + result, err := fixture.BatchApplier.ApplyBatch(ctx, issueops.ApplyBatchRequest{ + Actor: "apply-writer", + ForceIDPrefix: true, + Items: []issueops.ApplyItem{ + // A keyed create: the plan's root node. + {Kind: issueops.ItemCreate, Create: &issueops.CreateItem{ + Key: "epic", + Issue: &issueops.Issue{ID: epic, Title: "the plan's root", Status: types.StatusOpen, Priority: 2, IssueType: types.TypeTask}, + }}, + // A second node whose metadata reaches BACKWARD to the epic's minted + // id via MetadataRefs — the splice CreateItem.MetadataRefs documents. + {Kind: issueops.ItemCreate, Create: &issueops.CreateItem{ + Key: "task", + Issue: &issueops.Issue{ID: task, Title: "spliced to its epic", Status: types.StatusOpen, Priority: 2, IssueType: types.TypeTask}, + MetadataRefs: map[string]issueops.Ref{"epic_id": {Key: "epic"}}, + }}, + {Kind: issueops.ItemCreate, Create: &issueops.CreateItem{ + Key: "blocker", + Issue: &issueops.Issue{ID: blocker, Title: "blocks the task", Status: types.StatusOpen, Priority: 2, IssueType: types.TypeTask}, + }}, + // A dep_add edge, plain. + {Kind: issueops.ItemDepAdd, DepAdd: &issueops.DepAddItem{ + Source: issueops.Ref{Key: "task"}, Target: issueops.Ref{Key: "blocker"}, Type: issueops.DepBlocks, + }}, + // A dep_add edge of type parent-child — "parent-child included", same + // item kind as the one above, a different Type. + {Kind: issueops.ItemDepAdd, DepAdd: &issueops.DepAddItem{ + Source: issueops.Ref{Key: "task"}, Target: issueops.Ref{Key: "epic"}, Type: issueops.DepParentChild, + }}, + // A waits-for edge whose spawner is named by plan KEY, with a thread: + // the lineage gc's mapping carries (issues.batchApply.depAddLineage). + // The spawner stamp can only resolve once that key has an id. + {Kind: issueops.ItemDepAdd, DepAdd: &issueops.DepAddItem{ + Source: issueops.Ref{Key: "epic"}, Target: issueops.Ref{Key: "blocker"}, Type: issueops.DepWaitsFor, + HasSpawner: true, ThreadID: "th-plan", + }}, + // A trailing update for AssignAfterCreate, resolving the key BACKWARD + // to the row the first items in this same request just minted. + {Kind: issueops.ItemUpdate, Update: &issueops.UpdateItem{ + Target: issueops.Ref{Key: "task"}, + Patch: issueops.IssuePatch{Assignee: issueops.Field[string]{Set: true, Value: "alice"}}, + }}, + }, + }) + if err != nil { + t.Fatalf("ApplyGraphPlan: %v", err) + } + if len(result.Items) != 7 { + t.Fatalf("ApplyBatch(7 items) returned %d item results", len(result.Items)) + } + + var metadata string + if err := fixture.QueryScalar(ctx, "SELECT COALESCE(metadata, '') FROM issues WHERE id = ?", []any{task}, &metadata); err != nil { + t.Fatalf("reading the spliced metadata: %v", err) + } + if !strings.Contains(metadata, result.Keys["epic"]) { + t.Errorf("task metadata = %q, want the epic's minted id %s spliced over epic_id", metadata, result.Keys["epic"]) + } + + var edges int + const edgeQuery = `SELECT COUNT(*) FROM dependencies WHERE issue_id = ? AND type = ? + AND COALESCE(depends_on_issue_id, depends_on_wisp_id, depends_on_external) = ?` + if err := fixture.QueryScalar(ctx, edgeQuery, []any{task, "blocks", blocker}, &edges); err != nil { + t.Fatalf("counting the blocks edge: %v", err) + } + if edges != 1 { + t.Errorf("blocks edges task->blocker = %d, want 1", edges) + } + if err := fixture.QueryScalar(ctx, edgeQuery, []any{task, "parent-child", epic}, &edges); err != nil { + t.Fatalf("counting the parent-child edge: %v", err) + } + if edges != 1 { + t.Errorf("parent-child edges task->epic = %d, want 1", edges) + } + + var waitsFor, thread string + const lineageQuery = `SELECT COALESCE(metadata, ''), COALESCE(thread_id, '') FROM dependencies + WHERE issue_id = ? AND type = ? AND COALESCE(depends_on_issue_id, depends_on_wisp_id, depends_on_external) = ?` + if err := fixture.QueryScalar(ctx, lineageQuery, []any{epic, "waits-for", blocker}, &waitsFor, &thread); err != nil { + t.Fatalf("reading the waits-for edge epic->blocker: %v", err) + } + var meta types.WaitsForMeta + if err := json.Unmarshal([]byte(waitsFor), &meta); err != nil { + t.Fatalf("waits-for metadata %q is not a gate object: %v", waitsFor, err) + } + if meta.SpawnerID != result.Keys["blocker"] { + t.Errorf("waits-for spawner_id = %q, want the blocker key's minted id %q", meta.SpawnerID, result.Keys["blocker"]) + } + if thread != "th-plan" { + t.Errorf("waits-for thread_id = %q, want %q", thread, "th-plan") + } + + if got := batchApplyColumnDirect(t, ctx, &fixture, "assignee", task); got != "alice" { + t.Errorf("task assignee = %q, want %q (AssignAfterCreate)", got, "alice") + } +} diff --git a/internal/httpclient/served_memories_deps_test.go b/internal/httpclient/served_memories_deps_test.go index 6d97f1d8b..014f38ce3 100644 --- a/internal/httpclient/served_memories_deps_test.go +++ b/internal/httpclient/served_memories_deps_test.go @@ -416,7 +416,7 @@ func TestServedDependencyEditorClosedChildAddSatisfiesAnAnyChildrenGate(t *testi conformance.RunDependencyEditorClosedChildAddSatisfiesAnAnyChildrenGate(t, t.Context(), newServedDependencyEditorFixture(t, "hd38")) } -// The two same-type re-add cases, newly wired: both drive the re-add through +// The same-type re-add cases, newly wired: each drives the re-add through // fixture.AddDependency (the reference store's own raw path, same reason // ClosedChildAddSatisfiesAnAnyChildrenGate reaches past the role above) and // need dual-write version history on, which the fixture now wires onto the @@ -429,3 +429,7 @@ func TestServedDependencyEditorSameTypeReAddWithChangedMetadataMintsOneVersion(t func TestServedDependencyEditorSameTypeReAddWithIdenticalMetadataIsANoOp(t *testing.T) { conformance.RunDependencyEditorSameTypeReAddWithIdenticalMetadataIsANoOp(t, t.Context(), newServedDependencyEditorFixture(t, "hd40")) } + +func TestServedDependencyEditorSameTypeReAddWithChangedThreadMintsOneVersion(t *testing.T) { + conformance.RunDependencyEditorSameTypeReAddWithChangedThreadMintsOneVersion(t, t.Context(), newServedDependencyEditorFixture(t, "hd41")) +} diff --git a/internal/httpclient/sweeper.go b/internal/httpclient/sweeper.go index 28b0e9785..f9c2a7a00 100644 --- a/internal/httpclient/sweeper.go +++ b/internal/httpclient/sweeper.go @@ -135,13 +135,21 @@ func (s *httpSweeper) refuseUnservedSweep(ctx context.Context, tier apigen.Sweep if err != nil { return err } - if tier == apigen.WispsPlane && !slices.Contains(snap.Capabilities, wire.CapSweepWispsPlane) { + // snap is nil, nil whenever Store.snapshot has no transport AND no cached + // handshake (a Store built with a nil wire): nothing was ever advertised, + // so every check below reads a nil capability list rather than + // dereferencing a nil *apigen.ContextResponse. + var capabilities []string + if snap != nil { + capabilities = snap.Capabilities + } + if tier == apigen.WispsPlane && !slices.Contains(capabilities, wire.CapSweepWispsPlane) { return s.store.unsupportedCapability("Sweeper.Sweep", wire.CapSweepWispsPlane) } - if req.ProtectLiveDependents && !slices.Contains(snap.Capabilities, wire.CapSweepLiveDependents) { + if req.ProtectLiveDependents && !slices.Contains(capabilities, wire.CapSweepLiveDependents) { return s.store.unsupportedCapability("Sweeper.Sweep", wire.CapSweepLiveDependents) } - if req.Limit != 0 && !slices.Contains(snap.Capabilities, wire.CapSweepLimit) { + if req.Limit != 0 && !slices.Contains(capabilities, wire.CapSweepLimit) { return s.store.unsupportedCapability("Sweeper.Sweep", wire.CapSweepLimit) } return nil diff --git a/internal/httpclient/wire/handshake.go b/internal/httpclient/wire/handshake.go index 13b10b586..b7db819c2 100644 --- a/internal/httpclient/wire/handshake.go +++ b/internal/httpclient/wire/handshake.go @@ -195,6 +195,15 @@ const CapSweepLiveDependents = "issues.sweep.liveDependents" // of what used to be a permanent refusal. const CapSweepLimit = "issues.sweep.limit" +// CapBatchApplyDepAddLineage is the behavior capability announcing that +// issues.batchApply's dep_add items accept `has_spawner` and `thread_id`, +// spelled exactly as httpapi's constant of the same name (held to it by +// TestCapabilityTableMatchesTheServerRouteTable). batchapplier.go reads this +// token before sending either field, refusing locally with a typed +// capability error rather than silently dropping graph lineage a caller +// asked to carry against an older server. +const CapBatchApplyDepAddLineage = "issues.batchApply.depAddLineage" + // CapExternalDependencies is the CONDITIONAL behavior capability announcing // that the ready, claim and close operations of this server apply bd's // external-dependency policy themselves, spelled exactly as httpapi's constant @@ -335,6 +344,7 @@ func (e *WireRevisionSkewError) Unwrap() error { return ErrWireRevisionSkew } var behaviorCapabilities = []string{ CapProjectEnforce, CapBatchApplyLarge, CapListSort, CapCountScope, CapSweepWispsPlane, CapSweepLiveDependents, CapSweepLimit, + CapBatchApplyDepAddLineage, } // CapabilityFor reports the capability token gating op, and whether op is on diff --git a/internal/httpclient/wire/vocabulary_test.go b/internal/httpclient/wire/vocabulary_test.go index 1bee3f45c..23d98908d 100644 --- a/internal/httpclient/wire/vocabulary_test.go +++ b/internal/httpclient/wire/vocabulary_test.go @@ -195,9 +195,11 @@ func TestTheProjectIdentityVocabularyMatchesTheServer(t *testing.T) { if !slices.Equal(behaviorCapabilities, []string{ httpapi.CapProjectEnforce, httpapi.CapBatchApplyLarge, httpapi.CapIssuesListSort, httpapi.CapIssuesCountScope, httpapi.CapIssuesSweepWispsPlane, httpapi.CapIssuesSweepLiveDependents, httpapi.CapIssuesSweepLimit, + httpapi.CapBatchApplyDepAddLineage, }) { t.Errorf("behaviorCapabilities = %v, want the server's project.enforce, issues.batchApplyLarge, issues.list.sort, "+ - "issues.count.scope, issues.sweep.wispsPlane, issues.sweep.liveDependents and issues.sweep.limit tokens", behaviorCapabilities) + "issues.count.scope, issues.sweep.wispsPlane, issues.sweep.liveDependents, issues.sweep.limit and "+ + "issues.batchApply.depAddLineage tokens", behaviorCapabilities) } } diff --git a/internal/httpclient/wire/writes_batch_cap_test.go b/internal/httpclient/wire/writes_batch_cap_test.go index c023b090b..c3d6d4a5e 100644 --- a/internal/httpclient/wire/writes_batch_cap_test.go +++ b/internal/httpclient/wire/writes_batch_cap_test.go @@ -97,6 +97,40 @@ func TestApplyBatchBetweenTheFloorAndTheCeilingWithTheCapabilitySucceeds(t *test } } +// TestApplyBatchAt356ItemsWithoutTheCapabilityRefusesBeforeDialing exercises +// the item-count gate at exactly 356 items -- the design's primary measured +// large-batch-apply shape (internal/storage/batchfixtures.Shape356) -- rather +// than only at the floor+1/ceiling+1 boundaries the other cases above pin. +// applyBatchRequestOfSize's own doc comment is why a synthetic 356-item plan +// is behaviorally identical to a real Shape356 plan for THIS gate: the cap +// logic never looks past len(body.Items). What a REALISTIC Shape356 payload +// must still get past this same gate -- and commit atomically once it does -- +// is covered end-to-end against the real served stack by +// internal/httpclient's TestServedBatchApplyShape356CommitsAtomically and +// TestServedBatchApplyShape356PlusAStaleGuardLeavesZeroRows. +func TestApplyBatchAt356ItemsWithoutTheCapabilityRefusesBeforeDialing(t *testing.T) { + c, rec := newTestClient(t, Options{}, nil, serveEverything(contextBody("v0", "proj-1", withBatchApply()...))) + _, err := c.ApplyBatch(ctx(t), applyBatchRequestOfSize(356)) + + var capErr *CapabilityError + if !errors.As(err, &capErr) { + t.Fatalf("err = %v (%T), want *CapabilityError", err, err) + } + if capErr.Capability != CapBatchApplyLarge { + t.Errorf("Capability = %q, want %q", capErr.Capability, CapBatchApplyLarge) + } + // Never dialed past the handshake: a masked server (one that does not + // advertise CapBatchApplyLarge) must refuse a 356-item plan PRE-DIAL, the + // same way it refuses any other over-floor count. + if rec.count() != 1 { + t.Fatalf("made %d requests, want only the handshake (a 356-item plan must refuse pre-dial against a server that does not advertise %s)", + rec.count(), CapBatchApplyLarge) + } + if got := rec.at(t, 0).path; got != PathContext { + t.Errorf("only request = %q, want %q", got, PathContext) + } +} + func TestApplyBatchOverTheAbsoluteCeilingRefusesRegardlessOfTheCapability(t *testing.T) { for _, tc := range []struct { name string diff --git a/internal/httpclient/write_ledger_test.go b/internal/httpclient/write_ledger_test.go index 29967f9c0..945c51477 100644 --- a/internal/httpclient/write_ledger_test.go +++ b/internal/httpclient/write_ledger_test.go @@ -594,18 +594,24 @@ func writeShapes() []writeShape { }, }, { - // The edge item. The gate normalization a waits-for edge gets is - // the ROLE's and travels inside the blob. HasSpawner and ThreadID - // have no wire member, so they are absent from carried below and - // refuse under W-DepAddItem.HasSpawner and W-DepAddItem.ThreadID. + // The edge item. TOTAL. The gate normalization a waits-for edge + // gets is the ROLE's and travels inside the blob. HasSpawner and + // ThreadID are carried unconditionally at this structural layer — + // CapBatchApplyDepAddLineage is a separate, client-side refusal + // (batchapplier.go's refuseUnservedDepAddLineage) gating WHETHER + // this client sends either member against an older server, not + // whether the field reaches the wire body type at all. (HasSpawner + // off a waits-for edge is the role's no-op, dropped by value.) name: "applyBatch/item/dep_add", source: reflect.TypeOf(issueops.DepAddItem{}), body: reflect.TypeOf(apigen.ApplyDepAddItem{}), carried: map[string]carriage{ - "Source": member("source"), - "Target": member("target"), - "Type": member("type"), - "Metadata": member("metadata"), + "Source": member("source"), + "Target": member("target"), + "Type": member("type"), + "Metadata": member("metadata"), + "HasSpawner": member("has_spawner"), + "ThreadID": member("thread_id"), }, }, { diff --git a/internal/storage/batch_apply.go b/internal/storage/batch_apply.go index 1a2d30afb..6df88107b 100644 --- a/internal/storage/batch_apply.go +++ b/internal/storage/batch_apply.go @@ -243,8 +243,11 @@ func planApplyBatchClose(item *issueops.CloseItem, index int, keyIndex map[strin return nil } -// planApplyBatchDepAdd checks an edge's endpoints and type and normalizes its -// gate metadata. +// planApplyBatchDepAdd checks an edge's endpoints, type and thread id and +// normalizes its gate metadata. The thread id gets its column's bound here, the +// one the http leg's decode already applies, so an over-long one is +// ErrValidation before any database work on every leg rather than a storage +// error mid-transaction on the local ones. // // IT RECORDS NOTHING AS TOUCHED, and that is a decision rather than an // oversight. The ExpectedVersion rule above refuses a guard on a row this @@ -269,6 +272,9 @@ func planApplyBatchDepAdd(item *issueops.DepAddItem, index int, keyIndex map[str return fmt.Errorf("%w: apply batch item %d requires a dependency type (max %d chars)", issueops.ErrValidation, index, types.MaxDependencyTypeLen) } + if err := types.CheckFieldLen("dependency thread_id", item.ThreadID); err != nil { + return fmt.Errorf("%w: apply batch item %d: %v", issueops.ErrValidation, index, err) + } metadata, err := normalizeApplyEdgeMetadata(item.Type, item.Metadata) if err != nil { return fmt.Errorf("%w: apply batch item %d: %v", issueops.ErrValidation, index, err) diff --git a/internal/storage/dolt/batch_apply_contract_test.go b/internal/storage/dolt/batch_apply_contract_test.go index 7c32d9a37..13b950360 100644 --- a/internal/storage/dolt/batch_apply_contract_test.go +++ b/internal/storage/dolt/batch_apply_contract_test.go @@ -180,6 +180,21 @@ func TestBatchApplyContract(t *testing.T) { defer cancel() conformance.RunBatchApplyStampsSpawnerIDOnlyWhenNamed(t, ctx, fixture) }) + t.Run("CarriesThreadIDOntoTheStoredEdge", func(t *testing.T) { + ctx, cancel := testContext(t) + defer cancel() + conformance.RunBatchApplyCarriesThreadIDOntoTheStoredEdge(t, ctx, fixture) + }) + t.Run("CarriesThreadIDOntoAnExistingEdge", func(t *testing.T) { + ctx, cancel := testContext(t) + defer cancel() + conformance.RunBatchApplyCarriesThreadIDOntoAnExistingEdge(t, ctx, fixture) + }) + t.Run("RefusesAThreadIDLongerThanItsColumn", func(t *testing.T) { + ctx, cancel := testContext(t) + defer cancel() + conformance.RunBatchApplyRefusesAThreadIDLongerThanItsColumn(t, ctx, fixture) + }) t.Run("SplicesAForwardMetadataRef", func(t *testing.T) { ctx, cancel := testContext(t) defer cancel() diff --git a/internal/storage/dolt/dependency_commit_boundary_test.go b/internal/storage/dolt/dependency_commit_boundary_test.go index 19421828b..b952fd544 100644 --- a/internal/storage/dolt/dependency_commit_boundary_test.go +++ b/internal/storage/dolt/dependency_commit_boundary_test.go @@ -68,9 +68,21 @@ func (c *dependencyCommitBoundaryConn) QueryContext(_ context.Context, query str return &dependencyCommitBoundaryRows{columns: []string{"exists"}}, nil case strings.Contains(query, "SELECT issue_type FROM wisps WHERE id = ?"): return &dependencyCommitBoundaryRows{columns: []string{"issue_type"}, values: [][]driver.Value{{"task"}}}, nil + // The add path's existence probe reads the stored edge's metadata and + // thread_id alongside its type: a same-type re-add compares both to decide + // whether it changes anything. + case strings.Contains(query, "SELECT type, metadata, thread_id FROM dependencies"), + strings.Contains(query, "SELECT type, metadata, thread_id FROM wisp_dependencies"): + if c.driver.newEdge { + return &dependencyCommitBoundaryRows{columns: []string{"type", "metadata", "thread_id"}}, nil + } + return &dependencyCommitBoundaryRows{ + columns: []string{"type", "metadata", "thread_id"}, + values: [][]driver.Value{{"related", "{}", nil}}, + }, nil // The remove path reads the edge's metadata alongside its type: the events // journal records the removed edge's full payload so a consumer can replay - // it (bd-opisf). The add path's existence probe still selects type alone. + // it (bd-opisf). case strings.Contains(query, "SELECT type, metadata FROM dependencies"), strings.Contains(query, "SELECT type, metadata FROM wisp_dependencies"): if c.driver.newEdge { diff --git a/internal/storage/dolt/dependency_editor_contract_test.go b/internal/storage/dolt/dependency_editor_contract_test.go index 3f3b7d26a..f5fac1515 100644 --- a/internal/storage/dolt/dependency_editor_contract_test.go +++ b/internal/storage/dolt/dependency_editor_contract_test.go @@ -55,6 +55,12 @@ func TestDependencyEditorSameTypeReAddWithIdenticalMetadataIsANoOp(t *testing.T) conformance.RunDependencyEditorSameTypeReAddWithIdenticalMetadataIsANoOp(t, ctx, fixture) } +func TestDependencyEditorSameTypeReAddWithChangedThreadMintsOneVersion(t *testing.T) { + fixture, ctx, cleanup := newDoltDependencyEditorFixture(t, "idemthread") + defer cleanup() + conformance.RunDependencyEditorSameTypeReAddWithChangedThreadMintsOneVersion(t, ctx, fixture) +} + func TestDependencyEditorRepeatsWithinOneRequestCollapse(t *testing.T) { fixture, ctx, cleanup := newDoltDependencyEditorFixture(t, "repeat") defer cleanup() diff --git a/internal/storage/domain/db/dependency.go b/internal/storage/domain/db/dependency.go index 066ed7bd5..dc4332bb1 100644 --- a/internal/storage/domain/db/dependency.go +++ b/internal/storage/domain/db/dependency.go @@ -110,12 +110,12 @@ func (r *dependencySQLRepositoryImpl) Insert(ctx context.Context, dep *types.Dep table := pickDepTable(opts.UseWispsTable) var existingType string - var existingMetadataNS sql.NullString + var existingMetadataNS, existingThreadNS sql.NullString err := r.runner.QueryRowContext(ctx, //nolint:gosec // G201: table and depTargetExpr are hardcoded constants - fmt.Sprintf("SELECT type, metadata FROM %s WHERE issue_id = ? AND %s = ?", table, depTargetExpr), + fmt.Sprintf("SELECT type, metadata, thread_id FROM %s WHERE issue_id = ? AND %s = ?", table, depTargetExpr), dep.IssueID, dep.DependsOnID, - ).Scan(&existingType, &existingMetadataNS) + ).Scan(&existingType, &existingMetadataNS, &existingThreadNS) switch { case err == nil: existingMetadata := existingMetadataNS.String @@ -123,28 +123,35 @@ func (r *dependencySQLRepositoryImpl) Insert(ctx context.Context, dep *types.Dep existingMetadata = "{}" } if existingType == string(dep.Type) { - if issueops.DependencyMetadataEqual(existingMetadata, metadata) { - // Same type, same metadata: a change-free write. Nothing is - // written and nothing is journaled (#5898 R3). + // A re-add naming a thread the row does not carry moves it; one + // naming none keeps the stored thread (the issueops twin's rule). + thread, threadChanged := issueops.ReAddedDependencyThread(existingThreadNS, dep.ThreadID) + if !threadChanged && issueops.DependencyMetadataEqual(existingMetadata, metadata) { + // Same type, same metadata, same thread: a change-free write. + // Nothing is written and nothing is journaled (#5898 R3). return nil } //nolint:gosec // G201: table and depTargetExpr are hardcoded constants if _, err := r.runner.ExecContext(ctx, - fmt.Sprintf("UPDATE %s SET metadata = ? WHERE issue_id = ? AND %s = ?", table, depTargetExpr), - metadata, dep.IssueID, dep.DependsOnID, + fmt.Sprintf("UPDATE %s SET metadata = ?, thread_id = ? WHERE issue_id = ? AND %s = ?", table, depTargetExpr), + metadata, thread, dep.IssueID, dep.DependsOnID, ); err != nil { return fmt.Errorf("db: DependencySQLRepository.Insert: refresh metadata: %w", err) } - // A same-type add refreshes edge metadata. It is an observable graph - // mutation, so emit the complete replacement edge for replay. + // A same-type add refreshes the edge's metadata or thread. It is an + // observable graph mutation, so journal the replacement edge for + // replay. EventDep has no thread member, so a thread-only change + // journals the same payload as the original add; the source's + // version snapshot is what records the new thread. if err := issueops.RecordDepEventInTx(ctx, r.runner, issueops.EventDepAdd, dep.IssueID, string(dep.Type), dep.DependsOnID, metadata, actor); err != nil { return err } - // The metadata genuinely changed, so this re-add is a real - // durable-state mutation of the source issue and mints on the - // same terms as a new edge (#5898 leg 2: "a same-type re-add - // whose metadata actually changed mints EXACTLY ONE version - // carrying the new state"). + // The metadata or thread genuinely changed, so this re-add is a + // real durable-state mutation of the source issue (its version + // snapshot carries each edge's thread_id) and mints on the same + // terms as a new edge (#5898 leg 2: "a same-type re-add whose + // metadata actually changed mints EXACTLY ONE version carrying the + // new state"). return issueops.RecordVersionInTx(ctx, r.runner, dep.IssueID, actor) } return &domain.DependencyTypeConflictError{ diff --git a/internal/storage/domain/db/dependency_null_metadata_test.go b/internal/storage/domain/db/dependency_null_metadata_test.go index 60f8a68cd..e15cbead6 100644 --- a/internal/storage/domain/db/dependency_null_metadata_test.go +++ b/internal/storage/domain/db/dependency_null_metadata_test.go @@ -29,7 +29,9 @@ func newMockDependencyRepo(t *testing.T) (sqlmock.Sqlmock, *dependencySQLReposit // which would turn every subsequent re-add of that edge into an error on a // path that used to be idempotently happy. NULL is the absent-metadata state, // so it reads as `{}` and the change-free re-add of a metadata-free edge stays -// the no-op it was. +// the no-op it was. thread_id is nullable the same way and read by the same +// gate; a re-add naming no thread keeps a NULL one, so the row holds NULL in +// both columns and the re-add is still change-free. // // The repair landed on both planes; without this the two planes are pinned // asymmetrically and a revert of the serve-mode scan alone has nothing red to @@ -37,9 +39,9 @@ func newMockDependencyRepo(t *testing.T) (sqlmock.Sqlmock, *dependencySQLReposit func TestDependencyInsertReadsNullStoredMetadataAsEmptyObject(t *testing.T) { mock, repo := newMockDependencyRepo(t) - mock.ExpectQuery(regexp.QuoteMeta("SELECT type, metadata FROM dependencies")). + mock.ExpectQuery(regexp.QuoteMeta("SELECT type, metadata, thread_id FROM dependencies")). WithArgs("dep-a", "dep-b"). - WillReturnRows(sqlmock.NewRows([]string{"type", "metadata"}).AddRow(string(types.DepRelated), nil)) + WillReturnRows(sqlmock.NewRows([]string{"type", "metadata", "thread_id"}).AddRow(string(types.DepRelated), nil, nil)) dep := &types.Dependency{IssueID: "dep-a", DependsOnID: "dep-b", Type: types.DepRelated} // DepRelated is not a scheduling edge and the hierarchy check is declared diff --git a/internal/storage/embeddeddolt/batch_apply_contract_test.go b/internal/storage/embeddeddolt/batch_apply_contract_test.go index 3ed6724a9..c7be4ca2d 100644 --- a/internal/storage/embeddeddolt/batch_apply_contract_test.go +++ b/internal/storage/embeddeddolt/batch_apply_contract_test.go @@ -116,6 +116,15 @@ func TestBatchApplyContract(t *testing.T) { t.Run("StampsSpawnerIDOnlyWhenNamed", func(t *testing.T) { conformance.RunBatchApplyStampsSpawnerIDOnlyWhenNamed(t, ctx, fixture) }) + t.Run("CarriesThreadIDOntoTheStoredEdge", func(t *testing.T) { + conformance.RunBatchApplyCarriesThreadIDOntoTheStoredEdge(t, ctx, fixture) + }) + t.Run("CarriesThreadIDOntoAnExistingEdge", func(t *testing.T) { + conformance.RunBatchApplyCarriesThreadIDOntoAnExistingEdge(t, ctx, fixture) + }) + t.Run("RefusesAThreadIDLongerThanItsColumn", func(t *testing.T) { + conformance.RunBatchApplyRefusesAThreadIDLongerThanItsColumn(t, ctx, fixture) + }) t.Run("SplicesAForwardMetadataRef", func(t *testing.T) { conformance.RunBatchApplySplicesAForwardMetadataRef(t, ctx, fixture) }) diff --git a/internal/storage/embeddeddolt/dependency_editor_contract_test.go b/internal/storage/embeddeddolt/dependency_editor_contract_test.go index 15fb44f16..88335f2d7 100644 --- a/internal/storage/embeddeddolt/dependency_editor_contract_test.go +++ b/internal/storage/embeddeddolt/dependency_editor_contract_test.go @@ -57,6 +57,12 @@ func TestEmbeddedDependencyEditorSameTypeReAddWithIdenticalMetadataIsANoOp(t *te conformance.RunDependencyEditorSameTypeReAddWithIdenticalMetadataIsANoOp(t, ctx, newEmbeddedDependencyEditorFixture(t, ctx, "idemmetasame")) } +func TestEmbeddedDependencyEditorSameTypeReAddWithChangedThreadMintsOneVersion(t *testing.T) { + skipUnlessEmbeddedDolt(t) + ctx := t.Context() + conformance.RunDependencyEditorSameTypeReAddWithChangedThreadMintsOneVersion(t, ctx, newEmbeddedDependencyEditorFixture(t, ctx, "idemthread")) +} + func TestEmbeddedDependencyEditorRepeatsWithinOneRequestCollapse(t *testing.T) { skipUnlessEmbeddedDolt(t) ctx := t.Context() diff --git a/internal/storage/issueops/dependencies.go b/internal/storage/issueops/dependencies.go index d6acfe91f..17b113438 100644 --- a/internal/storage/issueops/dependencies.go +++ b/internal/storage/issueops/dependencies.go @@ -32,6 +32,19 @@ func DependencyMetadataEqual(a, b string) bool { return bytes.Equal(aCanon, bCanon) } +// ReAddedDependencyThread returns the thread_id a same-type re-add leaves on an +// existing edge and whether that differs from the stored one. A named thread +// the row does not already carry replaces it; an empty one names no thread +// rather than asking for none, so the stored value — NULL included — is kept. +// Both dependency re-add idempotency checks share this, alongside +// DependencyMetadataEqual, so they can't drift. +func ReAddedDependencyThread(stored sql.NullString, requested string) (sql.NullString, bool) { + if requested == "" || requested == stored.String { + return stored, false + } + return sql.NullString{String: requested, Valid: true}, true +} + type DepTargetKind int const ( @@ -178,8 +191,9 @@ type DepTargetPrecheck struct { // - Source/target existence validation // - Hierarchy deadlock validation for blocking deps (GH#1495, bd-wg7ve) // - Cycle detection via recursive CTE across both dependency tables -// - Idempotent same-type re-adds: a metadata change updates it, a -// change-free re-add writes and journals nothing (#5898 R3) +// - Idempotent same-type re-adds: a metadata or thread change updates it +// (an empty ThreadID keeps the stored thread), a change-free re-add +// writes and journals nothing (#5898 R3) // - Type conflict detection // // The caller is responsible for transaction lifecycle, dolt commits, and @@ -195,9 +209,9 @@ type DepTargetPrecheck struct { // state, so it mints one version row for the source — on EVERY leg that reaches // this helper (the dependency editor, the legacy store verbs, batch apply), // whether or not an audit event was requested. A same-type re-add that changes -// metadata is the same kind of durable-state change and mints on the same -// terms; only a genuinely change-free re-add (identical type and metadata) -// mints nothing. +// metadata or thread is the same kind of durable-state change and mints on the +// same terms; only a genuinely change-free re-add (identical type and metadata, +// no new thread) mints nothing. func AddDependencyInTx(ctx context.Context, tx *sql.Tx, dep *types.Dependency, actor string, opts AddDependencyOpts) (bool, error) { return addDependencyInTx(ctx, tx, dep, actor, opts, nil, true) } @@ -295,38 +309,46 @@ func addDependencyInTx(ctx context.Context, tx *sql.Tx, dep *types.Dependency, a // target expression defensively so stale/reclassified rows in another typed // target column cannot bypass the idempotency/conflict check. var existingType string - var existingMetadataNS sql.NullString + var existingMetadataNS, existingThreadNS sql.NullString //nolint:gosec // G201: writeTable from WispTableRouting; depTargetEquals has no user input. - err := tx.QueryRowContext(ctx, fmt.Sprintf(`SELECT type, metadata FROM %s WHERE issue_id = ? AND %s`, writeTable, depTargetEquals("")), - dep.IssueID, dep.DependsOnID).Scan(&existingType, &existingMetadataNS) + err := tx.QueryRowContext(ctx, fmt.Sprintf(`SELECT type, metadata, thread_id FROM %s WHERE issue_id = ? AND %s`, writeTable, depTargetEquals("")), + dep.IssueID, dep.DependsOnID).Scan(&existingType, &existingMetadataNS, &existingThreadNS) if err == nil { existingMetadata := existingMetadataNS.String if !existingMetadataNS.Valid { existingMetadata = "{}" } if existingType == string(dep.Type) { - if DependencyMetadataEqual(existingMetadata, metadata) { - // Same type, same metadata: a change-free write. Nothing is - // written and nothing is journaled (#5898 R3). + // A re-add naming a thread the row does not carry moves it. One + // naming none keeps the stored thread rather than clearing it, so + // the callers that never carry a thread cannot erase one. + thread, threadChanged := ReAddedDependencyThread(existingThreadNS, dep.ThreadID) + if !threadChanged && DependencyMetadataEqual(existingMetadata, metadata) { + // Same type, same metadata, same thread: a change-free write. + // Nothing is written and nothing is journaled (#5898 R3). return false, nil } - // Same type, different metadata — idempotent; update metadata. No - // event is written, so the caller must not stage the events table - // for this re-add. + // Same type, different metadata or thread — idempotent; update the + // row in place. No event is written, so the caller must not stage + // the events table for this re-add. //nolint:gosec // G201: writeTable from WispTableRouting; depTargetEquals has no user input. - if _, err := tx.ExecContext(ctx, fmt.Sprintf(`UPDATE %s SET metadata = ? WHERE issue_id = ? AND %s`, writeTable, depTargetEquals("")), - metadata, dep.IssueID, dep.DependsOnID); err != nil { + if _, err := tx.ExecContext(ctx, fmt.Sprintf(`UPDATE %s SET metadata = ?, thread_id = ? WHERE issue_id = ? AND %s`, writeTable, depTargetEquals("")), + metadata, thread, dep.IssueID, dep.DependsOnID); err != nil { return false, fmt.Errorf("failed to update dependency metadata: %w", err) } - // A same-type add refreshes edge metadata. It is an observable graph - // mutation, so emit the complete replacement edge for replay even - // though no audit event is written. + // A same-type add refreshes the edge's metadata or thread. It is an + // observable graph mutation, so journal the replacement edge for + // replay even though no audit event is written. EventDep has no + // thread member, so a thread-only change journals the same payload + // as the original add; the source's version snapshot is what + // records the new thread. if err := RecordDepEventInTx(ctx, tx, EventDepAdd, dep.IssueID, string(dep.Type), dep.DependsOnID, metadata, actor); err != nil { return false, err } - // The metadata genuinely changed, so — unlike the change-free - // branch above — this re-add is a real durable-state mutation of - // the source issue and mints on the same terms as a new edge + // The metadata or thread genuinely changed, so — unlike the + // change-free branch above — this re-add is a real durable-state + // mutation of the source issue (its version snapshot carries each + // edge's thread_id) and mints on the same terms as a new edge // (#5898 leg 2: "a same-type re-add whose metadata actually // changed mints EXACTLY ONE version carrying the new state"). return false, mintDependencyVersion(ctx, tx, dep.IssueID, actor, mintVersion) @@ -421,11 +443,11 @@ func addDependencyInTx(ctx context.Context, tx *sql.Tx, dep *types.Dependency, a } // mintDependencyVersion versions the referencing (source) issue of an edge that -// was actually inserted, deleted, or had its metadata refreshed by a same-type -// re-add: the version-history seam for every dependency write path, reached -// from addDependencyInTx and removeDependencyInTx only past a real row write — -// never from a genuinely change-free re-add or the absent-edge return, which -// mint nothing. mint false defers to a caller that mints once for a +// was actually inserted, deleted, or had its metadata or thread refreshed by a +// same-type re-add: the version-history seam for every dependency write path, +// reached from addDependencyInTx and removeDependencyInTx only past a real row +// write — never from a genuinely change-free re-add or the absent-edge return, +// which mint nothing. mint false defers to a caller that mints once for a // multi-edge mutation. A wisp source is excluded by the seam itself. func mintDependencyVersion(ctx context.Context, tx DBTX, issueID, actor string, mint bool) error { if !mint { diff --git a/internal/storage/issueops/dependencies_test.go b/internal/storage/issueops/dependencies_test.go index 635f81cb2..af2cfb5cd 100644 --- a/internal/storage/issueops/dependencies_test.go +++ b/internal/storage/issueops/dependencies_test.go @@ -2,6 +2,7 @@ package issueops import ( "context" + "database/sql" "errors" "reflect" "regexp" @@ -331,6 +332,45 @@ func TestDependencyMetadataEqualComparesValuesNotBytes(t *testing.T) { } } +// TestReAddedDependencyThreadKeepsTheStoredThreadUnlessANewOneIsNamed pins the +// thread half of the same-type re-add gate. A re-add naming a thread the row +// does not carry is a change that must reach the row; a re-add naming none +// says nothing about threads, so it must leave the stored one — NULL, empty +// or named — exactly as it is, or every plain `bd dep add` of a threaded edge +// would erase its thread. +func TestReAddedDependencyThreadKeepsTheStoredThreadUnlessANewOneIsNamed(t *testing.T) { + t.Parallel() + + null := sql.NullString{} + empty := sql.NullString{Valid: true} + named := sql.NullString{String: "thread-1", Valid: true} + for _, tc := range []struct { + name string + stored sql.NullString + requested string + want sql.NullString + wantChanged bool + }{ + {name: "NoneNamedKeepsNull", stored: null, requested: "", want: null}, + {name: "NoneNamedKeepsEmpty", stored: empty, requested: "", want: empty}, + {name: "NoneNamedKeepsTheStoredThread", stored: named, requested: "", want: named}, + {name: "SameThreadIsNoChange", stored: named, requested: "thread-1", want: named}, + {name: "NewThreadOverNull", stored: null, requested: "thread-1", want: named, wantChanged: true}, + {name: "NewThreadOverEmpty", stored: empty, requested: "thread-1", want: named, wantChanged: true}, + {name: "DifferentThreadReplacesIt", stored: named, requested: "thread-2", + want: sql.NullString{String: "thread-2", Valid: true}, wantChanged: true}, + } { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + got, changed := ReAddedDependencyThread(tc.stored, tc.requested) + if got != tc.want || changed != tc.wantChanged { + t.Errorf("ReAddedDependencyThread(%+v, %q) = (%+v, %v), want (%+v, %v)", + tc.stored, tc.requested, got, changed, tc.want, tc.wantChanged) + } + }) + } +} + // TestAddDependencyInTxReadsNullStoredMetadataAsEmptyObject pins the widened // SELECT's handling of a SQL-NULL metadata column. dependencies.metadata is // nullable (`JSON DEFAULT (JSON_OBJECT())`, no NOT NULL), so a row written out @@ -341,6 +381,11 @@ func TestDependencyMetadataEqualComparesValuesNotBytes(t *testing.T) { // re-add of that edge into an error. NULL is the absent-metadata state, so it // reads as `{}` and the change-free re-add of a metadata-free edge stays the // no-op it was. +// +// thread_id is nullable the same way (a VARCHAR with no NOT NULL), and the gate +// reads it too, so the row here holds NULL in both columns: a re-add naming no +// thread keeps whatever thread the row stores, NULL included, so this re-add +// is still change-free. func TestAddDependencyInTxReadsNullStoredMetadataAsEmptyObject(t *testing.T) { t.Parallel() @@ -349,9 +394,9 @@ func TestAddDependencyInTxReadsNullStoredMetadataAsEmptyObject(t *testing.T) { mock.ExpectQuery(regexp.QuoteMeta("SELECT issue_type FROM issues WHERE id = ?")). WithArgs("dep-a"). WillReturnRows(sqlmock.NewRows([]string{"issue_type"}).AddRow("task")) - mock.ExpectQuery(regexp.QuoteMeta("SELECT type, metadata FROM dependencies")). + mock.ExpectQuery(regexp.QuoteMeta("SELECT type, metadata, thread_id FROM dependencies")). WithArgs("dep-a", "dep-b"). - WillReturnRows(sqlmock.NewRows([]string{"type", "metadata"}).AddRow(string(types.DepRelated), nil)) + WillReturnRows(sqlmock.NewRows([]string{"type", "metadata", "thread_id"}).AddRow(string(types.DepRelated), nil, nil)) kind := DepTargetIssue dep := &types.Dependency{IssueID: "dep-a", DependsOnID: "dep-b", Type: types.DepRelated} diff --git a/internal/storage/uow/batch_apply_contract_test.go b/internal/storage/uow/batch_apply_contract_test.go index d49656b44..6ae8f3899 100644 --- a/internal/storage/uow/batch_apply_contract_test.go +++ b/internal/storage/uow/batch_apply_contract_test.go @@ -118,6 +118,15 @@ func TestBatchApplyContract(t *testing.T) { t.Run("StampsSpawnerIDOnlyWhenNamed", func(t *testing.T) { conformance.RunBatchApplyStampsSpawnerIDOnlyWhenNamed(t, ctx, fixture) }) + t.Run("CarriesThreadIDOntoTheStoredEdge", func(t *testing.T) { + conformance.RunBatchApplyCarriesThreadIDOntoTheStoredEdge(t, ctx, fixture) + }) + t.Run("CarriesThreadIDOntoAnExistingEdge", func(t *testing.T) { + conformance.RunBatchApplyCarriesThreadIDOntoAnExistingEdge(t, ctx, fixture) + }) + t.Run("RefusesAThreadIDLongerThanItsColumn", func(t *testing.T) { + conformance.RunBatchApplyRefusesAThreadIDLongerThanItsColumn(t, ctx, fixture) + }) t.Run("SplicesAForwardMetadataRef", func(t *testing.T) { conformance.RunBatchApplySplicesAForwardMetadataRef(t, ctx, fixture) }) diff --git a/internal/storage/uow/dependency_editor_contract_test.go b/internal/storage/uow/dependency_editor_contract_test.go index 02b91a878..855ec2521 100644 --- a/internal/storage/uow/dependency_editor_contract_test.go +++ b/internal/storage/uow/dependency_editor_contract_test.go @@ -32,6 +32,7 @@ func TestUOWDependencyEditorContract(t *testing.T) { {name: "SameTypeReAddIsIdempotent", run: conformance.RunDependencyEditorSameTypeReAddIsIdempotent}, {name: "SameTypeReAddWithChangedMetadataMintsOneVersion", run: conformance.RunDependencyEditorSameTypeReAddWithChangedMetadataMintsOneVersion}, {name: "SameTypeReAddWithIdenticalMetadataIsANoOp", run: conformance.RunDependencyEditorSameTypeReAddWithIdenticalMetadataIsANoOp}, + {name: "SameTypeReAddWithChangedThreadMintsOneVersion", run: conformance.RunDependencyEditorSameTypeReAddWithChangedThreadMintsOneVersion}, {name: "RepeatsWithinOneRequestCollapse", run: conformance.RunDependencyEditorRepeatsWithinOneRequestCollapse}, {name: "AttributesItsEventsToTheActor", run: conformance.RunDependencyEditorAttributesItsEventsToTheActor}, {name: "RetypeRefusalLeavesTheOriginalEdge", run: conformance.RunDependencyEditorRetypeRefusalLeavesTheOriginalEdge}, diff --git a/issueops/batchapplier.go b/issueops/batchapplier.go index 39889926e..ac84c74df 100644 --- a/issueops/batchapplier.go +++ b/issueops/batchapplier.go @@ -220,9 +220,13 @@ type DepAddItem struct { // not express. One spelling, and it is this one. Metadata string // HasSpawner marks a DepWaitsFor edge whose caller explicitly named a - // spawner (bd create --graph's edges[].spawner_key/spawner_id, which the - // CLI's own plan validator already forces to equal this edge's own - // Target). Only then does the role stamp Metadata's spawner_id from the + // spawner: a graph plan's edges[].spawner_key/spawner_id, which bd create + // --graph's plan validator forces to equal the edge's own Target. It has + // two producers: bd create --graph itself, which sets it from those + // members on the embedded and proxied legs alike (cmd/bd's + // buildGraphApplyBatchRequest), and an embedder lowering such a plan onto + // this role (gc's ApplyGraphPlan mapping, on BatchApplier below). Only + // when it is set does the role stamp Metadata's spawner_id from the // resolved Target, once every id in the batch exists (see // StampWaitsForSpawnerID) — a plan-local spawner key cannot be resolved // any earlier than that. @@ -236,9 +240,15 @@ type DepAddItem struct { // Type. HasSpawner bool // ThreadID carries conversation-threading metadata (e.g. a replies-to - // edge's originating thread) onto the created dependency row. Empty means - // the edge carries none; it is a plain column, not part of Metadata's - // type-specific blob. + // edge's originating thread) onto the dependency row. Empty means the edge + // carries none; it is a plain column, not part of Metadata's type-specific + // blob, and one longer than the column holds is ErrValidation. + // + // A RE-ADD OF AN EDGE THAT ALREADY EXISTS WITH THE SAME TYPE CARRIES IT + // TOO. A thread the stored row does not already carry replaces it, and + // versions the source on the same terms as a Metadata change; an empty + // ThreadID keeps the stored thread rather than clearing it, so a re-apply + // that names none cannot erase one. ThreadID string } @@ -558,6 +568,29 @@ func HasExtendedRetryBudget(ctx context.Context) bool { // directly. `bd create --file` and `bd dep add --file` remain the file-shaped // front doors for the two homogeneous cases they already serve. // +// TWO EMBEDDER OPERATIONS MAP ONTO THIS ROLE RATHER THAN EARNING THEIR OWN +// (DESIGN §3.8, "Guarded writes: NO NEW ROLES"). Neither needs a new role or a +// new wire member; both are a SHAPE of ApplyBatchRequest, pinned by an +// http-leg conformance case so the shape does not drift under either side +// independently: +// +// - CloseWithMetadataIfMatch is an update item carrying a Metadata patch and +// ExpectedVersion, followed by a close item on the SAME target, in ONE +// request: []ApplyItem{{Kind: ItemUpdate, Update: &UpdateItem{Target: t, +// Patch: IssuePatch{Metadata: ...}, ExpectedVersion: &v}}, {Kind: ItemClose, +// Close: &CloseItem{Target: t}}}. It is atomic because the whole request is: +// a stale ExpectedVersion refuses the update, which refuses the request, and +// the close never runs — zero rows change. CloseItem itself carries no +// metadata member; this composition is the only way to land a metadata +// write and a close as one guarded act. +// - ApplyGraphPlan is a create item per node (Key, the issue's Labels and +// Metadata, Ephemeral, NoHistory, and MetadataRefs for a value only the +// plan's own later ids can supply), dep_add items for every edge the plan +// names — parent-child included, since a parent is a dep_add item of type +// parent-child like any other edge — and trailing update items for an +// AssignAfterCreate step, which patches a just-created row's Assignee by +// its backward Key reference. One request, declaration order, one outcome. +// // Implementations never mutate caller-owned request values, snapshot the // request at method entry, and apply validation and normalization only to // attempt-local clones. Deterministic request-validation failures match