beads/issueops/bootstrapper.go
CI Bot 27ffb42e1f feat(init): put bd init's identity seam behind Bootstrapper and InitVerifier (bd-zl3u8)
`bd init` had two implementations of what a workspace's identity IS. The direct
route read issue_prefix out of the config plane at init.go:1358 and _project_id
four hundred lines later, decided adopt-vs-write with two helper predicates, and
wrote both keys by name. The proxied route called domain.BootstrapUseCase, which
held its own list of which keys an identity is made of, wrote them
unconditionally, and folded the Dolt remote into the same call. The two agreed on
the key names and disagreed on the rule, and no test compared them.

ONLY THE IDENTITY SEAM IS A ROLE. Everything else init does — creating .beads/,
writing metadata.json and config.yaml, initializing git, installing hooks,
starting a Dolt server — CREATES the substrate or the workspace around it, and a
role is reached through an accessor ON a store, so it cannot be what makes the
store exist. init.go alone is 3,060 lines; this commit touches the part that
happens inside the database.

TWO ROLES, AGAINST THE VersionReconciler PRECEDENT. That one is a read and a
write on one role because they are two shapes of one question, and every word of
that is true here too. The test that separates them is different: can one caller
be entitled to the READ and not the WRITE? Here yes, and not hypothetically —
`bd init --team-server` adopts a bts-provisioned identity and is forbidden to
write one, and a gateway credential may be read-only. Those paths now hold an
InitVerifier and never obtain a Bootstrapper, which the type system checks;
with one role they would hold the writer and the suppression would stay where it
is today, in three should* predicates on the CLI.

Q8 ANSWERED IN THE ROLE. Bootstrap over an already-identified substrate is
ErrAlreadyIdentified, carried by an *AlreadyIdentifiedError naming what was
found, decided from the same read the write would have followed inside ONE
transaction. Either marker is enough: a substrate several rigs share carries a
prefix one of them chose, and overwriting it renames every id the others are
about to mint. The guard now sits below both front doors instead of in front of
one, so gateway and adopt paths inherit it, and re-identifying is something
somebody asks for rather than something init does twice.

THE ROLE OWNS THE IDENTITY AND NOTHING ELSE. BootstrapProject wrote six values;
BootstrapRequest carries two. The fingerprints, the synced-at marker and the
recorded binary version are refreshed on EVERY init, adopt or not — a fresh clone
of an already-identified database needs its own fingerprints precisely because it
bootstrapped nothing — so a refusable one-time write would mean either a refusal
that stops recording them or a write that is no longer one-time. bd_version has a
second reason: it is VersionReconciler's key. The Dolt remote left too; it is
where the database syncs to, not what it is, and putting them in one call is what
let a remote that could not be created fail a bootstrap that had already
succeeded. domain.BootstrapUseCase is DELETED and domain.ConfigUseCase gains
SetMetadata, the write half of the GetMetadata it already published, so the
unit-of-work body can read, refuse and write in one transaction.

THE DEFECT. Proxied `bd init` against a database another rig had already
identified rewrote both markers with its own derived values. It verifies and
adopts now, printing the direct route's existing line, with the role's refusal as
the backstop. The direct route's two identity reads also became one snapshot, so
the prefix it adopts and the project id it reconciles against can no longer come
from either side of a concurrent write; shouldConsultInitProjectID still gates
whether the id is USED, so which identities init adopts is unchanged.

CONFORMANCE. backend/conformance/bootstrapper_contract.go holds twelve cases —
both roles in one file, because every promise on either is a statement about the
other — run at all three implementations with ZERO PARKS and zero divergences.
They deliberately do not re-test the decision: the validator's and the refusal's
whole tables are pinned without a database in internal/workapi/bootstrap_test.go.
What only a real backend can show is asserted instead: that the identity is there
for the NEXT caller (a new transaction on the unit-of-work backend), that a
refusal and a validation failure leave the markers EXACTLY as they were, that the
verifier reports an unreadable identity as an error rather than as an empty one,
and that a bootstrap costs at most one version-control entry. Two independent
bodies plus an engine check, not three votes: dolt and embeddeddolt share
internal/storage/issueops.BootstrapInTx and VerifyIdentityInTx and differ only in
how they reach a transaction. The bodies live there rather than in an importable
store<role> package because the read and the write it qualifies must see one
snapshot, which storage.DoltStorage cannot express — so there is no constructor
for a depguard entry to deny.

NO HTTP OPERATION, and that is a decision. A server can only serve a database it
is already bound to, and binding it required the identity this role writes, so
the only caller that could reach such an endpoint would be asking a running
server to identify a workspace that is by construction already identified — which
is the refusal. Bootstrapping over an unauthenticated surface is a different risk
class from reading one. The read half already has an endpoint:
ContextResponse.project_id on GET /v0/beads/context is InitVerifier's answer, on
the wire, today. Recorded in both leaf docs and in the checklist.

USER-VISIBLE, for the wave's changelog pass: proxied init adopts instead of
overwriting on a shared database; `bd init` no longer heals a substrate carrying
a prefix and no project id, which is Q8 as written; an explicit BEADS_DIR outside
the repo now gets a project id written from its own metadata.json instead of
being left half-identified. Reasoning and the alternatives are in
/data/tmp/sd-server/AMBIGUITIES.md as A-ini-0..7.

A-ini-0 IS A FALSE PREMISE IN THE BRIEF, not a finding about the code: bd-zl3u8,
bd-jtp1h and bd-yby99 do not exist in the workspace at BEADS_DIR. Verified by two
bd binaries failing to open it and by a direct SQL read of all 5,603 issues.
Everything else the brief asserted about the code checked out, so the spec used
was the brief plus Q8 plus A2.

Verified: build, vet, gofmt clean; golangci-lint 0 issues (its unparam check is
what found resolveInitIssuePrefix's now-dead `write` return, removed here);
TestBootstrapperContract 12/12 at dolt, embeddeddolt and uow; internal/workapi,
internal/storage, internal/telemetry, internal/jira, issueops, the root layering
pins and the whole internal/storage/domain and internal/storage/uow packages
green; internal/httpapi green and `make api-check` clean with no spec or
generated diff; TestInit* and TestResolveInit*/TestApplyInitGateway* and
TestCorpusGolden and TestDoctor* green under BEADS_TEST_EMBEDDED_DOLT=1;
TestProxiedServerExternalCreate, TestProxiedServerPing and TestProxiedServerUpdate
green under BEADS_TEST_PROXIED_SERVER=1, each of which runs
`bd init --proxied-server` in its harness; TestProxiedLookup green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-06 03:01:33 +00:00

141 lines
7.9 KiB
Go

package issueops
import "context"
// BootstrapRequest asks an UNIDENTIFIED substrate to record the identity every
// later open verifies against.
//
// THE REQUEST CARRIES THE IDENTITY RATHER THAN MINTING IT. Choosing a prefix
// from a directory name, generating a project UUID and deciding whether to adopt
// an identity another rig already chose are all decisions made where the
// workspace is — a working directory, a git remote, a metadata.json — and none
// of them is reachable from a substrate. What is reachable from a substrate is
// the write, the refusal that guards it and the read that observes both, which
// is the whole of what this role and InitVerifier are.
type BootstrapRequest struct {
// Prefix is the workspace's issue prefix, the string every id this
// workspace mints begins with. It is REQUIRED: "" is ErrValidation, because
// a substrate with no prefix cannot name an issue and every later open
// reports it as uninitialized.
//
// A TRAILING HYPHEN IS STRIPPED, and nothing else about the value is
// touched. The settings plane has always normalized this key that way, so
// stating it here is what makes Result.Prefix — and the answer a later
// VerifyIdentity gives — the same string on every backend rather than
// whichever one that plane happened to store.
Prefix string
// ProjectID is the workspace's project identity, the value cross-project
// verification compares on every connection to catch a workspace opened
// against another project's database. It is REQUIRED: "" is ErrValidation.
//
// This role does not generate one. A caller that has no identity to record
// yet mints it (configfile.GenerateProjectID); a caller adopting a
// substrate another rig or a provisioning server already identified must
// not be here at all — that is InitVerifier's question, and asking this one
// is the refusal below.
ProjectID string
}
// BootstrapResult reports the identity the substrate now carries.
//
// It echoes rather than adds, deliberately. There is no "created" flag: this
// role writes or refuses, so a nil error IS the flag, and a second statement of
// it is a second thing to keep true.
type BootstrapResult struct {
// Prefix is the prefix as STORED, which is the request's with any trailing
// hyphen removed. A caller that goes on to print the prefix, or to build
// ids with it, uses this rather than what it sent.
Prefix string
// ProjectID is the identity as stored, byte for byte what was requested.
ProjectID string
}
// Bootstrapper describes SEEDING A SUBSTRATE'S IDENTITY: the one-time write
// that turns a database bd can connect to into a workspace bd can use.
//
// WHY ONLY THIS SLICE OF `bd init` IS A ROLE. Everything else init does —
// creating .beads/, writing metadata.json and config.yaml, initializing a git
// repository, installing hooks, rendering agent instructions, starting a Dolt
// server — CREATES the substrate or the workspace around it. A role is reached
// through an accessor ON a store, so it cannot be what makes the store exist;
// and fs/git provisioning has exactly one implementation, so a three-backend
// conformance contract over it would be three names for one body. What is left
// once those are taken out is the part that happens INSIDE the database and
// that all three backends must agree about, and that part is the identity.
//
// THE VERSION-CONTROL REMOTE IS NOT IDENTITY and is not here, even though one
// of the two front doors used to write it in the same call. A remote is where
// this database syncs to; the identity is what this database IS. They have
// different lifetimes, different failure modes and different permissions, and
// putting them in one call is what let a remote that could not be created fail
// a bootstrap that had already succeeded.
//
// A BOOTSTRAP OVER AN ALREADY-IDENTIFIED SUBSTRATE IS REFUSED. See Bootstrap.
//
// There is NO HTTP SURFACE, and that is a decision rather than an omission —
// the same shape VersionReconciler's is, for a different reason. A server can
// only serve a database it is already bound to, and binding it required the
// identity this role writes; so the one caller that could reach such an
// endpoint would be asking a running server to identify a workspace that is by
// construction already identified, which is precisely the refusal below.
// Bootstrapping over an unauthenticated surface is also a different risk class
// from reading one: `bd serve`'s document is reads plus a claim plus one
// destructive sweep, and an operation that stamps a shared database's identity
// belongs to whatever provisions the database, not to a request. The identity a
// remote caller can act on is already published — ContextResponse.project_id on
// GET /v0/beads/context is InitVerifier's answer, on the wire, today.
//
// Deterministic request-validation failures match ErrValidation; result values
// are unspecified when error is non-nil.
type Bootstrapper interface {
// Bootstrap records the request's identity on a substrate that has none.
//
// AN ALREADY-IDENTIFIED SUBSTRATE IS REFUSED, with ErrAlreadyIdentified
// carried by an *AlreadyIdentifiedError naming what was found. "Already
// identified" means EITHER marker is present — a prefix, a project id, or
// both — and the reason it is either rather than both is that a substrate
// several rigs share carries a prefix one of them chose, and overwriting it
// renames every id the others are about to mint. A partial identity is
// refused for the same reason it is reported: bd cannot tell a half-written
// bootstrap from a deliberately half-provisioned database, and guessing
// wrong destroys the one it did not mean.
//
// THE REFUSAL WRITES NOTHING, and on every backend it is decided from the
// same read the write would have followed, in one transaction where the
// substrate has transactions. Re-identifying a workspace is therefore an
// explicit operation somebody has to ask for, rather than something that
// happens because init ran twice.
//
// IT WRITES THE IDENTITY AND NOTHING ELSE — the prefix and the project id,
// the same two markers the refusal reads and VerifyIdentity answers with.
//
// The per-clone bookkeeping `bd init` also seeds is deliberately NOT here.
// The repository and clone fingerprints, the synced-at marker and the
// recorded binary version are rewritten on EVERY init, adopt or not — a
// fresh clone of an already-identified database needs its own fingerprints
// precisely because it bootstrapped nothing — so folding them into a
// one-time, refusable write would mean either a refusal that skips them or
// a write that is no longer one-time. The recorded version has a second
// reason: it is VersionReconciler's key, and two roles writing one key is
// the accretion the governing rule exists to prevent.
//
// A LATER VerifyIdentity IS THE PROMISE. After a successful Bootstrap it
// answers with this result's Prefix and ProjectID, from a fresh connection
// or a fresh unit of work. That is what "bootstrapped" means here, and it
// is why the read is InitVerifier's rather than a second method: the two
// are asked by different callers with different permissions, and the caller
// that may only read must not be handed the writer.
//
// THE TWO MARKERS LAND IN ONE TRANSACTION on every backend, because every
// backend's body takes one — which is also what makes the refusal a refusal
// rather than a suggestion two racing inits both pass. This role therefore
// never leaves a HALF-identified substrate behind; it only FINDS one,
// written by something older or by a hand, and the refusal names what it
// found so its caller can tell that apart from a re-init.
//
// AT MOST ONE VERSION-CONTROL ENTRY is recorded, and a backend that records
// none is conforming. The two markers live on planes that travel, so a
// bootstrap is history-worthy where a backend commits at all; what the role
// forbids is one entry per key.
Bootstrap(ctx context.Context, req BootstrapRequest) (BootstrapResult, error)
}