Commit graph

135 commits

Author SHA1 Message Date
Julian Knutsen
dbaa4631ca
feat(roles): BatchGetter role and POST issues:batchGet (#7248)
* feat(roles): BatchGetter role and issues:batchGet route (S7)

Adds BatchGetter.GetMany(ids) -> {Issues, Missing}, a one-snapshot,
order-preserving, deduped, 1000-id-capped batch read, wired through all
three library legs (dolt, embedded dolt, uow) behind the existing
hook/telemetry decorator chain, plus the POST /v0/beads/issues:batchGet
HTTP route (spec, apigen, wire-shape golden, issues.batchGet capability
token). Conformance contract (RunBatchGetter*, 12 cases) passes on all
three legs against real backends. No HTTP client leg yet (waits on the
generator / PR #7247); left as a documented seam on BatchGetter's doc
comment.

CLI GetIssuesByIDs call sites are left unmigrated this slice and marked
with TODO(batchgetter) comments: every call site reads an unbounded id
list today, and GetMany's 1000-id cap has no chunking/fallback in any
caller yet, so swapping them in now would add a new, unhandled failure
mode to already-shipped CLI paths (export, import, molecule port,
ready-explain, wisp sweep).

Verified via three live-mutate guards against
internal/storage/issueops/batchget.go (disabling the cap check, dropping
the Missing append, and replacing ordered iteration with map iteration):
each turns the embedded-dolt contract red, confirming the cap, Missing
reporting, and order-preservation assertions actually catch a break.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(roles): close S7 review gaps — revision on wire, BUILD sync, handler tests

Addresses the S7 Opus review's FIX-FIRST items on BatchGetter/issues:batchGet:

HIGH
- batchGetResponse now projects apigen.BatchGetIssue (types.BatchGetIssue +
  NewBatchGetIssue), carrying `revision` per issue the way IssueDetails does;
  spec, apigen and the wire-shape golden regenerated (additive, no
  wire_revision bump).
- make bazel-sync: the 12 files missing from BUILD.bazel srcs are back in
  sync across 9 BUILD.bazel files.
- New internal/httpapi/batch_get_test.go: success incl. revision, missing
  ids, empty arrays not null, unknown member refused, missing/null ids
  refused, query parameter refused, 1001 ids refused with the full request
  reaching the role, 1000 ids accepted.

MED
- RunBatchGetterAcceptsExactlyTheCap pins the cap boundary (> vs >=).
- RunBatchGetterHydratesLabels pins Labels survive projection.
- RunBatchGetterReadsOneSnapshot renamed to
  RunBatchGetterSharesOneReadStructurally with a doc that no longer
  overclaims atomicity; a real interleaving test needs a hook on the frozen
  roleFixtureKit, out of scope here.
- Doc comments across ExecuteGetMany, GetManyResult.Issues and the
  BatchGetter interface now say hydration is labels only.

LOW
- failBatchGetErr's doc no longer claims blank entries are "already caught".
- PR #7247 references kept.

Re-ran build/vet/gofmt/lint, make api-check, make bazel-sync(-check), the
full internal/httpapi suite, and all three conformance legs (dolt via the
pinned local server, embeddeddolt, uow) plus targeted cmd/bd serve tests —
all green. Live-mutate-guard reverified: cap >=, dropping Missing from the
response, and clearing Labels each now fail the relevant test.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(roles): sync client vocabulary and repo gates with issues:batchGet

The S7 route landed on the server without the sibling tables that hold
the rest of the tree set-equal with the server's surface, so five
tests and two manifest gates went red on the PR head:

- httpclient/wire: mirror batchGetIssues into the client vocabulary,
  CLASSIFIED, not wired, the way the wire wave and #7250's
  issues.count.scope landed: OpBatchGetIssues, its issues.batchGet
  token on opCapability, its identity row, and the first-slice skew
  dimension 35 -> 36 (TestCapabilityTableMatchesTheServerRouteTable).
- httpclient/wire: BatchGetIssue is the first golden.json schema with
  a `revision` member that needs no legacy-integer tolerance — the
  route postdates #6053 and types.BatchGetIssue declares Revision a
  string, and a pre-#6053 server never advertises issues.batchGet, so
  Preflight refuses before any body is decoded. Exempt it with that
  reason in a new revisionSchemaExempt table rather than adding an
  issues[] rewrite no legacy server can reach; the gate refuses an
  entry that is both covered and exempt, a stale exemption, and an
  empty reason.
- httpclient/encode: give the oracle's role set a BatchGetter stub —
  httpapi.Listen requires the whole set, so all three oracle tests
  failed to bind.
- storage/uow: exempt IssueUseCase.GetMany from the notifying-parity
  partition as a read, the reason hook_batch_getter.go gives.
- shard manifest: place TestBatchGetterContract in the 15-shard
  embedded storage block (generator --write, incremental).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(roles): pin the BatchGetter pure tier and the spec ids caps

Review fixes, iteration 1. The review approved with no blocker or major
finding and three minors, and this commit takes all three. It changes
tests and one comment only, and every new assertion was mutation-probed
with go test -overlay.

- storage/issueops: add batchget_test.go, the database-free tier that
  FinishGetMany's doc already claimed ("pinned without a database") but
  that no test supplied. It pins:
  - the cap is checked before the blank scan (an over-cap request with
    a blank at position 0 answers *TooManyIDsError);
  - the bound is inclusive;
  - dedupe keeps the first mention, does not trim, and never writes
    through the caller's slice;
  - Issues and Missing both follow request order;
  - both slices are never nil;
  - ExecuteGetMany refuses one id repeated past the cap before any
    query (a sqlmock with no expectations).
  Ten mutants were each killed by exactly their intended test, with the
  rest of the package green: last-mention, sort, trim, in-place dedupe,
  blank-before-cap, >=, nil Missing, nil Issues, dedupe-before-validate
  and validate-after-query.
- httpapi: TestSpecDefaultsMatchSharedConstants now checks ids.maxItems
  against the enforced bound on the two request bodies that carry an
  `ids` list: batchGetIssues against issueops.MaxGetManyIDs, and
  deleteIssues against maxDeleteIDs. Each body is reached through its
  operation's own requestBody $ref. Setting either constant to 999 turns
  only this test red. The spec's other list caps (batch
  create/close/apply items, dependency edge lists) stay ungated, as
  before.
- cmd/bd/serve.go: the batchGetter field comment said its accessor
  "does NOT recurse through the hook decorator". HookFiringStore.
  BatchGetter does recurse to the inner getter; it just doesn't wrap
  the result. The comment now says that.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-05 12:09:18 -07:00
Julian Knutsen
6d7fecaa3e
feat(httpclient): OSS HTTP client wire/encode layers (contributed from bd-enterprise under MIT) (#7210)
* 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(httpclient): lift the HTTP client wire/encode layers from bd-enterprise (MIT contribution)

Contributed by gascity from bd-enterprise (github.com/gascity/bd-enterprise,
internal/enterprise/httpstore @ 49d1df2f6) to OSS beads under the MIT
license, with the owner's explicit approval. Every lifted file carries a
provenance header naming its source path.

Lifted into internal/httpclient:
- wire/    the HTTP transport, lazy handshake, project-identity stamping,
           problem-code decoding, retry behaviour and the capability vocabulary
- encode/  request/response encoders for the role operations
- credential*.go, ca*.go, target*.go   the bearer credential ladder,
           host-scoped CA trust and the http_target.json sidecar

Not lifted (stays enterprise-only): the hosted gateway (httpgw/gwauth),
box-login, storage profiles and gasworks.

Deferred to later slices (kept aside, not in this tree): the store transport
seam (WireClient/WireDialer/process-wide dialer, which goes to S3 with
dial.go), the enterprise-only BatchCloseRequest.claim_next encoder
(ClaimNextBody; the OSS server has no claim_next on batch close), and the
tests that need the store/dial layer.

This commit is the mechanical lift: import paths rewritten, package renamed,
two compile gaps removed. The production code builds. Known follow-up in the
next commit: reconcile the client's vocabularies and encoder tables with the
OSS spec (e.g. the OSS problem code notes_overwrite_refused, policy/sort
differences), restore the test helpers the lifted tests need, and wire in the
S0 wire_revision handling and S1 OpenOptions credentials.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(httpclient): compile the lifted client and reconcile with the OSS wire

The lift in ab11cb1f8 carried relative test paths and vocabulary tables
from bd-enterprise's internal/enterprise/httpstore (4 directories below
repo root) into internal/httpclient (3 below), and several tables
described enterprise-only server behavior OSS does not serve. Reconcile:

- Add testTarget test helper (written fresh) so internal/httpclient
  compiles and its tests pass.
- Fix four relative paths off by one "../" from the package relocation
  (skew_test.go, ledger_render_test.go, bijection_test.go x2).
- skew_test.go: importsHTTPClient now matches internal/httpclient instead
  of the retired internal/enterprise/httpstore path; the cmd/bd sweep no
  longer hard-fails when it legitimately finds zero matching files (cmd/bd
  does not import this client yet - that's S3's wiring).
- encode/table.go, encode/ledger_fields.go: removed a Reserved "reverse"
  entry and a refused ExcludeIDs field claimed for listIssues/ReadyRequest;
  OSS's listIssues never accepts "reverse" (confirmed against
  internal/httpapi/reads.go and routes.go's CapIssuesListSort, which gates
  `sort` only) and issueops.ReadyRequest carries no ExcludeIDs member in
  OSS. Each removal is documented in place.
- encode/table.go, encode/encode.go, encode/roundtrip_test.go: countIssues
  publishes has_metadata_key and include_ephemeral that CountRequest
  carries and the table/encoder/round-trip corpus all silently dropped;
  mapped and wired through.
- encode/ledger.go: ~70 ledger rows cited enterprise store-conformance and
  cmd/bd subprocess-parity tests (dual-run reader, claim races, flag-mode
  refusals) that don't exist in this package and belong to S3's store/dial
  seam and cmd/bd wiring. Re-pinned to a documented TODO(S3) sentinel
  (pinnedByS3Conformance) rather than deleted, per the ledger's own
  well-formedness discipline.
- wire/handshake.go, wire/vocabulary_test.go: added CapBatchApplyLarge
  (issues.batchApplyLarge) alongside the server's behaviorCapabilities.
- wire/problem.go: mapped the notes_overwrite_refused problem code to
  issueops.ErrNotesOverwrite.

internal/httpclient/... is fully green.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* feat(httpclient): wire-revision handshake gate and batch cap from capability

S0 integration (task #2): Client.Handshake now reads ContextResponse's
wire_revision/min_client_wire_revision and refuses with a typed
*WireRevisionSkewError before any post-handshake call when the server's wire
shape falls outside [ClientMinWireRevision, ClientWireRevision] -- mirroring
DESIGN.txt sec 4's "Client rule". A decoded 0 is treated as "the server
omitted the member" per the permanently-retired-values rule, never as a value
needing refusal. The client now also stamps Bd-Wire-Revision on every request
(client.go's stampRequest), and problem.go gained the per-request mirror:
*WireRevisionUnsupportedError, decoded from the reason:"wire_revision_unsupported"
extension members, for the case where the SERVER refuses this client's
declared revision as too old. Both error types are deliberately distinct --
one is this client declining after reading a 200, the other is the server
refusing a request outright -- and neither branches on bd_version (only
assigns it into error text), so TestNoFeatureBranchesOnBdVersionOrSchemaVersion
stays green.

Also added legacyRevisionFields/decodeRevisionToken to problem.go: a
precondition_failed refusal's expected_version/actual_version, typed *string
on the generated Problem, now tolerates a pre-#6053 server sending either as a
bare JSON integer rather than the decimal string every server since has used,
recovering the field the primary decode silently drops rather than losing it.

Batch cap (task #3): ApplyBatch reads the handshake snapshot on every call and
enforces 100 items unless the server advertises issues.batchApplyLarge, in
which case the ceiling is issueops.MaxApplyBatchItems (1000) -- never a bare
compiled constant. A plan over the applicable cap refuses before the dial: via
the existing *CapabilityError machinery when advertising the capability would
help (D7 case 2), or via a new *BatchTooLargeError (unwraps to
issueops.ErrValidation) when it would not. BatchTooLargeError lives in
handshake.go rather than beside ApplyBatch because every exported method in
writes.go is swept by TestEveryOperationMethodRoutesThroughTheSharedDispatch as
an operation-dispatch method.

All three internal/httpclient/... packages build and `go test` passes with
TMPDIR=/data/projects/.scratch/s2t BEADS_TEST_SKIP=dolt.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* feat(httpclient): REQUIRE-mode credential resolution bridge to backends.Credential

Task #4: adds the knob internal/storage/backends/backends.go's OpenOptions.Credential
doc explicitly deferred ("S1 does not add a RequireCredential knob to enforce
the multi-tenant rule mechanically -- that is deferred to S2").

ProvidedCredential wraps an embedder-supplied wire.CredentialProvider (via its
httpclient alias) as a backends.Credential, so a multi-tenant embedder (for
example gc, Gas City: one process serving many workspaces) can carry a
per-workspace credential through backends.OpenOptions without the backends
package needing to know this package's CredentialProvider shape.

ResolveCredential(opts, base, require) is the bridge itself:
  - nil Credential, require=false: NewBearerProvider(base), the existing
    single-tenant ambient bearer ladder (unchanged).
  - nil Credential, require=true: ErrCredentialRequired -- the multi-tenant
    fail-closed case backends.go's doc names: a missing per-workspace
    credential must be a loud refusal, not a silent fall-through to
    process-global ambient env that cannot tell one tenant's workspace from
    another's.
  - a ProvidedCredential with a non-nil Provider: returned directly,
    regardless of require.
  - a ProvidedCredential with a nil Provider, or any other
    backends.Credential this package does not recognise: refused -- the
    former as ErrCredentialRequired (a present-but-empty wrapper must not
    look like "a credential was supplied"), the latter wrapping
    backends.ErrUnsupportedCredential per the OpenWith contract
    internal/storage/backends/open_with_test.go already pins
    (TestBackendOpenWithRefusesUnsupportedCredentialType).

No bd-enterprise source was copied for this file; it is new code written
against the OSS backends.go contract and the existing BearerProvider/
CredentialProvider types already lifted into this package. Live-mutated all
three guards (the require branch, the ProvidedCredential type assertion, and
the nil-Provider check) and confirmed each produces a RED test before
reverting.

go build/vet/gofmt clean; `go test ./internal/httpclient/...` passes with
TMPDIR=/data/projects/.scratch/s2t BEADS_TEST_SKIP=dolt.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* test(httpclient): S2 task #6 wire-revision/legacy-decode coverage, fix legacyRevisionFields bug

Add httptest coverage for the two wire-revision mechanisms task #2 added
(commit 7ff68b29d8):

- handshake_wire_revision_test.go: the client-initiated skew gate
  (checkWireRevision/WireRevisionSkewError) and the per-request
  Bd-Wire-Revision header stamp. Live-mutated both switch arms in
  checkWireRevision and the stamped header value; confirmed RED, reverted.

- problem_wire_revision_test.go: the server-initiated
  wire_revision_unsupported refusal (reason-before-code dispatch priority)
  and the legacy-integer revision-token fallback.

Writing the legacy-decode tests surfaced a real bug in legacyRevisionFields:
its presence guard treated any non-nil *string field as "already decoded,"
but encoding/json's indirect() pre-allocates a pointer to "" for a *string
field before discovering a type mismatch (e.g. a bare JSON integer). A
type-mismatched expected_version/actual_version therefore arrived as a
non-nil pointer to the empty string, not nil -- exactly the one case the
fallback exists to recover, and exactly the case the old guard skipped.
Fixed by adding revisionNeedsFallback(p) (nil-or-empty), used in place of
the bare nil checks. No legitimate server response uses a literal
empty-string revision token, so this changes no other behavior.
Live-mutated the fixed guard back to the old nil-only checks; confirmed RED
on both recovery tests, reverted.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* test(httpclient): S2 task #6 ApplyBatch item-cap coverage

Add writes_batch_cap_test.go: httptest coverage for ApplyBatch's
capability-gated item ceiling (task #3), separate from the generic
two-speed "is issues.batchApply routed at all" gate writes_twospeed_test.go
already covers.

Cases: at-or-under the 100-item floor succeeds without the capability;
over the floor without issues.batchApplyLarge refuses with a
*CapabilityError before any dial past the handshake; the capability raises
the ceiling to issueops.MaxApplyBatchItems (1000), both at the new ceiling
and strictly between the old floor and it; over the absolute ceiling
refuses with *BatchTooLargeError regardless of the capability, also
without dialing the batch-apply endpoint.

Live-mutated all three guards in ApplyBatch (the limit computation, the
n > limit check, and the capability-vs-absolute-ceiling branch); confirmed
each produces a distinct RED, reverted.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* test(httpclient): S2 task #6 live TLS coverage for wrong-CA refusal

Add ca_wrong_ca_test.go: an end-to-end httptest TLS dial proving
TransportFor's configured CA pool is actually enforced at the wire, not
just recorded on the transport struct. ca_test.go already proves the
latter (TestTransportForReplacesRootPoolNotExtends, via
x509.CertPool.Equal) and proves the RIGHT CA dials successfully
(TestTransportForFileRotationClosesSupersededIdleConnections's live GETs);
neither exercises a server whose leaf a DIFFERENT CA signed.

TestTransportForWrongCARefusesTheTLSHandshake dials a server through a
transport built from an unrelated CA file and asserts the handshake fails
with x509.UnknownAuthorityError. TestTransportForRightCASucceedsOverTLS is
the positive control, using the same (newly-exercised) ca.startServer
helper that was defined but had no caller before this test -- without it,
a mutation that drops RootCAs entirely (falling back to the system pool)
would still pass the wrong-CA test for the wrong reason; the positive
control catches that case. Live-mutated transportForFile to drop RootCAs;
confirmed the positive control goes RED, reverted.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* build(bazel): gazelle BUILD files for the lifted httpclient package tree

Task #7: bazel run //:gazelle, now that internal/httpclient and its
encode/wire subpackages exist in the OSS tree (ab11cb1f8) and have gained
this S2 slice's new files. No existing BUILD.bazel files changed; these
three packages previously had none.

Note for S3: bazel test //internal/httpclient/... fails on tests that read
sibling source trees by relative path at runtime
(TestLedgerRowsAreWellFormed, TestEveryEncoderTableParameterIsPublished,
TestDivergenceLedgerDocMatchesLedger in encode, and
TestNoFeatureBranchesOnBdVersionOrSchemaVersion,
TestEveryOperationMethodRoutesThroughTheSharedDispatch,
TestEveryOperationMethodIsCoveredByTheTwoSpeedTable in wire) -- paths like
../../../cmd/bd and ../../httpapi/spec/openapi.v0.yaml resolve under `go
test`'s working directory but not Bazel's sandbox, which gazelle cannot
infer `data` attributes for. Pre-existing in code from task #1/#2, not
introduced by this commit; `go test ./internal/httpclient/...`,
`go vet ./...`, `gofmt -l .`, `golangci-lint run ./internal/httpclient/...`,
and `make api-check` are all clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(httpclient/wire): tolerate bare-integer revision on success-path responses

Review HIGH #2: against a fake pre-#6053 server (one whose ContextResponse
omits wire_revision), CloseIssue and its revision-bearing siblings
(ApplyBatch, ReleaseIssue, ReopenIssue, UpdateIssue) failed with an untyped
`json: cannot unmarshal number ... revision of type string`. S0's
string-or-number tolerance (problem.go's legacyRevisionFields) only covered
the problem+json error path, never the success path.

Adds revision_tolerance.go: a pre-unmarshal rewrite that walks a response
body and turns a bare JSON number at a "revision" key into its exact decimal
string, scoped to the five apigen response types that carry the member and
gated on the handshake having seen no wire_revision at all. Left
apigen/types.gen.go and the OpenAPI spec untouched (both are
regenerate-and-diff gated by `make api-check`), rather than introducing a
custom Revision JSON type through codegen, to keep the fix's blast radius to
the wire package's own reader.

Updates ClientMinWireRevision's doc comment (handshake.go) to describe
tolerance on both halves of the wire instead of overclaiming the error-path
fix alone covered it. Adds revision_tolerance_test.go: a read (ListReadyWork)
and a guarded write (CloseIssue with ExpectedVersion) against a fake
pre-#6053 server, plus a modern-server control proving the rewrite never
fires when wire_revision is present. Mutation-tested: disabling the rewrite
reproduces the exact untyped UnmarshalTypeError the review reported.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* build(bazel): sandbox internal/httpclient's source-reading tests (Bazel gate green)

Review HIGH #1: the Bazel lane was red because three tests under
internal/httpclient read sibling/cross-package files by relative OS path at
runtime, which bazel test's sandbox does not materialize without an explicit
`data` dependency.

- internal/httpclient/encode/BUILD.bazel: encode_test gets
  data = ["//cmd/bd:go_srcs", "//internal/httpapi/spec:openapi.v0.yaml",
  "//:engdocs/design/http-divergence-ledger.md"] + glob(["*.go"]), covering
  bijection_test.go's cmd/bd scan and ledger_render_test.go's golden-doc read.
- internal/httpclient/wire/BUILD.bazel: wire_test gets
  data = ["//cmd/bd:go_srcs", "//internal/httpclient:go_srcs"] + glob(["*.go"]),
  covering skew_test.go's AST sweep of both trees.
- internal/httpclient/BUILD.bazel gains a go_srcs filegroup via `make
  bazel-sync` (tools/bazel/go_srcs.py): added "internal/httpclient" to the
  script's managed PACKAGES list rather than hand-writing the block.
- internal/httpapi/spec/BUILD.bazel and the root BUILD.bazel gain
  exports_files for openapi.v0.yaml and engdocs/design/http-divergence-ledger.md,
  scoped to //internal/httpclient/encode:__pkg__.
- bijection_test.go's loadPublishedParameters now reads the wire contract
  through spec.OpenAPIV0() (the package's existing go:embed) instead of a
  relative os.ReadFile path, per review suggestion -- the embed makes the
  parameter set reachable without a `data` dependency on the YAML at all; the
  openapi.v0.yaml data entry above stays as defense in depth for any other
  reader the package gains.

Ran via `bazel run //:gazelle` then `python3 tools/bazel/go_srcs.py`
(bazel-sync-check passes). `bazel test //internal/httpclient/...` is fully
green: 3/3 test targets pass.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* docs(httpclient): scrub private/enterprise infra references from code and docs

Review MEDIUM #3. Provenance headers ("Contributed by gascity from
bd-enterprise...") stay by design -- this removes references to private
infrastructure and unported internals from comment bodies and generated docs:

- wire/doc.go: dropped the internal/enterprise/hostedbeads and
  internal/enterprise/storageprofile build-tag comparison (neither exists in
  this OSS tree) and the dangling citation of the never-written
  engdocs/design/http-client-backend.md, replacing both with an accurate
  description of this package's own build-tag-free status and a pointer to
  the divergence ledger that does exist.
- credential.go: CredentialProvider's doc no longer names gwauth/DPoP/gateway
  auto-detection by their private spelling; describes the interface generically.
- ca.go: dropped "cherry-to-AWS RTT" (generalized to "a typical cross-region
  RTT") and the cmd/bd/enterprise_connect.go file reference (generalized to
  "a `bd connect --ca-file X`-style command").
- ca_permissions_unix.go / ca_permissions_unix_test.go: ~/.config/gascity and
  /etc/gascity example paths replaced with ~/.config/bd and /etc/bd.
- encode/skew_test.go: beads.corp replaced with bd.example.invalid.
- encode/ledger_render.go + ledger_render_test.go: the generated-doc preamble
  and regenerate-hint strings now name internal/httpclient/encode (this
  package) instead of internal/enterprise/httpstore/encode; regenerated
  engdocs/design/http-divergence-ledger.md via `go test
  ./internal/httpclient/encode -run TestDivergenceLedgerDocMatchesLedger
  -update-ledger-doc` rather than hand-editing it.

Final grep for enterprise/cherry/gascity/corp/gwauth under internal/httpclient
and engdocs turns up only: provenance headers (kept deliberately), this
session's own "no bd-enterprise source copied" disclaimers, and a handful of
generic "enterprise-tagged"/"enterprise server" references describing a
build-tag or commercial-tier server concept in the abstract -- none name a
private host, path, or credential.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* test(httpclient): review LOW items -- S3 TODO, env-driven CA test, lockstep doc

Review LOW #4-#6:

- wire/skew_test.go: TODO(S3) on the branch where the cmd/bd AST sweep is
  vacuous (no store/dial wiring yet), naming the slice that closes it.
- ca_wrong_ca_test.go: TestTransportForWrongCAViaEnvRefusesTheTLSHandshake,
  the BEADS_HTTP_CA_FILE env-driven sibling of the existing direct-CAFile
  wrong-CA test -- same live-TLS refusal, resolved through resolveCAFile's
  host-scoped env syntax instead of Target.CAFile.
- vocabulary_test.go: expanded the ClientWireRevision/CurrentWireRevision
  comment to explain why this repo holds them in strict lockstep (client and
  server ship from the same commit) rather than merely <=, distinguishing it
  from the real cross-version compatibility ClientMinWireRevision exists for.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(httpclient/wire): re-review HIGH-a/b -- cover IssueDetails, stop recursing into metadata

HIGH-a: the legacy-revision set was missing apigen.IssueDetails (GET
/v0/beads/issues/{id}'s body, an alias for types.IssueDetails that a grep for
"type ... struct" never sees). getIssue is a baseline op that can dispatch
with no cached handshake at all, so serverPredatesRevisionStrings now treats
"no snapshot" the same as "WireRevision == 0" instead of only the latter.
revisionBearingResponse's set is now pinned exhaustively against
internal/httpapi/wireshape/testdata/golden.json -- the same committed digest
TestWireShapeDigest guards -- by a new test
(TestRevisionBearingResponseCoversEveryWireShapeSchemaWithARevisionMember), so
a future schema gaining a `revision` member can't silently miss coverage
again. New coverage: both "with" and "without" a prior handshake for getIssue,
and an explicit items[].revision test for ApplyBatchResponse.

HIGH-b: the previous fix recursed into every nested object looking for a
bare-number "revision" key, which reached caller-owned blobs like
CloseIssueResponse.issue.metadata -- real user data shaped like
{"revision":3} came back silently coerced to a string, on every server the
broadened gate above now also covers. tolerateLegacyRevisionNumbers no longer
recurses at all: it rewrites only the body's own top-level "revision", and,
for *apigen.ApplyBatchResponse specifically, each item's top-level
"revision" in the top-level "items" array. New
TestCloseIssueLegacyRewriteNeverTouchesIssueMetadata proves a metadata
document with "revision" keys at three nesting depths round-trips
byte-for-byte unchanged.

Mutation-tested both guards by hand (not committed): dropping the
IssueDetails case turns TestRevisionBearingResponseCoversEveryWireShapeSchemaWithARevisionMember
and both getIssue tests red with the exact missing-coverage/decode-failure
messages; reinstating a fully recursive rewrite turns
TestCloseIssueLegacyRewriteNeverTouchesIssueMetadata red, showing the
metadata's revision keys silently rewritten at all three depths. Both
reverted clean before this commit.

internal/httpapi/wireshape/BUILD.bazel and internal/httpclient/wire/BUILD.bazel
export/declare testdata/golden.json as data for wire_test's new exhaustiveness
test.

Verified: go test ./internal/httpclient/... (ok, one pre-existing unrelated
flake in ca_wrong_ca_test.go confirmed not reproducible across 8 reruns),
golangci-lint run ./internal/httpclient/... (0 issues), make api-check (no
apigen drift), bazel test //internal/httpclient/... //internal/httpapi/wireshape/...
(5/5 PASSED).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(httpclient): stop the wrong-CA TLS tests racing Happy Eyeballs

Root cause: startServer rewrites its httptest TLS server's URL to the
hostname "localhost" so SNI is actually sent, but the server itself only
binds 127.0.0.1. net/http's default dialer does RFC 6555 Happy Eyeballs
for a hostname with more than one address family, racing a tcp6 dial to
::1:<port> against the real tcp4 dial. On this host, many unrelated
processes (JVM tooling) are bound to high ::1 ports, so the tcp6 race
occasionally "won" against a listener that had nothing to do with the
test, and the client spoke TLS to it instead -- surfacing as "tls: first
record does not look like a TLS handshake" rather than the expected
x509.UnknownAuthorityError. Confirmed via ss -tlnp captured at the moment
of failure (a java process holding the exact port raced) and via an
immediate manual redial to 127.0.0.1 on that port succeeding against the
real, still-live test server.

Fix: forceIPv4Loopback (new shared helper in ca_test.go) rewrites the
returned *http.Transport's DialContext to dial tcp4 only. SNI and the
request Host are unaffected, since crypto/tls and net/http derive both
from the URL, never from which address family carried the bytes. Wired
into every TLS fixture test in the package (ca_wrong_ca_test.go's three
tests, and ca_test.go's rotation test) -- grepped the rest of the repo
for the same "rewrite to localhost for SNI" pattern and found no other
occurrences.

Also fixed a latent bug this surfaced: TestTransportForWrongCAViaEnvRefusesTheTLSHandshake
called TransportFor(Target{}) with a nil BaseURL, so caHostMatches always
returned false and the CAFileEnv path was never actually exercised --
the nil RoundTripper was silently masked by http.Client's fallback to
http.DefaultTransport, which also failed to verify (via system roots)
for an unrelated reason. Now passes Target{BaseURL: u} so the test
exercises the host-scoped env-resolution path it documents.

go test -race -count=50 -run WrongCA: 8/8 clean. Whole package
go test -race -count=20: clean, twice. bazel test, golangci-lint,
make api-check: all green.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(httpclient): repair CI-red tests and apply review fixes (adopt-pr #7210)

Three defects on the contributor head, none of them present on the base:

- test/docsync's TestEngdocsAndRootMarkdownLinks fails: the generated
  divergence-ledger doc links http-client-backend.md, an architecture
  spec this repository does not carry. Name it in a code span instead,
  in ledgerDocPreamble, and regenerate the doc (-update-ledger-doc).

- TestCAFileHygieneRefusesGroupWritableFile fails under umask 022:
  os.WriteFile's 0o660 passes through the umask, so the file lands 0640,
  is never group-writable, and TransportForFile accepts it. Chmod it
  explicitly. Its acceptance twin had the same gap on its file (only the
  explicitly chmodded directory reached the user-private-group
  exception), so chmod that file too: a mutant that drops the exception
  for files alone passed the old test under umask 022 and fails the new
  one.

- That acceptance twin calls the unix-only isUserPrivateGroup from
  ca_test.go, which carries no build constraint, so the package's tests
  do not compile for GOOS=windows. Move it, otherwise verbatim, into
  ca_permissions_unix_test.go beside the other isUserPrivateGroup tests.

Review fixes (iteration 1):

- Encode dispatched through nine case arms of op/shape conjunctions
  (cyclomatic 24). Switch on an (op, shape) struct key instead, and move
  the getIssue and search-bridge arms into encodeGetIssue and
  encodeSearch. The arms are disjoint, so dispatch and every error string
  are unchanged. Cyclomatic 24 -> 10.

- EventStream.Next kept four accumulators and the per-field switch in
  one loop (cognitive 27). Gather the accumulators into sseEvent and
  fold each field line, per-event cap included, in applyField. Next
  cognitive 27 -> 12; applyField is 11/11.

- The CA hygiene walk joined a relative symlink target onto the textual
  containing directory, so with a/link -> ../b/c and b/c/x -> ../y it
  resolved a/y where the kernel opens b/y: a valid CA was refused, or a
  hygienic file at a/y was checked and read instead. readLinkTarget joins
  onto the directory's EvalSymlinks path, taken after that directory's
  own ancestors passed the hop-by-hop check. The regression test plants
  a decoy at a/y; a lexical-join mutant reads it and fails.

- SaveTarget wrote a relative CAFile that every later LoadTarget
  refuses. Both now go through checkCAFileAbsolute, so SaveTarget refuses
  first, with LoadTarget's own message, and writes nothing.

- Document the cached transport TransportFor and TransportForFile return
  as shared and read-only.

Review fixes (iteration 2):

- The walk still dropped a ".." inside a symlink target textually:
  filepath.Join cleans a relative target, and an absolute target's
  ancestors come from filepath.Dir, while the kernel takes that ".."
  from wherever the component before it really leads. Both reviews
  rated the relative leaf as a wrong-file read, and it is one: with
  x/d -> ../e/s, x/L -> d/../y read a decoy at x/y where the kernel
  opens e/y. The other three shapes are hygiene bypasses: an absolute
  leaf target x/d/../y, and an ancestor link to d/../dir or x/d/../dir
  with the CA at x/L/y, each read a file in a world-writable e that the
  walk never checked. readLinkTarget now refuses a target with a ".."
  after any other component, relative or absolute; a leading run of
  ".." is still taken from the directory's physical path. The test pins
  all four shapes behind a control that refuses e/y named directly, and
  a table pins hasInteriorDotDot's boundary. Mutants that drop the
  refusal, limit it to relative targets, refuse every "..", or count
  "." as a component each fail.

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>
2026-10-05 02:58:34 -07:00
Julian Knutsen
4af58c97fd
feat(count): Counter scope — ParentID, NoParent, ExcludeTypes, ExcludeStatus (issues.count.scope) (#7199)
* 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, #7182 be1f0bad72) 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>
2026-10-05 02:57:14 -07:00
Julian Knutsen
5439be97ba
feat(httpapi): wire-shape signal — wire_revision, client floor, golden shape digest, param tokens (#7182)
* 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>
2026-10-04 22:29:12 -07:00
Julian Knutsen
6cd1184687
feat(httpapi): opt-in large issues:batchApply envelope (≤1000 items, one transaction) (#7051)
* 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>
2026-10-01 08:32:56 -07:00
Isis Anisoptera
45a116d1a7
fix(update): fence unforced --notes overwrites behind --force across all surfaces (#5946)
* fix(update): fence unforced --notes overwrites behind --force across all surfaces

bd update --notes silently replaced existing notes, destroying handoff
history. The contract now refuses an unforced overwrite of non-empty
notes with ErrNotesOverwrite (409 notes_overwrite_refused over HTTP,
force_notes_overwrite to override), enforced inside the mutation
transaction on both the dolt and uow backends, for single updates and
batch apply alike. CAS guards keep precedence: a stale
--if-assignee/--if-status still surfaces as the exit-13 mismatch, on
both backends, before the fence speaks.

CLI: --force and --if-assignee are no longer mutually exclusive (that
exclusion made overwriting under a guard impossible); both update
routes translate the fence's sentinel into the same actionable advice
(--force to overwrite, --append-notes to preserve history), and the
post---force warning is worded as an audit statement. The shipped
plugin skill docs and bd note help now prescribe --append-notes for
handoffs instead of the newly fenced bare --notes.

The fence is the single enforcement point: no client-side pre-read
copies of the rule. Conformance contracts, unit tests for
AuthorizeNotesOverwrite, and embedded/proxied/httpapi regression
coverage included.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MAFpn9pUw8WKMfymteZHbh

* fix(update): exempt explicit clears from the notes fence; share its predicate

CI surfaced three gaps in the fence's reach:

- Clearing notes (--notes "" / patch.notes: "") was refused, diverging
  from every sibling text field's clear and from the backend behavior
  contracts. The fence now targets only its actual footgun — replacing
  non-empty notes with different non-empty content — via a single shared
  predicate, issueops.NotesReplacement, used by both the contract's
  AuthorizeNotesOverwrite and the CLI's warning path, so the two can no
  longer drift. Prose updated to match everywhere the rule is stated
  (ErrNotesOverwrite, ForceNotesOverwrite, OpenAPI spec + regenerated
  types).
- The revision-CAS integration tests' incidental concurrent writes now
  patch design instead of notes, so they no longer depend on notes-fence
  semantics at all.
- The historical-upgrade harness deliberately replaces fixture notes and
  asserts the new value; its two bd update --notes calls now pass
  --force.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MAFpn9pUw8WKMfymteZHbh

* fix(update): address review — changelog BREAKING entry, problem.go doc block, close-policy-under-guard test

Review follow-ups on #5946 (bee-ghosttrack, MERGE-AFTER-FIXES):

- CHANGELOG: BREAKING entry under [Unreleased] ### Changed for the notes
  fence on both wires (CLI exit 1, HTTP 409 notes_overwrite_refused), with
  the --force / --append-notes migration line. It also names the two
  deliberate edges: the explicit-clear exemption, and --force widening to
  the close-policy half under --if-assignee now that the flag pair is legal.
- problem.go: CodeNotesOverwrite's comment had landed inside
  CodeDependencyCycle's doc block; each const now sits under its own docs.
- assign_fence_embedded_test.go: pin the previously untested close-policy
  half of --force under --if-assignee (refused unforced, authorized forced).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JyuQ6Tjv3D7tpNqeb2WDED

* test(update): align TestWarnNotesReplacement with the post-fence warning copy

The test landed on main after this branch was cut and pins the pre-fence
wording, where the warning fired on any unforced overwrite. Since the fence,
an unforced overwrite is refused outright and warnNotesReplacement fires only
after a forced one — the audit trail for a habitual --force — so the copy it
pins is now '--force replaced existing notes'.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JyuQ6Tjv3D7tpNqeb2WDED

* docs(import): record bd import's notes-fence exemption as by-design (GH#6190)

Import consults none of the per-field live-state fences — notes overwrite,
live-claim reassign, close policy — and that is the intended shape, not an
omission: its contract is wholesale row replacement, guarded by its own
staleness check (only strictly-newer rows rewrite local state, --allow-stale
is the single deliberate-overwrite opt-in) and reported field-by-field in
updated_issues. Named in AuthorizeNotesOverwrite's enforcement-boundary
comment and in bd import's help; the published CLI docs pick the help text
up at the next release pin bump.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JyuQ6Tjv3D7tpNqeb2WDED

* fix(update): refuse --notes "" and add --clear-notes; stop --notes help reading as additive

GH#6021: an empty --notes wiped the whole notes field at exit 0 behind the
same ✓ Updated receipt as a successful write — and the empty string is
exactly what a dead command substitution collapses to. The empty value is
now refused on both CLI routes (the accident and the deliberate clear are
the same bytes at the flag layer), and the deliberate clear gets its own
verb, --clear-notes, mutually exclusive with --notes/--append-notes. A verb
rather than the proposed --allow-empty-notes opt-in: what needs authorizing
is an intent, not an input path — --allow-empty-description unblocks
stdin/file plumbing, which notes does not have — and an opt-in passed
habitually would silently disarm the guard while a habitual --clear-notes
fails loudly. --force does not bypass the refusal; the fence's clear
exemption stands, so the verb alone authorizes the erase. The HTTP API is
unchanged: patch.notes "" still clears.

GH#6272: bd update --help called --notes "Additional notes" and the prime
text said "Add supplementary notes" — both read as appending, so agents
following the injected guidance faithfully clobbered prior context. The
update help now names the operation with the --append-notes contrast at the
point of use, the shared/create help is field-named like --description and
--design, and the prime line points at bd update --append-notes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JyuQ6Tjv3D7tpNqeb2WDED

* fix(bazel): enumerate the PR-new files in cmd/bd and issueops srcs

The base added cmd/bd/BUILD.bazel and internal/storage/issueops/BUILD.bazel
with EXPLICIT srcs lists after this branch was cut, so the three files this
PR adds were never enumerated:

  cmd/bd/update_notes_guard.go        (go_library bd_lib)
  cmd/bd/update_notes_guard_test.go   (go_test bd_test)
  internal/storage/issueops/aggregate_authorize_notes_test.go (go_test)

The go_library omission is a hard build break, not a silent skip:
update.go:215,220 and update_input.go:106,111 are enumerated and call
validateNotesUpdate / clearNotesRequested, so //cmd/bd:bd_lib compiles the
callers without the callee. bazel.yml arms unconditionally for fork PRs
(head.repo.fork == true) and builds //cmd/bd:bd + //cmd/bd:bd_test, so this
reds the lane. make bazel-sync-check cannot see it -- go_srcs.py only
validates the glob-based go_srcs filegroup, never the rule srcs lists.

Generated by make bazel-sync (gazelle), not hand-edited, so the workflow's
own BUILD-files-in-sync drift step agrees byte-for-byte.

* fix(notes): name --clear-notes in bd note's rm guidance, correct the fence boundary comment, pin both request-shape rules

Takes all three non-gating minors from the review. No behavior change: two
prose fixes and two test cases.

1. cmd/bd/note.go's rm|remove|delete branch advised
   `bd update <id> --notes "text" --force` under "To change or clear notes",
   but clearing through --notes is exactly what this PR made impossible --
   validateNotesUpdate refuses an empty value unconditionally and --force does
   not reach it. The branch now names both verbs separately: --notes --force to
   replace, --clear-notes to clear. The edit and update branches speak only of
   replacing and were already correct, so they are untouched.

2. aggregate.go's enforcement-boundary comment claimed the UpdateIssueInTx
   funnel's "one notes-replacing caller is bd edit". Under this PR's own
   NotesReplacement predicate there are at least four more (bd note's
   read-combine-write, bd defer --reason, bd rename and delete-tombstoning's
   mechanical ID rewrites, bd compact's clears). The exemption is still sound --
   every funnel writer derives its new value from the current notes -- so the
   comment now names those CLASSES instead of a single caller, which is the
   claim that is actually true and that a future fence auditor can check.

3. Both branches this PR adds to ValidateUpdateRequest were uncovered: the
   batch apply leg reaches them here and nowhere else, while the single-issue
   HTTP handler's own pre-check returns before storage. Added a sibling table
   (the existing one varies only the patch; these two rules are properties of
   the REQUEST) with a case each. Mutation-checked, disjoint: neutralizing the
   force-without-notes branch reds only the first case, neutralizing the
   notes+append branch reds only the second, and the pre-existing
   canonical-fields table stays green under both.

Not an amend of 5ffcc9c16c: that commit's message states it was generated by
make bazel-sync and not hand-edited, so folding hand-written Go into it would
falsify the claim its own BUILD-files-in-sync argument rests on. No new files,
so the srcs lists it repaired stay correct.

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
2026-10-01 05:02:40 -07:00
mtccressall
652c29b805
fix(show): disclose dependency edges the listing cannot represent (be-lpi) (#6352)
* fix(show): disclose dependency edges the listing cannot represent (be-lpi)

`bd show --json` emitted a self-contradicting payload on any issue with a
cross-repo or `external:` dependency:

    {"id":"hq-cv-ftcra","dependency_count":1,"dependencies":null}

and `bd show` in text mode rendered no dependency section at all, so
`bd dep add x liveop-y` reported success and the `bd show x` a caller ran
straight after was indistinguishable from the edge never having been written.

THE COUNT IS CORRECT. THE ENUMERATION IS THE DEFECT.

`GetDependenciesWithMetadataInTx` reads the edge rows, resolves each far end,
then does a bare `continue` past any id with no local row. An `external:` or
cross-repo target HAS no local row by construction: `IsExternalDepTarget`
routes exactly the ids this database cannot hold into `depends_on_external`,
the one target column with no foreign key into issues. The count queries have
no such join. So the count keeps the edge and every listing drops it, and the
difference is precisely the set of edges that are real, stored, and
unrenderable from here.

Reported as a phantom count on convoy beads. It is neither phantom nor
convoy-specific: `hq-cv-ftcra` carries a real `tracks` edge to
`external:liveop:liveop-kmf`, and convoys are simply the only producer of
external targets in that store (77 external edges, all `tracks`). The
`bd list --json` zero the report also cites is correct by design and unrelated
— that count is blocks-only per `SearchCountsSQL`, and the edge is `tracks`.

Publish the difference instead of leaving the caller to infer it, following
the `comments_omitted` precedent (ga-clgh):

  - `IssueDetails` gains `unresolvable_dependencies` / `unresolvable_dependents`
  - `BuildIssueDetails` sets them, so every frontend — CLI `--json` and the
    HTTP detail view — gets it at once
  - text mode says the same thing on stderr, never stdout, so the rendered
    issue is byte-identical for the common fully-local case; that is the
    choice `warnDroppedDepEdges` already made in dep.go for this same gap
  - the notice helper is shared with the watch-mode render so the two cannot
    drift apart in what they disclose

Set ONLY when the row list was actually read and came back short: the
dependency read's error is now kept rather than discarded, because a FAILED
read and a SHORT read both leave the slice empty and must not collapse into
one signal. `unresolvable_dependents` only under `IncludeDependents`, where
the rows exist — without them the slice is nil by design and a delta would
report every dependent an issue has as unresolvable.

Deliberately NOT done: making the count match the listing. The count is right
and the edge is real, so zeroing it would delete the only signal these edges
exist. Nor does `GetDependenciesWithMetadata` synthesise placeholder issues
for external targets — it has 14 non-test call sites including the Linear,
GitLab, Jira and ADO sync paths, which would then map a fabricated issue onto
a remote tracker.

`bd dep list` needed no change: bd-mtla already warns there and points at
`bd dep list <id> <id>`, which prints the raw edge record. The installed
v1.2.2 predates that fix, which is why the bead's measurements saw a bare `[]`.

Tests. `internal/workapi/detail_unresolvable_test.go` pins the arithmetic
against a source whose counts and rows are set independently, with negative
controls for a fully local store, a failed row read, a failed count read, and
count-only mode. `cmd/bd/show_unresolvable_deps_embedded_test.go` drives the
production path — init, create, `dep add`, `show` — for both target shapes
plus a fully local control, and asserts the notice reaches stderr and not
stdout. Verified the scratch fixture's stored columns are identical to the
production row rather than merely similar. Sabotage control run on both tiers:
removing the guard turns each red, and the negative controls stay green.

`docs/reference/json-schema.md` is intentionally untouched — it is
hand-written and documents the pinned release (`docs/cli-docs.pin` is v1.2.2),
not main. Follow-up filed as be-soj.

Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of Marc Cressall
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017B2Z4eQi2a9Cgfumj2RRnR

Executed-By: beadsrig/polecats/toast

* fix(show): do not read a failed dependency listing as unresolvable edges (be-lpi)

Codex review of the previous commit, and it is right.

`bd show` renders dependencies best effort and discarded the listing error:

    depsWithMeta, _ := issueStore.GetDependenciesWithMetadata(ctx, issue.ID)

so when that read FAILED while the count query succeeded, the new notice
reported every counted edge as cross-repo/external. A transient backend error
was rendered as a claim about the data, which is the more expensive of the two
mistakes — the user goes looking for edges that are simply unread.

This is the distinction `BuildIssueDetails` already draws with `depsErr` on
the JSON side, and it is the reason that error is kept there. The text path
did not draw it at all, so the two planes disagreed under failure: `--json`
stayed silent and the human render accused the data.

Carry each direction's rows and error together in a `depListing` and require
BOTH reads to have succeeded before reporting a difference. Rendering stays
best effort; only the diagnosis is gated. A failure in one direction no longer
suppresses the other, which is a case the single-error shape could not express.

`cmd/bd/show_unresolvable_deps_unit_test.go` pins it: 10 cases including the
two the review found, a fully local negative control, a failed count read, and
one direction failing while the other stays reportable. Sabotage control —
relaxing the guard back to `countErr != nil` alone fails exactly the two
listing-read-failed cases and nothing else.

Reuses the existing race-safe `captureStderr` from test_helpers_pure_test.go
rather than a second copy.

Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of Marc Cressall
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017B2Z4eQi2a9Cgfumj2RRnR

Executed-By: beadsrig/polecats/toast

* fix(show): read the dependency counts before the row listings (be-lpi)

Second codex finding on this change, and it is real on the path `bd show`
actually uses.

The unresolvable-edge difference is computed from two reads. Where the source
is not snapshot-consistent, a write landing between them skews it — and with
the listing read first the skew was the expensive direction: a freshly added,
perfectly ordinary local edge came back as `unresolvable_dependencies: 1` and
as a stderr notice accusing the data.

Only the store-backed source is exposed. `uow.issueReader.Get` wraps the whole
build in `RunTxRead`, so the UOW path shares one snapshot; `storereader` — what
`EmbeddedDoltStore.IssueReader` returns, and therefore what `bd show` runs on —
issues a connection per call.

Read the counts FIRST. An edge added in the window then leaves the count
stale-LOW, the difference goes negative, and nothing is reported. The text path
gets the same order structurally: the helper is split into `readDepCounts`,
called before the listings, and `warnUnresolvableDepEdges`, called after, so
the ordering is visible at both call sites rather than buried.

THIS IS AN ORDERING MITIGATION, NOT A FIX, and the code says so. A concurrent
DELETE still leaves the count stale-HIGH and produces a spurious notice. Closing
that needs a shared snapshot across the two reads, or a store method that counts
edges whose target has no row directly — either is a new seam across both
backends and the domain path, out of proportion to an advisory field. Filed
separately. Deletion of a dependency edge is also far rarer than addition, which
is why this ordering is strictly better rather than merely different.

The first version of the JSON-side test DID NOT PIN THE ORDER. It used a source
returning fixed values, so reversing the two reads still passed — a test
pinning arithmetic while claiming to pin an order, and the sabotage run is what
caught it. Replaced with `mutatingSource`, where whichever read runs first sees
one edge and the second sees two; swapping the reads in `BuildIssueDetails` now
fails with exactly the false report the review described. The text-side case is
relabelled to say it covers the subtraction only, since the call-site order is
not in its scope.

Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of Marc Cressall
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017B2Z4eQi2a9Cgfumj2RRnR

Executed-By: beadsrig/polecats/toast

* fix(show): disclose unrenderable dep edges in proxied render (be-lpi)

`bd show` has three text renders and be-lpi closed two of them.
usesProxiedServer() returns at show.go:45 before any of the fixed code,
and runShowProxiedDefault binds the shared issueops.Reader -- hence
BuildIssueDetails, hence unresolvable_dependencies -- only when
`jsonOutput && !in.shortMode`, so plain text falls through to
proxiedRenderIssue, which rendered both dependency sections from
proxiedListDeps with discarded errors and said nothing. On a
server-backed repo the change`s own symptom survived: a cross-repo or
`external:` dependency still rendered as no dependency at all.

Call warnUnresolvableDepEdges from that route too, counts before the
listings, taking the counts through workapi.NewUOWDetailSource. The
domain use cases behind a proxied UOW are per-table, so proxiedDepCounter
carries the isWisp flag the DetailSource counts take. That flag is
arithmetically inert on this path, and the earlier claim here that the
store seam "resolves" it was the wrong mechanism: the repository read
seam discards it outright -- CountByID forwards only Direction and Types
to CountDependencyEdgesInTx, and ListWithIssueMetadata forwards only the
source id to Get{Dependencies,Dependents}WithMetadataInTx
(dependency.go:888-917) -- so both sides span `dependencies` and
`wisp_dependencies` alike and only the mutating paths pick a table.
The conclusion is unchanged and is what the notice depends on: the
arithmetic is the same on both routes, because
CountDependencyEdgesInTx counts `dependencies` plus `wisp_dependencies`
with no join to `issues`, and proxiedListDeps runs the very
GetDependenciesWithMetadataInTx the direct route runs, so the difference
means here what it means there. --refs and --children stay out of scope:
an alternate query with no count beside it to contradict. The precedent
this design cites, warnDroppedDepEdges, covers both of its own routes
(dep.go:1148, dep_proxied_server.go:457), which is the in-repo standard
applied here.

Pinned by TestProxiedServerShow2/show_discloses_unresolvable_dep_edges
with a fully-local negative control. Measured, not assumed: deleting the
new call reds the first and leaves the control green.

Also from the same review, all non-gating:

- The recovery pointer is outbound-only now. `bd dep list <id> <id>`
  reaches raw edge records through the duplicate-id form, which
  dep.go:1101 selects on `batchMode && direction == "down"`, and
  dep.go:1144 says in the repo`s own words that "up" has the same gap
  with no inbound EdgeReader role to close it. An issue short only on
  dependent edges was handed a command that cannot show them, and now
  gets a line saying so instead.

- The ordering comment no longer advertises a guarantee nothing holds.
  Splitting readDepCounts from warnUnresolvableDepEdges makes the
  counts-first order readable at the call sites; it does not pin it.
  Measured: reversing it at all three sites leaves this package green,
  including the embedded production-path test, because the unit test
  drives warnUnresolvableDepEdges directly and no CLI test can land a
  write inside the window. The only automated pin is one tier down, on
  TestBuildIssueDetails_ConcurrentAddIsNotReportedAsUnresolvable. A CLI
  test that could fail on the order would have to own that window, which
  is out of proportion for an advisory notice, so the comment now states
  its scope rather than overstating it.

- The plane asymmetry is documented rather than changed: text mode reads
  dependents unconditionally and always discloses the inbound direction,
  while unresolvable_dependents needs include_dependents (--json only).
  The per-field restriction is the correct half -- without the rows a
  delta would call every dependent unresolvable -- so the godoc and the
  spec description record the disagreement.

One correction to be-lpi`s own commit message, which cannot be amended
from here: enumerating the edges via issueStore.EdgeReader() is not "a
new seam across both backends and the domain path" on the CLI path.
EdgeReader() sits on the variable that path already holds
(storage.go:235, used at show.go:177). The concurrent-DELETE residual
still stands on the two-reads argument alone, which remains true of
ReadEdges plus a set difference.

Review iteration 2 adds the BUILD-file sync the required Bazel lane
needs, plus one comment correction:

- cmd/bd/BUILD.bazel and internal/workapi/BUILD.bazel now list the three
  test files this change adds. The relevant failure is not a broken
  build: bazel.yml`s "BUILD files in sync" step (:382-406) runs
  `make bazel-sync` and exits 1 on a non-empty `git status --porcelain`,
  and that step`s job is BAZEL_TEST, one of seven Bazel rows in
  pr.yml`s CI_GATE_REQUIRED (:1496-1524, mapped at :1551), so the drift
  reds a required lane rather than merely leaving the files invisible to
  Bazel. The repo`s own fixture agrees: scripts/ci_workflow_test.go`s
  bazelLaneGateIDs holds bazel-test, and bazelAdvisoryLanes retains only
  bazel-integration.

  The rows are gazelle output rather than hand-written. `make bazel-sync`
  on this head proposes five; init_git_bootstrap_routing_test.go and
  init_role_environment_test.go are base staleness that origin/main
  already lists, and a run on the merge target proposes them not at all,
  so only the three this change owns are committed.

  Certificate, run on the merge target rather than argued: merge
  origin/main into this head, resolve, `make bazel-sync`, then
  `git status --porcelain --untracked-files=all` is empty -- which is
  exactly the gate step`s own test, and it also confirms the resolution
  is byte-identical to what gazelle emits. `bazel build //cmd/bd:bd_test
  //internal/workapi:workapi_test` on that tree completes successfully,
  so the widened srcs lists compile.

  These rows do introduce a merge conflict this change did not have
  before: origin/main added show_watch_loop_test.go into the same slot of
  the same sorted srcs list in cmd/bd/BUILD.bazel. It is an add/add with
  an empty base -- neither side edits shared text -- and the resolution
  is the sorted union of all three rows, which is what gazelle emits and
  what the certificate above was run against.

- The ordering comment`s measurement clause named show.go and
  show_display.go while the claim was true of three call sites, the
  third being the show_proxied_server.go site this fixup added. It now
  names all three, re-measured at this head: reversing readDepCounts
  below its listings at every site leaves the selector green -- 35
  subtests across TestWarnUnresolvableDepEdges,
  TestEmbeddedShowUnresolvableDeps and TestProxiedServerShow2.

Maintainer fixup for PR #6352, review iterations 1-2.

---------

Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
2026-10-01 01:29:36 -07:00
Julian Knutsen
8995f2471e
test(count): pin --include-ephemeral as the plane bit alone, and fix the plane prose (post-merge #6240) (#6998)
* test(count): pin include_ephemeral as the plane bit and nothing else

PR #6240 added `bd count --include-ephemeral` so a count can reach the
wisps table without IncludeInfra's other three changes: dropping
templates, dropping gates, and routing an infra type to the ephemeral
tier. Nothing asserted that second half. Routing IncludeEphemeral
through the builder's infra branch, or mapping `include_ephemeral` onto
IncludeInfra in the HTTP handler or the CLI, passed every existing test.

- workapi: TestCountIncludeEphemeralIsThePlaneBitAndNothingElse, the
  count twin of the list pin. IncludeEphemeral (no type, a named type,
  an infra type) leaves IsTemplate, ExcludeTypes and Ephemeral unset;
  IncludeInfra still sets all four.
- httpapi: TestCountForwardsTheEphemeralPlaneParameter sends each plane
  parameter alone and asserts the exact request the role receives.
- cmd/bd: TestCountIncludeEphemeralFlagShape pins the flag, its false
  default, and that --include-ephemeral alone leaves IncludeInfra false.

Each new test fails against its mutant, and it is the only test that
does:
- builder: `if in.IncludeInfra || in.IncludeEphemeral`
- handler: `IncludeInfra: q.boolean("include_infra") || q.boolean("include_ephemeral")`
- CLI:     `IncludeInfra: includeInfra || includeEphemeral`

Post-merge review follow-up for #6240.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(count): name include_ephemeral where the plane prose said include_infra alone

#6240 added a second way to reach the wisps tier, but several statements
still said only include_infra could reach it:

- spec, countIssues "Planes": "DURABLE-PLANE ONLY unless include_infra
  is set" now names both knobs and says what include_ephemeral changes.
- spec, include_infra: "Unset, the count is durable-plane only" now holds
  only with include_ephemeral also unset (types.gen.go regenerated).
- issueops.CountRequest: the same "Unset" sentence on IncludeInfra and on
  IncludeEphemeral, each now conditional on the other knob.
- workapi.applyCountIncludeInfra: "a count without IncludeInfra keeps its
  durable-only semantics" now allows for IncludeEphemeral.
- httpapi countFilters: the "plane switch" comment named one knob;
  IncludeEphemeral now has its own comment saying why it is never folded
  into IncludeInfra.
- count_test.go: the default-plane comment names both zero values, and
  the stale "25 filters" / "26th filter" literals are dropped (the
  struct has 26 fields).

Comment and spec-prose only; `make api-check` is green.

Post-merge review follow-up for #6240.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Eddie the Engineer <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 01:14:25 -07:00
Julian Knutsen
4caeeffeec
feat(serve): name the blockers on a live-blocker not_closable (#6893)
* feat(issueops): type the blocked-close refusal as BlockedError

Every close-policy blocker refusal was fmt.Errorf("%w: %s is blocked by
%v", ErrCloseBlocked, ...), so the blocker list existed only as prose. A
caller reporting the refusal elsewhere (the HTTP surface) had to parse it
or drop it.

issueops.BlockedError carries IssueID, the typed []Blocker (id plus the
blocking edge type when known) and the wrapped sentinel. Its message is
byte-identical to the historical sentence, so the direct and proxied CLI
lines and failed[].error do not move, and errors.Is(ErrCloseBlocked) still
matches. The sentinel is a field rather than fixed so other "X is blocked
by Y" refusals (e.g. a blocked claim) can reuse the type.

The in-transaction guard keeps the edges typed (isBlockedByInTx, with
IsBlockedInTx formatting through Blocker.String), and the external guard
builds the error from IsBlocked's []string via ParseBlocker, the inverse
of that spelling.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* feat(httpapi): name the blockers on a live-blocker not_closable

The served close refusal said only "issue is blocked", so an HTTP client
could not tell the user what held the close, while bd close on the direct
and proxied routes prints "cannot close blocked issue: X is blocked by
[Y]".

A live-blocker not_closable now carries a `blockers` extension member,
[{id, kind: local|external, type?}], read from *issueops.BlockedError's
typed list, and a detail that opens with the direct route's sentence
built from the same list. It covers issues/{id}:close, per-item
issues:batchClose outcomes, PATCH into a done status and
issues:batchApply. The code, status and open_children discriminator are
unchanged; an error that only mentions blockers in prose keeps the old
generic detail and no member.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(issueops): test the external: prefix before the type split in ParseBlocker

Maintainer review fixup for #6893.

ParseBlocker tried the " (" / ")" split before the external: prefix
branch, so it won for any external reference whose capability ends in
")". validateExternalRef (cmd/bd/dep.go) constrains a capability to
non-empty only, so `external:remote:pay (beta)` is a legal reference
created by the sanctioned `bd dep add` path -- and it parsed to a
truncated ID of "external:remote:pay" plus Type "beta", a value outside
the documented blocks|waits-for|conditional-blocks vocabulary that
falsifies the spec's own promise that an external blocker carries no
type.

Only the structured half was wrong: the mis-split round-trips through
String(), so the prose detail and the CLI sentence stayed byte-identical
and the failure was silent on exactly the new `blockers` member this
change exists to make trustworthy.

Hoisting the prefix test is loss-free -- Blocker.Type's doc comment
already states an external reference never carries a reported type.

Pin: the ParseBlocker/String table in
TestBlockedErrorKeepsTheHistoricalSentence gains the paren-suffixed
external row; every external case tabled there was paren-free, which is
why this got through. Restoring the old ordering reds the new row.
The DeepEqual failure now prints %#v, because Blocker implements
String() and the default verbs render got and want identically for
precisely this defect.

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
2026-10-01 00:51:06 -07:00
Stephanie Jarmak
12b19a6df7
feat(dep): detect cycles through tracks edges (#6148)
* 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>
2026-09-30 20:20:17 -07:00
Harry Miller
dfdedf5dfb
fix(status): disclose the counted rows bd list will not show (#5763)
* feat(stats): count the rows the default listing suppresses

bd status counts the issues table; bd list hides gates and templates on
account of what they are. The two therefore disagree, and nothing
reconciles them: a teardown driven by bd list leaves a gate behind and
status reports a total the operator cannot account for from any listing.

Break the suppressed rows out as their own counts. TotalIssues keeps
counting the database, which is what a command titled "Issue Database
Status" should report; these say how much of that total no default
listing will show. Every backend's statistics path funnels through
ScanIssueCountsInTx, so one query serves all of them.

Infra types need no counterpart here: they live on the wisp plane, which
this query does not read.

* fix(status): disclose the counted rows bd list will not show

bd status reported "Total Issues: 2" for a workspace whose every listing
showed one, because gates and templates are suppressed from a default
bd list. Nothing connected the two numbers, so the remainder read as a
phantom -- most visibly after a teardown driven by bd list, which leaves
its gates behind and then cannot see them.

Report the suppressed rows under the summary they qualify, naming the
flag that reveals each kind. The breakdown is printed rather than a
single hidden-total, since a template gate would otherwise be counted
twice. Nothing is printed when there is nothing suppressed.

Stacked on the statistics counts that make this reportable.

* docs(api): put gate_issues and template_issues on the Statistics schema

The Statistics schema is pinned to types.Statistics, so the two new
counts were on the wire the moment the struct grew them, and
TestWireTagBijection fails the openapi gate until the spec says so:

    Go fields with no spec property: [gate_issues template_issues]

Document both as a breakdown of total_issues rather than an addition to
it — they count rows the default `bd list` suppresses, which
total_issues already includes — and warn against summing them, since a
row can be both a gate and a template.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(status): give --assigned the same disclosure, and test the behavior

Three points from review.

1. `bd status --assigned` never printed the line. AssigneeStats does not
   go through ScanIssueCountsInTx - it folds one actor's rows through
   workapi.FoldStatsAssigneeSummary, which left both new fields zero. That
   route's filter sets only Assignee, so IsTemplate stays nil and the
   actor's gates and protos really ARE in those rows while
   `bd list --assignee` suppresses both: the same reconciliation gap, one
   scope down. The fold now counts them, and its doc says they are set
   deliberately rather than borrowed from a workspace-wide answer.

2. The infra-type suppression is now explained rather than asserted away,
   and the answer is that a durable infra row is NOT unreachable, so the
   third breakdown is filed as GH#6439 rather than dismissed. Both the
   plane routing and the listing's exclusions read the workspace-configured
   types.infra set, and writing that key only invalidates a cache
   (dolt/config.go) - it never moves rows already written. So durable rows
   created while a type was not infra stay durable once it becomes one, and
   a type evicted from the set creates durable rows outright, which the
   create contract already pins ("evicted infra type",
   issue_operations_contract.go). Counting them needs that configured set,
   which ScanIssueCountsInTx - portable SQL with no config seam, called
   from six backend sites - cannot reach; guessing with the built-in names
   would be wrong in exactly the workspaces where it matters.
   suppressedTypeSummary's doc now carries that reasoning.

3. The behavior itself had no test - both existing cases exercised a pure
   string formatter, and would pass with the render call site deleted. Now:

   - TestRenderStatusEmitsTheSuppressedRowsLine captures renderStatus's
     stdout, asserts the line and both parts, and asserts it sits after the
     totals it reconciles rather than in the extended block. It fails with
     the call site removed ("renderStatus did not emit the disclosure
     line"), plus a companion asserting the line is absent when there is
     nothing to disclose.
   - Three conformance cases in stats_reporter_contract.go, wired into all
     three role wirings (dolt, embeddeddolt, uow), so the new SQL is
     checked cross-backend rather than at one call site:
     BreaksOutTheRowsTheDefaultListingSuppresses (with the negative rows a
     loose predicate would also move), BreaksOutAGateThatIsAlsoATemplate
     (the two suppressions are independent, so a proto's gate step counts
     in both), and AssigneeStatsBreaksOutTheSuppressedRows for the fold.
     statsReporterCounts and assertStatsReporterDelta carry the two fields.
     All three are behavioral reds against zeroed counts, not compile
     errors:

         GateIssues moved by 0 (0 -> 0), want 1
         TemplateIssues moved by 0 (0 -> 0), want 1
         GateIssues = 0, want 1 - the actor's gate is in this answer but
           not in `bd list --assignee`

4. Nit: pluralCount takes both spellings instead of appending "s", so a
   caller with an irregular plural is not silently mis-served.

Also adds the CHANGELOG entry the behavior change was missing, including
the GH#6439 gap.

Reported-by: bee-ghosttrack
Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of Harry Miller

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(conformance): declare the new stats cases in the order the table runs them

TestRoleContractCasesCoverEveryContractCase checks more than coverage: the
roleContractCases table has to list cases in the order their contract file
DECLARES them, because that is the order the unit-of-work leg's runners use
and the order its config-writing cases depend on.

I declared all three new cases together, then registered the assignee one
with the other assignee cases in the table, so the two orders disagreed:

    roleContractCases is out of declaration order at position 449: table
    has RunStatsReporterAStatusOutsideTheTalliesIsCountedOnlyInTotal,
    source has RunStatsReporterAssigneeStatsBreaksOutTheSuppressedRows

Fixed by moving the declaration rather than the table entry, since the
assignee case belongs beside the other assignee-scoped ones anyway - the
grouping the table already had was the correct one. Caught by CI because I
ran go vet over backend/conformance but not its tests; both now pass.

Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of Harry Miller

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* docs(changelog): move this PR's entry under [Unreleased]

The 1.3.0 cut renamed the old [Unreleased] block, so the entry this branch
added there now merges cleanly into the released [1.3.0] section (#6643).

Agent-Signature: claude-code-opus-5-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(status): complete the disclosure's remedy and pin its population

Maintainer review fixes for PR #5763 (adopt-pr iteration 1). Four of the
five review findings taken; the nit is declined with its measurement.

Finding 2 (minor, gate impact minor) - the printed remedy was incomplete.
The two counters come from the same scan as TotalIssues and are status-blind
with it, but the flags they named lift only the TYPE exclusion, so a CLOSED
gate was counted while `bd list --include-gates` still would not show it.
Gates are closed as the work they guard completes, so that is the ordinary
case rather than an edge.

Took the "complete the hint" arm over the "scope the counters" arm. Every
other field ScanIssueCountsInTx fills is workspace-wide; the disclosure
exists to account for TotalIssues, a database number printed three lines
above it; and scoping these two to the listing's population would leave them
explaining nothing about the total they are broken out of. `--all` "replaces
the status exclusions only" and lifts no type exclusion of its own
(backend/conformance/reader_contract.go:487), so the two flags together are
exactly the remedy. Recorded the population in the types.go field comment,
the status.go doc, and the CHANGELOG, which printed the old example verbatim.

Finding 3 (minor) - the three new conformance cases seeded only open rows,
so a backend counting over every status and one counting only the listing's
population returned identical numbers on all of them. Added a closed gate and
a closed proto to the first case. Proved it now decides the question: scoping
both SQL SUMs with `AND status <> 'closed'` reds exactly that case
("GateIssues moved by 1 (0 -> 1), want 2") while the all-open sibling
BreaksOutAGateThatIsAlsoATemplate stays green.

Finding 4 (minor) - the normative role doc in issueops/statsreporter.go
enumerated only the six prior counts. Added the two to that scan's bullet and
corrected two statements this PR had falsified: the headline "six counts of
one set", and the AssigneeStats bullet's "the fold ... tallies the five
statuses and nothing else", which stopped being true when the fold gained the
two increments.

Finding 1 (minor, gate impact minor) - ran `make bazel-sync`. It proposed
exactly one line, `+ "status_suppressed_test.go"` in cmd/bd/BUILD.bazel, and
nothing else, confirmed by porcelain rather than by bazel-sync-check.
Generator-owned, not hand-edited.

Finding 5 (nit) - declined. The three helpers already in package main
(pluralIssue, pluralize, plural) all DERIVE the "s" and cannot render a
caller-chosen pair; the tree's one two-form helper, pluralWord, is unexported
in internal/storage/issueops, and exporting it so a CLI string could reach it
would add exported surface to a storage role for a cosmetic. Recorded that
trade in pluralCount's doc comment instead.

Validation: `go build ./...` and `go vet` (6 pkgs) clean, gofmt clean,
`git diff --check` clean; cmd/bd 4/4 named PASS, internal/httpapi
TestWireTagBijection|TestSpec* PASS, internal/workapi PASS,
internal/storage/uow TestStatsReporterContract 18/18 subtests PASS. Both new
pins are mutation-proved: reverting `--all` reds all four table cases, both
flag subtests and the render-path pin, while the absence assertion stays
green.

Not done here: the PR body carries the same stale example line
("1 gate (--include-gates)"). Review iterations do not touch the PR surface,
so that correction is stamped for finalize.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
2026-09-30 15:44:40 -07:00
Julian Knutsen
a7fe6aea50
feat(httpapi): PATCH /v0/beads/issues/{id} accepts claim, the wire spelling of bd update --claim (#6890)
The update operation had no way to express a claim, so an HTTP client of
`bd serve` had to refuse `bd update <id> --claim` outright. The request now
carries a `claim` boolean that passes straight through to
issueops.UpdateRequest.Claim on the same lifecycle role the direct route
uses, so the claim and the patch land in one transaction with the direct
route's semantics: same-actor re-claim is idempotent (changed: false), a
foreign holder is 409 already_claimed and an unclaimable status 409
not_claimable, both naming `claim` and carrying {id}:claim's extension
members (shared through claimRefusal), and a refused claim writes none of
the patch.

With claim: true the patch may be empty (the claim is the whole write).
claim beside expected_assignee, expected_status or force_assignee_transfer
is refused at the edge as a 400 naming `claim` rather than surfacing the
role's ErrValidation as the generic patch 400. No capability token: per the
document's version-skew rules, member presence is probed, and an older
server refuses `claim` as unknown_parameter before any database work.

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.local>
2026-09-30 15:42:37 -07:00
Karel Bourgois
e8f318316f
feat(count): --include-ephemeral, the plane knob bd count never had (#6240)
* feat(count): --include-ephemeral, the plane knob `bd count` never had

`bd count` can admit the wisps table only through `--include-infra`, which
makes four changes at once. This adds the flag that makes just the first one,
mirroring the `--include-ephemeral` that `bd list` gained in #6098.

## Why the plane is unreachable on its own

The write path routes on STORAGE CLASS, not type — dolt's `useWispsTable` is
`Ephemeral || NoHistory || WispType != "" || IsInfraType`. So a `no_history`
task lives in the wisps TABLE while remaining ordinary durable work, and a
default `bd count` never sees it.

Recovering it today means `--include-infra`, which this repo's own doc calls
"FOUR changes at once and not one": it admits the plane, drops the infra-type
exclusions, changes the template treatment, and reconciles cardinality with
`bd list --all`. Its template exclusion then silently drops template rows of
the named type — so a caller who wanted the plane trades one silent undercount
for another.

`ListRequest.IncludeEphemeral` has been the narrow answer on the listing side
since #5476, and #6098 gave it a CLI flag. `CountRequest` had no equivalent
field at all. This is the missing half of that pair.

## The change

- `issueops.CountRequest.IncludeEphemeral` — the plane knob alone: exactly the
  first of `IncludeInfra`'s four changes, with none of the other three.
- `internal/workapi/count.go` — one line, `} else if !in.IncludeEphemeral {`.
- `cmd/bd/count.go` — flag registration, matching `bd list`'s wording.
- `internal/httpapi` — `include_ephemeral` on `countIssues`, in the spec; the
  generated `types.gen.go` is `make api-gen` output, not hand-edited.

Unset, the count is durable-plane only: the historical answer, unchanged. Every
default is untouched.

It does NOT promise a count and a listing agree. They already differ on
TEMPLATES without this flag and still do with it — a count includes template
rows unless `IncludeInfra` excludes them, a listing excludes them unless
`IncludeTemplates` admits them. That predates this and is unchanged by it; only
`IncludeInfra` sets out to reconcile cardinality, and it pays with three
changes beyond the plane.

## Verification

    ok  github.com/steveyegge/beads/internal/workapi
    ok  github.com/steveyegge/beads/internal/httpapi
    ok  github.com/steveyegge/beads/issueops
    --- PASS: TestEmbeddedCountIncludeEphemeral (39.71s)
    --- PASS: TestCountIncludeInfraFlagShape
    --- PASS: TestParseCountRequestCarriesEveryFilterFlag

`TestEmbeddedCountIncludeEphemeral` was run with `BEADS_TEST_EMBEDDED_DOLT=1`
and really executed — 39.71s, not a skip. The default fast tier would have
skipped it and reported `ok`.

`make api-gen` reproduces `types.gen.go` byte-for-byte from the spec hunk, so
the two cannot drift apart in review. `go build ./...`, `go vet` and `gofmt`
clean.

Claude-Session: https://claude.ai/code/session_01X1jMLQTSrCwtzFRS1xeUC6

* count: reframe the comments for this repo, not the fork they came from

Review on #6240 (bee-ghosttrack): five comment blocks were written from the
fork's point of view and become false once merged here — "belongs upstream",
"the half that still has to go upstream", "the fork's old wide default",
and "upstream's default" meaning the current default.

Find-and-replace, as asked: the reasoning is kept, only the frame of reference
changes. "upstream's default" -> "the default before this change"; the bd
list sibling "landed in #6098"; the infra-type divergence is "pinned, not
fixed, here" with the reason; the embedded test's fork-maintenance history is
replaced by what it actually pins. No code changes.

* build(bazel): list the two test files this PR adds in their go_test srcs

Maintainer review fixes for #6240, review iteration 1. The synthesis and the
quality scorecard both returned approve with no required changes; this commit
takes the one minor whose subject is the PR's own added files.

Taken:

- Change Impact / Blast Radius (minor, gate impact minor). The PR adds
  cmd/bd/count_include_ephemeral_embedded_test.go and
  internal/workapi/count_skipwisps_test.go, but neither was listed in its
  package's explicit go_test srcs, so the PR's own assertions were invisible to
  `bazel test`. Both rows are now listed.

  Gazelle's verdict, not a hand-guess: `make bazel-sync` was run (bazel 9.2.0 is
  available here) and it produced exactly these two entries. Its full output
  also rewrote 12 other BUILD.bazel files -- pre-existing base drift from other
  PRs' files, plus dep/select churn -- which is out of scope for this PR, so the
  generated result was reverted and only the two rows this PR is responsible for
  were re-applied, at the slots gazelle chose. Both srcs lists remain sorted
  with no duplicates (cmd/bd bd_test 637 entries, internal/workapi workapi_test
  24 entries).

  The cgo build tag on count_include_ephemeral_embedded_test.go does not exempt
  it: the repo lists tag-gated *_embedded_test.go files anyway (99 of the 101 in
  cmd/bd are listed, and the sampled ones are simultaneously listed and tagged).

Declined:

- Test Evidence Quality (nit, gate impact none). The filing lane itself marked
  it optional and explicitly said not to gate on it, and its own reasoning holds:
  internal/storage/dolt/counts.go and internal/storage/embeddeddolt/counts.go
  both delegate to the same issueops.CountIssuesInTx, differing only in
  transaction acquisition.

Validation: go build ./... and CGO_ENABLED=1 go vet on cmd/bd, internal/workapi
and issueops all clean; go test ./internal/workapi/ ./issueops/ ok. No
production code changed -- the commit is two generated-list rows.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-29 16:56:23 -07:00
postoso
9017d33745
feat(count): accept --has-metadata-key (#6282)
bd list, bd ready and bd search all take --has-metadata-key. bd count did
not, so counting the rows that merely carry a key meant listing them and
measuring the page. This is the last metadata-filter parity gap between
count and the listings.

The storage layer already carries the filter: types.IssueFilter has
HasMetadataKey and sqlbuild.AppendMetadataClauses consumes it. What was
missing is the role field, the builder wiring, the CLI flag and the HTTP
contract, so this is one change rather than a stack.

Parsing matches list_input.go and ready_input.go, including the key
validation. BuildCountFilter now passes the key to ValidateMetadataFilters
instead of the empty string it passed before, which makes the role's
existing refusal reachable from the count surface; failReadErr already
classifies that error as a 400 on has_metadata_key.

apigen types are regenerated from the spec via go:generate, not hand
edited. The pinned CLI docs are untouched.

Fixes #6160

Co-authored-by: postoso <postoso@users.noreply.github.com>
Co-authored-by: Gas City Adopt-PR <noreply@example.com>
2026-09-29 13:16:37 -07:00
Julian Knutsen
f66375459f
test(bazel): runfiles helpers + declared inputs for scan-guard tests (#6828)
* test(bazel): add internal/testutil/bazeltest runfiles helpers

Repository-path resolution for tests that works identically under plain
go test (package cwd, full checkout), bazel test locally, and remote
execution (declared runfiles only):

- IsBazel, RepoRoot (BEADS_TEST_REPO_ROOT, then the runfiles workspace
  root, then a go.mod walk), OverrideRoot (drop-in condition for existing
  helpers; empty under plain go test), CallerDir
- Runfile for $(rlocationpath) values, GOROOT for type-checking tests
- ShardFreeEnv for helpers that re-exec a test binary

Every helper reduces to the pre-Bazel behavior under go test.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(bazel): declare source/data reads for 14 scan-guard targets

Source-scanning and repo-file tests read files their Bazel targets never
declared, so they failed under `bazel test` (and could not run on remote
workers at all). Declare narrow inputs as `data` and resolve paths through
bazeltest where the test located the tree via runtime.Caller:

- tools/bazel/go_srcs.py (run by `make bazel-sync` after gazelle) keeps a
  managed `go_srcs` filegroup in the packages whose Go source tests scan,
  plus `//internal/storage:tree_go_srcs` for the storage-tree walk. Bazel
  globs stop at package boundaries, so the aggregate needs one filegroup
  per package; the script keeps it in sync and gazelle-stable.
- Hand-written narrow inputs: //internal/storage/schema:migrations,
  //:docsync_files, //plugins/beads:plugin_files, and exports of
  .gitattributes, .claude-plugin/marketplace.json, cmd/bd list.go and
  ready.go, testutil/testdoltcommon.go, scripts README.md and the release
  catalog, each visible only to its consumer.
- runtime.Caller-based roots in backend, backend/conformance,
  internal/storage, internal/formula and test/docsync now go through
  bazeltest.CallerDir / OverrideRoot; relative-path tests need data only.
- integrations/ leaves .bazelignore (it is still gazelle-excluded) so the
  docsync link check can declare integrations/beads-mcp/PYPI.md.

Under --config=prcore every target reports the same PASS/SKIP/FAIL test
set as `go test -race -short` for its package, locally and remotely.
Plain `go test` behavior is unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(bazel): guard generated go_srcs and harden bazeltest root override

- tools/bazel/go_srcs.py: add --check (print diff, exit 1 on stale blocks);
  new `make bazel-sync-check` target runs it.
- scripts/bazel_policy_test.go: under go test, assert every tree_go_srcs
  (//internal/storage) lists exactly the BUILD.bazel packages below its
  root, run go_srcs.py --check, and forbid BUILD files under docs/ and
  engdocs/ (they would cut subtrees out of //:docsync_files).
- bazeltest: honor BEADS_TEST_REPO_ROOT only when it holds go.mod
  (RepoRoot fails loudly otherwise); drop the unused GOROOT() helper,
  whose compiled-in branch could never fire under rules_go.
- scripts/ci/lib/test-env.sh: unset BEADS_TEST_REPO_ROOT.
- Document the hand-listed out-of-tree link targets in //:docsync_files.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* build(bazel): re-sync BUILD files with main

Regenerated with make bazel-sync after commits that landed while the
scaffold PR was in CI (new internal/execenv, gitenv, gitignore packages
and new sources/deps).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(bazel): declare init_safety_help.go for docsync

TestInitSafetyCLIHelpCoversReCloneGotchas (#6431) reads
cmd/bd/init_safety_help.go; export it to //test/docsync only.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-27 08:24:08 -07:00
Julian Knutsen
57ef364501
build(bazel): side-by-side Bazel scaffold + policy tests (#6798)
* build(bazel): add side-by-side Bazel scaffold (module + gazelle)

Add a Bzlmod Bazel build alongside the Go toolchain. `go build` and
`go test` are unchanged; nothing in CI invokes Bazel yet.

- MODULE.bazel: rules_go 0.63.0, gazelle 0.53.0, Go SDK 1.26.7 (matches
  the go.mod toolchain directive), go_deps from go.mod.
- ICU policy (engdocs/ICU-POLICY.md): a go-mysql-server gazelle_override
  selects the pure-Go regex backend and excludes regex_cgo.go, and
  .bazelrc builds with --@rules_go//go/config:tags=gms_pure_go, so no
  target depends on go-icu-regex or links libicu.
- third_party/patches: three module_override patches for dolt deps that
  ship WORKSPACE-era BUILD files, adapted from the gascity project.
- .bazelrc: prcore/ci test configs (inert for now; they match pr-core's
  test selection, not yet its environment isolation) and a generic
  remote-exec config with a bounded remote timeout. Executor endpoints and
  TLS credentials come only from a gitignored .bazelrc.local/user.bazelrc
  or a CI rc outside the workspace.
- .bazelversion pins Bazel 9.2.0; .bazelignore skips separate modules,
  non-Go trees, nested agent worktrees (.claude, .worktrees) and local
  data/output dirs (.beads, .dolt, dist, .runtime, tmp), so a primary
  checkout neither builds nor gazelle-rewrites nested worktree copies.
- Gazelle-generated BUILD.bazel files for every Go package.
- Makefile: `make bazel-sync` (gazelle + bazel mod tidy).
- .gitignore: bazel-* output symlinks and machine-local rc files.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(bazel): policy tests for the Bazel configuration

Add scripts/bazel_policy_test.go, plain Go tests that run under both
`go test ./scripts` and `bazel test //scripts:scripts_test`:

- MODULE.bazel go_sdk.download version equals the go.mod toolchain.
- ICU policy: .bazelrc sets gms_pure_go for build, the go-mysql-server
  gazelle_override excludes regex_cgo.go, and the root BUILD.bazel
  carries `# gazelle:build_tags gms_pure_go`.
- .bazelversion pins an exact Bazel release.
- .bazelrc.local and user.bazelrc are gitignored (parsed from .gitignore
  and cross-checked with git check-ignore when in a checkout).
- No remote-execution endpoints or credentials in committed bazelrc-like
  files, Markdown docs or .github/**: remote/BES/TLS flags
  (--remote_executor, --remote_cache, --bes_backend, --remote_header,
  --tls_client_certificate, ...) with a literal value, with or without a
  URL scheme, and non-loopback gRPC URLs in rc/.github files. Placeholders,
  $VARIABLES, and loopback are allowed; Markdown gRPC URLs (OTel exporter
  docs) are not flagged. Skipped outside a git checkout, e.g. in the Bazel
  sandbox.

Each check is a pure function also exercised against fixtures that break
the invariant. The files the tests read are declared as data via
//:bazel_policy_files so they resolve from runfiles under Bazel.

scripts/check-build-tags.sh now treats Bazel invocations as governed by
.bazelrc: the shell command segment that invokes Bazel (split on &&, ||,
;, |, $( and backticks) is exempt from the per-line `go` tag check, while
a bare `go` in another segment of the same line is still flagged. When
any scanned file invokes Bazel (or .bazelrc exists) .bazelrc must set
--@rules_go//go/config:tags=gms_pure_go for build.
scripts/check_build_tags_test.go covers both in a temp repository.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(scripts): split bazel lines in pure bash so check-build-tags works with BSD sed

BSD sed (macOS) does not expand \n in s/// replacements, so the segment
split never happened and the Bazel-exemption tests failed on macos-latest.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test(scripts): skip check-build-tags tests when bash lacks mapfile

macOS runners use /bin/bash 3.2, which has no mapfile; check-build-tags.sh
has always required bash >= 4, so the new tests are skipped there.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-27 03:41:02 -07:00
mtccressall
d14ed67f71
fix(list): expose comment bodies in bd list/show --json (be-73x) (#6473)
* fix(list): expose comment bodies and mark the omission in bd list --json (be-73x)

`bd list --json` reported comment_count and carried no comment text and no sign
that any was missing. The consequence is not a missing field: a content search
over a listing answers with a well-formed, NON-EMPTY result set whose matching
rows are absent, and nothing about that answer invites a second look. An empty
result invites suspicion; eight rows do not.

Two halves, and the second is the one that fixes what was actually reported:

  1. --include-comments on `bd list` populates each row's comments with the
     full bodies, the list twin of `bd show --include-comments`. Opt-in: it
     costs one query per row that has comments.
  2. Every row with a nonzero comment_count whose bodies were NOT hydrated now
     carries comments_omitted=true, by default, with no flag. A flag nobody
     knows to pass does not fix a silent hole; a marker on the row does.

The bodies ride on types.Issue.Comments, which already carried the `comments`
key for export/import and was simply never populated on this path, so the only
new field is the marker.

Hydration is one shared body (workapi.HydrateListComments) called from BOTH
issueops.Reader.List implementations, the store-backed and the unit-of-work
one. Those are separate bodies that have answered one contract method
differently before; it runs in the page epilogue beside FinishPageAt, after the
trim, so a page never pays for rows it is about to drop.

The source parameter is a CONSTRUCTOR rather than a source, and that is
load-bearing. Building the unit-of-work comment source eagerly made a
capability only the opt-in path uses into a requirement every caller had to
satisfy, and turned `GET /v0/beads/issues` into a 500 on a provider without a
comment use case — on requests that had asked for no comments. A count-only
listing now constructs nothing, pinned by a test that fails if the constructor
is called.

Tests pin each implementation separately rather than duplicating: unit tests
over a fake source, an embedded-dolt test over the real CLI on the direct
route, and a proxied-server test over the real CLI on the unit-of-work route.
Sabotage-controlled three ways — no-op the shared body and all three suites go
red; unwire either reader alone and only that reader's CLI test fails, which is
what proves neither integration test is redundant.

Not addressed, deliberately: gt-mfp5 (bd comment does not advance updated_at,
the orthogonal recency axis) and be-ozp (bd ready --json carries no marker; it
does not route through Reader.Ready).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XK4B7N2CrgfKGEQvDTPM4D

Executed-By: beadsrig/polecats/dag

* fix(list): do not read a skipped comment count as proof of no comments (be-73x)

Codex review of the parent commit, correctly.

`IncludeComments: true` combined with `SkipCounts: true` returned a page with
no comment bodies at all — no error, no marker, nothing — while
`IncludeComments` documents a guarantee to populate them. The hydration loop
skipped any row whose CommentCount was zero as an optimisation, and SkipCounts
zeroes every count: `issueops.ListRequest.SkipCounts` says in its own doc that
a zero then means UNKNOWN rather than none.

That is this bead's own failure mode reintroduced one layer down by the fix for
it: a silent, well-formed, empty answer to a request that asked for content.

I had considered the interaction and resolved it wrongly, in a comment reading
"the count is authoritative here because the JSON route never sets SkipCounts".
True of today's CLI callers, and not a property of the contract — issueops
.ListRequest is a PUBLIC request type and permits both fields at once. A
comment saying "X cannot happen because of how callers behave today" on a
public type is a bug with a justification attached, and worse than no comment,
because it tells the next reader the case was checked.

countsKnown is now a parameter rather than an assumption; call sites pass
!req.SkipCounts.

  countsKnown true   a zero count proves a row has nothing; skip its query.
  countsKnown false  query every row, because nothing proves otherwise, and
                     mark no row omitted, because comments_omitted asserts a
                     nonzero count the page cannot support.

The second half is the mirror defect on the marker path — the same conflation,
the other direction — which the review did not name.

No behaviour change on any current CLI path: the JSON route never sets
SkipCounts, so it passes countsKnown true, and the text route asks for no
comments and marked nothing before either. Verified: `bd list --json` output
identical, and text output identical with and without the flag.

Regression tests HonorsIncludeWhenCountsAreSkipped and
MarksNothingWhenCountsAreSkipped. Sabotage-controlled: restoring the
count-authoritative skip fails the first with "issued 0 comment reads, want 2".

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XK4B7N2CrgfKGEQvDTPM4D

Executed-By: beadsrig/polecats/dag

* fix(list): resolve the comment plane by residence, not by the row's flags (be-73x)

Maintainer review fixup for #6473, iteration 1. Both review lanes reached the
same major independently and the synthesizer re-verified it against the tree.

The new list hydration derived the comment table from the row's own
Ephemeral/NoHistory flags - issueops.IsWisp's rule, which is right for routing a
record being WRITTEN and wrong on a read. `bd import` pins a `no_history` record
to the DURABLE table while preserving the flag on the row, because clearing it
would change the content hash and break export->import->export byte-identity,
and every clone materializes its database by importing JSONL. So a promoted
no-history bead that has been through a round-trip is a durable row whose flags
say wisp:

  bd list --json --include-comments   read wisp_comments, found nothing, and
                                      returned comment_count=N beside an empty
                                      `comments`, with no marker and no error
  bd comment, bd show                 write and read that same row's comments on
                                      the issues plane, by found-table

That is be-73x's own failure mode reintroduced under the flag whose contract is
"gets them or gets an error", and a cross-role divergence: `bd list` and
`bd show` disagreed about one row. The mirror case is real too - an import
record whose `wisp_plane` key pins it to the wisps table with neither flag set
reads back as durable - so no flag-based rule gets both directions right.

The plane now comes from the seam that knows it. HydrateListComments takes a
CommentPlanes lookup instead of inferring; the unit-of-work reader answers it
from the wisps TABLE (IssueUseCase.GetWispsByIDs, the call edgeReader.ReadEdges
already makes for the same question), once per page, inside the page's own read
transaction. The store-backed seam passes SourceRoutesCommentPlanes because its
source routes ids itself (DoltStore.GetIssueComments picks the table from
isActiveWisp) and would buy a lookup for an argument it ignores. isWispPlane is
deleted: nothing on this path infers a plane any more. A nil lookup is an error
rather than a silent "durable", so a third seam has to answer the question
rather than inherit the default this bug was.

A MISSING WISPS TABLE STAYS "NO WISPS" rather than a failed listing, classified
through the same two helpers the counts query that produced the page uses
(dberrors.MissingTableName + sqlbuild.OptionalWispTable). Any other failure of
the lookup fails the call: a guessed plane answers with the wrong table's
contents and nothing in the response shows it.

Tests. The unit table now asserts residence AGAINST the flags, with each row's
comments present only on the plane it lives on, so a wrong-table read shows up
as missing TEXT and not merely as a wrong flag in a recorded call. Restoring the
flag inference reds exactly the two rows where flags and table disagree
(durable-carrying-no_history, wisp-table-carrying-no-flags) and leaves the two
agreeing rows green. The old `override_wins_over_flags` case is gone:
WispPlaneOverride is `json:"-"` and set only by import, in memory, so no scanned
row can carry it and that branch was unreachable on this path - which is what
made the suite look sufficient (Codex's separate minor, folded in here as the
same root cause). New seam-level tests drive the real uow Reader.List over both
shapes, and pin that a listing without the flag resolves no planes at all, that
a missing wisps table is tolerated, and that any other lookup failure
propagates; emptying the residence answer reds the wisp-row leg.

Also from the review, non-gating:

- types.IssueWithCounts.CommentsOmitted and the OpenAPI property stated the
  marker rule unconditionally on a type Reader.Ready and the claim response also
  return, neither of which calls the epilogue. Both now scope the rule to the
  List surfaces and cite be-ozp, which is where the parent commit deliberately
  left the ready surfaces. (`bd ready --json` does not route through
  Reader.Ready; GET /v0/beads/ready and ClaimNextResponse.claimed do.)
- GET /v0/beads/issues gained no `include_comments` parameter, so its
  description now says so and points at the detail read, in the idiom the
  `revision` paragraph above it already uses.
- One internal/httpapi list test for the new wire field: the marker present for
  a commented row, absent for an uncommented one. It was asserted only by the
  spec file; the detail twin has get_issue_test.go. Neutering
  markCommentsOmitted reds it.

Validation: go build ./...; go vet over the changed packages and again with
CGO_ENABLED=0; make api-check clean, so the spec edits oblige no regeneration;
go test ./internal/workapi/... ./issueops/... ./internal/types/;
TestBothReaderImplementationsAgreeOnTheListEpilogue plus the new plane tests in
./internal/storage/uow/; BEADS_TEST_PROXIED_SERVER=1
TestProxiedServerListComments 3 PASS and BEADS_TEST_EMBEDDED_DOLT=1
TestEmbeddedListComments 4 PASS.

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>
2026-09-27 02:12:13 -07:00
Vishnu J
073556c791
test(httpapi): match missing token file with errors.Is, not Unix text (#6628)
TestNewTokenFileAuthRefusesAnUnusableFile/missing asserted the substring
"no such file", which is Unix-only wording; on native Windows the OS
reports "The system cannot find the file specified." and the test fails.
readTokenFile already wraps the open error with %w, so assert
errors.Is(err, fs.ErrNotExist) for that case and leave the other cases'
message checks alone.

Fixes #6543

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-26 09:45:11 -07:00
Rongjun GENG
2bc7f8de60
fix(serve): retire idle SQL connections before Dolt (#6741)
* 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>
2026-09-26 05:23:11 -07:00
Julian Knutsen
b3d17caa6d Merge release/1.3.0 into main (post-tag forward-port)
Forward-ports the 38 commits that shipped on release/1.3.0 (tagged v1.3.0 at
f45b249ce) into main, as RELEASING.md mandates after a tag. None of them had
ever been forward-ported. Recorded as a merge so main becomes a superset of
the release branch and the lineage is in the history.

Migration ordinal collision (the reason this needed a human-shaped merge):
both branches independently claimed clone-local ignored slot 0026 under
different filenames, so git merged both in with no conflict and left the
series with two migrations at ordinal 26 — a single-integer cursor cannot
address that, and migrationSource.list() panics on it.

Main's ignored/0026_add_wisps_current_revision is renumbered to 0027.
Release's 0026_dep_rekey_dedup_marker is in the shipped v1.3.0 tag, so field
stores have already recorded it at 26 and it can never move; main's twin has
never shipped in any release, so it is the one that is free to move. 0027 was
unused in the ignored series (both sides topped out at 26).

This trips check-migration-hygiene.sh Check C (frozen migrations), which has
no exemption mechanism. That is expected and accepted: breaking the collision
requires a rename, and the ignored series' cursor table is itself dolt-ignored,
so its content hashes are clone-local and never participate in the cross-clone
ContentHashSkew comparison that Check C exists to protect. Main's 0067 body is
deliberately NOT edited for the same reason in reverse — it is main-plane and
its hash IS compared across clones.

Conflicts resolved:

  CHANGELOG.md                       release's finalized [1.3.0] section kept
                                     byte-identical; main's two unreleased
                                     entries (#6023, #5859) moved up under
                                     [Unreleased] where they belong
  cmd/bd/init_safety.go              union — release's added paragraph is
  cmd/bd/init_safety_help.go         accurate against the merged code (three
                                     exit-12 sources, incl. init.go:3147)
  internal/storage/uow/dolt_sql_provider.go
                                     kept main's newProvider refactor AND
                                     release's readOnly field/assertion;
                                     newProvider gained readOnly: opts.readOnly
                                     so release's read-through-refused-migration
                                     behavior survives main's refactor
  .github/workflows/main.yml         single -timeout=30m per release's #6091
  scripts/ci_workflow_test.go        design (flag on the invocation, not in
                                     matrix.test-flags); the shadowed 25m in
                                     matrix.test-flags removed
  scripts/migration-test/lib/versions.sh
                                     union — main's darwin/arm64 corpus plus
                                     release's v1.2.2 linux/amd64 entry
  integrations/beads-mcp/uv.lock     ruff 0.16.5 (release, newer); block is
                                     internally consistent, uv lock --check ok
  default.nix                        vendorHash left at main's value and is
                                     KNOWN STALE — see below

Version stamp lands at 1.3.0 (main had been sitting at the previously-released
1.2.2, this project's between-releases pattern). check-versions.sh: 24/24.

Known follow-up: default.nix vendorHash. The merged go.mod/go.sum is a genuine
union (release's kin-openapi/oapi-codegen bumps + main's newer Dolt stack) and
matches neither side, so neither recorded hash is correct. It must be
regenerated with scripts/update-nix-vendorhash.sh. The repo's automatic fixer
(update-vendor-hash.yml) is dependabot-only and will not run on this PR.
2026-09-15 22:09:13 +00:00
postoso
267085264d
feat(count): support --metadata-field filtering (#6024)
* feat(count): support --metadata-field filtering

* fix(count): review refusal docs, guard test, and changelog

---------

Co-authored-by: postoso <postoso@users.noreply.github.com>
2026-09-02 17:25:57 -07:00
Julian Knutsen
a18416484c
fix(create): wire --storage-class through the proxied, markdown, and graph input paths (#6060)
* refactor(create): extract resolveCreateStorageClass from the direct RunE

The flag→class block (parse, per-type config fallback, ephemeral spelling →
wisp plane, --no-history exclusivity, plane reconciliation) becomes one helper
so the other CLI doors can call the same decision instead of reimplementing or
skipping it. Pure refactor: the direct route's behavior and error strings are
unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(create): wire --storage-class through the proxied, markdown, and graph doors

createInput carries the resolved class, so the proxied single create persists
it, routes `--storage-class ephemeral` to the wisp plane, rejects a durable
class paired with --ephemeral/--no-history, and honors the per-type
storage-class.<type> config default — all four of which it silently dropped.

buildMarkdownBatchRequest resolves the class per template, which fixes `--file`
on BOTH transports at once (one shared projection), and --graph now refuses a
plan-wide --storage-class the way it already refuses --mol-type, pointing at
the per-node storage_class field that works.

The v0 HTTP wire is unchanged: storage_class stays off the create member list
and unknown members are still refused by name. The spec gains one sentence
saying the per-type config defaults are CLI-door policy, so the divergence is
documented rather than silent.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(create): pin the storage-class contract on every CLI door

The pure table covers resolveCreateStorageClass end to end (three classes,
config default, alias-normalized type key, both conflict arms) plus the two
links the proxied bug broke: gatherCreateInput populating createInput and
buildCreateIssueFromInput carrying it.

storage_class_proxied_integration_test.go is the proxied mirror of the embedded
suite, asserting the raw storage_class cell on the plane each request should
have landed on — the JSON alone would have agreed with itself. It reproduces
what the field report hit (unversioned dropped, an ephemeral request minting a
durable row, the wisp-plane conflict silently collapsed, the config default
skipped) as failing assertions.

The embedded suite grows --file subtests on all four class outcomes and the
--graph rejection.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-29 07:16:04 -07:00
Julian Knutsen
d594092ebb
security: v1.3.0 dependency + toolchain bumps (7 reachable stdlib advisories, criticals triaged) (#6047)
* security: pin build toolchain to go1.26.7

go1.26.5 carries 8 stdlib advisories, 7 of them reachable from the shipped
bd binary. Verified with govulncheck in call-graph mode against ./cmd/bd,
toolchain pinned so the analysis cannot drift:

  GO-2026-6218  net/url        quadratic resolvePath
  GO-2026-6091  html/template  JS-regexp context tracking
  GO-2026-6090  crypto/tls     post-handshake message flood
  GO-2026-6089  net/http       ReadHeaderTimeout on the h2c check
  GO-2026-6088  encoding/xml   recursion depth
  GO-2026-5972  encoding/asn1  recursion depth
  GO-2026-5026  net/http       vendored x/net/idna punycode
  GO-2026-5942  net            dnsmessage SVCB/HTTPS RR (linked, uncalled)

`bd serve` is a real HTTP server and bd makes TLS client connections, so
these are live paths rather than dead weight: httpapi.Serve reaches four of
them directly. go1.26.6 fixes all eight; 1.26.7 adds one more net/http fix.
After the bump the same scan reports zero.

The `go` directive stays at 1.26.5 so importers of the module keep their
current floor; `toolchain` is what we actually build with. release.yml
builds the shipped binaries with a bare `go build` under the default
GOTOOLCHAIN=auto, which honors the toolchain line.

The Makefile needed the second half of this. It pinned GOTOOLCHAIN from the
`go` directive, which is the importer floor, not the build version - left
alone it would have held every make target (the test suite, the npm and MCP
package gates, local `make build`) at 1.26.5 while the release binaries
moved to 1.26.7, which is both a silent downgrade and a split between what
CI tests and what we ship. It now reads `toolchain` first and falls back to
`go` when there is no toolchain directive, preserving the original reason
for pinning: one exact version so the compile tools and coverage
instrumentation cannot disagree.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* security: bump x/crypto, x/mod, klauspost/compress, moby/go-archive

Four advisories, none reachable from the shipped bd binary; these are
hygiene bumps that also clear the Dependabot board.

  golang.org/x/crypto           v0.54.0 -> v0.55.0   GO-2026-6303
  golang.org/x/mod              v0.37.0 -> v0.40.0   GO-2026-6179/6180
  github.com/klauspost/compress v1.18.5 -> v1.18.7   GO-2026-5841
  github.com/moby/go-archive     v0.2.0 -> v0.3.3    CVE-2026-17106 (#140)

Reachability, from `go list -deps ./cmd/bd` plus govulncheck call-graph mode:
x/crypto/ssh proper enters only through testcontainers (test-only); the
compress advisory is in the s2 codec, which is not linked into bd at all
(bd links zstd/gzip/flate/huff0 via dolt); the x/mod sumdb/tlog code is
required but never called; go-archive is testcontainers-only and absent
from the binary's package graph entirely.

go-archive goes to v0.3.3, not the advisory's minimum v0.3.0: v0.3.0's
hardened extraction rejected absolute symlinks and hardlinks and broke
device nodes and implied directories, all fixed across v0.3.1-v0.3.3.

MVS carries x/net, x/text, x/tools and x/telemetry along. No replace
directives, and the dolt pin is untouched - dolt requires older versions of
all three x/ modules, so beads' go.mod already wins the version selection.

The examples/ modules reach the parent through a `replace` directive, so
their recorded graph goes stale on any root go.mod change and both failed
scripts/build-examples.sh with the documented "updates to go.mod needed".
Re-tidied here rather than left for the advisory job to warn about; the
diff is purely the mirror of the bumps above.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* security: bump oapi-codegen to v2.7.1 and kin-openapi to v0.144.0

Clears the board's one critical (#133, GHSA-r277-6w6q-xmqw, CVSS 9.1) plus
#142, #141, #134 and the low #132. All five are codegen-tool-only:
kin-openapi reaches the module graph solely through the go.mod `tool`
directive for oapi-codegen, no beads source file imports kin-openapi,
oapi-codegen or openapi3filter, and `go list -deps ./cmd/bd` contains none
of them. The critical is a fail-open bug in openapi3filter's
ValidationHandler.Load(), middleware this repo never runs - request
validation in internal/httpapi is hand-rolled. Dependabot scopes the alert
"runtime" because it cannot model Go tool-directive semantics.

Both must move together: oapi-codegen v2.6.0 does not compile against
kin-openapi v0.144.0 (pkg/codegen/schema.go:909, openapi3.MappingRef vs
string). v2.7.1 is the minimum-fix pair, chosen over the latest 2.8.0/0.149.0
to keep codegen churn off a release branch.

The `make api-gen` regen diff is two lines of real change: the generated
BearerTokenScopes constant picks up a generated named context-key type
instead of being an untyped string. The identifier has no references outside
types.gen.go. `make api-check` is green - regeneration is idempotent,
pinning.go's compile-time welds hold, and TestWireTagBijection passes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* security: refresh beads-mcp uv.lock (clears all 19 pip alerts)

`uv lock --upgrade` with fastmcp still pinned ==3.4.5. Every one of the 19
Dependabot alerts on integrations/beads-mcp/uv.lock is a fastmcp transitive,
and each lands at or above its first-patched version:

  mcp              1.25.0 -> 1.29.1   #129 #128 #127 (high)
  cryptography     48.0.0 -> 50.0.1   #137 #138 #82 #139
  pyjwt             2.12.1 -> 2.13.0  #79 #136 #81 #78 #135
  joserfc            1.6.5 -> 1.7.4   #113 #109
  python-multipart 0.0.27 -> 0.0.32   #88 #87 #86 #85
  idna                3.11 -> 3.19    #68

Real exposure was already low: beads-mcp runs stdio transport only
(server.py's mcp.run_async(transport="stdio")), so the three high mcp-SDK
alerts - WebSocket Host/Origin validation, HTTP session principal handling,
task-handler cross-access - are all HTTP/WS-transport bugs this server never
reaches, and the auth libraries ride along with fastmcp's extras rather than
being used by beads-mcp's own code. The lock governs dev and CI installs;
PyPI users resolve fresh and already get patched versions.

mcp 1.25 -> 1.29 is the only behaviorally interesting jump. The full package
gate is green: uv sync --locked, ruff, mypy, 228 passed / 5 skipped, uv build.
The resolved lock is byte-identical under uv 0.9.5 and CI's uv 0.11.16.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* chore(nix): update vendorHash for go.sum changes

The go.mod/go.sum bumps in this branch invalidate the proxyVendor
fixed-output hash in default.nix, which fails the nix-build gate. The
workflow that repairs this automatically only fires for dependabot PRs
targeting main, so it does not cover this branch.

Recomputed with scripts/update-nix-vendorhash.sh's flow and verified:
`nix build .#default` completes green, which also confirms the new
`toolchain go1.26.7` directive is compatible with default.nix's
GOTOOLCHAIN = "local".

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-28 23:26:04 -07:00
Julian Knutsen
b858a29e4a
fix(contracts): JSON contract fixes before 1.3.0 freezes them — string revision tokens, --set-metadata scalar typing, create --json nano timestamps (#6053)
* fix(metadata): restore v1.2.2 scalar typing for --set-metadata values

8ebd53e88 moved the CLI's metadata-edit helpers into
internal/storage/metadata.go and, in the move, replaced v1.2.2's
toJSONValue inference with a MetadataEditValue that always json.Marshals
the value as a string. The intent was GH#4146 (a numeric-looking id or a
version like "1e3" came back as a JSON number, breaking map[string]string
Go consumers), but it silently changed the shipped CLI contract:
`bd update --set-metadata k=5` started storing "5" instead of 5. That
regression shipped only in the deprecated/superseded v1.2.1, never in
v1.2.2, and 1.3.0 would freeze it.

Restore v1.2.2's inference body-for-body inside MetadataEditValue, so the
parity claim stays checkable against `git show v1.2.2:cmd/bd/update.go`:
"null" is JSON null, "true"/"false" are booleans, a spelling that scans
as a float AND is valid JSON on its own is emitted as that literal
(5 -> 5, 1e3 -> 1e3, 0.50 -> 0.50, while 05, +5 and NaN stay strings),
and everything else is a string. Every --set-metadata caller funnels
through this one function: embedded (cmd/bd/update.go ->
storage.ApplyMetadataEdits), proxied (parseSetMetadataFlags) and the
update executor's []string path.

GH#4146's concern is served by the explicitly typed routes, which are
untouched: --metadata / --metadata-json on the CLI (MergeMetadataJSON)
and the typed set map on the HTTP/Go path (applyTypedMetadataEdits).

No data migration: a "5" written by an in-window build is
indistinguishable from a string a user set intentionally through the
typed paths, so normalizing stored metadata would corrupt intended data.
Re-running the same --set-metadata k=5 retypes any given key.

Tests: new table in internal/storage/metadata_edit_value_test.go pinning
the v1.2.2 matrix plus an ApplyMetadataEdits end-to-end; the tests that
pinned the string-always behavior are flipped (domain/db mergeops suite,
update_lifecycle patch mapping, cmd/bd toJSONValue table) and the
embedded + proxied CLI suites now assert a stored JSON number. The
contract corpus is regenerated: its update/list/ready goldens run
`--set-metadata phase=2`, so `"phase": "2"` becomes `"phase": 2` and
nothing else moves.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(create): echo full-precision timestamps from bd create, not the DATETIME(0) re-read

b92442d1a routed `bd create` through issueops.Lifecycle, whose executors
build their result by re-reading the row they just wrote
(HydrateIssueOperationResult -> GetIssueInTx). created_at/updated_at are
DATETIME(0) columns, so that snapshot comes back at whole-second
precision and cmd/bd/create.go echoes it. v1.2.2 returned the caller's
own in-memory struct, which PrepareIssueForInsert stamps with
time.Now().UTC() including nanoseconds, so `bd create --json` used to
print e.g. 2026-08-28T12:34:56.789012345Z. Agents that create several
issues in a burst order them by exactly that fraction; rounded to the
second they all tie.

Restore the echo with OverlayCreateTimestamps: after hydration, put back
the created_at/updated_at (and closed_at, when the write set one) the
INSERT actually sent. Everything else on the snapshot stays DB-truth,
which is the facade's contract — only create, and only these fields.

Applied at every create body, not just the two the CLI reaches:
issueops.ExecuteCreate and ExecuteCreateBatch behind the dolt and
embedded-dolt stores, and the unit-of-work provider's own Create,
CreateBatch and batch-apply create item, which is what the proxied server
and POST /v0/beads/issues run on. Fixing only the shared executors would
have left the two bodies disagreeing about the same promise.

What is NOT changed, because it is not a regression: `bd show --json` and
`bd list --json` answered whole seconds in v1.2.2 too — they read the
column — and update/close/reopen re-read after writing there as well.
Widening the columns to DATETIME(6) would give reads sub-second times
too, but that is a schema migration on user Dolt DBs and touches paths
that deliberately compare at second precision; it is a 1.4 change.

The accepted skew, which predates this and stays: the engine ROUNDS to
the column rather than truncating, so a later read of the same row can
sit up to half a second either side of the create echo.

Tests: two new conformance cases, run on all three backends —
RunLifecycleCreateEchoesSubSecondTimestamps (a caller-supplied
nanosecond stamp must survive to the result exactly; the auto-stamped arm
stays a bounded smoke check, since requiring a non-zero fraction off the
clock is flaky by a billionth) and RunBatchCreatorEchoesSubSecondTimestamps
(per item, since both bodies build the result one snapshot at a time).
Plus a cmd/bd embedded test asserting `bd create --json` prints a
fractional part, and one httpapi assertion that the wire does not round
the role's snapshot on the way out. All four fail on the pre-fix tree.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(httpapi,types)!: revision / expected_version tokens are opaque JSON strings

The optimistic-concurrency token is minted by freshRowLock over the FULL
int64 range (crypto-random, non-zero) and published on the wire as a JSON
number: `revision` on responses, `expected_version` on guarded requests.
A JSON number does not survive a consumer that decodes into an IEEE-754
double — JavaScript's JSON.parse, Go's `any`, Python's `float`, jq. Live
tokens run past 5e17, where a double's ulp is already 64, so such a
client reads back a value NEAR the token, echoes that as its guard, and
earns a 409 against a row nobody else touched. The spec already carried
"DECODE IT AS A 64-BIT INTEGER" paragraphs telling clients to work around
this; that is a workaround for a wire type that should not have been a
number.

Emit and accept the token as a decimal STRING instead. It is documented
as opaque and EQUALITY-ONLY — compare it, never order or interpret it —
and a string round-trips exactly in every JSON consumer. It also leaves a
future backend free to mint a token that is not an int64 at all.

Internals are untouched: freshRowLock, the row_lock BIGINT column, its
migration, types.Issue.RowVersion and the ExpectedVersion *int64 guards
on the issueops requests all stay int64. Only the wire projection moves,
through the one spelling of the encoding — types.RevisionToken and
types.ParseRevisionToken.

STRICT STRING ONLY, with no transitional number-or-string acceptance.
This API already refuses unknown members by name and keeps one spelling
of the guard, and a number is precisely the shape a double-based client
has already rounded before it left the client — accepting it would
preserve the defect. A numeric guard is a 400 naming the member.

Chosen over clamping freshRowLock to 53 bits: a clamp does not fix rows
already minted with full-range tokens by in-window builds, so a JS
consumer reading one still rounds past 2^53 — repairing that would need a
row_lock normalization sweep over issues and wisps, a migration days
before a tag.

Surface: types.IssueDetails.Revision (what `bd show --json` prints and
GET /v0/beads/issues/{id} returns), the five hand-assigned httpapi
response fields, applyVersionGuardMember (now the reader for the batch
update item too, ahead of its typed decode, so a mistyped token still
earns a 400 naming the member), Problem.expected_version, and 14 OpenAPI
members regenerated through `make api-gen`. actual_version goes with them
— it is documented as "the `revision` the row was found holding", so
leaving it an integer would make the expected/actual pair disagree about
its own type; it is declared but never populated, so nothing changes
behaviorally.

Nothing shipped in a tagged release ever carried this member: v1.2.2 has
no internal/httpapi at all and no `revision` anywhere on the wire, so the
whole surface is in-window and can still be changed compatibly. Legacy
migration-0054 rows read as the string "0" with the same CAS semantics.

Corpus goldens are UNCHANGED: the canonicalizer already replaced any
`revision` value with the string "<REVISION>" whatever its JSON type.

Tests: types-level pins that the marshaled member matches `"revision":
"-?\d+"` and that RevisionToken/ParseRevisionToken round-trip MinInt64,
MaxInt64 and 2^53+1, plus a JS-realistic decode of 2^53+1 with a float64
control proving the token really is one a number would corrupt; httpapi
refusal tests for a numeric guard on update, close, reopen, delete and
both batch item kinds; a 409 echo asserted as the string; and the proxied
serve integration tests now splice the response's own token back in
verbatim rather than re-rendering a parsed one.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-29 05:20:27 +00:00
Julian Knutsen
8aaefe2d4f
feat(httpapi): serve bd list's order with sort on listIssues (#5666)
* feat(httpapi): serve `bd list`'s order with `sort` on listIssues

The issue listing served one order, `(created_at DESC, id ASC)`, because the
cursor is a keyset position in it. The spec stated the constraint in its own
words: "the sort order is welded to the cursor contract, and a new order needs
new surface." That welding put the cost on every client wanting `bd list`'s
ordering — the only way to get it was to page the whole result set and sort
locally, which is the one cost on this surface that grows with the project.

Measured against a real `bd serve` over 1400 rows at the 200-row page an HTTP
client actually uses: walk-and-sort is 7 requests plus a client-side
comparator, `?sort=priority` is 1. Both are checked against `bd list --json`
row for row, because the claim that matters is not "fewer requests" but "the
same order".

`sort` takes `created` and `priority` and nothing else. Each value is a keyset
contract — a position shape, a strictly-after predicate, an index — not a
display preference, and both keys are provably total (priority and created_at
are non-null, id is unique) so a page boundary inside a run of equal keys
resolves on id. The seven other orders `bd list --sort` takes have no such key:
`id` is natural-numeric and no database expresses it, `updated` moves on every
write, `closed` is nullable, and status/title/type/assignee are mutable and
unindexed. `priority` here is (priority ASC, created_at DESC, id ASC), which is
both `bd list`'s flagless order and what `--sort priority` produces — a stable
priority sort over the created order is the same sequence — so one served order
retires the walk for both.

Absent `sort` still means `created`, permanently: it is the compatibility
contract for every client written before the parameter existed.

THE CURSOR NOW CARRIES ITS ORDER. This is the half that makes the parameter
safe rather than merely useful, and the obvious implementation gets it wrong.
The token was base64 of `{t,i}` with no binding, so a created-order cursor
replayed under `sort=priority` decoded perfectly and was read as a position in
a different total order — a page that skips and duplicates rows, served with a
200, undetectable by the client. Tokens are now `v2` with an explicit order
member, and decode takes the wanted order as a parameter so a mismatch is
unrepresentable at the seam rather than merely detectable past it. Outstanding
`v1` tokens stay readable as the created-order positions they are, so no
traversal in flight has to restart. This does not contradict "the token carries
no filters": filters select the set, the order decides what the position means.

Storage grows one field. IssueFilter.AfterPriority extends the existing
position; the predicate nests the created one rather than restating it, because
the created/id comparison is only reachable at the cursor's own priority.
Flattening it the way the created predicate's leading-bound trick invites looks
equivalent and is not — it re-delivers rows at the cursor's priority created
after it, which the new conformance walk catches against real Dolt.

NO INDEX MIGRATION, by measurement rather than by omission. A composite
(priority, created_at, id) index was tried on Dolt 2.2.0 against the production
predicate, in both the plain ascending and the mixed-direction spelling Dolt's
DDL accepts: the plan is byte-identical in all three cases, keeping the
single-column priority seek and the TopN. It would have bought write
amplification on every insert and every priority update for no measured change.
The sargability guard pins what is achieved — an IndexedTableAccess range on
idx_issues_priority — and records the measurement to redo if Dolt learns to
stream the composite.

Agent-Signature: claude-opus-5
Co-authored-by: CI Bot <ci@beads.test>

* fix(changelog): drop leftover diff3 conflict marker in sort entry

The rebased adopt-PR head left a stray '|||||||' merge-base marker on the first line of the new `sort` CHANGELOG entry (CHANGELOG.md:381), which `git diff --check` flagged as a leftover conflict marker. Remove only the marker line; the resolved entry content is unchanged. Maintainer fixup for PR #5666 adoption review.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-08-27 09:21:12 -07:00
Bee
67556264c4
feat(events-journal): record the mutating actor on every journal row (#5908)
* feat(events-journal): record the mutating actor on every journal row (bd-mbrxm)

The bd_events_journal row recorded op/ts/issue_id/payloads but never WHO
performed the mutation, so downstream attribution (e.g. same-field,
different-actor conflict detection over the journal) had nothing to key on.

- Schema: `actor VARCHAR(255) NOT NULL DEFAULT ''` on bd_events_journal, on
  both migration planes (0066 + ignored/0025) so the two-door shape converges.
- Record*InTx takes the actor explicitly (no ambient ctx) — every call site
  already sits beside an audit-event emit that has the actor in hand; thread
  that same value (incl. the UOW door's MovePersistence). Comment rows carry
  the comment's author. Blank = unattributed (derived maintenance, deletes —
  follow-up bd-zxt49 — and pre-column rows); never user attribution.
- `bd events tail/export` JSON gains an additive, omitempty `actor` field;
  the wire vocabulary is otherwise untouched (openapi spec, reference doc,
  CHANGELOG; golden regenerated deliberately).
- CLI bundle: direct-DDL override for 0066 in cliCompatibleMigrationSQL —
  dolt 2.2.0 (CI's pin) no-ops the prepared ALTER (dolthub/dolt#11345), so
  without it the parity oracle sees actor only on the runtime side. Measured:
  AllMigrationsSQL() through 2.2.0 lands bd_events_journal WITHOUT actor and
  2.3.1 WITH; with the override both land it. String assertions + a
  requireDoltColumnShape guard pin it without a Dolt binary.

Verified (enumerated): go build ./...; gofmt; go vet; migration hygiene
(BASE_SHA=07c163df0); internal/storage/schema (string test + CLI-apply test
under dolt 2.3.1 AND 2.2.0); internal/storage/domain/...; eventsjournal;
journalops; httpapi (wire-tag bijection incl. actor); storage/dolt
-run 'Journal|EventsJournal|ActorAttribution' against real dolt;
cmd/bd -run Events (golden); storage/uow -p 1 (-timeout 90m): every test green except 3
timeout-shaped reds (ConcurrentInstantiation lock-acquire, EndToEnd 30s
init-schema, PreexistingDirty docker reaper) in a /private/tmp worktree
under box load 40-68; the same 3 at origin/main in that worktree also
red, and at THIS commit in the primary clone all 3 PASS (130s) — box
flake, not the diff.

* docs(events-journal): align seq:4 example with the actorless golden fixture

Maintainer review follow-up on PR #5908 (bd-mbrxm). Both reviewers flagged that
the reference JSONL example's seq:4 is_blocked derived-maintenance row carried
"actor":"worker-1", contradicting the record-contract field table (derived
is_blocked recomputes are actorless) and the golden fixture
cmd/bd/testdata/events_journal_records.jsonl, which emits that same seq:4/bd-100
row without an actor. Drop the actor member so the doc example mirrors the
fixture byte-for-byte and consumers do not misclassify a system recompute as a
user write.

The other, optional review nit (the "stray typographic quote" in the
insertEventRow doc comment) is intentionally left as-is: that glyph is gofmt's
canonical rendering of '' in a Go 1.19+ doc comment (TeX-style quoting turns two
ASCII apostrophes into U+201D), so the reviewers' literal '' suggestion is a
no-op the enforced pre-commit gofmt reverts on every commit. It is cosmetic and
non-gating; the DDL and INSERT are already correct.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-08-23 13:55:59 -07:00
Julian Knutsen
d38ac728b5
fix(httpapi): make beads_dir and repo_root optional in ContextResponse (#5757)
GET /v0/beads/context required both. They are the only two members of the
identity handshake that describe the SERVER's filesystem rather than the
workspace's logical identity, and an absolute host path is not something a
remote client can act on: it cannot open it, and project_id, database and
backend are what tell two servers apart.

The schema already called publishing them a cost "an operator accepts when
binding beyond loopback". While they were required, accepting it was the only
conforming option -- a deployment that did not want to disclose its filesystem
layout had no way to withhold them and still serve a body matching this
document. Making them optional restores that choice, in the only direction
that cannot break a client that was already reading the document.

No body changes. bd serve publishes both, always, exactly as before; the
optionality is a promise to clients that absence is legal and must be
tolerated, not a switch on the server. In Go the two generated members become
*string, and the handler takes the addresses of the same published values.

TestContextResponseRequiredSet pins the split from both sides -- the
document's required list and the generated struct's pointer-ness -- so
re-requiring a member re-imposes the disclosure only with a test edit, and
dropping one that belongs there fails the same way.

Co-authored-by: CI Bot <ci@beads.test>
2026-08-19 22:58:03 -07:00
Jim Wordelman
28d65c1329
fix(httpapi): remove flaky race in TestSemaphoreShedsLoadInsteadOfQueueingForever (#5808)
* 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.
2026-08-19 21:01:10 -07:00
Jim Wordelman
f6a191fd64
fix: canonicalActor collapses the --/__ axes correctly; claim-verify uses ActorMatches (be-p7dzx, bundled be-vc51) (#5856)
* test(feat): red — canonicalActor collapses the --/__ axes: misses gascity slash identities and widens ActorMatches (bundled with be-vc51 authorize/verify split) (refs be-fh0g)

* feat: green — canonicalActor collapses the --/__ axes: misses gascity slash identities and widens ActorMatches (bundled with be-vc51 authorize/verify split) (refs be-fh0g)

* docs(identity): correct the five contract surfaces that still document the pre---- collapse rule

canonicalActor stopped collapsing an exact "--" run when it started decoding
that run to "/", but five places still tell a reader the old rule: a run of
".", "_" or "-" matches any other such run. That is now false for "--", and
two of the five are public contract surfaces rather than internal comments --
the OpenAPI description a client reads, and the conformance text a backend
implementor is expected to satisfy.

Corrected in place, all saying the same thing: an exact "--" run decodes to
"/" because that is gascity's session-name encoding of a rig-qualified
agent's slash, so "a--b" matches "a/b" and no longer matches "a__b" or "a-b";
longer and mixed runs, "__" included, still collapse.

  issueops/releaser.go                      ExpectedAssignee's contract
  issueops/issueops.go                      the update-side cross-reference
  internal/httpapi/spec/openapi.v0.yaml     wire contract (source of truth)
  internal/httpapi/apigen/types.gen.go      regenerated via make api-gen
  backend/conformance/releaser_contract.go  cross-backend contract text

The conformance limb is annotated rather than re-pinned: the respelling it
exercises is "-" -> "_", which this change does not affect, so it stays green
either way -- which is exactly why CI could not catch the stale text. Adding a
"--" limb there would pin new cross-backend behavior and is a wider change
than correcting a contract description.

This is the keep-in-sync obligation identity.go records under ga-5ksp5,
applied to the documentation half.

* docs(changelog): record the --/__ equivalence-class change under [Unreleased]

The actor-matching change is user-visible and silent: it moves which stored
spellings compare equal for ExpectedAssignee on release and update, and for
claim/close/unclaim authorization. "gastown--mayor" starts matching
"gastown/mayor" and stops matching "gastown__mayor" and "gastown-mayor".

The entry says the widening is the intended fix -- "gastown--mayor" is the
agent "mayor" on rig "gastown" while "gastown__mayor" is the dotted alias
"gastown.mayor", and matching them was wrong -- and then states the part a
reader actually needs to act on: any stored "--" spelling that is NOT a
gascity slash encoding changes equivalence class with no error to notice.

---------

Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
2026-08-19 13:23:35 -07:00
Julian Knutsen
2c06c76b51
Publish PUT and DELETE /v0/beads/config/{key}, the write half of issueops.WorkspaceConfig (ga-098zm) (#5596)
* Publish PUT and DELETE /v0/beads/config/{key}, the write half of issueops.WorkspaceConfig (ga-098zm)

Settings are read-only over v0: `WorkspaceConfig.SetSetting` and `UnsetSetting`
have no wire operation, which leaves the infra-over-http surface able to see that
a workspace is configured and unable to configure it. These are those operations.
The role, its contract and all three legs already exist; this slice wires them.

Spec first, then `make api-gen`, then the handlers.

PUT AND DELETE ON THE KEY'S OWN PATH, and the methods ARE the argument rather
than a preference. The resource has a canonical URI, the caller names it, and the
request carries the value that becomes its whole state — that is what PUT already
means, and the write is idempotent in the strict sense. `POST /v0/beads/memories`
is the operation this is deliberately NOT: that one posts to the COLLECTION
because its key may be derived from the content, so the caller cannot always name
the resource it is creating. Here it always can. The removal is
`DELETE /v0/beads/memories/{key}`'s shape unchanged — one named resource, no body,
no flags — and all three rows share one pattern, differing only in method, which
ServeMux registers together.

THE KEY IS THE PATH'S AND APPEARS NOWHERE IN THE BODY, so `SetSettingRequest`
carries exactly one member. A body spelling the anchor a second time is one
request with two anchors and a question about what to do when they disagree; the
parity test asserts the absence from both sides.

## The redaction doctrine, and what the write half owes it

A KEY WHOSE NAME MARKS IT CREDENTIAL-BEARING IS WRITABLE, resolved from the
facade's actual behavior rather than from the shape of the read. `ValidateSettingWrite`
refuses an empty key, `issue_prefix` in either spelling, and a `status.custom`
that does not parse — and nothing else; `config.IsSecretKey` appears nowhere in
the write path. The CLI's own secret guard is `CheckSecretKeyGitSafety`, which is
gated on `IsYamlOnlyKey` and protects a git-tracked **config.yaml** — a different
plane with a different hazard, a credential in git history — and returns clean for
every key this operation reaches. The role states the asymmetry itself: the reads
are a firewall, the writes are not, and a write discloses nothing. Refusing here
would be a refusal the role does not have, invented by the projection, and it
would leave a workspace's credentials visible as PRESENT and permanently
unconfigurable through this door.

WHAT THE WIRE OWES INSTEAD IS THE RESPONSE. Redaction is caller-independent and
decided on the KEY, and `Setting.value` says in one place that a `redacted: true`
entry withholds a value that may well be stored — so a write answering with both
would make one schema mean two different things depending on which operation
produced it. The write is therefore projected by `wireSetting`, the SAME function
the read is projected by, and the test states that as an equality rather than as
two assertions that could drift: the body of a PUT is byte-for-byte the body of
the GET that follows it. It costs the caller nothing, because the role promises
the stored value equals the value sent for every key this plane accepts, so the
echo carries no information the caller does not already hold.

The removal publishes `key` and nothing else. No `removed` flag — the storage seam
discards the affected-row count on all three legs, so the member would be a value
one of them had to invent — and no `value`, which on the one settings operation
that withholds nothing would publish exactly the credential the read redacts.

## Absent-vs-empty, and the 404 that is not here

REMOVING A KEY NOTHING SET SUCCEEDS. This is where the operation parts company
with the memory delete it otherwise copies: that role reports Found, and `bd recall`
already has an exit-code contract for the miss. This one cannot — an absent key
and a key stored as the empty string are one answer on this plane, the same
conflation `GET /v0/beads/config/{key}` has no 404 for — so the operation states
an intended END STATE, and the same request twice is 200 and then 200. The
document also records what the removal does NOT undo: `status.custom`'s
projection survives the row it came from, on all three implementations
(bd-yby99.33), as does the protected key's write-refused/remove-permitted
asymmetry (bd-yby99.34).

The empty string is a legal VALUE and is stored, not read as a removal: a caller
that meant "remove it" has DELETE, and conflating the two would make one request
mean whichever the handler guessed.

## The one bound that is the write's alone

`config.key` is VARCHAR(255) and the PUT INSERTS into it, so an over-long key is
an error from the column — a 500 for a request the caller could have fixed. The
GET and the DELETE COMPARE the same value and never store it, so a key no column
could hold matches nothing and already has an answer, and refusing it there would
be a refusal the role does not have. That is `releaseExpectedAssignee`'s rule
applied to the other keyed plane, and the asymmetry is asserted in both
directions.

THE ROLE'S 400 CARRIES NO `param`, and that is the depguard rule doing its job
rather than a shortcut. Two of the role's refusals are reachable and they name
different members — the protected key, and a value that does not parse — and
telling them apart takes the role's protected-key VOCABULARY, which this package
cannot hold: `httpapi-transport-boundary` denies internal/workapi from every
non-test file here, precisely so a second copy of a shared rule cannot exist to
drift. `detail` carries the role's own sentence, which names what to send instead;
every refusal this handler owns names its member.

ONE STALE SENTENCE FIXED ON THIS SURFACE. `listSettings` justified redaction with
"this API has no authentication", which stopped being true when #5516 landed the
optional bearer and which #5545 rewrote everywhere except here; settings.go's file
comment carried the same sentence. Both now say what is actually load-bearing — a
configured bearer is a single shared token that decides WHO may call and never
what a caller who is let in may read — which is the statement this whole slice
depends on. `forgetMemory`'s description carries the same staleness and is left
for that surface's own change.

CENSUS +1 EACH, twice over: two spec paths on one existing path item;
SetSettingRequest and RemovedSetting; the document's no-query-parameter list and
its two counts; two route rows on the pattern the read already registers; two
capability tokens in the ContextResponse prose (the only hand edit — Capabilities()
is derived); OpSetSetting and OpUnsetSetting; two operationCodes rows
(getSetting's vocabulary, no code minted). NOTHING new in the role plumbing:
Config.Settings, sourceRoles, roleSourceNames and s.workspaceConfig() already
carry this role, and the hook decorator's WorkspaceConfig accessor deliberately
wraps nothing — the workspace hook vocabulary hands a script an ISSUE, and a
settings write has none to name, so there is no RoleFiresHooks case to add.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Bound the settings value at the edge, and pin PUT's idempotence and the no-leak in bytes

Review found this branch shipping the exact hazard its own key bound was written
to prevent, plus two properties driven live and pinned by nothing.

## `config.value` had no bound, and it is a TEXT column

`settingWriteKey` refuses an over-long KEY with a 400 naming the member, and the
comment on it says why: an over-long key would be "a 500 for a request the caller
could have fixed". The VALUE beside it had no such check and lands in a `TEXT`
column. Measured before the fix: a 100 KiB `PUT` is a generic 500 out of the
column — the one code that tells the caller nothing about how to fix it — on the
same operation, in the same PR.

Bounded at the edge, keyed on a storage constant rather than a literal, refusing
with `param: "value"` before the role is asked.

BYTES, NOT CHARACTERS, which is why this is `types.CheckTextLen` beside
`CheckFieldLen` rather than the same helper with a bigger number: MySQL and Dolt
bound a TEXT column by ENCODED length, so 40000 two-byte characters overflow it
while 65000 ASCII ones do not. A rune-counting bound would have accepted the
former and handed the 500 back. Both directions are pinned — exactly
`MaxTextBytes` is accepted and reaches the role, one byte more is refused, and
the multi-byte case is its own test — and all three mutations (bound removed,
runes instead of bytes, one byte too strict) fail it.

NOT WIDENED, deliberately, and this is the opposite call from the ephemeral
comment column in the commit before it. A comment is a DOCUMENT — a stack trace,
a diff, a transcript — and the two comment planes disagreeing about one was a
bug. A setting is a VALUE: nothing this plane holds is a megabyte of
configuration, so the narrow bound is the honest description of what a settings
row is for rather than a limitation to widen later. The spec now states the
number and the contrast instead of claiming the 1 MiB body cap is the only limit.

## Two properties that were driven live and pinned by nothing

PUT'S IDEMPOTENCE. The method's whole argument is that the same request twice
leaves the same row, and the E2E exercised it while no test asserted it. Now
pinned on both halves: the second response is byte-for-byte the first, and BOTH
calls reach the role — the second half matters because the role performs its
write and its projection unconditionally (a no-op detection would make repairing
a drifted table depend on the row having changed, which is the state that needs
repairing), so this surface must not short-circuit either. Verified with a
compiling short-circuit mutation, which the "want 2" assertion catches.

THE NO-LEAK GREP NOW READS RAW RESPONSE BYTES rather than the decoded map. The
integration test already greps marshaled JSON; the unit test was checking members
it had thought to name, which an extension member, a duplicated key or an echo
inside a `detail` string would all walk past. Demonstrated: a mutation that adds
a `stored_preview` member carrying the credential passes every member assertion
in that test and is caught only by the byte grep — which is also what a client, a
proxy log and an access log actually receive.

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>
2026-08-10 19:47:21 -07:00
Julian Knutsen
cc3d0bcf3c
Publish POST /v0/beads/issues/{id}/comments, the wire half of issueops.Commenter (ga-rslox) (#5594)
* Publish POST /v0/beads/issues/{id}/comments, the wire half of issueops.Commenter (ga-rslox)

The commenter is one of the facade roles the ext-api-store audit lists with no
wire operation, and comment READS already ride `getIssue?include_comments=true`.
This is the write. The role, its contract and all three legs already exist; this
slice wires them.

Spec first, then `make api-gen`, then the handler.

IT IS A SUB-RESOURCE COLLECTION OF THE ISSUE, and the argument is
listRelatedIssues' applied to a write: the row this creates is the SAME pinned
`Comment` schema `GET /v0/beads/issues/{id}?include_comments=true` already carries
under `comments`, so the operation that appends one belongs on the resource whose
members it publishes. A PLAIN collection POST rather than a custom method, for
`POST /v0/beads/issues`' reason — creating one member of the collection a path
names is what POST already means — and the collision worth checking rather than
assuming is the POST wildcard: `/v0/beads/issues/{idop}` matches ONE segment after
`/issues/` and this path has two, so the dispatcher never sees a request for it.
Checked by driving the documented path, not by reading the pattern.

THE COLLECTION PUBLISHES NO GET, and that is a statement rather than a gap. No
role answers a comment PAGE: issueops.Commenter says reading the thread is a
second question with a cursor of its own, so a GET here would be this surface
inventing the role that declined to exist. A GET lands on the catch-all and gets
the 404 every method mismatch here gets; 405 is not in the v0 vocabulary.

`author`, NOT `actor`, AND IT IS STILL CALLER-ASSERTED. The two are not the same
member wearing a different name: an `actor` is the principal a mutation is
attributed to and is no part of what the mutation wrote, while this value IS part
of the row and is echoed back by every read of the thread — so it is spelled the
way the `Comment` element that carries it back spells it. It is NOT the
authenticated principal even where a bearer is required, on the claim's terms: the
token a deployment configures admits a client to the whole surface and names
nobody. A reader of the thread is reading a claim the writer made about itself.

THE TWO MEMBERS ARE VALIDATED TO DIFFERENT DEPTHS, and the difference is the
column. `author` lands in a VARCHAR(255) every renderer of the thread prints, so
it gets `actor`'s rules whole — trim, non-empty, 256 bytes, 255 characters,
no control runes — through validateNameMember, which is validateActor's body
parameterized by the member's spelling rather than a second copy of the bounds.
`text` lands in a TEXT column stored VERBATIM, so it is checked for SHAPE only:
no trim, no length bound, no character rule, because a comment is routinely a
stack trace or a diff and the newlines are the comment. Its one content rule —
blank after trimming — stays in the ROLE, rememberMemory's posture, so `bd comment`
and this endpoint refuse the same input with the same sentence.

A WISP IS A LEGAL TARGET, resolved from the facade body rather than assumed and
pinned against real Dolt: the anchor resolves across both planes, the comment
lands on `wisp_comments` and reads back from the ephemeral thread. Only the
DURABLE trace is absent — a comment on an ephemeral row records NO history entry,
because the wisp tables are dolt-ignored precisely so ephemeral work never ships.

NO CONFLICT CODE AND NO GUARD, and both absences are the contract. A thread is
append-only and this write touches no field of the issue, so there is no row state
for an `expected_version` to be stale about and no concurrent comment to collide
with. Not idempotent either — a retry appends a second row, because two identical
comments are a legitimate thread — and the proxied test asserts that against the
table rather than the handler.

ONE ARM IN THE FAILURE PATH, and the deleted one is evidence rather than taste.
There is no explicit ErrNotFound case: ClassifyError already carries that row, and
adding one back leaves the whole package green — measured, the way #5540 measured
the same redundancy. The 400 names `text` unconditionally because exactly one of
the role's three refusals is reachable: the edge refuses an empty author under
strictly stronger rules, and an empty id cannot arrive at all.

RoleFiresHooks DID NOT KNOW ABOUT THE COMMENTER, and publishing this operation is
what made that matter. hook_commenter.go has fired the update hook for every
comment it lands since it was written, and the switch that stops `bd serve` from
being handed a hook-firing role had no case for it — harmless only while no front
door took the role off a store. An unpeeled commenter runs the workspace's script
once per comment, which is exactly the write an agent makes in a loop. The case is
added and pinned from both ends.

CENSUS +1 EACH: spec path; AddCommentRequest schema; the document's no-query-
parameter list and its two counts; route row; capability prose (the only hand
edit — Capabilities() is derived); OpAddComment; operationCodes row
(getDependencyTree's vocabulary, no code minted); httpapi.Config.Commenter with
sourceRoles, roleSourceNames, the Server field, Listen and s.commenter();
timedProvider.Commenter and its CommenterSource assertion; checkedCommenter; and
the bd serve binding. Plus Commenter on serveRoleSource and both cmd/bd stubs,
which is #5539's return: a named build error in the file that has to grow a method.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Close the RoleFiresHooks blind spot as a CLASS, and finish 0049 on the ephemeral comment plane

Review found the first version of this branch overclaimed twice. Both claims are
now either true or gone, and both are held by a test rather than by prose.

## The hook guard was blind FOUR ways, not one

The commit said the commenter was "the one hook-firing role RoleFiresHooks did
not know about". It was one of four. `*hookReadyClaimer`, `*hookBatchCloser` and
`*hookBatchCreator` were outside the switch too, and all three are served over
PUBLISHED operations — `issues:claimNext`, `issues:batchClose`,
`issues:batchCreate` — through roles `httpapi.Listen` sweeps by way of that exact
switch. A store-derived value for any of the three was therefore ADMITTED and
served, running the workspace's scripts for the life of the process: once per
bead a polling drainer wins, once per landed item plus one for a chained claim,
and once per item of a batch — so a hundred-item create was a hundred
subprocesses inside one HTTP call.

Fixed: three cases, plus the same both-ends pins the commenter got. Store side,
the accessor really hands back a hook-firing value and `serveIssueRoles` peels to
exactly the layer beneath it (the peel-depth half matters — a peel two layers
deep also answers false and silently drops the telemetry span, so the assertions
check identity, not just the predicate). Server side, `Listen` really refuses each
one.

AND THE PROSE IS NOW TRUE BECAUSE A SCAN MAKES IT TRUE.
`internal/storage/hook_decorator.go` has carried the sentence "every case that
exists today is in the switch" while it was false four ways, because every one of
the four was found by hand by whoever happened to publish an operation over that
role. That is a discovery process, not a guarantee, and it left the others
standing each time. `TestRoleFiresHooksKnowsEveryHookFiringRole` now parses this
package's `hook_*.go` for every decorator that holds an `issueOperationHooks` and
requires a case that RETURNS TRUE for it. Source scan rather than reflection, for
the reason backend/conformance's role census gives: these types are unexported
and are never built except through their accessor.

It counts the RETURN, not the case label, which closes the second failure mode
this switch has actually had: a Go type switch does not fall through, so
`case *hookMetadataCAS:` with an empty body answers FALSE, and a rebase shipped
exactly that with the compiler, vet, lint and CI all green. Mutation-verified in
both directions — deleting a case and emptying a case each fail the scan by name.

## `wisp_comments.text` was still TEXT, so the document's bound was false

The spec said `text`'s only cap is the 1 MiB every body shares. That was true on
one plane. Migration 0049 widened `comments.text` to LONGTEXT and did not touch
`wisp_comments.text`, which has been TEXT — 65535 bytes — since 0021 created the
table. Measured live before the fix: a 102,000-byte comment is 200 against a
durable issue and 500 against a wisp. This operation resolves its anchor across
BOTH planes deliberately, so nothing above the storage seam could tell a caller
which side of the bound it was on until the write failed.

Widened rather than caveated: the two planes should not disagree about what a
comment may contain, and a caveat would have to be re-stated by every client. The
handler grows no length check — there was never one to add; the fix was the
column.

MIGRATION 0065 + ignored/0024, and the twin is required rather than offered:
`wisp_comments` is clone-local and dolt-ignored, so a fresh clone materializes it
from the ignored series while the main cursor arrives at-latest and 0065 never
runs there. That is check D of scripts/check-migration-hygiene.sh, and the same
fresh-clone door ignored/0021 — the wisps half of this identical 0049 gap —
already records. Both guarded on 0049's `COLUMN_TYPE = 'text'` probe, so they are
no-ops on an already-widened workspace and idempotent on replay; the `.down` is
0049's intentional no-op, because shrinking back would truncate.

Verified from both ends: red-first against real Dolt (the wisp 500 above, green
after), and `TestEmbeddedIgnoredSeriesConvergesWithFreshInitShape` — the
engine-level backstop behind check D — fails naming `wisp_comments.text` when the
twin is withheld.

### MIGRATION LANE NOTE, for the deployment checklist

THIS MOVES THE MIGRATION CEILING FROM 0064 TO 0065, and the ignored series from
0023 to 0024. Anything pinned to "latest is 0064" — a deployment checklist, a
pre-flight assertion, a fixture bundle — transfers to 0065 when this lands.
Migration files are frozen once merged (hygiene check C), so a follow-up cannot
edit these two; a fix would be a further migration. NOTHING IS DEPLOYED BY THIS
PR: it ships the files, and the schema moves on whatever schedule the deployment
checklist runs.

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>
2026-08-10 18:59:57 -07:00
Stephanie Jarmak
0954be4166
feat(list,ready,httpapi): reach the Brief projection from both front doors (#5586)
* feat(list,ready,httpapi): reach the Brief projection from both front doors

Application half of #5546, stacked on the storage half. `--brief` on `bd list`
and `bd ready`, `brief` on `GET /v0/beads/issues` and `GET /v0/beads/ready`.
Defaults to false everywhere, so no payload changes for a caller that does not
ask; #4122 objects to default payload changes and #5078 records what the last
one cost.

ONE REGISTRATION PER COMMAND REACHES BOTH OF ITS ROUTES, because the two
gatherers are shared. `bd list` hands `in.ListRequest` to issueops.Reader.List
verbatim on the direct and the proxied route. `bd ready` uses the Reader role on
NEITHER: both routes pass the filter that gatherReadyInput built through
workapi.BuildReadyFilter, so `types.WorkFilter.Lite` is what has to carry it
there, and the CLI-hop tests assert the filter rather than the request for that
reason. The HTTP handlers build both requests independently of the CLI, so they
are wired separately.

REFUSED WHEREVER IT CANNOT BE HONORED, rather than accepted and dropped, which
is the silent no-op the storage half was written to close. `Lite` reaches a
driver through exactly two queries: the bare SearchIssuesInTx (#3906) and the
counts mega-query (the storage half). `GetReadyWork` and the by-ID hydration
behind the tree walk read neither, so:

  - `bd ready --brief` requires --json, and is refused with --claim, --gated,
    --mol and --explain. `bd ready` runs the counts query for --json alone; the
    text routes call the bare GetReadyWork and the three specialized modes
    answer with shapes of their own. The direct route dispatches those modes
    BEFORE gathering, so each check appears in cmd/bd/ready.go as well as in
    the gatherer, exactly as the --claim conflicts beside them already do.
  - `bd list --brief` works in text mode too, since all of its page routes reach
    Reader.List, and is refused with --watch, with --format, and with --parent
    in the tree view. --tree defaults to true, so a bare --parent in text mode
    is that same walk without the flag being typed.

--claim is refused for a stronger reason than the rest: no route can serve it.
ClaimNext refetches its winning row whole and returns ErrValidation for a
projected request. Catching it in the gatherer keeps the message about the two
flags the user typed, and leaves readyRoleRequest free to carry Brief for the
COUNT, which needs it.

--format is refused rather than annotated because a caller's template can print
any of the six dropped fields and there is nothing to hang a marker on.
`bd list --long` is the one built-in text rendering that prints one of them, and
it is allowed because it CAN say so: it now prints
"Description: (omitted by --brief)". That keys off types.Issue.IsLitePartial
rather than off the flag, so a row that arrived projected reads the same
whichever door set it.

THE JSON PAYLOAD CARRIES NO MARKER, and the flag help and both OpenAPI
descriptions say so plainly. types.Issue.IsLitePartial is `json:"-"` and
documented as internal-only by #3906, so an omitted field is indistinguishable
from an empty one on the wire; only the caller that sent the flag knows. #5549
deferred exactly this marker for brief_deps as its own change, and this follows
that, rather than changing a shared type's wire form on the way past.

`brief` is decoded in handleListReadyWork and NOT in readyFilters, the
vocabulary the ready listing shares with :count and :claimNext, because it
projects fields rather than selecting rows and neither of those returns rows to
project. That made TestClaimNextAdmitsExactlyTheListingsFilters fail, correctly:
its single hardcoded `limit` exception is now a `pageKnobs` table of the
listing's two page knobs, each still asserted ABSENT from claimNext, since a
documented parameter that is always a 400 is a trap. Both branches of that
assertion were verified by sabotage.

RED BEFORE GREEN on all nine new assertions, each verified and reverted: the two
request hops, the seven refusals, the long-format marker, and both branches of
the parity table.

Gates: go build ./..., go vet ./..., gofmt, cmd/bd, internal/httpapi,
internal/workapi, backend/conformance, internal/storage/issueops, issueops,
make api-check, ./scripts/generate-cli-docs.sh --check.

Refs: #5546, #3906

* fix(ready,changelog): close the review findings on #5586

THE THREE DIRECT-ROUTE REFUSALS WERE UNTESTED, and the review's mutation
proved it: deleting the --gated check left `go test ./cmd/bd/` entirely green
while `bd ready --gated --brief` silently ignored the flag on the direct route.
Nothing in the package drives readyCmd's RunE, so the gatherer's tested copies
were only ever guarding the proxied route. The PR body's "seven refusals, red
before green" covered five.

Taking the second of the two suggested fixes, since it removes the duplication
rather than testing it. The per-mode copies in ready.go are deleted. Their body
moves to briefModeConflict, which gatherReadyInput now calls, and RunE calls
once through briefModeConflictFromFlags, hoisted ABOVE the mode dispatch and
above the proxied branch so it is the single place a --brief conflict is
decided for this command on either route.

TestReadyCmdRefusesBriefBeforeItDispatches drives RunE directly, which is
reachable because that check now precedes every store access. Verified by
reproducing the review's own mutation: deleting the hoisted call fails the
--gated, --mol and --explain cases.

THE CHANGELOG ENTRY CONTRADICTED ITSELF, claiming --brief "marks each row
is_lite_partial" and then, in the same paragraph, that the response carries no
marker. The first half was written before the wire form was checked;
types.Issue.IsLitePartial is `json:"-"` and never serialized, so an agent
following that sentence would have grepped its JSON for the field and concluded
the feature was broken. The no-marker fact is now its own paragraph, and the
only marker the entry claims is the text one `bd list --long --brief` prints.
The entry cites #5554 and #5586 alongside #5546, matching the sibling
brief-deps entry.

Gates: go build ./..., go vet ./..., gofmt, cmd/bd, internal/httpapi,
internal/workapi, backend/conformance, internal/storage/issueops, issueops,
make api-check, ./scripts/generate-cli-docs.sh --check.

---------

Co-authored-by: sjarmak <t@t.co>
2026-08-10 13:05:00 -07:00
Julian Knutsen
4e7cc88180
feat(journalops): the mutation journal becomes the third facade namespace (#5552)
* feat(journalops): the mutation journal becomes the third facade namespace

The durable mutation journal's read side is now a role. `journalops` is a
leaf package beside `issueops` and `memoryops` holding Row, Page,
TruncatedError/TruncatedCode and `Journal`, whose doc comment is the
specification: since-exclusive, seq-ascending, limit 0 uncapped with the
wire's cap named as the handler's, a head that comes with its rows and never
decreases, a caught-up checkpoint, and a typed truncation naming a resumable
window.

NOTHING CHANGES BEHAVIOR. The four names in `internal/storage` become
ALIASES of the leaf — `type EventsJournalCursor = journalops.Journal` and its
three siblings — so every implementation, every errors.As site and every
caller compiles unchanged. The alias direction is what avoids the import
cycle: the leaf imports context and fmt and cannot name internal/storage, so
the canon goes down and the alias goes up. Outside storage.go and the
conformance tier, the only non-test edits in this change are COMMENTS.

The role brings the apparatus a role owes:

- backend/conformance/journal_contract.go, six cases over a fixture carrying
  the role, the activation switch, a prune, and a mutation kit that is
  exhaustive against the engine's closed op vocabulary.
- Wirings on all three legs (dolt, embeddeddolt, uow), so #5499's
  entrypoint-scoped lock passes with every leg running every case.
- journalops added to the conformance census's facadePackages. That is the
  #5459 demand side, and the role that needed it: `Journal` is handed out by
  NO accessor — a front door type-asserts for it — so only a source parse can
  see it. issueops.Importer is the precedent.

EventsJournalAccessor and EventsJournalConfigurer stay in internal/storage.
Retention and activation are operator surface, and a server documented to
publish the journal and never retain it must not hold a delete.

Net deletion on the bespoke side: TestEventsJournalPageReportsTheHead is
subsumed by the contract and is gone. TestEventsJournalRestartAndRetentionBoundary
stays, because it observes ReadEventsInTx — the accessor's second read body,
deliberately not on the role — and a mutation of one is invisible to the other.

Mutation-measured, per case, on the embedded leg: an inclusive checkpoint, a
head derived from the page, an untyped truncation, a head taken from MAX(seq)
of surviving rows, and a dropped engine-only op each redden exactly the arm
named for them, and a fixture whose activation hook is a no-op reddens all
six. Reading the head BEFORE the rows leaves all six green — that promise is
declared unpinnable in the contract header rather than faked.

Refs ga-fvya1, ga-2yaqp.4.

* docs(journalops): fix three comment-precision findings from review

All comments, plus one test-only compile-time pin block.

1. journal_facade_test.go told a misassembled causal story: it used the
   CURSOR de-aliasing as its example and then attributed the breakage to
   errors.As. Those are two different failures. Measured, both:
   de-aliasing the interface builds the WHOLE TREE clean and breaks nothing
   behavioral — what it costs is the claim that one role has one name — while
   the error's dangerous shape is not the bare defined type (which loses
   Error() and fails to build) but the COPY-PASTE TWIN, which compiles in
   silence and stops crossing errors.As for everything holding the leaf's
   spelling. Rewritten to say that straight.

2. The seq commit-order unpinnable declaration cited "the dolt package's own
   journal tests" for the server-mode half. Those are single-threaded. The
   actual pin is internal/storage/domain/db/journal_seq_test.go —
   TestEventsJournal_CommitOrderedGaplessSeq drives two OVERLAPPING
   transactions on independent connections, and
   TestEventsJournal_ConcurrentWritersGaplessNoDup a racing batch. Cited
   correctly, and the single-threaded ones named as NOT the pin.

3. EveryMutationKindLandsARow's runs-last ordering is load-bearing but held
   by convention: a reorder compiles, passes, and silently gives up the only
   coverage that a journal keeps recording after a full prune. It was stated
   in the dispatch table and the three leg wirings; it is now stated at the
   case itself, where somebody editing a leg file is actually looking.

And the compile-time half of the alias pin, which fires before any test runs:
a pointer conversion per name. The pointer form is not decoration — for the
three structs a plain assignment would do, but for the INTERFACE it would be
blind, since interface-to-interface assignment goes by method set and a
de-aliased cursor still accepts a journalops.Journal. Watched fail: the
de-aliased interface, which nothing else in the tree catches.

---------

Co-authored-by: Review Sim <ci@beads.test>
2026-08-10 10:58:05 -07:00
Stephanie Jarmak
4a76685f90
feat(show,httpapi): reach BriefDeps from both front doors, with conformance coverage (#5549)
* feat(show): --brief-deps flag reaching DetailOptions.BriefDeps

Application half of #5546, stacked on #5547. Both show routes gather flags
separately, so the flag is read in cmd/bd/show.go and in
gatherShowProxiedInput; a flag added to one reaches neither by implication.

Defaults to false, so the JSON payload is unchanged for callers that do not
ask. #4122 objects to default payload changes and #5078 records what the last
one cost.

Measured against a 16,051-issue store: bd show <id> --json is 216,605 bytes and
the same call with --brief-deps is 23,287, an 89.3% reduction, with the
identity fields intact and zero bytes of dependency text.

* feat(httpapi,conformance): reach BriefDeps from the HTTP door and pin it

Review follow-ups from #5547.

The conformance case is the blocking one: backend/conformance pins
IncludeDependents/IncludeComments so an out-of-tree Reader cannot ignore them,
and BriefDeps landed on the same public contract with no case. Registered at
all four call sites. Verified non-vacuous by disabling the projection and
watching TestReaderContract go red against a real backend.

The HTTP handler builds GetRequest independently of the CLI, so wiring cmd/bd
alone left the field reachable from one front door of two. Adds the brief_deps
query parameter to the v0 spec and regenerates apigen types; make api-check is
green.

Also: the cmd/bd flag test reset the value but left pflag's Changed true, which
outlives the value and contaminates later tests in the package.

* fix(conformance,show): close the review findings on #5549

The conformance case asserted Design and AcceptanceCriteria were empty without
ever seeding them, so a Reader that stripped description and notes but leaked
the other two passed. That is the same fixture-blindness the parent PR was
written against. Seeds all four heavy fields, and asserts Title, which the
projection deliberately keeps and the OpenAPI text promises.

Both CLI routes built GetRequest inline inside functions that need a
UnitOfWork, so the hop was unreachable from a test and deleting either
assignment left the suite green. Extracted showGetRequest and
showProxiedInput.getRequest and pinned both, matching what the HTTP door
already had.

The case now gets its own Test at each storage call site rather than riding
inside the OptionalRowLists test, so a BriefDeps failure reports under its own
name instead of misdirecting triage. The embeddeddolt site no longer builds a
second fixture.

Adds the CHANGELOG entry for the #5547 + #5549 pair, at the point the feature
becomes reachable.

---------

Co-authored-by: sjarmak <t@t.co>
2026-08-10 08:40:32 -07:00
Julian Knutsen
ff75b45c91
docs: the ext-api-store documentation tranche — post-#5516 auth sweep, wave doc coherence, role checklist refresh (#5545)
Three beads (ga-uwix0.1, ga-2yaqp.5, ga-2yaqp.6) plus a fable review round.
Docs and spec prose only: all 19 touched .go files are gofmt-normalized,
comment-stripped byte-identical to main. The one exception is deliberate and
reviewed — scripts/check_doc_freshness_test.go gains a data row, because the
delegated gate ruling required it.

ga-uwix0.1 — #5516 gave bd serve optional bearer auth and made it MANDATORY
beyond loopback; fifteen prose sites still said the opposite. The three the
council named are reworded to the stronger true form (the actor is not the
authenticated principal even where a bearer is required; a shared token admits
a client to the WHOLE surface and grants no narrower right). The sweep for a
fourth found eight more in five spellings the audit's grep could not reach,
including claim.go's "any client can claim as any name", release.go's
no-AUTHORIZATION variant, and six memory/settings-plane sites where the true
statement is sharper: a bearer decides WHO may call, never what a caller who
is let in may read. The review round found four more in the CHANGELOG's
UNRELEASED section, which round one had misclassified as released history —
they would have shipped false in the same release as the auth entry.

The serve runbook's "Binding beyond loopback" section was actionably wrong: it
said the flag "prints a warning and changes nothing else", and its refusals
table quoted a string not in the binary. Rewritten against a build, with every
flag, error string, event name and reason value produced by running the
command. It gains the operational trap nobody had written down: /healthz is
auth-exempt and GET /v0/beads/ready is not, so an unauthenticated readiness
probe earns a 401 forever while liveness stays green. The runbook is now IN
scripts/check-doc-freshness.sh, pinned to the four files it is read against.

ga-2yaqp.5 — nine prose defects, every count re-derived rather than trusted;
three of the audit's own numbers had moved again. 38 route rows and 36
capability-bearing ones; thirteen pinned schemas, not twelve or seven; six
missing entries in the no-query-parameter list, not five; twenty-eight role
accessors, not twenty-seven; nineteen patch members, not thirteen. Two prose
"code counts" were counting paragraphs. CodeAlreadyClaimed claimed the holder
is always attached when only one of four producers always attaches it and
releaseIssue never does. MetadataCAS's leaf contradicted its own shipped wire.
The path/operationId inversion is now recorded where a spec author looks.

ga-2yaqp.6 — the role checklist refreshed against what this wave's additions
actually cost, traced to real commits. Step 10 sent people to a name list
#5460 deleted. The "four more edits" claim was stated twice and undercounted
both times: the two freshest wire slices share a nine-file core plus
roles_test.go. The step-with-no-number gained the fact that explains its
instances — write-role decorators wrap, read-role decorators recurse, so the
call lands on the stub, and both real instances are reads. The wave got its
first CHANGELOG entry: six new public operations, not three, and zero new role
accessors in the window.

Review verdict: FIX-REQUIRED then all items addressed. The reviewer
live-falsified the strong auth form and failed to break it, and confirmed
every recount re-derives exact.
2026-08-10 08:05:07 -07:00
Julian Knutsen
2a4b75b810
Publish GET /v0/beads/issues/{id}/related, the wire half of issueops.Relations (ga-81p36) (#5540)
Relations is one of the facade methods the ext-api-store audit lists with no
wire operation, and it is the one gc's infra-over-http read surface cannot do
without: `bd dep list`'s dependents view has no other direction-aware wire path,
because EdgeReader is outgoing-only. This is that operation. The role, its
contract and all three legs already exist; this slice wires them.

Spec first, then `make api-gen`, then the handler.

IT IS A SUB-RESOURCE OF THE ISSUE, and the argument is ELEMENT IDENTITY rather
than a claim about what the dependency collection answers with — getDependencyTree
answers hydrated TreeNodes, so "everything under /dependencies is about edges"
would be false and is not said. What decides it is narrower and checkable: the
rows here are the SAME pinned struct `GET /v0/beads/issues/{id}` already carries
under `dependencies` and `dependents`, so this operation is that pair,
standalone, direction-parameterized and type-filterable, and it belongs on the
resource whose members it publishes: `/v0/beads/issues/{id}/related`. The route table's first sub-resource: the
segment is a LITERAL after a single-segment wildcard, so pattern and specPath
agree and the claim row's exception does not apply. It collides with nothing —
`/v0/beads/issues/{id}` is a different whole path, which is what ServeMux
matches on, and the custom-method dispatcher is POST-only and one segment
shorter.

The consequence is stated in the document rather than left to be discovered:
the length of `items` is a NEIGHBOR count and not an EDGE count, because a
target that is an `external:` reference or another repository's id has no far
end here and is silently not a neighbor. The same edge IS a row on
`GET /v0/beads/dependencies`. That single observation is what separates the two
operations, and the proxied test asserts both halves of it against real Dolt.

THE ANCHOR-BOUND maxItems GATE DOES NOT APPLY. The facade signature is
single-anchor — one `RelatedRequest.ID`, not a slice — so there is no question
to bound at 100 the way the three dependency-collection reads bound theirs, and
`TestSpecDefaultsMatchSharedConstants`' three-op loop is deliberately untouched.
The other side of single-anchor is the 404: those reads report a miss per anchor
because failing would throw away the ids that were found, and here there is one
anchor and nothing to preserve. `getDependencyTree`'s operationCodes row,
unchanged, is this one's.

TWO-PLANE, AND BOTH HALVES ARE REAL. The neighbours are collected from
`dependencies` AND `wisp_dependencies` and hydrated from `issues` AND `wisps`,
so a durable anchor's `in` answer includes the wisps that depend on it and a
wisp id is a legal ANCHOR. Resolved from the bodies, not assumed, and pinned
against real Dolt: a durable anchor with one durable and one wisp dependent
answers two, and the wisp element carries `ephemeral` — which is what catches an
implementation that spanned the edge tables and hydrated one issue table.

VALIDATION STAYS IN THE ROLE, on `dependencies:count`'s terms rather than
`issues:count`'s. Relations has two bodies and every accessor calls
ValidateRelatedRequest, so its refusals are reachable over the wire: the handler
forwards `direction` raw and classifies on the sentinel, naming the parameter by
re-asking the validator's own questions in its own order. Only two of the
validator's three refusals are reachable — the path bound turns an unusable id
into the 404 a real miss gets, which is why there is no `id` arm in the picker
and why the tests say so.

Census: +1 spec path, +1 schema (`RelatedIssues`, unpinned for `EdgeCounts`'
reason — the element under it is the pinned one), +1 route row, +1 capability
(`issues.related`, hand-edited only in the document's vocabulary — `Capabilities()`
is derived and untouched), +1 `Op*` const, +1 `operationCodes` row, +1 required
`Config` field with its `sourceRoles`/`roleSourceNames`/accessor lines, +1 `bd
serve` binding. No code was minted: every problem code on the row is inherited.

THE "STEP WITH NO NUMBER" IS NOW A BUILD ERROR, and this is the first role to
measure that rather than assert it. #5539 landed the serveRoleSource subset while
this was in review, so `IssueRelations` joins that interface and both `cmd/bd`
stubs are COMPELLED to declare it — omitting either is

    *serveRolesStore does not implement serveRoleSource (missing method IssueRelations)

in the file that has to grow the method, checked both ways. Counter and
GraphCounter had to be FOUND, the second only by a full-package CI shard; this
one could not be missed. Both stub comments are rewritten to say so: the
promoted-method-on-a-nil-embed narrative is history now, not instruction, and on
the identity stub the surviving load-bearing fact is PLACEMENT — the accessor
sits at depth 1, shallower than serveStubRest's nil store, so it shadows the
promotion and the assertion can see it. Swept for a third stub site reaching this
path: serve_registered_backend_test.go reuses serveIdentityDoltStore and a real
embeddeddolt.Open, so there is none. A drive-by one-liner beside all that:
timedProvider gained the `uow.GraphCounterSource` compile-time assertion #5536's
accessor landed without.

One arm was DELETED after measurement. failRelatedErr shipped with an explicit
`storage.ErrNotFound` case, mutating it out left every case in the package green
— ClassifyError already carries that row, so the 404 travels through the one
shared mapping — and a green arm named for half the contract is worse than no
arm. The ErrValidation arm is the opposite: deleting it turns every refusal on
this operation into a generic 500, and both measurements are recorded at the
site.

Evidence, six mutations. The picker's arms collapsed reddens the four direction
cases and nothing else; the ErrValidation arm deleted reddens all five refusal
cases; `items` as a nil slice reddens the empty-array case; the path bound
dropped reddens the impossible-anchor case; the dependents read narrowed to
`dependencies` and the hydration narrowed to `issues` each redden the two-plane
case against real Dolt at 1-of-2. A seventh, a json tag on types.Issue.RowVersion,
reddens the no-revision case — and TestWireTagBijection too, which the test now
says out loud.

Rebased onto #5539 (06b0dffb2). Fable review: APPROVE, zero blocking findings
— the reviewer re-ran every mutation, probed the router live (an issue literally
named "related" does not shadow the detail read), and confirmed the
environmental-failure set name-identical to pristine main. Its one INFO, the
overclaimed placement rationale, is the paragraph rewritten above.

Gates: `make api-check` a no-op, `go build ./...`, `go vet ./...`, `gofmt -l`
clean, `internal/httpapi` + `internal/telemetry` + `internal/storage` +
`internal/storage/uow` (the nine-minute parity run) green, and
`BEADS_TEST_PROXIED_SERVER=1 CGO_ENABLED=1 go test ./cmd/bd/ -run
TestProxiedServerServeRelatedIssues` green against real Dolt in five cases. The
pre-commit hook's `go run golangci-lint@v2.10.1` downgrades the toolchain to
go1.25 and refuses this go1.26.5 module outright (ga-2ltro.13), so the
CI-pinned binary was run by hand — `golangci-lint run --new-from-rev=origin/main`,
0 issues — and this commits with --no-verify citing that bead.

Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-10 05:23:30 -07:00
Julian Knutsen
06b0dffb22
Make the next serve role a compile error, and check the one role with a positional result (#5539)
* refactor(serve): make the next role a compile error in the serve stubs

serveIssueRoles took a whole storage.DoltStorage, so the test stubs that
stand in for a store satisfied it the only affordable way: embed the
interface and leave it nil. Every accessor a stub had not declared then
arrived as a promoted method on a nil interface — a segfault inside role
extraction, not a compile error.

It has landed twice in one PR cycle, both on GraphCounter. First in
serve_source_test.go, then in serve_store_identity_test.go, where no local
-run pattern names the test and only a full cmd/bd shard found it.

So the function now asks for serveRoleSource: the accessor subset it
actually reaches, which a whole store still satisfies. Both stubs declare
that subset and assert it, and the store they must still BE — the
decorator chain takes one, and backends.Backend.Open returns one — comes
from an embed one level deeper that their own accessors shadow. Adding a
role to the loop is now:

    cannot use (*serveRolesStore)(nil) ... does not implement
    serveRoleSource (missing method GraphCounter)

ADDING_AN_ISSUEOPS_ROLE.md's "step with no number" listed these two stubs
among the surfaces to grep for by hand; it now says this pair is taken
care of and the rest still are not.

Swept the embed pattern across cmd/bd for a third instance reaching this
path: none.

Bead: ga-c3g45

* fix(httpapi): check the batch closer, the one role with a positional result

internal/httpapi has checked wrappers for Reader, BatchCreator, Lifecycle,
Claimer and Releaser, but the batch closer went out unwrapped — on the
reasoning that CloseBatchResult is a value and its issue pointer is
forwarded rather than dereferenced. True, and it is why there is no panic
here to prevent. What it left unguarded is the thing this role owns that
none of the others do: an array the client reads POSITIONALLY.

Two shapes reached the wire as answers rather than faults, and they fold
at different scopes:

  - An outcome count that does not match the request cannot be walked
    against the caller's items at all. Projected anyway it reports one
    item's answer under another item's id for the rest of the array,
    silently, inside a 200. Whole-batch 500, never a partial projection —
    checkedBatchCreator's refusal exactly.

  - An outcome carrying neither a row nor a refusal has no honest wire
    shape: `code`'s absence promises `issue`, so it projects as a success
    with no row, which is the shape closeOutcome's `default` branch
    already refuses to produce. Folded into THAT item, because this batch
    is not all-or-nothing — the survivors have committed, and failing the
    request would hide durable closes.

The fold corrects a copy: the outcomes slice is the role's, and one that
answers from a prepared result would otherwise carry this server's
correction into everything it hands back afterwards.

No wire shape changes and no spec changes; make api-check is a no-op, and
the error classification order in failBatchClose is untouched.

Bead: ga-39tl5

---------

Co-authored-by: Julian Knutsen <ci@beads.test>
2026-08-10 04:34:15 -07:00
Julian Knutsen
86d24711c6
Publish GET /v0/beads/dependencies:count, the wire half of issueops.GraphCounter (#5536)
The role landed facade-only (#5485) with neither front door, and its own doc
said why: the numbers it answers are already printed through internal/workapi's
detail seam, and the wire operation "lands in the graph-counts wire slice".
This is that slice. What it buys is the question the stored-edge read cannot
ask — how many edges, in a direction the caller names, without materializing a
row.

Spec first, then `make api-gen`, then the handler.

IT IS NOT THE LISTING COUNTED, and the operationId says so. `listDependencies`
is OUTGOING ONLY and takes no direction; this one REQUIRES a direction and
answers about either end, so the two agree on a number at `direction=out` and
nowhere else. `countDependencies` would have promised they always agree, so it
is `countDependencyEdges` — and the path is `/v0/beads/dependencies:count`,
the collection-level custom method `ready:count` and `issues:count` already
spell, on the collection whose listing it sits beside. Both segments are
literal, so pattern and specPath agree; it collides with nothing, because
/cycles, /blocking and /tree all carry a separating slash and ServeMux matches
whole segments.

THE ANSWER IS PER ANCHOR, which is the shape difference from the listing beside
it. An edge row carries its own `issue_id`, so that operation flattens; a number
does not, so folding these would produce a total nobody asked for and lose the
per-issue answer every caller wants. `anchors` is an ARRAY in first-mention
order — the role's doc says a map would be the one result shape a wire
operation cannot carry without inventing a key vocabulary, and that the
request's order is part of the answer. `count` and `missing` are both emitted
on every entry: 0 is the COMMON answer here and `missing` is the only thing
that tells a typo from an issue that genuinely has none.

THE IDS CAP IS THE ONE THE LEAF ASSIGNED TO THIS SLICE. EdgeCountRequest.IDs
says there is no size cap on the role, that the bound belongs to the WIRE, and
that "the graph-counts wire slice sets it". It is 100 — the same number, from
the same `maxDependencyAnchors`, as the stored-edge read on the same
collection, because the two bound the same thing and a client holding both
should not have to learn two numbers. And it is now PINNED: nothing kept the
document's maxItems and the Go constant together on ANY of the operations that
read it, so TestSpecDefaultsMatchSharedConstants grew a case covering all
THREE — including listBlockingAnnotations, which enforces the same constant and
declares the same maxItems and predates this slice entirely. Pinning only the
two operations this slice touched would have gated the copies that happened to
be in front of me and left the oldest one free to drift.

VALIDATION STAYS IN THE ROLE, which is the opposite of `issues:count` and for a
reason the checklist spells out. That operation refuses its one enum at the edge
because NO role refusal is reachable; here the role has ONE body on all three
legs with ValidateEdgeCountRequest inside it, so four refusals are reachable —
a missing or unrecognized direction, a status beside direction=out, an empty id,
an unusable type. The handler classifies on the sentinel and names the
parameter by re-asking the validator's own questions IN THE VALIDATOR'S OWN
ORDER, which is part of that function's contract. Two cases carry two offenders
each and assert the FIRST is named; swapping the picker's arms reddens them.

The role's own semantics — sum-not-distinct, both dependency planes, the status
asymmetry, the missing-anchor rule — are CITED, never restated. A second telling
is a second thing to keep true.

Config gains a required GraphCounter field on the checklist's terms, `bd serve`
binds it beside the issue counter, and TWO stub stores gain the accessor — the checklist's "step with no number", found exactly as it
predicts: the read role's hook decorator RECURSES, the recursion lands on a
stub that embeds a nil DoltStorage, and the panic arrived the moment `bd serve`
began binding the role. storage.RoleFiresHooks needs nothing, because that
table takes only decorators that WRAP.

THE SECOND STUB IS THE ONE WORTH RECORDING, because it says what the checklist's
warning actually costs. serve_source_test.go was found by running the tests a
role slice thinks to run; serve_store_identity_test.go's serveIdentityStore has
the same nil embed and was found only by the FULL-SUITE macOS shard, because no
test name in that file matches a pattern anyone would guess
(TestServeAnswersFromTheStoreTheRootCommandOpened). #5508's own message recorded
this same gap — "I ran the proxied shards by name and never the whole cmd/bd
package" — and I repeated it. The rule that actually holds is the checklist's:
GREP FOR THE EMBED, NOT FOR THE INTERFACE. Both stubs are now swept, and a
tree-wide sweep for a type declaring Counter() without GraphCounter() finds no
third.

The structural fix is deliberately NOT in this slice: as long as these stubs
embed the whole storage.DoltStorage interface, every future read role is a
promoted method on a nil interface — a segfault rather than a compile error.
Replacing the embed with an explicit role-accessor subset would turn the next
one into a build failure, and that is its own change.

ONE NICE PROOF OF #5508's WORK: the capability list needed ZERO hand edits in
Go. routes.go's diff is a table row and nothing else — `Capabilities()` is
untouched — and TestSpecCapabilityVocabularyMatchesTheRouteTable passes, which
means the derived list picked `dependencies.count` up on its own. The only hand
edit was the document's own prose vocabulary, which is precisely what that gate
exists to demand.

Evidence. Three mutations, each red in the right place: the picker's arms
reordered reddens the two-offender cases and nothing else; `omitempty` on
`count`/`missing` reddens the per-anchor case (which decodes through pointers
for exactly that reason); the anchor cap as `>=` reddens the at-the-cap
assertion that the two refusal cases could not see. A fourth, drifting the
spec's maxItems to 50, reddens the new shared-constant pin.

Real Dolt through a real `bd serve`, five cases: out and in over an ASYMMETRIC
fixture (2 and 3, so neither direction can pass by coincidence) with the
outbound count reconciled against the rows `GET /v0/beads/dependencies`
returns; the TWO-PLANE SUM, where a durable anchor depended on by one durable
issue and one wisp counts 2 across `dependencies` and `wisp_dependencies` — a
count reading one table answers 1 and looks fine; a missing anchor reported
beside two found ones, both of the other two carrying 0 so only the flag
separates them; the status filter narrowing inbound edges by the dependent's
stored status, an unrecognized status counting 0 rather than failing, and the
400 naming `status` beside direction=out; and a repeated anchor answered once.

Gates: `make api-check`, `go build ./...`, `go vet ./...`, `gofmt -l` clean,
`golangci-lint run --new-from-rev=origin/main` on the touched packages (0
issues), `internal/httpapi`, `internal/telemetry`, `internal/storage` and
`internal/storage/uow` (the nine-minute parity run the checklist names), and
`BEADS_TEST_PROXIED_SERVER=1 CGO_ENABLED=1 go test ./cmd/bd/ -run
TestProxiedServerServeEdgeCounts` 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.

Stacked on feat/httpapi-read-revision (#5535); rebase after that merges.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-10 02:06:57 -07:00
CI Bot
b9f38840b8 feat(httpapi): per-request project-id enforcement (Bd-Project-Id header)
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>
2026-08-10 01:26:42 -07:00
Julian Knutsen
6775f60f67
Publish revision on the detail read: the token a guarded write is composed from (#5535)
Every `expected_version` on this surface is composed from a token some response
carried, and until now every response that carried one was a WRITE. A client
that wanted to read a row, decide from what it said, and write it back under a
guard had to precede its first guarded write with a write it did not want to
make — or guard on nothing, which is the lost update the whole family exists to
refuse. Five places in the document said "no READ on this surface publishes a
revision yet" and named the member a read would have to agree with. This is that
member.

Spec first, then `make api-gen`, then the projection.

GET /v0/beads/issues/{id} PUBLISHES IT; GET /v0/beads/issues DOES NOT, and the
reason is not payload. Measured against a 20,482-row production export the
member is 28 bytes on a 1449-byte median row — under 2%, and the list rows are
already fat enough that a token would disappear into them. The reason is that
`types.IssueWithCounts` is ALSO THE INTERCHANGE ROW: `exportIssueRecord` embeds
it in both `bd export` and the auto-export that flushes a git-tracked
`issues.jsonl`, and the token is re-minted by every write, so publishing it on
that element would put a per-write-random value into a file whose whole value is
that it diffs when something meant something. That is precisely the loss
`types.Issue.RowVersion`'s `json:"-"` is there to prevent, and a wire member
cannot opt out of it — the list element and the export element are one pinned Go
struct. `types.IssueDetails` has neither problem: nothing interchanges it, and
`workapi.BuildIssueDetails` is its ONE production construction site against
IssueWithCounts's SIX, which is the second half of the argument. (Six
field-populating non-test literals: export.go, export_auto.go, search.go,
claim_next.go, ready_work_counts.go and uow/ready_claimer.go. The `[]*T{claimed}`
spellings in ready.go and ready_proxied_server.go are slice literals wrapping a
role-built element, not independent places to forget a field, and they are not
counted.) A token field on a struct built in six places is silently 0 wherever a
site forgets it, and 0 is a LEGAL token (the migration-0054 backfill), so
nothing — no test, no client — can tell a forgotten one from a legacy row.

So the projection moved onto the canonical type behind ONE DOOR. types.Revision
is set by types.NewIssueDetails and nowhere else, because a struct literal with
an unset token publishes a wrong answer that looks exactly like a right one.

THE DOOR IS WRITTEN INTO THE DOCUMENT, not just into this description. A later
revision that wants the token on the list rows needs a list element that is NOT
the interchange element, and the listing's own prose now says so — together with
the rule a client needs meanwhile: model the absent member as ABSENT, never as
0, because 0 is a real token and a client that defaulted would compose guards
matching exactly the rows it is most dangerous to be wrong about.

THIS DELETES A PARITY DIVERGENCE RATHER THAN ADDING ONE. `bd show --json` has
published this token for as long as guarded writes have existed, through a
CLI-only wrapper, and `readsParityAllowlist` waived the difference with the note
"if the token is ever needed over HTTP, extend that surface and delete this
entry". The wrapper is gone, both front doors read the member off the one detail
seam, and the allowlist is now EMPTY — kept declared, because an empty allowlist
is a stronger statement than no allowlist.

The wire council's outstanding fix rides along, because it is the same member
family: `ApplyItemResult.revision` and both apply-item `expected_version`
members gained the DECODE-AS-64-BIT clause every other revision-bearing member
already carried. The batch spelling is where it bites hardest — a token
corrupted by an IEEE-754-double parser refuses the WHOLE plan rather than one
write.

Evidence. Four mutations, each watched to go red in the right place and only
there: the constructor stopping projecting reddens all three legs; the seam
regressing to a struct literal reddens the workapi pin ALONE and leaves the
httpapi case green, which is why both exist; `omitempty` reddens exactly the
legacy-zero arms; and adding the field to `types.IssueWithCounts` reddens the
new list case while leaving `TestRowVersionNeverSerialized` GREEN — the separate
unset field carries none of the forbidden spellings — and reddens
`TestWireTagBijection` only while the document has not caught up. That measured
pair is written into the new case's own comment, because it is why the case is
not redundant with either gate.

Real Dolt through a real `bd serve`: read the token, guard a patch with it, watch
it land; watch a write move it; watch the read and the write agree on the new
one; watch the stale guard 409 with `param: expected_version`; re-read and watch
the retry land. The same loop on `close`, and the ephemeral fallback — where the
token is a different column on a different table and the failure mode is a zero
rather than an absence.

Gates: `make api-check`, `go build ./...`, `go vet ./...`, `gofmt -l` clean,
`golangci-lint run --new-from-rev=origin/main` on the touched packages (0
issues), the internal/types, internal/workapi, internal/httpapi and
internal/storage package runs, the byte-pinned `cmd/bd/protocol` corpus, and
`BEADS_TEST_PROXIED_SERVER=1 CGO_ENABLED=1 go test ./cmd/bd/ -run
'TestProxiedServerServeReadRevision|TestProxiedServerServeReadParity'` 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: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-10 00:27:49 -07:00
Julian Knutsen
ffb41ae3ad
Publish GET /v0/beads/issues:count, with the role's whole filter surface (#5508)
* 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>
2026-08-09 19:39:13 -07:00
Julian Knutsen
2632d57e09
feat(serve): optional bearer auth and a Host allowlist for bd serve (#5516)
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>
2026-08-09 18:05:56 -07:00
Julian Knutsen
413887be94
Publish the row-version guard on close, reopen and delete (#5506)
* Publish the row-version guard on close, reopen and delete

`expected_version` already existed on all three roles — `CloseRequest`,
`ReopenRequest` and, since the deleter slice, `DeleteRequest` — and none of
the three published it. `internal/httpapi/close.go` even carried the reason
in a comment ("a precondition would need a frozen conflict code for
ErrVersionMismatch and a `row_version` on the issue body for clients to
echo"). Both of those landed with `updateIssue`'s guarded members:
`precondition_failed` is frozen, `PreconditionFailed()` exists, and
`UpdateIssueResponse.revision` is the token clients echo. This retires the
comment by making it false.

Spec first, then `make api-gen`, then the handlers.

- `closeIssue` and `reopenIssue` take `expected_version` and answer with
  `revision`. The guard is checked BEFORE the idempotent re-close and before
  the non-done no-op, which is the role's own order; `force` bypasses close
  POLICY and never the precondition.
- `deleteIssues` takes `expected_version` under the role's SINGLE-ID rule: a
  guard beside more than one DISTINCT id is a 400 naming the member, refused
  at the edge so the client gets a member name the role's own ErrValidation
  route cannot give it. Duplicates collapse after trimming, matching
  workapi.NormalizeDeleteIDs; a blank id is refused first so the arity rule
  cannot steal a broken list's answer.
- Every precondition arm is matched TYPED and FIRST. ClassifyError has no row
  for ErrVersionMismatch and neither leg wraps it in ErrValidation, so below
  those arms all three would answer a generic 500. Verified by mutation.
- `applyInt64Member` becomes `applyVersionGuardMember` and names the member
  itself: five call sites, one spelling, and no unparam exclusion.

Two tests changed rather than being added to: reopen's "publishes no conflict
code" is now "publishes no POLICY conflict code", written as an exact set, and
`TestDeleteRequestMembersMatchTheHandler` is new — that handler's member list
was hand-rolled with nothing tying it to the document.

Gates: `make api-check`, `go build ./...`, `go vet ./...`, `gofmt -l` clean,
`golangci-lint run` on the touched packages and `--new-from-rev=origin/main`
(0 issues), and `BEADS_TEST_PROXIED_SERVER=1 CGO_ENABLED=1 go test ./cmd/bd/
-run 'TestProxiedServerServeClose|TestProxiedServerServeDelete'` 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>

* Record the compare-and-set rule where the next handler author will look

Five handlers now match ErrVersionMismatch typed before reaching failErr, and
each said why in its own words. That is five coincidences, not a rule: handler
author #6 reads ClassifyError, finds no row for the sentinel, and concludes the
shared mapping covers it.

State it at ClassifyError instead. That function CANNOT build a
precondition_failed — the refusal echoes the value the REQUEST guarded on and
ClassifyError is handed an error alone — so any operation publishing
expected_version, expected_status or expected_assignee must match the sentinel
typed in its own failure path. Forgetting is not a worse 4xx: neither storage
leg wraps these in ErrValidation, so the miss falls through the default arm and
every guard failure on that operation is a generic 500.

The three handlers this stack added now cite that rule rather than restating it.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* lint: the last US spelling in problem.go

main was red on its own Lint job (misspell, locale US) from two words the
release slice added. `neighbour` has since been fixed upstream; `archaeology`
at problem.go:85 is the one left, and the PR workflow lints the whole tree with
only-new-issues: false, so every open PR inherits the failure until it goes.

Not this stack's breakage, and landed here only because this stack is what it
was blocking. Prose only; no behavior.

---------

Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-09 17:02:53 -07:00
Julian Knutsen
38c3564075
claimNext + batchClose + incremental labels: the three role-backed ops with no wire (ga-g3gg8) (#5510)
* 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>
2026-08-09 16:02:52 -07:00
Julian Knutsen
294af94be2
Publish POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv) (#5507)
* 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>
2026-08-09 14:41:28 -07:00
Julian Knutsen
93924f1226
Publish updateIssue's guarded members: status, assignee, parent_id, metadata (#5484)
`PATCH /v0/beads/issues/{id}` documented four exclusions and gave one
reason for all of them: status belongs to close/reopen/claim, assignee to
the claim's compare-and-set, metadata deserves its own design pass,
parent_id is a graph edit in patch clothing — and keeping them out was
"half the reason this operation documents no 409 at all."

That held until `issues:batchApply` landed, whose update item publishes
`status`, `assignee`, both force flags and all three `expected_*` guards,
and says of itself that it patches one issue "under PATCH's rules plus the
preconditions and force flags that operation deliberately does not
publish." Two operations for patching one issue, disagreeing about what
patching one issue means. This closes the gap from the other side.

`patch` grows `status`, `assignee`, `parent_id` and `metadata` — the last
reusing `ApplyMetadataPatch` and `applyMetadataPatch()` themselves, not a
second spelling of the replace/merge/set/unset algebra. Beside `patch` the
request grows `expected_version`, `expected_status`, `expected_assignee`,
`force_close_policy` and `force_assignee_transfer`.

The conflicts follow the members, and every one is inherited rather than
invented: close policy's `not_closable` from `status`, the assignee fence's
`already_claimed` from `assignee`, the graph's `dependency_cycle` and
`dependency_exists` from `parent_id`, and `precondition_failed` from the
guard trio. failUpdate matches all of them TYPED and BEFORE its
ErrValidation and ErrNotFound arms, which is the correctness of this
change: the reparent and precondition bodies return raw on one leg and
wrapped on another, so without that order one condition would have answered
500 on the unit-of-work leg and 400 on the store legs.

`UpdateIssueResponse` gains `revision`. `expected_version` guards an opaque
token, `types.Issue.RowVersion` is json:"-" so no read on this surface
publishes one, and a guard whose token no response carries is a guard a
caller cannot fill. A read-modify-write loop now composes its next
expectation from the value the write answered with.

A `patch.parent_id` naming the issue itself is refused at the edge — the
child is the id in the path, so the request contradicts itself with no
state read, and the two legs of the role disagree about which error they
raise for it. A new parent that names nothing stays a 400, conforming to
dependencies:add; the 404 remains the path id's alone.

Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-09 10:24:36 -07:00
Julian Knutsen
b138fb08ef
Publish POST /v0/beads/issues: the single create, with the whole vocabulary (#5483)
`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>
2026-08-09 09:21:56 -07:00
Julian Knutsen
e9e2c49431
Add issueops.BatchApplier: one plan, one transaction (#5480)
* 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>
2026-08-09 06:59:34 -07:00
Julian Knutsen
9a2c918b0e
Admit the ephemeral plane from a list request, on the facade and on the wire (#5476)
* feat(reader): admit the ephemeral plane from a list request

`issueops.Reader.Ready` has had an ephemeral gate since it was written;
`List` has not. The wisp plane was reachable from a list request only as
a SIDE EFFECT of `IncludeInfra`, which also drops the infra-type
exclusions, or by naming an infra type, which routes to that plane
ALONE. A caller that wants the ephemeral rows of ordinary types — a
message bead, say — could ask for them on the ready query and not on the
listing, and the wire said so in prose: listIssues published no
`include_ephemeral`, and the document called the asymmetry out.

ListRequest.IncludeEphemeral closes it, with the same semantics
ReadyRequest.IncludeEphemeral already has.

  false (zero value)  durable rows only — today's listing, unchanged
  true                the wisp plane merged IN ADDITION; the answer is a
                      superset of the false answer under the same
                      filters, and never ephemeral-only
  WispType            a predicate on the wisp_type COLUMN, which BOTH
                      tables carry, so it selects no plane: it narrows
                      whatever was admitted. WispType alone answers with
                      nothing, since no durable row carries a
                      classification; WispType + IncludeEphemeral is
                      lawful and composes as an ordinary AND
  order               ONE order across both planes, by SortBy, as if
                      they were a single table — not durable rows
                      followed by ephemeral ones. A Limit truncates the
                      merged order, and the keyset position is applied
                      to BOTH legs, so a cursored walk over the merge
                      drops no row and repeats none. The non-snapshot
                      caveat is the one every multi-page walk already
                      has; the ephemeral plane only turns over faster
  --ready             CARRIED, not dropped. The ready query has an
                      ephemeral gate of its own, so
                      ReadyFilterFromIssueFilter now reads the plane bit
                      off the list filter. That also carries
                      IncludeInfra's plane half, which the projection
                      used to drop silently — `bd list --ready
                      --include-infra` now answers with the wisps `bd
                      count --include-infra` already counts

It is a PLANE knob and not a TYPE knob, which is the whole difference
from the three fields beside it: templates, gates and infra types stay
hidden by their own predicates. IncludeInfra remains strictly wider.

The wire gets `include_ephemeral` on listIssues, spec-first. There is no
capability-token change: it is an ordinary optional query parameter, so
an older server answers it with 400 `unknown_parameter` — the designed
skew signal, whose recovery is to degrade rather than retry.

Conformance runs on all three legs (server-backed store, embedded store,
unit of work) and covers admission, the merged order, every page bound
across the interleaving, a cursored walk across the plane boundary, and
the WispType interaction. The two seams arrange the merge differently —
one merge-sorts two independently ordered legs in Go and trims, the
other ORDERs a SQL UNION ALL — so the bounded and cursored arms are a
genuine two-body case rather than one body twice.

* fix(reader): correct the flag's reach, and settle the merge seam it lands on

Review follow-up. Three of these are documentation being wrong about the
code; one is the code itself.

THE MOTIVATING EXAMPLE WAS FALSE. `message` is one of the DEFAULT INFRA
TYPES (agent, role, message), so "the ephemeral rows of ordinary types —
a message bead, say" named the one row this flag cannot reach: the
infra-type exclusion is a TYPE predicate and survives the plane knob, as
the golden already recorded and nothing asserted. `bd ready` cannot
deliver it either — ReadyWorkExcludeTypes appends the infra set
unconditionally. The field doc, the operation description and the
parameter text now say that ephemeral agent/role/message rows need
IncludeInfra, and what the flag alone reaches is the ephemeral rows of
the types a listing already shows.

The contract case is what makes it more than a corrected sentence. The
fixture's only wisp was a task, which comes back under EITHER knob, so a
body that wired the plane flag to IncludeInfra's branch answered every
row correctly. An infra-typed wisp is hidden twice over — once by the
plane, once by the type — and is the only row that can tell the two
apart. Three rows now pin it: absent under IncludeEphemeral, present
under IncludeInfra, present under both. Wiring the flag into the
type branch fails it.

TWO MORE DOC CORRECTIONS on the same field. It admits the wisps TABLE,
which holds no-history rows (ephemeral = 0) alongside true ephemerals —
stated, rather than left as "the ephemeral plane". And it is NOT
identical to ReadyRequest.IncludeEphemeral: ready reads both planes
either way and adds a per-ROW ephemeral predicate when unset, where this
selects which TABLES are read. The difference is observable on exactly
those no-history rows, which a DEFAULT ready answer already contains and
a default listing does not.

The ready projection's predicate is negative, on a field whose zero
value means admit, so it fires for a filter that merely never set
SkipWisps rather than for one that asked. Every caller is handed a
BuildListFilter result, which decides that field for every request, so
"unset" is unreachable today — named at the site so the next hand-built
filter does not walk into it.

THE SEAM DISAGREEMENT, which is the code change. A cross-plane duplicate
id was tolerated by the per-table seam (collapse to the canonical wisp,
answer) and HARD-ERRORED by the union seam, and this flag routes every
wisp-inclusive read onto the union. Two implementations of one role
answering a page and an error is a divergence, not a design, and leaving
it silent while making it reachable is worse than either behavior.

The union now resolves it the way its sibling does, at all four sites,
and the strict flag is gone rather than left as a footgun. Three things
say that is the right verdict and not merely the convenient one: the
per-table seam has said so since be-iabdi ("hard-erroring breaks every
lookup city-wide"); `bd doctor` detects the state with a query of its
own, so answering blinds no detector; and its fix deletes the stale
ISSUES copy, which is exactly the row the union now drops. Its own check
text names the hard failure as the damage — "stale issues-table copies
break every lookup for the affected IDs". The four tests that pinned the
error now pin the wisp-canonical answer; inverting the preference fails
all four.

Preferring the wisp needs a second pass: the outer ORDER BY can place
either copy first, so which leg produced a row is known in full only
after the scan.

Last, a stale comment: issueops/count.go claimed SearchIssuesInTx was
the corruption detector. It has not been one since be-iabdi. The count
trusts the disjoint-table invariant and no read enforces it, so a
dual-resident id is counted twice and listed once; doctor is the
detector and the repair.

---------

Co-authored-by: Review Sim <ci@beads.test>
2026-08-09 05:06:36 -07:00
Julian Knutsen
1a1431be3f
Add issueops.MetadataCAS: compare-and-set over one metadata key (#5473)
* 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>
2026-08-09 04:15:34 -07:00