Commit graph

3 commits

Author SHA1 Message Date
Julian Knutsen
2c06c76b51
Publish PUT and DELETE /v0/beads/config/{key}, the write half of issueops.WorkspaceConfig (ga-098zm) (#5596)
* Publish PUT and DELETE /v0/beads/config/{key}, the write half of issueops.WorkspaceConfig (ga-098zm)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---------

Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-10 19:47:21 -07:00
CI Bot
67d38d2620 Trim this series' comments toward the repo's own density
Ten agents over 216 files, one directory-balanced group each, working to a
rubric that named what to cut (duplication narration, restatement of the next
line, the governing rule echoed in every command file, throat-clearing) and
what to keep (traps, invariants, security, tracker ids, behaviour changes, and
the "why a naive simplification destroys this assertion" rationale).

Net 1,523 lines. Density against this repo's own per-directory norm on main:

  cmd/bd              33.6% -> 27.3%   (main 10.7%)
  internal/storage    26.1% -> 23.1%   (main 14.1%)
  backend/conformance 34.0% -> 29.6%   (main 22.8%)
  internal/httpapi    30.9% -> 27.8%   (main 30.6%, now below)
  overall             34.7% -> 31.6%

Every agent landed at 18-25% rather than the 30% asked for, and every one gave
the same reason independently: what remained was on the keep list. Ten separate
judgements agreeing is the most useful result here — the prose is dense, but it
is mostly load-bearing, and the shortfall is the honest answer rather than a
failure to try.

TWO REVERTS, both to protect something worth more than the lines.

issueops/ is back to its pre-trim state, giving up 610 lines. The conformance
contracts cite the leaf docs BY LINE — "pins treewalker.go:52-66" — 155 times.
Trimming the cited files silently repointed those at whatever text moved into
those numbers, across agent boundaries so no agent could see it. A semantic
remapper recovered 141 of them, but 23 needed judgement and several landed on
struct fields. The leaf docs are the spec the contracts are written against;
they are the one place in this change where dense prose IS the deliverable, and
keeping them stable is worth more than the 610 lines. tree_walker_contract.go
and version_reconciler_contract.go went back for the same reason: an agent had
deleted a paragraph containing a citation, so positional restoration could not
align them.

After the reverts, exactly 5 citations point into a still-trimmed file and 2 of
those are weak — both in cmd/bd/config_guard_test.go, which this series never
touched and whose citations were already wrong on main (init.go:361 pointed at
a closing brace; the guard it names is at init.go:1499).

VERIFICATION. A guard strips every comment and all whitespace from each of the
193 modified files at HEAD and in the worktree and requires the two to be
byte-identical, so a code change cannot hide in a comment diff. It handles `//`
inside string and raw-string literals, and was tested against a deliberate code
change before being trusted. gofmt clean, go build, go vet, golangci-lint 0
issues, and the two AST-based tests that PARSE trimmed files — the timed
provider binding pin over claim.go and the serve database-source gate over
serve.go — both pass.

One real defect found while trimming: checkDatabaseSource's doc block ran into
`// sourceRoles is ...` with no blank line, so godoc attached thirty-one lines
of the wrong prose to func sourceRoles and left checkDatabaseSource
undocumented. Fixed by separating them.
2026-08-06 08:06:59 +00:00
CI Bot
270515915f feat(config): put bd config's stored settings behind the WorkspaceConfig role (bd-kzepq)
`bd config` had two implementations of the same four verbs. The direct route
called store.SetConfig/GetConfig/GetAllConfig/DeleteConfig in cmd/bd/config.go;
the proxied route opened its own unit of work and called the config use case in
config_proxied_server.go, then printed the same lines a hundred lines away. Both
now build an issueops request and ask for the role, and the difference between
the two routes is which accessor answers.

THE ROLE. issueops.WorkspaceConfig is the workspace's DURABLE SETTINGS PLANE:
the key-value rows the workspace database holds. It is born with four methods
because read, write, remove and enumerate over ONE keyed namespace are four
shapes of one question — the governing rule forbids appending to a role, not a
role being born whole — and because their promises are statements about each
other: SetSetting's promise is about what a later GetSetting returns, and
UnsetSetting's about what a later ListSettings omits.

The methods are GetSetting/ListSettings/SetSetting/UnsetSetting rather than
Get/List/Set/Unset, and that is not verbosity. Reader already has Get and List,
and the decorator conformance tests drive ONE sentinel that implements every
role at once; two roles with the same method name and different signatures make
that sentinel unwritable. The collision was the design telling us the short
names belong to issues.

ONLY THE KV SLICE IS A ROLE, and the rest is a deliberate no. `bd config show`,
`drift`, `apply` and `validate` are multi-source diagnostics over config.yaml,
environment variables, git config, this plane and server state at once. Three of
those five sources are files on the CLIENT's filesystem, which a server
answering for a remote workspace can never read, so a substrate role claiming to
answer them would be claiming to see something it cannot. `bd config set-many`
is off the role too, for a different reason: it exists to make N keys ONE Dolt
commit, the role writes and commits one setting per call, and
TestProxiedServerConfigSetMany pins the difference. A batched write is a
separate capability, exactly as `bd create --file` stays off Lifecycle.Create.

TWO LIVE DEFECTS FIXED.

  1. THE PROJECTION, which is the Q11 user-visible change. Reads of the custom
     status and type vocabularies are TABLE-first: they consult custom_statuses
     and custom_types and fall back to the config string only when the table is
     empty. The store backends have always rewritten the table in the same
     transaction as the row; the unit-of-work backend wrote only the string. So
     on a team server `bd config set types.custom "session"` reported success,
     `bd config get` read it back, `bd doctor` re-verified against the string and
     reported all-OK, and `bd create -t session` answered "invalid issue type"
     for as long as the workspace lived. Fixed where dab71c5eb fixed it — in the
     config repository, so the row and its projection commit together — and
     verified by reverting the fix and watching ProjectsCustomStatuses and
     ProjectsCustomTypes fail on uow alone.

  2. `bd config set-many issue_prefix=x` re-prefixed the workspace. The
     single-key verb refuses the prefix in both spellings and points at
     `bd init --prefix`, `bd bootstrap` and `bd rename-prefix`; set-many
     partitioned its pairs by source and wrote the database ones straight
     through, so it never saw that guard. Beads created before the write and
     after it disagreed about their own namespace with nothing to reconcile
     them. The refusal is now in the role for every caller that goes through it,
     and at set-many's front door because it does not.

THE BRIEF'S THIRD PREMISE IS FALSE, and it is worth saying so: "uow SetConfig
skips issue_prefix normalization" is not true at this base.
configSQLRepositoryImpl.SetConfig has trimmed the trailing hyphen since the file
was created (4fcbd5882, verified with git log -L). The normalization half needed
no fix; the custom-table half did, and dab71c5eb is NOT in this base.

WHAT ELSE CONVERGED. The status.custom parse lived in THREE places (both routes
of `bd config set` plus set-many) and is now one; the routing that stays at the
front door — which source owns a key, and whether writing it would leak a secret
into git — stays there, because those are questions about files on this machine.

CONFORMANCE. backend/conformance/workspaceconfig_contract.go holds fourteen
cases run at all three implementations with ZERO parks. Its shape is
deliberately not the issue contracts': there are no rows to seed, so it asserts
PRECEDENCE (which of two writes a later read sees, and whether a refusal leaves
the earlier value standing) and SIDE EFFECTS. Every projection case reads the
TABLE through QueryScalar rather than reading the setting back through the role,
because reading it back through the role is exactly the check that passed on the
backend where nothing took effect. Two independent bodies plus an engine check,
not three votes: dolt and embeddeddolt share
internal/workapi/storeworkspaceconfig.

TWO ASYMMETRIES ARE PINNED RATHER THAN FIXED, because all three backends agree
and closing either is a user-visible change this slice was not approved for.
UnsetSetting does not undo SetSetting's projection, so removing types.custom
leaves the custom types applying (bd-yby99.33); and `bd config unset
issue_prefix` is not refused where `bd config set` is (bd-yby99.34). Both are
stated in the leaf doc and asserted by a case, so neither can drift or be closed
on one backend while the owner decides.

HTTP. GET /v0/beads/config and GET /v0/beads/config/{key}, spec-first, taking
the v0 surface from six operations to eight. A setting whose KEY marks it as
credential-bearing — notion.token is database-backed — is published with
`redacted: true` and NO value: withheld values are omitted rather than masked,
which is the document's own "verbatim or absent" rule, and the CLI is unchanged
because its caller already holds the database while this surface has no
authentication. There is no HTTP WRITE, and that is the honest answer rather
than a hedge: `bd config set` routes most keys to config.yaml or git config
before the database is reached, so a server-side PUT of `export.auto` would
return 200 and land a row nothing reads. `Setting` is the one unpinned response
component, with the reason in the document beside it — the CLI marshals an
ad-hoc map, so there is no canonical struct to pin to, and minting one would
mean changing `bd config get --json` in order to satisfy a rule about not
changing it. All three are recorded in AMBIGUITIES.md as A-cfg-1..3.

ENFORCEMENT. storeworkspaceconfig joins the cmd-bd-role-constructors deny list.
`bd config` never named types.IssueFilter, so there is no forbidigo exception to
remove. engdocs/ADDING_AN_ISSUEOPS_ROLE.md gains what step 12 now costs since
the owner's scope decision: the spec operation, the route row, the Op constant
and operationCodes row, the capability token, and the Config field that a
store-shaped database source must now carry.

Verified: build, vet, gofmt clean; golangci-lint 0 issues;
TestWorkspaceConfigContract green at dolt (14/14), embeddeddolt (14/14) and uow
(14/14); the workapi validator unit tests, the two decorator enumerations, the
root layering pins and internal/jira green; internal/httpapi green and
`make api-check` clean; TestProxiedLookup green; `-run Config` green under
BEADS_TEST_EMBEDDED_DOLT and, under BEADS_TEST_PROXIED_SERVER, green except
TestConfigValidateReadOnlyIsHermetic, which fails identically on a pristine base
worktree under the same filter and passes standalone on both. TestCorpusGolden
green, so `bd config --json` is byte-identical to the committed corpus.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-05 09:14:54 +00:00