beads/internal/httpapi
CI Bot 7992c00702 feat(httpapi): publish the events journal on the v0 surface (bd-opisf)
GET /v0/beads/events pages the durable mutation journal from a caller-held
checkpoint, so a hosted consumer stops shelling out to `bd events tail`. The
journal and its retention contract already landed; this is the consumption
surface for them.

THE RECORDS ARE THE CLI'S RECORDS, and that is a machine fact rather than a
promise. The envelope and its projection moved out of cmd/bd into
internal/eventsjournal, beside the activation and auto-prune logic that already
had to be reachable from two binaries; the spec pins EventRecord to that struct
with x-go-type, pinning.go proves the generator emitted an alias, and the
committed golden fixture now renders through the same function the handler
serves from. A second wire struct in internal/httpapi would have passed its own
tests while quietly shipping a different `ts` shape or a `dep` that appeared
when empty, and the consumer who notices is the one reconciling an HTTP mirror
against a CLI export.

THREE ANSWERS THE DATA CANNOT TELL APART, which is most of the design:

  - CAUGHT UP is a 200 with an empty list. "Nothing new yet" is an ordinary
    answer about a log, and a poller whose steady state was a 404 would have to
    treat this surface's miss vocabulary as its happy path.
  - DISABLED is a 409 `events_journal_disabled`. A journal that is off reads as
    zero rows and a head of zero — byte-identical to an enabled journal nothing
    has written yet — so without this gate a consumer would poll a workspace
    that will never emit a record and call itself caught up forever. Activation
    is workspace state, so it is resolved by cmd/bd (eventsjournal.EnabledFor)
    and handed in; this package resolves no workspace state of its own. A 409
    for CodeNotClosable's reason: a statement about state the client cannot see,
    which the same request stops earning once an operator changes it.
  - PRUNED PAST is a 410 `events_journal_truncated` carrying `since`, `floor`
    and `head`. It is the surface's only 410 and it is the right one: those
    records existed, were addressable by exactly this request, and were
    deliberately deleted — retrying the same `since` can never succeed, which is
    what a 404 would wrongly invite. The mapping lives in ClassifyError, keyed
    on the typed error with errors.As, so neither database source can forget it;
    the code is storage's own constant, so the CLI's `--json` failure and this
    body cannot drift to two spellings of one condition.

`head` is why the read seam grew. ReadEventsJournal answers what came next and
cannot answer "keep asking, or wait?", so ReadEventsPageInTx returns the rows
and the counter head from ONE transaction, read in that order — a head taken
first could land below the last row served, which a consumer reads as "past the
end" and stalls on. `bd events tail --follow` keeps the cheaper path: it runs
the truncation decision every second and pays for a head read only in the
ambiguous cases.

The handler holds storage.EventsJournalCursor, a read-only interface, not the
wider accessor the CLI takes. There is no prune, no acknowledge and no
truncate over HTTP: retention stays a workspace decision, and a surface
documented to publish the journal should not be one line from a delete.

EventsJournal is the first CONDITIONAL role on httpapi.Config — required
exactly when the workspace's journal is enabled. A storage backend with no
journal seam is an ordinary backend as long as nobody asked it to record
anything (eventsjournal.Apply takes the same deal at open time), and demanding
it unconditionally refused to start two registered-backend servers that had no
use for it.

`limit` runs 1..10000 defaulting to 1000, and `0` is REFUSED rather than
meaning unlimited as it does on the issue listings: a caller resuming from an
old checkpoint would otherwise ask one process to buffer the whole retained
window. `since` is required — defaulting a missing checkpoint to zero serves
the entire window to a consumer that meant to resume, which arrives as a flood
of duplicates rather than as an error.

Tests: handler-level over both refusals, the caught-up/empty/disabled trio, the
limit bounds and an int64 checkpoint; a storage-level head guard against the
real embedded store; and three end-to-end legs through a real `bd serve` —
mutate over HTTP then read the journal back gapless, prune and meet the 410 then
recover from floor-1, and a disabled workspace refusing. The truncation mapping,
the disabled gate, the window members and the limit ceiling were each mutated
and each failed a test.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
2026-08-09 06:01:23 +00:00
..
apigen feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00
spec feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00
batch_create.go feat(httpapi): serve closeIssue over v0 2026-08-07 22:25:38 +00:00
batch_create_test.go feat(httpapi): serve closeIssue over v0 2026-08-07 22:25:38 +00:00
blocking.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
blocking_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
claim.go feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00
claim_test.go docs(httpapi): stop the orientation prose enumerating a surface it no longer has 2026-08-08 01:34:33 +00:00
close.go feat(httpapi): serve closeIssue over v0 2026-08-07 22:25:38 +00:00
close_test.go feat(httpapi): serve updateIssue over v0 2026-08-07 22:25:47 +00:00
context_test.go feat(serve): bd serve skeleton — lifecycle, mode gate, /healthz, /v0/beads/context (bd-60z) 2026-07-31 10:07:14 +00:00
cursor.go feat(issueops): add the Reader role and wire both front doors through it 2026-07-31 18:37:25 +00:00
cycles.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
cycles_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
delete.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
delete_test.go feat(httpapi): serve closeIssue over v0 2026-08-07 22:25:38 +00:00
dependency_edit.go feat(httpapi): publish addDependencies on the v0 surface 2026-08-08 00:19:48 +00:00
dependency_edit_test.go feat(httpapi): publish addDependencies on the v0 surface 2026-08-08 00:19:48 +00:00
doc.go docs(httpapi): stop the orientation prose enumerating a surface it no longer has 2026-08-08 01:34:33 +00:00
edges.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
edges_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
events.go feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00
events_test.go feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00
get_issue_test.go test(httpapi): assert what the getIssue include legs actually carry 2026-08-08 01:29:45 +00:00
handlers.go refactor(context): one snapshot-to-fields projection for both context surfaces 2026-07-31 22:35:09 +00:00
memories.go Put the memory plane behind memoryops, conformance-tested at three backends (#5387) 2026-08-07 03:57:04 -07:00
memories_test.go feat(httpapi): serve closeIssue over v0 2026-08-07 22:25:38 +00:00
pinning.go feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00
problem.go feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00
problem_test.go feat(httpapi): OpenAPI v0 spec, types-only codegen, and the drift gates (bd-ilb) 2026-07-31 08:37:34 +00:00
query.go feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00
reads.go docs(httpapi): stop the orientation prose enumerating a surface it no longer has 2026-08-08 01:34:33 +00:00
reads_test.go fix(defer): auto-wake expired dated defers on ready-front reads and claims (bd-i8qx8) (#5386) 2026-08-07 04:34:38 -07:00
ready_count_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
reopen.go feat(httpapi): serve reopenIssue over v0 2026-08-07 22:25:42 +00:00
reopen_test.go feat(httpapi): serve reopenIssue over v0 2026-08-07 22:25:42 +00:00
roles.go feat(httpapi): serve updateIssue over v0 2026-08-07 22:25:47 +00:00
roles_test.go feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00
routes.go feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00
server.go feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00
server_test.go feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00
settings.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
spec_parity_test.go test(httpapi): gate the four request member lists the wave left ungated 2026-08-08 01:37:11 +00:00
stats.go Merge branch 'facade/wave-3' into facade/wave-4 2026-08-06 21:39:05 +00:00
stats_test.go Merge branch 'facade/wave-3' into facade/wave-4 2026-08-06 21:39:05 +00:00
sweep.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
sweep_test.go feat(httpapi): serve closeIssue over v0 2026-08-07 22:25:38 +00:00
timed_provider_binding_test.go feat(httpapi): publish removeDependency on the v0 surface 2026-08-08 00:19:48 +00:00
tree.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
tree_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
update.go feat(httpapi): serve updateIssue over v0 2026-08-07 22:25:47 +00:00
update_test.go docs(httpapi): stop the orientation prose enumerating a surface it no longer has 2026-08-08 01:34:33 +00:00
wire_bijection_test.go feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00