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

456 lines
33 KiB
Go

// Contributed by gascity from bd-enterprise (internal/enterprise/httpstore/encode/ledger_fields.go@49d1df2f6)
// to OSS beads under the MIT license.
package encode
import "reflect"
// The per-field half of divergence ledger v1: one row for every request-shape
// field this package's encoder cannot put on the v0 wire, plus the two it
// deliberately drops.
//
// These are instances of L12 — "an inexpressible filter refuses, never drops" —
// enumerated one field at a time, because a class rule that is not enumerated
// is a rule nothing can check. The bijection gate reads them back against
// reflection over the same structs, so a field added upstream lands here or
// fails CI.
const (
fieldSpec = "D9 L12, D7, D8"
// fieldPin and dropPin are the same test because it is the same property:
// the sweep populates one field at a time and asserts the behavior the
// table declares, so a refusal that stopped refusing and a drop that
// started sending both fail there.
fieldPin = "TestEncoderHonorsEveryTableDisposition"
dropPin = "TestEncoderHonorsEveryTableDisposition"
dropSpec = "D9 (a degradation not in this table is a bug)"
noWireList = "listIssues publishes no such parameter (internal/httpapi/reads.go handleListIssues; internal/httpapi/spec/openapi.v0.yaml)"
)
// briefRetiredWhy is the one retirement story behind the three rows #5586's
// `brief` parameter retired — the ready listing's, the issue listing's, and the
// ready bridge's Lite, which workapi assigns to the same field.
//
// IT IS A CONSTANT BECAUSE IT WAS THREE COPIES, and the three drifted the way
// copies do: the closing sentence stayed true of the WIRE and false of the
// CALLER for a whole wave, in triplicate, and correcting it meant finding all
// three. One string is one thing to keep true.
const briefRetiredWhy = "upstream #5586 published `brief` on GET /v0/beads/ready and GET /v0/beads/issues, which is the retirement path this row named. " +
"Both page encoders send the parameter now — readyTable, listTable and the ready bridge all map it — so the client asks for the projection it was handed and the server leaves the text columns unselected. " +
"The COUNT keeps the drop under E-ReadyRequest.Brief@countReadyWork, because countReadyWork publishes no such parameter and a cardinality has no rows to project. " +
"WHAT DID NOT RETIRE WITH IT IS THE WIRE HALF OF THE MARKER, and only that half: types.Issue.IsLitePartial is `json:\"-\"` and never crosses, so a projected page arrives on the transport byte-identical to a page of genuinely textless rows — the same absence getIssue's brief_deps carries, deferred upstream by #5549. " +
"THE CALLER-VISIBLE AMBIGUITY IS CLOSED, by client wave ga-f352s: `brief` is a parameter to the page decode rather than a field on anything, so httpReader hands it to wireRows (role_reader.go) and this client stamps IsLitePartial on every row of a page it ASKED to be projected — which is precisely what issueops.ListRequest.Brief's own leaf says a wire consumer distinguishes the two by — and never on a hydrated one. `bd list --long --brief` therefore prints \"Description: (omitted by --brief)\" over http exactly as it does locally, and TestHTTPCommentAndBriefRenderEndToEnd pins that line through the real binary"
func refusal(id string, ty reflect.Type, field, what, why, spec string) Row {
return Row{
ID: id, Kind: KindRefuse,
Type: ty, Field: field,
What: what, Why: why, SpecRow: spec, PinnedBy: fieldPin,
}
}
// readyRequestRows are the ready vocabulary's two inexpressible members.
//
// [Removed: a third row, "E-ReadyRequest.ExcludeIDs", stood here for an
// enterprise-only id-exclusion filter. issueops.ReadyRequest carries no
// ExcludeIDs member in OSS (issueops/reader.go), so the row named a struct
// field that does not exist and TestEncoderTableClassifiesEveryRequestField
// failed "names a field that does not exist" against it. The matching table.go
// entry in readyFilterEntries() was removed alongside this row. The separate,
// still-real "E-WorkFilter.ExcludeIDs" row below (workFilterBridgeRows) is
// unaffected: workapi.WorkFilter genuinely carries that field.]
func readyRequestRows() []Row {
return []Row{
refusal("E-ReadyRequest.MolType", tyReadyRequest, "MolType",
"a molecule-type restriction on ready work refuses",
"neither listReadyWork nor countReadyWork publishes a mol-type parameter, and the ready query applies molecule typing inside — so a dropped restriction would answer with the wider set of every molecule type",
fieldSpec),
refusal("E-ReadyRequest.Offset", tyReadyRequest, "Offset",
"a non-zero Offset on ready work refuses",
"the wire publishes no offset parameter, and the store-backed role refuses a non-zero Offset itself with a typed *ErrUnsupported. A ready request carries no keyset position, so there is no portable way to page ready work at all — a caller that must page pages a ListRequest instead",
fieldSpec+", D12"),
{
ID: "E-ReadyRequest.Brief", Kind: KindRetired,
What: "RETIRED — the ready listing SENDS the projection; only the count still drops it",
Why: briefRetiredWhy,
SpecRow: dropSpec,
PinnedBy: dropPin,
},
{
// The count's half of the retired row above, and it is a separate
// row rather than a narrowing of that one because the two answer
// different operations: countReadyWork publishes no `brief` at all,
// so its drop survives the parameter that retired the listing's.
ID: "E-ReadyRequest.Brief@countReadyWork", Kind: KindDegrade,
Type: tyReadyRequest, Field: "Brief",
What: "the free-form-text projection is DROPPED on the COUNT, not refused: a cardinality has no rows to project",
Why: briefCountDropWhy,
SpecRow: dropSpec,
PinnedBy: dropPin,
},
{
ID: "E-ReadyRequest.Limit@countReadyWork", Kind: KindRefuse,
Type: tyReadyRequest, Field: "Limit",
What: "a Limit on a ready COUNT refuses",
Why: "countReadyWork publishes no limit parameter and ReadyCounter.CountReady refuses one itself: a cardinality has no page, and CountReady's identity with the listing it sizes stops being true the moment one is accepted. " +
"An explicit zero is refused with the rest — an unlimited count is the only kind there is",
SpecRow: fieldSpec + ", D8 row 2",
PinnedBy: fieldPin,
},
}
}
// listRequestRows are the listing vocabulary's inexpressible members. It is the
// longest population in the ledger, and deliberately so: `bd list` publishes
// far more filters than the v0 listing does, and every one of them is a set
// this client would widen if it dropped it.
func listRequestRows() []Row {
listRefusal := func(field, what, why string) Row {
return refusal("E-ListRequest."+field, tyListRequest, field, what, why, fieldSpec)
}
rows := []Row{
listRefusal("TitleSearch", "a title search refuses", noWireList),
listRefusal("SpecPrefix", "a spec-id prefix restriction refuses", noWireList),
listRefusal("IDFilter", "an explicit id set on the LISTING refuses",
noWireList+"; the exact-ids question is getIssue's, reached through the SearchIssues bridge's exact-ids shape (D11), not through a listing filter"),
listRefusal("LabelPattern", "a glob label filter refuses",
noWireList+" — listReadyWork does publish label_pattern, which is exactly why the absence here has to refuse rather than fall through"),
listRefusal("LabelRegex", "a regex label filter refuses",
noWireList+" — as for LabelPattern, listReadyWork publishes label_regex and the listing does not"),
listRefusal("TitleContains", "a title substring filter refuses", noWireList),
listRefusal("DescContains", "a description substring filter refuses", noWireList),
listRefusal("NotesContains", "a notes substring filter refuses", noWireList),
listRefusal("ExternalContains", "an external-ref substring filter refuses", noWireList),
listRefusal("ExternalRef", "an exact external-ref filter refuses", noWireList),
listRefusal("UpdatedAfter", "an updated-after bound refuses", noWireList+" — only the created bounds are published"),
listRefusal("UpdatedBefore", "an updated-before bound refuses", noWireList+" — only the created bounds are published"),
listRefusal("ClosedAfter", "a closed-after bound refuses", noWireList),
listRefusal("ClosedBefore", "a closed-before bound refuses", noWireList),
listRefusal("DeferAfter", "a defer-after bound refuses", noWireList),
listRefusal("DeferBefore", "a defer-before bound refuses", noWireList),
listRefusal("DueAfter", "a due-after bound refuses", noWireList),
listRefusal("DueBefore", "a due-before bound refuses", noWireList),
listRefusal("EmptyDesc", "the empty-description predicate refuses", noWireList),
listRefusal("NoAssignee", "the unassigned predicate refuses",
noWireList+" — listReadyWork publishes `unassigned`; the listing does not"),
listRefusal("NoLabels", "the no-labels predicate refuses", noWireList),
listRefusal("Priority", "an exact priority filter refuses",
noWireList+" — listReadyWork publishes `priority`; the listing does not"),
listRefusal("PriorityMin", "a minimum-priority bound refuses", noWireList),
listRefusal("PriorityMax", "a maximum-priority bound refuses", noWireList),
listRefusal("PinnedFlag", "selecting the pinned-FLAG rows refuses",
noWireList+". The pinned STATUS is reachable through `status`; the flag is a separate predicate at any status and has no parameter"),
listRefusal("NoPinnedFlag", "holding the unflagged predicate in place refuses",
noWireList+". It changes nothing on a default listing and NARROWS under `all` or a pinned/hooked status — which is precisely when dropping it would widen the answer"),
listRefusal("ExcludeTypes", "a type exclusion refuses",
noWireList+" — listReadyWork publishes exclude_type; the listing publishes only the four include_* toggles"),
listRefusal("NoParent", "the top-level-only predicate refuses", noWireList),
listRefusal("MolType", "a molecule-type restriction refuses", noWireList),
listRefusal("WispType", "a wisp-type restriction refuses",
noWireList+". The listing now ADMITS the wisp plane — include_ephemeral landed upstream and the encoder sends it (L1 retired) — so this refusal is no longer redundant with an invisible plane: it is the only thing standing between a caller and a listing that returns every wisp type when they named one"),
listRefusal("DeferredFlag", "the deferred predicate refuses", noWireList),
listRefusal("OverdueFlag", "the overdue predicate refuses", noWireList),
listRefusal("ReadyFlag", "switching a listing onto the ready set refuses",
"ReadyFlag is not a filter but a change of QUESTION: it selects the blocker-aware ready query, which reads a narrower filter vocabulary than a ListRequest can describe. Over the wire that question is listReadyWork, a different operation with a different parameter table. "+
"Routing it there would have to decide, silently, which of this request's fields survive the crossing — so v1 refuses and the retirement path is an explicit route in the store, not a re-encode here"),
listRefusal("IncludeComments", "hydrating every row's comment bodies refuses",
noWireList+". listIssues documents `comments` as always absent on its rows; a caller that needs an issue's comments reads getIssue with include_comments, one issue at a time"),
listRefusal("Offset", "a non-zero Offset refuses",
noWireList+". The portable page is the keyset position, which the pager walks (D8 row 1); the store-backed role refuses a non-zero Offset itself"),
}
return append(rows,
Row{
ID: "E-ListRequest.SkipLabels", Kind: KindDegrade,
Type: tyListRequest, Field: "SkipLabels",
What: "the label-hydration opt-out is DROPPED, not refused: the wire hydrates labels either way",
Why: "the listing publishes no hydration parameter, so the client cannot ask the server to skip the labels JOIN. Dropping it hands the caller MORE data than it asked for and never fewer — the row set, its order, Parent and the has-more verdict are exactly what they would have been — so it cannot be misread as a narrower or wider answer. " +
"It is a degradation rather than a refusal because refusing would make `bd list --skip-labels` a hard error for a performance flag whose only observable effect over http is that the server pays for a join. The retirement path is a hydration parameter on the wire",
SpecRow: dropSpec,
PinnedBy: dropPin,
},
Row{
ID: "E-ListRequest.Brief", Kind: KindRetired,
What: "RETIRED — `bd list` over http sends the projection",
Why: briefRetiredWhy,
SpecRow: dropSpec,
PinnedBy: dropPin,
},
Row{
ID: "E-ListRequest.IncludeAllTypes", Kind: KindRefuse,
Type: tyListRequest, Field: "IncludeAllTypes",
What: "the never-hide-a-bead intent refuses",
Why: "it is the UNION of four intents the wire does publish — include_templates, include_gates, include_infra, include_ephemeral — and encoding it as those four would be a client-side restatement of a union whose whole point is that a FIFTH suppression added to workapi is lifted by it automatically. " +
"The day that fifth lands, the restatement silently stops lifting it and the listing hides beads from a caller whose contract is that it hides none. Dropping it narrows the answer for the same reason, so it refuses until the wire publishes the intent itself",
SpecRow: fieldSpec,
PinnedBy: fieldPin,
},
Row{
ID: "E-ListRequest.SkipCounts", Kind: KindDegrade,
Type: tyListRequest, Field: "SkipCounts",
What: "the cardinality-hydration opt-out is DROPPED, not refused: the wire hydrates the three counts either way",
Why: "the same reasoning as SkipLabels, and here refusing would be actively wrong: EVERY text rendering of `bd list` sets SkipCounts (cmd/bd/list.go:284, and its proxied twin), so a refusal would kill the default listing over http. " +
"Dropping it means real counts arrive where zeros were expected, and a caller that must read a zero as UNKNOWN is safe reading a true count. The cost is the three aggregate joins — including the reverse-blocker one the embedded planner cannot index — paid on a page that prints none of them",
SpecRow: dropSpec,
PinnedBy: dropPin,
},
)
}
// queryRequestRows: the boolean-query surface publishes almost its whole
// vocabulary, so there is one member left over.
func queryRequestRows() []Row {
return []Row{
refusal("E-QueryRequest.Offset", tyQueryRequest, "Offset",
"a non-zero Offset on a boolean query refuses",
"queryIssues publishes no offset parameter — the document deliberately omits one, because the two database sources this server can be built on disagree about whether they can honor it — and the store-backed role refuses one uniformly",
fieldSpec),
}
}
// bridgeWhy is the SearchIssues bridge's whole rule, written once. Every field
// row below is an instance of it.
const bridgeWhy = "the off-role SearchIssues bridge serves TWO shapes and no others: the exact-ids fast path D11 special-cases to getIssue, and the ParentID-only descendant walk D4 maps to paged listIssues?parent=<id>. " +
"Any other populated field is a filter the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly — so it refuses"
// issueFilterRows classify every member of types.IssueFilter against the
// SearchIssues bridge.
//
// The three fields the bridge DOES read — IDs, ParentID and Limit — still get
// rows, because each is refused in the shape it does not belong to: an IDs set
// alongside a ParentID is neither shape, and a ParentID or a Limit alongside an
// exact-ids lookup is a filter getIssue cannot apply.
func issueFilterRows() []Row {
bridgeRefusal := func(field string) Row {
return refusal("E-IssueFilter."+field, tyIssueFilter, field,
"a populated IssueFilter."+field+" refuses on the SearchIssues bridge", bridgeWhy,
"D8 (off-role raw methods), D4, D11, D9 L12")
}
rows := make([]Row, 0, len(issueFilterBridgeRefusals)+4)
for _, field := range issueFilterBridgeRefusals {
rows = append(rows, bridgeRefusal(field))
}
return append(rows,
Row{
// No Type/Field: this row is about a PAIR of fields, and pinning it
// to either one would make the refusal read as if the other were
// fine on its own.
ID: "E-IssueFilter.shapeConflict", Kind: KindRefuse,
What: "an id set and a ParentID together refuse — the pair is NEITHER expressible shape",
Why: "the exact-ids shape dials getIssue per id and applies no filter at all, so honoring the parent restriction would mean discarding answers client-side; the descendant walk dials listIssues?parent=<id>, which publishes no id filter, so honoring the ids would mean intersecting two answers no single wire call asked for. " +
"Both readings are drops wearing a filter's clothes, so the combination refuses before a shape is chosen",
SpecRow: "D4, D11, D9 L12",
PinnedBy: "TestASearchFilterMatchingNeitherShapeRefuses",
},
refusal("E-IssueFilter.Limit@exactIDs", tyIssueFilter, "Limit",
"a Limit alongside an id set refuses",
"getIssue answers one row per call, so a Limit could only be applied by discarding answers the caller named explicitly",
"D11"),
Row{
ID: "E-IssueFilter.IDs@bound", Kind: KindRefuse,
Type: tyIssueFilter, Field: "IDs",
What: "an id set larger than MaxExactIDs refuses",
Why: "the exact-ids shape costs one getIssue per id, so an unbounded set is an unbounded burst at one shared server. The bound is 100 and is a GUESS: open question 6 asks for the real call-site fan-out to be measured before GA",
SpecRow: "D11, open question 6",
PinnedBy: "TestTheExactIDsFanOutIsBounded",
},
Row{
ID: "E-IssueFilter.noShape", Kind: KindRefuse,
What: "a raw SearchIssues call matching neither expressible shape refuses",
Why: bridgeWhy + ". A filter naming no ids and no parent — the unbounded `everything` shape included — is not one of them",
SpecRow: "D8 (off-role raw methods), D4, D11, D9 L12",
PinnedBy: "TestASearchFilterMatchingNeitherShapeRefuses",
},
Row{
ID: "E-bridge-parent-shape", Kind: KindRetired,
What: "RETIRED — the ParentID-only shape was unreachable from `bd list --parent` as the CLI builds it, and the walk refused over http",
Why: "the escalation this row raised (ga-2ieek) was resolved by spec revision 6b428bf63 as semantic inversion: the wire publishes INTENTS (`all`, `include_templates`, `include_gates`, `include_infra`) rather than materialized exclusions, and the server's role re-derives the exclusions from the same builder against its own authoritative vocabulary. " +
"The bridge therefore inverts the derived members back to intents instead of encoding them, and the objection recorded here — that recognizing the baseline would be an unsanctioned second encoder — is answered by VERIFYING each candidate through workapi.BuildListFilter itself rather than reimplementing it. The live rules are the P-IssueFilter.* population",
SpecRow: "D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek",
PinnedBy: "TestTheParentWalkInvertsTheDerivedDefaults",
},
)
}
// parentWalkRows classify types.IssueFilter against D4's descendant walk, which
// reads the SAME struct as the exact-ids shape and reads it differently.
//
// Three populations, and the split is the whole content of the ga-2ieek
// resolution:
//
// - the six DERIVED DEFAULTS workapi.BuildListFilter populates from the
// intent flags. A value the same builder would have derived for the intents
// being sent is accounted for and sends nothing; every other value refuses
// here. These are the rows the inversion raises by id;
// - the four members the walk carries that decide nothing, DROPPED with the
// argument that says why the difference cannot be read as a narrower or
// wider answer;
// - everything else, refused exactly as it is on the other shape — the walk
// just reaches it from a filter that has more populated than an id lookup
// ever does.
const parentWalkSpec = "D4 (`bd list --parent` hierarchical walk), D9 L12, escalation ga-2ieek"
func parentWalkRows() []Row {
const pin = "TestTheParentWalkInvertsTheDerivedDefaults"
derived := func(field, what, why string) Row {
return Row{
ID: "P-IssueFilter." + field, Kind: KindRefuse,
Type: tyIssueFilter, Field: field,
What: what, Why: why, SpecRow: parentWalkSpec, PinnedBy: pin,
}
}
walkRefusal := func(field string) Row {
return Row{
ID: "P-IssueFilter." + field, Kind: KindRefuse,
Type: tyIssueFilter, Field: field,
What: "a populated IssueFilter." + field + " refuses on the descendant walk",
Why: "listIssues publishes no parameter for it, and the walk's inversion accounts only for the members BuildListFilter DERIVES plus the explicit filters the operation does publish. " +
"Anything left over is a restriction the bridge would have to drop to answer at all, and a dropped filter widens the set invisibly",
SpecRow: parentWalkSpec, PinnedBy: pin,
}
}
drop := func(field, what, why string) Row {
return Row{
ID: "P-IssueFilter." + field, Kind: KindDegrade,
Type: tyIssueFilter, Field: field,
What: what, Why: why, SpecRow: parentWalkSpec + ", D9", PinnedBy: pin,
}
}
rows := []Row{
derived("ExcludeStatus", "a status exclusion that is not the derived default refuses",
"listIssues publishes no exclude_status: the wire publishes the INTENT (`all`) and the server re-derives the exclusions from the same builder against its own authoritative vocabulary, which additionally heals L7's degraded client-side set for the walk. "+
"An exclusion list no intent reproduces is therefore unstatable, and dropping it would widen the listing to closed work"),
derived("Pinned", "a pinned predicate that is not the derived default refuses",
"the pinned default is the FOURTH derived member and has no parameter of its own: `--pinned` selects the flagged rows and `--no-pinned` holds the unflagged predicate in place under `--all`, and the wire can express neither. "+
"Its derived value is a function of the `all` intent alone — upstream #5333 stopped an every-status selector from forcing it, so `--status all` and `--all` are now one filter and one wire question — and a value that intent does not reproduce is a user's own predicate, which NARROWS, and that is precisely when dropping it would answer a different question"),
derived("IsTemplate", "a template predicate that is not the derived default refuses",
"listIssues publishes include_templates, an intent, not an is_template predicate. `&false` is what the absent flag derives and sends nothing; nil is what `--include-templates` derives and sends the flag; `&true` selects templates ONLY, which no intent on this operation can say"),
derived("ExcludeTypes", "a type exclusion beyond the derived gate and infra members refuses",
"listIssues publishes include_gates and include_infra — intents — and no exclude_type. The gate member and the whole infra vocabulary are what their absent flags derive; a leftover member is a user's `--exclude-type`, and dropping it would return the type they asked to hide"),
derived("Ephemeral", "an ephemeral predicate that is not the derived default refuses",
"BuildListFilter sets it only for an infra `--type`, from the same flag the walk already encodes; the wire publishes no ephemeral PREDICATE on the listing — include_ephemeral is an intent that ADMITS the plane, not a selector that restricts to it — so any other value is unstatable"),
derived("SkipWisps", "a wisp-merge opt-out that is not the derived default refuses",
"NARROWED by client wave ga-mijra, which closed the client-side gap this row used to record. The walk now encodes include_ephemeral — SkipWisps going false IS that intent, and it is read back off the member the way every other derived default is — so a wisp-inclusive descendant listing crosses instead of refusing, which is the shape gc's TierBoth reads take. "+
"What still refuses is a SkipWisps no set of intents reproduces: holding the plane out while include_infra or an infra `--type` admits it. BuildListFilter never builds that pair, so it is a hand-made filter rather than a flag combination, and dropping the opt-out would merge a plane the caller asked to skip"),
drop("SortBy", "the walk's sort key is DROPPED",
"findAllDescendants accumulates every level into a map keyed by id, so no per-level order reaches the answer: the walk's own assembly discards it before the caller sees it. This is a drop with nothing to drop, and the rendering order is the tree renderer's"),
drop("SortDesc", "the walk's sort direction is DROPPED",
"the other half of the order findAllDescendants discards; see P-IssueFilter.SortBy"),
drop("SkipLabels", "the label-hydration opt-out is DROPPED",
"the listing publishes no hydration parameter, so the client cannot ask the server to skip the labels join. Dropping it hands the caller MORE data and never fewer rows, so it cannot be misread as a narrower or wider answer"),
drop("SkipCounts", "the cardinality-hydration opt-out is DROPPED",
"the same absence as SkipLabels, and here refusing would be actively wrong: every text rendering of `bd list` sets it, so a refusal would kill the walk's DEFAULT rendering — the one behavior D4 classifies the walk as served in order to keep"),
}
for _, field := range parentWalkRefusals {
rows = append(rows, walkRefusal(field))
}
return append(rows, Row{
// No Type/Field: this row is about the whole recognition failing, not
// about one member. It fires when the builder rejects every candidate
// intent, which means the filter names vocabulary this client cannot
// reproduce at all.
ID: "P-IssueFilter.unrecognized", Kind: KindRefuse,
What: "a descendant-walk filter whose intents this client cannot reproduce at all refuses",
Why: "the inversion proves a candidate by RE-RUNNING workapi.BuildListFilter and comparing the derived members, so a candidate the builder itself rejects — an unknown status, a vocabulary the client's degraded copy does not carry (L7) — is never compared. " +
"When every candidate is rejected that way there is no member to blame, and refusing on the recognition is the only honest answer",
SpecRow: parentWalkSpec + ", D9 L7",
PinnedBy: pin,
})
}
// parentWalkRefusals enumerates the IssueFilter members that refuse on the
// descendant walk: everything BuildListFilter can carry that is neither a
// derived default nor a filter listIssues publishes.
//
// Written out rather than derived, for the reason issueFilterBridgeRefusals is:
// a list computed from the struct would absorb a field added upstream, and the
// bijection gate exists to catch exactly that arrival.
var parentWalkRefusals = []string{
"Priority", "LabelPattern", "LabelRegex",
"TitleSearch", "IDPrefix", "SpecIDPrefix",
"TitleContains", "DescriptionContains", "NotesContains", "ExternalRefContains", "ExternalRef",
"UpdatedAfter", "UpdatedBefore", "ClosedAfter", "ClosedBefore", "StartedAfter", "StartedBefore",
"AfterCreatedAt", "AfterID", "AfterPriority",
"EmptyDescription", "NoAssignee", "NoLabels", "PriorityMin", "PriorityMax",
"SourceRepo", "EphemeralTier", "IsBlocked", "NoParent", "MolType", "WispType",
"Deferred", "DeferAfter", "DeferBefore", "DueAfter", "DueBefore", "Overdue",
"IncludeDependencies", "NoIDShrink", "Offset", "Lite",
}
// issueFilterBridgeRefusals enumerates the IssueFilter members that refuse in
// BOTH bridge shapes, in declaration order.
//
// It is written out rather than reflected FROM types.IssueFilter on purpose: a
// list derived from the struct would silently absorb a field added upstream,
// which is the one event this whole gate exists to catch. Both the ledger and
// the encoder tables read this one enumeration, so the two cannot disagree.
var issueFilterBridgeRefusals = []string{
"Status", "Statuses", "Priority", "IssueType", "Assignee",
"Labels", "LabelsAny", "ExcludeLabels", "LabelPattern", "LabelRegex",
"TitleSearch", "IDPrefix", "SpecIDPrefix",
"TitleContains", "DescriptionContains", "NotesContains", "ExternalRefContains", "ExternalRef",
"CreatedAfter", "CreatedBefore", "UpdatedAfter", "UpdatedBefore",
"ClosedAfter", "ClosedBefore", "StartedAfter", "StartedBefore",
"AfterCreatedAt", "AfterID", "AfterPriority",
"EmptyDescription", "NoAssignee", "NoLabels", "PriorityMin", "PriorityMax",
"SourceRepo", "Ephemeral", "EphemeralTier", "Pinned", "IsBlocked", "IsTemplate",
"NoParent", "MolType", "WispType", "ExcludeStatus", "ExcludeTypes",
"Deferred", "DeferAfter", "DeferBefore", "DueAfter", "DueBefore", "Overdue",
"MetadataFields", "HasMetadataKey",
"IncludeDependencies", "SkipLabels", "SkipCounts", "SkipWisps", "NoIDShrink",
"Offset", "SortBy", "SortDesc", "MaxRows", "MaxRowsSource", "Lite",
}
// workFilterRows classify types.WorkFilter against the reverse ready bridge.
//
// The bridge exists because `bd ready`'s listing is still raw at tip, so the
// client has to map a WorkFilter back onto ready parameters until the front
// door moves onto issueops.Reader. It is deliberately throwaway; what is not
// throwaway is that it refuses every field it cannot express (L12).
func workFilterRows() []Row {
bridge := func(field, what, why string) Row {
return refusal("E-WorkFilter."+field, tyWorkFilter, field, what, why,
"D8 (off-role ready bridge), D9 L12")
}
return []Row{
{
// The one DEGRADE on this bridge, and it is here rather than among
// the refusals because it is not a filter: it is the same free-form
// text projection ReadyRequest.Brief carries, reached from the
// legacy shape. WorkFilter.Lite IS ReadyRequest.Brief — workapi
// assigns one to the other — so the two dispositions have to agree
// or the same request answers differently depending on which door
// it came in.
ID: "E-WorkFilter.Lite", Kind: KindRetired,
What: "RETIRED — the ready bridge maps Lite onto `brief`, the same parameter ReadyRequest.Brief now sends",
Why: briefRetiredWhy,
SpecRow: dropSpec,
PinnedBy: dropPin,
},
{
// A DERIVED DEFAULT, not a flat refusal (D4's parent-walk inversion,
// applied here): the one value the server re-derives drops, every
// other refuses. KindRefuse because the disposition is DispInverted,
// which the encoder drives exactly as a refusal — its sentinel value
// is by construction not the derived one.
ID: "E-WorkFilter.Status", Kind: KindRefuse,
Type: tyWorkFilter, Field: "Status",
What: "a ready-work status that is not the derived default refuses; the default (open only) is DERIVED server-side and drops",
Why: "listReadyWork publishes no status parameter: handleReady decodes a status-LESS request and the server re-derives ready work's status through workapi.BuildReadyFilter, which is unconditionally StatusOpen — open work only, the set `bd list --ready` shows. The client sends that one derived value as the absence the server reads it back from, so every real `bd ready` and `bd ready --json` (whose filter BuildReadyFilter always stamps StatusOpen) round-trips to the identical rows. Any other status is unstatable and refuses: a named status would answer over the query's open-only default rather than the set named, and the empty status is the storage layer's own open+in_progress default, which this operation cannot express either",
SpecRow: "D8 (off-role ready bridge), D9 L12, D4 (derived-default inversion, escalation ga-2ieek)",
PinnedBy: fieldPin,
},
bridge("Statuses", "a multi-status OR set on ready work refuses",
"listReadyWork publishes no status parameter, and an OR-set is neither the server's derived default (open only) nor anything the wire can carry — dropping it would widen the answer to statuses the caller did not ask for, so it refuses alongside a non-default Status (L12)"),
bridge("MoleculeID", "restricting ready work to one molecule's direct children refuses",
"listReadyWork publishes `parent` for the RECURSIVE descendant restriction and nothing for direct membership; the two are different sets, so `parent` is not a substitute"),
bridge("MolType", "a molecule-type restriction on ready work refuses",
"no wire parameter — the same absence E-ReadyRequest.MolType records, reached from the other source shape"),
bridge("WispType", "a wisp-type restriction on ready work refuses",
"listReadyWork publishes include_ephemeral, which admits the wisp plane wholesale, and nothing that selects a wisp TYPE within it"),
bridge("ExcludeIDs", "an id exclusion set on ready work refuses",
"listReadyWork publishes no id-exclusion parameter; the set is what the external-dependency policy decorator (upstream #4753) injects to hide sources behind unsatisfied external blockers, and dropping it would widen the answer to exactly the issues the caller's policy excluded (L12). A server that advertises policy.external_dependencies applies the policy itself, so the client never builds the set for it"),
bridge("Offset", "a non-zero Offset on ready work refuses",
"no wire parameter, and ready work carries no keyset position to page by; see E-ReadyRequest.Offset"),
}
}