diff --git a/docs/superpowers/specs/2026-10-20-stop-repository-prepare-re-walking-all-of-main-s-history-to-design.md b/docs/superpowers/specs/2026-10-20-stop-repository-prepare-re-walking-all-of-main-s-history-to-design.md new file mode 100644 index 000000000..5912c8197 --- /dev/null +++ b/docs/superpowers/specs/2026-10-20-stop-repository-prepare-re-walking-all-of-main-s-history-to-design.md @@ -0,0 +1,202 @@ +# Recognize the docket branch by its shape in the everyday repository commands + +Change 0574 — Recognize the docket branch by its shape in the everyday repository commands + +## Why + +`docket repository prepare` took 68.7 seconds on this repository on 2026-10-20 (29s user, 24s +system CPU). Prepare runs at the start of nearly every docket workflow, so every one of them pays +it. `repository check`, `repository repair`, `repository configure-tests`, and `repository +configure-harnesses` pay the same cost for the same reason. + +The cause is the metadata-ownership verifier, `verifyMetadataOwnership` +(`internal/app/metadata_ownership.go`). It first runs two cheap structural checks on the fetched +metadata tip: the branch has exactly one parentless root, and it shares no history with the +integration branch. It then looks for proof that the root is a docket seed. A root carrying a +docket seed receipt, or an empty tree, is proved instantly. A root with no receipt and a nonempty +tree goes to `verifyLegacyEquivalence`, which walks the complete integration history newest-first, +looking for the snapshot the seed was copied from. On this repository that is 4,474 commits; the +match is commit 4,382 of them. The walk spawns separate git processes per commit (two `ls-tree` +calls per commit, about three more per distinct snapshot, 422 distinct snapshots), roughly 10,000 +git processes in all. Nothing is kept, so every prepare repeats it. + +Every repository seeded by the old Bash migration script has such a root. A repository whose +metadata branch began with an empty first commit already takes the instant path, and its prepare +finishes in a few seconds, mostly fetches. + +The content proof exists to tell docket's own metadata branch apart from a branch somebody else +happens to have named `docket`. It earns its keep in the two commands that create or destroy +planning data: `repository migrate`, which deletes the planning surface from the integration +branch and must first confirm the metadata branch really holds it, and `repository init`, which +decides whether to adopt an existing branch. The everyday commands only write to the metadata +branch, the same as every docket operation that runs after prepare. For them the two structural +checks catch the realistic accident (an ordinary branch named `docket`, which shares the +integration branch's history), and prepare already refuses when the remote metadata branch stops +building on the local one (`local-metadata-ahead`, `local-metadata-diverged`). + +Change 0378, which introduced the shared verifier, listed bare single-root acceptance as out of +scope. This change deliberately reverses that for the everyday commands only. + +## Goal + +The everyday repository commands (`prepare`, `check`, `repair`, `configure-tests`, +`configure-harnesses`) decide metadata-branch ownership from the branch name plus the two +structural checks, deterministically in the binary. A prepare on this repository takes seconds, +not a minute. + +## Non-goals + +- Retiring `repository migrate`, the old single-branch layout states, or the code that supports + them. Considered and declined during grooming: it is unrelated to the ownership check and about + 1% of the non-test Go. +- Changing `repository init` or `repository migrate`. Both keep the full verifier, history search + included. They run rarely, and they are the commands that create or delete planning data. +- Speeding up the full verifier (for example batching its git calls into one `cat-file + --batch-check` stream). Not needed once the everyday commands skip it. +- The seed receipt format, or how new repositories are seeded. +- The implement-next coordination cost (#360). + +## Anti-goals + +- A cache, stored proof, or receipt written after the fact. That is new state to invalidate, and + the verifier deliberately trusts only receipts on the root commit itself. +- Reading a git error as owned or as foreign. A probe that fails is unknown, and unknown refuses, + exactly as today. +- Any model judgment. The model runs `docket repository prepare` and reads its disposition; the + binary decides. + +## Decisions + +### 1. The quick ownership check + +The branch-name part is unchanged: the existing remote-metadata presence probe (`docket` on the +metadata remote in a shared repository, `dckt` in a private one). Given the fetched metadata tip +and the integration tip, the quick check decides: + +1. **One starting commit.** Exactly one parentless commit is reachable from the metadata tip + (`gitcli` `RootCommits`). More than one means an unrelated history was merged in: foreign. +2. **No shared history with the integration branch.** The metadata tip and the integration tip + have no common ancestor (`gitcli` `HasSharedAncestry`). Shared history means an ordinary branch + cut from the integration branch: foreign. +3. **Errors stay unknown.** A failing probe, or an unknown integration tip, is `RootUnknown` with + the error retained. + +Otherwise the branch is owned (`RootParentless`). The quick check reads no receipt and no file +contents. These are exactly the steps `verifyMetadataOwnership` runs before its receipt and +content proofs today. Factor them into one function that the full verifier calls first, so the +shared steps have a single source. Each command takes about 15ms on this repository (6,112 +metadata commits). + +### 2. Which command uses which check + +The split: commands that create or delete planning data keep the full verifier; every other +command uses the quick check. + +| Command | Where it reads ownership | Ownership check | +|---|---|---| +| `repository prepare` | `prepareAugment` | quick | +| `repository check` | `augmentCheckFacts` | quick | +| `repository configure-tests` | `augmentCheckFacts` | quick | +| `repository configure-harnesses` | `augmentCheckFacts` | quick | +| `repository repair` | `migrateRoute` | quick | +| `repository migrate` | `migrateRoute`, `reconcileResumeSeed` | full, unchanged | +| `repository init` (its adopt-or-refuse decision) | `repository_init.go` | full, unchanged | + +Change `augmentCheckFacts` in place, so `check` and both configure commands agree on what healthy +means. (Leaving the configure commands on the full verifier would keep them at about 70 seconds and +let them refuse a repository `check` calls healthy, sending the user to a dead end.) Private +`repository init` also calls `augmentCheckFacts` once, after it has finished, to report the state +the repository ended in. That report gets the quick check too. It is harmless, because init's own +adopt-or-refuse decision, which runs earlier, keeps the full verifier. + +`repository repair` reaches the verifier through migrate's routing (`migrateRoute`, on the +re-fetched metadata tip). That routing consumes only the verifier's `Shape` (owned / foreign / +unknown), never which proof matched, so the quick check fits it without other changes. Repair +must get the quick check while migrate keeps the full one; migrate's behavior must not change. +Repair never reaches migrate's second verifier call (`reconcileResumeSeed`), because it refuses +the resume-prune phase and points at `repository migrate`. + +### 3. Outcome changes, deliberate + +Under the quick-check commands, these now read as owned instead of foreign: + +- a root with no receipt and a nonempty tree that matches no historical integration snapshot; +- a root whose docket receipt fails validation (malformed trailers, an init receipt over a + nonempty tree, a migrate receipt whose copy digest mismatches or whose source revision is + malformed or unreachable). + +`repository migrate` and `repository init` still refuse them. Everything else is unchanged: +two roots and shared history are foreign, failed probes are unknown, and the dirty, ahead, and +diverged refusals stay. + +This reaches the half-migrated detection. With the quick check, these commands classify "owned +metadata branch, planning surface still on the integration branch" as an interrupted migration +and point at `repository migrate`, which then runs the full verifier and refuses a branch it +cannot prove. That is safe. The same holds for the attach-incomplete partial state +`augmentCheckFacts` sets (`PartialIntegrationPruned`): a branch only the full verifier would reject +can now reach the `attach-incomplete` or `local-metadata-missing` remedies, which point at +`repository migrate`, which refuses it. Leave those remedies as they are (my call); prepare still +attaches the worktree normally. The comment in `reposetup.Classify` saying the +partial state "resolves here only because the RootForeign case above already claimed the +non-corresponding seed tree as conflict" stops being true for the quick-check callers; rewrite it. +The `RootShape` doc comments in `internal/reposetup/probe.go` describe owned as "a verified +docket seed root"; reword them to mean "proven owned by the caller's ownership check", quick or +full, and say which commands use which. + +### 4. Finding text + +The `metadata-root-foreign` text lives in two places, and the reason is now structural in both: + +- `internal/reposetup/health.go`, used by `check` and the configure commands: "The remote docket + branch is not a docket-created orphan root (foreign or non-corresponding tree)." +- `prepareRoute` (`internal/app/repository_prepare.go`), used by prepare: "The remote docket + branch is not a docket-created parentless orphan root." + +Reword both in plain words: what was found (the remote metadata branch has more than one starting +commit, or shares history with the integration branch), that docket therefore will not treat it +as its own, and the remedy (leave it unchanged, resolve it with a human). The code stays +`metadata-root-foreign`. Migrate's and init's own refusal text is unchanged. Repair's foreign +refusal comes from the routing it shares with migrate ("not a verified docket metadata branch"), +which is still accurate. It may keep that text unless the builder splits the routing. + +### 5. ADR (my call) + +Record a new ADR through `docket-adr` during the build. Decision: the everyday repository commands +(prepare, check, repair, configure-tests, configure-harnesses) recognize the metadata branch by +name and shape; the content proof +(receipts, legacy equivalence) is reserved for the commands that create or delete planning data +(init, migrate). Alternatives considered: batching the history walk (fast, but keeps a full walk +on every command for no everyday benefit), caching the proof (new state to invalidate), name only +(adopts an ordinary branch someone named `docket`), and retiring migrate (unrelated to ownership). +The ADR exists so a later change does not quietly put the content proof back into prepare. + +### 6. Tests + +- **The everyday commands no longer run the content proof.** A fixture whose metadata root has no + receipt, a nonempty tree, and no matching integration snapshot: prepare reaches a healthy + disposition, check reports no `metadata-root-foreign`, `configure-tests` is not refused on + ownership, and a repair preview reaches its already-migrated phase instead of refusing as + foreign. `repository migrate` on the same fixture still refuses it as foreign. This is the + deterministic stand-in for the speed fix; there is no wall-clock assertion. +- **The structural checks still refuse.** For prepare, check, and repair: two parentless roots + are foreign, shared history with the integration branch is foreign, and an unreadable tip or + unknown integration tip is unknown. Mutation-test each structural check: remove it and watch its + test redden. +- **Existing tests.** Command-level tests that expect prepare or check to report foreign for a + content or receipt mismatch (for example `TestIntegrationRepoOwnershipCheckForeignNonemptyRoot`) + flip to the new expectation. Verifier-level tests of `verifyMetadataOwnership` stay, because + migrate and init still use it. Sweep every test that references `RootForeign`, + `metadata-root-foreign`, or the verifier; today that includes `finding_codes_test.go`, + `repoownership_integration_test.go`, `repoprepare_integration_test.go`, + `repository_prepare_test.go`, `internal/bashupgrade/bashupgrade_integration_test.go`, and the + `reposetup` classify and health tests. +- **Acceptance by hand**, recorded in the results file: time `docket repository prepare + --repo-dir --json`, `docket repository check`, and a `docket repository + repair` preview on this repository with the new binary. Each takes seconds. + +## Left to the builder + +- Function names and how the shared structural steps are factored. +- How repair's routing receives the quick check while migrate keeps the full verifier (a + parameter on the shared routing, or a split). +- Exact finding wording, within decision 4. diff --git a/internal/app/metadata_ownership.go b/internal/app/metadata_ownership.go index d85ff6584..8eae21cf8 100644 --- a/internal/app/metadata_ownership.go +++ b/internal/app/metadata_ownership.go @@ -19,6 +19,7 @@ const ( proofMigrateReceipt // OpMigrateSeed receipt, source reachable, CopyDigest == root tree proofLegacyEmpty // receiptless empty-tree root (legacy bootstrap) proofLegacyEquivalent // receiptless root exactly equal to a historical source projection (Task 4) + proofShape // structural only (one parentless root, disjoint from integration); set by the quick check the everyday commands use ) // metadataOwnership is the shared verifier's result. It is never a boolean: @@ -33,19 +34,29 @@ type metadataOwnership struct { Err error // retained diagnostics when Shape is RootUnknown } -// verifyMetadataOwnership decides, at a single pinned metadata tip, whether the -// tip's sole parentless-root lineage is a verified docket seed root -// (RootParentless, with permitted descendants and merges), readable evidence -// with no ownership proof (RootForeign), or incomplete/unreadable evidence -// (RootUnknown). Every probe error maps to RootUnknown with the error retained — -// never collapsed into absence or into foreign — and a receipt that claims -// docket provenance but fails validation is foreign, never downgraded to the -// receiptless legacy path. Receipt trailers are read from the ROOT COMMIT -// ITSELF: a valid receipt on a descendant cannot authorize an unrecognized root. +// ownershipCheck is the signature shared by the full verifier +// (verifyMetadataOwnership) and the quick structural check +// (quickOwnershipCheck), so a caller can be handed either one. +type ownershipCheck func(ctx context.Context, git *gitcli.Client, repo gitcli.Repository, tip, integrationTip gitcli.ObjectID, defaultBranch string) metadataOwnership + +// quickOwnershipCheck adapts verifyMetadataShape to ownershipCheck; the default +// branch is unused because the quick check reads no historical configuration. +func quickOwnershipCheck(ctx context.Context, git *gitcli.Client, repo gitcli.Repository, tip, integrationTip gitcli.ObjectID, _ string) metadataOwnership { + return verifyMetadataShape(ctx, git, repo, tip, integrationTip) +} + +// verifyMetadataShape is the quick ownership check. At a single pinned metadata +// tip it runs only the two structural steps: exactly one parentless root is +// reachable from tip (more than one is RootForeign), and tip shares no history +// with integrationTip (shared history is RootForeign). It reads no receipt and +// no file contents. Every probe error, and an unknown integrationTip, maps to +// RootUnknown with the error retained — never foreign, never owned. Otherwise +// the result is RootParentless with proofShape. // -// defaultBranch is threaded through for the legacy historical-config resolution -// (Task 4); it is unused by the topology and native-receipt proofs here. -func verifyMetadataOwnership(ctx context.Context, git *gitcli.Client, repo gitcli.Repository, tip, integrationTip gitcli.ObjectID, defaultBranch string) metadataOwnership { +// The everyday repository commands (prepare, check, repair, configure-tests, +// configure-harnesses) decide ownership with it; verifyMetadataOwnership runs it +// first, so these structural steps have one source. +func verifyMetadataShape(ctx context.Context, git *gitcli.Client, repo gitcli.Repository, tip, integrationTip gitcli.ObjectID) metadataOwnership { own := metadataOwnership{Tip: tip, Shape: reposetup.RootUnknown} roots, err := git.RootCommits(ctx, repo, tip) if err != nil { @@ -70,6 +81,30 @@ func verifyMetadataOwnership(ctx context.Context, git *gitcli.Client, repo gitcl own.Shape = reposetup.RootForeign return own } + own.Shape, own.Proof = reposetup.RootParentless, proofShape + return own +} + +// verifyMetadataOwnership is the full verifier, reserved for repository init +// and repository migrate, the commands that create or delete planning data. It +// runs verifyMetadataShape first, then decides whether the tip's sole +// parentless-root lineage is a verified docket seed root +// (RootParentless, with permitted descendants and merges), readable evidence +// with no ownership proof (RootForeign), or incomplete/unreadable evidence +// (RootUnknown). Every probe error maps to RootUnknown with the error retained — +// never collapsed into absence or into foreign — and a receipt that claims +// docket provenance but fails validation is foreign, never downgraded to the +// receiptless legacy path. Receipt trailers are read from the ROOT COMMIT +// ITSELF: a valid receipt on a descendant cannot authorize an unrecognized root. +// +// defaultBranch is threaded through for the legacy historical-config resolution +// (Task 4); it is unused by the topology and native-receipt proofs here. +func verifyMetadataOwnership(ctx context.Context, git *gitcli.Client, repo gitcli.Repository, tip, integrationTip gitcli.ObjectID, defaultBranch string) metadataOwnership { + own := verifyMetadataShape(ctx, git, repo, tip, integrationTip) + if own.Shape != reposetup.RootParentless { + return own + } + own.Shape, own.Proof = reposetup.RootUnknown, proofNone // receipt/content proofs below decide // Receipt trailers are read from the ROOT COMMIT ITSELF; a valid receipt on // a descendant cannot authorize an unrecognized root. The root is parentless, // so a scan from the root sees exactly the root. diff --git a/internal/app/repoownership_integration_test.go b/internal/app/repoownership_integration_test.go index 815f6c55f..cf3d8a958 100644 --- a/internal/app/repoownership_integration_test.go +++ b/internal/app/repoownership_integration_test.go @@ -441,6 +441,29 @@ func TestIntegrationRepoOwnershipUnreadableTipIsUnknown(t *testing.T) { } } +// A probe error AFTER the structural steps pass must still be RootUnknown. A +// migrate receipt naming a well-formed but absent source revision makes the +// reachability probe fail. This pins the full verifier's reset of the quick +// check's RootParentless back to RootUnknown before its receipt/content proofs: +// without it, this probe error would return owned. +func TestIntegrationRepoOwnershipMigrateReceiptAbsentSourceIsUnknown(t *testing.T) { + f := newOwnFixture(t) + proj := f.mktree(map[string]string{"docs/changes/active/0001-a.md": "a\n"}) + root := f.commitTree(proj, nil, seedMessage("migrate absent source", + opTrailer(reposetup.OpMigrateSeed), + srcTrailer(strings.Repeat("b", 40)), // well-formed, but no such object + copyTrailer(proj), + repairTrailer("deadbeef"))) + + own := f.verify(t, gitcli.ObjectID(root), gitcli.ObjectID(f.mainTip())) + if own.Shape != reposetup.RootUnknown { + t.Fatalf("Shape = %v Proof = %d, want RootUnknown when the source reachability probe fails (err=%v)", own.Shape, own.Proof, own.Err) + } + if own.Err == nil { + t.Error("Err is nil, want the retained probe error") + } +} + func TestIntegrationRepoOwnershipUnknownIntegrationTipIsUnknown(t *testing.T) { f := newOwnFixture(t) et := f.emptyTree() @@ -458,6 +481,116 @@ func TestIntegrationRepoOwnershipUnknownIntegrationTipIsUnknown(t *testing.T) { } } +// --- Quick (structural-only) ownership check --------------------------------- +// +// verifyMetadataShape runs only the two structural steps: one parentless root, +// and no shared history with the integration branch. It reads no receipt and no +// file contents, so a root the full verifier refuses on content grounds is owned +// here. The full-verifier assertions in the last two subtests prove the fixture +// really exercises that gap. + +// verifyShape runs the quick structural check against this fixture. +func (f *ownFixture) verifyShape(t *testing.T, tip, integration gitcli.ObjectID) metadataOwnership { + t.Helper() + return verifyMetadataShape(context.Background(), newGitClient(t), gitcli.Repository{PrimaryWorktree: f.dir}, tip, integration) +} + +func TestIntegrationRepoOwnershipShapeCheck(t *testing.T) { + t.Run("two parentless roots", func(t *testing.T) { + f := newOwnFixture(t) + et := f.emptyTree() + r1 := f.commitTree(et, nil, "root one") + r2 := f.commitTree(f.mktree(map[string]string{"a": "1\n"}), nil, "root two") + merge := f.commitTree(et, []string{r1, r2}, "merge of two orphan roots") + + own := f.verifyShape(t, gitcli.ObjectID(merge), gitcli.ObjectID(f.mainTip())) + if own.Shape != reposetup.RootForeign { + t.Fatalf("Shape = %v, want RootForeign for two parentless roots (err=%v)", own.Shape, own.Err) + } + }) + + t.Run("shared ancestry", func(t *testing.T) { + f := newOwnFixture(t) + foreign := f.commitTree( + f.mktree(map[string]string{"docs/changes/active/0001-a.md": "a\n"}), + []string{f.mainTip()}, + seedMessage("docket metadata seed", opTrailer(reposetup.OpInitRoot))) + + own := f.verifyShape(t, gitcli.ObjectID(foreign), gitcli.ObjectID(f.mainTip())) + if own.Shape != reposetup.RootForeign { + t.Fatalf("Shape = %v, want RootForeign for shared ancestry with integration (err=%v)", own.Shape, own.Err) + } + }) + + t.Run("unreadable tip", func(t *testing.T) { + f := newOwnFixture(t) + own := f.verifyShape(t, gitcli.ObjectID(strings.Repeat("a", 40)), gitcli.ObjectID(f.mainTip())) + if own.Shape != reposetup.RootUnknown { + t.Fatalf("Shape = %v, want RootUnknown for an absent tip object", own.Shape) + } + if own.Err == nil { + t.Error("Err is nil, want the retained probe error") + } + }) + + t.Run("unknown integration tip", func(t *testing.T) { + f := newOwnFixture(t) + root := f.commitTree(f.emptyTree(), nil, seedMessage("docket init", opTrailer(reposetup.OpInitRoot))) + + own := f.verifyShape(t, gitcli.ObjectID(root), "") + if own.Shape != reposetup.RootUnknown { + t.Fatalf("Shape = %v, want RootUnknown when disjointness is unprovable", own.Shape) + } + if own.Err == nil { + t.Fatal("Err is nil, want the retained diagnostic") + } + // Pin the guard's own text: without the guard the ancestry probe would + // still error into RootUnknown, hiding its removal. + if !strings.Contains(own.Err.Error(), "integration tip unknown") { + t.Errorf("Err = %v, want the integration-tip-unknown diagnostic", own.Err) + } + }) + + t.Run("receiptless nonempty root with no matching snapshot is owned", func(t *testing.T) { + f := newOwnFixture(t) // main carries only README: no historical snapshot can match + root := f.commitTree(f.mktree(map[string]string{"docs/changes/active/zzz.md": "x\n"}), nil, "receiptless seed") + desc := f.commitTree(f.mktree(map[string]string{"docs/changes/active/zzz.md": "y\n"}), []string{root}, "meta 1") + + own := f.verifyShape(t, gitcli.ObjectID(desc), gitcli.ObjectID(f.mainTip())) + if own.Shape != reposetup.RootParentless { + t.Fatalf("quick Shape = %v, want RootParentless (err=%v)", own.Shape, own.Err) + } + if own.Proof != proofShape { + t.Errorf("quick Proof = %d, want proofShape", own.Proof) + } + if own.Root != gitcli.ObjectID(root) { + t.Errorf("quick Root = %s, want %s", own.Root, root) + } + if own.Tip != gitcli.ObjectID(desc) { + t.Errorf("quick Tip = %s, want %s", own.Tip, desc) + } + full := f.verify(t, gitcli.ObjectID(desc), gitcli.ObjectID(f.mainTip())) + if full.Shape != reposetup.RootForeign { + t.Fatalf("full Shape = %v, want RootForeign: the fixture must exercise the content-proof gap (err=%v)", full.Shape, full.Err) + } + }) + + t.Run("invalid receipt is owned", func(t *testing.T) { + f := newOwnFixture(t) + root := f.commitTree(f.mktree(map[string]string{"docs/changes/active/0001-a.md": "a\n"}), nil, + seedMessage("init but nonempty", opTrailer(reposetup.OpInitRoot))) + + own := f.verifyShape(t, gitcli.ObjectID(root), gitcli.ObjectID(f.mainTip())) + if own.Shape != reposetup.RootParentless { + t.Fatalf("quick Shape = %v, want RootParentless (err=%v)", own.Shape, own.Err) + } + full := f.verify(t, gitcli.ObjectID(root), gitcli.ObjectID(f.mainTip())) + if full.Shape != reposetup.RootForeign { + t.Fatalf("full Shape = %v, want RootForeign for an init receipt over a nonempty tree (err=%v)", full.Shape, full.Err) + } + }) +} + // --- Task 4: receiptless legacy exact-tree equivalence ------------------------ // // A receiptless NONEMPTY orphan root is proven (or refused) by exact-tree @@ -777,7 +910,7 @@ func TestIntegrationRepoOwnershipLegacyUnreadableHistoryIsUnknown(t *testing.T) } } -// --- Check-level scenarios: augmentCheckFacts consumes the verifier ----------- +// --- Check-level scenarios: augmentCheckFacts consumes the quick check -------- // // These drive the read-only `repository check` service end to end against the // real bare-upstream + clone fixture (newHealthyRepo, from @@ -868,10 +1001,16 @@ func TestIntegrationRepoOwnershipCheckDescendantsPreserveFrontmatterFindings(t * } } -// TestIntegrationRepoOwnershipCheckForeignNonemptyRoot proves a single-root -// nonempty metadata branch that carries no seed receipt and matches no historical -// snapshot is still reported foreign at the check boundary. -func TestIntegrationRepoOwnershipCheckForeignNonemptyRoot(t *testing.T) { +// TestIntegrationRepoOwnershipCheckReceiptlessNonemptyRootIsOwned proves the +// everyday check no longer runs the content proof: a single-root nonempty +// metadata branch that carries no seed receipt and matches no historical +// snapshot passes the quick structural check (one parentless root, no shared +// history with the integration branch), so check reports no +// metadata-root-foreign. repository migrate still runs the full verifier and +// refuses such a root (TestIntegrationRepoOwnershipEverydayCommandsSkipContentProof). +// The local docket branch is left unsynced, so the state may be conflict for +// that reason; only the foreign finding is asserted. +func TestIntegrationRepoOwnershipCheckReceiptlessNonemptyRootIsOwned(t *testing.T) { r := newHealthyRepo(t) // Replace origin/docket with a disjoint parentless NONEMPTY commit (built on an // orphan branch in the writer clone) carrying no receipt. @@ -883,8 +1022,123 @@ func TestIntegrationRepoOwnershipCheckForeignNonemptyRoot(t *testing.T) { runGit(t, r.writer, "push", "-q", "-f", "origin", "foreign-docket:docket") res := r.runCheck(t) - if !findingWithCode(res, "metadata-root-foreign") { - t.Errorf("foreign nonempty root not reported foreign; state=%q findings=%+v", res.RepositoryState, res.Findings) + if findingWithCode(res, "metadata-root-foreign") { + t.Errorf("check reported metadata-root-foreign for a structurally owned receiptless nonempty root; state=%q findings=%+v", res.RepositoryState, res.Findings) + } +} + +// publishReceiptlessLegacyRoot replaces origin/docket with a parentless, +// receiptless, NONEMPTY root (one valid change record) that matches no +// integration snapshot, then moves the invocation clone's .docket worktree +// (and so its local docket branch) to it, so local and remote stay in sync. +func (r *initRepo) publishReceiptlessLegacyRoot(t *testing.T) string { + t.Helper() + wf := &ownFixture{t: t, dir: r.writer} + tree := wf.mktree(map[string]string{"docs/changes/active/0001-legacy.md": changeRecord(1, "legacy", "Legacy seed")}) + tip := r.publishCraftedDocket(t, wf.commitTree(tree, nil, "legacy seed")) + dotDocket := filepath.Join(r.invocation, ".docket") + runGit(t, dotDocket, "fetch", "-q", "origin", "docket") + runGit(t, dotDocket, "reset", "-q", "--hard", "FETCH_HEAD") + return tip +} + +// TestIntegrationRepoOwnershipEverydayCommandsSkipContentProof is the +// deterministic stand-in for the speed fix: on a metadata root the full +// verifier rejects only on content (receiptless, nonempty, no matching +// snapshot), the everyday commands decide ownership from shape alone and accept +// it, while repository migrate keeps the full verifier and still refuses it. +func TestIntegrationRepoOwnershipEverydayCommandsSkipContentProof(t *testing.T) { + r := newHealthyRepo(t) + tip := r.publishReceiptlessLegacyRoot(t) + + // Oracle: the full verifier rejects this root, so the fixture exercises the + // content-proof gap rather than a root either check would accept. + integration := runGit(t, r.invocation, "rev-parse", "origin/main") + if own := verifyMetadataOwnership(context.Background(), newGitClient(t), gitcli.Repository{PrimaryWorktree: r.invocation}, + gitcli.ObjectID(tip), gitcli.ObjectID(integration), "main"); own.Shape != reposetup.RootForeign { + t.Fatalf("full verifier Shape = %v (err=%v), want RootForeign: the fixture would prove nothing", own.Shape, own.Err) + } + + if res := runPrepareAt(t, r.invocation); res.Disposition != PrepareDispositionNoOp || prepareFinding(res, "metadata-root-foreign") { + t.Errorf("prepare disposition = %q, findings = %+v; want no-op with no metadata-root-foreign", res.Disposition, res.Findings) + } + + check := r.runCheck(t) + if check.RepositoryState != string(reposetup.StateHealthy) { + t.Errorf("check RepositoryState = %q (%s), want healthy", check.RepositoryState, check.HumanText()) + } + if findingWithCode(check, "metadata-root-foreign") { + t.Errorf("check reported metadata-root-foreign:\n%s", check.HumanText()) + } + if code := check.CheckExitCode(); code != 0 { + t.Errorf("check exit = %d (%s), want 0", code, check.HumanText()) + } + + if ct := r.runConfigureTests(t); ct.Result == ResultInvalidState || ct.RepositoryState == string(reposetup.StateConflict) { + t.Errorf("configure-tests = %q / %q (%s), want not refused on ownership", ct.Result, ct.RepositoryState, ct.HumanText()) + } + + repair := r.runRepair(t, RepairOptions{}) + if repair.RepositoryState == string(reposetup.StateConflict) { + t.Errorf("repair preview RepositoryState = conflict (%s), want it past the ownership routing", repair.HumanText()) + } + if repair.SourceRevision != tip { + t.Errorf("repair preview SourceRevision = %q, want the crafted tip %q (the already-migrated phase pins it)", repair.SourceRevision, tip) + } + + // Migrate last: it keeps the full verifier and refuses the unprovable root. + mig := r.runMigrate(t, MigrateOptions{}) + if mig.RepositoryState != string(reposetup.StateConflict) { + t.Errorf("migrate RepositoryState = %q (%s), want conflict", mig.RepositoryState, mig.HumanText()) + } + if !strings.Contains(mig.HumanText(), "not a verified docket metadata branch") { + t.Errorf("migrate text %q must refuse the branch as not a verified docket metadata branch", mig.HumanText()) + } +} + +// TestIntegrationRepoOwnershipEverydayCommandsRefuseStructuralForeign proves the +// quick check still refuses both structural shapes in prepare, check, and +// repair: a metadata branch with two parentless roots, and one sharing history +// with the integration branch. The local docket branch is not synced; the +// foreign verdict comes first in every route. +func TestIntegrationRepoOwnershipEverydayCommandsRefuseStructuralForeign(t *testing.T) { + cases := []struct { + name string + craft func(t *testing.T, r *initRepo, wf *ownFixture) string + }{ + {"two parentless roots", func(t *testing.T, r *initRepo, wf *ownFixture) string { + runGit(t, r.writer, "fetch", "-q", "origin", "docket") + root1 := runGit(t, r.writer, "rev-parse", "FETCH_HEAD") + root2 := wf.commitTree(wf.mktree(map[string]string{"other.txt": "unrelated\n"}), nil, "second root") + return wf.commitTree(wf.emptyTree(), []string{root1, root2}, "merge an unrelated history") + }}, + {"shared ancestry", func(t *testing.T, r *initRepo, wf *ownFixture) string { + runGit(t, r.writer, "fetch", "-q", "origin", "main") + mainTip := runGit(t, r.writer, "rev-parse", "FETCH_HEAD") + tree := wf.mktree(map[string]string{"docs/changes/active/0001-x.md": changeRecord(1, "x", "X")}) + return wf.commitTree(tree, []string{mainTip}, "docket cut from integration") + }}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + r := newHealthyRepo(t) + wf := &ownFixture{t: t, dir: r.writer} + r.publishCraftedDocket(t, tc.craft(t, r, wf)) + + if res := runPrepareAt(t, r.invocation); res.Disposition != PrepareDispositionRefused || !prepareFinding(res, "metadata-root-foreign") { + t.Errorf("prepare disposition = %q, findings = %+v; want refused with metadata-root-foreign", res.Disposition, res.Findings) + } + if check := r.runCheck(t); !findingWithCode(check, "metadata-root-foreign") { + t.Errorf("check did not report metadata-root-foreign; state=%q findings=%+v", check.RepositoryState, check.Findings) + } + repair := r.runRepair(t, RepairOptions{}) + if repair.RepositoryState != string(reposetup.StateConflict) { + t.Errorf("repair RepositoryState = %q (%s), want conflict", repair.RepositoryState, repair.HumanText()) + } + if !strings.Contains(repair.HumanText(), "not a verified docket metadata branch") { + t.Errorf("repair text %q must refuse the branch as not a verified docket metadata branch", repair.HumanText()) + } + }) } } diff --git a/internal/app/repoprepare_integration_test.go b/internal/app/repoprepare_integration_test.go index 3137904d8..f81868ecf 100644 --- a/internal/app/repoprepare_integration_test.go +++ b/internal/app/repoprepare_integration_test.go @@ -30,11 +30,11 @@ import ( // earlier copied predicate in prepareAugment (`len(roots)==1 && roots[0]==tip`) // misclassified every such chain as RootForeign — the root is not the tip once a // descendant lands — and refused every real docket repository. prepareAugment now -// consumes the shared verifyMetadataOwnership verifier (the same one -// repository_check.go uses), which proves the init-seed root owns the chain +// consumes the quick structural check verifyMetadataShape (the same one +// repository_check.go uses), which proves the sole parentless root owns the chain // (RootParentless) regardless of how many descendants sit on top. Under the old -// predicate these scenarios refuse with metadata-root-foreign; under the verifier -// they classify owned and reach their true disposition. +// predicate these scenarios refuse with metadata-root-foreign; under the shape +// check they classify owned and reach their true disposition. // // Every refusal scenario asserts the `.docket` worktree bytes and tip are untouched // AFTER the refusal (positive evidence), not merely that the disposition is refused: @@ -149,8 +149,8 @@ func prepareFinding(res RepositoryPrepareResult, code string) bool { // proof of the prepareAugment rewire: a healthy remote whose docket branch is a real // multi-commit chain (root != tip) is classified OWNED (RootParentless) and prepared, // never refused as a foreign metadata root. Under the old copied root-equals-tip -// predicate this refused with metadata-root-foreign; the shared verifier proves the -// init-seed root owns the whole chain. +// predicate this refused with metadata-root-foreign; the shape check proves the +// sole parentless root owns the whole chain. func TestIntegrationRepoPrepareMultiCommitChainClassifiesOwned(t *testing.T) { r := newPrepareOrigin(t) if n := r.originDocketCommitCount(t); n < 2 { diff --git a/internal/app/repository_check.go b/internal/app/repository_check.go index 595184be5..c32bcfb2b 100644 --- a/internal/app/repository_check.go +++ b/internal/app/repository_check.go @@ -260,12 +260,15 @@ func checkRevisions(facts reposetup.Facts) map[string]string { func augmentCheckFacts(ctx context.Context, git *gitcli.Client, f *reposetup.Facts, sc setupContext) { metaRef := metadataRef(sc.layout) - // Metadata root shape: the shared ownership verifier decides, at the FETCHED - // remote docket tip, whether the tip's sole parentless-root lineage is a - // verified docket seed root (RootParentless — a native init/migrate receipt or - // a receiptless legacy-equivalent tree, with any number of permitted - // descendants and merges; the root need not equal the tip), readable evidence - // with no ownership proof (RootForeign), or unreadable evidence (RootUnknown). + // Metadata root shape: the quick structural check (verifyMetadataShape) + // decides at the FETCHED remote docket tip — exactly one parentless root and + // no shared history with the integration branch is owned (RootParentless, with + // any number of descendants; the root need not equal the tip), more than one + // root or shared history is RootForeign, and a probe error is RootUnknown. It + // reads no receipt and no file contents: the content proof + // (verifyMetadataOwnership) is reserved for init and migrate, the commands + // that create or delete planning data. check, configure-tests, and + // configure-harnesses all read ownership here, so they agree on healthy. // The fetched tip is the single authority (learning // decide-and-act-on-the-same-copy): it becomes RemoteMetadata's reported // revision and the remote side of syncRelationship, so the @@ -284,7 +287,7 @@ func augmentCheckFacts(ctx context.Context, git *gitcli.Client, f *reposetup.Fac f.MetadataRoot = reposetup.RootUnknown } else { f.RemoteMetadata.Tip = string(rev.Commit) - own := verifyMetadataOwnership(ctx, git, sc.repo, rev.Commit, gitcli.ObjectID(sc.sourceRevision), sc.defaultBranch) + own := verifyMetadataShape(ctx, git, sc.repo, rev.Commit, gitcli.ObjectID(sc.sourceRevision)) f.MetadataRoot = own.Shape } } diff --git a/internal/app/repository_migrate.go b/internal/app/repository_migrate.go index e4dd1883b..047b3910a 100644 --- a/internal/app/repository_migrate.go +++ b/internal/app/repository_migrate.go @@ -141,7 +141,7 @@ func RunRepositoryMigrate(ctx context.Context, d SetupDeps, o MigrateOptions) Re // selected phase to a result. It is split out so the debris sweep can wrap it // without threading its report through every branch. func migratePhaseDispatch(ctx context.Context, d SetupDeps, o MigrateOptions, facts reposetup.Facts, sc setupContext) RepositoryMigrateResult { - phase, refusal := migrateRoute(ctx, d.Git, facts, &sc) + phase, refusal := migrateRoute(ctx, d.Git, facts, &sc, verifyMetadataOwnership) if refusal != nil { return *refusal } @@ -223,15 +223,20 @@ func migratePhaseDispatch(ctx context.Context, d SetupDeps, o MigrateOptions, fa // migrateRoute classifies the gathered remote postconditions into a migration // phase or a refusal. When the metadata branch is present it fetches it and runs -// the shared ownership verifier (verifyMetadataOwnership) at the re-read remote -// tip — the base gatherer deliberately leaves the root shape unproven so the +// checkOwnership at the re-read remote tip. The routing is shared by migrate and +// repair, which pass different checks: repository migrate passes the full +// verifier (verifyMetadataOwnership), because it deletes the planning surface +// from the integration branch and must first prove the metadata branch holds it; +// repository repair passes the quick structural check (quickOwnershipCheck). +// Only own.Shape is consumed, never which proof matched, so either check fits. +// The base gatherer deliberately leaves the root shape unproven so the // authoritative adopt/conflict decision keys on the promised remote state, not a // gather-time proxy. It pins sc.metadataTip to that re-read tip so a local-finish // resume attaches at the ACTUAL latest tip (not the seed root), and an established // migrated branch is recognized however many descendants it has grown. Every probe // error is surfaced, never read as a clean absence (learning // probe-error-is-not-clean-absence). -func migrateRoute(ctx context.Context, git *gitcli.Client, facts reposetup.Facts, sc *setupContext) (migratePhase, *RepositoryMigrateResult) { +func migrateRoute(ctx context.Context, git *gitcli.Client, facts reposetup.Facts, sc *setupContext, checkOwnership ownershipCheck) (migratePhase, *RepositoryMigrateResult) { if u := migrateUnknownProbes(facts); len(u) > 0 { r := migrateRefusal(reposetup.StateUnknown, "a required repository probe could not be resolved ("+strings.Join(u, ", ")+"); run `docket repository check` after ensuring the remote is configured and reachable") @@ -265,7 +270,7 @@ func migrateRoute(ctx context.Context, git *gitcli.Client, facts reposetup.Facts // established migrated branch with descendants is finished at its latest tip, // never reset to the seed. sc.metadataTip = string(rev.Commit) - own := verifyMetadataOwnership(ctx, git, sc.repo, rev.Commit, gitcli.ObjectID(sc.sourceRevision), sc.defaultBranch) + own := checkOwnership(ctx, git, sc.repo, rev.Commit, gitcli.ObjectID(sc.sourceRevision), sc.defaultBranch) switch own.Shape { case reposetup.RootUnknown: // Incomplete or unreadable evidence: an external failure retaining the probe diff --git a/internal/app/repository_prepare.go b/internal/app/repository_prepare.go index 53c1cc22a..27e05e55b 100644 --- a/internal/app/repository_prepare.go +++ b/internal/app/repository_prepare.go @@ -319,8 +319,8 @@ func prepareRoute(f reposetup.Facts, heldElsewhere prepareHolder) prepareVerdict return prepareRefuseVerdict(reposetup.StateConflict, reposetup.Finding{ Code: string(FCMetadataRootForeign), Severity: reposetup.SeverityError, - Message: "The remote docket branch is not a docket-created parentless orphan root.", - Remedy: "Inspect the remote docket branch and resolve it manually with a human, then run `docket repository check`.", + Message: reposetup.MetadataRootForeignMessage, + Remedy: reposetup.MetadataRootForeignRemedy, }) } // A metadata branch published alongside a still-live integration surface is an @@ -634,19 +634,19 @@ func prepareAugment(ctx context.Context, git *gitcli.Client, f *reposetup.Facts, metaRef := metadataRef(sc.layout) // Metadata root shape at the FETCHED remote docket tip (fetch it first so the - // object is local on a clone that never fetched docket). The shared ownership - // verifier — the same one repository_check.go's augmentCheckFacts consumes via - // `verifyMetadataOwnership(` — decides whether the tip's sole parentless-root - // lineage is a verified docket seed root (RootParentless: a native init/migrate - // receipt or a receiptless legacy-equivalent tree, with ANY number of permitted - // descendants and merges, so the root need NOT equal the tip — a real - // multi-commit docket branch is owned, not foreign), readable evidence with no - // ownership proof (RootForeign), or unreadable evidence (RootUnknown). This - // replaces the earlier copied root-equals-tip predicate, which misclassified - // every real multi-commit docket chain as RootForeign and refused it. A fetch - // error is the safe RootUnknown, which the router refuses on rather than reading - // parentless (never a stale object, never a false shape); the fetched tip is the - // single authority the ownership proof is computed at. + // object is local on a clone that never fetched docket). The quick structural + // check — the same one repository_check.go's augmentCheckFacts consumes via + // `verifyMetadataShape(` — decides: exactly one parentless root and no shared + // history with the integration branch is owned (RootParentless, with ANY number + // of descendants and merges, so the root need NOT equal the tip — a real + // multi-commit docket branch is owned, not foreign), more than one root or + // shared history is RootForeign, and a probe error is RootUnknown. It reads no + // receipt and no file contents: the content proof (verifyMetadataOwnership), + // whose history search costs a full walk of the integration branch, is + // reserved for init and migrate. A fetch error is the safe RootUnknown, which + // the router refuses on rather than reading parentless (never a stale object, + // never a false shape); the fetched tip is the single authority the ownership + // check is computed at. metaTip := sc.metadataTip if metaTip != "" { rev, ferr := git.FetchBranch(ctx, sc.repo, metadataRemote(sc.layout), metaRef) @@ -655,7 +655,7 @@ func prepareAugment(ctx context.Context, git *gitcli.Client, f *reposetup.Facts, } else { metaTip = string(rev.Commit) f.RemoteMetadata.Tip = metaTip - own := verifyMetadataOwnership(ctx, git, sc.repo, rev.Commit, gitcli.ObjectID(sc.sourceRevision), sc.defaultBranch) + own := verifyMetadataShape(ctx, git, sc.repo, rev.Commit, gitcli.ObjectID(sc.sourceRevision)) f.MetadataRoot = own.Shape } } diff --git a/internal/app/repository_prepare_test.go b/internal/app/repository_prepare_test.go index b906677c8..a25ca94fe 100644 --- a/internal/app/repository_prepare_test.go +++ b/internal/app/repository_prepare_test.go @@ -312,6 +312,12 @@ func TestRepositoryPrepareForeignRootRefusesAsForeign(t *testing.T) { if code := findingCode(t, v); code != "metadata-root-foreign" { t.Errorf("finding code = %q, want metadata-root-foreign", code) } + if v.finding.Message != reposetup.MetadataRootForeignMessage { + t.Errorf("finding message = %q, want reposetup.MetadataRootForeignMessage", v.finding.Message) + } + if v.finding.Remedy != reposetup.MetadataRootForeignRemedy { + t.Errorf("finding remedy = %q, want reposetup.MetadataRootForeignRemedy", v.finding.Remedy) + } } // TestRepositoryPrepareUnknownRootRefusesAsReachability — an UNREADABLE remote diff --git a/internal/app/repository_repair.go b/internal/app/repository_repair.go index fd906a77c..4c7fe6a25 100644 --- a/internal/app/repository_repair.go +++ b/internal/app/repository_repair.go @@ -193,7 +193,7 @@ func repairPreflight(ctx context.Context, d SetupDeps) (setupContext, string, *R r := repairFromMigrateResult(migrateGatherFailure(err)) return setupContext{}, "", &r } - phase, refusal := migrateRoute(ctx, d.Git, facts, &sc) + phase, refusal := migrateRoute(ctx, d.Git, facts, &sc, quickOwnershipCheck) if refusal != nil { if refusal.RepositoryState == string(reposetup.StateFresh) { r := repairRefusal(reposetup.StateFresh, diff --git a/internal/bashupgrade/bashupgrade_integration_test.go b/internal/bashupgrade/bashupgrade_integration_test.go index d6b76957d..7b1de7c33 100644 --- a/internal/bashupgrade/bashupgrade_integration_test.go +++ b/internal/bashupgrade/bashupgrade_integration_test.go @@ -22,6 +22,13 @@ var ownershipRefusals = []string{ "metadata-presence-unknown", "docket-dir-foreign", } +// TestIntegrationBashUpgradeOwnership requires every saved Bash-made docket branch +// to be accepted as docket-owned by both ownership checks. repository prepare and +// repository check decide ownership with the quick structural check (one +// parentless root, no history shared with the integration branch); the full proof, +// which also reads seed receipts and compares the root's contents against the +// integration history, runs only in repository init and migrate, so the test +// reaches it through the unauthorized migrate preview. func TestIntegrationBashUpgradeOwnership(t *testing.T) { for _, tag := range savedTags(t) { t.Run(tag, func(t *testing.T) { @@ -49,10 +56,33 @@ func TestIntegrationBashUpgradeOwnership(t *testing.T) { } t.Logf("%s exit %d\nstdout:\n%s\nstderr:\n%s", strings.Join(args, " "), r.Code, r.Stdout, r.Stderr) } + assertMigrateAcceptsOwnership(t, c) }) } } +// assertMigrateAcceptsOwnership runs the unauthorized repository migrate preview on +// the adopted case. migrate routes through the full ownership proof (receipt and +// content equivalence), so on an already-migrated Bash case it must report the +// no-op, never refuse the branch as unverified. The preview writes nothing: it is +// not authorized, and prepare has already attached the .docket worktree. +func assertMigrateAcceptsOwnership(t *testing.T, c *upgradeCase) { + t.Helper() + r := c.run(t, c.Clone, c.Docket, "repository", "migrate", "--json") + t.Logf("repository migrate --json exit %d\nstdout:\n%s\nstderr:\n%s", r.Code, r.Stdout, r.Stderr) + var doc struct { + Result string `json:"result"` + RepositoryState string `json:"repository_state"` + } + if err := json.Unmarshal([]byte(r.Stdout), &doc); err != nil { + t.Fatalf("repository migrate produced no JSON (code %d): %v\nstderr:\n%s", r.Code, err, r.Stderr) + } + if r.Code != 0 || doc.Result != "no-op" { + t.Fatalf("BLOCKED: repository migrate's full ownership proof did not accept the Bash-made docket branch "+ + "(code %d, result %q, state %q)\nstdout:\n%s\nstderr:\n%s", r.Code, doc.Result, doc.RepositoryState, r.Stdout, r.Stderr) + } +} + // TestIntegrationBashUpgradeGuideShape keeps the guide and the step registry in step // both ways, and refuses an unmarked block that runs docket commands. func TestIntegrationBashUpgradeGuideShape(t *testing.T) { diff --git a/internal/reposetup/classify.go b/internal/reposetup/classify.go index a2923589a..ef0b51a25 100644 --- a/internal/reposetup/classify.go +++ b/internal/reposetup/classify.go @@ -81,9 +81,12 @@ func Classify(f Facts) Classification { } // 3. Partial: an interrupted init/migration that is safe to resume. The - // seeded-but-unpruned shape (remote docket proven parentless, integration - // live surface still present) resolves here only because the RootForeign - // case above already claimed the non-corresponding seed tree as conflict. + // seeded-but-unpruned shape is a remote docket branch the caller's ownership + // check proved parentless while the integration live surface is still present. + // Under the quick structural check (prepare, check, repair, configure-tests, + // configure-harnesses) a branch only the full content proof would reject can + // land here. That route is safe: its remedy, `repository migrate`, runs the + // full check and refuses such a branch. if f.RemoteMetadata.Presence == PresencePresent && f.MetadataRoot == RootParentless && f.LiveSurface == PresencePresent { return Classification{State: StatePartial, Reasons: []string{"metadata-seeded-live-surface"}} diff --git a/internal/reposetup/classify_test.go b/internal/reposetup/classify_test.go index 7fb099931..ddc0c6508 100644 --- a/internal/reposetup/classify_test.go +++ b/internal/reposetup/classify_test.go @@ -159,7 +159,7 @@ func TestClassify(t *testing.T) { reasonsReq: true, }, { - // The seed tree does not correspond: the gatherer sets RootForeign, + // The caller's ownership check reports RootForeign, // so the seeded-live-surface shape resolves to conflict, not partial. name: "metadata present + live surface present but root foreign -> conflict", facts: func() Facts { diff --git a/internal/reposetup/health.go b/internal/reposetup/health.go index 169d5c7b1..b35ff1544 100644 --- a/internal/reposetup/health.go +++ b/internal/reposetup/health.go @@ -174,8 +174,8 @@ func findingFor(reason string, f Facts) Finding { return Finding{ Code: "metadata-root-foreign", Severity: SeverityError, - Message: "The remote docket branch is not a docket-created orphan root (foreign or non-corresponding tree).", - Remedy: "Inspect the remote docket branch and resolve it with a human before any repository operation; leave it unchanged.", + Message: MetadataRootForeignMessage, + Remedy: MetadataRootForeignRemedy, } case "docket-dir-foreign": return Finding{ @@ -248,6 +248,15 @@ func findingFor(reason string, f Facts) Finding { } } +// MetadataRootForeignMessage and MetadataRootForeignRemedy are the one copy of +// the metadata-root-foreign finding text. findingFor (check and the configure +// commands) and prepareRoute (prepare) both use them, so the two never drift. The +// message names the structural reason both ownership checks share. +const ( + MetadataRootForeignMessage = "The remote docket branch has more than one starting commit, or shares history with the integration branch, so docket will not treat it as its own." + MetadataRootForeignRemedy = "Leave the remote docket branch unchanged and resolve it with a human, then run `docket repository check`." +) + // TestConfigMissingCode is the stable machine token for the test-policy health // finding: a local suite gate cannot run because no command is configured (or a // legacy `auto` is still declared). Its remedy names `docket repository diff --git a/internal/reposetup/health_test.go b/internal/reposetup/health_test.go index 62c037c53..b77868142 100644 --- a/internal/reposetup/health_test.go +++ b/internal/reposetup/health_test.go @@ -1249,3 +1249,28 @@ func TestRepairFindingFindingCode(t *testing.T) { }) } } + +// TestMetadataRootForeignFindingNamesStructuralReason — the metadata-root-foreign +// finding names the structural reason the everyday commands refuse a branch +// (more than one starting commit, or shared history with the integration +// branch) in plain words, and check and prepare share the same text. +func TestMetadataRootForeignFindingNamesStructuralReason(t *testing.T) { + f := findingFor("metadata-root-foreign", Facts{}) + if f.Code != "metadata-root-foreign" { + t.Errorf("Code = %q, want metadata-root-foreign", f.Code) + } + if f.Message != MetadataRootForeignMessage { + t.Errorf("Message = %q, want MetadataRootForeignMessage", f.Message) + } + if f.Remedy != MetadataRootForeignRemedy { + t.Errorf("Remedy = %q, want MetadataRootForeignRemedy", f.Remedy) + } + for _, want := range []string{"more than one starting commit", "shares history"} { + if !strings.Contains(f.Message, want) { + t.Errorf("Message %q does not name %q", f.Message, want) + } + } + if strings.Contains(f.Message, "docket-created") { + t.Errorf("Message %q still carries the old docket-created wording", f.Message) + } +} diff --git a/internal/reposetup/probe.go b/internal/reposetup/probe.go index 1414bc042..b58745077 100644 --- a/internal/reposetup/probe.go +++ b/internal/reposetup/probe.go @@ -24,8 +24,8 @@ type RootShape int const ( RootUnknown RootShape = iota // incomplete or unreadable evidence — never collapsed into foreign - RootParentless // a verified docket seed root with permitted descendants and merges sharing that root; the root need not equal the tip - RootForeign // readable, exhausted evidence, no ownership proof (no valid seed receipt, no legacy-equivalent tree, or >1 root) + RootParentless // proven owned by the caller's ownership check: the quick structural check (prepare, check, repair, configure-tests, configure-harnesses) or the full content proof (init, migrate); descendants and merges share the one root, which need not equal the tip + RootForeign // readable evidence the caller's check rejects: more than one root or shared history with the integration branch (both checks), or no valid receipt and no legacy-equivalent tree (full check only) ) // BranchFact carries a branch's presence and, when Present, its tip object id.