From 479f170aa694eaed2e703c91c346b677f4fb88a7 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 20 Oct 2026 13:58:13 -0400 Subject: [PATCH 1/5] Add design spec: Recognize the docket branch by its shape in the everyday repository commands --- ...walking-all-of-main-s-history-to-design.md | 202 ++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 docs/superpowers/specs/2026-10-20-stop-repository-prepare-re-walking-all-of-main-s-history-to-design.md 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. From ff5ec682aa034f3a3ccca45cd117272a5c19cb30 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 20 Oct 2026 14:10:05 -0400 Subject: [PATCH 2/5] refactor(repository): factor the structural ownership steps into a quick check --- internal/app/metadata_ownership.go | 59 ++++++-- .../app/repoownership_integration_test.go | 133 ++++++++++++++++++ 2 files changed, 180 insertions(+), 12 deletions(-) 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..ed16c521b 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 From 168a4b3c2433c5e35fe6e8ee3a7b0c27c8e2f5d4 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 20 Oct 2026 14:20:01 -0400 Subject: [PATCH 3/5] fix(repository): recognize the docket branch by its shape in prepare, check, repair, and configure --- .../app/repoownership_integration_test.go | 135 +++++++++++++++++- internal/app/repoprepare_integration_test.go | 12 +- internal/app/repository_check.go | 17 ++- internal/app/repository_migrate.go | 15 +- internal/app/repository_prepare.go | 28 ++-- internal/app/repository_repair.go | 2 +- 6 files changed, 169 insertions(+), 40 deletions(-) diff --git a/internal/app/repoownership_integration_test.go b/internal/app/repoownership_integration_test.go index ed16c521b..cf3d8a958 100644 --- a/internal/app/repoownership_integration_test.go +++ b/internal/app/repoownership_integration_test.go @@ -910,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 @@ -1001,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. @@ -1016,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..f828e6a64 100644 --- a/internal/app/repository_prepare.go +++ b/internal/app/repository_prepare.go @@ -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_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, From b5a0f58a7d5bf8cda01e0d735332ff858149f517 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 20 Oct 2026 14:22:01 -0400 Subject: [PATCH 4/5] fix(repository): name the structural reason in the foreign docket branch finding --- internal/app/repository_prepare.go | 4 ++-- internal/app/repository_prepare_test.go | 6 ++++++ internal/reposetup/classify.go | 9 ++++++--- internal/reposetup/classify_test.go | 2 +- internal/reposetup/health.go | 13 +++++++++++-- internal/reposetup/health_test.go | 25 +++++++++++++++++++++++++ internal/reposetup/probe.go | 4 ++-- 7 files changed, 53 insertions(+), 10 deletions(-) diff --git a/internal/app/repository_prepare.go b/internal/app/repository_prepare.go index f828e6a64..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 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/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. From 7d83a4d05c1be983bd1908b89f3c5b00903060ca Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Tue, 20 Oct 2026 14:36:21 -0400 Subject: [PATCH 5/5] test(bashupgrade): prove the full ownership check still accepts every saved Bash-made docket branch repository prepare and check now decide ownership with the quick structural check, so the Bash upgrade ownership test no longer exercised the full proof (seed receipts and content equivalence) against the real Bash-made shapes. Add a leg that runs the unauthorized repository migrate preview, which routes through the full proof, and require its no-op on each saved case. The doc comment now says which check each command runs. --- .../bashupgrade_integration_test.go | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) 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) {