beads/issueops/initverifier.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

75 lines
3.9 KiB
Go

package issueops
import "context"
// VerifyIdentityRequest asks what identity a substrate carries. It has no
// fields today and is spelled as a type so that gaining one is an additive
// change to something callers already name — the reason
// RecordedVersionRequest and ListSettingsRequest are spelled the same way.
type VerifyIdentityRequest struct{}
// VerifyIdentityResult is the identity the substrate carries, as it stands.
//
// BOTH FIELDS ARE "" WHEN ABSENT, and "" IS A NORMAL ANSWER rather than an
// error or a missing row to classify. A substrate nothing has bootstrapped
// answers with two empty strings, and that is the answer a caller deciding
// whether to bootstrap needs; turning it into ErrNotFound would make the
// ordinary case look like a failure and force every caller to unwrap it back
// into the same two strings.
type VerifyIdentityResult struct {
// Prefix is the substrate's issue prefix, or "" when it carries none.
Prefix string
// ProjectID is the substrate's project identity, or "" when it carries
// none.
//
// THE TWO ARE READ AS ONE SNAPSHOT wherever the substrate publishes a
// transaction, so a caller never sees a prefix from before a bootstrap
// beside a project id from after one. That matters because the pair is what
// a caller compares against a local metadata.json, and a torn read there
// looks exactly like the cross-project mismatch the comparison exists to
// find.
ProjectID string
}
// InitVerifier describes READING A SUBSTRATE'S IDENTITY: the prefix and project
// id `bd init` reconciles against, adopts, or refuses to invent.
//
// IT IS A SEPARATE ROLE FROM Bootstrapper, AND NOT ITS READ HALF. The
// precedent that would have made them one — VersionReconciler, whose read and
// write are two shapes of one question — does not reach here, because the
// callers are different and so are their PERMISSIONS. bd reads this identity on
// paths where it is forbidden to write one: against a bts-provisioned team
// database, whose identity the provisioning tool owns and bd adopts; against an
// authenticating gateway, whose credential may be read-only and whose
// server-side identity a client must never overwrite. Handing those callers a
// surface with a write on it is exactly the shape that produced the writes they
// now have to suppress flag by flag. A capability a caller must not have is a
// capability it should not be able to reach.
//
// THE ONE PROMISE EVERYTHING ELSE HERE IS FOR: an ABSENT identity and an
// UNREADABLE one are different answers. Absent is "" with a nil error;
// unreadable is an error. Nothing in this role ever reports a failed read as an
// empty answer, because every caller then decides the same thing from it — an
// unprovisioned database gets bootstrapped or refused as a provisioning-contract
// violation, and a database that merely could not be reached must get neither.
// A flaky connection misread as an empty database is how a workspace acquires a
// second identity.
//
// IT WRITES NOTHING. Not the keys it reads, not a marker that it ran, and no
// version-control entry. A verifier that repaired what it found would be the
// bootstrap this role exists to keep separate.
//
// There is NO HTTP surface, for the reason recorded on Bootstrapper: the
// identity a remote caller can act on is already published as
// ContextResponse.project_id on GET /v0/beads/context, and a second spelling of
// one fact is a second thing to keep true.
//
// Deterministic request-validation failures match ErrValidation; result values
// are unspecified when error is non-nil.
type InitVerifier interface {
// VerifyIdentity returns the substrate's identity as it stands.
//
// It answers "" for each marker the substrate does not carry, reports a
// read failure as an ERROR rather than as absence, and writes nothing.
VerifyIdentity(ctx context.Context, req VerifyIdentityRequest) (VerifyIdentityResult, error)
}