engdocs/design/bd-serve-v0.md states the contract and the decisions behind
it: the six operations, the error-code vocabulary and the one-way-door rule
on it, the cursor's four normative properties (including that misuse is not
detectable), the loopback posture and its three bounds, and the no-hooks and
no-auto-commit decisions as contract rather than gaps. It carries across the
SHARED / ENFORCED-and-by-what / NOT-ENFORCED claim from httpapi/doc.go and
issueops/reader.go verbatim in substance and deliberately does not
strengthen it - this epic shipped an overstated version three times.
engdocs/SERVE_RUNBOOK.md is the operator half: the fixed-port recommendation
with the honest note that --addr 127.0.0.1:0 carries NO mutual exclusion,
the readiness probe (/healthz is liveness only), the SIGHUP/supervisor note,
the ambiguous-shutdown re-claim recovery and why a re-claim is safe by
construction, the connection-budget arithmetic for a shared external Dolt
server, and the request-log field list.
Both address generic automation clients and orchestrators. Every decision is
motivated from the API contract - a client that substring-matched claim
conflicts should switch to the typed 409 - and no downstream consumer,
product or fork is named.
The CHANGELOG entry is the user-facing announcement of the same surface.
DOC_INVENTORY gains a row for each new file, and the runbook a Last-reviewed
marker naming the constants it tabulates.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>