Commit graph

10,646 commits

Author SHA1 Message Date
Steve Yegge
634cbbc4bc chore(release): bump version to 1.2.1 v1.2.1
Re-cut of the burned v1.2.0: that tag failed pre-publish in goreleaser on
the freebsd cross-compile break (no artifacts were published), and a
burned tag is never reused (v1.1.1 precedent), so the same content ships
as 1.2.1 with the fix (#5661) included. The [1.2.0] changelog section is
renamed to [1.2.1] with a note; versionChanges rides along. Also the
first bump to regenerate the tracked .githooks markers via the previous
commit's update-versions.sh fix, clearing the main-red from fa3d8cc5c.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-11 14:06:37 -07:00
Steve Yegge
ce20a64bb4 fix(release): version bumps now own the tracked .githooks markers
The v1.2.0 bump (fa3d8cc5c) reddened main: the tracked .githooks/* managed
sections embed the binary Version in their BEGIN/END markers, and
TestTrackedManagedHookSectionsMatchGenerator (added with the sections in
#5522) holds them byte-equal to the cmd/bd/hooks.go generator — but
update-versions.sh's hook step was a stale comment saying there were no
hook files to update (true of the old cmd/bd/templates/hooks/*, not of the
tracked rendered copies). update-versions.sh now rewrites the marker
version wholesale (not from CURRENT_VERSION — the markers were already
drifted at v1.1.0 when the 1.2.0 bump ran), and check-versions.sh gates
the markers so a bump that skips them is refused before the push instead
of reddening main after it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-11 14:06:28 -07:00
Steve Yegge
8a01f31a30
fix(build): restore freebsd compilation with unsupported-platform stubs for procid + unverified-process (release v1.2.0 blocker) (#5661)
The dbproxy arc gated procid and the force-stop process inspection behind
linux/darwin/windows build tags with no fallback, breaking freebsd/amd64 —
a target every release ships (.goreleaser.yml bd-freebsd-amd64) but no PR
CI cross-compiles, so it surfaced only at the v1.2.0 goreleaser run
(31533013414), which failed pre-publish and burned the tag number.

Both stubs refuse cleanly with a named ErrUnsupported instead of guessing
at process identity: reattach-and-signal without birth identity is exactly
the PID-reuse race these packages exist to close. Ordinary bd use on
freebsd is unaffected — dbproxy machinery has never run there (v1.1.2
shipped freebsd with no dbproxy at all).

Verified: the full release matrix (linux/{amd64,arm64}, android/arm64,
windows/{amd64,arm64}, freebsd/amd64, + darwin/arm64) now cross-compiles
with -tags gms_pure_go; native lint + tests green. CI-gap follow-up (add a
cross-compile check to PR CI) filed separately.
2026-08-11 14:03:44 -07:00
Steve Yegge
fa3d8cc5ce chore(release): bump version to 1.2.0 v1.2.0
Cuts the [Unreleased] changelog (1,223 commits since the v1.1.2 hotfix,
mainline's first release since v1.1.0) as 1.2.0. Headliners in
versionChanges: migration 0062 (events -> dolt_ignored, one-time
self-committing flip), bd sync, --brief listings, defer auto-wake,
telemetry startup + eventsData bounding. Includes the uv.lock refresh
(the v1.1.1 lesson: the MCP gate must never meet a stale lock after the
tag exists).
2026-08-11 13:26:57 -07:00
Steve Yegge
6128bc0172
fix(metrics): bound the eventsData queue — TTL + drop-oldest caps in the flusher child (bd-ulfod) (#5660)
The eventkit file queue has no cap, TTL, or size bound: when emission
outruns the throttled drain (one file per HTTPS round trip, one 30s child
per 5 minutes), the queue grows without bound — 149k .evtq / 1.1GB observed
on one shared-$HOME machine, all of it <48h old. Orphaned .write-* temps
(emitter killed between CreateTemp and Rename) additionally leak forever,
invisible to both the flusher and the pending-check.

PruneQueue runs in the detached send-metrics child before Flush, so its
full directory scan never lands on an interactive bd invocation:

- drops .evtq batches AND orphaned .write-* temps older than 7 days —
  nothing downstream wants week-old telemetry, and a drain that far behind
  never catches up by uploading history first;
- caps surviving batches at 10k files / 64 MiB, dropping oldest-first
  (recent telemetry is the only kind worth shipping late);
- never touches the .last-flush throttle marker, the eventkit.lock, or any
  other non-queue name; tolerates losing every race with a concurrent
  flusher child (already-deleted files count as success-shaped).

A stderr line reports what a prune dropped (visible on a manual bd
send-metrics run; the detached spawn path discards child stderr).

Fixes the capacity half of bd-ulfod; upstream drain-rate work (batch
aggregation per GA4 request, adaptive flush window) is tracked separately
in GH#5649.
2026-08-11 13:24:29 -07:00
Steve Yegge
18c24a3ac3
perf(metrics): stop paying telemetry startup costs on every bd invocation (#5646)
* perf(metrics): cache the telemetry machine ID; never probe when metrics are disabled (bd-rzweb)

metrics.Init eagerly computed eventkit.MachineID on every bd invocation —
a fork of the platform machine-id probe (ioreg on macOS), measured at
20.2±1.2ms — even with BD_DISABLE_METRICS=1 and even for bd --version,
because the enabled gate only selected the emitter.

Now the ID is resolved only on the enabled path, and cached at
~/.beads/machine-id (0600, atomic temp+rename write) so the probe forks at
most once per machine instead of once per invocation. A probe failure
(eventkit's literal "invalid") is never cached, and a corrupt cache reads
as a miss and is recomputed. The probe call itself stays in metrics.go
behind computeMachineID, keeping the depguard eventkit fence unchanged.

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

* perf(metrics): spawn the send-metrics flusher only when events are queued, at most every 5 minutes (bd-p6o3y)

CloseAndFlush unconditionally re-exec'd the full bd binary as a detached
'bd send-metrics' child (plus an HTTPS POST) on every invocation — 8.5 to
14.1ms in-band before the child even starts, ~10k spawns/day on a busy
machine, with no check that anything was queued.

MaybeSpawnFlusher now spawns only when the eventsData queue holds at
least one .evtq batch AND the last spawn attempt is 5+ minutes old
(marker file eventsData/.last-flush, mtime = last attempt; attempt-based
so the rate stays bounded even when uploads keep failing). The marker
carries no .evtq extension so the eventkit FileFlusher scan ignores it.
Queued events still upload — batched, worst case one interval late plus
one bd invocation. Env/config gates (BD_IS_FLUSHER, BD_DISABLE_METRICS,
BD_DISABLE_EVENT_FLUSH, BEADS_TEST_MODE) are unchanged and still checked
first.

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

* perf(metrics): stat the throttle marker before scanning the event queue (bd-p6o3y)

flusherDue scanned the queue dir with os.ReadDir before consulting the
throttle marker — and os.ReadDir reads and sorts EVERY entry before
returning. On a machine whose uploads keep failing, the queue backs up
without bound (148k .evtq / 1.1GB observed), and that scan cost ~250ms on
every bd invocation: the commit meant to remove a ~10ms tax added a 5x
startup regression (65ms -> 330ms for bd --version) exactly where the
queue is unhealthiest. Caught re-measuring bd-c9c57 against this branch.

Now the marker stat runs first, so the throttled path — every invocation
inside the 5-minute interval — is one stat and never touches the queue;
the pending-events check (hasQueuedEvents) reads the directory in
unsorted 64-entry chunks and returns at the first match. Decision
semantics are unchanged for every marker-age/queue-state combination.
Measured: 40ms warm against the 148k-entry queue.

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

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-11 01:27:34 -07:00
Steve Yegge
96388ea019
fix(search): order Go-side-sort pages before every trim; honor sortDesc for id (#5639)
* fix(search): order Go-side-sort pages before every trim; honor sortDesc for id

Two live defects, both named-but-deferred in #5587's commit message and
both reachable from bd query '<expr>' --sort id (DefaultQueryLimit means a
bound is always set):

1. sqlbuild.Less ignored sortDesc for "id" — the one Go-side sort key —
   so every merge sort feeding a reversed id page kept the byte-FIRST
   rows. idSrcPage.sortGoSide's doc named this sibling bug explicitly.

2. #5587's fix (a page bound is only ever pushed under an order the query
   can express) covered the union seam only. The per-table seams
   (searchTable/scanFilterIDs, and the counts twin's
   finishSearchCountsPage) received the full matching set — searchWindowFor
   already withholds the page bound — but trimmed it with no sort anywhere:
   measured, 10 rows sort id desc limit 3 answered [000 001 002] where
   [009 008 007] was owed. The store-backed seam (issueops.searchTableInTxT)
   was worse off: it still pushed LIMIT into the leg SQL with no ORDER BY,
   so each leg contributed an arbitrary engine-ordered subset.

Fixes, one per seam, all converging on the same rule:

- sqlbuild.Less: sortDesc now flips the id comparison (byte order, matching
  the SQL the key would render if it could).
- domain/db: new sortRowsGoSide helper (the per-table copy of
  idSrcPage.sortGoSide) runs before finishWindow at searchTable's wide
  path, scanFilterIDs, and finishSearchCountsPage.
- issueops.searchTableInTxT: a Go-side sort leg no longer carries a SQL
  LIMIT; the leg scans the complete matching set, orders it in Go, and
  applies the same EffectiveSearchLimit bound after the order exists
  (goSideSortAndTrim), so cap accounting is unchanged and Pattern B
  hydrates only surviving rows.
- idProjection gains a comparator for the one key its payload can order
  ("id"), removing the merged-id-search landmine the old nil documented.

Tests: red-before-green verified on all three seams. sqlbuild unit test
pins Less; sqlmock tests pin the store-backed leg shape (no LIMIT under a
Go-side sort, bound still pushed under a SQL sort) and the ordered+trimmed
page; the domain/db suite adds per-table membership cases (asc, the
measured desc repro, and a four-route parity check: wisps-empty probe,
SkipWisps, wide path, counts twin must answer one page) plus a reversed
union page fence.

(bd-jao3t, bd-69c1a)

* fix(search): extend the Go-side-sort bound rule to the store-backed counts seam; one LessID comparator

Review round (adversarial pass on PR #5639):

F1 — runFilterSearchQueryInTx (issueops/search_counts.go) had the identical
defect the first commit fixed in searchTableInTxT: LIMIT eff pushed
unconditionally while sqlbuild.OrderBy renders no ORDER BY for "id". This
is the seam bd query '<expr>' --sort id actually reaches on the
store-shaped backends (storequerier → SearchIssuesWithCounts →
SearchIssuesWithCountsInTx), where BuildQueryPlan always pushes a bound —
so the first commit's repro claim held only for the uow/domain-db bodies.
Now the counts leg scans the complete matching set under a Go-side sort
and applies the same eff bound after ordering (goSideSortAndTrim),
leaving merge/trim/cap accounting exactly what the SQL LIMIT handed them.
bd list was already safe here (workapi.SQLLimit zeroes the pushed limit
for --sort id); only the querier path pushed a bound.

F2 — the byte-order id comparison existed in five hand-rolled copies
(Less, idProjection.less, goSideSortAndTrim, sortRowsGoSide,
idSrcPage.sortGoSide) — the exact duplication that let Less drift from
sortGoSide in the first place, and that hid F1's sixth site. All five now
call the one exported comparator, sqlbuild.LessID.

F3 — the ascending per-table suite case is annotated as the weak witness
it is (engine order for a PK-clustered prefix scan tends to be
byte-ascending already); the DESC cases are the red-before-green fences.

New shape test pins the counts legs: under --sort id neither the issues
nor the wisps counts query may carry a LIMIT (red on the previous commit:
the leg query carried LIMIT 3).

(bd-jao3t, bd-69c1a)
2026-08-11 00:24:28 -07:00
Steve Yegge
ffeffdda45
fix(circuit): stop the legacy sweep churning against live TMPDIR-less writers (#5640)
The legacy /tmp/beads-circuit closed-file sweep (GH#4636) assumed the
directory is abandoned — 'no live process left to reuse or clean' its
files. That premise is false wherever os.TempDir() still resolves to /tmp:
any TMPDIR-less process (launchd, cron, a bare ssh command) uses the
legacy path as its LIVE breaker directory and rewrites its closed file on
every successful connection (RecordSuccess). Every TMPDIR-set invocation
then deleted that live file and logged
'[circuit-breaker] removed legacy closed breaker file: ...' — recreate,
delete, log, forever, one stderr line per bd invocation on any machine
mixing TMPDIR-set and TMPDIR-less contexts (macOS most of all, where
interactive shells get a per-user TMPDIR and background contexts do not).

Deterministic repro at tip: 'env -u TMPDIR bd list' creates the file; the
next normal 'bd list' logs and deletes it; repeat.

Fix: gate the closed-file removal on an mtime TTL (legacyClosedSweepTTL,
24h) and drop the per-file log line. A live writer keeps its file's mtime
fresh, so it is never fought; a genuinely abandoned file — the GH#4636
ephemeral-port accumulation this sweep exists for — only ages, and still
gets cleaned. Open/half-open handling is unchanged.

Test updated to pin the split: aged closed file removed, fresh closed
file (a live writer's state) survives, fresh open file survives.
Red-before-green: the old code removes the fresh closed file
unconditionally.

(bd-uann8, from the post-wave startup audit bd-7x3ov)
2026-08-11 00:14:51 -07:00
ecuthiell
0498b22a75
fix(scripts): scrub Windows env keys case-insensitively (#5534) (#5609)
Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell

Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
2026-08-10 23:45:33 -07:00
ecuthiell
59abaff140
fix(make): quote install paths containing spaces (#5600)
* Fix Make install paths containing spaces (#5526)

Quote expanded build and install operands, and prove native Windows install-force preserves an exact spaced destination.

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell

* Keep proven rm-first install shape on native Windows (atomic rename fails the spaced-USERPROFILE proof there)

---------

Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
2026-08-10 23:03:42 -07:00
ecuthiell
1b67d0b1fb
fix(ci): remove recursive Make from lint formatting (#5302) (#5320)
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-10 21:43:59 -07:00
ecuthiell
05e3f99ae0
fix(config): reject unsafe user config paths (#5528) (#5602)
Resolve user config candidates through a shared absolute-native-path gate, preserve precedence, and keep display fallbacks out of filesystem operations. Add focused and native Windows process coverage for unsafe profile environments.

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-10 21:10:49 -07:00
ecuthiell
53b73e523f
Skip store initialization for worktree commands (#5601)
Worktree operations use only Git and filesystem state. Mark the parent as store-free and lock the inherited command inventory with an absent-store behavioral guard.

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-10 21:09:00 -07:00
ecuthiell
3c7c86d326
Fix CRLF worktree gitignore matching (#5525) (#5605)
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-10 21:08:01 -07:00
ecuthiell
9628c0189f
ci: simplify js/wasm boundary proof (saa-cgh.63) (#5612)
Use Go's supported wasm executor wrapper directly in the required CI lane. Preserve non-vacuous exact-test outcome checks and aggregate-gate propagation without runner host-attestation ceremony.

Fixes #5491

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-10 21:02:35 -07:00
ecuthiell
49a28af801
Validate doc freshness max age (#5524) (#5606)
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-10 21:02:23 -07:00
ecuthiell
c742412464
fix(gc): report active database size (#5532) (#5608)
Measure GC before/after bytes through ActiveDatabaseSizer so sibling databases cannot distort reclaimed-space reporting. Keep unavailable measurements best-effort and omit them from JSON.

Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-10 21:02:18 -07:00
ecuthiell
10f46914d6
Make wasm hook refusals observable (#5607)
Record the existing unsupported-execution sentinel on a root hook.exec span with the same identifying attributes as native runners.

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-10 21:01:31 -07:00
ecuthiell
192a6cdd69
fix: route list formats through command writer (#5543) (#5610)
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-10 20:59:20 -07:00
AJBcoding
e83ff98e4a
fix(install): stage to a temp name and rename into place so bd is never partial on the live path (#5611)
The install target overwrote ~/.local/bin/bd with rm -f + cp. cp onto the
final path is not atomic: for the whole ~200MB copy the live path holds a
truncated binary, and on macOS a partially-copied signed binary fails
code-signature validation, so the kernel SIGKILLs it at exec — rc 137 with
zero bytes on stdout or stderr, which callers cannot distinguish from an
empty result set. The rm -f adds an ENOENT window on top. Incident
(2026-08-08, gas city rig): every bd call on the host died rc=137 with empty
output for ~3 minutes while the binary was mid-copy; agents polling bd ready
read the empty output as an empty ledger and stood down.

Stage the copy to a temp name inside INSTALL_DIR (same filesystem) and mv -f
it over bd: rename(2) guarantees every exec sees either the old complete
binary or the new complete binary. Same treatment for the beads symlink
(ln -sfn to a temp name, rename over the alias) and the Windows bd.exe
branch.

Measured on macOS (signed ~200MB bd, exec loop hammering `bd version` while
installs run over it):

  old recipe, 25 installs: 67 of 71 execs die, every one rc=137
  new recipe, 400 installs: 0 of 13 execs fail

End state verified via make install-force to a scratch INSTALL_DIR, twice:
binary and beads alias both execute, the second install replaces via a fresh
inode, no temp litter remains.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-10 20:59:13 -07:00
ecuthiell
bf930078e8
test(scripts): report helper-only probe as skipped (#5599)
Mark the launchability probe skipped in ordinary package runs so a helper-only guard cannot be mistaken for executed coverage.

Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com>

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-10 20:58:58 -07:00
Ary Rabelo
85ce502dc0
fix(doctor): propagate TLS and password to federation checks (#5597)
doltServerConfig() copied ServerHost, ServerPort and ServerUser out of
metadata.json but left ServerTLS and ServerPassword at their zero values.
Every federation check therefore dialled the configured Dolt server in
plaintext and unauthenticated, so a server with require_secure_transport
rejected all four of them:

  failed to check if database "x" exists on server host:3307:
  Error 1105 (HY000): unknown error: Code: UNAVAILABLE
  server does not allow insecure connections, client must use SSL/TLS

The two sibling open paths already do this correctly, which is why normal
CRUD and the non-federation doctor checks work against the same server:

  - internal/storage/dolt/open.go (applyResolvedConfig) sets both
  - cmd/bd/doctor/dolt.go (openDoltDB) builds a ServerDSN with
    TLS: cfg.GetDoltServerTLS() and the port-keyed password

Verified against a remote TLS-only Dolt server (dolt_server_tls: true,
password in ~/.config/beads/credentials): FEDERATION goes from 2/6 to 5/6
passing, and the remaining warning is an unrelated local-server one.
Peer Connectivity, Sync Staleness, Federation Conflicts and Dolt Mode all
connect instead of erroring.

Signed-off-by: Ary Rabelo <aryrabelo@gmail.com>
2026-08-10 20:58:45 -07:00
ecuthiell
6748ef650c
build: make repository text EOL deterministic (#5319)
* build: make repository text EOL deterministic

Apply one repository-wide LF policy to detected text so Windows checkout settings cannot turn ordinary Go source or future text formats into CRLF. Preserve concise rationale for LF-sensitive hook templates, embedded Markdown, migration hashes, and generated-doc comparisons; keep the tracked JPEG explicitly binary and remove redundant path selectors.

Exercise a real isolated Git checkout with core.autocrlf=true through a narrow test package. Bind the existing required Ubuntu, macOS, and Windows matrix to exact expected GOOS values, fail closed on missing or wrong host identity and skipped or zero EOL coverage, and preserve the original doc-freshness command as a separate step.

Resolve and positively identify one canonical Git executable, reuse it under a curated environment with repo-local hooks, and protect the workflow topology with regression tests. Bind the required aggregate to startup-clean absolute Linux Bash and uname identities, require the exact POSIX checkout workspace, and re-enter privileged profile-free Bash with exec so ambient functions or startup state cannot turn a gate failure into success.

Exercise the aggregate shell boundary in subprocess regressions with hostile exported source and exit functions, poisoned startup options, paired clean and failing fixtures, wrong-host falsification, and invalid-workspace cases.

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell

* build: split CI-gate hardening from EOL policy

Remove the profile-free CI-gate host-binding chain and its structural and subprocess tests from PR #5319 so the final diff matches the accepted repository EOL motivation. Preserve the required three-host EOL policy lane and its CI Gate propagation. The merge-gate hardening will be reconstructed from current main under its own threat model and review vehicle.

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-10 20:48:09 -07:00
ecuthiell
766e6c17f2
fix: reject incompatible timeout in generated hooks (#5522)
Select timeout or gtimeout only after a successful GNU coreutils identity probe, validate BEADS_HOOK_TIMEOUT as positive whole seconds, and preserve the Perl and warned direct fallbacks under inherited shell options.

Keep GNU and Perl deadlines soft and backend-scoped, preserve natural status 137, regenerate every tracked hook artifact, and exercise the real process boundary through the required three-host preflight.

Fixes #5503

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-10 20:47:53 -07:00
Michael Hackner
1e30815156
fix(show): a close reason too big for a metadata line renders as body text (#5595)
Every other free-text field on an issue — description, design, notes,
acceptance criteria, comments — reaches the terminal through
uimd.RenderMarkdown, which word wraps at the terminal width and indents
two spaces. The close reason did not. It was formatted straight into the
metadata block beside Owner: and Created:, so it never wrapped, never
indented, and was never rendered.

For `Close reason: Closed` that is correct and this change keeps it. But
`bd close --reason-file` exists so agents can write structured multi-
paragraph close reports, and those came out corrupted rather than merely
ugly: the reason's second and later lines land in the metadata block as
peers of the metadata lines, so a blank line and a bare "- bullet one"
read as separate metadata entries directly under Created:.

So the rule is now the one the metadata block always implied — a
metadata line holds a one-liner. A reason that still contains a newline
once trimmed, or that is wider than the renderer's own wrap width, is
body text and gets a CLOSE REASON section rendered by the same call
every other body field makes. Short reasons, which is nearly all of
them, are untouched.

Not changed: bd close still echoes the whole reason on its success line.
A long reason-file dumps itself back at you there, but nothing follows
it on screen, so it is cosmetic rather than corrupting.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 20:44:10 -07:00
Julian Knutsen
2c06c76b51
Publish PUT and DELETE /v0/beads/config/{key}, the write half of issueops.WorkspaceConfig (ga-098zm) (#5596)
* Publish PUT and DELETE /v0/beads/config/{key}, the write half of issueops.WorkspaceConfig (ga-098zm)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---------

Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-10 19:47:21 -07:00
Julian Knutsen
cc3d0bcf3c
Publish POST /v0/beads/issues/{id}/comments, the wire half of issueops.Commenter (ga-rslox) (#5594)
* Publish POST /v0/beads/issues/{id}/comments, the wire half of issueops.Commenter (ga-rslox)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### MIGRATION LANE NOTE, for the deployment checklist

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

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

---------

Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-10 18:59:57 -07:00
Julian Knutsen
f925f3f5b0
Retire the last three wisp-switch call sites, and bound the wisp-inclusive union reads (ga-2ltro.12, ga-2ltro.7) (#5587)
* Retire the last three wisp-switch call sites, and open the label guard on the whole package (ga-2ltro.12)

ga-26w10 deleted a four-way switch over (add|remove) x (wisp|durable) from
`bd label` and lint the door shut behind it. THE SWITCH SURVIVED AT THREE MORE
SITES, and the rule that was supposed to stop the next one could not see two of
them. This retires all three and makes the rule package-wide.

`bd tag`'s proxied route (cmd/bd/mutate_proxied_server.go) reached
uw.LabelUseCase() through proxiedMutateIssue, whose callback signature hands out
a unit of work AND an isWisp boolean — an invitation to pick a plane, which the
tag callback accepted. It now builds one IssuePatch and hands it to
issueops.Lifecycle.Update. IssuePlaneOnly stays false, so the role resolves the
plane inside its own transaction; TestProxiedServerTag/tag_wisp_routes_to_wisp_labels,
which asserts at the SQL table that a wisp's label lands in wisp_labels and the
durable table stays empty, passes through the role with no branch in the
command. It went red on the pre-fix tree under the boolean flipped backwards,
which is the mutation this exists to kill and which is no longer expressible.

THE MOLECULE PORT'S LABEL WRITE IS GONE RATHER THAN RE-ROUTED, and that is the
stronger fix. molWriter had an AddLabel verb with exactly one caller —
bondProtoProtoInto, labelling a compound it had just created — and two
implementations that each resolved the plane AGAIN by a DIFFERENT predicate:
storeMolWriter deferred to the storage layer's isActiveWisp, uowMolWriter
consulted a cache filled from IssueUseCase().GetWisp. Two predicates for one
fact is how a row and its labels come apart. The label now travels in
compound.Labels, so the create that decides the row's table places the label
too, and AddLabel is deleted from the interface and both implementations. The
disagreement is unrepresentable, not merely unlikely.

Worth stating plainly for the reviewer: uowMolWriter.AddLabel's WISP branch was
unreachable. Its only caller labels a durable epic it just created, so the cache
answers false every time. That is why this site had no end-to-end mutation to
run and why the new test is a unit test with a recording writer: it pins that
the create carries the label, which is the property that makes the branch
unnecessary rather than merely unused.

`bd set-state` had the switch FOUR times — the label read, the event create, the
old-label remove and the new-label add — and a second implementation of the whole
command in cmd/bd/state_proxied_server.go that no longer exists. All three verbs
now have ONE body each, on both routes, ending at issueops.Reader.Get and
issueops.Lifecycle:

  - the label READ is Reader.Get's already-hydrated, already-sorted Labels, so
    there is no label-shaped read here at all — the same move ga-26w10 made for
    `bd label list`;
  - the dimension SWAP is one IssuePatch carrying Add and Remove together;
  - the EVENT is one Lifecycle.Create with ParentID, which mints the same
    hierarchical child id and writes the parent edge atomically.

FOUR DELTAS, none of them absorbed.

THE DIRECT ROUTE'S DELTA IS THE EVENT'S PLANE, AND ONLY THAT. An earlier draft
of this message claimed the direct route "read no state and wrote its label into
the wrong table" for a wisp. That was reasoned, not measured, and it is FALSE:
store.GetLabels, AddLabel and RemoveLabel all reach issueops.*InTx with an EMPTY
table name, which routes by IsActiveWispInTx, and utils.ResolvePartialID
resolves through the wisp-inclusive search. Measured at the parent commit,
`bd set-state <wisp> patrol=muted` on the direct route resolves, swaps the
label, and `bd state <wisp> patrol` reads back "muted".

What the parent DID get wrong is the EVENT. It created the state-change bead
with store.CreateIssue and no wisp flag, so an ephemeral subject got a DURABLE
event child, and the parent edge was a second unguarded write across the two
planes. Measured on both sides of this commit, same wisp, same command:

  parent   event ms-wisp-865.1, no `ephemeral` field  -> durable
  this     event ms-wisp-859.1, `"ephemeral": true`   -> the subject's own plane

so a wisp's state history now dies with the wisp instead of outliving it in the
durable table, and its parent edge is written inside the guarded create rather
than beside it.

That correction is the finding, not the footnote: this commit's own brief is
MEASURED, NOT REASONED ABOUT, and the sentence that broke the rule was in the
commit message. The rule covers the artifact too.

A FAILED REMOVAL NO LONGER PASSES SILENTLY — with one half still open. Both
retired routes warned and carried on when the remove failed, leaving the issue
holding two values for one dimension, which findStateLabel then resolves by
whichever the label read returns first. A store-level failure now fails the
command, because the remove and the add are one guarded update.

WHAT THAT DOES NOT CLOSE, stated because the first draft of this line
overclaimed it as "the dimension has one value or nothing was written": the
CONCURRENT swap. Two racing `bd set-state <id> dim=...` calls both read the same
old label, each patch removes a label the other already removed — a no-op, not a
conflict — and both adds land, so the dimension ends with TWO values. A patch is
atomic for ONE writer; it is not a fence. ExpectedVersion cannot supply one
either, because label writes deliberately do not remint RowVersion. The race is
pre-existing, is not made worse here, and is filed as ga-dle5g.

The proxied route LOSES ONE TRANSACTION. Its event and its label swap used to
commit together; they are now two role calls. The direct route was never atomic
at all (four unguarded writes), so this is a net gain there and a stated cost
here, and it is the same trade ga-26w10 took for the same reason. The event's
plane is the subject's own retention mode copied onto the child rather than
chosen, and it is CHECKED: a guarded create refuses a parent edge it cannot
write, so an event that disagreed with its subject's plane fails loudly instead
of landing in the wrong table.

DOLT HISTORY ATTRIBUTION MOVES, which is cosmetic and is said anyway because an
unstated delta is how the two corrections above came to be needed. The role
composes its own version-commit message, so `bd tag` and `bd set-state` write
"bd: update <id>" where they used to write "bd: tag <id>" and
"bd: set-state <id>". `bd dolt log` still names the issue; it no longer names
the verb. Nothing greps for those strings in this tree.

THE FORBIDIGO RULE IS NOW PACKAGE-WIDE ACROSS cmd/bd. It was narrowed by a
path-except to cmd/bd/label.go on the argument that holding an unmigrated
command to a rule written for a migration it had not had would be a lint waived
on sight. What that missed is that the waiver was INVISIBLE — a file outside the
exemption got no marker, no reason and no diff — so the three commands still
hand-rolling the switch looked exactly like the files with nothing to declare.
Two of them were additionally exempted by `path:`-only holes written for the
FILTER rule, which silently open every forbidigo rule for their files:
mol_port.go by the mol_ hole and export_source.go by the bulk-movement one.

EVERY HOLE IN THAT FAMILY IS `text:`-SCOPED NOW, not just those two. Scoping
only the holes that covered a violation TODAY was the same reasoning error as
the paragraphs above — it sized the guard by where the calls are rather than by
where the next one may be WRITTEN — and a review probe proved it with two dodges
that both passed: a neutrally-named helper dropped into the ado/gitlab/jira/
linear hole, and that helper handing the RAW use case back to a NEW file, which
then needs no import and never spells the accessor. Both are caught now, the
second one twice (the return type and the call), and both were re-confirmed to
PASS with the hole unscoped, so the fix is the scope and not a coincidence. The
`_test\.go` exemption stays unscoped on purpose: `run: tests: false` means
forbidigo never analyzes a test file, so scoping it would assert nothing.

MEASURED, NOT REASONED ABOUT. Before: 27 LabelUseCase call sites in 8 non-test
files. After: 15 in 6, every one carrying //nolint:forbidigo and the reason that
site is not a role's question, and they add up: five in-transaction port reads
(mol_port.go), two alternate-view reads (show_proxied_server.go), two bulk
relation loads (export_source.go), two label-vocabulary reads and two
label-propagate WRITES (label_proxied_server.go), one in-transaction command
read (close_proxied_server.go) and one dry-run preview read
(create_proxied_server.go). 5+2+2+2+2+1+1 = 15. The propagate pair are the
acknowledged carve-out and the only survivors that write; each site names its
follow-up, and propagate's is issueops.BatchApplier.ApplyBatch, blocked on a
cmd/bd accessor.

Both halves verified by mutation, one bypass each. A scratch
uw.LabelUseCase().AddLabel() planted in cmd/bd/state.go — reached through
proxiedOpenReadUOW, so the file imports neither internal/storage/uow nor
internal/storage/domain and depguard is blind to it — is caught by forbidigo. A
scratch uow import in the same file is caught by depguard, which cmd/bd/state.go
now joins: it is the second entry on that list because its three verbs really
have migrated, so the rule pins something that happened.

The depguard prose said the forbidigo rule was "scoped to this same file" and
the exclusions block said its label narrowing cost "a `text:` on ONE of the
per-path holes". Both are now what they are: package-wide, and three.

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

* Bound the union legs, and stop letting SQL page a sort it cannot order (ga-2ltro.7)

The two residues the #5476 review deferred, and they turned out to be one rule
observed from both ends: A WINDOW IS ONLY EVER PUSHED UNDER AN ORDER THE QUERY
CAN EXPRESS.

F4 — THE LEGS CARRY THE WINDOW NOW. buildUnionSubquery emitted no bound on
either side of the UNION ALL; only the outer query had one, so both planes were
read in full to deliver a page. Measured on a seeded two-plane store, a
four-row page with twenty matching rows per plane: each leg returned 20 rows,
40 scanned to deliver 4. Each leg now carries the outer clause VERBATIM plus the
deepest row index the outer query can reach, and returns 5 — the bound plus its
probe row — for 10 scanned instead of 40.

EACH LEG IS PARENTHESIZED NOW, and that is load-bearing rather than cosmetic: a
leg carrying its own ORDER BY and LIMIT inside a bare `leg UNION ALL leg` is a
SYNTAX ERROR, the engine reading the trailing clause as the union's own. The
first cut of this change shipped without the parentheses and `bd search` failed
outright — caught by CI, not by the leg probe below, because that probe executes
each subquery STANDALONE where the same string is perfectly legal. A test that
measures the part is not evidence about the whole, so there is now a case that
runs the composed query on both twins across six shapes (ordered, offset, text
term, default order, unbounded, Go-side), and it goes red on the un-parenthesized
form with the exact engine error.

Reusing the outer ORDER BY string rather than rebuilding it is what makes the
bound safe: unionOrderBySQL names `id` and the `sort_*` aliases, both of which
every leg already projects, so one string is valid in both positions and a leg
cannot come to rest in a different order than the one the outer query is about
to cut against. The pushdown is sound because the order is TOTAL — every clause
sqlbuild renders ends in `id ASC` — so a row in the union's top-N is in its own
leg's top-N, there being nothing else it could be behind. legLimit is the bound
PLUS any offset the engine carries, because those are rows the outer query reads
and discards; an offset this package keeps for itself is already inside the
bound.

F5 — AND THE OTHER HALF IS WHY THE LEGS GET NOTHING UNDER `--sort id`. That key
is the one sqlbuild renders no ORDER BY for, so the query ran
`SELECT id, src FROM (leg UNION ALL leg) merged  LIMIT n` — a LIMIT with no
ordering anywhere in the statement. A LIMIT without an ORDER BY does not return
the first n rows, it returns n rows.

MEASURED, and it is worse than "arbitrary". On a store with 12 durable and 12
ephemeral beads whose ids interleave, `--sort id --limit 5` answered
[000 002 004 006 008]: five durable rows, and not one wisp. The Go-side sort
then put them in perfect order, which is why this reads as a correct page — the
ORDER was right and the MEMBERSHIP silently excluded an entire plane.

Two changes close it, and both are needed:

  - searchWindowFor pushes NO page bound for a Go-side sort, which is the same
    answer internal/workapi.SQLLimit gives the reader role for the same reason.
    The CAP is not waived with it: maxRows still sizes a bound, so an unordered
    scan too large to hold answers ErrTooManyRows rather than reading the
    workspace.
  - idSrcPage.sortGoSide establishes the order before finishWindow trims. This
    is the union seam's copy of issueops.sortMergedResults and exists for the
    identical reason that one gives: a concatenation trimmed without a re-sort
    keeps an arbitrary prefix. The id is already on the ref, so no row has to be
    hydrated to be placed.

THE LIVE CALLER IS `bd query`, NOT `bd list`, and the review's note undersized
it. `bd list` is protected by workapi.SQLLimit and the wire's list endpoint pins
"created" — but workapi.BuildQueryPlan pushes SortBy and Limit straight onto the
filter for any filter-expressible query with no such guard, DefaultQueryLimit
means a limit is ALWAYS set, and "id" is in both the CLI's and the HTTP
endpoint's accepted sort keys. So `bd query '<expr>' --sort id` and
GET /v0/beads/issues/query?sort=id reached this on the DEFAULT path, on a wire
the review recorded as safe. BuildQueryPlan's own comment justifies the pushdown
by promising "the page is the first N in the requested order on every backend";
that was true of every key except the one IsGoSideSort names. Both twins are
covered — the counts twin is the one those callers reach.

TWO THINGS THIS DOES NOT FIX, named rather than left for the next reader.
The per-table seam (internal/storage/issueops) bounds each leg with
EffectiveSearchLimit under the same absent ORDER BY, so it picks an arbitrary
subset per leg before sortMergedResults runs; and sqlbuild.Less ignores sortDesc
for "id", so a reversed id page there keeps the byte-FIRST rows. sortGoSide
honors sortDesc rather than mirroring that.

Costs, stated. A caller combining `--sort id` with a small limit and no cap now
reads every matching row where it used to read limit+1. It read the wrong ones,
and the reader role has always paid this price on the same query.

Also folded in, both comment-only and both named by the review: count.go cited
`bd doctor --check=cross-table`, a selector that does not exist (the flag takes
artifacts, conventions, pollution and validate; the cross-table check runs in
the default sweep), and scanIDSrcPage claimed the shadowed durable row is
dropped "wherever it sits" when the drop only ever reached the scanned window —
a distinction this change sharpens, since the legs are now bounded.

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

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

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

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

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

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

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

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

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

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

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

Refs: #5546, #3906

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

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

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

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

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

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

---------

Co-authored-by: sjarmak <t@t.co>
2026-08-10 13:05:00 -07:00
matt wilkie
3b7eaa7d42
fix(doltserver): drain MySQL handshake before closing probe connections (#5277)
A bare Close() on a dial-only probe connection (waitForReady, the dolt-store
fail-fast dialer, the socket-fallback probe, the circuit breaker probe, and
several doctor/CLI reachability checks) sends a TCP RST instead of a clean
FIN. dolt sql-server interprets that RST as an aborted MySQL handshake;
enough of them in a short window can crash the server process (see #4132,
hamchowderr's Windows repro in issuecomment-5014617950 on #4132).

Add internal/doltserver.DrainAndCloseProbe/ProbeSQLServer, a shared helper
that reads (and discards) the handshake greeting before closing, and sweep
every MySQL-speaking dial+close probe in the tree onto it. waitForReady also
gets an F7 fix along the way: a dial that succeeds but never greets (TCP
listener accepting, MySQL engine not yet writing) is no longer treated as
ready — it keeps polling until a greeting arrives or the deadline passes.

Non-MySQL probes (remotesapi gRPC/HTTP, SSH, HTTP(S)) are left as bare
dial+close with a comment explaining why: there is no handshake to drain.

This lands the drain half of #4133 (Zireael). The config half (background
Dolt workers via --config YAML) is not ported here — it is superseded by
main's #4986 YAML-config path, which already addresses that PR's F1 lint
findings. The orphaned-server angle from #4133's report remains tracked by
the existing #4282.


Agent-Signature: claude-fable-5-high on behalf of maphew

Co-authored-by: Zireael <3856578+Zireael@users.noreply.github.com>
2026-08-10 12:51:12 -07:00
Julian Knutsen
4e7cc88180
feat(journalops): the mutation journal becomes the third facade namespace (#5552)
* feat(journalops): the mutation journal becomes the third facade namespace

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

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

The role brings the apparatus a role owes:

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

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

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

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

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

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

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

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

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

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

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

---------

Co-authored-by: Review Sim <ci@beads.test>
2026-08-10 10:58:05 -07:00
Stephanie Jarmak
7e825441b4
feat(workapi,storage): opt-in Brief projection for the list and ready pages (#5554)
STORAGE LAYER ONLY, per CONTRIBUTING_PR_GUIDELINES.md. issueops.ListRequest
and issueops.ReadyRequest gain Brief; no CLI flag and no HTTP parameter sets
it yet, so no front door's payload changes. The wiring stacks on top.

WHAT IT DROPS is the free-form text: description, design, acceptance_criteria,
notes, payload and waiters are not selected, and the row comes back carrying
types.Issue.IsLitePartial. #5546 measured a 16,051-issue store where
`bd ready --json` returned 454,021 bytes and notes plus description were 76% of
it, on the call an agent makes to decide what to work on. Measured through
issueops.Reader on 100 rows sized from those per-row ratios: 362,301 bytes
full, 24,001 brief, a 93.4% reduction.

THE PRIMITIVE WAS HALF-BUILT AND UNREACHABLE. #3906 landed
types.IssueFilter.Lite, IssueSelectColumnsLite, HeavyDropList,
ScanIssueLiteFrom and Issue.IsLitePartial, then wired filter.Lite into exactly
one place: SearchIssuesInTx, the UNCOUNTED store-backed search. Every read that
answers with IssueWithCounts, which is every --json route of both commands,
both implementations of issueops.Reader, and both HTTP reads, runs the counts
mega-query instead and ignored the field. A request that set it would have come
back correct, fully hydrated, and with nothing on it to say the projection had
not happened. That silent no-op is what this closes.

THE APPLICATION POINT IS THE COUNTS MEGA-QUERY, and it is one point rather than
four because sqlbuild.SearchCountsSQL and issueops.ScanReadyWorkRowWithCounts
are already the pair every counted read passes through: the store seam's list
(search_counts.go) and ready (ready_work_counts.go), and the unit-of-work
seam's list (issue_search_counts.go) and ready (ready_work_union.go, via
fetchCountsByIDs). sqlbuild.CountsHydration is already the value that carries
hydration opt-outs across that pair on both seams, so Lite is a third field on
it rather than a new channel.

IT CHANGES THE PROJECTION'S SHAPE, which SkipLabels and SkipCounts do not, and
that is why ScanReadyWorkRowWithCounts now takes the whole hydration instead of
a bool: the value that chose the SELECT list is the value that drives the scan,
so the two cannot be given different answers. Substituting empty strings in the
heavy positions would have kept one scan path and was rejected, because the row
would carry blank text with IsLitePartial=false, which is indistinguishable
from a genuinely textless row, the ambiguity ga-clgh and CommentsOmitted
already record.

WHERE IS INDEPENDENT OF SELECT, so this bounds the size of a row and never
which rows match: DescContains, NotesContains and EmptyDesc keep selecting
exactly what they select today, and no sort key, keyset cursor or wisp-merge
dedup reads a dropped column (CompareIssuesBy orders on nine fields, none of
them heavy).

THE CLAIM REFUSES IT, which is not the same call the page makes and is the
sharper case of the rule Limit and Offset already state. A claim does not read
its row through the page's query at all: ExecuteClaimNext refetches the winning
row whole with GetIssueInTx and hydrates its counts itself, so the projection
has nothing to apply to. Accepting the field would answer a MUTATING request
with a fully hydrated row carrying IsLitePartial=false, the caller's one signal
that it did not get what it asked for, reporting that it did. The check lives
in issueops.ValidateClaimNextRequest, which is the shared rule both ready
claimers and BatchCloser's claim already run, so all four backends refuse it on
the same line.

BuildReadyCountFilter CARRIES it, which is the opposite treatment and the
opposite reason. A count reads no field of any row, so the projection cannot
make the number wrong, and the count is not always cheap enough for that to be
the end of it: the unit-of-work seam has no COUNT(*) over the ready predicate
and sizes the set by running the unbounded page and taking its length
(uow/ready_counter.go), so dropping the field there would hydrate every heavy
column of the whole ready set to answer `bd ready --brief`, a larger read than
the page it was asked for. Carrying it also keeps that builder what its doc
says it is: the listing's filter with the PAGE removed and nothing else.

TWO ASYMMETRIES on the page path, both deliberate and both stated in code:

  - Brief IS carried onto the --ready arm (ReadyFilterFromIssueFilter) where
    SkipLabels and SkipCounts are dropped. Those two hide a number the ready
    renderings print; this drops a body no listing prints, so carrying it is
    what makes `bd list --ready` and `bd ready` answer one request one way.
  - types.WorkFilter carries Lite and neither of the other two, so the ready
    paths get readyHydrationFor rather than hydrationFor. Before this, both
    uow ready call sites passed a hardcoded CountsHydration{}, a literal that
    could not carry a filter's answer at all, which is how that path would have
    been missed.

CONFORMANCE at all four registered sites, one Test per case, for the two page
cases and for the claim refusal. Every field the cases assert stripped is
seeded heavy first and the premise is checked, so a backend that never
round-trips one of the six fails loudly instead of turning that clause into one
that cannot fail. Identity is asserted too (ID, Title, Status, IssueType,
Priority), or a body that stripped the row to its id would satisfy every
emptiness clause. IsLitePartial is asserted in both directions.

THE LITE COLUMN LIST IS PINNED BY ORDER, not only by membership. Both lists are
scanned positionally, so two columns of the same SQL type can be transposed
with no membership change at all: the pre-existing set-based parity test stays
green, the scan succeeds, and every row silently carries one column's value in
another's field. TestIssueSelectColumnsLite_IsFullMinusHeavyInOrder derives the
expected list by deleting HeavyDropList from IssueSelectColumns in place, which
makes the lite list a derivation rather than a second hand-maintained copy.

RED BEFORE GREEN, five sabotages, each verified and reverted:

  - deleting the lite branch from CountsHydration.IssueColumns fails both page
    cases with "expected 58 destination arguments in Scan, not 52";
  - accepting Brief without plumbing it to either filter, the silent no-op this
    change exists to close, fails both page cases on all six text fields and on
    IsLitePartial, which is the run that proves the assertions are
    load-bearing;
  - transposing created_by and owner in IssueSelectColumnsLite fails only the
    new order test, on IssueSelectColumnsLite[9] = owner, want created_by,
    while the set-based test stays green, which is the gap it was added for;
  - dropping the claim's refusal fails the claimer contract with "ClaimNext
    with brief: error = <nil>, want ErrValidation"; and
  - clearing Brief in BuildReadyCountFilter fails
    TestBuildReadyCountFilterIsTheUnboundedReadyFilter, which already existed to
    catch a ReadyRequest field the count builder forgets to carry and gains
    Brief in its fixture here.

The recorded ready-filter golden gains "Lite": false in 62 cases because
types.WorkFilter gained the field and the test compares marshaled JSON
byte-for-byte. False is what a request that did not ask for the projection
resolves that field to, so the replay stays exact; the test comment says so.

Gates: go build ./..., go vet ./..., gofmt, internal/storage/... (dolt,
embeddeddolt with BEADS_TEST_EMBEDDED_DOLT=1, uow, issueops, sqlbuild,
domain/db), internal/workapi/..., backend/conformance/..., issueops/...,
make api-check.

Refs: #5546, #3906

Co-authored-by: sjarmak <t@t.co>
2026-08-10 10:45:23 -07:00
Stephanie Jarmak
4a76685f90
feat(show,httpapi): reach BriefDeps from both front doors, with conformance coverage (#5549)
* feat(show): --brief-deps flag reaching DetailOptions.BriefDeps

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

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

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

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

Review follow-ups from #5547.

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

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

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

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

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

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

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

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

---------

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

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

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

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

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

Review verdict: FIX-REQUIRED then all items addressed. The reviewer
live-falsified the strong auth form and failed to break it, and confirmed
every recount re-derives exact.
2026-08-10 08:05:07 -07:00
Stephanie Jarmak
8ac3e6ea04
feat(workapi): opt-in BriefDeps projection for the issue detail view (#5547)
be-4d36f2 gave the dependents side a shallow shape after hub beads made
`bd show --json <hub>` allocate 5-13 GB marshaling full Issue records. The
dependencies side of the same builder never got it, and still returns the
complete body of every dependency.

Measured on a 16,051-issue store, one `bd show <id> --json` returned 214,456
bytes, of which 193,039 was the dependencies array; a single dependency carried
a 180,975-byte notes field. Reading one issue costs the full text of everything
it depends on.

BriefDeps reuses the shape collectDependents already settled on (id, status,
type, priority, title, dependency_type) and drops the free-form text. It is
opt-in and the default payload is unchanged, so no existing caller loses a
field it reads. That matters here: #4122 objects to default payload changes
and #5078 records what the last one cost.

The reduction runs after the Parent scan, which reads DependencyType and ID off
the full rows, and builds a new slice rather than overwriting the one the source
returned, which a caching source would keep shallow for later callers.

collectDependents now routes through the same shallowDep helper so the two
shapes are identical by construction rather than by coincidence.

Storage layer only, per CONTRIBUTING_PR_GUIDELINES.md; the cmd/bd flag that
reaches this is the follow-up PR.

Refs #5546

Co-authored-by: sjarmak <t@t.co>
2026-08-10 06:51:41 -07:00
Marlon Costa
c990ff2bb4
fix(prime): never split UTF-8 when truncating compact memories (#5338)
truncate() used byte slicing (s[:maxLen-3]+"..."), which can emit invalid
UTF-8 when a multi-byte rune (e.g. em dash) straddles the cut. bd prime --mcp
then breaks SessionStart hosts that decode stdout strictly.

Keep the byte budget, walk back to a valid UTF-8 boundary, and route
truncateMemory / todoTruncate / truncateDescription through the same helper.

Co-authored-by: Marlon Costa <marlonsc@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
2026-08-10 06:40:04 -07:00
Vishnu J
cff6bac4ed
fix(ui): stop using blocked ● for priority in CLI output (#5511)
Priority used the filled circle also mapped to status-blocked, so agents
misread ready work as blocked (GH#4996). Render P-labels only; document
the convention for agents; keep ● for blocked status alone.

Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
2026-08-10 06:19:51 -07:00
Isis Anisoptera
ef0ec061fa
fix(cook/pour): honor declared formula step types instead of squashing them to task (#5520)
* Stop cook coercing non-whitelisted formula step types to task

stepTypeToIssueType had a hardcoded five-type switch whose default
branch silently turned every other step type — custom types like
"duty", but also built-ins like decision, spike, and story — into
task. Pass the type through with Normalize() instead, defaulting to
task only when the step type is empty.

No validation is added here: pour already registers non-built-in
types via ensureSubgraphCustomTypes and the storage layer validates
against types.custom, the same division of labor as bd create --type.

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

* Fix custom-type registration gaps and honor declared parent step types

Review follow-ups to the cook/pour type passthrough (GH#5443):

- bd cook --persist now registers custom step types via
  ensureSubgraphCustomTypes, matching the pour path
- doltTransaction.SetConfig syncs custom_types/custom_statuses tables so
  in-transaction registration is visible to validation
- Wisp creation builds its validation BatchContext on regularTx (new
  issueops.CreateIssuesInTxWithContext), so a custom type registered in
  the same transaction validates on the dolt server backend
- Parent steps with a declared type keep it; only an undeclared type
  defaults to epic
- Step types are trimmed before normalizing; types.custom is serialized
  with json.Marshal; doctor's multirepo checks parse it JSON-first
- Registration gates on IsBuiltIn() so built-in types like event are not
  churned into types.custom
- Regression test runs against a local dolt sql-server when the Docker
  test container is unavailable

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

* Consolidate duplicated custom-type plumbing behind shared issueops helpers

Cleanup pass over the GH#5443 branch:

- Export issueops.ParseTypesConfigValue and point the doctor, domain/db,
  template.go's comma-split hack, and config_helpers.go's own inline
  copies at it instead of five parallel JSON-or-CSV parsers.
- Extract issueops.SyncConfigTables to own the config-key -> normalized
  table mapping; all four SetConfig implementations now share it.
- Build one BatchContext per doltTransaction create call: hoisted above
  the wisp/regular branch in CreateIssue, shared across both legs in
  CreateIssues (drops 4 redundant config reads on mixed batches).
- CreateIssuesInTxWithContext sets SkipChildCounterReconcile on a
  shallow copy so the caller's context is reusable.
- Retype ensureSubgraphCustomTypes as ensureCustomTypesForIssues taking
  []*types.Issue, removing cook's throwaway TemplateSubgraph wrapper.
- Rebuild setupLocalServerStore on the setupWispCascadeStore recipe:
  t.Cleanup teardown and CreateIfMissing instead of hand-rolled
  CREATE DATABASE / initSchemaOnDB / shelled dolt init.

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

* Stop auto-registering formula custom types; flatten unregistered to task/epic

Pour and cook --persist no longer write step types into types.custom.
A step type that is neither built-in nor already registered is flattened
with a warning — to epic when the step has children (matching the
undeclared-parent default), task otherwise. Operators opt in with
bd config set types.custom before pouring; a typo'd step type can no
longer become a permanently registered custom type.

ensureCustomTypesForIssues (the read-merge-write into types.custom)
becomes flattenUnregisteredIssueTypes, reading types.custom through the
transaction plus config.yaml-declared types to match insert validation.
The now-unused molConfigWriter interface is gone.

Also lands the code-review fixes on the same plumbing:
- storeMolWriter.GetConfig routes through the bound transaction, fixing
  out-of-tx config reads (lost-update window; MaxOpenConns=1 hang).
- doltTransaction.SetConfig invalidates DoltStore's config caches via
  the shared invalidateConfigCaches, so long-lived processes stop
  serving stale custom type/status sets.
- doctor's unknown-type check uses IsBuiltIn instead of a stale 6-type
  hardcoded list that would have flagged spike/story/gate as unknown.
- schema backfill uses issueops.ParseTypesConfigValue (no import cycle;
  the old copy kept untrimmed JSON elements).
- Dead EnsureCustomTypeInTx (misleading GH#3213 doc, wrote table-only
  rows the sync invariant wipes) and dead GetCustomTypesTx deleted.

Step.Type docs updated and schema_gen.go regenerated via go generate.

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

* Fold the last SetConfig path into SyncConfigTables; cleanups

Follow-up cleanup on the custom-types work.

EmbeddedDoltStore.SetConfig still carried the hand-rolled `switch key`
that the other four SetConfig paths replaced with SyncConfigTables, so
the helper's stated invariant — every SetConfig path keeps the
projection in step — had a hole. Route it through the helper, then
unexport syncCustomTypesTable/syncCustomStatusesTable: with no callers
left outside SyncConfigTables, the single-entry-point rule is enforced
by the compiler rather than by a comment.

Smaller cleanups alongside it:

- Drop linearConfigReader; it was the same single-method interface as
  configReader, in the same package.
- flattenUnregisteredIssueTypes built three collections where one does
  the job. Seed `unknown` directly and delete registered types, losing
  the string/IssueType round-trip.
- Use WarnError instead of open-coding its Fprintf.
- processStepToIssue trimmed step.Type twice, once inside
  stepTypeToIssueType and again for the epic default; hoist to one
  declaredType so the two can't drift.
- Remove the `typesStr == ""` guard in readTypesFromDB, left behind
  when its loop became ParseTypesConfigValue (which returns nil for
  empty).
- Rename the BatchContext copy in CreateIssuesInTxWithContext from
  `local` to `batch` instead of reassigning the parameter, so bc
  provably stays the caller's pointer.
- Lead storeMolWriter.GetConfig's doc with the reason that still
  applies (second pool connection deadlocks at MaxOpenConns=1); nothing
  registers types in-transaction during pour any more.

No behavior change. gofmt, go vet, and the affected tests pass;
golangci-lint was not available locally.

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

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-10 05:36:33 -07:00
Isis Anisoptera
c8dd08c262
fix(human): respond/dismiss text sources, bd list parity, and proxied-server support (#5333)
* fix(cli): one text-source layer for comment, note, and human respond

`bd comment`, `bd note` and `bd comments add` each read their body text a
little differently, and all three applied a SILENT precedence when a caller
gave two sources: positional text plus --stdin or --file resolved to the flag
and dropped the positional half with no message. In every case we could find,
the dropped half was the text the caller meant.

One textSources layer now owns the reading for all of them. Naming two sources
is an ERROR ("cannot combine positional text ... with --stdin") rather than a
precedence question; --file content is passed through verbatim, matching every
other file-input flag (--body-file, --design-file, --reason-file), while stdin
keeps trimming the trailing newline a shell appends; and an explicitly-set-but-
empty text flag counts as a source via cobra's Changed, so `--response ""` gets
"cannot be empty" rather than "no text provided".

`bd human respond` joins them: its response can come from positional args,
--response, --file or --stdin, so --response is no longer a required flag.
`bd human dismiss` takes its reason positionally as well as via --reason, and
both accept trailing free text (`<id> [text...]`) the way `bd comment` does —
a second argument is text, never a second id. The "Response: " prefix and the
shared Dismissed close reason are now formatted ONCE, before the proxied
dispatch, so the two backends cannot shape them differently; the same move
lets the proxied comment entry points take resolved text instead of re-reading
the flags themselves.

`human stats` classifies dismissals by that shared Dismissed prefix instead of
a case-insensitive substring search for "dismiss", so the writer and the
classifier cannot drift. Beads closed earlier with a lowercase or mid-string
"dismiss" move from the Dismissed count to Responded; CHANGELOG carries the
note.

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

* fix(human): bring `human list`/`stats` to bd list parity via IncludeAllTypes

`bd human list` built its own two-field filter: a label match plus whatever
--status the caller typed, unvalidated. So it showed closed beads by default
where `bd list` hides them, answered a typo'd status with a silent empty list
instead of an error, and — because it never went through the shared builder —
could not be told what a default listing is SUPPOSED to hide.

It goes through workapi.BuildListFilter now, which gets it the done/frozen
status exclusions, the pinned default, status validation against built-in and
custom names, comma-separated sets, and "all". `human stats` counts the same
universe (--status=all) through the same path, and the proxied side calls
openAndPrepare rather than hand-building a second filter, so the command
cannot mean one thing in direct mode and another behind the proxy.

What it must NOT inherit is the type suppression: a `human` label is an
explicit request for a person's attention, and this command is the only place
a person sees it, so gates, wisps, infra beads and templates all show. That is
the new issueops.ListRequest.IncludeAllTypes — the union of IncludeTemplates,
IncludeGates, IncludeInfra AND IncludeEphemeral. Both the type exclusions and
the PLANE decision now live in one applyTypeSuppressions that the flag skips
whole, so it decides the ephemeral plane too rather than lifting three type
knobs and leaving `bd human list` blind to human-labeled wisps. A suppression
added there in future is lifted here without touching this command.

Two pinned fixes fall out of parsing the status selector ONCE instead of
comparing the raw string in three places:

  * --status=all no longer forces Pinned=false. "all" promises every status;
    the string comparison never matched it, so the one selector that hides
    nothing kept hiding pinned beads. The golden case status_all_keyword is
    re-recorded (Pinned false -> null) and TestPinnedDefaultBySelector owns
    the rule now.
  * --status=pinned,closed no longer excludes the pinned beads it asks for —
    the same comparison missed every multi-status set.

--ready is deliberately unaffected: it forces status open and otherwise
ignores the selector, so an "all" the query never applies must not have a
pinned side effect either.

BEHAVIOR CHANGE, called out in CHANGELOG: scripts using --status=all as a way
to list everything EXCEPT pinned beads will see pinned beads appear. Add
--no-pinned to keep the old result.

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

* fix(human): let proxied respond/dismiss answer wisps, and stop the phantom label warning

Two gaps in the proxied twins of `bd human respond`/`dismiss`, both of which
`bd human list` showing every bead type now makes reachable:

WISPS. The pair resolved through proxiedRequireIssue and then wrote the
comment and the close against the DURABLE tables. A human-labeled wisp is a
bead a person can see in `bd human list` — so it has to be one they can also
answer. Resolution goes through workapi.GetIssueOrWisp and the write side
branches: AddCommentToWisp/CloseWisp for the ephemeral plane, unchanged calls
for the durable one, still inside the single RunTx the proxied write
convention asks for.

THE ADVISORY WARNING FIRED ON A FAILED LOAD. The missing-'human'-label warning
read labels with the error discarded, so a label load that FAILED was
indistinguishable from a bead with no human label, and the user was told the
label was missing when nothing had been checked. The result now carries
labelsKnown, and a failed load simply warns nothing.

NOT salvaged: the post-commit close-hook firing this branch originally carried.
It was written when each proxied call site hand-wired its own hooks; main has
since moved firing onto the unit-of-work plumbing (uow.NewNotifyingProvider,
bd-opisf), which buffers during the transaction and drains after Commit. The
proxied human close already fires its hooks — a hand-wired call here would
fire each one twice. The reason is recorded on closeHumanProxied so the next
reader does not re-add it.

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

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 05:36:11 -07:00
Michael Hackner
10484482c3
Fix supersedes and other dependency types displaying as blockers (#5529)
`bd show` printed "DEPENDS ON" on an issue that another supersedes, and
"BLOCKS" on its replacement instead of the obvious "SUPERSEDED BY" and
"SUPERSEDES." "BLOCKS" was doubly wrong since supersedes takes no part
in ready-work calculation.

Only blocks, parent-child, related and discovered-from had verbiage of
their own; duplicates, replies-to, tracks, attests and every other type
fell through to a `default: blocks` fallback, while conditional-blocks
and waits-for do block but lost the distinction.

One table now names each type from both ends of its edge and all three
renderers share it.

Type names have no consistent left-to-right reading, so each entry takes
its direction from the command that writes the edge: `bd supersede old
--with new` stores (old, new), making the source the replaced issue.

Same bug elsewhere, also fixed: `bd show --refs` headed groups with the
bare type name, so a canonical issue announced itself as the copy; `bd
dep add` and `rm` said "depends on" whatever the type; `bd dep list`'s
batch header said "X depends on:"; `bd list --deps` had supersedes and
conditional-blocks backwards; and the dependencies doc described
supersedes in reverse.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 05:32:51 -07:00
ecuthiell
10e23e0982
fix: route graph exports through command writer (#5513)
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-10 05:31:46 -07:00
ecuthiell
07d679ea51
fix: export the native prebuilt test binary path (#5512)
Derive the complete test-runner output with go env GOEXE before both
building and exporting it. Add a fast process regression for launchability
and caller precedence, maintained by the existing three-host preflight lane.

Fixes #5502

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-10 05:31:23 -07:00
ecuthiell
27c1fe7085
docs: clarify CI topology authority (saa-cgh.61) (#5501)
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-10 05:30:43 -07:00
ecuthiell
345dbe8878
test(ci): derive storage timeout nesting (saa-cgh.64) (#5498)
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-10 05:29:58 -07:00
Bùi Phan Viết Cường
0e2e2a4741
fix(dolt): scrub stderr-directed git tracing before git-remote transfers (#5323)
* fix(dolt): scrub stderr-directed git tracing before git-remote transfers

Dolt's git blobstore drives git plumbing through a runner that captures
stdout and stderr into a single buffer and parses object ids out of the
result (store/blobstore/internal/git/runner.go). Any stderr chatter
therefore corrupts every captured value: with GIT_TRACE=1 in the
environment, bd dolt push/fetch/clone against a git+ remote dies with
"failed to get remote db", and the credential hints Dolt appends to the
error point the user at auth instead of tracing. #3996 fixed the same
combined-output class in bd's own git helpers, but the vendored Dolt
runner is out of reach.

What bd can do is keep the poison out of the environment the runner
inherits. New internal/gittraceenv knows the GIT_TRACE* family and
strips only stderr-directed values: absolute-path targets
(GIT_TRACE=/tmp/log) and trace2 af_unix: sockets keep working, and
disabled values (0/false/empty) are left alone. Like githooksenv it
refcounts a process-wide scope so concurrent remote ops nest safely.

Wiring mirrors #5186: the in-process CALL DOLT_PUSH/FETCH/CLONE path
gets the scrub through a single withRemoteEnvGuards helper in
versioncontrolops, which now owns both env guards so a call site cannot
pick up one and silently miss the other, and the dolt CLI fallback
scrubs the child environment in prepareDoltCLITransferCommand.

Repro on stock bd, any git+file remote: GIT_TRACE=1 bd dolt push fails
every time; with this change the traced and untraced pushes both pass.

* fix(dolt): close git-trace scrub gaps from review

The scrub covered the in-process engine path and the dolt CLI transfer
route, but three subprocess spawns still inherited stderr-directed git
tracing, and the value classifier accepted af_unix: targets for
variables that do not support them.

- githooksenv gains DisabledEnv, the subprocess-env counterpart of
  WithDisabled, with exec last-wins replace semantics. Combined with
  gittraceenv.ScrubEnv it forms the guarded env every dolt spawn that
  can touch a git-protocol remote needs, so a spawn site cannot pick up
  one guard and miss the other.

- Server spawns: the directly-managed sql-server spawn and the proxied
  one now build their child env through a shared
  doltserver.ServerSpawnEnv(). A server auto-started from a shell
  carrying GIT_TRACE=1 no longer poisons every server-side git-protocol
  transfer until restart.

- Bootstrap clone: BootstrapFromRemoteWithDB spawns dolt clone via
  bootstrapCloneCmd with the guarded env; it does not route through
  prepareDoltCLITransferCommand, so it needs the guards itself.

- remotecache: cross-rig cache push/clone/pull spawn dolt through one
  doltCmd choke point with the guarded env; previously all three
  inherited the caller's environment with neither guard.

- Classifier: stderrDirected is name-aware; af_unix:[<mode>:]<path> is
  a file target only for the GIT_TRACE2 family, so GIT_TRACE=af_unix:...
  is now scrubbed instead of drawing "warning: unknown trace value" on
  stderr per plumbing call. On Windows, env names match
  case-insensitively (Set Git_Trace=1 enables tracing in the child all
  the same) and a leading dir separator counts as a file target, the
  way git's is_absolute_path reads it.

- domain/db: the dormant Fetch/Push/Pull/Clone verbs get a comment
  routing future wiring to the right guard site. The Runner behind this
  repository is a connection to the sql-server, so the git plumbing
  spawns from the server's environment — process-env guards in bd would
  be inert here; ServerSpawnEnv at spawn time is the protection.

Regression tests assert the guarded env at each spawn site (effective
GIT_CONFIG_PARAMETERS via last-wins Extract), the survival of
file-target tracing, and the classifier table including the Windows
name/path semantics.

---------

Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
2026-08-10 05:25:15 -07:00
Julian Knutsen
2a4b75b810
Publish GET /v0/beads/issues/{id}/related, the wire half of issueops.Relations (ga-81p36) (#5540)
Relations is one of the facade methods the ext-api-store audit lists with no
wire operation, and it is the one gc's infra-over-http read surface cannot do
without: `bd dep list`'s dependents view has no other direction-aware wire path,
because EdgeReader is outgoing-only. This is that operation. The role, its
contract and all three legs already exist; this slice wires them.

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

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

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

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

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

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

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

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

    *serveRolesStore does not implement serveRoleSource (missing method IssueRelations)

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

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

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

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

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

Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-10 05:23:30 -07:00
Julian Knutsen
cff62bd631
Make the pre-commit lint gate trustworthy, and stop one main-side lint word from reddening every PR (#5538)
* fix(githooks): build golangci-lint with the repo's Go, not golangci-lint's

The pre-commit hook ran `go run golangci-lint@v2.10.1`. For a pkg@version
build the go command honours the TARGET module's toolchain directive, so
GOTOOLCHAIN=auto downgraded to go1.25.12 — and golangci-lint built by
go1.25 refuses this repo's `go 1.26.5` at config load:

    go: github.com/golangci/golangci-lint/v2@v2.10.1 requires go >= 1.25.0; switching to go1.25.12
    Error: can't load config: the Go language version (go1.25) used to build golangci-lint is lower than the targeted Go version (1.26.5)

Every Go commit failed there, so the hook taught six-plus contributors to
reach for --no-verify — the one habit a lint gate must never train.

CI never hit it because actions/setup-go installs the go.mod version and
exports GOTOOLCHAIN=local, so its `go install ...@v2.10.1` compiles the
linter with go1.26.5. Pinning GOTOOLCHAIN to the go directive reproduces
that resolution on any host, including one whose base toolchain is older
than the repo's target (where a bare GOTOOLCHAIN=local would pin the
linter to that older toolchain instead).

Verified on a real staged Go change: red before with the message above,
`0 issues.` after, and still exit 1 on a planted errcheck violation.

Bead: ga-2ltro.13

* ci: lint PRs for what they introduce, sweep the whole tree on main

Both PR lint gates linted the whole tree: the `lint` job left
only-new-issues at its false default, and pr-lint-wrapper ran
`make ci-pr-lint` over ./... . So a single lint word landing on main —
twice this wave, once a prose misspell — turned EVERY open PR red for a
change it did not make, and each author had to either fix someone else's
line or wait.

The tradeoff, recorded beside the job: a pre-existing issue in untouched
code no longer blocks a PR, and because "new" is measured off the diff, a
violation carried in by a MOVE or a rename does. What it buys is that a
main-side word now reds main's own run, where it belongs. main.yml
already runs both jobs unscoped on every push, so whole-tree coverage —
including the GOOS=windows cross-lint — is unchanged; only its blast
radius moves.

The wrapper takes its scope from BD_LINT_NEW_FROM_MERGE_BASE, set only
by pr.yml, so `make ci-pr-lint` run by hand still sweeps the tree. That
makes the local wrapper STRICTER than the PR gate rather than equal to
it, which is what LINTING.md and CI_CLEANUP_PLAN.md said before and no
longer would: both now state the two-lane contract and say the local
run's extra strictness is deliberate. Their freshness markers move with
the workflow and wrapper files they are pinned to.

Bead: ga-uwix0.2

---------

Co-authored-by: Julian Knutsen <ci@beads.test>
2026-08-10 04:55:55 -07:00
Julian Knutsen
06b0dffb22
Make the next serve role a compile error, and check the one role with a positional result (#5539)
* refactor(serve): make the next role a compile error in the serve stubs

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

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

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

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

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

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

Bead: ga-c3g45

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

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

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

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

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

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

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

Bead: ga-39tl5

---------

Co-authored-by: Julian Knutsen <ci@beads.test>
2026-08-10 04:34:15 -07:00
Julian Knutsen
d0e612eaf8
fix: a re-close that runs on_close, a silent cycle-gate walker, and a leaf that contradicts the wire (#5537)
* fix(storage): fire the batch-close hook on Changed, not on a nil per-item error

hookBatchCloser tested `outcome.Err == nil`, so an idempotent re-close — a
per-item SUCCESS that persisted nothing — announced itself like a close that
landed. A teardown replayed against an already-closed convoy ran the
workspace's on_close script again on every pass, once per item.

Its own header already claimed per-LANDED-item firing, and the sibling
hookBatchApplier fires its ItemClose on Changed and named this wrapper's
predicate as the bug not to copy. The predicate now matches both.

The firing test becomes a table modelled on the applier's, recording the id
each hook fired for: the new rows are an idempotent re-close (fires nothing)
and a re-close beside a real close (announces only the one that landed). Both
are red against the old predicate.

Two comments that described the bug as live are now history: the applier's
header, and its table's "sibling bug NOT to copy" row.

ADJACENT AND DELIBERATELY UNCHANGED: the SINGLE-close paths still fire on a
re-close. HookFiringStore.CloseIssueChecked documents it ("this includes the
idempotent no-op") and hookIssueOperations.Close is unconditional on success
by the same legacy parity. That divergence is now pinned where it is asserted,
in uow's notifying parity table, rather than left to be rediscovered.

Refs: ga-2yaqp.1

Committed with --no-verify: the pre-commit hook's
`go run golangci-lint@v2.10.1` resolves a go1.25 toolchain and refuses this
repo's go 1.26.5 target ("the Go language version used to build golangci-lint
is lower than the targeted Go version"), independent of any staged content.
`golangci-lint run --new-from-rev=origin/main` with the correctly-built local
v2.10.1 binary reports 0 issues, and gofmt is clean.

* refactor(dolt): call types.IsSchedulingEdge in the cross-tier cycle gate

checkCrossTierSchedulingCycle spelled the scheduling-type set as an inline
switch, so it was not among the four copies #5480 folded into
types.IsSchedulingEdge — and it is the copy whose staleness is silent. A fifth
scheduling type would fall to the switch's default, return nil, and SKIP the
merged two-session cycle probe entirely: no error, no log line, a committed
cross-session cycle. The other copies refuse or mis-render; this one just
stops looking.

Behaviour is unchanged today — the predicate holds exactly blocks,
conditional-blocks and parent-child — and #5480's "one edit for a fifth type"
claim is now true.

The guard arm had no coverage, so it gets a case: a committed scheduling edge
R -> W, then a cross-tier `related` edge W -> R that closes the loop. The only
difference from TestRunInTransactionCrossTierCycleRejected is the edge type,
so the case fails the moment the arm stops excusing non-scheduling edges —
verified by replacing the guard with `if false` and watching it refuse with
"would create a cycle".

Refs: ga-2ltro.10

Committed with --no-verify for the pre-commit golangci-lint toolchain
mismatch documented on the previous commit; the local v2.10.1 binary reports
0 issues over the branch.

* fix(issueops): the Releaser leaf claimed byte-for-byte holders; it is separator-insensitive

ReleaseRequest.ExpectedAssignee documented "HOLDERS COMPARE BYTE FOR BYTE, not
trimmed and not folded". That has been false since ga-5ksp5: the comparison is
actorMatches/canonicalActor, which collapses any run of ".", "_" or "-" to one
separator, so agent-a, agent_a and agent.a are one holder.

The published wire schema already says this correctly
(ReleaseIssueRequest.expected_assignee: "SEPARATOR-INSENSITIVE AND NOTHING
ELSE ... not trimmed and not case-folded"), so a role leaf and a shipped spec
contradicted each other about a compare-and-set predicate — and the leaf was
the wrong one. A client author reading the role doc coded the wrong holder
comparison. The wire text is the model and is ported here verbatim in
substance; no wire field changes, and `make api-check` is clean.

Actor's ownership-fence paragraph gets the same cross-reference: that fence is
actorMatches too (issueops/unclaim.go), so "is the current holder" must not be
read as exact equality either.

Nothing at the role tier pinned the canonicalization, so
RunReleaserReleasesOnlyTheExpectedHolder grows the two limbs that do:
"releaser_holder" releases a claim held by "releaser-holder", and
" releaser-holder" still refuses with ErrAssigneeMismatch leaving the row and
its version untouched. They are arms inside the existing case rather than new
Run* entrypoints, so the bundle and coverage gates need no new accounting.

Both limbs verified able to fail: making actorMatches byte-for-byte (the old
doc's claim) reds the respelled limb, and making it TrimSpace-tolerant reds
the padded one. Green on all three legs — dolt, uow, and embeddeddolt under
BEADS_TEST_EMBEDDED_DOLT=1.

A sweep of the leaf for other stale comparison claims found none: the
remaining byte-for-byte mentions are about project ids, error text and
metadata round-tripping, and the other Expected* docs say only "must match"
without asserting how.

Refs: ga-2ltro.14

Committed with --no-verify for the pre-commit golangci-lint toolchain
mismatch documented on the first commit; the local v2.10.1 binary reports 0
issues over the branch.

* fix(uow): gate the batch close notification on Changed in the proxied plumbing

Commit 1 fixed ONE of the two write plumbings. In proxied-server mode — which
is what `bd serve`, and therefore the whole HTTP path, runs — CloseBatch
composes uow.closeBatchItem onto recordingIssueUC.CloseIssueChecked, which
records opClose whenever err == nil. So the exact user-visible symptom of
ga-2yaqp.1 survived there: a teardown replayed against an already-closed convoy
still ran the workspace's on_close script once per item, every pass.

THE GATE GOES IN THE BATCH COMPOSITIONS, NOT IN THE VERB. recordingIssueUC's
close methods are shared with the single close, whose re-close firing is
deliberate and pinned. Gating inside them would silently change that too. So
closeBatchItem and uowApplyRun.applyClose mark the notification buffer before
the item's close and rewind to that mark when the item persisted nothing; the
verb stays honest about what it did and the composition decides what is worth
telling a script about. With hooks disabled the UnitOfWork is not the notifying
decorator at all, and both helpers are no-ops.

Red-first on the uow leg, reproducing the symptom:

  a batch re-close reports the close once:
    fired [{close bd-1} {close bd-1}], want [{close bd-1}]
  a batch pass announces only the close that landed:
    fired [{create bd-2} {close bd-1} {close bd-1} {close bd-2}],
    want [{create bd-2} {close bd-1} {close bd-2}]

The parity table's existing double-close row still asserts TWO firings for the
SINGLE close, so the two camps are now pinned side by side in one table.

The BatchApplier arm gets its own case rather than riding on the closer's: both
compositions reach the same verb, so a fix applied to one passes the other's
tests untouched. Verified by removing each gate in turn — the closer rows and
TestNotifyingUOWBatchApplierAnnouncesOnlyLandedCloses each go red only for
their own arm.

Two mock-fidelity fixes were needed to reach the composition at all:
notifyIssueUC.GetIssue/GetWisp now answer a miss with ErrNotFound, because
operationIssue tells "not on this plane" from "this plane is broken" by that
sentinel alone and a bare error aborts the two-plane resolve.

Also in this commit, from the same review:

- notifying.go's recordingIssueUC header still said "hookBatchCloser fires for
  every outcome that did not refuse", made false by commit 1. It now states the
  override and where it lives. `grep -rn "did not refuse" internal/` is empty.
- hook_batch_closer_test.go cited a non-existent BatchCloseRequest.ClaimNext;
  the role type is issueops.CloseBatchRequest.
- The two single-close sites (hook_decorator.go, hook_issue_operations.go) get
  one-line back-pointers to the batch camp, so the divergence is discoverable
  from either end.
- hookBatchCloser's header now says both plumbings answer the same way, which
  commit 1 could not honestly claim.

Refs: ga-2yaqp.1

Committed with --no-verify for the pre-commit golangci-lint toolchain mismatch
tracked as ga-2ltro.13; the correctly-built local v2.10.1 binary reports 0
issues over the branch.

---------

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

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

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

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

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

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

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

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

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

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

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

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

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

Gates: `make api-check`, `go build ./...`, `go vet ./...`, `gofmt -l` clean,
`golangci-lint run --new-from-rev=origin/main` on the touched packages (0
issues), `internal/httpapi`, `internal/telemetry`, `internal/storage` and
`internal/storage/uow` (the nine-minute parity run the checklist names), and
`BEADS_TEST_PROXIED_SERVER=1 CGO_ENABLED=1 go test ./cmd/bd/ -run
TestProxiedServerServeEdgeCounts` green against real Dolt. The pre-commit hook's
`go run golangci-lint@v2.10.1` fails on this host with a toolchain mismatch
unrelated to this change, so the hook's contents were run by hand before
committing with --no-verify.

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

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

Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-10 02:06:57 -07:00