beads/internal/httpclient/encode/ledger.go
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

1040 lines
90 KiB
Go

// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/encode/ledger.go@49d1df2f6)
// to OSS beads under the MIT license.
package encode
import (
"fmt"
"reflect"
"sync"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/issueops"
)
// The divergence ledger, v1.
//
// engdocs/design/http-client-backend.md D9 states the discipline this file
// instantiates: "Every knowingly-degraded behavior is a ledger row with a
// pinned test... A degradation not in this table is a bug." The prose table
// lives in the design; this is the machine-readable copy the client actually
// consults, and it carries three populations rather than one:
//
// - The D9 rows themselves (L1-L18, with L17 deleted rather than skipped —
// see the L-sequence note in designRows), which describe whole behaviors rather
// than single fields. They are here so that the numbering the design and
// the review log cite resolves to something a test can read.
// - The refuse-not-drop enumeration D8 closes with: every role-request field
// the wire has no member for. These name a Go field on a request type and
// are what makes "refused, never dropped" checkable rather than asserted.
// - One row per request-shape field this package's encoder cannot put on the
// wire. Those are the rows the encoder itself reaches for: a refusal is
// raised BY ledger id, so a refusal with no row is a compile-time absence
// rather than a prose gap, and the bijection gate reads the same rows back.
//
// WHY A REFUSAL CARRIES A ROW RATHER THAN A STRING. D7's third taxonomy text
// has to name the flag that produced a parameter, and D9 requires every
// degradation to cite a pinned test. Both facts belong to the divergence, not
// to the call site that discovered it, so the call site raises the id and the
// row supplies the vocabulary. It also makes the failure mode of a forgotten
// entry loud: RowByID panics on an unknown id, and the bijection gate fails on
// a row nothing references.
//
// WHAT IS NOT HERE. Rows for the surfaces this package does not encode — the
// unsupported-allowlist refusals of D8, the whole-command refusals of D7 that
// have no request field — appear only where the design names them as
// refuse-not-drop residue or as a D9 row. The store skeleton owns the rest.
// Kind classifies what a ledger row promises.
type Kind string
const (
// KindRefuse is a divergence that FAILS rather than proceeding: a
// populated field, or an invoked flag, that the v0 wire cannot express.
// Refusing is the whole point — a dropped filter widens a result set
// invisibly, which is the one failure class no server-side gate can
// observe (D7).
KindRefuse Kind = "refuse"
// KindDegrade is a divergence that PROCEEDS with knowingly different
// behavior. Every one of these is a judgment that the difference cannot be
// misread as a narrower or wider answer than the caller asked for.
KindDegrade Kind = "degrade"
// KindRetired is a row the design has retired. It stays so the L-numbers
// the design, the council log and the beads cite keep resolving, and so a
// re-enumeration can tell "retired" from "never existed".
KindRetired Kind = "retired"
)
// Row is one divergence: what diverges, why, which decision it comes from, and
// what pins it.
type Row struct {
// ID is the stable citation. D9's own rows keep their L-numbers; the rest
// are prefixed by population — E for an encoder field, W for the
// write-side refuse-not-drop enumeration, F for a command or flag.
ID string
// Kind is what this row promises.
Kind Kind
// Type and Field name the Go request field that diverges, for the rows
// that have one. Type is nil on a row that describes a behavior or a flag
// rather than a field. Holding the reflect.Type rather than its name is
// what makes a renamed or deleted field a test failure instead of a stale
// string.
Type reflect.Type
Field string
// Flag is the user's spelling, where one exists — D7's refusal texts speak
// flags and commands, never store method names. Empty when the divergence
// has no single flag behind it.
Flag string
// Command is the cmd/bd command path this row is about, spelled the way the
// classification tables spell it ("count", "ready", "mol ready"). Empty on a
// row that is not about a command.
//
// It exists because the command was only ever in the PROSE, and prose is
// what let F-count claim `bd count` refuses for a whole wave after the
// command was served. cmd/bd's TestFRowsAgreeWithTheCommandClassification
// binds this field to httpRefusedCommands/httpServedCommands, so the claim
// is checked rather than read.
Command string
// Capability is the wire token behind a LATE refusal: the command is SERVED
// and refuses only against a server that does not advertise this token.
//
// It is what distinguishes F-close — a refuse row whose command is served —
// from a whole-command refusal, and it binds harder than a boolean would:
// the gate requires the served command's own capability list to name it.
Capability string
// What describes the divergence for a reader. Required on every row; on a
// field row it says what the field asked for that the wire cannot carry.
What string
// Why is the reason the wire cannot carry it, or the reason the
// degradation is the right answer.
Why string
// SpecRow cites the decision in engdocs/design/http-client-backend.md.
SpecRow string
// PinnedBy names the test that holds this row honest, or carries a
// TODO(<bead>) when the pinning test is another bead's deliverable. It is
// never empty: D9's whole discipline is that a ledger row without a pin is
// a wish.
PinnedBy string
}
// pinnedByS3Conformance is the TODO sentinel for ledger rows whose claim is
// provable only from behind two seams this package (S2) does not build:
//
// - a server wired to a real/reference backing store — multi-page reads
// under concurrent writes, racing claims, dual-running against a second
// implementation, actor/provenance rules an httptest fixture's canned
// in-memory role does not enforce — and
// - cmd/bd wired to this client — the subprocess parity corpus, the
// pre-run classified-refused-command table, flag-mode refusals driven
// through the real cobra tree.
//
// Both are S3's: the store/dial seam and the cmd/bd integration that gives
// this client a binary to run those suites against. Until that wiring lands
// there is no test in ANY package that exercises the claim, so each row that
// cited an enterprise test of this shape is re-pinned here rather than left
// pointing at a name with nothing behind it — the well-formedness gate
// accepts TODO(<bead>) for exactly this reason (see PinnedBy's doc comment).
//
// This package's OWN behavior — the encode/decode tables, the capability
// gate, the wire-revision floor — stays pinned to real tests in this package
// (TestEncoderTableClassifiesEveryRequestField,
// TestEncoderHonorsEveryTableDisposition,
// TestEncodedParametersRoundTripThroughTheServerDecoder, and friends); this
// sentinel covers only the rows whose evidence is a layer S2 never touches.
const pinnedByS3Conformance = "TODO(S3): store/dial-seam and cmd/bd conformance this package's own gates do not reach; see the S2 handoff notes for the full list of rows re-pinned here and engdocs/design/http-client-backend.md D9 for the discipline"
// Ledger returns divergence ledger v1, in citation order.
//
// It builds a fresh copy per call rather than handing out a package-level
// slice, so no caller can edit the ledger another caller reads. The encoder's
// own lookups go through cachedLedger below and never through this.
func Ledger() []Row {
var rows []Row
rows = append(rows, designRows()...)
rows = append(rows, writeSideRows()...)
rows = append(rows, commandRows()...)
rows = append(rows, readyRequestRows()...)
rows = append(rows, listRequestRows()...)
rows = append(rows, queryRequestRows()...)
rows = append(rows, issueFilterRows()...)
rows = append(rows, parentWalkRows()...)
rows = append(rows, workFilterRows()...)
return rows
}
// RowByID returns the row a refusal cites.
//
// It PANICS on an unknown id, which is the correct severity: the ids are
// package constants used from this package's own encoder, so an unknown one is
// a programming error that would otherwise surface as a refusal with no
// vocabulary — exactly the "raw store-method refusal reaching a %v call site"
// D7's choke point exists to make impossible.
func RowByID(id string) Row {
for _, row := range cachedLedger() {
if row.ID == id {
return row
}
}
panic(fmt.Sprintf("encode: no divergence-ledger row %q", id))
}
// cachedLedger is what a REFUSAL reads, so raising one does not rebuild the
// whole ledger. Ledger() keeps building a fresh copy for everyone else.
var cachedLedger = sync.OnceValue(Ledger)
var (
tyReadyRequest = reflect.TypeOf(issueops.ReadyRequest{})
tyListRequest = reflect.TypeOf(issueops.ListRequest{})
tyQueryRequest = reflect.TypeOf(issueops.QueryRequest{})
tyCountRequest = reflect.TypeOf(issueops.CountRequest{})
tyCountByGroupRequest = reflect.TypeOf(issueops.CountByGroupRequest{})
tyGetRequest = reflect.TypeOf(issueops.GetRequest{})
tyIssueFilter = reflect.TypeOf(types.IssueFilter{})
tyWorkFilter = reflect.TypeOf(types.WorkFilter{})
tyUpdateRequest = reflect.TypeOf(issueops.UpdateRequest{})
tyCloseRequest = reflect.TypeOf(issueops.CloseRequest{})
tyReopenRequest = reflect.TypeOf(issueops.ReopenRequest{})
tyDeleteRequest = reflect.TypeOf(issueops.DeleteRequest{})
tyAddDeps = reflect.TypeOf(issueops.AddDependenciesRequest{})
tyIssuePatch = reflect.TypeOf(issueops.IssuePatch{})
tyCreateRequest = reflect.TypeOf(issueops.CreateRequest{})
tyCreateBatch = reflect.TypeOf(issueops.CreateBatchRequest{})
tyBatchCreateItem = reflect.TypeOf(issueops.BatchCreateItem{})
tyCreateDep = reflect.TypeOf(issueops.CreateDependency{})
tyApplyCreateItem = reflect.TypeOf(issueops.CreateItem{})
)
// designRows are D9's own table, transcribed. They describe behaviors rather
// than fields, so they carry no Type — but they are the rows the L-numbers in
// every other citation resolve to, and dropping them here would leave those
// citations pointing at prose only.
func designRows() []Row {
// pinnedElsewhere is for the three PRE-RUN degradations of D4 — molecule
// auto-load (L5), auto-import (L6), the ready view's parent-epic map (L13) —
// whose observable behavior is a cmd/bd invocation's, not a store call's.
// They are the subprocess parity tier's, and that tier is the one this wiring
// did not build. ga-b8ddd.12 (per-request project-id enforcement) closed the
// read-display ESCALATION — every read now carries the stamp, so a drifted
// server refuses it rather than rendering another project's rows — but the
// remaining fixture corpus that would PIN these pre-run displays is its
// follow-up, ga-b8ddd.23, which owns them.
//
// L17 (the conditional dep-remove guard) used to be the one remaining TODO row
// that was NOT subprocess-owned. It carried no row of its own once its
// condition resolved: the dual run ga-b8ddd.30 wrote
// (TestServedDependencyRecordsSurfaceUnresolvedRowsVerbatim) showed the wire
// surfaces unresolved depends_on_id rows VERBATIM, so the guard does not
// degrade and there was nothing to ledger. It is DELETED rather than retired,
// because a retirement records a divergence that once existed and this one
// never did. L1 is the retirement beside it — a row that WAS live and is kept
// as KindRetired for exactly that reason.
const pinnedElsewhere = "TODO(ga-b8ddd.23): a pre-run degradation, observable only through a cmd/bd invocation; the subprocess parity corpus pins it"
return []Row{
{
// IT WAS DELETED OUTRIGHT for a while, against this file's own
// retirement policy: KindRetired exists so a re-enumeration can tell
// "retired" from "never existed", and the design keeps L1 in D9's
// table. A deleted row makes the two disagree and turns RowByID("L1")
// into a panic rather than an answer.
ID: "L1", Kind: KindRetired,
What: "RETIRED — `bd list` over http could not ask for the wisp plane",
Why: "retired by the upstream ask the design page filed for it: \"include_ephemeral on listIssues (retires L1)\". Upstream published the parameter, the server decodes it (internal/httpapi/reads.go handleListIssues), and the encoder emits it whenever ListRequest.IncludeEphemeral is set. " +
"THERE IS NO DIVERGENCE LEFT TO RECORD. `bd list` still shows no wisps, but it shows none LOCALLY either: the front door registers no --include-ephemeral (only `bd ready` does, ready.go), so the field is unset on both paths and both answer the durable plane. A degrade row describing behavior the local oracle shares is not a degradation, and keeping it as one would be the same falsified-premise problem the W- rows had — a ledger arguing from a document that moved",
SpecRow: "D9 L1 (RETIRED), D8 row 1",
// A retirement turns a refusal pin into a ROUND-TRIP pin: the
// parameter is populated here and read back by the server's own
// decoder, which is the fact the retirement rests on.
PinnedBy: "TestEncodedParametersRoundTripThroughTheServerDecoder",
},
{
ID: "L2", Kind: KindDegrade,
What: "a non-created `bd list` sort, the flagless default included, costs page-to-exhaustion on the three legs that cannot push the order down: an unlimited read (--limit 0), a caller-supplied keyset position, and a server that does not advertise issues.list.sort",
Why: "NARROWED, not retired, by the upstream ask this row named: listIssues publishes `sort` and `reverse`, and the pager's pushdown leg (list_walk.go sortedPage) answers a bounded, position-free request against an advertising server in ONE request, with the server's own LIMIT deciding which rows survive the caller's order. " +
"What is left is the legs where that is unavailable or unsafe. An unlimited read has to cross every row whatever the order, and `limit=0` pushed down would newly meet the server's unlimited-read refusal. A keyset position is defined in the created order, and the pager's prefix discard run against a page some other order truncated would drop rows whose replacements were never fetched — a wrong answer rather than a slow one. A down-level server is the fallback the capability probe exists to reach. On all three the client still fetches every page and applies the SQL order's own Go-side mirror plus a copy of the page epilogue's comparator. " +
"The weld itself is NOT a divergence and never was: a cursor is bound to the paged order it was minted in (`created` or `priority`) and the server refuses it under any other `sort`",
SpecRow: "D9 L2, D8 row 1",
// The dual run is the load-bearing half: it answers the SAME
// request from the reference store and from the client and compares
// the orders, so the divergence this row admits (the cost) is
// pinned separately from the one it forbids (a different answer).
// It now runs every arm TWICE, once down each leg, which is what
// makes the narrowing checkable: the pushdown and the walk have to
// agree with the reference AND with each other, truncated pages
// included, where the truncation is the only thing a re-sort cannot
// repair.
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L3", Kind: KindDegrade,
What: "a multi-page fetch has no snapshot isolation",
Why: "the keyset cursor pins a position, not a snapshot: rows created mid-walk are missed and row states mix instants, where local mode is one query",
SpecRow: "D9 L3",
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L4", Kind: KindRetired,
What: "`bd show` dependents sections and comment bodies were degraded",
Why: "retired by council #1: the write-lifecycle wave landed include_dependents/include_comments on getIssue, and both the off-role text path and the on-role JSON path are wired",
SpecRow: "D9 L4 (RETIRED), D4, D8 row 1",
// The dual run answers a Get from both sides and compares the
// MARSHALED bytes, over a row seeded with an edge and a comment
// precisely so the dependents and comments the retired degradation
// was about are non-empty on at least one side.
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L5", Kind: KindDegrade,
What: "molecules are not auto-loaded pre-run",
Why: "the loader writes, the write refuses, and the call site swallows the refusal to debug.Logf",
SpecRow: "D9 L5, D4",
PinnedBy: pinnedElsewhere,
},
{
ID: "L6", Kind: KindDegrade,
What: "a pre-run auto-import ATTEMPT reaches an http workspace and fails as a best-effort stderr warning; nothing is imported",
Why: "THE MECHANISM THIS ROW USED TO NAME DOES NOT EXIST. It said the path was \"force-disabled through an import.auto=false env override\", and there is no such override anywhere: shouldRunAutoImportJSONL (cmd/bd/main.go) reads the config key, whose default is true (internal/config/config.go), and no http path sets it false. " +
"WHAT ACTUALLY HAPPENS is that maybeAutoImportJSONL runs — on any non-read-only, non-global, non-server-mode command — and is stopped by its own guards rather than by a switch: a missing or empty issues.jsonl, the attempt stamp, or the emptiness guard, which is a GetStatistics the server serves. Where all three pass (an empty server beside a non-empty local JSONL) the import is attempted and fails, because the client is not a jsonlImporter and the fallback importer's first write — SetConfig, or CreateIssuesWithFullOptions — is on the unsupported allowlist. The function is documented best-effort, so the failure is an stderr warning and the command proceeds. " +
"The DEGRADATION is therefore that nothing imports, which is the outcome the design wanted for the right reason — importing a local JSONL into a shared server is not a pre-run side effect — reached by refusal rather than by configuration. It stays a degrade because the command proceeds and the answer is not narrower or wider than the caller asked for. The retirement path is a real skip on the http backend, so the warning stops being the mechanism",
SpecRow: "D9 L6, D4",
PinnedBy: pinnedElsewhere,
},
{
ID: "L7", Kind: KindDegrade,
What: "the client-side status/type vocabulary is defaults plus the status.custom/types.custom/types.infra config keys; table-backed customs are invisible client-side",
Why: "the custom_statuses/custom_types tables have no wire operation; server-side role validation still uses the true vocabulary",
SpecRow: "D9 L7, D4",
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L8", Kind: KindRefuse, Flag: "--deps",
What: "`bd list --deps` refuses, and the pretty/--format dependency-decoration arms render undecorated",
Why: "GetAllDependencyRecords has no wire mapping in v1; listDependencies is an anchored read. --tree is NOT in this row: it defaults true and is `bd list`'s default text rendering",
SpecRow: "D9 L8, D4",
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L9", Kind: KindDegrade,
What: "credential-bearing settings are unreadable client-side",
Why: "the server redacts by omission and says so on the wire in Setting.redacted; the client answers absent-WITH-A-REASON rather than the empty string a caller would read as unset",
SpecRow: "D9 L9",
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L10", Kind: KindRefuse, Flag: "--watch",
What: "`bd list --watch` and `bd show --watch` refuse",
Why: "the loops poll every 2s, each `bd list` tick is a full cursor walk (L2), per-tick errors spam or vanish, and the decoration is refused anyway (L8); N watchers against one server is a request storm its semaphore answers with 503s the loop does not back off from",
SpecRow: "D9 L10, D10",
// Two halves, one pin each: the TEXT is byte-pinned in the store
// (TestTheWatchRefusalReadsExactlyAsTheSpecWroteIt), and the
// flag-level early refusal that renders it is exercised against the
// real cobra tree here. The wrapper reads the text off
// (*Store).RefuseWatch rather than keeping a second copy.
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L11", Kind: KindDegrade,
What: "hooks fire client-side after the server's commit with no shared transaction, on connected workspaces only",
Why: "the seam sits below HookFiringStore in the client process; a --server-url ephemeral invocation has no hook directory and runs none",
SpecRow: "D9 L11, D1",
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L12", Kind: KindRefuse,
What: "an inexpressible filter refuses, never drops — the class rule every E- row below is an instance of",
Why: "a dropped filter widens a result set invisibly, and the server can only reject parameters it receives",
SpecRow: "D9 L12, D7",
PinnedBy: "TestEncoderHonorsEveryTableDisposition",
},
{
ID: "L13", Kind: KindDegrade,
What: "pretty `bd ready` shows no parent-epic context",
Why: "buildParentEpicMap swallows the GetDependencyRecordsForIssues refusal into a nil map; the retirement path is an anchored listDependencies plus per-parent getIssue",
SpecRow: "D9 L13, D4",
PinnedBy: pinnedElsewhere,
},
{
ID: "L14", Kind: KindDegrade,
What: "against a server that does NOT advertise issues.claimNext, the composed ReadyClaimer leaves three residues: the ready-at-fetch/claim-at-dial window, a false empty under contention after the bounded refetch, and a claimed row whose CARDINALITIES are as of the listing rather than of the claiming transaction",
Why: "claimIssue validates claimability, not readiness, so a listing plus a claim is not the local role's one transaction and cannot be made into one. " +
"THE ROW IS NARROWER THAN IT WAS. Upstream published POST /v0/beads/issues:claimNext (#5510) and client wave ga-jpywb dials it, so on any server that advertises the token NONE of these three residues exists: selection, the compare-and-set and the hydration share the server's own transaction, an empty front is a 200 with `claimed` absent rather than a lost-races error, and the counts describe the state the claim produced. The whole ReadyClaimer contract tier runs against that leg with nothing parked, which is the measurement that says the residues were the COMPOSITION's rather than the wire's. " +
"WHAT KEEPS THE ROW ALIVE is the DOWN-LEVEL leg, which survives on purpose: `bd ready --claim` worked against pre-#5510 servers before this port, and refusing it now would be a regression dressed as progress. It is the posture BatchCloser takes toward issues.batchClose, and it is why this row describes shipped behavior rather than history. " +
"The third residue is stated in its IMPLEMENTED form, which is not the one the design anticipated: the design expected a follow-up getIssue to hydrate the counts, and therefore a read that could fail AFTER the claim was durable. The composition takes the counts from the ready page it already fetched instead, so that failure mode does not exist — a claim changes no dependency, dependent or comment count, and what is left is staleness bounded by the same fetch-to-dial window residue (a) already owns. " +
"Retirement is no longer an upstream ask but a fleet fact: the row goes when no server this client may meet is older than #5510",
SpecRow: "D9 L14, D8 row 4",
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L15", Kind: KindDegrade,
What: "a --max-rows cap can fire over http on a query whose Limit is at or under the cap, on the `bd list` legs that still walk",
Why: "locally the effective SQL LIMIT is min(Limit, MaxRows+1), so a window at or under the cap can never exceed it; over http a walk to exhaustion fetches far more than the window and the cap deliberately bounds WIRE ROWS FETCHED — safety wins over exit-code parity on exactly the unbounded walk the cap exists to bound. " +
"NARROWED by the same pushdown that narrowed L2: the pushdown leg asks for min(limit, MaxRows+1) rows in one request, which IS the local expression, so a cap at or above the limit can no longer fire there and a request that used to exit 2 now answers. That is a convergence toward the contract, and it is observable — the same command changes from a refusal to a page. " +
"THE NARROWING IS SCOPED TO THE ORDERS SQL CAN EXPRESS, and that scope is a correctness bound rather than an optimization left on the table. For a GO-SIDE sort — sqlbuild.IsGoSideSort, today `--sort id`, which needs the natural-numeric comparison (bd-9 before bd-10) no ORDER BY renders — workapi.SQLLimit pushes 0 down instead of the limit, so LOCALLY the window is MaxRows+1 whatever the limit is and the cap fires on the overage even under a limit at or below it. min(limit, MaxRows+1) is therefore NOT the local expression there, and a request bounded by the limit cannot see the overage at all. walkIssues' gate keeps a capped Go-side sort on the walk, where fetching MaxRows+1 wire rows reproduces that unbounded local window exactly and raises the same refusal — so on this one shape the walk leg is the CONVERGENT one and pushing down would have been the divergence. " +
"What keeps the row live is the walk legs (unlimited reads, keyset positions, down-level servers), where the old accounting is unchanged and correct, and `bd ready`, which has no pushdown at all",
SpecRow: "D9 L15, D12",
// Re-pointed from the ready bridge's cap test to the list one,
// because the narrowing is a `bd list` fact and the ready cap is
// the part that did not move. The list test carries the repair
// (a roomy cap under pushdown answers), the residue (a cap under
// the limit still fires there) and the control (the same roomy cap
// still fires down the walk leg) in one place.
// TestTheReadyBridgeEnforcesMaxRowsClientSide still pins the ready
// half and is unchanged.
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L16", Kind: KindRefuse, Flag: "--file",
What: "`bd dep add --file` carrying more than 100 edges refuses, naming the wire bound; it is never chunked",
Why: "maxAddDependencyEdges = 100 (internal/httpapi/dependency_edit.go); chunking is the one path that silently breaks the request's one-transaction/one-history-entry contract, where naive forwarding at least fails loudly",
SpecRow: "D9 L16, D7, D8 row 18",
// The boundary itself, both sides: exactly maxAddDependencyEdges
// serves, one more refuses, and the refusal never dials — chunking
// is what this row forbids, so "did not reach the server" is the
// assertion that matters.
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L-close-cap", Kind: KindRefuse,
What: "a batch close naming more than 100 items refuses, naming the wire bound; it is never chunked",
Why: "maxBatchCloseItems = 100 (internal/httpapi/batch_close.go); the item cap bounds how long one request may hold a write transaction. Chunking is the one path that silently breaks the request's one-transaction/one-history-entry contract — the same reason L16 refuses a bulk dependency add rather than splitting it — so a larger list refuses and the caller splits it, each request atomic on its own",
SpecRow: "D9 L-close-cap, D7 F-close, D8 row 17",
// L16's sibling: exactly maxBatchCloseItems serves, one more refuses,
// and the refusal never dials — chunking is what the row forbids.
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L-dep-endpoint", Kind: KindDegrade,
What: "a dependency add whose source or target names no issue refuses as ErrValidation over http, not as *DependencyEndpointNotFoundError wrapping ErrDependencySourceNotFound or ErrDependencyTargetNotFound",
Why: "the wire spells that refusal as a 400 invalid_argument with reason `invalid_value` and the offending member in `param` (internal/httpapi/dependency_edit.go). Reason and code are the same ones a malformed id earns, so the two are indistinguishable without reading `detail` prose — which is exactly what the extension-member vocabulary exists to avoid. " +
"The refusal still FAILS the request and still writes nothing; only its classification is coarser. Upstream ask: a distinguishing code or reason for the endpoint-not-found refusal, which retires this row",
SpecRow: "D8 row 18",
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L-claim-prose", Kind: KindDegrade,
What: "a claim refusal's MESSAGE does not carry the ClaimedBy/NotClaimableStatus fragments, so beads.ParseClaimConflict recovers nothing from it over http",
Why: "the fragments exist so that parser can recover the conflicting assignee and status from PROSE. Over the wire both arrive as typed extension members and *ClaimConflictError is reconstructed whole, so a caller reading the FIELDS loses nothing. " +
"Recomposing the copy client-side would mean re-implementing which copy each refusal shape gets — an open issue held by someone else deliberately omits the assignee tail, an in-progress one carries it — which is a second implementation of the very rule the fragments were introduced to keep single",
SpecRow: "D8 row 3",
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L-delete-notfound", Kind: KindDegrade,
What: "issueops.Deleter.Delete over http refuses an absent id as issueops.ErrNotFound, not as *NotFoundError naming WHICH ids did not resolve",
Why: "the role's error is a typo report and names every missing id; the wire deliberately does not repeat them (internal/httpapi's NotFound() carries a FIXED detail, so a 404 body cannot echo caller input back). " +
"The refusal still FAILS the request and still deletes NOTHING — not even the ids beside the typo — so the all-or-nothing promise is intact and only the classification is coarser. " +
"It is stated at the ROLE rather than at a command because `bd delete` is not reachable against an http workspace at all (see httpUnconsumedCapabilities); the embedder holding the role is the audience. Upstream ask: an ids extension member on the not_found problem, which retires this row",
SpecRow: "D8 row 13",
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L-delete-dependents", Kind: KindDegrade,
What: "the unforced dependents guard refuses as issueops.ErrValidation, not as *DependentsOutsideRequestError wrapping ErrDependentsOutsideRequest",
Why: "the wire spells that refusal as a 400 invalid_argument with no `param` (internal/httpapi's failDeleteErr) — the fix is to change the REQUEST, by sending cascade or force — so the blocked id and its dependents cannot be reconstructed without parsing detail prose, which is what the extension-member vocabulary exists to avoid. " +
"The guard itself is untouched: the request fails and the graph is whole. Upstream ask: a dependents_outside_request code carrying issue_id and dependents, which retires this row",
SpecRow: "D8 row 13",
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L-delete-bound", Kind: KindRefuse,
What: "issueops.Deleter.Delete refuses a request naming more than 1000 ids, citing the wire bound; it is never split across requests",
Why: "maxDeleteIDs = 1000 (internal/httpapi/delete.go). Splitting is the one path that silently breaks the request's one-transaction, one-history-entry contract — and it would ask the dependents guard about half a request at a time, so a pair the caller deliberately listed together would be refused as an outside dependent. Naive forwarding at least fails loudly. Stated at the ROLE: `bd delete` cannot reach an http workspace, so the embedder is the audience",
SpecRow: "D8 row 13, D9 L16 (the same argument, on the other bulk write)",
// The boundary itself, both sides: exactly maxDeleteIDs serves, one
// more refuses, and the refusal never dials.
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L-batchcreate-bound", Kind: KindRefuse,
What: "`bd create --file` carrying more than 100 issues refuses, naming the wire bound; it is never split across requests",
Why: "maxBatchCreateItems = 100 (internal/httpapi/batch_create.go). The request IS the transaction, so two requests are two transactions and two history entries where the role promises one — and a failure in the second leaves half a plan created, which is the outcome all-or-nothing exists to make impossible",
SpecRow: "D8 row 14, D9 L16",
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L-edgecount-bound", Kind: KindRefuse,
What: "issueops.GraphCounter.CountEdges refuses a request naming more than 100 DISTINCT anchors, citing the wire bound; it is never chunked across requests",
Why: "maxDependencyAnchors = 100 (internal/httpapi/edges.go), the same bound the stored-edge read on this collection carries — the role deliberately sets none of its own and says the bound belongs to the WIRE. " +
"Chunking is what a READ could get away with and this one cannot: CountEdges promises that an anchor's EXISTENCE and its edge count are read from one consistent view, so two requests would let an anchor be reported missing by a probe that raced a create the other chunk's count already saw — one answer contradicting itself, which is the exact failure AnchorEdgeCount.Missing exists to make impossible. " +
"Refusing at the bound fails loudly instead, and the caller splits the question knowing it asked twice. Upstream ask: a cursor or a higher bound on the anchor list, which retires this row",
SpecRow: "D9 L16 (the same argument, on a read), D8",
// The boundary itself, both sides: exactly 100 anchors serve, 101
// refuse, and the refusal never dials.
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L-batchcreate-target", Kind: KindDegrade,
What: "a batch create whose edge target names no issue refuses as issueops.ErrValidation alone, not as ErrValidation WRAPPING ErrNotFound",
Why: "the wire answers a dangling edge target with a 400 invalid_argument naming `items` (internal/httpapi's failBatchCreate), and deliberately does not quote the role's own message, which arrives as a driver error naming tables and constraints. The refusal still fails the whole batch and creates nothing — the promise the row is about — and only the second sentinel is lost. Upstream ask: a distinguishing code for the absent-target refusal",
SpecRow: "D8 row 14",
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L-batchcreate-inbatch", Kind: KindRefuse,
What: "an edge onto an EARLIER ITEM OF THE SAME BATCH cannot be expressed at all over http",
Why: "the capability needs the earlier item to have named an id for itself, and apigen.BatchCreateItem publishes no id member — an explicit id is refused with the rest of W-BatchCreateItem.Issue. So the target of an in-batch edge can only be a row the workspace already holds. " +
"It is a REFUSE row rather than a degrade because the request that asks for it fails: the client refuses the explicit id before the dial, and there is no second spelling that would land the edge silently. The wire's own `target_id` description names this case, so the gap is in the SCHEMA rather than in the handler — the upstream ask is an item id member, which retires this row",
SpecRow: "D8 row 14",
PinnedBy: pinnedByS3Conformance,
},
// L17 (the conditional GH#5005 dep-remove guard) is DELETED, not present as a
// row: ga-b8ddd.30's dual run proved the wire surfaces unresolved
// depends_on_id rows verbatim (see pinnedElsewhere above), so the
// degradation it was contingent on never materialized. The L-sequence skips
// from L16 to L18 for that reason.
{
// IT WAS MISSING HERE while the design carried it and F-close cited
// it TWICE, so RowByID("L18") panicked on a citation the ledger's own
// prose made. The design's record is the one transcribed below.
ID: "L18", Kind: KindDegrade,
What: "DOWN-LEVEL ONLY: against a server that does not advertise issues.batchClose, a single-id `bd close` still composes onto closeIssue and records the SERVER's own close commit message rather than the batch's id-naming entry; the multi-id and --claim-next shapes refuse there",
Why: "the composed leg is one closeIssue call, so the history entry it leaves is the one that operation writes for itself — the batch's entry names the ids it closed and this one cannot, because no batch ran. " +
"Where issues.batchClose IS advertised the whole request is one call and one server-side transaction, so this divergence does not arise at all; the down-level leg survives on purpose, because `bd close` worked against pre-batchClose servers before this port and refusing it now would be a regression dressed as progress. It is the same posture L14 takes toward issues.claimNext. " +
"It is a degrade rather than a refuse because the close LANDS and the answer is neither narrower nor wider than the caller asked for — only the record of it is the operation's rather than the batch's. Retirement is a fleet fact rather than an upstream ask: the row goes when no server this client may meet is older than issues.batchClose",
SpecRow: "D9 L18, D8 row 17",
// The down-level leg, driven against a store whose stub carries no
// capabilities: the single-item shape composes and every other shape
// refuses without dialing.
PinnedBy: pinnedByS3Conformance,
},
}
}
// writeSideRows are the refuse-not-drop enumeration D8 closes with: role-request
// fields on the SERVED writes that the wire publishes no member for.
//
// This package encodes none of these shapes — they are request bodies, not
// query strings — but the rows live here because the ledger is one artifact,
// and because a renamed or deleted field is caught by the same reflection the
// read shapes get.
func writeSideRows() []Row {
const updateSpec = "D8 refuse-not-drop, D7"
// The lifecycle wiring landed, and with it the sweep that drives every
// excluded member one at a time and asserts each fails WITHOUT dialing. The
// completeness of this population — that no member reaches the wire
// unclassified in the first place — is the store package's write-ledger
// gate, which reflects these rows against the apigen bodies.
const pinned = pinnedByS3Conformance
return []Row{
{
ID: "W-UpdateRequest.Claim", Kind: KindRefuse,
Type: tyUpdateRequest, Field: "Claim",
What: "a claim combined with any other UpdateRequest member refuses; a claim ALONE does not — it dials claimIssue directly (see httpLifecycle.claimOnlyUpdate)",
Why: "a claim is claimIssue's own operation and updateIssue cannot perform one, on this wire or on any other; it is the one row here that upstream #5484 did not touch. " +
"claimIssue's own request is the actor alone, so a claim-only UpdateRequest IS that request and is served through the Claimer role instead of refusing — that is gc's exclusive claim path, `bd update <id> --claim --json`. " +
"What still refuses is PATCH claim: a claim folded into one atomic transaction WITH a patch, a guard or a force override, which no operation on this wire publishes and which is not synthesized as two calls (claimIssue then updateIssue), since that would let a caller observe an issue claimed but not yet patched. Upstream gastownhall/beads#6890 tracks the capability that would carry both in one call",
SpecRow: updateSpec,
PinnedBy: pinned,
},
{
// What/Why below are plain and short DELIBERATELY: RefusedError.Error()
// prints both verbatim to whatever reads the returned error, all the
// way out to a CLI user running `bd update <wisp-id> --claim` over an
// http workspace — so this is user-facing prose, not an internal
// engineering note, and it should read that way.
//
// The engineering rationale, for a future reader of this file: the v0
// wire's claimIssue operation (issueops.Claimer's own contract)
// answers a wisp id with ErrNotFound on every backend, including the
// direct route's own claim-by-id — the wisp plane is not claimable
// through that role at all. But claimOnlyUpdate's caller is
// `bd update <id> --claim`, whose Lifecycle.Update DOES claim wisps
// locally (issue-or-wisp routing). Over http, that command is served
// through claimIssue rather than through updateIssue's general
// wisp-aware routing, so a wisp id would otherwise surface the wire's
// generic not-found — a live row reported as though it does not
// exist, indistinguishable from an id naming nothing at all, which a
// not-found-sensitive caller (gc's Claim among them) would read as
// missing rather than as an unclaimable wisp. This refuses by name
// instead, once the client itself recognizes the id names a wisp —
// which it learns only AFTER claimIssue itself answers not_found (see
// claimOnlyUpdate), so an ordinary claim of a real, non-wisp issue
// never pays this probe. Serving a wisp-aware claim (a server-side
// ClaimWisp capability) is tracked as a pending decision, not
// implemented here.
ID: "W-ClaimRequest.Wisp", Kind: KindRefuse,
What: "claiming a wisp is not supported over http",
Why: "the v0 wire's claim operation excludes the wisp plane on every backend; claim this issue from a local workspace instead",
SpecRow: updateSpec,
PinnedBy: pinnedByS3Conformance,
},
{
ID: "W-UpdateRequest.ForceAssigneeTransfer", Kind: KindRefuse, Flag: "--force",
Type: tyUpdateRequest, Field: "ForceAssigneeTransfer",
What: "bypassing the anti-steal assignee fence refuses",
Why: "the wire publishes `force_assignee_transfer` (upstream #5484) and this client does not send it. What the refusal STANDS ON changed with client wave ga-7i6by and the row is narrower for it: the `assignee` the fence guards IS now sent (W-IssuePatch.Assignee), so what is left is the bypass alone. " +
"The fence itself is unbypassable rather than absent — a transfer away from a live foreign in-progress owner refuses with already_claimed, and a matched `expected_assignee` is the OTHER bypass, which this client does send. Carrying this one is a two-member port tracked as ga-2ltro.15",
SpecRow: updateSpec,
PinnedBy: pinned,
},
{
ID: "W-UpdateRequest.ForceClosePolicy", Kind: KindRefuse, Flag: "--force",
Type: tyUpdateRequest, Field: "ForceClosePolicy",
What: "bypassing close policy on a status-crossing update refuses",
Why: "the wire publishes `force_close_policy` (upstream #5484) and this client does not send it; see W-UpdateRequest.ForceAssigneeTransfer for what the refusal now stands on, since client wave ga-7i6by sends the `status` whose crossing the policy gates. " +
"The policy is therefore enforced and not bypassable here: a status crossing into the done category with open children or a live blocker refuses with not_closable, typed, and writes nothing. Tracked as ga-2ltro.15",
SpecRow: updateSpec,
PinnedBy: pinned,
},
{
ID: "W-UpdateRequest.ExpectedVersion", Kind: KindRetired,
What: "the compare-and-set row-version precondition used to refuse",
Why: "RETIRED by the client wave that sends it (ga-jbuyf). The refusal was always the CLIENT's rather than the document's — upstream #5484 published `expected_version` and this client had not been taught to emit it — and the row said so in as many words: 'flipping it is a port, not a decision: send the member, retire this row, and turn the refusal pin into a round-trip pin'. " +
"That is what happened. The member is now sent as a POINTER, so absent stays absent: 0 is a legal token (the migration-0054 backfill left rows holding it) and encoding 'no guard' as 0 would have armed a guard on every unguarded update. The pin below asserts the round trip in both directions",
SpecRow: updateSpec,
PinnedBy: pinnedByS3Conformance,
},
{
ID: "W-UpdateRequest.ExpectedAssignee", Kind: KindRetired,
What: "the compare-and-set assignee precondition used to refuse",
Why: "RETIRED with W-UpdateRequest.ExpectedVersion (ga-jbuyf). Its own trap is the mirror image of that one's: the EMPTY assignee is a real guard — it is how a caller says 'only if nobody holds it' — so this member cannot be omitted when it is empty either. " +
"A pointer expresses both, and the pin drives the empty-string guard as its own case",
SpecRow: updateSpec,
PinnedBy: pinnedByS3Conformance,
},
{
ID: "W-UpdateRequest.ExpectedStatus", Kind: KindRetired,
What: "the compare-and-set status precondition used to refuse",
Why: "RETIRED with W-UpdateRequest.ExpectedVersion (ga-jbuyf). The status guard is the readable one — `Issue.status` is on every read of this surface, so a caller can guard a transition with no token at all — and it is sent as the workspace's own status vocabulary, verbatim",
SpecRow: updateSpec,
PinnedBy: pinnedByS3Conformance,
},
{
ID: "W-UpdateRequest.IssuePlaneOnly", Kind: KindRefuse,
Type: tyUpdateRequest, Field: "IssuePlaneOnly",
What: "restricting an update to the issue plane refuses",
Why: "updateIssue publishes no plane restriction and the server's role auto-resolves both planes, so dropping the flag would EDIT the wisp the caller asked to be told did not exist — the widening refuse-not-drop exists to stop. " +
"Not in the design's own enumeration: the page lists the UpdateRequest members it had reviewed, and this one was found while wiring the role",
SpecRow: updateSpec,
PinnedBy: pinnedByS3Conformance,
},
{
ID: "W-UpdateRequest.Provenance", Kind: KindRefuse,
Type: tyUpdateRequest, Field: "Provenance",
What: "labeling an update's history entry refuses",
Why: "updateIssue publishes no provenance member and the server writes its own label, so a dropped Provenance would leave the history entry naming the SERVER's surface while the caller believed it named theirs. " +
"It is refused rather than degraded because the field's whole purpose is the label, so dropping it drops the request",
SpecRow: updateSpec,
PinnedBy: pinnedByS3Conformance,
},
{
ID: "W-CloseRequest.ExpectedVersion", Kind: KindRetired,
What: "the compare-and-set row-version precondition on a close used to refuse",
Why: "RETIRED by the client wave that sends it (ga-jbuyf). CloseIssueRequest publishes expected_version (upstream #5506) and this client now emits it, so the guard reaches the server rather than refusing here — and the ordering the role promises, that the precondition is checked BEFORE the idempotent re-close, is the server's to keep and the served tier's to assert",
SpecRow: updateSpec,
PinnedBy: pinnedByS3Conformance,
},
{
ID: "W-ReopenRequest.ExpectedVersion", Kind: KindRetired,
What: "the compare-and-set row-version precondition on a reopen used to refuse",
Why: "RETIRED with W-CloseRequest.ExpectedVersion (ga-jbuyf). The design's enumeration named the close half only, and the reopen half is the same field on the same verb pair — it retires the same way",
SpecRow: updateSpec,
PinnedBy: pinnedByS3Conformance,
},
{
ID: "W-DeleteRequest.ExpectedVersion", Kind: KindRetired,
What: "the compare-and-delete row-version precondition used to refuse",
Why: "RETIRED with W-CloseRequest.ExpectedVersion (ga-jbuyf), and it is the one whose stakes made the refusal worth having: dropping this guard erases a row the caller had asked not to erase, with nothing left to compare afterwards. " +
"The multi-id refusal the wire attaches to it is deliberately NOT anticipated client-side: distinctness is measured after trimming and collapsing duplicates, which is the normalization this role sends its ids verbatim to avoid re-implementing",
SpecRow: updateSpec,
PinnedBy: pinnedByS3Conformance,
},
{
ID: "W-ReopenRequest.Provenance", Kind: KindRefuse,
Type: tyReopenRequest, Field: "Provenance",
What: "labeling a reopen's history entry refuses",
Why: "reopenIssue publishes no provenance member and the server writes its own fixed label (`bd serve: reopen issue`); see W-UpdateRequest.Provenance",
SpecRow: updateSpec,
PinnedBy: pinnedByS3Conformance,
},
{
ID: "W-AddDependenciesRequest.SkipPerEdgeCycleCheck", Kind: KindRefuse, Flag: "--no-cycle-check",
Type: tyAddDeps, Field: "SkipPerEdgeCycleCheck",
What: "`bd dep add --no-cycle-check` refuses on the bulk --file path",
Why: "the wire deliberately leaves SkipPerEdgeCycleCheck UNPUBLISHED and therefore false (internal/httpapi/dependency_edit.go). The single-edge spelling forwards false and only gates the post-hoc cycle warning, which the wire-backed CycleDetector serves, so it is served-with-note rather than refused",
SpecRow: "D7, D8 row 18, D9 L16",
PinnedBy: pinnedByS3Conformance,
},
{
ID: "W-IssuePatch.Status", Kind: KindRetired,
What: "`bd update -s` used to refuse",
Why: "RETIRED with client wave ga-7i6by. IssuePatchBody published `status` with upstream #5484 and this client's encoder now emits it; close and reopen still carry the lifecycle semantics a status write has nowhere to put — the reason and session under first-close-wins, the done-status normalization, the already-closed idempotence flag — and stay the operations to reach for. " +
"What this member serves is the status moved ALONGSIDE other fields in one transaction, which is the thing two calls cannot do",
SpecRow: "D8 refuse-not-drop",
PinnedBy: patchMemberPin,
},
{
ID: "W-IssuePatch.Assignee", Kind: KindRetired,
What: "assignment and unassignment through update used to refuse",
Why: "RETIRED with W-IssuePatch.Status (ga-7i6by). The EMPTY STRING is the half that makes this member more than a rename: it UNASSIGNS, so a client that skipped an empty value would turn a real edit into no edit at all. " +
"The anti-steal fence around it is the server's and is unchanged — a transfer away from a live foreign in-progress owner still refuses with already_claimed, and the two bypasses (`force_assignee_transfer` and a matched `expected_assignee`) are W-UpdateRequest.ForceAssigneeTransfer and the guard wave's own",
SpecRow: "D8 refuse-not-drop",
PinnedBy: patchMemberPin,
},
{
ID: "W-IssuePatch.Metadata", Kind: KindRetired,
What: "a metadata patch used to refuse",
Why: "RETIRED with W-IssuePatch.Status (ga-7i6by). IssuePatchBody publishes the same replace/merge/set/unset algebra MetadataPatch carries, member for member, so the client projects it rather than translating it and the ordering rule — merge, then set in key order, then unset, with replace refusing beside the other three — stays the ROLE's, applied by the same body a local workspace runs. " +
"The CLEAR is the one state the wire's own struct cannot spell (`omitempty` omits it), which is why the document is built as a map and an empty replacement travels as the empty document. The compare-and-set door is a different question and is served by its own accessor (issues.casMetadata, ga-7i6by's other half)",
SpecRow: "D8 refuse-not-drop",
PinnedBy: patchMemberPin,
},
// Four of these are refused by BOTH patch documents — updateIssue's and
// issues:batchApply's — so one row covers both operations rather than a
// second reason being minted for one fact. Owner is the exception and
// says so: ApplyPatchBody publishes it, and the batch's own encoder
// carries it.
patchRow("SpecID", "a spec-id edit refuses", "neither IssuePatchBody nor ApplyPatchBody publishes spec_id"),
patchRow("AwaitID", "an await-id edit refuses", "neither IssuePatchBody nor ApplyPatchBody publishes await_id"),
patchRow("Owner", "an owner edit refuses ON updateIssue",
"IssuePatchBody excludes owner — which the document itself calls an accident of order rather than a decision, since ApplyPatchBody DOES publish it and issues:batchApply's update item carries it"),
patchRow("ClosedBySession", "a closed-by-session edit refuses", "neither IssuePatchBody nor ApplyPatchBody publishes closed_by_session"),
patchRow("Persistence", "a persistence-mode edit refuses",
"neither body publishes persistence: moving a row between planes mid-plan is a different act from writing its fields"),
{
ID: "W-IssuePatch.ParentID", Kind: KindRetired,
What: "a parent re-hang through update used to refuse",
Why: "RETIRED with W-IssuePatch.Status (ga-7i6by). It is ONE call rather than a remove-then-add pair, which is the whole reason the member exists: the two-call spelling leaves the issue parentless if the second call fails, and dependencies:add/remove — still the general write side of the graph over this wire — cannot express the atomic replacement. " +
"The empty string removes every parent-child edge, so it travels like `assignee`'s empty string rather than being skipped. The graph refusals it earns are the server's and arrive typed: a cycle through the issue's own descendant as the PLAIN dependency_cycle, and an existing edge of another type as dependency_exists",
SpecRow: "D8 refuse-not-drop",
PinnedBy: patchMemberPin,
},
{
ID: "W-CreateBatchRequest.Provenance", Kind: KindRefuse,
Type: tyCreateBatch, Field: "Provenance",
What: "labeling a batch create's history entry refuses",
Why: "batchCreateIssues publishes actor and items only, and the server writes its own label; see W-UpdateRequest.Provenance. It is the one Provenance whose ABSENCE is visible in shipped history — the surface this role serves has always named its source file in the entry (`bd: create 3 issue(s) from plan.md`)",
SpecRow: "D8 row 14 refuse-not-drop",
PinnedBy: batchCreatePin,
},
{
ID: "W-CreateBatchRequest.ForceIDPrefix", Kind: KindRefuse, Flag: "--force",
Type: tyCreateBatch, Field: "ForceIDPrefix",
What: "permitting explicit ids outside the workspace's configured prefix refuses",
Why: "the wire publishes no such member — and could not honor one, since it publishes no explicit id for the flag to permit (W-BatchCreateItem.Issue). Dropping it would answer a request about WHERE ids may be written with a batch whose ids the server chose",
SpecRow: "D8 row 14 refuse-not-drop",
PinnedBy: batchCreatePin,
},
{
ID: "W-BatchCreateItem.Issue", Kind: KindRefuse,
Type: tyBatchCreateItem, Field: "Issue",
What: "an item whose Issue populates any member outside the wire's eight refuses, naming the member",
Why: "apigen.BatchCreateItem carries title, description, design, acceptance_criteria, priority, issue_type, assignee and labels and nothing else, while the role accepts far more of a types.Issue: an explicit id, the wisp flags, metadata, the storage class, every timestamp, the gate/molecule/event fields. " +
"ONE row rather than one per member because the reason is one reason — the wire's item vocabulary — and forty rows repeating it would say nothing a reader does not learn here. Exhaustiveness is held by REFLECTION instead: the client's carried and role-ignored tables are checked against types.Issue field by field, so a member added upstream is refused the day it lands rather than dropped until someone notices. " +
"The members the role ITSELF ignores on a create (ContentHash, RowVersion, lease, compaction, routing overrides, hydration flags) are not in this population and are not refused: a local create drops them too",
SpecRow: "D8 row 14 refuse-not-drop",
PinnedBy: batchCreatePin,
},
// The three edge rows are BATCH-CREATE's, and the qualifier is
// load-bearing now that a second operation writes the same shape:
// createIssue's own edge publishes `reverse` and `metadata` (its issue
// HAS an id for a target to point back at, which a batch item does
// not), so the client sends both there. Only ThreadID is refused on
// both, because no operation publishes a thread member.
createDependencyRow("Reverse", "an edge written from the target back to the new issue refuses ON A BATCH CREATE",
"BatchCreateDependency carries target_id and type only; dropping Reverse would write the edge in the OPPOSITE direction from the one asked for, which is a different graph. createIssue's CreateIssueDependency DOES publish it, and the single-create path sends it"),
createDependencyRow("Metadata", "typed edge metadata refuses ON A BATCH CREATE",
"BatchCreateDependency publishes no metadata member, and a waits-for gate whose metadata was dropped is a readiness rule that silently does not hold. createIssue's edge publishes it, and the single-create path sends it verbatim"),
createDependencyRow("ThreadID", "associating an edge with a discussion thread refuses",
"neither BatchCreateDependency nor CreateIssueDependency publishes a thread member"),
{
ID: "W-CreateRequest.IDPrefix", Kind: KindRefuse,
Type: tyCreateRequest, Field: "IDPrefix",
What: "overriding the prefix an explicit id is checked against refuses",
Why: "createIssue publishes no `id_prefix`, and the omission is the SERVER's decision rather than a gap (internal/httpapi/create.go): the field exists because a workspace's own config.yaml prefix wins over the database's and only a local front door can read that file, so a remote caller's config.yaml describes a workspace this server does not serve. " +
"Publishing it would let a caller override the served workspace's prefix rule from outside it. Dropping it instead would check the id against the SERVER's prefix while the caller believed it was checked against theirs — the same request, two different answers to 'may this workspace mint this id'",
SpecRow: "D8 row 16 refuse-not-drop",
PinnedBy: createPin,
},
{
ID: "W-CreateRequest.Issue", Kind: KindRefuse,
Type: tyCreateRequest, Field: "Issue",
What: "a create whose Issue populates any member outside the wire's twenty refuses, naming the member",
Why: "createIssue publishes the whole create VOCABULARY — id, title, description, design, acceptance_criteria, notes, status, issue_type, priority, assignee, owner, estimated_minutes, external_ref, due_at, defer_until, sender, metadata, labels, ephemeral, no_history — and deliberately not the rest of a types.Issue: the creation stamp (created_at, created_by), because a caller-supplied creation time makes the row disagree with the journal entry that records it and re-dating history is what an import is for; and spec_id, await_*, mol_type, wisp_type, work_type, storage_class, source_*, pinned, is_template and the event quartet, which this surface publishes on no operation, read or write. " +
"ONE row rather than one per member for W-BatchCreateItem.Issue's reason — the reason is one reason — and exhaustiveness is held by the same REFLECTION over types.Issue, sharing the role-ignored table with the batch so the two operations cannot disagree about what the ROLE drops. " +
"Issue.Comments and Issue.Dependencies are not in this population: the role itself refuses them, so a local create fails too and this is validation rather than divergence",
SpecRow: "D8 row 16 refuse-not-drop",
PinnedBy: createPin,
},
{
ID: "L-create-notfound", Kind: KindDegrade,
What: "a create whose dependency or waits-for target names no row refuses as issueops.ErrValidation ALONE — not as ErrValidation wrapping ErrNotFound — and does not name the target",
Why: "the wire answers a dangling target with a 400 invalid_argument naming `dependencies` and a FIXED detail (internal/httpapi's failCreateIssue), which deliberately does not quote the role's own message: that message arrives as a driver error naming tables and constraints, and 4xx details on this surface reflect the caller's own input back rather than server internals. " +
"The refusal still fails the whole request and creates NOTHING — the promise the row is about — and only the second sentinel and the target's name are lost. It is batchCreateIssues' L-batchcreate-notfound on the single create, and it retires the same way: an upstream code that distinguishes the absent-target refusal and carries the target. " +
"A missing --parent target already retired out of this row: failCreateIssue's errors.As(&parentNotFound) arm answers it with a distinguishing 404 not_found that names the target, and the client maps that to issueops.ErrNotFound (see TestServedCreateRefusesAnAbsentParentAsNotFound) — the row now covers only dependency and waits-for targets",
SpecRow: "D8 row 16",
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L-create-prefix", Kind: KindDegrade,
What: "an unforced explicit id outside the workspace's configured prefix refuses as issueops.ErrValidation rather than as storage.ErrPrefixMismatch",
Why: "the wire spells that refusal as a 400 invalid_argument with `param: \"id\"` and `reason: invalid_value` (internal/httpapi's failCreateIssue), which is the SAME pair a malformed or oversized `id` earns — so nothing on the wire tells the two apart, and reconstructing the typed sentinel from the pair would misclassify every other refusal of that member. " +
"The guard itself is untouched: the id is refused, nothing is created, and the detail names `force_id_prefix` as the bypass, which is the recovery a caller needs. What is lost is the errors.Is arm both local front doors use to decide whether to re-offer the create with --force. Upstream ask: a prefix_mismatch code, or a reason that distinguishes it, which retires this row",
SpecRow: "D8 row 16",
PinnedBy: pinnedByS3Conformance,
},
// The issues:batchApply population, from client wave ga-mijra. It is
// SMALL, and that is the operation rather than an oversight: the create
// item publishes createIssue's whole twenty, the close item maps whole,
// the edge item maps whole, and the update item's patch is WIDER than
// updateIssue's in the two places that matter to a plan (a full label
// patch, and `owner`). What is left is one patch member and two facts
// about the RESULT.
{
ID: "W-CreateItem.Issue", Kind: KindRefuse,
Type: tyApplyCreateItem, Field: "Issue",
What: "a create ITEM whose Issue populates any member outside the wire's twenty refuses, naming the member",
Why: "ApplyCreateItem publishes exactly createIssue's create vocabulary — id, title, description, design, acceptance_criteria, notes, status, issue_type, priority, assignee, owner, estimated_minutes, external_ref, due_at, defer_until, sender, metadata, labels, ephemeral, no_history — and deliberately not the rest of a types.Issue, for the reasons W-CreateRequest.Issue gives in full. " +
"It is a row of its OWN rather than a citation of that one because the operations are different: a caller auditing why their PLAN refuses must not be sent to a row about a single create, and the two can diverge the day either vocabulary moves. The partition itself is SHARED — one carried table, one role-ignored table, held against types.Issue by the same reflection — so they cannot disagree about what the wire carries or about what the role drops. " +
"Issue.Comments and Issue.Dependencies are not in this population and are refused as validation on both sides: edges in this role are ITEMS, so a create item has nowhere to put one at all",
SpecRow: "D8 refuse-not-drop",
PinnedBy: applyPin,
},
{
ID: "W-ApplyPatch.ParentID", Kind: KindRefuse,
Type: tyIssuePatch, Field: "ParentID",
What: "a parent re-hang inside an update ITEM refuses, where the same member serves on updateIssue",
Why: "ApplyPatchBody deliberately publishes no parent_id, and the absence is this operation's ONE-EDGE-ONE-SPELLING rule rather than a gap: a parent is a dep_add item of type parent-child, so the ORDER of every edge in a plan stays total and there is exactly one place an edge is written. " +
"The single patch has no ordering to express and publishes the member directly (W-IssuePatch.ParentID, retired by client wave ga-7i6by), which is why the same Go field is carried by one document and refused by the other. " +
"Refusing is not a loss of capability, only of spelling: a plan re-hangs a parent with a dep_add item, which is the atomic replacement in the position the caller declared it",
SpecRow: "D8 refuse-not-drop",
PinnedBy: applyPin,
},
{
ID: "L-apply-snapshot", Kind: KindDegrade,
What: "every ItemResult of a batch apply comes back with Issue nil, where a local backend hydrates a post-item snapshot",
Why: "the WIRE result is lean by the document's own decision and the role's leaf says why: ApplyItemResult carries ids, `changed` and `revision` and no issue, because the Go contract carries the snapshot for its COMPLETION HOOKS — which hand a script the row they are telling it about — and hooks never fire on the http surface at all. A hundred hydrated issues with their labels and edges would be a response an order of magnitude larger than the request that produced it. " +
"What a caller loses is a read it can make: the ids ARE published, per item and through Keys, so the rows are one getIssue away and the plan's next step is composed from ids rather than from snapshots. It is a degradation rather than a refusal because nothing about the WRITE differs — every item landed exactly as asked — and refusing would make the whole operation unavailable over http to keep a member no consumer on this surface can use",
SpecRow: "D8 refuse-not-drop (result half)",
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L-apply-ref", Kind: KindDegrade,
What: "an unresolvable metadata_refs key comes back as a *RefError naming the MEMBER rather than the key, and the reconstructed error replaces the server's problem envelope",
Why: "the wire's 400 names the offending member in `param` — `items[3].create.metadata_refs` — and carries the item index, the item's key and `declared_later`, but not WHICH entry of the refs map failed: the role's RefError.Member is diagnostic prose (`metadata_ref <key>`) rather than a vocabulary, so the server maps it onto the document's own member names instead of publishing it. The two ADDRESSING refs, target and source, are named exactly. " +
"The envelope is dropped because issueops.RefError has nowhere to put it: its Unwrap is hardcoded to ErrValidation and it carries no member for a cause, which is the role type's shape rather than a choice made here. The discriminator a caller ACTS on — an ordering mistake against a typo — survives whole, in both polarities. Upstream ask: a typed ref-key member on the problem document, which retires this row",
SpecRow: "D8 refuse-not-drop (result half)",
PinnedBy: pinnedByS3Conformance,
},
{
// The COMMENT population, from client wave ga-f352s, and it is the
// one divergence on that role: the request maps member for member,
// so nothing refuses on shape and there is no W- row.
ID: "L-comment-author", Kind: KindDegrade,
What: "a comment's AUTHOR is subject to the server's own actor rule, which no local leg applies: it is stored TRIMMED where a local backend stores it verbatim, and one carrying a control character is refused (issueops.ErrValidation) where a local backend stores it",
Why: "the operation validates `author` with the `actor` rules whole (internal/httpapi's validateNameMember: trim, refuse empty, refuse past 256 bytes or 255 characters, refuse any control rune) and passes the TRIMMED value on to the role, while issueops.ValidateAddCommentRequest checks only that the field is non-empty and stores what it was given. So the same request produces a different STORED VALUE on the two legs, and a value one leg stores the other refuses. " +
"IT IS THE SERVER'S RULE AND THE DOCUMENT PUBLISHES IT, which is why this is a ledger row rather than a bug on either side: the schema states the trim and the character rule in as many words, and the reason is the column — `author` is 255 characters wide and every renderer of the thread prints it, where an unfiltered C1 introducer is an escape-sequence payload. The refusal half is a NARROWING the wire makes on purpose. " +
"THE CLIENT DOES NOT ANTICIPATE EITHER HALF, and that is the decision this row records. Trimming here would make the client agree with the server about the stored value and disagree with the role's own contract — and it would silently rewrite a caller's request, which is the one thing this seam never does. Refusing the control rune here would be a second copy of a server rule that is free to move. So the value travels as the caller wrote it and the server's answer is reported unchanged, which keeps the divergence visible instead of laundering it. " +
"IT IS A DEGRADE RATHER THAN A REFUSE because the ordinary path PROCEEDS: a well-formed author is stored, and the difference cannot be misread as a wider or narrower answer — a comment lands on the thread the caller named either way. The refusal half is the SERVER's, not this client's refuse-not-drop, which is what KindRefuse classifies. " +
"What a caller loses is an author whose surrounding space survives, and the recovery is the one the role's own contract already implies: compose the author from a value you would be willing to see printed. Upstream ask: either the role trimming its own author on every leg, or the operation storing it verbatim — the rows agree the day the two rules become one",
SpecRow: "D8 row 19",
PinnedBy: pinnedByS3Conformance,
},
{
// The RELEASE population, from client wave ga-f352s, and it has
// exactly one row. releaseIssue's request maps member for member —
// actor, the guard, force and the path — so nothing refuses on
// shape; what diverges is one REFUSAL VOCABULARY, which is the same
// shape as the two create parks and retires the same way.
ID: "L-release-notclaimed", Kind: KindDegrade,
What: "a release of a row that holds NO CLAIM answers issueops.ErrNotReleasable rather than issueops.ErrNotClaimed; a status that will not accept a release answers ErrNotReleasable as it does everywhere",
Why: "the role splits the two — ErrNotClaimed for a row nobody holds, ErrNotReleasable for a status the transition is not defined over — and the wire spells BOTH `not_releasable` under one code, with no member telling them apart. That is the server's deliberate choice (internal/httpapi's CodeNotReleasable) rather than an omission, and its detail names both conditions instead of guessing between them. " +
"So this client maps to the WIDER of the two, which is the only honest read: reconstructing ErrNotClaimed would assert a fact about the row that the wire never sent, and scraping the detail for it would bind a sentinel to prose. " +
"NOTHING ELSE ABOUT THE REFUSAL MOVES — nothing is written, the row and its version are untouched, and the conditional path is unaffected: a caller that named a holder gets ErrAssigneeMismatch on both sides, because that refusal has a code of its own. " +
"The caller who loses something is the one that told 'I already released this' from 'the row was never claimed', and the recovery is the one the server's own detail prescribes: READ THE ROW rather than retrying blind. Upstream ask: a code, or a member, that distinguishes the unheld row from the unreleasable status — which retires this row",
SpecRow: "D8 (Releaser), D9",
PinnedBy: pinnedByS3Conformance,
},
{
ID: "L-release-notowner", Kind: KindDegrade,
What: "an unforced, unconditional release by an actor that is NOT the holder answers issueops.ErrAlreadyClaimed — carrying *issueops.ClaimConflictError — rather than issueops.ErrNotOwner",
Why: "the wire answers the ownership fence with `already_claimed`, which is the code updateIssue already gives the same situation (a live foreign owner refusing a write, with a force bypass and a name-the-holder bypass), and this client maps that code to the sentinel every other operation means by it. The two sentinels are distinct values in issueops and neither wraps the other, so the arm a caller writes differs. " +
"REPORTING IT AS ErrNotOwner WOULD BE THE WORSE TRADE, not merely a different one: the code is shared with the claim refusals, so a client that special-cased it for this operation would be reading the OPERATION to decide the sentinel rather than the code — and would then answer ErrNotOwner for a genuine already_claimed the day the server reuses the code here for anything else. " +
"WHAT SURVIVES IS EVERYTHING A CALLER ACTS ON: the refusal is typed, it names the row (the request supplied the id the wire leaves out), nothing is written, and BOTH bypasses answer exactly as the role says — force releases the foreign claim, and naming the holder in expected_assignee releases it too, because a match replaces the fence. The wire deliberately sends no `assignee` member here, so the holder is not named: absence means 're-read the row', never 'nobody holds it'. Upstream ask: a code, or a member, that separates the release's fence from a claim conflict — which retires this row",
SpecRow: "D8 (Releaser), D9",
PinnedBy: pinnedByS3Conformance,
},
{
ID: "W-IssuePatch.Labels", Kind: KindRetired,
Type: tyIssuePatch, Field: "Labels",
What: "RETIRED — the whole ordered label edit crosses: `labels` replaces, `add_labels` adds, `remove_labels` removes",
Why: "upstream #5510 published add_labels and remove_labels on IssuePatchBody and client wave ga-jpywb emits both, which is the retirement path this row named. " +
"The three travel as FLAT siblings where applyBatch nests them under one object, and the server assembles all three into ONE issueops.LabelPatch — so the algebra the role states (replace, then add, then remove; removal wins) is applied server-side and is never this client's to arrange. " +
"WHAT THE REFUSAL WAS PROTECTING is worth keeping after the refusal is gone: degrading an incremental edit onto the replace-only member would have meant reading the set, adding to it and writing it back, which silently drops any label another writer added in between. `bd label add` and every agent that tags work concurrently are exactly that caller, so the refusal was right for as long as the members did not exist — and it is the members that retire it, not a change of mind about the read-modify-write",
SpecRow: "D8 refuse-not-drop, open questions (tracked-refusal roadmap)",
PinnedBy: pinnedByS3Conformance,
},
{
// The CONFIG-WRITE population, from client wave ga-jpywb, and it has
// exactly one row. Both verbs map member for member — a key in the
// path, a value in the body, nothing else — so nothing refuses on
// shape; what diverges is a pair of EDGE BOUNDS the wire applies
// and no local leg does.
ID: "L-config-bounds", Kind: KindDegrade,
What: "a setting VALUE past types.MaxTextBytes bytes, and a setting KEY past types.MaxFieldLen characters on the WRITE, are refused with issueops.ErrValidation naming the member; on a local leg the same request reaches the column and fails with the engine's own `too large for column` error, which is no sentinel at all",
Why: "the bound belongs to the OPERATION rather than to the role: internal/httpapi's settingWriteKey and settingValue check both before the role is called, because a request the caller could have fixed should be a 400 naming the member rather than the 500 a column overflow would otherwise produce. workapi.ValidateSettingWrite — the rule every leg shares — applies no length bound at all, so below the wire the column is the only check there is. " +
"MEASURED, not inferred: a 65536-byte value answers `400 invalid_argument: \\`value\\` is 65536 bytes; storage holds at most 65535` over http and `Error 1105: string ... is too large for column 'value'` on the embedded leg, and a 306-character key splits the same way. Exactly 65535 bytes is accepted on both. " +
"THIS CLIENT RESTATES NEITHER BOUND, and that is the decision this row records. They are the SERVER's policy on a value whose shape the role accepted, one release away from moving, so a second copy here would either drift or refuse a request a newer server would take — the same argument L-comment-author makes about the author rule, and the same posture. What travels back is the operation's own 400, which the problem mapper turns into ErrValidation. " +
"IT IS A DEGRADE RATHER THAN A REFUSE because the ordinary path PROCEEDS and because the divergence runs in the CALLER'S FAVOR: over http an oversized write is a typed, member-named refusal that wrote nothing, where a local leg hands back a driver error no caller can classify. What a caller loses is nothing; what a caller must not assume is that a value a local workspace stored will store here. " +
"THE TWO BOUNDS ARE NOT SYMMETRIC ACROSS THE VERBS, and the asymmetry is the operation's: DELETE checks only that the key names something, so removing a 306-character key succeeds over http exactly as it does locally. Upstream ask: the length rules moving onto the shared validator, which retires this row by making the two legs one",
SpecRow: "D8 row 11, D9",
PinnedBy: pinnedByS3Conformance,
},
{
// The UPDATE-BOUNDS row, and L-config-bounds' sibling one operation
// over. It is not the same row because the two are not the same
// situation: there the role applies no length rule at all and the
// column is the only check below the wire, HERE THE ROLE APPLIES THE
// SAME RULE with the same constant — so what is lost is a sentinel
// rather than a bound.
ID: "L-update-fieldlen", Kind: KindDegrade,
What: "an updateIssue patch member past types.MaxFieldLen characters — a label on any of the three label members, `title`, `external_ref` — is refused with issueops.ErrValidation naming the member; on a local leg the same request answers types.ErrFieldTooLong",
Why: "the bound is applied TWICE and identically: internal/httpapi/update.go checks types.CheckFieldLen at the edge before the role is called, and internal/storage/issueops applies the same function below it. So this is a classification divergence and not a policy one — a value one leg stores the other stores, and a value one leg refuses the other refuses. " +
"WHAT COARSENS IT is the spelling: the operation refuses with `invalid_argument` and reason `invalid_value` (internal/httpapi's refuse on the patch member), which is the SAME pair a malformed status, an unparseable timestamp or any other bad value on the same member earns. Nothing on the wire tells them apart, so reconstructing ErrFieldTooLong from the pair would misclassify every other refusal of that member — the argument L-create-prefix makes about the id, on the patch. " +
"MEASURED, not inferred: a 256-character label answers `400 invalid_argument: \\`add_labels[0]\\` is 256 characters; storage holds at most 255` over http and ErrFieldTooLong through the reference store's own Lifecycle role, and exactly 255 characters is accepted on both. " +
"THIS CLIENT RESTATES THE BOUND NOWHERE, and the reason differs from L-config-bounds': not that the rule is the server's to move, but that a second copy of a rule two layers already apply is a third place for it to drift. What travels back is the operation's own 400. " +
"IT IS A DEGRADE RATHER THAN A REFUSE because the path PROCEEDS and the outcome is identical on both legs — the request fails, the row is untouched, and no truncated value is stored — while the detail names the offending member and its length, which is the recovery a caller needs. What is lost is the errors.Is arm a caller writes to tell 'too long' from 'malformed'. Upstream ask: a `too_long` reason, or a code of its own, which retires this row",
SpecRow: "D8 row 16, D9",
PinnedBy: pinnedByS3Conformance,
},
{
// The EVENTS-JOURNAL population, from client wave ga-jpywb, and it
// has exactly one row. The read maps member for member — a
// checkpoint, a bound, a page of records and a head — and the typed
// truncation crosses whole through the problem document's three
// window members. What diverges is the one promise a PAGED transport
// cannot make about an UNPAGED read.
ID: "L-events-paging", Kind: KindDegrade,
What: "an UNCAPPED journal read (limit 0) is served as a loop of handler-sized requests rather than one, so its rows and its head no longer come from a single instant; a bounded read is one request and is unaffected",
Why: "the role imposes no ceiling of its own — journalops.Journal says a limit of 0 means uncapped, because the caller that pages a hundred thousand records out to a file is as legitimate as the one polling for ten — and the OPERATION refuses `limit=0` by value, capping a page at 10000 (internal/httpapi's maxEventsLimit). That cap is the handler's promise to its clients rather than a narrowing of the role, and this client is on the other side of it. " +
"SO THE LOOP IS THE ONLY HONEST READING. Refusing an uncapped read would refuse something the role permits; capping one silently at 10000 would answer a partial page beside a head saying there is more, which is a consumer stalling on a gap nobody told it about. Both are worse than N transactions. " +
"WHAT SURVIVES IS WHAT A CONSUMER ACTS ON: rows stay contiguous and seq-ascending, because each page continues exactly where the last ended; the head is the LAST page's, so it is the freshest and can only be at or ahead of the last row served; and a truncation on any page is the whole read's failure, never a shorter answer — a loop that returned the prefix it had already gathered would answer a gap with a plausible-looking suffix, which is the one failure a replay feed must never ship. " +
"WHAT DOES NOT SURVIVE is atomicity across the whole answer: a mutation committing mid-loop appears in a later page of the SAME call rather than in the next one. A consumer cannot observe that as a gap or a duplicate — it reads as records it would have received on its next poll, arriving early — which is why this is a degrade rather than a refusal. " +
"IT IS A DEGRADE RATHER THAN A REFUSE for the ordinary reason too: the path proceeds, and the answer cannot be misread as narrower or wider than the caller asked for. Upstream ask: an unlimited spelling on the operation, or a cursor the page can hand back — either retires this row",
SpecRow: "D8 (Journal), D9",
PinnedBy: pinnedByS3Conformance,
},
}
}
// batchCreatePin is the one sweep behind every batch-create refusal row: it
// drives each excluded member one at a time and asserts the call fails WITHOUT
// dialing, and it holds the carried/ignored partition against types.Issue by
// reflection so the population cannot go stale by omission.
const batchCreatePin = pinnedByS3Conformance
// createPin is the single-create counterpart: the same shape of sweep, driving
// every excluded member of a CreateRequest one at a time and asserting the call
// fails WITHOUT dialing, with the carried/ignored partition held against
// types.Issue by reflection.
const createPin = pinnedByS3Conformance
func createDependencyRow(field, what, why string) Row {
return Row{
ID: "W-CreateDependency." + field, Kind: KindRefuse,
Type: tyCreateDep, Field: field,
What: what,
Why: why + " (internal/httpapi/spec BatchCreateDependency)",
SpecRow: "D8 row 14 refuse-not-drop",
PinnedBy: batchCreatePin,
}
}
// applyPin is the sweep behind every batch-apply refusal row: it drives each
// excluded member one at a time and asserts the call fails WITHOUT dialing,
// with the create item's carried/ignored partition held against types.Issue by
// the same reflection the two other create paths use.
const applyPin = pinnedByS3Conformance
// patchMemberPin is the round trip behind the four patch members client wave
// ga-7i6by carries: it drives each one into the document the role builds and
// reads it back off the transport, which is the one thing about this operation
// no result can show.
const patchMemberPin = pinnedByS3Conformance
func patchRow(field, what, why string) Row {
return Row{
ID: "W-IssuePatch." + field, Kind: KindRefuse,
Type: tyIssuePatch, Field: field,
What: what,
Why: why + " (internal/httpapi/update.go issuePatchMembers)",
SpecRow: "D8 refuse-not-drop",
PinnedBy: pinnedByS3Conformance,
}
}
// commandRows are D7's named members of the refused class that carry no request
// field: whole commands and the flag modes of served commands.
func commandRows() []Row {
// The cmd/bd wiring landed. Two pins, split the way the mechanism is: a
// whole command is early-refused from the classification table and every
// entry in it is driven against the REAL cobra tree, while a served
// command's refused flag mode is a per-flag invocation.
const refusedCommand = pinnedByS3Conformance
const refusedFlagMode = pinnedByS3Conformance
// Every row this helper builds cites D7 and nothing else: D7 IS the
// whole-command-and-flag-mode decision, and a row citing a second decision
// is a row that wants writing out in full (F-count and F-close both do).
row := func(id, command, flag, what, why string) Row {
pinned := refusedCommand
if flag != "" {
pinned = refusedFlagMode
}
return Row{ID: id, Kind: KindRefuse, Command: command, Flag: flag, What: what, Why: why, SpecRow: "D7", PinnedBy: pinned}
}
return []Row{
row("F-ready-explain", "ready", "--explain", "`bd ready --explain` refuses",
"it dispatches onto raw GetBlockedIssues/GetIssuesByIDs/GetDependencyCounts/DetectCycles, three of which are on the unsupported allowlist"),
row("F-ready-mol", "ready", "--mol", "`bd ready --mol` refuses",
"its molecule subgraph load reaches findHierarchicalChildren, an IDPrefix SearchIssues shape the parent-walk bridge cannot express (E-IssueFilter.noShape). GetDependencyRecords and GetDependentsWithMetadata, which the same load also calls, stopped being the blocker when ga-b8ddd.30 flipped them onto the wire"),
row("F-ready-gated", "ready", "--gated", "`bd ready --gated` refuses",
"it dispatches onto a filtered SearchIssues shape the bridge cannot express, plus GetDependents"),
row("F-show-thread", "show", "--thread", "`bd show --thread` refuses",
"showMessageThread renders each reply's sender, recipient, body and timestamp off GetDependentsWithMetadata, but ga-b8ddd.30 flipped that read onto getIssue's include_dependents parameter, which carries the collectDependents SHALLOW projection (id/status/type/priority/title + edge type only, be-4d36f2). Those fields come back zeroed over http and zero-timestamp replies sort ahead of the root — a silent-wrong degrade the refuse-over-degrade doctrine forbids. Retires with a full-dependent wire shape, a server-side ask"),
row("F-show-refs", "show", "--refs", "`bd show --refs` refuses",
"showIssueRefs's --json marshals the full GetDependentsWithMetadata rows, but the wire answers the same collectDependents shallow projection, so created_at/assignee/description come back zeroed and the JSON differs from a local workspace. The text render consumes only the shallow fields, but the flag cannot be split from its --json mode, so the whole flag refuses rather than serve a divergent JSON silently"),
row("F-show-children", "show", "--children", "`bd show --children` refuses",
"showIssueChildren's --json marshals the full GetDependentsWithMetadata rows, the same collectDependents shallow projection as --refs, so created_at/assignee/description come back zeroed over http; `bd children` refuses as a whole command for the same reason"),
row("F-mol-ready", "mol ready", "", "`bd mol ready` refuses",
"it is the same runMolReadyGatedCore body as `bd ready --gated`"),
row("F-blocked", "blocked", "", "`bd blocked` refuses",
"it is raw GetBlockedIssues, which is on the unsupported allowlist"),
{
ID: "F-count", Kind: KindRetired, Command: "count",
What: "RETIRED — `bd count` is SERVED whole",
Why: "it said the command refuses because \"issueops.Counter has no wire operation; a counts operation is a filed upstream ask\", and that ask was DELIVERED: upstream #5508 published countIssues, client wave ga-icks1 wired the Counter accessor, and `count` moved from httpRefusedCommands into httpServedCommands. D8 row 20 and docs/reference/http-workspaces.md have said so since; this row was the last place that did not. " +
"Every flag the command publishes reaches a wire member — the whole predicate, the six instant bounds, the three emptiness checks, --include-infra, and the five --by-* flags as the one group_by parameter — so there is no refused mode left to name either. " +
"HOW IT ROTTED IS THE PART WORTH KEEPING. Its pin was TestClassifiedRefusedCommandsRefuseBeforeTheOSSPreRun, which walks httpRefusedCommands and drives every entry. The moment `count` left that table the pin stopped covering this row — it stayed LIVE BY NAME, so the well-formedness gate that resolves PinnedBy to a real test kept passing, and DEAD BY COVERAGE, so nothing anywhere asserted the row's claim. A ledger row can be false for a whole wave under a green pin, which is what TestFRowsAgreeWithTheCommandClassification now makes impossible",
SpecRow: "D7 (RETIRED), D8 row 20",
// The retirement's own evidence: the corpus replay compares `bd
// count`'s answer byte-for-byte over http against the same command
// over a local Dolt workspace, and a count's whole answer is a
// number — a predicate narrowed or widened on the way out prints a
// different integer and nothing else differs.
PinnedBy: pinnedByS3Conformance,
},
row("F-serve", "serve", "", "`bd serve` refuses against an http workspace",
"the OSS classifier would happily serve it from the opened store, and a bd serve re-serving a remote bd serve is a proxy chain nobody designed: run serve where the database is"),
{
ID: "F-close", Kind: KindRefuse, Command: "close", Capability: "issues.batchClose",
What: "`bd close` is SERVED whole — single id, several ids and --claim-next — over issues:batchClose; it refuses only against a DOWN-LEVEL server that does not advertise issues.batchClose",
Why: "the CLI's close front door routes every id, single-id included, through BatchCloser.CloseBatch, and Lifecycle.Close has zero CLI callers at tip. The wire now carries issues:batchClose, so the whole CloseBatchRequest — multi-item and the atomic ClaimNext included — is one wire call and one server-side transaction; nothing is composed or refused where the capability is present. " +
"Against a server too old to advertise issues.batchClose, servesBatchClose() reads the handshake snapshot and routes around the batch dial entirely, so no Preflight runs and no wire.ErrCapabilityAbsent is raised: the down-level leg's refuseUnservedCloseShape raises the STORE's own *ErrHTTPUnsupported (batchcloser.go), and cmd/bd's renderEscapedHTTPRefusal turns it into the capability-absent taxonomy (case 2) by scanning the served command's own capability list for the first token the server does not advertise — issues.batchClose, which is the token it then names to upgrade to. The single-item, no-ClaimNext shape still composes onto closeIssue in that down-level leg (see L18); the shapes that cannot compose refuse there. The item cap is L-close-cap",
SpecRow: "D8 row 17 (resolved, Wire), D9 L18, D9 L-close-cap",
// The command is served; the down-level refusal is the capability gate's,
// exercised against a server without issues.batchClose.
PinnedBy: refusedFlagMode,
},
{
ID: "F-partial-id", Kind: KindRefuse,
What: "partial-id resolution refuses with its own taxonomy text",
Why: "SearchIssueIDs has no wire operation, and the client cannot tell a partial id from a full id that does not exist — so the refusal text covers both outcomes rather than falling through to a raw search error",
SpecRow: "D11",
PinnedBy: pinnedByS3Conformance,
},
}
}