* feat(httpapi): wire-shape signal — wire_revision, floor header, golden digest, param tokens
S0 of the HTTP role-parity program: give a client a single place to learn
whether this build's wire shape has moved under it, and give CI a gate that
catches an undocumented move.
- GET /v0/beads/context reports wire_revision (bumps only on a non-additive
response-shape change) and min_client_wire_revision. An optional
Bd-Wire-Revision request header lets a client declare the revision it was
built for; checkWireRevision refuses a declared revision below the floor
with 400 invalid_argument/reason=wire_revision_unsupported and a
min_wire_revision field, on every route but /healthz (wireRevisionExempt) —
including the identity handshake, where catching the mismatch is cheapest.
Absent header is today's behavior; malformed value is invalid_value, never
wire_revision_unsupported. The floor lives in Server.minClientWireRevision
(defaulting to the MinClientWireRevision constant) so a test can raise it.
- internal/httpapi/wireshape: a golden digest over every response's every
content-type schema (including application/problem+json) across the whole
spec, keyed by schema+member. TestWireShapeDigest fails closed when a
member's JSON name or type changes without wire_revision bumping to match;
regenerate with `go run ./internal/httpapi/wireshape/cmd/gendigest`.
- GET /v0/beads/issues' `sort` parameter now carries the issues.listSort
capability token, the same convention `capabilities` entries use.
TestNewParameterOnExistingOperationHasABehaviorToken requires every new
parameter on an existing operation to carry one, checked against a
write-once grandfather baseline (testdata/pretoken_parameters.json) of
parameters that predate the rule; TestUntokenedParameterRuleFires proves
the checker itself against a synthetic fixture.
- Docs: engdocs/design/bd-serve-v0.md gets a "The wire-shape signal" section;
CHANGELOG.md gets an Added entry.
Live-mutated and reverted three RED demonstrations during development:
retyping api_version in the spec failed TestWireShapeDigest; short-circuiting
checkWireRevision's floor comparison failed
TestWireRevisionBelowFloorRefusesEveryEnforcedRoute; adding an untokened
query parameter to listIssues failed
TestNewParameterOnExistingOperationHasABehaviorToken. All three now pass
against the unmutated tree.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(httpapi): rename issues.listSort to issues.list.sort, harden token rule
Opus review of 12c5144ca (HIGH-1, MEDIUM-5):
- Rename the capability token issues.listSort -> issues.list.sort to match
bd-enterprise's client (httpstore/wire/handshake.go:121, DESIGN.txt S4e),
and widen capabilityToken to accept an optional third segment.
- untokenedParameters() now requires the extracted token to be one
Capabilities() actually serves, not just backtick-shaped text. This
catches real false positives that existed in the spec already
(workapi.DefaultReadyLimit, status.custom) which only shape-matched the
old regex; they're added to the pretoken baseline as genuinely
pre-existing untokened parameters.
- Extend the rule to request body members (new
testdata/pretoken_request_body_members.json baseline) and exempt
brand-new operations via a frozen testdata/pretoken_operations.json
snapshot.
- Add TestPretokenBaselinesNeverGrow pinning all three baseline sizes so
a future change can't hand-add an exemption instead of a token.
- Update spec prose for the widened rule scope.
go test ./internal/httpapi/... and the reviewer's pmut.py all pass as
expected: plain/bogus modes go RED, reuse (real-but-unrelated token) stays
green, matching the review's literal ask ("a token must be one advertised
by Capabilities()").
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(wireshape): close four digest-coverage gaps, add gendigest write guard
Opus review of 12c5144ca (HIGH-2, MEDIUM-4). The digest only tracked
Type/Format/Enum/Required on direct properties, missing:
- nullable: true (never read at all)
- array item shape (Issue.labels items string->integer was invisible;
only object-shaped items got recursed into)
- additionalProperties value shape (IssueCount.groups)
- request bodies entirely (Compute() only walked responses, so
DeleteIssuesRequest.expected_version string->integer, the other half
of #6053, was invisible)
Also added defensive oneOf flattening alongside the existing allOf merge
(dormant today -- grep confirms this spec uses oneOf nowhere -- but no
longer silently invisible if that changes).
Extracted the golden-vs-computed comparison into wireshape.Compare(),
shared by TestWireShapeDigest and the new wireshape.SafeToWrite(), which
gendigest now calls before writing: it refuses to overwrite golden.json
with changed/removed entries unless the candidate's wire_revision is
strictly greater than the existing golden's. Pure additions always write.
TestSafeToWrite exercises both guard directions.
golden.json is regenerated. This single regen is a one-time exception to
the new guard, done by writing the digest directly rather than through
gendigest: confirmed via a throwaway diff (not checked in) that every one
of the 57 "changed" entries differs only in the NEW fields the wider walk
now populates (ItemType/ItemFormat/Nullable/AdditionalProps*) -- every
pre-existing Type/Format/Required/Enum value is byte-identical. Nothing on
the wire changed; the measurement got more precise. Bumping
CurrentWireRevision for this would have written a false "the protocol
changed here" entry into the revision history table. Going forward, any
REAL change the guard now reports uses the normal bump-then-regenerate
path, same as before.
Verified against the reviewer's mut.py: nested_type, nullable,
nullable_issue, array_items, addlprops, request_body and format all go RED
on TestWireShapeDigest, each reverted after confirming.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(httpapi): make bd_version wire_revision inference advisory
Opus review of 12c5144ca (HIGH-3). The spec told a client inferring
wire_revision from bd_version to use the release cutoff >= 1.3.0, and said
nothing about what happens when that inference is wrong -- which it
demonstrably is for real builds already in the field:
- main builds up to commit b3ef65c85 report bd_version 1.2.2 (below any
1.3.0 cutoff) while already sending the string-typed revision/
expected_version shape (#6053).
- 1.3.0-rc.N pre-release builds sort BELOW the release cutoff 1.3.0 under
plain string comparison despite already carrying the string shape.
- The bd-enterprise compatibility line at d3ab32773462 reports bd_version
1.1.0 while also sending strings.
Moved the cutoff to >= 1.3.0-rc.1 (compared as semver-with-prerelease,
which at least captures the rc builds), documented both named exceptions
inline, and made the whole inference explicitly ADVISORY: a client must
accept revision/expected_version as either a string or a number whenever
wire_revision is absent (or probe directly) rather than let the inferred
value choose a decoder, and must never refuse solely because the inferred
revision is 0. Mirrored into engdocs/design/bd-serve-v0.md.
This is spec/doc prose only -- there is no server-side inference code to
change, since this server always sends wire_revision directly; the
inference is guidance for clients reading a pre-signal server's response
(this server, past builds, or an unrelated implementation).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(httpapi): LOW-7/8/9/10 review follow-ups for wire-revision signal
LOW-7: WireRevisionUnsupported now also sets Problem.wire_revision (this
server's CurrentWireRevision) and Problem.bd_version on the
wire_revision_unsupported refusal, alongside the existing
min_wire_revision, so a client logging the refusal has this server's
full self-description without a second /v0/beads/context call.
LOW-8: gazelle + make bazel-sync add the BUILD.bazel entries the prior
commits were missing: wire_revision.go/wire_revision_test.go in
internal/httpapi's srcs, new BUILD.bazel files for wireshape and
wireshape/cmd/gendigest, and a testdata glob on httpapi's go_test so
the pretoken_*.json baselines are visible under `bazel test`. Verified
with `bazel build //internal/httpapi/...` and
`bazel test //internal/httpapi/... --test_env=BEADS_TEST_SKIP=dolt`
(both green) and `python3 tools/bazel/go_srcs.py --check` (clean).
LOW-9: narrowed CHANGELOG.md and engdocs/design/bd-serve-v0.md to
describe the digest's actual final coverage (format/enum/required/
nullable, array items, additionalProperties, request bodies, $ref/
allOf/oneOf recursion, the SafeToWrite revision-bump guard) and the
token rule's actual final shape (three pinned baselines, request-body
members, Capabilities()-membership validation, new-operation
exemption) instead of the original, narrower claims.
LOW-10: Bd-Wire-Revision now parses via a strict decimal-only
parseStrictNonNegativeInt (no leading '+', no leading zero except a
bare "0") instead of strconv.Atoi alone, so two different header
bytes can no longer name the same revision. New malformed-header test
cases: "+1", "01", "007".
Regenerated apigen/types.gen.go (make api-gen) for the new Problem
fields and wireshape/testdata/golden.json (go run
.../wireshape/cmd/gendigest) for the two new additive Problem members;
the latter wrote cleanly through SafeToWrite itself, since both are
pure additions.
go test ./... and bazel test //internal/httpapi/... both green.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(httpapi): re-review LOW follow-ups — retirement test, gendigest -init, docs
1. TestRetiredRevisionsStayBelowTheFloor pins the PRESENCE guarantee the
wire_revision property doc relies on: CurrentWireRevision >= 2 (so 0
and 1 stay permanently retired) and MinClientWireRevision <=
CurrentWireRevision (so this build's own floor never refuses every
request against itself).
2. gendigest now refuses to create a golden.json that does not exist yet
unless run with -init. Previously a missing file (moved testdata,
wrong path, accidental delete) was indistinguishable from a real first
run and silently wrote a fresh golden with no revision history checked
against anything. writeGolden() is extracted out of main() so this is
covered directly: TestWriteGoldenRequiresInitWhenMissing,
TestWriteGoldenInitCreatesWhenMissing,
TestWriteGoldenIgnoresInitWhenGoldenExists (the existing-golden path is
still governed only by SafeToWrite, -init or not).
3. Narrowed the two remaining stale claims that still described the
digest's original, narrower coverage: the wire_revision property's
prose in openapi.v0.yaml (regenerated into apigen/types.gen.go via
make api-gen) and wireshape/doc.go now both list nullable, array item
shape, additionalProperties value shape, request bodies, and
$ref/allOf/oneOf recursion, plus the new -init guard.
go test ./internal/httpapi/... and make api-check both green;
bazel test //internal/httpapi/... (httpapi, wireshape, and the new
gendigest test target) green; python3 tools/bazel/go_srcs.py --check
clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(wireshape): cover operation parameters in the wire-shape digest
The digest previously walked only response and request-body schemas, so a
type, enum, required, or removal change on one of the spec's 138 operation
parameters (123 query, 14 path, 1 header) passed the gate silently — the
open item from PR review on #7182.
Each parameter is now recorded as its own Entry, keyed by
"param:"+operationId / location+":"+name (operation-scoped, not
schema-scoped, since two operations' same-named parameter are independent
wire contracts), capturing type, array item shape, enum, required, style,
explode and default. Adding a parameter stays additive; removing,
retyping, narrowing its enum, or changing required/style/explode/default
now trips SafeToWrite exactly like a response or request-body change.
Verified against the live spec: retyping listIssues' `limit` query
parameter from integer to string now fails TestWireShapeDigest (confirmed
red, then reverted — not part of this commit). golden.json regenerated via
gendigest; the new parameter entries are a pure addition, no wire_revision
bump needed. Added TestParameterMutationsAreCaught (remove/retype/narrow-
enum against real golden entries) and updated wireshape's doc.go, the
`wire_revision` spec prose, and the CHANGELOG to describe the new
coverage.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(wireshape): review fixes — stale-golden and lowered-revision arms, effective param serialization, digest boundary
Maintainer fixup from the adopt-pr review loop (iterations 1 and 2), on
top of e17ba924f.
- goldenDrift (A, I): TestWireShapeDigest's comparison moves into a
goldenDrift helper. An addition alongside a moved wire_revision no
longer passes with a stale golden: it asks for a regenerate, as a
changed or removed entry after a bump already did. Every message now
names response/request-body members AND parameters, and TestGoldenDrift
pins each arm. This takes only the test half of the stranded fixup
(adopt-pr/bd-47kdge/stranded-fixup-528cd6095); its doc half, which says
parameters are outside the digest, is false since e17ba924f and is not
replayed (J).
- Lowered wire_revision (D): a CurrentWireRevision LOWER than the
golden's is a wrong constant, not a stale golden, so goldenDrift says to
restore it instead of regenerating, and SafeToWrite (so gendigest)
refuses any write at a lower revision, whatever the entries.
- Effective style/explode (B): walkParam records style and explode with
OpenAPI 3.0's defaults filled in (form for query/cookie, simple for
path/header; explode defaults to style == form). Adding `explode: false`
to a query array that relied on form's implicit explode is now a
changed entry, while spelling out a default changes nothing.
testdata/golden.json is regenerated with -init: 111 parameter entries
change only in style/explode (96 to form/true, 15 to simple), 828
entries before and after, wire_revision stays 2. The golden is new in
this PR and unreleased, so this needs no bump.
- TestWalkParam (H): a package-internal table test
(wireshape_internal_test.go) pins every field walkParam extracts,
through a computeFrom(document, revision) seam that Compute now wraps:
per-location defaults, $ref'd parameters and items, format, nullable and
default, content parameters, and the nil returns.
TestEffectiveSerializationIsCompared pins B end to end through Compare
and SafeToWrite. BUILD.bazel embeds the library in the go_test, which is
gazelle's own output.
- Required inputs and the digest boundary (C, E, F; docs only): all five
prose surfaces (openapi.v0.yaml's wire_revision description and the
regenerated apigen/types.gen.go, wireshape/doc.go, CHANGELOG.md,
engdocs/design/bd-serve-v0.md) now say that a new REQUIRED request
input is recorded as an ordinary addition and needs its own review,
that value constraints and member-level composition are outside the
digest, and that object and content parameters are recorded only as
their container. bd-serve-v0.md also gains the parameter coverage it
was missing.
- G: a brand-new operation is permanently exempt from the
capability-token rule; its own review decides its capability story.
- Iteration 2 (nit): walkParam's comment now says that the location
default it records as a `content` parameter's style and explode is a
placeholder, since OpenAPI 3.0 applies style and explode only to a
parameter described by `schema`. All 138 operation parameters in the
spec use `schema`, so the golden does not change.
Validated: go test ./internal/httpapi/... (gms_pure_go), make api-check,
go vet for linux/windows/darwin, gofmt, git diff --check, gazelle on the
package (no drift), make bazel-sync-check, and bazel test
//internal/httpapi/wireshape/... in the local processwrapper sandbox
(2 of 2 pass). Overlay mutation probes: dropping the added-after-bump
arm, the lowered-revision arm, SafeToWrite's lowered check, or the
effective-default fill each turns the new tests red.
Iteration 2 changes only that comment; go test
./internal/httpapi/wireshape/... (gms_pure_go), go vet, gofmt and git
diff --check pass again.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* feat(count): add Counter scope fields (S8) — ParentID, NoParent, ExcludeTypes, ExcludeStatus
Extends issueops.CountRequest with ParentID, NoParent, ExcludeTypes and
ExcludeStatus, closing the gap where bd count could not express the
filters bd list already has, forcing downstream consumers like gc to
fall back to listing everything just to get a count.
- issueops.Counter: four new CountRequest fields, documented against the
List equivalents they mirror (ParentID/ExcludeTypes) or newly define
(NoParent, ExcludeStatus has no List counterpart). Status "all" is
pinned as equivalent to unset, matching BuildListFilter's own "all" and
preserving count/list cardinality parity (the role's reason to exist).
- internal/workapi.BuildCountFilter: maps the four fields onto the one
types.IssueFilter builder all three storage legs (dolt, embeddeddolt,
uow) already share via internal/storage/issueops and sqlbuild, so no
per-leg storage code was needed.
- cmd/bd: --parent, --no-parent, --exclude-type, --exclude-status flags.
- HTTP: adds parent/no_parent/exclude_type/exclude_status to GET
/v0/beads/issues:count, behind the new issues.count.scope behavior
token (routes.go), wired in reads.go's countFilters, documented in
openapi.v0.yaml with per-parameter tokens and an extended capabilities
description. gendigest confirms a byte-identical golden.json: query
parameters are outside the wire-shape digest's scope, so this is a
zero-diff, no-revision-bump change as expected.
- backend/conformance: four new Counter contract cases (ParentID scoping,
NoParent's edge-only semantics vs ParentID's edge-or-dotted-id match,
ExcludeTypes composing with include_infra's own exclusions, and
ExcludeStatus), run identically against all three storage legs via a
new CounterFixture.AddDependency hook shared with ReaderFixture.
Verified: go build ./...; go test ./internal/httpapi/... ./internal/workapi/...
./issueops/... and the Counter contract on all three legs (dolt via
testcontainers, embeddeddolt, uow via local dolt binary); make api-gen
(additive-only apigen diff) and make api-check; go vet and golangci-lint
clean; gofmt clean; gazelle diff empty (no new files/imports). Mutation
testing: dropping issues.count.scope from behaviorCapabilities turns
TestCapabilitiesAdvertiseEveryImplementedOperation,
TestSpecCapabilityVocabularyMatchesTheRouteTable and
TestNewParameterOnExistingOperationHasABehaviorToken red; no-op'ing
ExcludeStatus in BuildCountFilter turns
TestBuildCountFilterExcludeStatusTakesNamesAsWritten and the
embeddeddolt ExcludeStatusNarrowsThePredicate conformance case red. Both
reverted and reconfirmed green.
Deviation: DESIGN.txt's literal text would make count --status all an
ErrValidation; shipped behind a test and a doc comment instead, since
"all" already means "every status" on both count and list and rejecting
it would break the count/list parity this role exists to guarantee.
S3/S4 note: no OSS HTTP client exists yet to enforce capability-token
skew. A doc comment on CapIssuesCountScope in routes.go specifies the
required behavior once one lands: check issues.count.scope against the
cached handshake capabilities and refuse locally with a typed
ErrUnsupported{Capability} before sending any of the four new params to
an older server.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(count): S8 review follow-ups — refusal parity, exclude-status validation, doc fixes, parity tests
Addresses the Opus review's six required changes for S8 (bd count scope
fields):
1. BuildCountFilter now refuses ParentID+NoParent together as ErrValidation,
matching bd list's CLI refusal wording; wired through the role, the CLI,
and invalid_argument classification in internal/httpapi/reads.go.
2. Status:"all" is documented in DESIGN.txt as every status, matching List's
no-filter reading (count/list cardinality parity) — a coordinator decision
recorded in beads-design/DESIGN.txt, outside this worktree.
3. ExcludeStatus names are now validated against the workspace vocabulary
(built-in statuses plus workspace-custom ones); an unknown name is
ErrValidation instead of a silent no-op, since a typo here would overcount.
4. Fixed openapi.v0.yaml and issueops/reader.go doc claims about bd list
--parent's default tree-walk vs. the one-level role answer that bd count
--parent agrees with (confirmed by tracing list_show_filter_modes.go); fixed
an Oxford-comma nit in routes.go and the spec.
5. Added storage-level count == len(List) parity tests for ParentID, NoParent
and ExcludeTypes (List has no ExcludeStatus counterpart), plus wisp-child
and closed-child contract cases, across all three backends (dolt,
embeddeddolt, uow). CounterFixture gained a List hook for this.
6. Extended the routes.go skew note: gc's ErrCountUnsupported fallback to List
is now named explicitly, with a note that S3/S4 must add a skew test that
masks the token and asserts the fallback fires.
Also fixed RunCounterExcludeStatusNarrowsThePredicate's now-stale "unrecognized
status excludes nothing" assertion to expect ErrValidation instead.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(count): PR #7199 review follow-ups — exclude-status config load, ParentID doc swap
Addresses bee's REQUEST-CHANGES on gastownhall/beads#7199 (S8):
1. BLOCKER: storecounter.filter and uow.countFilter only loaded the
workspace list config when IncludeInfra was set, so BuildCountFilter's
ExcludeStatus validation refused a workspace's own custom status unless
the caller also passed the unrelated IncludeInfra flag. Both legs now
load the config when IncludeInfra OR len(ExcludeStatus) > 0, with
comments corrected to say so. Added leg-level regression tests (the
conformance fixture cannot drive a workspace-configured custom status)
on embeddeddolt and uow, reproducing the reviewer's CLI repro directly,
plus an HTTP-level probe in cmd/bd's real-Dolt proxied count test.
2. issueops.ReadyRequest.ParentID's comment had been overwritten with the
one-level direct-children wording that belongs to ListRequest.ParentID;
Ready actually walks all descendants via GetDescendantIDsInTx (GH#3396).
Restored the descendants comment on ReadyRequest.ParentID and moved the
one-level explanation to ListRequest.ParentID, which had none.
Verified: make api-check; dolt-server, embeddeddolt and uow Counter
contract legs (BEADS_TEST_DOLT_SERVER=local with a pinned dolt binary for
uow; Docker for the dolt-server leg); the new proxied HTTP exclude_status
probe (BEADS_TEST_PROXIED_SERVER=1).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* chore(wireshape): add the countIssues scope parameters to the wire-shape golden
#7182 now digests operation parameters. The four new issues:count parameters
(parent, no_parent, exclude_type, exclude_status) are additive entries, so no
wire_revision bump is needed; regenerated with gendigest.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(conformance): register the S8 count-scope cases with RunRoleContracts (adopt-pr #7199)
The PR adds nine RunCounter* contract cases to counter_contract.go and wires
them into the three in-tree TestCounterContract legs, but not into the
Counter row of roleContractCases. TestRoleContractCasesCoverEveryContractCase
derives the expected set from source, so it fails on the PR head, and an
external backend running RunRoleContracts would never see the new cases.
Register them in source-declaration order (after
RunCounterAnUnknownStatusMatchesNothing), which the same guard enforces.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(count): correct the S8 scope docs the review found wrong (adopt-pr #7199)
Comment and spec-description fixes only; no behavior change. Review-loop
iterations 1 and 2 of the #7199 relaunch.
- ListRequest.ParentID (issueops/reader.go) said "DIRECT children only
... the same one-level clause". The sqlbuild clause has two arms and
neither walks: the parent-child edge arm stops at one level, but the
dotted-prefix arm (`id LIKE CONCAT(?, '.%')` for rows with no
parent-child edge) reaches every edge-less dotted id at any depth, which
RunReaderListParentReachesEveryDescendantAndOnlyItsOwn pins with an
edge-less X.1.1. State both arms, and say the CLI tree view re-runs the
clause against the store once per level (findAllDescendants calls
SearchIssues, not the role). Document ListRequest.NoParent, which had no
doc. The contributor's ReadyRequest.ParentID text is kept; only its
cross-reference to this field changes from "one-level" to "non-walking".
- CountRequest.NoParent (issueops/counter.go) and the count flag comment
(cmd/bd/count.go) said NoParent counts rows with "neither" an edge nor a
dotted prefix. Its SQL checks only the edge table, so an edge-less X.1
is counted by both --parent X and --no-parent, as bd list lists it.
- RunCounterExcludeStatusNarrowsThePredicate's header said an
unrecognized name "excludes nothing rather than failing" while its body
asserts ErrValidation. The header now matches the body.
- The OpCountIssues entry in problem.go's operationCodes said the role has
"exactly one reachable refusal". It has three: an invalid metadata key,
an unrecognized exclude_status name, and parent with no_parent (named
no_parent), all classified by invalidFilterParam. The code set is
unchanged.
- BuildCountFilter's header said cfg is "only read under IncludeInfra".
It is also read to validate ExcludeStatus against the workspace's
custom statuses, which is why both callers load it when ExcludeStatus is
non-empty.
- The countIssues `parent` description in openapi.v0.yaml carried the
same one-level claim as ListRequest.ParentID; it now states both arms.
types.gen.go is regenerated (make api-gen); make api-check passes.
Review fixes (iteration 2), still comment and spec text only:
- The iteration-1 problem.go rewrite called all three count refusals
ErrValidation. Only the exclude_status and parent-with-no_parent
refusals wrap issueops.ErrValidation (internal/workapi/count.go). The
metadata-key refusal is ValidateMetadataFilters' plain fmt.Errorf
chain, so errors.Is(err, ErrValidation) is false for it; it reaches the
wire as a 400 only because invalidFilterParam matches message prefixes.
The comment now says that, so a later move to typed errors cannot trust
it and demote the metadata-key refusal to a 500. The sentinel itself is
not added here: ValidateMetadataFilters is shared with the list and
ready builders.
- invalidFilterParam's comment on the count rows pointed at the
metadata-key rows as "above"; they come after it in the switch.
- The countIssues `parent` description said the CLI tree mode walks
"every edge-linked descendant". findAllDescendants re-runs the full
two-arm predicate per level, so it also descends through edge-less
dotted ids; it now says "every descendant reachable through either
arm". types.gen.go is regenerated; make api-check passes.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* chore(wireshape): re-record the count scope params under the base's param digest (adopt-pr #7199)
The base branch (feat/wire-revision-signal, #7182be1f0bad72) now digests
the effective style/explode of scalar query parameters. This PR's golden
entries for countIssues query:parent and query:no_parent were written by
the old algorithm, so after the base refresh TestWireShapeDigest reported
them as "changed without a wire_revision bump".
No bump is owed: all four count-scope entries (parent, no_parent,
exclude_type, exclude_status) are additions this PR introduces and are
absent from the base golden. golden.json was reset to the base copy and
regenerated with `go run ./internal/httpapi/wireshape/cmd/gendigest`. The
result is four pure additions against the base (+35/-0); parent and
no_parent gain "style": "form" and "explode": true, and wire_revision
stays 2.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* ci: place the PR's new embedded counter test in the shard manifest
TestCounterExcludeStatusAcceptsAWorkspaceCustomStatusWithoutIncludeInfra,
added to internal/storage/embeddeddolt in f23bf5ddbf, is a new top-level
embedded storage test. The 15-shard block of
.github/scripts/embedded-storage-test-shards.txt must list every
discovered test exactly once. Without the entry,
TestStorageEmbeddedShardManifestGeneratorNotStale (scripts/) fails, both
on the reviewed head 89a387de6c and on the merge. CI never ran the check
on this PR: pr.yml runs only for PRs based on main, release/** or
hotfix/**, and this PR was based on feat/wire-revision-signal until the
retarget.
Generated with
`python3 scripts/ci/gen_embedded_storage_shard_manifest.py 15 --weights=duration --write`.
The incremental write adds this one line, in shard 4, and moves no other
test.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.local>
* feat(httpapi): wire-shape signal — wire_revision, floor header, golden digest, param tokens
S0 of the HTTP role-parity program: give a client a single place to learn
whether this build's wire shape has moved under it, and give CI a gate that
catches an undocumented move.
- GET /v0/beads/context reports wire_revision (bumps only on a non-additive
response-shape change) and min_client_wire_revision. An optional
Bd-Wire-Revision request header lets a client declare the revision it was
built for; checkWireRevision refuses a declared revision below the floor
with 400 invalid_argument/reason=wire_revision_unsupported and a
min_wire_revision field, on every route but /healthz (wireRevisionExempt) —
including the identity handshake, where catching the mismatch is cheapest.
Absent header is today's behavior; malformed value is invalid_value, never
wire_revision_unsupported. The floor lives in Server.minClientWireRevision
(defaulting to the MinClientWireRevision constant) so a test can raise it.
- internal/httpapi/wireshape: a golden digest over every response's every
content-type schema (including application/problem+json) across the whole
spec, keyed by schema+member. TestWireShapeDigest fails closed when a
member's JSON name or type changes without wire_revision bumping to match;
regenerate with `go run ./internal/httpapi/wireshape/cmd/gendigest`.
- GET /v0/beads/issues' `sort` parameter now carries the issues.listSort
capability token, the same convention `capabilities` entries use.
TestNewParameterOnExistingOperationHasABehaviorToken requires every new
parameter on an existing operation to carry one, checked against a
write-once grandfather baseline (testdata/pretoken_parameters.json) of
parameters that predate the rule; TestUntokenedParameterRuleFires proves
the checker itself against a synthetic fixture.
- Docs: engdocs/design/bd-serve-v0.md gets a "The wire-shape signal" section;
CHANGELOG.md gets an Added entry.
Live-mutated and reverted three RED demonstrations during development:
retyping api_version in the spec failed TestWireShapeDigest; short-circuiting
checkWireRevision's floor comparison failed
TestWireRevisionBelowFloorRefusesEveryEnforcedRoute; adding an untokened
query parameter to listIssues failed
TestNewParameterOnExistingOperationHasABehaviorToken. All three now pass
against the unmutated tree.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(httpapi): rename issues.listSort to issues.list.sort, harden token rule
Opus review of 12c5144ca (HIGH-1, MEDIUM-5):
- Rename the capability token issues.listSort -> issues.list.sort to match
bd-enterprise's client (httpstore/wire/handshake.go:121, DESIGN.txt S4e),
and widen capabilityToken to accept an optional third segment.
- untokenedParameters() now requires the extracted token to be one
Capabilities() actually serves, not just backtick-shaped text. This
catches real false positives that existed in the spec already
(workapi.DefaultReadyLimit, status.custom) which only shape-matched the
old regex; they're added to the pretoken baseline as genuinely
pre-existing untokened parameters.
- Extend the rule to request body members (new
testdata/pretoken_request_body_members.json baseline) and exempt
brand-new operations via a frozen testdata/pretoken_operations.json
snapshot.
- Add TestPretokenBaselinesNeverGrow pinning all three baseline sizes so
a future change can't hand-add an exemption instead of a token.
- Update spec prose for the widened rule scope.
go test ./internal/httpapi/... and the reviewer's pmut.py all pass as
expected: plain/bogus modes go RED, reuse (real-but-unrelated token) stays
green, matching the review's literal ask ("a token must be one advertised
by Capabilities()").
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(wireshape): close four digest-coverage gaps, add gendigest write guard
Opus review of 12c5144ca (HIGH-2, MEDIUM-4). The digest only tracked
Type/Format/Enum/Required on direct properties, missing:
- nullable: true (never read at all)
- array item shape (Issue.labels items string->integer was invisible;
only object-shaped items got recursed into)
- additionalProperties value shape (IssueCount.groups)
- request bodies entirely (Compute() only walked responses, so
DeleteIssuesRequest.expected_version string->integer, the other half
of #6053, was invisible)
Also added defensive oneOf flattening alongside the existing allOf merge
(dormant today -- grep confirms this spec uses oneOf nowhere -- but no
longer silently invisible if that changes).
Extracted the golden-vs-computed comparison into wireshape.Compare(),
shared by TestWireShapeDigest and the new wireshape.SafeToWrite(), which
gendigest now calls before writing: it refuses to overwrite golden.json
with changed/removed entries unless the candidate's wire_revision is
strictly greater than the existing golden's. Pure additions always write.
TestSafeToWrite exercises both guard directions.
golden.json is regenerated. This single regen is a one-time exception to
the new guard, done by writing the digest directly rather than through
gendigest: confirmed via a throwaway diff (not checked in) that every one
of the 57 "changed" entries differs only in the NEW fields the wider walk
now populates (ItemType/ItemFormat/Nullable/AdditionalProps*) -- every
pre-existing Type/Format/Required/Enum value is byte-identical. Nothing on
the wire changed; the measurement got more precise. Bumping
CurrentWireRevision for this would have written a false "the protocol
changed here" entry into the revision history table. Going forward, any
REAL change the guard now reports uses the normal bump-then-regenerate
path, same as before.
Verified against the reviewer's mut.py: nested_type, nullable,
nullable_issue, array_items, addlprops, request_body and format all go RED
on TestWireShapeDigest, each reverted after confirming.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(httpapi): make bd_version wire_revision inference advisory
Opus review of 12c5144ca (HIGH-3). The spec told a client inferring
wire_revision from bd_version to use the release cutoff >= 1.3.0, and said
nothing about what happens when that inference is wrong -- which it
demonstrably is for real builds already in the field:
- main builds up to commit b3ef65c85 report bd_version 1.2.2 (below any
1.3.0 cutoff) while already sending the string-typed revision/
expected_version shape (#6053).
- 1.3.0-rc.N pre-release builds sort BELOW the release cutoff 1.3.0 under
plain string comparison despite already carrying the string shape.
- The bd-enterprise compatibility line at d3ab32773462 reports bd_version
1.1.0 while also sending strings.
Moved the cutoff to >= 1.3.0-rc.1 (compared as semver-with-prerelease,
which at least captures the rc builds), documented both named exceptions
inline, and made the whole inference explicitly ADVISORY: a client must
accept revision/expected_version as either a string or a number whenever
wire_revision is absent (or probe directly) rather than let the inferred
value choose a decoder, and must never refuse solely because the inferred
revision is 0. Mirrored into engdocs/design/bd-serve-v0.md.
This is spec/doc prose only -- there is no server-side inference code to
change, since this server always sends wire_revision directly; the
inference is guidance for clients reading a pre-signal server's response
(this server, past builds, or an unrelated implementation).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(httpapi): LOW-7/8/9/10 review follow-ups for wire-revision signal
LOW-7: WireRevisionUnsupported now also sets Problem.wire_revision (this
server's CurrentWireRevision) and Problem.bd_version on the
wire_revision_unsupported refusal, alongside the existing
min_wire_revision, so a client logging the refusal has this server's
full self-description without a second /v0/beads/context call.
LOW-8: gazelle + make bazel-sync add the BUILD.bazel entries the prior
commits were missing: wire_revision.go/wire_revision_test.go in
internal/httpapi's srcs, new BUILD.bazel files for wireshape and
wireshape/cmd/gendigest, and a testdata glob on httpapi's go_test so
the pretoken_*.json baselines are visible under `bazel test`. Verified
with `bazel build //internal/httpapi/...` and
`bazel test //internal/httpapi/... --test_env=BEADS_TEST_SKIP=dolt`
(both green) and `python3 tools/bazel/go_srcs.py --check` (clean).
LOW-9: narrowed CHANGELOG.md and engdocs/design/bd-serve-v0.md to
describe the digest's actual final coverage (format/enum/required/
nullable, array items, additionalProperties, request bodies, $ref/
allOf/oneOf recursion, the SafeToWrite revision-bump guard) and the
token rule's actual final shape (three pinned baselines, request-body
members, Capabilities()-membership validation, new-operation
exemption) instead of the original, narrower claims.
LOW-10: Bd-Wire-Revision now parses via a strict decimal-only
parseStrictNonNegativeInt (no leading '+', no leading zero except a
bare "0") instead of strconv.Atoi alone, so two different header
bytes can no longer name the same revision. New malformed-header test
cases: "+1", "01", "007".
Regenerated apigen/types.gen.go (make api-gen) for the new Problem
fields and wireshape/testdata/golden.json (go run
.../wireshape/cmd/gendigest) for the two new additive Problem members;
the latter wrote cleanly through SafeToWrite itself, since both are
pure additions.
go test ./... and bazel test //internal/httpapi/... both green.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(httpapi): re-review LOW follow-ups — retirement test, gendigest -init, docs
1. TestRetiredRevisionsStayBelowTheFloor pins the PRESENCE guarantee the
wire_revision property doc relies on: CurrentWireRevision >= 2 (so 0
and 1 stay permanently retired) and MinClientWireRevision <=
CurrentWireRevision (so this build's own floor never refuses every
request against itself).
2. gendigest now refuses to create a golden.json that does not exist yet
unless run with -init. Previously a missing file (moved testdata,
wrong path, accidental delete) was indistinguishable from a real first
run and silently wrote a fresh golden with no revision history checked
against anything. writeGolden() is extracted out of main() so this is
covered directly: TestWriteGoldenRequiresInitWhenMissing,
TestWriteGoldenInitCreatesWhenMissing,
TestWriteGoldenIgnoresInitWhenGoldenExists (the existing-golden path is
still governed only by SafeToWrite, -init or not).
3. Narrowed the two remaining stale claims that still described the
digest's original, narrower coverage: the wire_revision property's
prose in openapi.v0.yaml (regenerated into apigen/types.gen.go via
make api-gen) and wireshape/doc.go now both list nullable, array item
shape, additionalProperties value shape, request bodies, and
$ref/allOf/oneOf recursion, plus the new -init guard.
go test ./internal/httpapi/... and make api-check both green;
bazel test //internal/httpapi/... (httpapi, wireshape, and the new
gendigest test target) green; python3 tools/bazel/go_srcs.py --check
clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(wireshape): cover operation parameters in the wire-shape digest
The digest previously walked only response and request-body schemas, so a
type, enum, required, or removal change on one of the spec's 138 operation
parameters (123 query, 14 path, 1 header) passed the gate silently — the
open item from PR review on #7182.
Each parameter is now recorded as its own Entry, keyed by
"param:"+operationId / location+":"+name (operation-scoped, not
schema-scoped, since two operations' same-named parameter are independent
wire contracts), capturing type, array item shape, enum, required, style,
explode and default. Adding a parameter stays additive; removing,
retyping, narrowing its enum, or changing required/style/explode/default
now trips SafeToWrite exactly like a response or request-body change.
Verified against the live spec: retyping listIssues' `limit` query
parameter from integer to string now fails TestWireShapeDigest (confirmed
red, then reverted — not part of this commit). golden.json regenerated via
gendigest; the new parameter entries are a pure addition, no wire_revision
bump needed. Added TestParameterMutationsAreCaught (remove/retype/narrow-
enum against real golden entries) and updated wireshape's doc.go, the
`wire_revision` spec prose, and the CHANGELOG to describe the new
coverage.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(wireshape): review fixes — stale-golden and lowered-revision arms, effective param serialization, digest boundary
Maintainer fixup from the adopt-pr review loop (iterations 1 and 2), on
top of e17ba924f.
- goldenDrift (A, I): TestWireShapeDigest's comparison moves into a
goldenDrift helper. An addition alongside a moved wire_revision no
longer passes with a stale golden: it asks for a regenerate, as a
changed or removed entry after a bump already did. Every message now
names response/request-body members AND parameters, and TestGoldenDrift
pins each arm. This takes only the test half of the stranded fixup
(adopt-pr/bd-47kdge/stranded-fixup-528cd6095); its doc half, which says
parameters are outside the digest, is false since e17ba924f and is not
replayed (J).
- Lowered wire_revision (D): a CurrentWireRevision LOWER than the
golden's is a wrong constant, not a stale golden, so goldenDrift says to
restore it instead of regenerating, and SafeToWrite (so gendigest)
refuses any write at a lower revision, whatever the entries.
- Effective style/explode (B): walkParam records style and explode with
OpenAPI 3.0's defaults filled in (form for query/cookie, simple for
path/header; explode defaults to style == form). Adding `explode: false`
to a query array that relied on form's implicit explode is now a
changed entry, while spelling out a default changes nothing.
testdata/golden.json is regenerated with -init: 111 parameter entries
change only in style/explode (96 to form/true, 15 to simple), 828
entries before and after, wire_revision stays 2. The golden is new in
this PR and unreleased, so this needs no bump.
- TestWalkParam (H): a package-internal table test
(wireshape_internal_test.go) pins every field walkParam extracts,
through a computeFrom(document, revision) seam that Compute now wraps:
per-location defaults, $ref'd parameters and items, format, nullable and
default, content parameters, and the nil returns.
TestEffectiveSerializationIsCompared pins B end to end through Compare
and SafeToWrite. BUILD.bazel embeds the library in the go_test, which is
gazelle's own output.
- Required inputs and the digest boundary (C, E, F; docs only): all five
prose surfaces (openapi.v0.yaml's wire_revision description and the
regenerated apigen/types.gen.go, wireshape/doc.go, CHANGELOG.md,
engdocs/design/bd-serve-v0.md) now say that a new REQUIRED request
input is recorded as an ordinary addition and needs its own review,
that value constraints and member-level composition are outside the
digest, and that object and content parameters are recorded only as
their container. bd-serve-v0.md also gains the parameter coverage it
was missing.
- G: a brand-new operation is permanently exempt from the
capability-token rule; its own review decides its capability story.
- Iteration 2 (nit): walkParam's comment now says that the location
default it records as a `content` parameter's style and explode is a
placeholder, since OpenAPI 3.0 applies style and explode only to a
parameter described by `schema`. All 138 operation parameters in the
spec use `schema`, so the golden does not change.
Validated: go test ./internal/httpapi/... (gms_pure_go), make api-check,
go vet for linux/windows/darwin, gofmt, git diff --check, gazelle on the
package (no drift), make bazel-sync-check, and bazel test
//internal/httpapi/wireshape/... in the local processwrapper sandbox
(2 of 2 pass). Overlay mutation probes: dropping the added-after-bump
arm, the lowered-revision arm, SafeToWrite's lowered check, or the
effective-default fill each turns the new tests red.
Iteration 2 changes only that comment; go test
./internal/httpapi/wireshape/... (gms_pure_go), go vet, gofmt and git
diff --check pass again.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* test(storage): measure ApplyBatchInTx SQL statement counts (B0)
Adds a driver.Connector-level counting/latency-injecting wrapper
(internal/storage/sqlcount) plus shared plan-request fixtures
(internal/storage/batchfixtures: mol-normalized 356/712-item shapes and a
40-item classic shape) and backend-specific pinning tests + benchmarks
(internal/storage/embeddeddolt, internal/storage/dolt) that measure the
ACTUAL number of SQL statements issueops.ApplyBatchInTx issues for each
shape, on both the embedded and Dolt (TCP) backends.
Measured totals (Prepare+Exec+Query+StmtExec+StmtQuery inside one
transaction): 356 items ~7008-7009, 712 items 14014-14015, 40 items 846,
identical on both backends (expected: statement issuance is driven by Go
application logic, not backend-specific SQL planning). Pinned with a small
(+/-2) tolerance to absorb an observed, host-contention-driven +/-1 Query
drift (Exec is deterministic on every run). This is the regression baseline
slice B2 (a later, lighter fast path) must demonstrably lower.
batchfixtures.UncappedPlan bypasses issueops.MaxApplyBatchItems so this
measurement does not depend on slice B1's cap raise.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(httpapi,issueops): raise batchApply envelope to 1000 items with bounded large-apply handling
POST /v0/beads/issues:batchApply now accepts up to 1000 items (up from 100);
issueops.MaxApplyBatchItems moves accordingly and the request body cap rises
to 16 MiB. The whole plan still applies in exactly ONE transaction. A request
over 100 items runs under a separate, flat, operator-configured whole-run
budget (`bd serve --large-apply-ceiling`, 5 minutes by default) instead of
the ordinary 60s request deadline; a request at or under 100 items is
unaffected and keeps exactly the 60s deadline and 15s commit-retry ceiling it
always had.
Concurrency and shutdown are bounded, not just documented:
- Oversized requests serialize through a dedicated one-wide semaphore, and at
most one caller may wait for that semaphore at a time (a CAS-guarded single
waiter) — a burst of oversized requests is shed with 503 rather than
queuing and starving ordinary traffic behind the general semaphore.
- The run deadline is stamped only once the slot is actually acquired, not
at the time the request arrived.
- Graceful shutdown closes new admissions before computing its drain budget,
then waits out an in-flight large apply up to its own remaining deadline
(plus a few seconds' grace for the response to write); any large apply
still queued for the semaphore when shutdown begins is refused rather than
extending the drain further. A queued caller that disconnects gets a clean
503, never a misclassified context error. `bd serve`'s orchestrator stop
grace must be at least `--large-apply-ceiling` — see
engdocs/SERVE_RUNBOOK.md.
- ApplyBatch's commit-retry budget only extends past the ordinary 15s ceiling
on this explicit large-apply path (via a context marker), with headroom
reserved so the final retry attempt can't be killed mid-commit by the
context's own expiry.
A new `issues.batchApplyLarge` capability token on `GET /v0/beads/context`
lets a client learn whether a given server accepts the raised envelope.
Wall-clock measurement (embedded Dolt, whole-transaction build+commit) backs
the 5-minute ceiling default: 356 items ~12.6s (23.8x headroom), 1000 items
~57.5s (5.2x headroom).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(httpapi,serve): wire the large-apply retry budget; repair stale pins
Review fixes for the large batchApply envelope, on top of the test
repairs the PR needed against main.
The extended commit-retry budget was never switched on.
internal/storage/uow's retryTxBudget lets a large apply keep retrying a
commit-time conflict past the ordinary 15s ceiling only when its context
carries issueops.WithExtendedRetryBudget's marker, and the docs on both
sides say admitLargeApply sets it, but nothing did: the marker's only
callers were the uow tests, which mark their contexts by hand. A
1000-item apply that hit a conflict still gave up after 15s with most of
its 5-minute ceiling unused. admitLargeApply now marks the run context
it builds, and TestApplyBatchMarksOnlyALargeApplyForTheExtendedRetryBudget
pins the seam over HTTP: marked at 101 and 1000 items, unmarked at 100.
Removing the mark fails the 101 and 1000 cases; marking every request in
handleApplyBatch fails the 100 case.
Smaller fixes from the same review:
- `bd serve --large-apply-ceiling` repeated the 5m default as a literal
of its own, and since bd serve always passes a positive ceiling, that
literal, not httpapi's, was the default every deployment ran. Export
httpapi.DefaultLargeApplyCeiling, default the flag to it, and pin the
flag's 5m0s default in TestServeFlags.
- admitLargeApply's release cancels the run context before clearing
s.largeApplyDeadline, the order acquireLargeApply's doc states; it
cleared the deadline first.
- Drop the batchfixtures test's dead t.Skipf, which waited for the cap
to reach 1000, and correct a graph-counter comment that still cited
the 100-item cap and the TestServeFlags doc line that called the
no-argument server unchanged.
The PR raises issueops.MaxApplyBatchItems from 100 to 1000 and adds
`bd serve --large-apply-ceiling`, but two base-owned tests still pinned
the old surface and went red on every lane that runs them (Bazel / test,
Test (macos-latest)):
- TestServeFlags pins the exact `bd serve` flag list; add
large-apply-ceiling.
- TestPlanApplyBatchRefusesAnUnusableRequest/too_many_items built 101
items and expected "at most 100 items", a request the 1000 cap now
plans successfully. Size the over-cap request and its message from
issueops.MaxApplyBatchItems, as TestPlanApplyBatchAcceptsTheBoundary
already does for the other side of the cap; the cap's value stays
pinned by TestCapBatchApplyLargeTiesAllThreeLimits.
The PR's own TestLargeApplyBurstNeverStarvesSmallRequestsForSemTimeout
also went red in PR Core (-race, -p 4 on a 4-vCPU runner): all eight
small requests took 160-165ms against a 100ms bound. The stall it
guards against lasts semTimeout (5s), while a small request can still
queue briefly behind the refused large requests, each holding a general
sem slot while its body decodes. Bound it at a second, the "want well
under a second" its sibling TestLargeApplyQueueDoesNotStarveOrdinaryRequests
already uses. Pinned to four cores beside 24 busy loops, small requests
measured 183ms mean and 338ms max, and the 1s bound passed 80/80 runs;
with the one-waiter gate in acquireLargeApply disabled the test still
fails 3/3, on its 2s never-completed check.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(uow): stop a doomed large-apply retry before ctx cuts it off
retryTxBudget sizes maxElapsed once at ApplyBatch entry, but says nothing
about how long an individual attempt takes. A slow first attempt (e.g.
157s of a large apply's commit) left little of the budget for a retry,
which then got killed mid-transaction by ctx's own deadline instead of
finishing and reporting its own outcome -- surfacing as
context.DeadlineExceeded (isUnavailable excludes it -> a generic 500)
instead of the exhausted-write-conflict result this loop already reports
correctly (-> 503 + Retry-After).
RunTxResultWithin now tracks the previous attempt's duration and, before
starting a new one, stops early with the last real serialization error
when time left on ctx is less than that duration plus a fixed headroom --
but only when publicops.HasExtendedRetryBudget(ctx) is set (the same
marker retryTxBudget itself checks). Applying the look-ahead
unconditionally regressed TestApplyBatchHonorsAnExtendedRetryBudgetFromContext's
unmarked case: ordinary requests have cheap attempts and are meant to run
until their own ctx deadline ends the loop, and the large-apply-sized 5s
headroom was tripping that for any short-ctx caller with a near-instant
failing attempt.
Adds TestRunTxResultWithin_SlowAttemptStopsBeforeADoomedRetry (a 1.2s
commit against a 2s marked ctx must stop after one attempt with its own
serialization error, never DeadlineExceeded, and never touch a second
unit of work) and its control, TestRunTxResultWithin_ShortAttemptStillRetries
(a 50ms attempt against the same shape must still retry and succeed).
Both mutation-checked against the look-ahead condition and its gate.
Also updates the stale "items accepts at most 100 entries" prose on the
applyBatch endpoint description (openapi.v0.yaml) to the large-envelope
wording already used elsewhere in the spec: 1000-item cap behind the
issues.batchApplyLarge capability, large-apply-ceiling deadline extension,
<=100 unaffected. dependencies:count's own "at most 100" lines are
unrelated and untouched.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(ci,serve): fit the 1000-item cap's tests in the storage shard budget
Review fixes for the relaunched #7051, iteration 1.
Raising issueops.MaxApplyBatchItems from 100 to 1000 made the base-owned
TestBatchApplyContract take 604s under -race, against 97s at the old cap
(main run 35862663577). It hashed onto the legacy test-embedded-storage
shard 2/5, beside ~5m of other tests, and that shard hit its 15m budget
twice (PR Risk run 36807191489). PR Risk no longer runs the legacy tier
on same-repo PRs (#7071), but Main's push run and fork PRs still do, so
the merge would have carried the timeout to Main.
Raising the jobs' timeout-minutes alone would not fix it: the shard
script passes the binary its own -test.timeout=15m. So:
- embedded-storage-test-shard.sh passes -test.timeout=20m (and its go
test fallback -timeout 20m), as embedded-test-shard.sh does for
cmd/bd.
- test-embedded-storage in main.yml and pr-risk.yml: timeout-minutes 15
-> 25, the script's 20m plus setup.
- embeddeddolt_embedded_test appends -test.timeout=19m, as
bd_embedded_test does, so Go's timeout, which dumps every goroutine,
fires before rbe-west's 1200s action kill, which does not.
TestBazelEmbeddedJobMirrorsEmbeddedTier now checks the override on
both sharded targets instead of only cmd/bd's, and the PR Risk
coverage test pins the storage target's new args.
- embedded-storage-test-shards.txt places TestBatchApplyContract on
shard 4, which has ~3m of other tests, and the PR's two large-batch
tests, TestLargeBatchApplyStatementCounts_Embedded (247s) and
TestLargeBatchApplyWallClock_Embedded (261s), on shards 2 and 5. From
the PR run's per-test times, the heaviest shard projects to ~13m, down
from shard 2's 15m-plus.
Also correct the stop-grace guidance. For an in-flight large apply,
Serve's drain waits out the apply's remaining deadline plus drainGrace
(5s), so the orchestrator's stop grace must be at least
--large-apply-ceiling plus 5s, as Serve's own doc says. The runbook, the
flag help, the LargeApplyCeiling field doc and the CHANGELOG entry asked
for the ceiling alone.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* feat(dep): teach bd dep cycles to traverse tracks edges (gc-818bx)
Adds DetectCyclesRequest.IncludeTracks and a CanonicalMixedCyclePaths
walk so a molecule-root deadlock closing through a tracks edge (root
--blocks--> its own entry step, step --tracks--> root) is detectable,
while a cycle made entirely of tracks edges stays silent by
construction (guards against the PR #4933 false-positive regression).
Wired end to end: public issueops.DetectCyclesRequest -> pure
CanonicalMixedCyclePaths/AppendMixedCycleGraphInTx ->
DetectCycleReportInTx -> dolt/embeddeddolt/uow-domain transactional
wrappers -> `bd dep cycles --include-tracks`. Default request behavior
is unchanged (byte-identical code path when IncludeTracks is false).
Tests: pure-function unit tests for the new DFS variant (rotation,
parallel-edge dedup, self-loops, map-order determinism); conformance
cases against both dolt and embeddeddolt real backends plus the uow
provider (RunCycleDetectorIncludeTracksIgnoresAPureTracksLoop,
RunCycleDetectorIncludeTracksFindsTheMoleculeRootShape, and an added
DepTracks case in RunCycleDetectorFollowsOnlyBlockingEdges pinning the
default's exclusion); CLI-level flag registration and threading tests.
Scope: fix candidate 3 only, per gascity-pl's 2026-08-10 scope-narrowing
comment on gc-818bx (candidates 1/2 addressed upstream by gastownhall/
gascity PR #5202).
* fix(dep): find mixed cycles by SCC instead of single-pass DFS (gc-818bx)
CanonicalMixedCyclePaths could report no cycle for a graph that has a
qualifying one. A single global visited/onPath set only detects a back
edge to a node still on the active recursion stack, so a tracks-only
loop that fully closes and unwinds first (a->b->a) leaves b marked
visited-but-off-path by the time a scheduling edge into the same
component (a->c->b) is examined, and the c->b return edge is invisible
to the DFS.
Every internal edge of a strongly connected component lies on some
cycle within it, so replace the DFS with Tarjan's algorithm: find each
SCC, and for any SCC containing a scheduling edge, walk a deterministic
BFS return path back to that edge's source. Nodes, adjacency, SCC
membership, the chosen edge, and the return path are all sorted so the
result stays a pure function of the graph, matching the existing
determinism guarantee.
Adds the counterexample from exact-head review: a--tracks-->b,
b--tracks-->a, a--blocks-->c, c--tracks-->b, which the prior
implementation reported as acyclic despite the qualifying a->c->b->a
cycle.
* fix(dep): fail loudly if SCC path invariant breaks (gc-zo8a7)
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of sjarmak
* fix(dep): keep every default cycle in the --include-tracks report
CanonicalMixedCyclePaths emitted one cycle per strongly connected
component, so a tracks edge joining two separate blocks-only deadlocks
collapsed them into one reported cycle and --include-tracks could report
fewer cycles than the default walk.
The widened report is now the union of the default depth-first walk on the
scheduling-only subgraph and, for each blocks/conditional-blocks edge
inside a component of the widened graph, that edge closed by its shortest
return path over either edge type. The first set is the default report by
construction; the second adds cycles that close through tracks edges. Every
reported cycle still contains a scheduling edge, so tracks-only loops stay
out. The report holds at most one cycle per internal scheduling edge plus
the default cycles.
A missing return path inside a component is an invariant breach; it now
returns an error through DetectCycles instead of panicking.
* test(dep): pin tracks edge direction in the cycle detector contract
A two-node cycle reads the same under edge reversal, so the existing
IncludeTracks cases could not tell a walk that follows issue_id ->
depends_on_id from one that follows the reverse. The new three-node case
seeds a -> c (tracks), c -> b (blocks), b -> a (tracks), whose reported
path is a, c, b and becomes a, b, c if the edges are reversed.
Also refresh the cycledetector.go line citations this branch shifted.
* perf(dep): share one return-path search per target in the --include-tracks report
CanonicalMixedCyclePaths ran one breadth-first search per scheduling edge
inside a component, O(E(V+E)). On a dense tangle E grows with the square of
V, so the report grew with the fourth power of the component size.
Group the component's scheduling edges by target and close every edge into a
target from one shortestPathTree rooted there, confined to the component.
closeMixedCycle now reads the return path out of that tree and still returns
an error, never loops, when the tree does not reach the edge's source.
TestShortestPathTreeClosesEachEdgeAsAPerEdgeSearchDid checks over generated
graphs that each edge closes to the cycle reachPath produced for it alone,
ties included. BenchmarkCanonicalMixedCyclePathsDenseTangle (80 issues, a
blocks edge for every ordered pair, one tracks edge back): 26.3 ms and
27.8 MB per call before, 5.4 ms and 2.8 MB after.
* fix(dep): scope the --include-tracks guarantee and bound its output
Review iteration 1 (maintainer fixup) for the one gating major. The
IncludeTracks doc claimed that requiring "at least one blocks/
conditional-blocks edge" on every reported cycle is what keeps out the
`bd doctor` regression that "produced thousands of cycles". That rule is
NECESSARY, NOT SUFFICIENT. One tracks-only loop fuses everything it
touches into a single strongly connected component, after which every
scheduling edge inside that component lies on a cycle and is reported --
even where those scheduling edges alone are strictly acyclic and the
default walk reports nothing. A 10-step molecule whose entry step tracks
back to its root yields 9 reports against the default walk's 0.
The doc's own BOUND paragraph conceded the volume ("never more than twice
the distinct scheduling edges") while the paragraph above it claimed the
guard prevented it. The algorithm is correct and is unchanged; what was
wrong is the contract written over it, plus the absence of any cap on a
diagnostic that can now be edge-count sized.
A census found the claim in 5 sites, not the 2 the review cited:
issueops/cycledetector.go IncludeTracks field doc
internal/storage/issueops/cycle_report.go the BOUND paragraph
internal/storage/issueops/cycles.go AppendMixedCycleGraphInTx
cmd/bd/dep.go flag registration comment
internal/storage/issueops/cycle_report_test.go section header
backend/conformance/cycle_detector_contract.go:246 already scoped it
correctly ("a loop made entirely of tracks edges stays silent") and is
left alone. The PR body and the contributor's commit messages assert only
the true narrow rule, so neither needed correcting.
--limit caps the RENDERED list (default 50, 0 = no limit), matching the
idiom in list/search/stale/find_duplicates. It is a rendering cap and not
a narrower request because CycleReport.Cycles promises to omit no cycle:
the printed total stays the whole report's, the truncation says how much
it held back, and --json is never capped.
TestCanonicalMixedCyclePathsBoundsAFusedMoleculeByItsSchedulingEdges pins
the manufacture direction ...KeepsDeadlocksATracksEdgeFuses left open --
that one fuses two real deadlocks and checks neither is lost; this one
fuses none at all and still gets 9 reports.
Also taken, both non-gating: dropped the dormant
`json:"include_tracks,omitempty"` tag, since no serializer of
DetectCyclesRequest exists in the tree and handleDependencyCycles calls
requireNoQuery, so the tag advertised a wire contract the server refuses;
and added a comment naming the backend conformance cases as the only pin
on the row->edge admission switch.
Declined this iteration: factoring appendDependencyGraphInTx and
AppendMixedCycleGraphInTx onto one shared row loop (nit, gate impact
none). It restructures the SQL read path that, per the finding directly
above it, is pinned only at the conformance layer, and
appendDependencyGraphInTx also backs AppendSchedulingGraphInTx -- the
write-time gate behind every `bd dep add`. That is a wider blast radius
than a zero-gate-impact nit earns inside a fixup whose subject is a doc
overclaim; it belongs in its own change.
Validation: go build ./... clean; go vet clean on the 4 touched packages;
golangci-lint v2.10.1 reports 0 issues on issueops/...,
internal/storage/issueops/... and cmd/bd/...; internal/storage/issueops
full package 749 PASS / 0 FAIL / 0 SKIP (748 before, +1 new); cmd/bd
dep-cycles selector 9 PASS / 0 FAIL / 0 SKIP; internal/httpapi
Cycle|SpecParity 6 PASS / 0 FAIL. Mutation: making tracks edges unable to
fuse a component reds the new pin plus 5 incumbents (the feature dies);
reporting only one cycle per component reds the new pin ALONE (1 of 14),
so it covers a degradation no existing test catches.
Review iteration 2: the remedy above re-entered its own finding class. Both
iteration-2 items indict text THIS fixup wrote, not the contributor's.
The --limit cap is UNCONDITIONAL -- `if limit > 0 && len(shown) > limit` never
consults includeTracks -- yet every rationale iteration 1 wrote for it was
scoped to the widened walk, and the IncludeTracks field doc still closed with
"the base walk this type's doc above describes is unchanged". True of the walk;
false of its rendering, since plain `bd dep cycles` printed every cycle at base
and now prints at most 50. That is the same defect class as the major this
commit exists to fix: a doc claiming a scope the mechanism does not honor.
Of the two arms the review offered, only documenting the true scope is
available. Gating the cap on includeTracks reds this PR's own incumbent test:
printCycleReportForTest calls runDepCycles(false, limit), so
TestDepCyclesTruncatesTheRenderedListButNotTheCount/capped asserts the DEFAULT
walk truncates. Measured, not assumed -- that arm fails capped and
registered_default while no_limit passes. The implementation, the flag's help
string and the tests already agreed the cap is unconditional; only the prose
disagreed, so the prose moved:
cmd/bd/dep_cycles.go runDepCycles doc: the cap is unconditional, bounds
both walks, and names the behavior change vs base
cmd/bd/dep.go flag comment: caps both walks; the widened walk is
what makes the cap necessary, not what scopes it
issueops/cycledetector.go the "Default false" closer: the walk is unchanged,
its RENDERING is not
Also the nit: the opening paragraph argued no flag can narrow either question
while --limit had no carve-out, where IncludeTracks had one. It now says no flag
narrows the ANSWER, and that --limit caps only what is PRINTED.
New renderer arm "registered default" closes the gap the minor named: every
existing arm drove an explicit limit, so the shipped 50 was pinned only by
TestDepCyclesLimitFlagRegistration's DefValue != "0". It reads the default off
the command and renders past it, so it tracks whatever ships; ids are
fixed-width so "past the cap" cannot match as a prefix of one inside it.
Mutation (3 arms, control restored byte-identical by cp -- the fixset was
uncommitted): gate the cap on includeTracks => capped + registered_default RED;
default 50 -> 0 => LimitFlagRegistration + registered_default RED (the new arm
independently catches an unbounded default); shown[:limit+1] => capped +
registered_default RED, so the arm pins the boundary and not merely "some
truncation". no_limit stays green under all three by design.
Validation: gofmt clean, git diff --check clean, go build ./... rc=0, go vet
clean on cmd/bd and issueops, cmd/bd dep-cycles selector 9 PASS / 0 FAIL / 0
SKIP (same top-level roster, +1 subtest). No production behavior changed this
iteration -- doc text plus one test arm.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: sjarmak <t@t.co>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
* fix(serve): retire idle SQL connections before Dolt
* ci: retrigger macOS checks
* fix(serve): refresh the sibling comments the 20s pool idle cap falsified
Maintainer review fixup for #6741. The review found no blocker and no major;
this is its one gate-impact minor (Architectural Consistency / Change Impact).
Comment-only, no behavior change.
Lowering servePoolLimits.ConnMaxIdleTime from 5m to 20s falsified the
"ConnMaxIdleTime (5m)" figure at the two sibling sites that reason about the
pool-drain/proxy-lifetime interaction. Both designs those comments defend get
STRONGER at 20s, so the decisions stand and only the figures were wrong -- with
one exception:
- cmd/bd/uow_factory.go is the load-bearing justification for
proxyIdle: proxy.IdleTimeoutNever. A pool that drops its last connection at
20s reaches zero clients well inside the proxy's 30s default, so the argument
holds harder than before; the figure now reads
"ConnMaxIdleTime (20s, servePoolLimits)".
- cmd/bd/serve_server_mode_integration_test.go was worse than a stale number:
it justified asserting on the spawned child's command line *because* the
failure "is otherwise only visible after five idle minutes, which no test can
wait for". At 20s that premise is false, so the comment argued against a test
that had become feasible. The command-line assertion stays -- observing the
failure directly still has to idle out the pool and then the proxy's own 30s
default, about a minute of dead time gated on two independent timers -- but
the stated reason is now one that survives the new constant.
Validation: gofmt clean on both files; git diff --check clean;
go vet ./cmd/bd/ with CGO_ENABLED=1, which type-checks the //go:build cgo
integration test file that holds the second comment.
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
* test(httpapi): red — slow-release acquire must tolerate more than a hair-trigger window
TestSemaphoreShedsLoadInsteadOfQueueingForever's final section shares its
semTimeout (20ms) with the shed-check above it, so the "eventually succeeds"
path only had ~15ms of margin over its 5ms release delay. Bump the delay to
25ms to deterministically prove the current margin is too tight: a release
that beats a merely-adequate window must still succeed. This fails today by
construction, not by chance (refs be-qczn).
* fix(httpapi): green — slow-release acquire must tolerate more than a hair-trigger window
Widen semTimeout to 2s for the "eventually succeeds" section only, leaving
the shed-check above untouched at 20ms. The two assertions were sharing one
field: the shed check needs a short deterministic timeout to stay fast, and
the slow-release check needs enough margin that a loaded runner overshooting
a short sleep can't turn a real success into a spurious ErrBusy. This is not
a blanket bump of the 20ms constant — the busy-path assertion keeps its
original tight window; only the section that was actually racing gets more
room (refs be-qczn).
Verified: go test -count=200, and -count=200 pinned to a single contended
core (GOMAXPROCS=1, 6 competing busy loops) — both clean.
* chore(release-gate): PASS record for flaky semaphore test fix (be-u8o4)
Deployer gate evaluation for be-f80c/be-u8o4: all 7 criteria PASS,
independently re-verified rather than trusted from review evidence alone.
Server-API hardening for the loopback HTTP surface: a request may now carry a
Bd-Project-Id header naming the workspace the client means to address, and the
server refuses it with 400 / invalid_argument / reason=project_mismatch when the
id does not match the project this server serves. This closes wrong-server reads
and writes structurally rather than by convention — a client that stamps its
requests can no longer silently operate against a workspace it did not intend,
and the refusal is raised before any database slot or unit of work is acquired,
so a misdirected request mutates nothing.
The check is capability-gated and backward-compatible:
- Absent header is today's behavior. Enforcement triggers only when the header
arrives, so clients already in the field are served exactly as before; this is
additive wire surface, not a new precondition.
- The comparison is literal. A server whose own project id is empty refuses any
non-empty stamp, mirroring the identity handshake: a server asserts only the
identity it can prove.
- /healthz and GET /v0/beads/context are exempt (projectExempt), the two reads
that touch no database: liveness must answer whatever workspace a caller
believed it reached, and the handshake is where a client learns the id to
stamp with in the first place.
- The refusal alone carries the server's own id in the new optional Problem
member server_project_id, and only after the request clears the Host gate — a
refusal raised earlier never discloses server identity.
- A new behavior capability, project.enforce, advertises the check so a client
relies on the refusal instead of discovering an older server ignored its
stamp.
The OpenAPI document is the source of truth: a fourth document-level cross-cutting
400 rule, the server_project_id Problem member, the project_mismatch reason, and
both capabilities prose sites are updated; the Go wire types are regenerated from
it. The proxied bd-serve capability literal
(cmd/bd/serve_proxied_integration_test.go: servedCapabilities) is updated to
carry the new project.enforce token, so the GET /v0/beads/context contract test
that asserts the advertised set exactly stays green in the proxied-server cmd
tier. Local gate green (make api-check clean; full internal/httpapi suite and the
proxied serve lifecycle test pass).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Publish GET /v0/beads/issues:count, with the role's whole filter surface
issueops.Counter is the role the ADDING_AN_ISSUEOPS_ROLE checklist was derived
from, and it was the last read role on the store with no HTTP half. `bd count`
reached it; nothing over the wire did. A client that wanted a number had to
page a listing and count the rows, which answers a DIFFERENT question: a
listing hides closed, pinned, template and gate rows and a count hides none of
them, so the two disagree by every one of those exclusions.
Spec first, then `make api-gen`, then the handler.
ONE OPERATION FOR BOTH OF THE ROLE'S METHODS. `group_by` selects the bucketed
shape, because the two ask the same predicate of the same set and the grouped
response is the scalar response PLUS `groups` — one schema with an optional
member, not two contracts under one id. That is the opposite of `events:watch`,
which is a sibling operation because it differs in media type, lifetime, limits
and capacity; here nothing differs but one member.
The full CountRequest surface is published — 23 filters plus the dimension —
because a wire narrower than the role would make an HTTP-backed store answer
questions the native one can and it cannot. The two parameters that could
mislead are documented rather than smoothed over: `status` is ONE status here
where the listing takes a comma-separated set, and `include_infra` changes four
things at once (merges the wisps tier, drops templates, drops gates, routes an
infra type to the ephemeral tier).
One finding worth the ledger: NO ROLE REFUSAL IS REACHABLE from this operation.
issueops.Counter has exactly one ErrValidation — ValidateCountGroup's unknown
dimension, since BuildCountFilter cannot fail — and the handler refuses that
dimension at the edge, so every `invalid_argument` here is the transport's. The
spec, the operationCodes row and a test all say so, and
TestCountGroupEnumMatchesTheRolesVocabulary is what keeps it true: a dimension
this server accepted and the role refused would arrive as an unclassified 500.
The wisp-plane question is answered against real Dolt rather than asserted: a
default count is DURABLE ONLY and `include_infra` merges the ephemeral tier in,
both agreeing with `bd count`'s own numbers through the same role.
Config gains a required Counter field on the checklist's own terms — a Config
missing it would bind, advertise issues.count and nil-dereference on the first
request — and `bd serve` binds it beside the ready counter.
Gates: `make api-check`, `go build ./...`, `go vet ./...`, `gofmt -l` clean,
`golangci-lint run` on the touched packages, `--new-from-rev=origin/main`, and
the windows/no-cgo cross-lint the PR workflow runs (0 issues each), plus
`BEADS_TEST_PROXIED_SERVER=1 CGO_ENABLED=1 go test ./cmd/bd/ -run
TestProxiedServerServeCount` green against real Dolt. The pre-commit hook's
`go run golangci-lint@v2.10.1` fails on this host with a toolchain mismatch
unrelated to this change, so the hook's contents were run by hand before
committing with --no-verify.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Derive both capability expectations from the route table
The count slice went red on a proxied shard for a list nothing about counting
had changed: cmd/bd's servedCapabilities is a second hand-written copy of the
capability vocabulary, and the thirteen checks a stacked PR runs do not include
the proxied shards. The literal was updated in internal/httpapi and missed out
here — which is the failure mode the list's own comment describes ("the
server-mode copy sat at four entries through every expansion since"), happening
again for the same reason.
Both literals are now derived from routeTable, which already carries capability
and implemented and already feeds the spec-vocabulary check.
The argument the old comment made against deriving — "comparing the server
against its own derivation would pass for any surface at all" — is true and is
answered somewhere better. TestSpecCapabilityVocabularyMatchesTheRouteTable
compares the derived set against the `capabilities` prose in openapi.v0.yaml in
BOTH directions, and that paragraph is written by hand for the operation being
added. So content still has an independent oracle, adding an operation still
costs a deliberate edit, and the edit is now in the document a client reads
rather than in two test files nobody does.
internal/httpapi re-derives from the table rather than calling Capabilities(),
which the handler already calls: Capabilities() == Capabilities() is green for
every surface including an empty one. A non-empty guard and a sortedness
assertion on the wire keep it from passing vacuously; reversing the sort turns
it red.
Two assertions written for this were DELETED after mutation testing showed they
cannot fail — a stub-advertises-itself loop and an implemented-gate check, both
green against the mutations they were named for, because the expectation
re-applies the same filter and v0 has no 501 rows to filter. The comment says
so and names what actually holds the gate (TestSpecStatusCodesMatchHandlerTable
fails on any unimplemented row) and the probe that would upgrade it.
Also, from review:
- TestEveryCountRequestFieldIsPublished pins issueops.CountRequest's 23 filters
against the parameters that reach them. A 24th field left unpublished turned
nothing red before, and an unreachable role filter is exactly how an
HTTP-backed store becomes narrower than the native one without anyone
deciding to narrow it. Falsified against a hypothetical field.
- TestCountParametersMatchTheHandler's comment records that its derivation is by
EXECUTION: it sees the names read on the path taken, which is the whole
vocabulary only because countFilters is straight-line today.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Declare Counter on the serve stub store
CI's macOS shard caught what my local runs did not: binding the count role in
serveIssueRoles made TestServeIssueRolesComeFromBeneathTheHookDecorator panic
with a nil dereference.
This is the hazard ADDING_AN_ISSUEOPS_ROLE.md calls "the step with no number" —
every surface that EMBEDS the store gains a new accessor PROMOTED rather than
declared, so the build stays green and the first symptom is a nil dereference in
somebody else's stub. serveRolesStore embeds a nil storage.DoltStorage and
declares only the roles its own test is about; Counter was not one of them.
The count role made it reachable for a reason worth recording: Counter is a
READ, so hook_counter.go RECURSES and hands back the inner surface unwrapped —
and that recursion lands on this stub. A role whose decorator wraps would have
stopped at the wrapper.
The other surfaces the checklist names were checked and need nothing:
storage.RoleFiresHooks takes cases only for decorators that WRAP, and uow's
notifying provider has declared CounterSource since the role landed.
The gap that let it through was mine: I ran the proxied shards by name and never
the whole cmd/bd package. Running it now shows an identical failure set on this
branch and on a clean origin/main worktree — 25 tests, all collateral from the
package exceeding go test's default 10m timeout on this host.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
bd serve's help says "No authentication and no TLS", and the first half of that
is what stops it being deployed anywhere but a developer's loopback. Two flags
answer it, and both default to the behavior that exists today: a `bd serve` with
no arguments is byte-for-byte the server it has always been.
AUTHENTICATION
--auth-token-file names a file of accepted tokens, one per line, all
accepted. There is deliberately no --auth-token: a credential passed as an
argument is readable by every local user out of ps.
The accepted set is NOT a startup snapshot. It is re-read while the server
runs, gated to at most one stat(2) per second for the whole process, and that
is what makes rotation hitless — write {new,old}, roll the clients, drop old —
and what makes a leaked token revocable inside a second without a restart.
The freshness check runs on the ACCEPTING path too, not only on a mismatch:
a token the operator just deleted still matches the cached set, so a
mismatch-triggered reload would give rotation and never give revocation.
A failed or empty re-read keeps the last-good set and logs the error, so a
writer that truncates before writing cannot lock every client out; the stat
cache is left untouched, so the next attempt re-reads and recovers.
The check sits in route(), on a per-operation authExempt column beside
bypassSemaphore, and runs BEFORE the semaphore — a refusal costs one SHA-256
and can never occupy the database slots authenticated clients are waiting for.
/healthz is the one exemption, because a probe carries no credential;
/v0/beads/context is not, because it reports the repo root, beads directory
and database name. Tokens are compared as SHA-256 digests in constant time,
so the process holds no raw credential and the 401 — fixed detail, via the
staticDetail map — can never echo the one that was presented.
The wire says so: a bearerToken securityScheme, a 401 on every guarded
operation, and a spec-parity test that fails if the route table's exemption
column and the document's security blocks ever disagree. That test is what
makes a NEW operation inherit the 401 in the same commit that routes it.
HOST ALLOWLIST
--allowed-host (repeatable) adds Host values the DNS-rebinding check answers
to. Matching stays exact; there is no wildcard or suffix syntax. Admitting a
name the operator enumerated does not weaken the defense: a rebound page
still cannot make a browser send that Host to 127.0.0.1, and the automation
clients that do send it are not browsers. Without this, a server reached by
any name other than a loopback spelling or the bind address 400s on every
request, which is the first thing a non-loopback deployment trips over.
WHY LOOPBACK BEHAVIOR IS UNCHANGED
Every new field defaults to the value that reproduces the old code path: no
Auth, no extra hosts. A zero-valued Config is the previous server, and the
whole pre-existing test suite proves it — none of those tests passes a token
or a host, and all of them still pass unmodified.
The one deliberate behavior change is at the other end: --allow-non-loopback
now REQUIRES --auth-token-file, escapable only by naming --insecure-no-auth.
Beyond loopback the old default was that reaching the address granted every
read and every claim. The three places that advertised "no authentication" —
the help text, the bind refusal and the flag usage — are reworded, since
leaving any of them would ship a false security statement.
Still no TLS, deliberately and unchanged. A non-loopback bind now warns that
the token and the issue data travel in plaintext and belong inside a trusted
boundary; supplying confidentiality is the deployment's job.
Agent-Signature: claude-opus-5
Co-authored-by: CI Bot <ci@beads.test>
* Publish POST /v0/beads/issues:claimNext: take ready work atomically (ga-g3gg8)
A client of this surface that wants the next piece of work composes
`GET /v0/beads/ready` with `POST /v0/beads/issues/{id}:claim`. That
composition is a RACE, and it is the reason this operation exists rather than
a round trip saved: between the listing that offered a row and the claim that
asked for it, another agent claims it — so the second agent earns a 409 for a
row it was correctly offered, and a fleet polling one queue spends its
requests losing races instead of doing work.
`claimNextIssue` publishes issueops.ReadyClaimer, where selection, the
compare-and-set that wins the row, and the hydration of the row that was won
are ONE transaction. The row cannot move between being chosen and being
reported.
THE FILTER IS THE LISTING'S, and not a copy of it. The parameters are decoded
by readyFilters — the same function `listReadyWork` and `countReadyWork` share
— because a claim that answered a different question than `bd ready` shows
would hand an agent work the listing never offered it, and two predicates that
are allowed to differ eventually do. The actor is the only body member: it is
provenance that lands in a column, and this surface has always carried that in
a body, while re-spelling the filter as a body object would create exactly the
second expression the shared decoder exists to prevent.
TestClaimNextAdmitsExactlyTheListingsFilters holds the DOCUMENT to the same
identity, since only the handler is protected by sharing the function.
`limit` is refused BY VALUE rather than left to the unknown-parameter rule,
and the distinction is two different client recoveries. `unknown_parameter`
means "this server does not know that name — version skew, degrade or fall
back", which would be false: it is a name this server knows perfectly well on
the sibling listing. It will not ACT on it, which is `invalid_value`, and the
reason is the role's: a claim delivers the one row it wins however large the
pool it scanned, and the scan must stay unbounded or a window that happens to
be full of rows a racing agent already took reports nothing to claim.
`sort` IS published, unlike on `ready:count`, because order decides WHICH row
a claim writes to where it cannot change a cardinality — and it is sent
explicitly for handleReady's reason, which bites harder here: an empty policy
adopts storage's hybrid fallback, and here that changes the row that gets
written rather than the order rows are printed in.
NOTHING ELIGIBLE IS A 200 WITH `claimed` ABSENT. An empty ready front is the
steady state of a drained queue, not a failure, and a polling agent that had
to classify an error to discover it would be pattern-matching prose. There is
no boolean beside the member and no scan count: a second member carrying the
same fact is a second member that can disagree with the first. This is the one
place the operation differs from `issues/{id}:claim`, which 404s an id that
names nothing — that one was asked about a ROW, and this one was asked a
question whose honest answer can be "none".
It documents no 409 and no 404 at all, and both absences are contract. There
is no id to have missed, and a row a racing agent took is simply not in the
set this claim scanned.
The real-Dolt leg asserts the guarantee a fake cannot express: nine concurrent
claimants against six ready rows win six distinct rows and never the same one
twice. The assertion is on duplicates rather than on timing, so it is
deterministic however the goroutines interleave.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Publish patch.add_labels and patch.remove_labels on updateIssue (ga-g3gg8)
The bead asked for "incremental label add/remove on the wire", noting that
labels are replace-only and that issueops.LabelPatch has Add and Remove. The
trace found the situation is narrower than that and more familiar: the role's
whole algebra IS already wire-expressible — as `labels.{replace,add,remove}`
on `issues:batchApply`'s update item, which has published `ApplyLabelPatch`
since it landed. What has no incremental spelling is `PATCH /v0/beads/issues/{id}`,
whose `patch.labels` is a bare array.
That is #5484's finding again, on the one member it did not close: two
operations for patching one issue, disagreeing about what patching one issue
means. This closes the gap from the same side, and this member is the last of
them.
`patch.labels` KEEPS ITS SHAPE, and that is a constraint rather than a
preference. Nesting it into an object the way `ApplyPatchBody` does would
RE-TYPE a published member, which is the one kind of change this document has
no additive route for — `## Profiles` names re-typing explicitly as not a
tightening, and the only remedies written down are a new optional member or
cutting /v1. So the increments arrive as two flat siblings, which is the shape
`notes` and `append_notes` already use for the same replace/increment pair on
this exact schema.
THEY ARE NOT MUTUALLY EXCLUSIVE WITH `labels`, and that is the difference from
that pair. The role defines an ORDER over all three — replace, then add, then
remove, so removal wins — so a request carrying all three has a defined result
and must reach the role whole. Notes have no such algebra, so there the two
members are a contradiction and are refused. The handler assembles one
LabelPatch in one loop for exactly this reason: a member decoded into its own
patch value would overwrite the others' fields and the last one decoded would
silently win.
The retired premise is worth stating, because it was written down and it was
half right. `patch.labels` said incremental edits were deferred because
"replacement is the only shape whose result the client already knows without a
read-back". That holds for a writer that knows it is alone and fails for every
other one: two agents each adding a tag to one row, each composing a
replacement from a read taken before the other wrote, silently drop each
other's label. `bd label add` and every agent that tags work concurrently are
that caller. The real-Dolt leg is written as exactly that scenario.
The length bound applies to all three members including `remove_labels`, where
a value the column could not hold could never have been stored: it is a rule
about what a label may BE, and the role refuses it there too and writes
nothing, so the edge refuses it where the 400 can name the member and the
index.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Publish POST /v0/beads/issues:batchClose: close many, keep the survivors (ga-g3gg8)
`bd close a b c` is one transaction and one history entry. Over this surface it
has been N calls to `POST /v0/beads/issues/{id}:close`, which is N transactions
and N history entries, with no way for a caller to say it wanted them together.
The request is the transaction boundary, which is the whole reason
issueops.BatchCloser is a role rather than a loop.
IT IS THE ONE OPERATION HERE WHOSE 200 CARRIES REFUSALS, and that shape is the
ROLE's rather than an arrangement of it. An id the batch turns down is skipped
and the survivors commit, because an agent that finishes four of five steps and
mistypes the fifth should keep the four — so a per-item refusal is a RESULT of
the batch, not an error of it. `batchCreateIssues` is the deliberate opposite
and has said so in its own document since it landed: half a created plan cannot
be re-sent without duplicating the half that landed.
The division that falls out is the contract a client codes against, and it is
stated on both sides: a NON-2xx means the batch NEVER RAN, and a per-item
`code` means that item did not land while others may have.
`code` ON AN OUTCOME IS `Problem.code`'s VOCABULARY, restricted to `not_found`
and `not_closable`. A second vocabulary was the alternative and it was refused:
an item refusal and a request refusal are the same question asked at two
scopes, so a client made to learn two spellings would be classifying the SCOPE
rather than the condition. `open_children` keeps both of its readings, and both
are the single close's: present-and-a-count on a success (the number a forced
close bypassed, reported even for an idempotent re-close), and PRESENCE as the
discriminator between the two `not_closable` refusals on a failure, exactly as
on a problem document.
The projection fails CLOSED. An item error no arm recognizes becomes a refusal
carrying the generic code, never a success — because a success with no row is a
shape a client cannot tell from a real close, and a `default` that fell through
would produce exactly that.
NO COMPOSED CLAIM, and the omission is reasoned rather than partial. The role
can claim the next ready issue in the same transaction once the closes land;
publishing that member would need a second, BODY-shaped spelling of the ready
filter vocabulary that `GET /v0/beads/ready` and the `issues:claimNext` landing
beside this one both express as query parameters — and two spellings of one
predicate eventually disagree, which is the reason ReadyClaimer.Filter is the
listing's own request type. A client that wants both sends two requests and
loses the single transaction, which is a real loss and is named in the document
rather than papered over. It is additive later.
The per-item id is bounded HERE, which the single close gets from the
custom-method dispatcher and this operation has no dispatcher to get it from. It
is a 400 rather than a per-item `not_found`, because it is a statement about the
REQUEST and because reporting it as a miss would let a caller map this server's
notion of a well-formed id.
The real-Dolt leg asserts the claim the whole shape rests on: a batch whose
middle item names nothing still commits the two either side of it, each with its
OWN reason — read back through the CLI rather than off the response the batch
composed. A fake cannot state that, because it holds no rows to roll back.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Scope the label members' no-op wording to the labels (ga-g3gg8)
`add_labels` and `remove_labels` each said a no-op edit "reports
`changed: false`". That is the RESPONSE's member and it describes the whole
patch, so it is only true of a request whose sole content was the no-op edit —
a request that also moved a title changed the row and reports true.
They now say what is true of the member: the edit changes no labels. The
response's reading is stated once beside it, as a fact about the patch.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Fix two misspell findings inherited from the release merge (ga-lzcuv)
`main` is red on Lint as of 294af94be2, and both findings are prose from that
squash rather than from anything in this branch:
internal/httpapi/problem.go:85 `archaeology` -> misspell wants `archeology`
internal/httpapi/problem.go:591 `neighbour` -> misspell wants `neighbor`
`.golangci.yml` sets `misspell.locale: US`, so both are real under this
repository's configuration. They are fixed here because this branch merges next
and would otherwise carry a red Lint of its own making no changes to earn.
`neighbour` takes the US spelling. `archaeology` is REWORDED to `excavation`
rather than respelled: `archeology` is the spelling the linter wants and the
one most readers would read as a typo, and the sentence loses nothing by not
having the word in it. Rewording is the only one of the two options that leaves
the comment saying what it meant without looking wrong.
Neither is reachable from the local pre-commit hook, which fails at
golangci-lint config load in this environment before it analyses a file.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Publish POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv)
The claim has had a wire since v0 and its inverse has had none. `bd unclaim`
is a subprocess for every client of this surface, and a release-if-current has
no route at all — so the one verb that frees stranded work is the one verb an
automation client cannot reach.
`releaseIssue` publishes issueops.Releaser whole: `actor`, the
`expected_assignee` compare-and-set, and `force`. The response carries the
issue, `changed`, and `revision` — the last for `updateIssue`'s reason, and
one of its own: a release REMINTS the row's token by design, so a caller that
guarded its next write on a version read before the release would miss, and
this member is the only place the new one exists.
THE REFUSAL CODES ARE THREE, AND ONLY ONE IS NEW.
`already_claimed` is the ownership fence — an unforced, unguarded release by
an actor that is not the holder. That is `updateIssue`'s assignee-fence
situation exactly, down to having two bypasses, so it takes that operation's
code rather than a fourth spelling of "a live foreign owner refused your
write". Like there, no `assignee` member: the fence refuses without naming the
holder, so absence means re-read the row.
`precondition_failed` is the guard, inherited from the same operation and
carrying the same members for the same reason — `expected_assignee` is the
REQUEST's value, and there is no `actual_assignee` beside it, because the
refusal rolled its transaction back and ErrAssigneeMismatch is a bare sentinel
that formats the holder it saw into prose. There is no ClaimConflictError
equivalent to read, and this surface does not scrape its own messages.
`not_releasable` is minted, covering ErrNotReleasable and ErrNotClaimed.
`not_claimable` is the nearest existing code and covers a superset of the same
statuses today, but the coincidence is not a contract — the release transition
is pinned to {open, in_progress} by releasableStatus and the claim's
eligibility is a separate predicate — and for the unheld half the reuse would
be an outright lie: an open, unassigned row is the most claimable row a
workspace has. The two conditions share ONE code with no discriminating
member, which is the narrow choice rather than the convenient one: neither
sentinel carries a typed observation, and splitting later is an ADDITION the
document already tells clients to tolerate, while merging two published codes
is the removal that breaks the wire.
IT IS NOT IDEMPOTENT, and the wire says so rather than inventing an answer the
role refused to give. An unheld row is 409, never a 200 carrying
`changed: false` — that value is one no role produces (ReleaseResult.Changed
is true on every non-error answer), and it would report one answer for "I
released this twice", "a reaper beat me to it" and "nothing ever claimed it",
because the post-state is anonymous and nothing is left on the row to tell
them apart. A client for which "already released" is the ordinary path maps
the code to success in one line it writes knowingly.
`expected_assignee` disagrees with `updateIssue`'s same-named member in
exactly one place, and the schema says so: the empty string is a 400 here
rather than a guard meaning "expected unassigned". It also documents what the
comparison ACTUALLY does — separator-insensitive over runs of `.`/`_`/`-`,
per actorMatches, and nothing else forgiven — rather than repeating the role
doc's "byte for byte", which the implementation stopped being at ga-5ksp5.
failRelease matches all four sentinels TYPED and BEFORE its ErrValidation and
ErrNotFound arms. None of them is wrapped in ErrValidation on any leg, so
below a generic arm every one would have been a 500 on every leg.
The real-Dolt leg asserts the property a fake cannot: after every refusal it
reads the row back through the CLI, so "nothing was written" — and above all
the CLAIM SURVIVING a wrong-holder refusal — is a fact about the stored row.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Fix the release document's three review findings (ga-lzcuv)
The mint stands; what the review caught is that the document was written as
though `not_releasable` meant one thing, and it means two.
THE SAFETY ONE. "A caller for which 'already released' is the ordinary path
treats that code as success" was true of the sentinel it was written against
and is FALSE of the code it shipped as. `not_releasable` also covers the
status refusal, and a row parked in a status this workspace configured is
refused WHILE STILL ASSIGNED — so a reaper following that sentence books a
claim as dropped while it stands, held by an agent that is already gone, with
nothing left to free it. That is the stranding this operation resolves ids
across both planes to prevent, reintroduced through the refusal vocabulary
instead of through the id.
It now says the opposite, in the operation description and again on the 409:
on `not_releasable`, READ THE ROW. The row carries the one fact that separates
the two — an assignee, or none. One extra request on an uncommon path is the
honest price of one code rather than two, and the handler's `detail` says so
too, since that is the string an operator actually reads.
THE ACCURACY ONE. CodeNotReleasable claimed "neither refusal is typed", which
is wrong and misleads the person who eventually splits it: ErrNotClaimed and
ErrNotReleasable are two distinct typed sentinels and failRelease holds both
in one case arm, so a split is a mapping change in that arm — no archaeology
and no prose-scraping. What is genuinely unavailable typed is the OBSERVATION
each refusal made, the status seen and the emptiness of the assignee, which is
why the code carries no extension member. That is a narrower claim than the
one the comment made, and it is the true one. The merge is recorded as what it
is: a deliberate start-narrow choice, kept because adding a code later is the
reversible direction.
THE WIDENING. The 200 now states it: the transition is defined over `open` AND
`in_progress`, so a row already open that STILL HOLDS AN ASSIGNEE is released
here — the state a partial write or an out-of-band status edit leaves behind,
and one a release-if-current guarding on `in_progress` did nothing for and
reported no error about. A client porting such a guard has to know that before
it ports one.
Beside it, the code-to-outcome mapping a release-if-current client wants, so
that mapping is written against a documented fact: `not_releasable`,
`precondition_failed`, `already_claimed` and `404` all mean "no release
happened, and that is not an error" — `(false, nil)` to a client spelling it
as a pair. With the reading that pair does NOT license, stated beside it,
because it is the same reading the safety finding is about: it means no
release happened, never that the claim is gone.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
`bd serve` could create issues only in batches, and only nine members of
one. `POST /v0/beads/issues:batchCreate`'s item has no `status`, no
`sender`, no `metadata`, no `ephemeral`, no `no_history` and no `id`, so a
caller composing a real row could not use it — the R1 lesson
`issues:batchApply` already learned when its create item published the
whole create vocabulary instead.
This is the single-issue create over `issueops.Lifecycle.Create`, on the
plain collection POST the batch deliberately left free by spelling itself
as a custom method. Its issue members are `ApplyCreateItem`'s exactly,
minus that schema's two plan-only members, plus the edge vocabulary that
operation moves into `dep_add` items: `parent_id`,
`inherit_labels_from_parent`, `dependencies` (typed edges, `reverse`
included) and `waits_for`.
Two conflict codes, both inherited rather than invented. `already_exists`
arrives with the explicit `id`, which the batch publishes none of.
`dependency_cycle` arrives with `parent_id` and `dependencies[].reverse`:
the first places the new row in a hierarchy the caller cannot see, the
second writes an edge INTO the id being minted, and between them a create
can close a cycle for the first time. There is no 404 — a target that
names nothing is a statement about the request body, not about a resource
this operation was asked to address — and no `dependency_exists`, because
the only type conflict a create can raise is between two edges of the same
request.
checkedLifecycle.Create stops passing through. It could, while no handler
on this surface reached it; handleCreateIssue writes *result.Issue onto the
wire, so a provider-supplied role answering nil with a nil error was a
panic on a live server.
`created_at`, `created_by`, `spec_id`, the await/molecule/event plumbing
and `IDPrefix` stay unpublished; the PR body carries the decision and the
evidence for each.
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Add issueops.BatchApplier: one plan, one transaction
A heterogeneous, ORDERED list of creates, updates, closes and edges applied
as one durable act. Each of BatchCreator, BatchCloser and DependencyEditor is
one verb repeated, so a caller that needs two of them needs two transactions
with a window in between; this role's unit is a PLAN.
The role, the two bodies, both decorators and the accessors on every
implementer. The wire half and the conformance contract land beside this.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Close the empty-commit-message hole a no-op batch could open
ApplyBatchCommitMessage now reads the write as well as the result. The counts
are ItemResult.Changed, which is what a CALLER observes; a request can still
write a durable row with every count at zero — a same-type edge re-add
rewrites that edge row's metadata, a re-close can settle blocked state. An
empty message for one of those is an unlabelled Dolt commit on the store legs
and a rollback of a real write on the unit-of-work leg.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Give BatchApplier the contract its two bodies justify
Thirty-nine cases over three legs and TWO independent bodies — the store legs
share issueops.ApplyBatchInTx, the unit-of-work leg cannot reach it, and the
contract header says so rather than claiming three backends agree.
The end-gate case is the one that could not have been written before: every
edge in it is legal when it is written, and only a re-validation against the
closure the whole request produced refuses the pair.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Publish batchApply on v0, and delete batchCreate's false promise
The spec first, the types from it, the handler against the types. The item
union is a TAGGED single-shape object rather than a oneOf, because the
document's x-go-type doctrine forbids composition keywords; the create item
publishes sender, metadata, status, ephemeral and no_history, none of which
batchCreateIssues has — which is why no measured caller could use that one.
The wire result stays lean: ids, changed and a revision. The hydrated
snapshot on the Go contract is what the completion hooks consume, and hooks
never fire on this surface.
OQ2: batchCreateIssues' description claimed a dependency target could name an
earlier item of the same batch. It never could — the server mints the ids and
a wire item has no name — so the paragraph is deleted rather than qualified.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Partition the two new dependency probes on the recorder's surface
The gate halves BatchApplier re-runs are repository PROBES — an ancestry walk
and a reachability walk — so recordingDepUC declares neither and the parity
test has to say so out loud rather than let embedding answer for it.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Teach the proxied topology's capability golden about batchApply
The one expectation stored as data outside the package whose gates would
otherwise have caught it — which is what its own header warns about.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Restore the CAS hook case, mint 409 already_exists, and stop over-claiming
Three fixes from review.
The rebase that brought MetadataCAS in left `case *hookMetadataCAS:` with an
EMPTY BODY: a Go type switch does not fall through, so RoleFiresHooks answered
FALSE for it and #5473's Listen refusal was silently disarmed. The compiler,
vet, lint and CI all pass on that. The case is restored and — because it had no
precondition of its own, which is why nothing caught it — serve_source_test now
pins CAS the way it pins the other four, with its peel assertion.
An occupied explicit create id becomes 409 already_exists rather than 400. The
body is well-formed and stays well-formed; what refuses it is state the client
must READ, and recovery is to look at that state. A dead 409 retires for free
where a narrowed 400 breaks clients.
Two headers claimed all three legs share the store body — every clause false,
one citing the contract header as agreeing when it says the opposite — and the
plan file gave a placement reason that is MetadataCAS's, not this role's. The
end-gate claim in ADDING_AN_ISSUEOPS_ROLE.md is narrowed to the true thing: the
two LEAF checks are shared, the orchestration around them forks.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Give the scheduling-edge set one definition, in types
Four packages walked {blocks, conditional-blocks, parent-child} under four
names — isSchedulingEdge, isSchedulingDep, isSchedulingDependency, and the
isApplySchedulingEdge this branch added as the fourth. Adding a fifth
scheduling type was four edits with nothing to catch a missed one.
It goes in internal/types rather than the issueops leaf the review named,
because internal/storage/issueops imports internal/storage/domain, so domain
cannot import back and two of the four copies would have survived there. Beside
the Dep* constants themselves, every walker reaches it: nine call sites, one
definition, one edit for a fifth type.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Add issueops.MetadataCAS: compare-and-set over one metadata key
The one coordination primitive missing at every layer. Everything the
metadata plane holds is written through Lifecycle.Update, which has no way
to say "only if", so every caller that needs a guarded write composes a
transaction, a read and an update by hand — and each one has to get the
composition right. Gas City emulates it client-side with RunInTransaction +
GetIssue + UpdateIssue for exactly that reason, and the comment it left
behind names the gap: "the upstream storage layer exposes no
conditional-UPDATE ... WHERE primitive".
The role is a state transition stated as a pair. Expected is the key's value
before, Value is its value after, and nil on either side means the key is
ABSENT there: a conditional create is (nil -> value), a conditional delete
is (value -> nil), and a caller that can take a lease can return it to the
state its own acquire tests for. Equality is canonical, so a caller cannot
lose a swap to its own formatter; numbers compare as their source literal,
because decoding through float64 equates two int64s past 2^53 and that is
the silent false match a compare-and-set exists to prevent.
A MISMATCH IS AN ANSWER, not an error: Swapped false, Current carrying the
value that refused it, nil error. That is the one place this diverges from
PROPOSAL-cas-conditional-update.md, which specifies a typed error and a loud
non-zero exit for the assignee/status guards. Its argument is a CLI one — a
swallowed refusal in a shell script is the bug class it was written for —
and a non-zero exit is the front door's enforcement, which the HTTP handler
here still owes and pays. The role's designed caller is a retry loop, for
which a lost race is the ordinary path, and an error cannot hand back
Current without a bespoke type every caller must errors.As before it can
read the one field it needs.
All three legs share one body (internal/storage/issueops), so this is one
reading plus two wrapper checks rather than three backends agreeing. The
wrapper check earned its keep: the unit-of-work leg rolled an ephemeral swap
back, because the shared body reported "no durable tables changed" and that
leg's commit message is what commits the SQL transaction as well as what
versions it. MetadataCASWrite now carries the two facts separately.
The HTTP half lands with the role per the 2026-08-05 scope decision:
POST /v0/beads/issues/{id}:casMetadata, spec first. A lost race is a 200
carrying swapped:false, so the operation has no conflict code; an omitted
`expected`/`value` member means absent and a member holding null is a value,
which is why the handler reads raw members.
No bd command yet: the primary consumer is an embedder, and a CLI front door
is additive. No .golangci.yml entry, for the reason memoryops gives — the
body is an …InTx function no front door can reach.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Review: read Current from the row, and let a client read a present null
Two shape fixes, both of which would have been expensive to change after
anyone depended on them.
A *json.RawMessage wire member cannot READ a present null: encoding/json
nils the pointer before UnmarshalJSON runs, so a generated client decoding
{"swapped":false,"current":null} gets the same value it gets for an omitted
member — and on this operation those mean opposite things. A retry loop
against a null-valued key would read "absent", swap with expected omitted,
mismatch, and livelock on a stream of 200s. x-go-type-skip-optional-pointer
makes the member a bare json.RawMessage, which is an Unmarshaler and
receives the literal; the wire is unchanged in both directions, which is
exactly why nothing else catches the regression, so the decode is now
pinned. nullable: true beside it, for the validating gateway in front of
somebody's server.
The number rule was defended in three places as protecting int64s past 2^53
from a float64 round-trip. It protects nothing: the metadata column decodes
through float64 itself — measured, 9007199254740993 stores as ...992, 1.0 as
1, -0.0 as 0, 1e300 as three hundred and one digits. The false justification
is gone from all three sites and replaced with what the probe actually
showed, plus the guidance it implies: compose an Expected from a previous
Current, and prefer a string for a coordination token.
That guidance was not true yet, because Current was the REQUEST's bytes
rather than the row's — so "what you get is what a later read sees" was
false, and a loop feeding Current back compared its own spelling against the
substrate's forever. Current is now re-read inside the deciding transaction
on every path. One extra SELECT, one statable invariant.
Three contract cases, each watched to fail: Current is the column's bytes
and a Current-driven loop converges (mutant: answer from the plan);
the history entry names the request's actor, counted per actor because
created_at is second-granularity and an ORDER BY decided this case on a coin
toss when it was first written (mutant: stamp a constant); a wisp swap
writes no durable event row, which two layers had been holding by
coincidence with nothing asserting either.
Also: the serializer-omits-null footgun in the spec (an absent `value` is a
DELETE, and Jackson/Pydantic/omitempty all omit nulls by default),
canonicalizeForContract's own float64 blind spot named in the coverage
paragraph, and the leaf now says corrupt stored metadata is an untyped error
— a 500 — because the request was well formed and the issue exists.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Close the three capability holes CI found, and one my sweep could not
All three are the same shape: a surface that loses the new role silently,
and none of them is reachable from the package tests I ran locally.
internal/storage/uow's notifying wrapper is the important one. Its
recordingIssueUC inherited CompareAndSetMetadataKey from the embedded use
case, so a swap through a notifying unit of work recorded nothing and the
hook the DoltStorage chain fires for the same write was lost. Its
notifyingProvider did not answer MetadataCAS at all, so a caller's type
assertion simply stopped matching and the wrapper dropped the capability
along with its hooks. Both are now declared, and the recorder reads the
use case's own "a row write landed" rather than inferring it from the
request — which is strictly better than what the hook decorator can do, and
snapshots anyPlane because this role resolves a wisp id itself.
cmd/bd's serveIdentityStore is the second stub store to nil-panic on the
promoted accessor, after serveRolesStore in the same commit. And
serve_proxied_integration_test.go carries a SECOND hardcoded capabilities
golden, whose own comment says two literals that must match are one literal
— it was right, and it was still missed.
My local sweep ran the metadata-cas contract on all three legs but not the
whole internal/storage/uow package, which takes nine minutes; that is where
the parity guards live. Ran it whole this time.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: name the step with no number — the surfaces that EMBED
A new accessor arrives on every embedder promoted rather than declared, so
the build stays green and the first symptom is a nil dereference in somebody
else's stub. Four such places caught this role after its own slice was
green: RoleFiresHooks, both halves of uow's notifying wrapper, and two
cmd/bd stub stores. Grep for the embed, not for the interface — and run
internal/storage/uow whole, because the parity guards live there and the
package takes nine minutes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
GET /v0/beads/events:watch holds a text/event-stream response open and emits
each committed mutation as it lands, so a consumer learns about a write when it
happens instead of on its next interval. It is a SIBLING of the paged read, not
a mode of it: `follow=true` would have given one operationId two media types,
two lifetimes, two limit rules and two capacity stories, and a client generated
from the document could not have described either.
THE CURSOR IS STILL THE CONTRACT, which is what makes this cheap to publish.
The server keeps no per-consumer state and remembers no subscription; a stream
is the `since` reads a poller would have performed, performed on its behalf
against the same ReadEventsJournalPage through the same read-only cursor. Every
event carries `id: <seq>`, so the checkpoint a client holds while streaming is
the number it would have held while polling, and `Last-Event-ID` — the header a
browser's EventSource resends by itself — takes exactly the value `since` takes.
That header WINS over the parameter, because the client that sends it did not
choose to: an EventSource reconnects to the URL it was built with, so honoring
`since` there would replay every record since the consumer started, on every
reconnect, forever. A nonempty unparseable one is a 400 naming the header rather
than a silent fallback, which would start a stream somewhere the client did not
ask for and never tell it; an EMPTY one means "no id yet" and defers to `since`,
because a client that always sets the header sends it empty on its first
connect and refusing that would break the request the header exists to serve.
Delivery is at-least-once against the client's own checkpoint: exactly once and
in order within a stream, duplicates only across a reconnect. No engine or
storage change — this consumes the poll read path.
EVERY REFUSAL IS DECIDED BEFORE THE FIRST BYTE — validation, the disabled 409,
the flush check, the stream cap, and then the first read, which is what turns a
pruned-past cursor into the paged read's own 410 rather than a 200 that
immediately reports its own failure. Exactly one failure can arrive after the
status is spent: a prune racing an open stream, emitted as a NAMED `truncated`
event carrying the 410's own body in the same encoding on one line (asserted
against Write's output, not merely agreeing with it), behind a raised `retry`
and followed by a close. Naming only the exception is what lets a bare
`onmessage` consumer treat an unrecognized event as "stop, this is not a
record"; one that ignores it does not lose records silently, it stalls loudly on
connect-time 410s, slowly. The other unreportable failure — a stored payload
that will not encode — ends the stream too, and names its seq in the log,
because it will end every stream that reaches that row and nothing else would
say which one it is.
THREE LIMITS HAD TO MOVE, and the middle one is the trap.
- requestDeadline (60s) does not apply to a streaming row. For every other
operation it is the backstop against a request holding resources forever;
here it would do nothing but sever the stream. Each READ carries a 15s
deadline instead — a liveness budget rather than a database one, since it
also bounds how long a stream can go without a heartbeat and how long it can
ignore a shutdown.
- http.Server.ReadTimeout (30s) had to be cleared per request, BEFORE the
connect read. There is no WriteTimeout on this server — statusWriter rolls a
deadline forward before every write, which bounds one stalled write rather
than a stream, and needs nothing here — but ReadTimeout is a deadline on the
WHOLE request, and net/http keeps a background read running while a handler
writes: the read that notices a disconnect. Its expiry cancels the request
context, so an idle stream would end itself at thirty seconds with no client
involved, and a database wedged during the connect read would be booked as
`client_closed`. Clearing it costs no disconnect detection — a client that
leaves still produces a read error — and a peer that vanishes without a FIN
is reaped by TCP keepalive, which Go's listener enables by default
(measured: 15s idle, 15s interval, 9 probes; ~150s).
- The database slot moves from the request to the read. Sixteen slots and
forty-eight stream places means one slot per open stream would let a handful
of idle consumers starve every other operation for hours with /healthz
green; a stream now takes a slot for the moment of each poll and gives it
back, and slot pressure delays a pass instead of ending a stream.
Streams are capped at 48, SIXTEEN BELOW the 64-connection limit, and the gap is
load-bearing arithmetic rather than caution: LimitListener returns a connection
slot only when the connection closes, which is after the handler returned and
after this counter came down, so a cap at maxConns could never be observed — the
connect that should earn the 503 would never be accepted, and neither would the
poll it is told to fall back to, nor a mutation, nor a fresh-connection
/healthz. The headroom makes the refusal deliverable; `events_watch_admitted`
carries the live gauge on every connect so accumulation is visible before the
cliff. Each stream jitters its own poll phase by ±10%, because consumers
reconnect together after a restart on one shared `retry` and a fixed interval
would march them into a single read burst per second forever. And a graceful
shutdown signals its streams (RegisterOnShutdown) rather than waiting them out;
the loop consults that signal and the client on EVERY pass, including the
draining ones, so a week-old backlog stays cancellable within one batch.
Tests: handler-level over live delivery (mutations land AFTER the connect),
id=seq, heartbeats, Last-Event-ID precedence including a stale header against a
live `since` and the empty-header polarity, the 400/409/410 connect legs, a
prune under an open stream, the cap and its 503, the cap's headroom against
maxConns, backlog drains cancelled by both a hangup and a shutdown, slot release
on every exit, a stream sharing a single-slot semaphore with a paged read, the
flusher refusal, the read-deadline clear and its ordering against the connect
read, jitter spread, and a clean drain with a stream open — all under -race.
Framing is pinned against a record whose payload carries literal newlines, a CR
and a `data:` line of its own. Two e2e legs through a real `bd serve`: mutate on
one connection while streaming on another under a 10s arrival bound, then
reconnect with Last-Event-ID and require the resume, plus the disabled refusal.
Mutated and each caught: the mid-stream truncated event, Last-Event-ID
precedence, the empty-header polarity, the cap decrement, the cap's headroom,
the drain-cancel fast path, the read-deadline clear and its ordering, the poll
jitter, the shutdown exit, and the deadline exemption.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
GET /v0/beads/events pages the durable mutation journal from a caller-held
checkpoint, so a hosted consumer stops shelling out to `bd events tail`. The
journal and its retention contract already landed; this is the consumption
surface for them.
THE RECORDS ARE THE CLI'S RECORDS, and that is a machine fact rather than a
promise. The envelope and its projection moved out of cmd/bd into
internal/eventsjournal, beside the activation and auto-prune logic that already
had to be reachable from two binaries; the spec pins EventRecord to that struct
with x-go-type, pinning.go proves the generator emitted an alias, and the
committed golden fixture now renders through the same function the handler
serves from. A second wire struct in internal/httpapi would have passed its own
tests while quietly shipping a different `ts` shape or a `dep` that appeared
when empty, and the consumer who notices is the one reconciling an HTTP mirror
against a CLI export.
THREE ANSWERS THE DATA CANNOT TELL APART, which is most of the design:
- CAUGHT UP is a 200 with an empty list. "Nothing new yet" is an ordinary
answer about a log, and a poller whose steady state was a 404 would have to
treat this surface's miss vocabulary as its happy path.
- DISABLED is a 409 `events_journal_disabled`. A journal that is off reads as
zero rows and a head of zero — byte-identical to an enabled journal nothing
has written yet — so without this gate a consumer would poll a workspace
that will never emit a record and call itself caught up forever. Activation
is workspace state, so it is resolved by cmd/bd (eventsjournal.EnabledFor)
and handed in; this package resolves no workspace state of its own. A 409
for CodeNotClosable's reason: a statement about state the client cannot see,
which the same request stops earning once an operator changes it.
- PRUNED PAST is a 410 `events_journal_truncated` carrying `since`, `floor`
and `head`. It is the surface's only 410 and it is the right one: those
records existed, were addressable by exactly this request, and were
deliberately deleted — retrying the same `since` can never succeed, which is
what a 404 would wrongly invite. The mapping lives in ClassifyError, keyed
on the typed error with errors.As, so neither database source can forget it;
the code is storage's own constant, so the CLI's `--json` failure and this
body cannot drift to two spellings of one condition.
`head` is why the read seam grew. ReadEventsJournal answers what came next and
cannot answer "keep asking, or wait?", so ReadEventsPageInTx returns the rows
and the counter head from ONE transaction, read in that order — a head taken
first could land below the last row served, which a consumer reads as "past the
end" and stalls on. `bd events tail --follow` keeps the cheaper path: it runs
the truncation decision every second and pays for a head read only in the
ambiguous cases.
The handler holds storage.EventsJournalCursor, a read-only interface, not the
wider accessor the CLI takes. There is no prune, no acknowledge and no
truncate over HTTP: retention stays a workspace decision, and a surface
documented to publish the journal should not be one line from a delete.
EventsJournal is the first CONDITIONAL role on httpapi.Config — required
exactly when the workspace's journal is enabled. A storage backend with no
journal seam is an ordinary backend as long as nobody asked it to record
anything (eventsjournal.Apply takes the same deal at open time), and demanding
it unconditionally refused to start two registered-backend servers that had no
use for it.
`limit` runs 1..10000 defaulting to 1000, and `0` is REFUSED rather than
meaning unlimited as it does on the issue listings: a caller resuming from an
old checkpoint would otherwise ask one process to buffer the whole retained
window. `since` is required — defaulting a missing checkpoint to zero serves
the entire window to a consumer that meant to resume, which arrives as a flood
of duplicates rather than as an error.
Tests: handler-level over both refusals, the caught-up/empty/disabled trio, the
limit bounds and an int64 checkpoint; a storage-level head guard against the
real embedded store; and three end-to-end legs through a real `bd serve` —
mutate over HTTP then read the journal back gapless, prune and meet the 410 then
recover from floor-1, and a disabled workspace refusing. The truncation mapping,
the disabled gate, the window members and the limit ceiling were each mutated
and each failed a test.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
Completes the graph write side: a batch of edges asserted as ONE
transaction, or none of them, over issueops.DependencyEditor.
All-or-nothing is the role's shape rather than a policy choice here.
Edges asserted together describe a graph, and half a graph is a graph
nobody asked for — the cycle a caller was refused for is exactly the
state a partial commit would leave behind. That is batchCreateIssues'
posture (fix the payload, resend unchanged), not BatchCloser's
keep-the-survivors one, and it is proved where a fake role cannot prove
it: a batch whose later edge closes a cycle is read back through a real
`bd serve` against real Dolt and leaves zero edges.
Two frozen codes, both 409, both statements about state the client
cannot see without reading it — the claim's not_claimable situation, so
the claim's answer:
dependency_cycle covers BOTH never-makes-progress refusals, the plain
scheduling cycle and the blocking edge against the issue's own
ancestor or descendant. One code because they have one client
recovery and no force bypass, and codes are the vocabulary of
recovery. The typed distinction is not lost: the hierarchy refusal
additionally carries issue_id, blocker_id and blocker_is_ancestor,
read from *DependencyHierarchyConflictError inside the refusing
transaction, and member PRESENCE is the discriminator. The three are
enough to rebuild the typed error whole, both polarities included,
which is why the boolean travels through a pointer and is emitted
when false. Nothing can recover them after the fact — the conflicting
hierarchy may exist only inside the batch that was rolled back.
dependency_exists is a pair carrying another type, with
existing_type and requested_type from
*DependencyTypeConflictError's fields.
The endpoint refusals PR #5415 typed are mapped to their 400 and named
by finding the refused edge in the request by BOTH endpoints, which is
what DependencyEndpointNotFoundError carries the whole edge for. A
target may legitimately be an `external:` reference or another
repository's id, so only a locally-visible absence refuses; the proxied
test pins both sides of that line.
A self-dependency is refused at the wire edge as a value, not a
conflict: it is invalid whatever the graph holds, and answering it here
is what lets the refusal name the offending edge.
SkipPerEdgeCycleCheck stays unpublished — an unauthenticated surface is
where a default must be the guarded one.
Co-Authored-By: Claude Fable <noreply@anthropic.com>
The dependency graph has been read-only over HTTP: a client could list
edges, walk the tree and find cycles, but had to fork `bd dep remove` to
unwire one. This adds the first graph WRITE, a thin adapter over
issueops.DependencyEditor.remove.
POST /v0/beads/dependencies:remove is a collection-level custom method
rather than a DELETE. An edge is named by TWO endpoints, so there is no
single-segment resource path for a DELETE to mean, and a DELETE carrying
a body is the shape proxies mangle; the forgetMemory precedent cuts the
other way because that one names a single resource and carries no body.
The operation is idempotent and its code set has NO 404, deliberately.
An edge that is not there is `removed: false` inside a 200, and an
endpoint id that names nothing holds no edge either, so this operation
probes no id's existence and has nothing it could report a miss on. An
agent replaying its own teardown must not have to classify an error to
discover it already ran.
The role reaches the server the way every other one does: a required
Config field, an accessor built OVER the timing wrapper on the provider
path, and a serveIssueRoles binding off the peeled store. That peel is
load-bearing here — HookFiringStore.DependencyEditor recurses and fires
the workspace's update hook per edited source — so RoleFiresHooks learns
the type, and Listen refuses a hook-firing editor rather than trusting
the comment that says not to pass one.
TestServeIssueRolesComeFromBeneathTheHookDecorator grows the editor the
way it already carries the reader and the claimer: an identifiable value
per layer, a precondition that the decorator's own accessor answers
RoleFiresHooks true, and a post-peel assertion that the role is the
middle store's own. Without the precondition the peel assertion would
pass on a predicate that answers false for everything, which is what
holds the new RoleFiresHooks case in place — a comment cannot.
The actor decode was the third copy of the same eighteen lines, so it is
now one shared requiredActorMember and the claim and batch-create paths
call it.
Co-Authored-By: Claude Fable <noreply@anthropic.com>
Adds PATCH /v0/beads/issues/{id}, the last operation in the write-lifecycle
tranche and the one with the widest body vocabulary.
A PLAIN METHOD, not a custom one, by the memories precedent: partial update of
one named resource is what PATCH already means, exactly as one named resource
with no body is what DELETE means for forgetMemory. It registers directly, keeps
pattern == specPath, and leaves the custom-method namespace for operations that
are not CRUD. The claim-route commentary calling the issue-detail path
"GET-only" is updated in the same change.
MEMBER PRESENCE IS THE SIGNAL, and that is why the body is decoded as raw
members: a member present sets the role's Field, a member absent leaves the
field untouched, and the generated struct cannot tell those apart because it
models both as a nil pointer. Explicit null is a third state read off the raw
bytes — a clear on the four nullable members, which are exactly the ones the
role models as Field[*T], and a 400 naming the member everywhere else. Without
that pre-check a `"title": null` would unmarshal to nil and slide through as
"untouched": a write the client asked for and the server silently dropped.
status, assignee and metadata are excluded and refused BY NAME. Keeping them
out is half the reason this operation documents no 409 at all — they are
exactly where close policy, the claim fence and the metadata algebra would have
entered its code set. parent_id, persistence, owner, closed_by_session, spec_id
and await_id are absent for the reasons the spec enumerates; each is additive
to publish later.
The role's ErrValidation maps to 400 in a failUpdate sibling of
failBatchCreate, with the same no-role-prose rule. Its ErrNotFound branch runs
first and is the divergence: this operation DOES address a resource by path, so
an id naming nothing is a genuine 404 rather than a statement about the body.
Two new spec gates. TestUpdateRequestMembersMatchTheHandler covers both levels
of the body, where a hand-rolled accepted set could otherwise drift from the
document with every other gate green. TestNullablePatchMembersAreExactlyThe
DocumentsNullableOnes pins the clear-vs-refuse set from both sides, because
drift there is silent in the worst direction: an unannounced clear on a field
nobody agreed could be cleared.
The PATCH wildcard also matches segments that look like custom methods, since
`{id}` matches any whole segment. That is the detail path's long-standing
behavior — GET has always answered the same way — and it resolves as an update
of an issue whose id is literally "bd-1:close", which no row holds.
TestPatchOnACustomMethodSegmentIsNeverTheCustomMethod pins the property that
matters: a PATCH never executes as a lifecycle verb.
Retained real-dependency proof: TestProxiedServerServeUpdate, against real
Dolt — one issue carrying a set member, a null-cleared member and an untouched
member, all read back after the PATCH; changed:false on a same-value resend;
label replacement removing an omitted label; and the workspace-vocabulary
refusal arriving as the documented 400 rather than a 500.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Adds POST /v0/beads/issues/{id}:reopen, the close's mirror. It completes the
lifecycle pair, so a recovery flow — close, discover the fix regressed, reopen,
reclaim — works end to end over this surface instead of dropping back to a
subprocess at the second step.
Near-trivial on the dispatcher the close built: a third row on the shared
wildcard is a row. That is the whole reason the delivery order puts it here.
No new codes, and the ABSENCE of a 409 is the operation's one design
statement. Close has a policy guard — open children, a live blocker — because
it moves an issue INTO the done category. Reopen moves it out, so there is no
state of the graph that can refuse it and nothing to name.
TestReopenPublishesNoConflictCode asserts that as an invariant rather than
leaving it as the current shape of a table, so a future guard has to land its
code deliberately.
`already_open` is `!result.Changed`, mirroring already_closed and
already_claimed: a reopen of a non-done issue changes nothing and succeeds,
because an agent replaying its own recovery should not have to classify an
error to learn it already ran.
The reason is recorded on the `reopened` EVENT rather than on a field of the
issue — the role's own contract — and the response deliberately does not carry
it, so a client reads it back from the place it actually lives.
The handler names the history entry (ReopenRequest.Provenance) instead of
taking the role's default. The implementations disagree about that default:
the store-backed ones write "bd: reopen issue" and the unit-of-work one
"reopen issue", so a workspace served by one backend today and another
tomorrow would grow two spellings of one event.
Retained real-dependency proof: TestProxiedServerServeClose grows the
close→reopen round trip against real Dolt — close_reason and
closed_by_session cleared, the reopen reason read back off the issue's event
stream via `bd history --events`, and the issue claimable again — plus the
idempotent reopen of an issue that was never done.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Adds POST /v0/beads/issues/{id}:close, the half of the agent loop — claim,
work, close — that still forced an automation client back to forking a `bd`
subprocess.
The routing change is the substantive one. `{id}:close` is not expressible as
a ServeMux pattern for the same reason `{id}:claim` is not, and unlike the
claim it COLLIDES: two rows cannot each register POST
/v0/beads/issues/{idop}. The route table grows a `customMethod` field; rows
carrying one share a single registration behind a dispatcher that splits the
trailing suffix off the matched segment and hands the request to the row that
claims it. A segment ending in no registered suffix gets the same 404 the
catch-all gives any unrouted path, so the wide pattern stays a routing detail
rather than undocumented surface — and the split happens before s.route, so an
unrouted suffix takes no database slot and books no operation on the request
line.
TestSpecRouteParity is untouched in mechanism: each row still declares its own
specPath and the test still compares document paths.
TestClaimNarrowsThePOSTSurface generalizes to
TestCustomMethodsNarrowThePOSTSurface, which is where a dispatcher that fell
back to its first row would be caught — that failure would otherwise leave the
claim's happy path green.
`not_closable` (409) joins the frozen vocabulary with `open_children` as an
optional Problem extension member. Both close-policy refusals share the code;
the member is attached only for the open-children one, from
*CloseOpenChildrenError's own field inside the refusing transaction, so member
PRESENCE is the discriminator and no client parses "3 open child issue(s)" out
of prose. `already_closed` mirrors `already_claimed` for the idempotent
re-close, which under first-close-wins rewrites neither reason nor session.
The lifecycle role joins Config's store-shaped source, and RoleFiresHooks
learns about *hookIssueOperations: a store's own IssueLifecycle() returns a
role that fires on_create, on_update and the close hooks for every mutation it
lands, which is precisely the value this server documents it does not run.
Without that case bd serve would have booted with hooks live on four verbs.
Retained real-dependency proof: TestProxiedServerServeClose, against real
Dolt — first-close-wins read back through a second close (reason and session
unchanged), and a forced close over two real open children with the count
read back from the 409. The role-level transition is already owned by
internal/storage/uow/lifecycle_close_reopen_contract_test.go, which this
cites rather than duplicates.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The memory commands get the treatment the sixteen issue commands got in #5378:
a role interface in a leaf package, conformance-tested at all three backends,
with the CLI routes and the HTTP handlers as thin callers over one
implementation.
memoryops is its own namespace rather than an addition to issueops. The two
planes share a config table and nothing else; a memory whose key shadows a
settings name is still a memory, and that separation is now the role's,
pinned by its contract, rather than a filter each caller reapplies.
Closes an unauthenticated disclosure found on the way: memory content was
served in cleartext on GET /v0/beads/config, and reachable through two more
doors — `bd config show` and `bd info --json`, the latter republished into
agent transcripts by MCP get_schema_info. Enumeration is now filtered at the
shared seam (workapi.FilterSettingsEnumeration); `bd config show` is left
alone deliberately, since an operator asks for it by name.
Two wire contracts were settled after the review council, recorded in full on
the PR: the search parameter is spelled `search` rather than `q`, because
issues:query already publishes `q` as a boolean expression and one surface
must not spell two questions one name; and getMemory keeps its 404, because
the status reports the distinction the front door already reports and
`bd recall` exits 1 on a miss where `bd config get` exits 0.
Ten agents over 216 files, one directory-balanced group each, working to a
rubric that named what to cut (duplication narration, restatement of the next
line, the governing rule echoed in every command file, throat-clearing) and
what to keep (traps, invariants, security, tracker ids, behaviour changes, and
the "why a naive simplification destroys this assertion" rationale).
Net 1,523 lines. Density against this repo's own per-directory norm on main:
cmd/bd 33.6% -> 27.3% (main 10.7%)
internal/storage 26.1% -> 23.1% (main 14.1%)
backend/conformance 34.0% -> 29.6% (main 22.8%)
internal/httpapi 30.9% -> 27.8% (main 30.6%, now below)
overall 34.7% -> 31.6%
Every agent landed at 18-25% rather than the 30% asked for, and every one gave
the same reason independently: what remained was on the keep list. Ten separate
judgements agreeing is the most useful result here — the prose is dense, but it
is mostly load-bearing, and the shortfall is the honest answer rather than a
failure to try.
TWO REVERTS, both to protect something worth more than the lines.
issueops/ is back to its pre-trim state, giving up 610 lines. The conformance
contracts cite the leaf docs BY LINE — "pins treewalker.go:52-66" — 155 times.
Trimming the cited files silently repointed those at whatever text moved into
those numbers, across agent boundaries so no agent could see it. A semantic
remapper recovered 141 of them, but 23 needed judgement and several landed on
struct fields. The leaf docs are the spec the contracts are written against;
they are the one place in this change where dense prose IS the deliverable, and
keeping them stable is worth more than the 610 lines. tree_walker_contract.go
and version_reconciler_contract.go went back for the same reason: an agent had
deleted a paragraph containing a citation, so positional restoration could not
align them.
After the reverts, exactly 5 citations point into a still-trimmed file and 2 of
those are weak — both in cmd/bd/config_guard_test.go, which this series never
touched and whose citations were already wrong on main (init.go:361 pointed at
a closing brace; the guard it names is at init.go:1499).
VERIFICATION. A guard strips every comment and all whitespace from each of the
193 modified files at HEAD and in the worktree and requires the two to be
byte-identical, so a code change cannot hide in a comment diff. It handles `//`
inside string and raw-string literals, and was tested against a deliberate code
change before being trusted. gofmt clean, go build, go vet, golangci-lint 0
issues, and the two AST-based tests that PARSE trimmed files — the timed
provider binding pin over claim.go and the serve database-source gate over
serve.go — both pass.
One real defect found while trimming: checkDatabaseSource's doc block ran into
`// sourceRoles is ...` with no blank line, so godoc attached thirty-one lines
of the wrong prose to func sourceRoles and left checkDatabaseSource
undocumented. Fixed by separating them.
`bd dep tree` had two implementations of one walk. The direct route resolved a
partial id, opened a prefix-routed store and called store.GetDependencyTree; the
proxied route took the id verbatim, opened a unit of work and called the use
case. Each then carried its own copy of the `both`-direction merge, the status
prune, the mermaid and human rendering and the empty-tree wording. The copies
agreed, which is the only reason nobody noticed that a `both` walk was two
independent reads with nothing spanning them. Both now build one
issueops.WalkTreeRequest and ask for the role.
THE ROLE, and both its neighbours said in advance why it had to be one.
Relations and EdgeReader each exclude the tree in the same words -- "a recursive
walk has a depth, a cycle policy and a node shape of its own" -- and all three
are on this contract: MaxDepth, the first-visit rule, TreeNode. It is not
CycleDetector either: a cycle has NO anchor and a tree is nothing but its
anchor, and the two disagree about what an edge is -- this walk follows every
type except `relates-to`, the cycle report follows `blocks` and
`conditional-blocks` only -- so one workspace can honestly have no cycles and a
tree that revisits a node.
ONE BODY, THREE LEGS, AND THAT IS ONE VOTE. Unlike every other role in
backend/conformance, all three implementations reach the same function: the two
stores wrap issueops.WalkDependencyTreeInTx in five lines around their own
transaction and the unit of work reaches it through a new domain repository
method. So TestTreeWalkerContract x 3 is one reading of the walk plus an engine
check, not three backends agreeing, and the contract file says so at the top.
What the legs still buy is the WRAPPERS, which is where every measured drift in
this graph family has actually lived -- so the refusals assert SENTINELS rather
than message text and the cap case asserts the typed error's fields. The parts
that decide what the answer MEANS are pure (ValidateWalkTreeRequest,
PruneTreeByStatus, MergeBidirectionalTree) and are pinned without a database.
TWO USER-VISIBLE CHANGES ON THE PROXIED ROUTE, both in the owner's Q11 set, both
in CHANGELOG.md.
PARTIAL IDS RESOLVE. `bd dep tree a1b2` worked on a direct workspace and
failed on a team server, because this route passed the argument to storage
verbatim. It resolves in its own short-lived read unit of work before the role
is asked for anything, so a lookup that finds nothing reports the lookup
failure rather than a provider that cannot offer a surface.
--max-rows IS HONORED. It used to be refused outright ("not supported in
proxied-server mode") because the unit-of-work path threaded no cap. The cap
is on the role's request now, so the shared body enforces it for all three
backends and the flag means the same thing wherever the command runs. It is
still POST-HOC -- a tree walk has no query filter to thread a cap through --
and both the leaf doc and --help say so. The shared --max-rows help text
forked for this (addRoutedMaxRowsFlag): the proxied-server refusal is still
true for the eight other commands that take the flag.
A DEFECT FIX NOT ON THAT LIST, recorded as AMBIGUITIES.md A-twk-1: a `both` walk
now sees ONE database state on every route, where it used to be two
unsynchronised reads that could show half an edit.
Q7 IS OBEYED. --show-all-paths stays a no-op -- accepted, ignored, and now
DOCUMENTED as ignored -- and TreeNode.Truncated stays always-false for the same
reason. The one-visit rule that makes both dead is now a stated promise
(TreeResult.Nodes) and a conformance case (RendersASharedSubtreeOnce), so
implementing either as a side effect of a later refactor fails a test instead of
shipping.
CONFORMANCE. backend/conformance/tree_walker_contract.go holds fifteen cases
citing the leaf doc by line, run at all three implementations with ZERO parks:
45 subtests green. Seeding a cycle takes raw SQL for the reason the
cycle-detector contract records -- no supported write creates one -- so that one
case uses the fixture's Exec hook.
HTTP. GET /v0/beads/dependencies/tree, spec first and the types generated
against it. TreeNode is x-go-type-pinned to internal/types, so `bd dep tree
--json` and the response body are one compatibility domain, and
DependencyTreePage's Items are pinned in pinning.go -- the trap wave 2 fell into
with DependencyEdges (bd-5o3gt), not repeated here. A root that names nothing is
a 404, which is the difference from GET /v0/beads/dependencies: one anchor
leaves no other answer to preserve. No max_rows on the wire; the cap is a CLI
circuit breaker. `capabilities` gains dependencies.tree, and TreeWalker becomes
a required field of the store-shaped httpapi.Config, which costs the in-tree
tests a line each and no shipped caller anything (bd serve builds a provider).
NOT TOUCHED: the legacy DetectCycles seam bd-5g4f2 is about. This walk reads
GetDependencyTreeInTx and never AppendBlockingGraphInTx, so the two-cycle-answers
problem is exactly where it was.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check green;
TestTreeWalkerContract 15/15 at dolt, embeddeddolt and uow; internal/httpapi 0
failures including the eight new tree-route cases; the pure tree_walk tests
green; TestEmbeddedMaxRowsNonListPaths green (DepTreeMaxRows still exits 2);
BEADS_TEST_PROXIED_SERVER=1 TestProxiedServerDep2 green including the four new
Tree cases; TestProxiedLookup* green; TestCorpusGolden green.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
THE TWO ROUTES DISAGREED ABOUT WHAT --force MEANS on a destructive command.
On a local database `--force` deletes the named beads and orphans their
dependents; on a team server it deleted the whole dependent subtree, `--cascade`
was REFUSED outright ("not supported in proxied-server mode (delete always
cascades)") and Cascade was hardcoded true at both call sites. So there was no
way to delete one bead on a team server without taking everything under it, and
asking for the safer behaviour was an error.
Q1 ANSWERED IN THE ROLE. issueops.Deleter has one method, reached through
store.Deleter() and the provider's own accessor, and the three modes are request
fields: no flags refuses over a dependent the request did not name, Force
orphans it, Cascade deletes the closure. The guard is workapi's and the body's,
below every front door, for the reason Sweeper's require-a-filter gate is: a
second front door that inherited the capability without the guard would orphan a
workspace's graph by omission — which is exactly what this commit's HTTP
operation would otherwise have been.
IT IS A DIFFERENT ROLE FROM Sweeper, not a mode of it. Sweeper erases a set the
caller DESCRIBED; this erases rows the caller NAMED. That is what decides where
each one's safety lives: a description can be accidentally too wide, so Sweeper
carries a require-a-filter refusal; a list of ids cannot be, so this one's guard
is about the graph.
THE DEFECT. The direct route's batch path deleted the rows in one transaction
and then rewrote `[deleted:ID]` into the neighbours' text afterwards, discarding
every update error. A failure in the window left a workspace whose beads were
gone and whose descriptions still cited them by id. The existence probe, the
guard, the cascade expansion, the deletion and the rewrite are now one
transaction. WHAT THAT COSTS is written into the leaf beside the promise: the
transaction is as large as the deletion plus its neighbourhood, so a batch with
a very large neighbourhood fails whole. It is NOT Sweeper's trade (bd-hysee) —
the delete itself was already one transaction on every route — and the part that
is new is named rather than measured, which is recorded for sign-off.
TWO MORE DEFECTS the single call site removed. The one-id path held its own
transaction that removed each edge by hand, so it never reported labels, events
or orphans; and `domain.DeleteIssuesParams.EnforceCascadePolicy` and `.Force`
were declared, documented in fifteen lines describing exactly these three modes,
and READ BY NOTHING. They are deleted; the policy lives in the role now.
THE CONTRACT IS WHAT WAS DELETED, not what was reported.
backend/conformance/deleter_contract.go holds eleven cases, each citing the leaf
doc, run at all three backends with ZERO PARKS and zero divergences. Every case
that acts asserts row counts through QueryScalar rather than trusting the result
the delete reported about itself. They are TWO INDEPENDENT BODIES plus an engine
check: dolt and embeddeddolt share internal/storage/issueops.DeleteInTx and
differ only in how they reach a transaction, and the unit-of-work provider
reaches the same questions through the domain use cases. It does NOT duplicate
backend/conformance/audit_issue-lifecycle.go, which stays the right home for
`DeleteIssues` at the STORAGE seam: that suite's Factory hands back a bare
storage.DoltStorage, so the unit-of-work backend — where the guard did not exist
at all before this commit — can never run a case placed there.
`bd serve` gains POST /v0/beads/issues:delete, spec first. The dependents guard,
the all-or-nothing id resolution and the reference rewrite are the role's, so
the handler is argument validation and a projection. `cascade` and `force`
default false, which is the guarded mode; DeleteIssuesResult is not
x-go-type-pinned for the reason SweepResult is not, and a reflection test keeps
the projection honest. No page envelope, so nothing to pin in pinning.go.
USER-VISIBLE, and the CHANGELOG says so loudly: a team-server script relying on
the implicit cascade starts leaving orphans; `bd delete <one-id>` without
--force now refuses over an outside dependent, converging the direct route's
three paths onto the answer two of them already gave; the proxied `--json`
result gains `orphaned_issues`. Reasoning and the alternatives are in
/data/tmp/sd-server/AMBIGUITIES.md as A-del-1..6.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
(regenerate-and-diff plus the httpapi suite) green; TestDeleterContract 11/11 at
dolt, embeddeddolt and uow; the internal/workapi delete unit tests; the
internal/storage, internal/telemetry and root layering pins;
TestConformance/Audit/issue-lifecycle and the dolt TestDeleteIssues* family
(this commit refactors DeleteIssuesInTx's guard); TestEmbeddedDelete,
TestEmbeddedDeleteJSONDependencyErrorContract, TestBurnWisps,
TestWispGCProtectsActiveWisps and TestCLI_WispGCExcludeType under
BEADS_TEST_EMBEDDED_DOLT=1; TestProxiedServerDelete{,ForceOrphans,Wisp,
Concurrent}, TestProxiedServerMolBurn and TestProxiedServerWispGC under
BEADS_TEST_PROXIED_SERVER=1; and TestProxiedLookup*.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
STAGE TWO OF TWO. Stage 1 (aa10a725e) added MaxRows and SkipCounts to
ListRequest and flipped no routes; this is the flip, plus the one role the
decoration needed.
TWO PARTS, and the role first because the flip needs it.
THE ROLE. `issueops.BlockingAnnotator` answers the decoration a listing prints
beside each row — `(parent: X, blocked by: Y, blocks: Z)` — for the ids of a
page that has already been chosen. It is its own role rather than EdgeReader
growth (Q12 asked and answered two), and the distance between them is larger
than it looks: EdgeReader returns STORED ROWS of every type with targets
spelled as stored, no status consulted, and a per-anchor Missing flag from an
existence probe; this one returns a DERIVED summary of two types with closed
blockers dropped, the inbound direction included, and NO existence probe at
all. It is not Reader growth either — it has no order of its own, nothing it
returns depends on how the page was chosen, and a ListRequest field would have
implied the annotation was part of the query.
THERE IS NO MISSING FLAG, and that is a decision the leaf states rather than an
omission: an id that names nothing and an id with no live blocking edges
decorate identically, so a probe would be a read whose answer no caller can
use. One conformance case asserts that ABSENCE of a distinction.
A BLOCKER THIS DATABASE HOLDS NO ROW FOR COUNTS AS OPEN — an `external:`
reference, a foreign-repository id, a row whose issue was deleted. An
unreadable status is not `closed`, and a listing that hid a blocker it could
not resolve would report work as unblocked on the strength of a row it never
found. Both implementations already did this; it now has a sentence and a case.
THE ORDER WITHIN EACH LIST IS NOW PINNED, ascending with repeats collapsed, and
this is the commit's ONE user-visible change. Both lists are joined into one
line of output, so the query's natural order was user-visible bytes that could
move between runs. It affects only rows with two or more live blockers, and it
is recorded as A-blk-2.
TWO BODIES, NOT THREE. dolt and embeddeddolt share
storage/issueops.ExecuteBlockingAnnotation inside their own read transaction;
the unit-of-work provider is the genuinely separate one — it reads BOTH
dependency tiers for every id and merges, where the store side partitions the
ids by plane, and it resolves statuses only for the ids a row mentioned.
FinishBlockingAnnotation is what makes the SHAPE of the answer one decision
rather than two. Seventeen cases, three wirings, ZERO PARKS.
THE HTTP HALF. GET /v0/beads/dependencies/blocking, spec first, `make api-gen`
after. `IssueBlocking` is x-go-type-pinned to the role package the way `Cycle`
and `CycleMember` are, and BOTH the schema and the envelope's Items are pinned
in internal/httpapi/pinning.go — the v2.6.0 allOf trap was checked (the
generated type is a bare alias) and bd-5o3gt did not become two. The size bound
is maxDependencyAnchors, SHARED with the stored-edge read rather than given a
constant of its own: the two operations are asked about the same page of ids,
and two numbers would let a client ask one about a page the other refuses.
`dependencies.blocking` joins the capability vocabulary; `checkDatabaseSource`
grows a required role, which is the edit that reaches code this commit did not
write.
THE FLIP, one mode at a time and named as such in the code. FIRST `--json`:
the role's List runs the same LoadStoreListConfig, the same BuildListFilter and
the same workapi.FinishPage the branch ran longhand, so the page is unchanged
bytes and ErrTooManyRows still reaches handleMaxRowsError for exit 2. SECOND
every text rendering, with SkipCounts set — stage 1 added that field for this
arrival, and without it the flip would trade a plain scan for three aggregate
joins on the most-run command in the tree. THIRD the decoration.
WHAT STAYS OFF THE ROLE is --watch and the hierarchical --parent tree, the two
modes that consume the FILTER as a value. The bead also named --deps and
--format, and its stated reason — "reach no epilogue on either route" — is
false for both: they run FinishPage and printTruncationHint today. What is
genuinely off-role in those two is the WHOLE-GRAPH dependency-record load they
perform, which is neither a page nor the blocking decoration; their page comes
from the role like every other mode's. Recorded as A-blk-3 with the reading
this commit proceeded under, which is also the reading stage 1's own message
states ("stage 2 moves bd list's TEXT path onto the role").
The proxied route loses `runListProxiedReady`: --ready is ListRequest.ReadyFlag
and picking the ready query from it is the role's job on both routes. Two
functions differing only in which use-case method they called is the drift this
replaces.
PROVABLY INERT AT THE CLI, measured rather than argued: 31 `bd list` / `bd
children` invocations — every output mode, both cap knobs, --ready, --parent,
--format, --deps — run against a binary built from integration/facade-wave-3
and one built from this commit, over ONE shared workspace, differ on exactly
the two multi-blocker lines A-blk-2 predicts and nothing else in 687 lines. A
base-against-base run isolates the one other moving line as the
once-per-period install tip.
The forbidigo exception list did NOT shrink, and the count in
issueops/reader.go's claim is unchanged. cmd/bd/list.go and
list_proxied_server.go were never on it; cmd/bd/list_show_filter_modes.go still
is, because the tree walk, the watch loop, the proxied builder call and `bd
show --current` all still name the type. Said in the config rather than implied
by silence.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; the seventeen new
cases at dolt, embeddeddolt (BEADS_TEST_EMBEDDED_DOLT=1) and uow, all green
with no skips; internal/httpapi and make api-check; internal/storage,
internal/telemetry, internal/jira, internal/workapi/..., issueops and the root
layering pins; the embedded `bd list`/`bd children`/max-rows CLI suites,
TestProxiedServerList under BEADS_TEST_PROXIED_SERVER=1 (58 subtests including
tree_parent, the three format modes, ready pagination and the three max-rows
refusals), TestProxiedLookup*, and the protocol corpus package.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`bd create --file plan.md` had two implementations of one bulk create. The
direct route built types.Issue values in cmd/bd/markdown.go and handed them to
store.CreateIssues; the proxied route parsed the same templates again, opened a
unit of work, read a create context, checked the types itself and looped the
domain use case. Both now build ONE issueops.CreateBatchRequest from one shared
projection, and the difference between the two routes is which accessor answers.
THE ROLE. A batch's REQUEST is its transaction boundary, which is the same
reason BatchCloser exists and cannot be a loop over Lifecycle.Close: N creates
one call at a time are N transactions and N history entries, and the caller who
wants them to land together has no way to say so. It is its own role rather than
a Create overload because it is ALL OR NOTHING where the batch close keeps its
survivors, and one method cannot make both promises. The difference is what has
already happened: a close records work that is done, so a rollback destroys
information the batch was carrying; a create makes the work, so a refused item
leaves no survivors, and half a created plan cannot be re-run without
duplicating the half that landed.
It is born with Provenance, which CreateRequest does not have. Both --file
routes have always written `bd: create N issue(s) from <path>`, and a label
composed from the result cannot spell a file the result does not carry, so
without the field this commit would have caused the regression Q16 recorded
rather than inherited it.
USER-VISIBLE, and bigger than the bead described. The bead and the Q11 batch say
direct --file is non-atomic today - "a bad row can leave earlier rows created".
Reading the path does not support it: markdown.go built every issue first and
made ONE store.CreateIssues call, which both stores run in a single SQL
transaction. What was true is worse, and is recorded as Q25/Q26 in
AMBIGUITIES.md with A-bcr-2:
- a dependency naming an id that does not exist was SILENTLY DROPPED on the
direct route (the batch engine skips a dangling edge and nothing passed
OnSkippedDependency), while the proxied route already failed on it. Every
requested edge is now written or the batch refuses. An `external:` target
and an id belonging to another repository are still written, exactly as
`bd dep add` accepts them.
- --ephemeral, --no-history, --mol-type and --validate were accepted and
IGNORED on the direct route while the proxied route acted on all four, so
`--file --ephemeral` created durable issues locally and wisps on a team
server. All four now mean what they mean everywhere else, templates are
linted on both routes, and created_by/owner are set as the single-issue
create sets them.
- --file --json emits the stored post-create rows on both routes. Additive.
- proxied --file loses its config.yaml fallback for types.custom, the
convergence Q17 already recorded for single-issue create.
--graph is untouched, per Q10: an upsert over a declared shape is a different
contract and gets its own role when it gets one.
CONFORMANCE. backend/conformance/batch_creator_contract.go holds nine cases,
each citing the leaf doc by line, run at all three implementations with ZERO
parks: 27 subtests green. They are TWO independent bodies plus an engine check,
not three - dolt and embeddeddolt share issueops.ExecuteCreateBatch, which
prepares every item and hands the slice to one CreateIssuesInTxWithResult, while
the unit-of-work body creates item by item through the domain use case and keeps
"all or nothing" by returning early and letting the transaction roll back. That
is also why no case asks for a FORWARD reference inside a batch: the store body
could resolve one and the uow body provably cannot, so the role promises only an
edge onto an EARLIER item and the contract says so at the case site (A-bcr-4).
The store-backed body is an InTx function rather than an internal/workapi/store
package, the documented variant EdgeReader introduced: it must assign every id
before any row is written so an item's edge can name a sibling, which cannot be
expressed above storage.DoltStorage. It needs no depguard entry for the same
reason - the shared function takes a transaction, so no front door can call it.
HTTP. POST /v0/beads/issues:batchCreate is new canonical surface, spec written
first and the types generated from it. It is a collection-level custom method
spelled the way ready:count is, which leaves POST /v0/beads/issues free for the
single create that belongs there; it does not collide with the claim row's wide
POST wildcard, because that pattern requires the separating slash
(TestBatchCreateDoesNotShadowTheClaimRoute drives both). BatchCreateResponse
carries no allOf, so the oapi-codegen v2.6.0 pin-dropping trap does not apply,
and its Items are pinned to []types.Issue in pinning.go.
The wire publishes no `id` member, which is what keeps the role's
ErrAlreadyExists off a vocabulary that has no already_exists code (A-bcr-5): the
server assigns every id and `bd import` remains the upsert surface. The role's
ErrValidation is answered by the operation's own failure path rather than by
ClassifyError, because the dangling-edge refusal wraps BOTH ErrValidation and
ErrNotFound and the shared classifier reaches ErrNotFound first - a 404 for a
request that addressed no resource. Neither branch quotes the role's message: a
refused edge arrives as a driver error naming tables and constraints, and 4xx
details here reflect the caller's input.
httpapi.Config's roles source grows to eight roles. The half-set cases that
built a Config by hand now go through rolesConfig, so the next role does not
have to edit six literals that are not about the role set.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check clean;
TestBatchCreatorContract green at dolt (9/9), embeddeddolt (9/9) and uow (9/9);
./internal/httpapi green including eleven new batch-create tests; TestCorpusGolden
green (the corpus has no --file capture); TestCreateFromMarkdownFile green; the
cmd/bd create suites green with BEADS_TEST_EMBEDDED_DOLT=1 and the proxied
integration create suites green with BEADS_TEST_PROXIED_SERVER=1;
TestProxiedLookup green.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`bd purge` selected closed wisps in one transaction and deleted them in
another. A bead closed, unpinned or cited in the window between the two was
judged on one state and acted on in a different one — the TOCTOU the bead
names — and the proxied twin held a second copy of the whole flow: its own
candidate filter, its own glob match, its own closed_at recheck, its own
reference scan and 190 lines of output kept character-identical to the direct
route's by hand.
PURGE AND PRUNE ARE ONE CAPABILITY, which the design left open and the code
answers plainly: both routes already ran ONE function with a `purgeScope`
struct choosing the tier. So issueops.Sweeper has ONE method, reached through
store.Sweeper() and the provider's own accessor, and SweepRequest.Tier selects
the plane — `ephemeral` is purge, `durable` is prune, and the two are disjoint
by construction. What genuinely differed became request fields rather than a
second role: the require-a-filter refusal keys on Tier, and the citation
protection is ASKED FOR (ProtectReferenced) instead of being inferred from a
command name, which is what the shared body did (`scope.cmdName == "prune"`).
Q9 ANSWERED IN THE ROLE. The require-a-filter gate is
workapi.ValidateSweepRequest, below every front door: a durable sweep with
neither a cutoff nor an id pattern is ErrValidation. It is a safety invariant,
not presentation — without it a second front door is one handler away from an
unguarded mass delete, which is exactly what this commit's HTTP operation would
otherwise have been. The CLI keeps its friendly message, and says in place that
it is there for the WORDING while the guard is the role's; the contract case is
what proves the guard survives that branch being deleted.
THE DEFECT, AND ITS PRICE. The whole sweep is now one transaction, so the set
the result describes IS the set it deleted. That gives up the server-backed
store's batched wisp deletion (200 per transaction, added for Dolt's 10s write
timeout after bd-2ehd and ff-tqm): a sweep too large now fails WHOLE. That is
the better failure — the partial one it replaces reported a deleted count of
ZERO while having deleted rows — and the other two backends already worked this
way. It is written down as a promise WITH its cost, and recorded for sign-off.
TWO MORE DEFECTS the single call site removed. `--dry-run` passed force=false
to the delete where the real run passed force=true, so a preview could FAIL
over dependents the sweep would have orphaned — and the CLI answered that
failure with zeros. And `filepath.Match`'s error was discarded on both routes,
so `--pattern '['` printed "No closed beads to prune" and exited 0; it is now
ErrValidation quoting the pattern.
THE CONTRACT IS WHAT WAS DELETED, not what was reported.
backend/conformance/sweeper_contract.go holds ten cases, each citing the leaf
doc, run at all three backends with ZERO PARKS and zero divergences. Every case
that acts asserts row counts through QueryScalar rather than trusting the
result the sweep reported about itself, which on a destructive operation is the
assertion that matters; every case scopes itself with an id pattern, because a
sweep is asked of a whole TIER and an unscoped one would clear the next case's
seeds. They are TWO INDEPENDENT BODIES plus an engine check: dolt and
embeddeddolt share internal/storage/issueops.SweepInTx and differ only in how
they reach a transaction, and the unit-of-work provider reaches the same four
questions through the domain use cases.
THE HTTP OPERATION, spec first (per bd-jtp1h's A2 scope decision):
POST /v0/beads/issues:sweep, capability `issues.sweep` — the first DESTRUCTIVE
operation on a surface that was reads plus one claim. It is a collection-level
custom method with a body rather than DELETE with a query string, because a
dropped query parameter widens what is erased where an unknown body member is
refused by name. The handler decodes six members and calls the role; it does
not implement the safety gate, the tier vocabulary or the glob, all of which
are the role's ErrValidation reaching the wire as a 400 through failSweepErr.
No component carries allOf and none is x-go-type-pinned — there is no canonical
Go struct whose JSON encoding is this body, since the CLI publishes these
numbers under `purged_count`/`pruned_count` — so the projection is tested
instead. `bd serve --help` grew a DESTRUCTIVE OPERATIONS section and the
--allow-non-loopback warning now says peers can bulk-delete closed beads.
`bd gc` keeps the closed-candidate recheck by calling the SAME pure function
the role calls (workapi.FilterSweepCandidates), so the two cannot drift; the
reference matcher and its 10K-body budget moved to internal/workapi with the
scan. cmd/bd/purge.go and purge_proxied_server.go LEFT the forbidigo exception
list, which is how a role commit proves its front doors reached the role.
USER-VISIBLE, for the wave's changelog pass: the version-control label for a
sweep is now `bd: sweep <n> <tier> bead(s)` on both routes, where proxied wrote
`bd: prune <n> bead(s)` and direct wrote `bd: delete <n> issue(s)` — an HTTP
sweep is not `bd prune`, so the label names the operation and the tier from
every door; a malformed `--pattern` now exits non-zero; `--dry-run` no longer
refuses over dependents the real sweep orphans; and `bd serve` gains a
bulk-delete endpoint. Reasoning and the alternatives are in
/data/tmp/sd-server/AMBIGUITIES.md as A-swp-1..9.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
(regenerate-and-diff plus the httpapi suite) green; TestSweeperContract 10/10 at
dolt, embeddeddolt and uow; the internal/workapi, internal/storage and
internal/telemetry suites; TestEmbeddedPurge, TestEmbeddedPurgeConcurrent,
TestEmbeddedPrune, TestPrune_protectsBeadCitedByCustomStatusBead and
TestEmbeddedGC under BEADS_TEST_EMBEDDED_DOLT=1; TestProxiedServerPrune under
BEADS_TEST_PROXIED_SERVER=1; TestProxiedLookup*; and the root layering pins.
The protocol corpus has no purge/prune case to account for.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`bd query "type=bug OR label=urgent"` has been answering with a prefix of its
answer and calling it complete. The expression language has OR, NOT and
parentheses, which no storage filter expresses, so both routes fetched a WINDOW
of candidate rows — max(3*limit, 100) — and applied the expression to those in
memory. A match past row 100 was absent from the page and unreported by
has-more. The same six lines of arithmetic were written twice, once per route,
and both copies were wrong in the same way.
THE ROLE. issueops.Querier, reached through store.Querier() and the provider's
own accessor. One method over a request whose predicate is a SENTENCE rather
than a set of fields, which is what makes it a role instead of a mode of
Reader: a ListRequest is a conjunction — every field narrows — and no
arrangement of its twelve callers' fields expresses a disjunction. It is
equally not a raw query passthrough; the language names no table, no join and
no column outside a closed vocabulary, which is why a contract can promise
anything about it at all.
THE FIX, which Q3 approved as user-visible. A predicate query's filter now
carries NO row limit: the predicate sees every candidate row, the page is the
first Limit MATCHES of the complete matching set, and has-more is exact. The
decision has one home, internal/workapi.BuildQueryPlan, which both bodies
execute. The cost is stated rather than hidden — a broad OR over a large
workspace now reads every row its base filters admit — and CHANGELOG.md says so
in the same words.
WHAT PINS THE FIX, at three levels, because the contract alone cannot see it.
TestBuildQueryPlanLeavesAPredicateQueryUNBOUNDED asserts the arithmetic in
microseconds. TestAPredicateQueryFindsAMatchBeyondTheOldWindow seeds 101 rows at
ONE backend and reads back the match at row 101 — verified to discriminate:
with the old window temporarily reinstated it returns zero rows. The portable
contract asserts the PROMISE the window broke (a page is a prefix, has-more is
exact) and, confirmed by the same experiment, does NOT discriminate the old
window at its small scale; the contract's header says so rather than implying
coverage it does not have.
THE CONTRACT. backend/conformance/querier_contract.go holds nine cases, each
citing the leaf doc by line, run at all three backends with ZERO parks. TWO
independent bodies plus an engine check: dolt and embeddeddolt share
internal/workapi/storequerier, and the unit-of-work provider is genuinely
separate — it is the only leg on which the Offset case takes its HONORED branch,
since that seam renders OFFSET where the store body refuses uniformly.
TWO SMALLER USER-VISIBLE CHANGES ride along, both filed in AMBIGUITIES.md
(Q22, Q23) for the owner's batch. `--offset` with an OR/NOT expression is no
longer refused: the offset skips MATCHES, which is only meaningful now that
every match is seen, so an error became an answer. `--limit -1` is now
ErrValidation instead of an undocumented second spelling of unlimited. The
`--offset` + `--sort` refusal survives and moved INWARD — the role makes it, for
every caller, because the order is applied to the rows the query bounded and
each page of an offset walk would be sorted for itself — so its wording changed
with its address, as did the wording of a malformed expression on both routes.
A DEFECT FOUND AND NOT FIXED, recorded as A-qry-1 rather than papered over: an
UNLIMITED request carrying an Offset renders SQL the Dolt engine answers with a
recovered panic (makeslice: cap out of range, out of topRowsIter). It predates
this role — `bd query --offset N --limit 0 --proxied-server` built the same
filter — and it is a storage-seam bug, so the contract case asks its question at
a bounded limit and says why at the case site.
THE HTTP OPERATION, spec first (per bd-jtp1h's A2 scope decision):
GET /v0/beads/issues:query, capability `issues.query`, answering a new QueryPage
{items, has_more}. It publishes no cursor and no `offset`: a predicate query's
matching set is assembled outside the database, so there is no keyset position
to encode, and an offset is honored by one database source and refused by the
other, which is not a difference to put on a wire. QueryPage carries no allOf
and its Items are pinned in pinning.go beside ReadyPage's and IssuesPage's — the
edit wave 2 missed once (bd-8ri3m). Adding a second sort enum made oapi-codegen
disambiguate the FIRST one, renaming the generated ListReadyWorkParamsSort
constants (Hybrid -> ListReadyWorkParamsSortHybrid); nothing outside the
generated file named them. httpapi.Config's roles source grows a required eighth
member, and a Config complete under the previous release is now refused at
Listen rather than nil-dereferencing on the first issues:query request.
WHAT ELSE CONVERGED. Both output modes read ONE query — the counted one --json
always used — so a predicate can no longer be applied to two different row sets
depending on the flag (A-qry-1's neighbour, Q24). The direct route prints the
truncation hint for the first time, not by new choice but because it finally has
an honest has-more to print.
Incidental: internal/storage/role_accessor_decorator_test.go's four
near-identical "the four read roles" paragraphs — one appended by each wave-2
slice — are collapsed into the one accurate paragraph the table needs. Same
defect as bd-8ri3m, comments only.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check green;
TestQuerierContract 9/9 at dolt, embeddeddolt and uow;
TestAPredicateQueryFindsAMatchBeyondTheOldWindow; the internal/httpapi package
suite; internal/workapi, internal/storage, internal/telemetry, internal/query
and the root package; TestEmbeddedQuery under BEADS_TEST_EMBEDDED_DOLT=1 and
TestProxiedServerQuery under BEADS_TEST_PROXIED_SERVER=1; TestProxiedLookup*.
The protocol corpus drives no `bd query` invocation and is untouched.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`bd ready --limit 100` prints "showing 100 of 412", and the 412 came from
nowhere in particular. The direct route computed it inline: unwrap past the
storage decorators, type-assert to storage.ReadyWorkCounter, and fall back to
an unbounded ready query when the assertion missed — twice, once in the --json
branch and once in the text one, with two different fallbacks. The proxied
route could not compute it at all and published no `total` key, so the same
script read a number under one workspace topology and nothing under another.
THE ROLE. issueops.ReadyCounter, reached through store.ReadyCounter() and the
provider's own accessor. It answers a question neither neighbour can: Reader
answers with a PAGE and its verdict is has-more ("did the limit hide
anything"), where this is "how many" — strictly larger, and already published
output, so collapsing the two would change what a shipped surface says. Counter
answers a predicate over one table, and the ready predicate is blocker-aware:
it reads the dependency graph and the wisp tier, which no CountRequest can
describe. Counter's own doc already said the count of ready work would be its
own role for that reason.
It takes issueops.ReadyRequest VERBATIM, the precedent ClaimNextRequest set, so
a listing, a claim and a count ask ONE question of ONE set. Limit and Offset are
ErrValidation for the reason a claim refuses them: a cardinality has no page, so
a limit would answer "how many of the first N" and an offset would subtract the
rows it skipped from the size of a set that still holds them.
THE CONTRACT IS AN IDENTITY, not a resemblance:
CountReady(r).Total == len(Reader.Ready(r with Limit=0).Items)
at every implementation. backend/conformance/ready_counter_contract.go holds
seven cases, each citing the leaf doc by line, run at all three backends with
ZERO parks. They are TWO independent bodies plus an engine check: dolt and
embeddeddolt share internal/workapi/storereadycounter (one indexed COUNT(*) per
plane minus their overlap), and the unit-of-work provider is genuinely separate
code that runs the unbounded ready query and takes its length — which is why
the wisp-tier case is written the way it is, since that is where a COUNT and
the page it sizes are assembled by different arithmetic.
A DEFECT THIS FOUND, and it is not the count's. `bd ready`'s directory-label
default (GH#541) never reached the ReadyClaimer role. claimNextRequest re-ran
the gatherer's own emptiness test against in.filter — and the gatherer had
already written the default INTO that filter, so the test saw a non-empty label
set and skipped. The branch could never fire. In a directory with
`directory.labels` configured, `bd ready --claim` therefore claimed from the
WHOLE ready front while `bd ready` beside it listed only the configured scope:
exactly the "hand an agent work the listing never offered it" that
ReadyClaimer's contract exists to forbid. The gatherer now RECORDS its decision
(readyInput.dirLabels) and both roles read it, so there is one answer instead of
two derivations of it. Caught by writing the count's own test for the same
line, and pinned by cmd/bd/ready_role_request_test.go.
WHAT ELSE CONVERGED. Both routes and both output modes now ask one question
through one accessor: the direct route's two inline epilogues become one call,
and the proxied route's `pagination.total` exists for the first time. The
"showing X of N" text a human reads and the total a script parses are the same
number by construction. cmd/bd no longer names storage.ReadyWorkCounter at all
— the capability is required by the store body's PARAMETER TYPE, so a backend
that cannot size the ready set fails to compile instead of falling back to a
mega-query at runtime.
THE HTTP OPERATION, spec first (per bd-jtp1h's A2 scope decision):
GET /v0/beads/ready:count, capability `ready.count`, answering
`ReadyCount {total}`. It publishes no `limit` and no `sort`: a cardinality has
no page and no order, and the handler sends the listing's own sort default so
the request stays the listing's request rather than one that resembles it. The
filter vocabulary is decoded by ONE function shared with GET /v0/beads/ready
(readyFilters), so the two operations cannot admit different parameters — which
is what the identity rests on over the wire.
`TestCountReadyAndListReadyAdmitTheSameFilters` compares the two predicates
built from one query string. No component here carries allOf and none is
x-go-type-pinned: the pinned seven are canonical Go structs whose JSON encoding
IS the contract, and there is no canonical struct for this number — the CLI
publishes it inside its own stdout envelope, which is not a wire type — so
pinning would weld the body to a CLI presentation type rather than prevent a
drift. The generated output was read to confirm it (a struct with `Total
int64`, not an alias), which is the v2.6.0 trap this document warns about.
httpapi.Config's ROLES database source grows a REQUIRED third member. That is
the sharp edge for the next role commit and is now written down in
engdocs/ADDING_AN_ISSUEOPS_ROLE.md as step 13: a Config carrying the old pair
would bind and then nil-dereference on the first request that reached the new
handler, so Listen refuses it with the same message a half-set pair gets.
USER-VISIBLE, for the wave's changelog pass: proxied `bd ready --json --limit N`
now publishes `pagination.total`; `bd ready --claim` now honours the
directory-label scope on both routes.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
(regenerate-and-diff plus the httpapi suite) green; TestReadyCounterContract
7/7 at dolt, embeddeddolt and uow; the httpapi package suite; the direct-route
`bd ready` suites under BEADS_TEST_EMBEDDED_DOLT=1 and the proxied ones under
BEADS_TEST_PROXIED_SERVER=1, including the pagination envelope that now asserts
the total; TestProxiedLookup*; and the ready protocol-corpus tests, which are
byte-identical.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`bd dep list a b c --direction=down` asks a different question from every
other dep read: it answers with RAW EDGE ROWS keyed by source, for many
anchors at once, and it has to say per anchor whether that anchor exists.
Both routes answered it off-role — the direct one out of
GetDependencyRecordsForIssues, the proxied one out of a unit of work — and
neither could tell "this issue has no dependencies" from "there is no such
issue".
THE ROLE. Relations is the near sibling and it cannot answer this. It is
SINGLE-ANCHOR, it answers with the ISSUES on the far end of an anchor's
edges, and an edge whose target this database has no row for — an
`external:` reference, an id in another repository — is silently not a
neighbor. A missing anchor is ErrNotFound there, which a batch cannot use
without discarding the anchors it did find. Different answer shape,
different miss policy, different arity: three, so a new role and a new
accessor rather than a second Relations method. Q12 confirmed the split
against merging it with BlockingAnnotator, which answers a derived
best-effort decoration rather than stored rows.
The direction is OUTGOING only and there is no parameter for it. The inbound
bulk read is a different read against a different key with its own
cross-table de-duplication, and no front door asks for it; a direction
nothing sets would be a promise nothing checks.
TWO DEFECTS THE ADOPTION FIXES, both of them the same shape — a silent
change of JSON document:
- the KNOWN DEFECT. The direct route's batched read fell through to the
hydrated neighbor listing on ANY error, so a transient failure turned
`bd dep list a b --json` from an array of dependency records into an
array of ISSUES, with no error and no warning.
- the same fall-through fired whenever routing split the anchors across
stores, so a cross-rig batch emitted that other document every time. The
role is reached per store now and the answers merge back into argument
order, so a routed batch and a local one have one shape.
Also fixed on both routes: `--type` used to test emptiness BEFORE filtering,
so an anchor whose every edge the filter rejected printed a header with no
rows under it. The role filters, so it prints "has no dependencies".
USER-VISIBLE, approved in the Q11 batch: PROXIED `bd dep list` NOW REPORTS
GHOST ANCHORS. It used to hand the raw arguments to the dependency use case,
which keys its answer by source and has no entry for an id that names
nothing, so a typo printed "<id> has no dependencies" and a script read a
clean graph. The role probes each anchor, so a typo now prints the warning
the direct route has always printed for an argument it could not resolve —
on stderr, in both modes, which is what leaves `--json` the flat array of
dependency records the command documents. The proxied route still resolves
nothing: ids go to the role exactly as the caller spelled them, because that
route has never done partial-id resolution.
One behaviour had no prior decision behind it and is recorded as Q15 rather
than chosen quietly: a repeated anchor now collapses onto its first mention,
where the old loop over a keyed map printed it twice.
CONFORMANCE. backend/conformance/edge_reader_contract.go holds fourteen
cases, each citing the leaf doc by line, run at all three implementations
with ZERO parks. They are TWO independent bodies plus an engine check, not
three: dolt and embeddeddolt both call storage/issueops.ExecuteEdgeRead
inside their own read transaction, and the unit-of-work provider is the
second body — it probes existence through two batched by-id use-case reads
where the stores run one batched EXISTS over both tables.
The store-backed body is an InTx function rather than an
internal/workapi/store<role> package, which is a documented deviation from
the twelve-step checklist and the reason is Relations': the anchor probe and
the edge read must share ONE transaction, or an anchor can be reported
missing by a probe that raced a create the edge read then saw. That cannot
be expressed above storage.DoltStorage. engdocs/ADDING_AN_ISSUEOPS_ROLE.md
now names that variant, including why it needs no depguard entry — the
shared function takes a transaction, so no front door can call it.
HTTP. GET /v0/beads/dependencies is new canonical surface, spec written
first and the types generated from it. `items` is an array of the already
x-go-type-pinned `Dependency`, so the CLI's `--json` and this body stay one
compatibility domain; the new `DependencyEdges` envelope carries no allOf,
so the oapi-codegen v2.6.0 pin-dropping trap does not apply, and the
generated `Dependency` is still an alias. A ghost anchor is on `missing`
rather than a 404, for the reason the role reports it per anchor. There is
no `limit` and no cursor: `bd dep list` has none either, so the QUESTION is
bounded instead — at most 100 `issue_id` values — which bounds the work
without truncating an answer a client could not then page.
httpapi.Config's roles source grows from two roles to three, and Listen
refuses a partially-set set for the reason it already refused a half-set
pair: the missing role is a nil dereference in a handler on a live server.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
clean; TestEdgeReaderContract green at dolt (14/14), embeddeddolt (14/14)
and uow (14/14); ./internal/httpapi green; TestCorpusGolden green, so the
committed `bd dep list --json` fixture is byte-identical; TestEmbeddedDep
and TestProxiedServerDep2 green with their gates set; TestProxiedLookup
green.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`bd dep cycles` had two implementations of one sweep and the post-add cycle
warning had two more. The direct route walked store.DetectCycles; the proxied
route walked the same lossy slice off the use case; and dep.go and
dep_proxied_server.go each carried a copy of the arrow-path warning. The two
copies agreed, which is the only reason nobody noticed that the slice they
agreed about was map-ordered and silently shortened. All four now build one
issueops.DetectCyclesRequest and ask for the role.
THE ROLE. A cycle has no ANCHOR. Every Relations request names a source and
answers with that source's neighbours; this one is asked of the whole graph and
answers with paths, so a Relations request type would have carried an anchor
field a sweep must ignore. Its own role and its own accessor per the governing
rule.
TWO USER-VISIBLE CHANGES, both ruled on by the owner (Q4, Q5), both recorded in
CHANGELOG.md.
Q4 CANONICAL OUTPUT. Every source of nondeterminism is removed, not just the
order of the answer, because ordering the answer would not have been enough:
a depth-first enumeration records one cycle per BACK EDGE, and which edges are
back edges depends on the walk. The roots came off a Go map and the adjacency
lists out of an unordered SQL read, so two runs against an unchanged database
could disagree about which cycles EXIST, not merely about their order. The
walk is now sorted at both, each path is rotated to its lowest id, and the
paths are sorted against each other.
Q5 HONEST PARTIAL. A member the database cannot describe used to be dropped
from the path, so a 3-cycle rendered as a 2-cycle and looked complete, and a
wholly undescribable cycle vanished from the report and from the
`Found N dependency cycles` count. Every member is now carried with its id,
its DESCRIPTION is omitted rather than the member, and the cycle is marked
Partial. There is no separate total, because there is no cycle the slice
omits -- the reading of "still counted" is recorded in AMBIGUITIES.md
(A-cyc-1) along with what it would cost to add one.
`bd dep cycles --json` therefore emits a new shape: an array of
{members:[{id, issue?}], partial} where it emitted an array of arrays of
issues. The protocol corpus has no dep-cycles capture, so nothing was pinned
to the old bytes.
WHERE THE BODY LIVES, and why it is not a store<role> package. The work is a
graph read plus a hydration that must see one snapshot, and a transaction is
not reachable through storage.DoltStorage. So the sharing happens one level
down at issueops.DetectCycleReportInTx -- the function both stores' legacy
DetectCycles already call -- with a five-line accessor in each store package
and a new domain repository method for the unit of work. Two wrappers over one
function is still ONE vote. The parts that decide what the answer MEANS are
pure (CanonicalCyclePaths, BuildCycles) and pinned without a database.
CONFORMANCE. backend/conformance/cycle_detector_contract.go holds eight cases
citing the leaf doc by line, run at all three implementations with ZERO parks:
24 subtests green.
SEEDING ONE TAKES RAW SQL, which is a fact about the system rather than a
shortcut. No supported write can create a cycle -- the editor's per-edge probe,
its whole-graph gate and the storage seam all refuse -- so there is no verb that
produces the state this role reports. And foreign keys (dependencies.issue_id
-> issues, wisp_dependencies.issue_id -> wisps) mean an undescribable member is
reachable only with foreign_key_checks off. That is not academic: those are
exactly the paths a cycle arrives by. Recorded as AMBIGUITIES.md A-cyc-2 with
the alternative if the owner would rather the contract not write that way.
HTTP. GET /v0/beads/dependencies/cycles, spec first and the types generated
against it. Cycle and CycleMember are x-go-type-pinned to the ROLE package, so
the CLI's --json element and the HTTP item are one struct; the bijection test
grew a per-schema import path to cover them and immediately caught a missing
json tag on Partial. No allOf on either component (the v2.6.0 trap), verified
in the generated output: both emit `type X = issueops.X`. No limit and no
cursor -- truncating would shrink the count, which is the number an operator
acts on -- so has_more is documented as always false. httpapi.Config's roles
source now requires the third role beside Reader and Claimer, refused at Listen
for the reason a half-set pair is.
ONE DEFECT FIXED BESIDE THE TWO RULINGS: proxied `bd link` ran its cycle sweep
and its title lookups INSIDE the write transaction, so the warning described a
graph nobody else could see. It now runs them after the commit, through
depEdgeFeedback, which is where the dep routes already did it.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
green; TestCycleDetectorContract 8/8 at dolt, embeddeddolt and uow;
internal/httpapi 0 failures including the five new cycle-route cases;
TestProxiedLookup* green; TestEmbeddedDep* green;
BEADS_TEST_PROXIED_SERVER=1 TestProxiedServerDep* green; TestCorpusGolden
green.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`bd status` (and its `bd stats` alias) had two implementations of the same
command. The direct route asked the store for statistics and, under
--assigned, built an assignee filter, ran a ready-work query and folded
five status counts itself; status_proxied_server.go did all four again
through a unit of work. Both now build an issueops request and ask for the
role, and the difference between the two routes is which accessor answers.
THE ROLE. Its numbers are DEPENDENCY-AWARE — the blocked count reads the
denormalized transitive is_blocked flag and readiness is derived from it —
so no predicate over the issues table describes them and this is its own
role rather than a sixth Counter dimension, which is what issueops/
counter.go already said it would be. Stats and AssigneeStats are born
together because they answer the same question of two sets; they are two
METHODS rather than one with an Assignee field because the assignee answer
fills four fields of the same struct by different definitions, and a
request whose optional string silently changed what a number meant is the
shape this programme exists to remove.
WHAT THE LEAF DOC NOW SAYS OUT LOUD, none of it written down anywhere
before: BlockedIssues counts the graph, not the "blocked" status;
ReadyIssues is arithmetic and NOT the cardinality of `bd ready`;
PinnedIssues overlaps every status bucket so the buckets do not sum to
Total; the workspace-wide answer excludes the wisp tier while the
assignee-scoped one merges it; --no-blocked is a HINT whose only report is
BlockedIssues being nil; and EpicsEligibleForClosure and AverageLeadTime
are structurally always zero, which is why `bd status`'s "Extended:"
branch has never once printed.
CONFORMANCE. backend/conformance/stats_reporter_contract.go holds thirteen
cases, each citing the leaf doc by line, run at all three implementations
with ZERO parks and zero divergences. Unusually for this suite they are
THREE genuine votes: the two stores share the role body (storestats) but
dolt/queries.go, embeddeddolt/statistics.go and domain/db/issue.go each
spell the blocked count and the ready subtraction themselves. Every
workspace-wide case asserts a before/after DELTA — a summary takes no
predicate, so there is no IDFilter to scope it with the way the Counter
contract scopes its cases.
HTTP. GET /v0/beads/stats is added to the Tier-1 document FIRST and the
types generated from it: a `Statistics` schema x-go-type-pinned to
types.Statistics (checked: the pin survives, and the schema is now in the
JSON-tag bijection test), a StatsResponse envelope mirroring the CLI's
--json shape minus `recent_activity`, which no shipped path populates. The
handler calls the same role both CLI routes call. `blocked_count_skipped`
is DERIVED from the answer, never echoed from the request, because the
hint is a hint. httpapi.Config's roles source grows a third field and
requires it with the other two: a source that answers some operations and
faults on others is not a source.
ENFORCEMENT. cmd/bd/status.go and status_proxied_server.go no longer name
types.IssueFilter or types.WorkFilter, so `status` LEAVES the forbidigo
exception list (63 -> 61 of 388 files). The role-constructor depguard list
gains storestats.
TWO USER-VISIBLE CHANGES, both improvements and both small: `bd status
--assigned` reports the underlying failure instead of the bare "failed to
get assigned statistics", identically on both routes; and the proxied
--no-blocked warning now fires from the ANSWER rather than from the route,
so a backend that gains a fast path stops printing it with no edit.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
clean (no codegen drift, whole httpapi package green);
TestStatsReporterContract 13/13 at dolt, embeddeddolt and uow;
TestEmbeddedStatus and TestProxiedServerStatus green with their gates set;
TestProxiedLookup green; TestCorpusGolden green.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`bd config` had two implementations of the same four verbs. The direct route
called store.SetConfig/GetConfig/GetAllConfig/DeleteConfig in cmd/bd/config.go;
the proxied route opened its own unit of work and called the config use case in
config_proxied_server.go, then printed the same lines a hundred lines away. Both
now build an issueops request and ask for the role, and the difference between
the two routes is which accessor answers.
THE ROLE. issueops.WorkspaceConfig is the workspace's DURABLE SETTINGS PLANE:
the key-value rows the workspace database holds. It is born with four methods
because read, write, remove and enumerate over ONE keyed namespace are four
shapes of one question — the governing rule forbids appending to a role, not a
role being born whole — and because their promises are statements about each
other: SetSetting's promise is about what a later GetSetting returns, and
UnsetSetting's about what a later ListSettings omits.
The methods are GetSetting/ListSettings/SetSetting/UnsetSetting rather than
Get/List/Set/Unset, and that is not verbosity. Reader already has Get and List,
and the decorator conformance tests drive ONE sentinel that implements every
role at once; two roles with the same method name and different signatures make
that sentinel unwritable. The collision was the design telling us the short
names belong to issues.
ONLY THE KV SLICE IS A ROLE, and the rest is a deliberate no. `bd config show`,
`drift`, `apply` and `validate` are multi-source diagnostics over config.yaml,
environment variables, git config, this plane and server state at once. Three of
those five sources are files on the CLIENT's filesystem, which a server
answering for a remote workspace can never read, so a substrate role claiming to
answer them would be claiming to see something it cannot. `bd config set-many`
is off the role too, for a different reason: it exists to make N keys ONE Dolt
commit, the role writes and commits one setting per call, and
TestProxiedServerConfigSetMany pins the difference. A batched write is a
separate capability, exactly as `bd create --file` stays off Lifecycle.Create.
TWO LIVE DEFECTS FIXED.
1. THE PROJECTION, which is the Q11 user-visible change. Reads of the custom
status and type vocabularies are TABLE-first: they consult custom_statuses
and custom_types and fall back to the config string only when the table is
empty. The store backends have always rewritten the table in the same
transaction as the row; the unit-of-work backend wrote only the string. So
on a team server `bd config set types.custom "session"` reported success,
`bd config get` read it back, `bd doctor` re-verified against the string and
reported all-OK, and `bd create -t session` answered "invalid issue type"
for as long as the workspace lived. Fixed where dab71c5eb fixed it — in the
config repository, so the row and its projection commit together — and
verified by reverting the fix and watching ProjectsCustomStatuses and
ProjectsCustomTypes fail on uow alone.
2. `bd config set-many issue_prefix=x` re-prefixed the workspace. The
single-key verb refuses the prefix in both spellings and points at
`bd init --prefix`, `bd bootstrap` and `bd rename-prefix`; set-many
partitioned its pairs by source and wrote the database ones straight
through, so it never saw that guard. Beads created before the write and
after it disagreed about their own namespace with nothing to reconcile
them. The refusal is now in the role for every caller that goes through it,
and at set-many's front door because it does not.
THE BRIEF'S THIRD PREMISE IS FALSE, and it is worth saying so: "uow SetConfig
skips issue_prefix normalization" is not true at this base.
configSQLRepositoryImpl.SetConfig has trimmed the trailing hyphen since the file
was created (4fcbd5882, verified with git log -L). The normalization half needed
no fix; the custom-table half did, and dab71c5eb is NOT in this base.
WHAT ELSE CONVERGED. The status.custom parse lived in THREE places (both routes
of `bd config set` plus set-many) and is now one; the routing that stays at the
front door — which source owns a key, and whether writing it would leak a secret
into git — stays there, because those are questions about files on this machine.
CONFORMANCE. backend/conformance/workspaceconfig_contract.go holds fourteen
cases run at all three implementations with ZERO parks. Its shape is
deliberately not the issue contracts': there are no rows to seed, so it asserts
PRECEDENCE (which of two writes a later read sees, and whether a refusal leaves
the earlier value standing) and SIDE EFFECTS. Every projection case reads the
TABLE through QueryScalar rather than reading the setting back through the role,
because reading it back through the role is exactly the check that passed on the
backend where nothing took effect. Two independent bodies plus an engine check,
not three votes: dolt and embeddeddolt share
internal/workapi/storeworkspaceconfig.
TWO ASYMMETRIES ARE PINNED RATHER THAN FIXED, because all three backends agree
and closing either is a user-visible change this slice was not approved for.
UnsetSetting does not undo SetSetting's projection, so removing types.custom
leaves the custom types applying (bd-yby99.33); and `bd config unset
issue_prefix` is not refused where `bd config set` is (bd-yby99.34). Both are
stated in the leaf doc and asserted by a case, so neither can drift or be closed
on one backend while the owner decides.
HTTP. GET /v0/beads/config and GET /v0/beads/config/{key}, spec-first, taking
the v0 surface from six operations to eight. A setting whose KEY marks it as
credential-bearing — notion.token is database-backed — is published with
`redacted: true` and NO value: withheld values are omitted rather than masked,
which is the document's own "verbatim or absent" rule, and the CLI is unchanged
because its caller already holds the database while this surface has no
authentication. There is no HTTP WRITE, and that is the honest answer rather
than a hedge: `bd config set` routes most keys to config.yaml or git config
before the database is reached, so a server-side PUT of `export.auto` would
return 200 and land a row nothing reads. `Setting` is the one unpinned response
component, with the reason in the document beside it — the CLI marshals an
ad-hoc map, so there is no canonical struct to pin to, and minting one would
mean changing `bd config get --json` in order to satisfy a rule about not
changing it. All three are recorded in AMBIGUITIES.md as A-cfg-1..3.
ENFORCEMENT. storeworkspaceconfig joins the cmd-bd-role-constructors deny list.
`bd config` never named types.IssueFilter, so there is no forbidigo exception to
remove. engdocs/ADDING_AN_ISSUEOPS_ROLE.md gains what step 12 now costs since
the owner's scope decision: the spec operation, the route row, the Op constant
and operationCodes row, the capability token, and the Config field that a
store-shaped database source must now carry.
Verified: build, vet, gofmt clean; golangci-lint 0 issues;
TestWorkspaceConfigContract green at dolt (14/14), embeddeddolt (14/14) and uow
(14/14); the workapi validator unit tests, the two decorator enumerations, the
root layering pins and internal/jira green; internal/httpapi green and
`make api-check` clean; TestProxiedLookup green; `-run Config` green under
BEADS_TEST_EMBEDDED_DOLT and, under BEADS_TEST_PROXIED_SERVER, green except
TestConfigValidateReadOnlyIsHermetic, which fails identically on a pristine base
worktree under the same filter and passes standalone on both. TestCorpusGolden
green, so `bd config --json` is byte-identical to the committed corpus.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Beads had two implementations of most issue verbs: one for the direct route
(the CLI talking to a store it opened itself) and one for the proxied-server
route (the CLI talking through a unit of work over a running Dolt server).
They drifted — different commit messages, different transaction boundaries,
different refusals, occasionally different answers.
Seven role interfaces now live in the leaf package issueops: Lifecycle,
Reader, ReadyClaimer, BatchCloser, DependencyEditor, Commenter and Relations.
Each is reached only through a store accessor, never a constructor, because
the accessor is where the hook and telemetry decorators add their layers.
Three implementations back every role — dolt, embeddeddolt, and the
unit-of-work provider the proxied route uses. Both routes call the same role
for close, dep add/remove/list, comment, ready --claim and update.
A depguard rule (httpapi-domain-boundary) denies internal/storage/domain from
internal/httpapi, so a handler cannot reach uw.IssueUseCase() past the roles
and open a second front door one lint-clean commit at a time.
Behaviour users will notice, all in the CHANGELOG:
- bd close a b c is one Dolt commit, not three, and --claim-next moved
inside that transaction so it fires only when something landed
- the open-children guard moved into the transaction and its hand-rolled
cmd/bd copy is gone, removing a read-then-write window that made
bd close <child> <parent> depend on argument order
- bd dep add --file honours deferred version commit
- embedded bd comment writes the role's message and author
- dep verb commit messages are the role's on the direct route
Wisp-sourced dependency edges are restored. Moving bd dep add onto the role
had pinned an edge's SOURCE to the issues plane, and the two routes did not
even fail alike: direct refused with "issue <id> not found", proxied threw an
fk_dep_issue violation. The comment justifying the pin claimed the issues
plane was "the only one its unit-of-work sibling can reach" — that was false;
domain.DependencyUseCase declared a full set of wisp twins with no production
caller. All three implementations now route per edge by the edge's own
source. A mixed request stays one transaction: parent-child-first ordering
and the whole-graph cycle gate span both planes, and a refusal rolls back
both. Behind the role, three bulk add verbs collapsed into one source-routed
AddDependencies, so no plane-pinned variant is left to reach for by mistake.
Six Provenance fields with no production caller were deleted rather than
wired — CloseRequest, CloseBatchRequest, ClaimNextRequest, AddCommentRequest,
AddDependenciesRequest, RemoveDependencyRequest. Each role already composes an
id-bearing message, so a caller could only restate the default and make it
unreachable from production. Two are not caller-settable even in principle:
CloseBatchCommitMessage names what LANDED and ClaimNextCommitMessage names the
id the claim WON. UpdateRequest and ReopenRequest keep theirs; commit messages
users see are unchanged.
Verified: build, vet and gofmt clean; golangci-lint 0 issues; protocol corpus
byte-identical under BEADS_PROTOCOL_REQUIRE_DOLT=1; all twelve
DependencyEditor conformance wirings green (four contract functions against
each implementation); TestEmbeddedDepAddWispSource runs bd dep add <wisp-id>
at the front door and was demonstrated RED against the pinned routing first.
Three internal/storage/dolt failures reproduce on pristine origin/main.
Known gaps are enumerated in the PR description rather than left to be found:
comment listing is on no role, bd dep tree and bd dep cycles have no role,
bd create and bd reopen are on Lifecycle only on the direct route, per-edge
line attribution is lost in bd dep add --file, multi-store bd close
--claim-next rides only the first store's batch, and the is_blocked staging gap
(bd-2y9ke, predates this change). Seven of the eight role interfaces now have a
shared conformance contract in backend/conformance, run at all three
implementations; main's Claimer, added in parallel by #5334, is the eighth and
has none yet.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Let httpapi.Config take the issue roles as a database source
bd serve could only be built from a unit-of-work provider: Config.Provider
was the only database field, and Listen refused a nil one. A backend whose
facade is a STORE — which is the shape the storage/backends registry seam
already has — had no way to be served at all, even though its accessors
return exactly the two roles the handlers now use.
Config gains Reader and Claimer beside Provider, and Listen takes exactly
one complete source: a provider, or both roles. Serving a store-backed
workspace is now Config{Reader: rd, Claimer: cl} from that store's own
IssueReader()/IssueClaimer(), with no unit-of-work provider invented in
between.
The provider path is byte-identical. reader() and claimer() still wrap the
provider per request in timedProvider and build the roles over that wrapper,
so uow_ms keeps measuring what it always measured and both timing tests keep
pinning it. On the roles path there is nothing to time — this server opens no
units of work — and 0.000 is the true value, so the startup line gains a
db=provider/db=roles field to make the zero attributable rather than silent.
The pool_* fields and the PoolTuner call stay behind the provider for the
same reason: the pool belongs to whatever the backend is.
A half-set pair is refused rather than tolerated. A reader with no claimer
would bind, answer every read, and fail the one write on this surface with a
nil dereference inside a handler.
No handler, route, spec or generated type changes: the wire is untouched, and
cmd/bd/serve.go still builds the provider it always did. The remaining piece —
serveModeGate narrowing plus a store-backed arm in runServe — waits on the
first registered store-shaped backend, and on resolving that cmd/bd's store
chain fires hooks on a landed claim, which bd serve documents that it does not.
Agent-Signature: claude-opus-5
Co-authored-by: CI Bot <ci@beads.test>
* Make the role seam's guarantees structural again, or loud
Config.Reader/Claimer took three guarantees that the provider seam enforced
by construction and turned them into prose contracts on caller-supplied
code. Two of them can be checked here and now are; the third cannot be
checked here at all, and the docs stop claiming otherwise.
A role that answers with nothing is no longer dereferenced. handleGetIssue
wrote *details and handleClaim wrote *result.Issue on the strength of a
property the provider path could not violate: s.reader() could only return
uow.NewIssueReader(...), whose Get routes through workapi.GetIssueOrWisp,
and that function exists precisely so no caller is ever handed a nil issue
with a nil error. A configured role is ordinary code. checkedReader and
checkedClaimer (roles.go) now wrap every role this server hands a handler,
from EITHER database source — unconditionally, so that "there is no other
way to reach the dereference" is the reason it is safe rather than a
separate belief about how the provider path behaves. A reader with no
detail view is folded into the documented miss and answers the same 404
body an absent issue does, byte for byte. A claimer that reports success
without a row has no documented reading, so it is the generic 500 — with
the fault in the log as an error and a request_error line beside it, which
is what the panic it replaces did not produce.
Listen refuses a role that fires the workspace's hooks. bd serve documents
that hooks do not fire, and a store's accessors hand out its decorators by
design — IssueClaimer recurses so that a CLI claim keeps its on_update — so
store.IssueClaimer() on bd's own chain (HookFiringStore ->
InstrumentedStorage -> raw) returns exactly the claimer that voids that
contract, silently, for as long as the process is up. The Config doc gave
that line verbatim as the intended pattern; it now names the store value to
take roles from instead, and storage.RoleFiresHooks lets checkDatabaseSource
refuse the other one at startup rather than trusting the paragraph.
The embedded-Dolt refusal keeps CLI-side enforcement, and the docs stop
grounding it in a structural fact it no longer has. It was structural while
Listen took a provider or nothing: there is no unit-of-work provider for
that backend, so an embedded-backed server was not constructible. The roles
source makes one constructible, and internal/httpapi cannot close that — a
role is an interface, and every check available at that layer is a
self-declaration by the same caller-supplied code being checked, which is
the trust it would be replacing rather than a replacement for it. So
serveModeGate is now the only enforcement point, and bd-serve-v0.md,
SERVE_RUNBOOK.md and serve.go say so plainly, with the permanence
re-grounded on the backend's commit protocol — a property of the backend
rather than of what has been written so far. The precondition a caller owns
is stated on Config.Reader/Claimer, and
TestServeBuildsOnlyAProviderBackedServer pins against cmd/bd's source that
bd names no database source but the provider that gate vouched for.
No wire change: internal/httpapi/spec and internal/httpapi/apigen are
untouched, and both new answers use codes v0 already publishes.
Agent-Signature: claude-opus-5
Co-authored-by: CI Bot <ci@beads.test>
---------
Co-authored-by: CI Bot <ci@beads.test>
Five comments added by this epic said a check was "the required PR job".
That is not true at the GitHub level and never was:
$ gh api repos/gastownhall/beads/branches/main/protection
{"message":"Branch not protected", ... "status":"404"}
$ gh api repos/gastownhall/beads/rules/branches/main
[{"type":"deletion", ...},{"type":"non_fast_forward", ...}]
main carries two org rules - no deletion, no force push - and no
required status check at all. Every gate in this epic therefore binds by
convention: a human merging on a red check is unimpeded.
The comments now say what is verifiable instead - the job runs on every
pull request, unconditionally, rather than in a shard only some pushes
reach - and doc.go states the enforcement limit once rather than five
times. Turning on branch protection is a repository-administration
action for the maintainer, not a code change, so nothing here attempts
it.
Left alone deliberately: the "required PR ... wrapper" strings in the
Makefile help text, `scripts/ci/pr-core.sh`'s header and the pre-existing
`CI Gate / Required` job name all predate this branch on origin/main and
are not this epic's claims to restate.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The frozen document says an invalid `metadata_field` key is a 400. It was a
500: the only check lived in the SQL builder, so the failure arrived wrapped in
the storage method's name ("GetReadyWorkWithCounts: invalid metadata key ...")
— a shape nothing above storage can classify — and client typos landed in the
request_error alarm stream. Three doc comments already claimed otherwise,
including the leaf contract's "Keys are validated inside", which no Reader
implementation did.
Both builders now call one validator, so the claim is true of every
implementation of the role rather than of the CLI's flag parsing only. The CLI
keeps its own usage errors: it validates the same input at flag-parse time and
reaches the builder with the keys already checked, so its messages and exit
codes are untouched.
invalidFilterParam gains the two prefixes, and every row of that switch — the
three that were already there included — is now driven end to end by
TestABuilderRefusalIsTheDocumentedBadRequest. `invalid issue type ` was pinned
nowhere before: rewording it in list.go turns ?type=bogus into a 500 and now
fails that test.
Reader is Lifecycle's read counterpart, built as its mirror image: a role in
the leaf `issueops` package, reached through a capability accessor on the
storage seam, implemented at the same six sites. `Storage` gains
`IssueReader() (issueops.Reader, error)` beside `IssueLifecycle()`, and the
governing rule holds — a new capability got a new role and a new accessor,
not four more methods on an existing one.
SUBSUME, NOT COMPOSE. Reader takes the whole high-level request and performs
filter and default construction INTERNALLY, supplying its own ConfigSource
from the store or unit of work it already holds. Under compose both front
doors would each build a ConfigSource, load config, call a builder and execute
— two callers again, which is the topology that shipped a bare IssueFilter to
a viewer and silently served in_progress rows as "ready". Under subsume the
ritual is not callable from a front door: handlers and RunE bodies can only
say rd.List(ctx, req), so the failure mode is unwritable rather than merely
discouraged.
The three read endpoints are implemented against the frozen OpenAPI v0
document and consume the accessor; the 501 stubs and their self-deleting
exemption list are gone. `bd show --json` reaches the same role through the
same accessor, resolving the canonical id first so fuzzy and cross-repo
lookup stay CLI-local.
The workapi builders are re-typed onto the leaf request types, so there is no
second params struct to drift; both recorded goldens replay byte-identical,
which is the proof the re-typing changed nothing.
Load-bearing details:
- `sort` is forwarded EXPLICITLY as priority when absent. The storage layer
reads an empty policy as hybrid, which demotes older high-priority work and
therefore changes the item SET once a limit truncates — while the document
still reads correctly. Pinned by a handler test on the recorded filter and
by the parity oracle's order assertion.
- The parity oracle compares FULL ITEM JSON, not id sets. An id-set oracle
passes while ready ships a bare Issue against the CLI's IssueWithCounts.
- internal/workapi no longer imports internal/storage/uow; it names the slice
of a unit of work it reads through, so the uow provider can implement the
role without closing an import cycle.
- internal/utils' cgo store test moves to an external test package for the
same reason, with its two unexported-symbol cases split out.
Verified: issueops is still a leaf (internal/types + stdlib only); the
protocol corpus is unchanged structurally and behaviourally under
BEADS_PROTOCOL_REQUIRE_DOLT=1; a real `bd serve` answers all six operations
against a real workspace with CLI and HTTP JSON identical field for field.
The k=v quoting predicate also stopped at 0x7F, and the claim route is
what makes that reachable: it records a refused request-body member name
(an arbitrary JSON string) and a refused Content-Type (where bytes
0x80-0xFF are legal obs-text) on the request line. An unquoted U+009B is
a CSI introducer, so tailing the server log was enough to hand an
attacker the operator's terminal.
The framing itself was never forgeable — newline, space, '"' and '=' were
already quoted — so this is bounded to escape-sequence injection into a
console. Invalid UTF-8 is checked separately because ContainsFunc sees
only U+FFFD for a raw obs-text byte, which is not a control character.
Five rows in TestLogValueQuotesInjectableText fail without the change,
each returning the payload unquoted.
POST /v0/beads/issues/{id}:claim is the one write in v0, and it replaces the
transitional 501 stub. The handler runs domain IssueUseCase.ClaimIssue inside a
caller-owned uow.RunTxResult — the single retry/commit implementation, which the
proxied CLI writes already use — and commits "bd serve: claim <id> by <actor>",
one storage commit per successful claim. A re-claim by the current holder
changes nothing, so it answers 200 with already_claimed and no commit at all: a
polling client cannot fill the history with empty ones.
The 409s are typed. `assignee` and `issue_status` come from a read inside the
claim's own transaction, never from parsing "already assigned to" or "claimed
by" out of a sentinel's message — which is what lets a client delete its
substring error classification. When that read fails the refusal still stands as
a 409; degrading it to a 500 would trade a precise answer for an unactionable
one.
Actor validation happens at the wire edge, before the CAS: trim, then refuse
empty, over 256 bytes, past the assignee column's 255 characters, or bearing a
control character. The domain layer rejects only actor == "", so a
whitespace-only or megabyte actor would otherwise reach the assignee column AND
the storage commit message, where an unvalidated newline forges audit-trail
lines. The body is refused the same way, with the offending member named:
application/json only (a JSON content type is not CORS-"simple", so a
cross-origin claim always meets a preflight this server never approves), one
known member, one JSON object, one megabyte.
The route pattern is a whole-segment wildcard, so every POST under
/v0/beads/issues/ reaches this handler. A segment that does not end in ":claim"
now gets the catch-all's 404 rather than being read as an id — the obligation
the skeleton recorded on that row, and the reason POST on the GET-only detail
path is not a claim of the issue it names.
uow.RunTxResult's per-attempt close switches to the detached-context pattern.
Close sends ROLLBACK and the transaction layer poisons the pinned connection
when that send fails, so closing with an already-canceled context burned one
session per client disconnect. Fixed in the one implementation, so the proxied
CLI writes inherit it.
Hooks do not fire and the per-command auto-commit globals are never touched,
seam-consistent with every proxied write today. The actor is caller-asserted
provenance for the audit trail, not authenticated identity: the CAS is a
correctness fence against concurrent claims, not an authorization boundary, and
the loopback-only bind is what bounds the blast radius. Both are stated in the
handler, because adoption depends on knowing them.
The claim row leaves the 501 exemption list; the three read stubs keep theirs,
and the list still fails the test the moment it outlives the last stub.
Verified against real Dolt: 12 concurrent claimants produce exactly one 200 and
11 typed 409s all naming the winner the database agrees on, dolt_log carries one
entry per successful claim and none for the idempotent re-claim, and
ClaimResponse.issue compares equal field-for-field to `bd update --claim
--json`[0] under an EMPTY allowlist.
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of CI Bot
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
TestSpecRouteParity compared the claim row's hand-declared specPath against
the document — a string the router never sees — while the pattern it actually
registers is /v0/beads/issues/{idop}. The link between the two was a comment.
A pattern that drifted (wrong prefix, wrong segment) would leave parity green
while the documented claim path 404d, and nothing stopped a future row from
setting specPath and detaching itself the same way. No test drove the literal
path either; stub coverage went through GET /v0/beads/ready.
Two checks now bound the exception rather than trusting it. Parity requires a
declaring row's pattern to be the documented path with its final segment
replaced by one single-segment wildcard — the only thing ServeMux cannot
spell — and rejects a declaration for a path that needs no exception at all.
TestClaimPathReachesItsHandler POSTs the documented path and asserts it lands
on claimIssue, which is the half no static check can do.
Both drift shapes were confirmed to fail: a typo'd prefix fails parity AND
404s the behavioral test; a needless specPath fails parity twice.
Also recorded on the claim row: while the handler is a stub the wildcard makes
POST /v0/beads/issues/{anything} answer 501, including the GET-only detail
path. Transitional, but the claim slice must 404 a segment that does not end
in ":claim" rather than reading it as an id, and that obligation was written
down nowhere.
And `bd serve --help` no longer sends operators to a readiness endpoint this
build answers 501 to without saying so. TestServeHelpTracksTheReadinessProbe
requires the caveat while ready.list is unimplemented and requires its DELETION
once the handler lands, like the 501 exemption list it mirrors.
Two blind spots in the observability floor, both on the paths an operator
reaches for first.
Connection-cap saturation was completely silent. netutil.LimitListener parks
Accept at 64 open connections, so further connections — including /healthz
probes, which need a fresh accept — wait in the kernel backlog with nothing on
stderr. liveConns was tracked and then reported only in the shutdown lines. At
3am "the API is hanging" from connection exhaustion is indistinguishable from
"no traffic": request lines simply stop. The semaphore got exactly this event;
the connection cap, which is the one wedge mode this slice can actually
exhibit, did not. connState now emits conn_cap_saturated on the edge (once per
exhaustion, re-armed when it clears), and conns rides the request and
semaphore lines so the climb is watchable beforehand.
Middleware 400s carried no attribution. A foreign-Host rejection logged
status=400 code=invalid_argument without the Host it refused — so an actual
DNS-rebinding probe, the very thing that check exists to stop, left no
server-side trace — and an unknown_parameter refusal never named the
parameter. No line carried RemoteAddr at all, so "which local process keeps
sending bad requests" needed tcpdump on a loopback service where the remote
port maps to a process via ss. Both refusals now record the refused value,
and every request line carries remote_addr. The injection-safe logValue
quoting was built for exactly these caller-controlled strings.
Also: `GET /healthz?=1` parses to a parameter whose name is the empty string,
and the response omitted `param` while the schema promises it on every 400
except an unparseable body. It is named now.
Tests: TestConnectionCapSaturationIsAnnounced (including the edge-trigger and
its re-arm), plus new assertions in TestRequestLogLine, TestHostHeaderAllowlist
and TestNoQueryParametersAccepted — all five fail without this change.
A client that hung up while queued on the semaphore, or during NewUOW, was
answered with 500 internal AND an event=request_error carrying
error="context canceled". acquire returns ctx.Err() on <-ctx.Done(),
ClassifyError deliberately keeps context.Canceled out of isUnavailable so it
falls through to CodeInternal, and failErr emits request_error for every
>=500. So on a saturated server — precisely when clients time out and hang up,
and precisely when an operator is watching — every impatient disconnect
inflated the 500 count and the error stream that gets alerted on.
failErr now recognizes context.Canceled and records a log-only outcome,
code=client_closed on the request line, with no request_error event. Nothing
about the wire changes: the status stays as classified and goes to a socket
nobody is reading. codeClientClosed is deliberately absent from codeStatus,
operationCodes and the document, so it cannot leak into the vocabulary.
An expired request deadline keeps the contract's specified 500/internal and
its request_error: nothing about it says the client left.
Test: TestClientHangupIsNotBookedAsAServerFault, both rows — the hangup row
fails without this change, the deadline row is the control that pins the
mapping that must not move.
A panicking handler left the contract by both doors. net/http's per-connection
recover printed an unstructured stack to stderr carrying no request_id, op or
path; the client got a dropped connection rather than the problem+json every
non-2xx byte is promised to be; and the event=request line — the observability
floor's one-line-per-request guarantee — was never written, because the
emission sat after next.ServeHTTP instead of in a defer. The one class of
failure where correlating a client report with a server log matters most was
the one class with no correlation at all.
withRequestContext now recovers: it logs event=panic with the request id and
the stack on one line, answers the generic 500 problem (static detail, panic
text to the log only, like every other 5xx), and emits the request line from a
defer so it survives any unwind. A panic with http.ErrAbortHandler keeps
net/http's documented silent-abort semantics — it gets its log line, then the
panic is handed back.
The safety properties already held and now have a regression test: the test
drives the real route() chain, so the deferred slot release runs during
unwinding and the slot is provably back afterwards.
Tests: TestPanickingHandlerStaysInTheContract (without the recover the panic
escapes the middleware entirely) and TestAbortHandlerPanicIsStillLogged.
route() releases the database slot when the handler returns, and the handler
returns only after writing the response body. WriteTimeout is deliberately
zero, the per-request deadline explicitly excludes the response write, and a
context deadline cannot interrupt a blocked ResponseWriter.Write in any case
— so a client that opened maxInflight requests and then stopped reading would
hold every slot, and every pinned SQL connection, until the process was
restarted. Later requests would be shed with 503 busy and a semaphore_timeout
event, so the wedge is observable; the holders were simply immortal, and
/healthz stays green throughout. That is the same black hole the semaphore's
bounded wait exists to prevent, moved from the database to the socket.
The header, read and idle timeouts do not cover this. They bound request
reading and keep-alive idle; the comment claiming otherwise is corrected.
statusWriter now rolls a write deadline forward before every write via
http.ResponseController. That bounds each WRITE rather than the transfer, so
`limit=0` can still stream an unlimited body to a client that keeps reading
— the reason there is no WriteTimeout — while a stalled one errors the
handler out and lets the deferred release and rollback run. Unreachable in
this slice (every body here fits in net/http's buffers); it lands with the
envelope decision because the read slices inherit both.
Test: TestStalledResponseWriteReleasesItsSlot drives a streaming handler
through the real route() chain against a client that never reads, and asserts
the slot comes back. Without the deadline it fails after 20s with the handler
still blocked in write.
A wildcard non-loopback bind disabled the Host allowlist entirely, which is
the most common spelling of --allow-non-loopback and exactly the deployment
DNS rebinding still targets: reachability by the operator's LAN is not the
same as reachability by the attacker, who rides an inside victim's browser
through the firewall — and the disabled check also dropped the defense on the
serving host's own loopback interface, rebinding's canonical target.
A wildcard bind now allows any numeric IP literal instead of allowing
anything. A rebound page cannot produce an IP-literal Host: the browser sends
the hostname from the attacker's URL, and fetching an IP URL directly is a
direct connection, which is the exposure --allow-non-loopback already
accepted. Foreign names stay refused on every bind shape.
Two more holes in the same policy, both fail-closed but both traps:
- a specific loopback bind (127.0.0.2, which ValidateBindAddr blesses and
the tests pin) never allowed its own address, so the server 400d every
client that dialed the address it was configured with;
- the allowlist matched IP text, so `[0:0:0:0:0:0:0:1]` and
`[::ffff:127.0.0.1]` were refused as if they were foreign names.
Both are gone: the policy holds parsed addresses and matches with net.IP.Equal,
so every spelling of an allowed address is that address.
The allowlist is now a hostPolicy value with no off switch, and the startup
line states it in full rather than reporting "disabled".
Tests: TestHostPolicyPerBindAddress drives all five bind shapes (fails on the
wildcard, alternate-loopback and long-form-IPv6 rows without this change) and
TestAlternateLoopbackBindAnswersItsOwnClients is the end-to-end half over a
real 127.0.0.2 listener.
The first slice that runs a server. Proxied-server workspaces go live; the
read and claim operations are registered as transitional 501 stubs so route
and spec parity can be proved all at once instead of growing a hole per slice.
`bd serve --addr 127.0.0.1:0 [--allow-non-loopback]`, and no other flags in
v0. The bound address is stdout's first line, because under the ephemeral
default it is the only way to find the port. Shutdown rides the signal context
the root command already installs. No lock file, pid file or discovery file:
serve is operator-invoked and the TCP bind IS the mutual exclusion — dbproxy
needs that machinery only because clients race to auto-spawn it.
The mode gate says two different things, deliberately. Embedded is a PERMANENT
typed storage.ErrUnsupported: there is no unit-of-work provider for that
backend. Dolt server mode is STAGED — the provider construction exists and is
tested, it just is not wired in yet — so the text names what works today and
says this does not, rather than reading as an architectural limit that would
send an operator off to change their topology for nothing.
One unit of work per request, closed through a DETACHED context. The
transaction layer poisons the pinned connection when a ROLLBACK send fails
(doltserver_tx.go), so closing with the request's own canceled context would
burn a session on every client disconnect.
Front-tier hardening lands here, not later, because without it a hung Dolt
becomes a silently growing black hole: slots fill with immortal queries,
/healthz stays green because it never touches the database, and recovery
produces a thundering herd. So: a Host-header allowlist (DNS-rebinding defense
for an unauthenticated, browser-reachable loopback service), a
netutil.LimitListener connection cap (Go spawns a goroutine per connection, so
the database semaphore alone does not bound what is accepted), a database
semaphore with a BOUNDED 10s wait mapping to the already-documented 503 busy,
a 60s per-request deadline, and explicit pool limits on the provider's *sql.DB
via a new uow.PoolTuner knob — openDB set none, and database/sql's default is
unlimited.
/v0/beads/context serializes an explicit ten-field allowlist and nothing else.
SyncRemote is hard-excluded in this and every future version: it is populated
unconditionally from config sync.remote, and remote URLs routinely embed
credentials. The database bind endpoint and the remaining absolute host paths
are excluded too. `capabilities` is derived from IMPLEMENTED handlers only, so
a release cut between this slice and the endpoint slices advertises only what
actually works.
The observability floor is an acceptance criterion, not a convention: one
structured stderr line per request (method, path, status, problem code,
duration, semaphore wait, unit-of-work acquire), startup and shutdown lines, a
semaphore-saturation event, and a request_id on every problem response. That
last one required documenting request_id on the spec's Problem schema — the
only spec edit here, additive, with types regenerated.
Decisions implemented as given: hooks do not fire (a user-controlled
subprocess per mutation is an unbounded latency multiplier and an orphaned
child at shutdown); the per-command auto-commit globals are never touched
(nothing to exclude — proxied PersistentPostRunE only closes the provider);
and actor on an HTTP request stays caller-asserted provenance, which the
context and capabilities wording does not contradict.
Tests: TestSpecRouteParity asserts set equality between the route table and
the document's paths, and builds the real mux so a pattern ServeMux would
refuse fails here rather than on the first request.
TestSpecStatusCodesMatchHandlerTable carries a commented, enumerated 501
exemption that is self-deleting — it fails if the route table and the list
disagree, and fails again if the list outlives the last stub. The context
allowlist is enforced from the handler out, over a body built from a snapshot
with every field populated and a credential-bearing sync remote.
TestWithUOWClosesWithADetachedContext records the close context's state AT
close time, which is the only moment it says anything.
Verified: build, vet and golangci-lint clean (the two gosec findings in
cmd/bd/main.go pre-date this change); internal/httpapi green under -race;
protocol corpus byte-identical with BEADS_PROTOCOL_REQUIRE_DOLT=1; and a real
server started against a proxied workspace, answered both endpoints, refused
a foreign Host, an unknown query key and a second bind, and drained to exit 0
on SIGTERM.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>