Skip to content

fork seam check: allow promoting a pending file to a declared seam - #549

Merged
scuttletoby merged 3 commits into
mainfrom
seam-check-promote-pending
Nov 19, 2026
Merged

scuttletoby merged 3 commits into
mainfrom
seam-check-promote-pending

Conversation

@scuttletoby

@scuttletoby scuttletoby commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

Unblocks #542.

#542 makes apps/web/src/components/settings/settingsSearch.ts a declared seam. It moves the file from pending to files and lists its 2 remaining fork lines under added. Main's checker refuses that move. Since #535, a file may leave pending for files only when it has no fork line left. CI runs main's copy of the checker, so #542 can't fix this from inside the PR.

The rule

A pull request may move a file from pending to files while fork lines are left, but only when all of these hold:

  1. The change leaves that file's text alone (a list-only change). Then the lines left are exactly main's ceiling, and lost plays no part, so a stale lost cannot hide an upstream line swapped for a fork line. Trimming the file goes in its own PR under the pending rules; any growth goes in a later PR, judged under the new files entry.
  2. The new entry's added lists exactly as many copies as are left. The number left is the same exact count fork seam check: #506 lens follow-ups (exact pending ceiling, summary, tests) #535 computes: main's ceiling, plus lines added, less lines removed, less upstream lines put back. Fewer copies would leave a line undeclared. More copies would let a later PR add a line without announcing it first. Only added counts here. An announced line is for a future line, and the run from upstream refuses one the file already has.
  3. Each listed line is in the file, with at least the listed number of copies.
  4. No announced line in the new entry is already in the file. An announced line is one a later change adds.

Nothing else in #535 changes:

  • A pending file that stays pending is still held to the exact ceiling.
  • Dropping an entry while lines remain is still refused.
  • Moving a file with "added": [] still needs no fork line left. Its refusal now also names the other fix ("or list exactly those N lines under added"). With no fork line left, the entry must list none (before, any lines passed).
  • A pending file may not gain a fork line, whether it stays in pending or moves. Before, a file that stayed pending could swap an upstream line for a fork line if its own list raised both the ceiling and lost.
  • The own list is still read only to refuse. The PR is judged by main's list and may not grow the file. The new entry takes effect only after the owner merges it, like any seam entry.

Why it is safe, and what fork-follow expects

From upstream (fork-follow.sh, seam_run), a files entry is judged by findSeamBreaches: every copy the head has over upstream must be within added (plus announced). Lost upstream lines are held to lost exactly as they are for a pending file. A files entry is never lowered (lowerList only touches pending and lost). So once the move merges, the next fork-follow run on main checks each moved fork line against the new entry, and a line can't be hidden.

There is one limit. A pull request's run has no upstream commit, so it can check how many fork lines are listed but not which ones they are. If an upstream line is listed in place of a fork line, the count still matches and the PR run passes. The next fork-follow run then refuses main, naming the unlisted line. One test asserts exactly this. The owner checks which lines are listed, the same review every seam entry already gets, with the --from-upstream merge-base command the docs now give. Follow-up #552 moves that check into CI.

I checked this explicitly with an end-to-end test (the command line lets a pull request make a pending file a seam, and fork-follow then passes main). It runs the real checker on a throwaway repository through these steps:

  1. On the upstream → main → PR sequence, the PR is run as fork-checks runs it, with --config-ref set to main, and passes.
  2. The merged head is then run as fork-follow runs it, --from-upstream against the upstream commit, both plain and with --after-rebase --lowered-list. Both pass, and no lowered list is written.

The property test now also checks moves: a list-only move whose entry lists main's real fork lines passes the PR run and the run from upstream, and a move that edits the file while fork lines are left is refused. Every list the PR run accepts passes the run from upstream. The right pending list passes the PR run whenever the change neither grows the file nor gains a fork line, and is refused otherwise.

#542 under the new checker

I ran it as the "Fork lines in upstream files" step does, with this branch's head as --config-ref and current main as the base:

node .github/scripts/fork-seam-check.cjs --config-ref 662f507b93 72f49ee0df c50b20a8ed
Note: this change edits .github/fork-seams.json; it is judged by the list in --config-ref 662f507b93…, not its own. …
Fork lines in upstream files: only the pinned seams (every upstream file it changes; list from --config-ref 662f507b93…).
exit 0

Main's checker on the same commits exits 1 with the refusal quoted in #542. The 2 lines #542 lists are the only lines in the file marked as the fork's, which matches main's ceiling of 2.

Review follow-ups (second commit)

Both reviews said MERGE; these follow-ups are folded in:

  • A move with fork lines left must be a list-only change (review A-1).
  • The "no fork line gained" refusal now covers a file that stays pending too (B-1).
  • The listed-lines check also runs with no fork line left (B-3).
  • An announced line the file already has is refused in a moved entry (B-4).
  • Tests with announced lines in a moved entry (A-3 / B-6), and wording fixes (A-4).
  • Docs give the owner's merge-base check for a move; seam check: verify promoted lines against upstream in CI #552 tracks doing it in CI.

Tests

  • node --test .github/scripts/fork-seam-check.test.cjs: 82 pass. Against the first commit's checker, 6 of them fail; each new refusal and the announced counting each also fail a test when undone one at a time. From the first commit:
    • a list-only promotion with every line declared passes (in any order, with duplicate copies, and with an announced line);
    • a promotion that leaves a line out is refused, as is one listing a line the file lacks, too many copies, a fork line only under announced, or an announced line the file has;
    • a promotion that also edits the file is refused (a line moved out, a swap, a stale-lost swap);
    • a promotion that also adds lines is refused (more lines, or an upstream line swapped for a fork line);
    • the command-line test above;
    • the property-test extension.
    • The fork seam check: #506 lens follow-ups (exact pending ceiling, summary, tests) #535 tests keep their cases and outcomes. Only the expected refusal text changed.
  • Fail before: against main's checker, the 6 new or changed tests fail. The refusal tests fail there only on wording, because main refuses those moves too.
  • node --test .github/scripts/*.test.cjs: 287 pass.
  • vp lint and vp fmt --check: clean (lint has only warnings, none new).

Upstream fit

Only fork files change: .github/scripts/fork-seam-check*.cjs and docs/fork/updates.md. No upstream file gains a line.

General vs project

General: the rule fits any fork that follows upstream with this seam check. A file whose fork lines predate counting can become a declared seam once its lines are named, without moving them out first. Project: none. The only project fact is that #542's settingsSearch.ts entry is the first to need the move, and that is in #542, not here.

🤖 Generated with Claude Code

A pull request may now move a file from "pending" to "files" while fork
lines are left, when the change adds no fork line and the new entry's
"added" lists exactly the copies left, each one the file has. The run
from upstream then holds each of them to that entry. A move with
"added": [] still needs no fork line left, and a pending file that stays
pending keeps the exact ceiling.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

Review (independent lens, head 4d4bd7a)

No blocking findings. The move cannot widen the gate. Every move the PR run accepts either is right or is refused by the next fork-follow run on main. No fork line gets past both runs. node --test .github/scripts/fork-seam-check.test.cjs: 81 pass.

What I checked:

  • Own list is read only to refuse: still true. ownFiles only picks which extra refusal applies. Main's grows > 0 refusal (fork-seam-check.cjs:348-353) still decides growth, whatever the own list says.
  • Duplicates, whitespace, CRLF, invisible characters: these are counted the same way here and in the run from upstream (lineCounts trims; refuseLineBreaks). A look-alike line has 0 copies and is refused.
  • Several files in one PR: each file is judged on its own. A line moved from one pending file to another makes the second grow, which is refused.
  • State: an entry with "added": [] lists 0 and is refused. A missing added makes the list malformed, so listProblem refuses it. A rerun gives the same result. After the move merges, a later PR that edits the file is judged by findSeamBreaches and findLostLines as a seam file, which is stricter than pending. lowerList never touches files, and the end-to-end test shows that --after-rebase --lowered-list writes nothing.
  • fork seams: judge the route tree as generated output; announce the Fork settings page lines #542: its move is list-only (settingsSearch.ts text is unchanged). Its 2 listed lines are the only two // Fork lines in main's copy, and main's exact ceiling is 2.

Findings (most severe first)

1. follow-up (strongly suggested; small): a move that also edits the file is held only by an honest lost, so the docs' "the change adds no fork line" claim does not hold. fork-seam-check.cjs:367 and :387; docs/fork/updates.md:67-68.

  • Failure, run against this head: upstream has a(); b(); c();. Main is that plus forkA();, and p.ts is pending with ceiling 1. A PR replaces b(); with forkB(); and moves p.ts to files with added: ["forkA();"], but leaves lost unchanged. Then grows = 0 and ownGone == mainGone, so want = 1. One line is listed and it is in the file, so the PR run passes. Main now has 2 fork lines against the old ceiling of 1. The next fork-follow refuses main (adds forkB(); and lost 1 > 0). The PR body's sentence "It is also refused when the line count stays level but the fork-line count rises" is true only when the author raises lost.gone by hand. The test at fork-seam-check.test.cjs:2235 covers only that honest case.
  • A second case: a PR deletes upstream b();, keeps forkA();, and leaves lost unchanged. Then want = 0, so a move with "added": [] passes too. Dropping the entry passes as well; that path was already open before this PR.
  • The pending (non-move) path from fork seam check: #506 lens follow-ups (exact pending ceiling, summary, tests) #535 has the same hole, so this PR does not add a new class of problem. But for a move it can be closed cheaply.
  • Fix: when fork lines are left (want > 0), allow the move only if the change leaves the file's text alone (!edited). In that case want is main's exact ceiling, and lost plays no part. fork seams: judge the route tree as generated output; announce the Fork settings page lines #542 already works this way. Any trimming of the file goes in its own PR under the pending rules. Then say in the docs "a list-only change to that file", and add the stale-lost swap as a test that must be refused.

2. follow-up: the PR run still cannot tell an upstream line from a fork line. It can be closed for moves without much work. fork-seam-check.cjs:393-405.

  • Failure (the one already admitted; confirmed): a list-only move that lists a(); (an upstream line) instead of forkA(); passes the PR run. The next fork-follow refuses main. Until an owner sends a list-only fix, a later PR may also delete that upstream a();, because findLostLines on a PR run lets listed lines go. fork-follow then catches that too.
  • The owner-review mitigation is acceptable. Nothing is hidden, because fork-follow fails closed. But each slip costs a red fork-follow and a fix PR.
  • Cheap close: in fork-checks, fetch upstream's default branch read-only, the same fetch fork-follow already does (+HEAD:refs/upstream-head). Take git merge-base $DEFAULT_SHA refs/upstream-head as the upstream commit, and pass it as an optional --upstream <rev> to the checker. For each moved file only, run findSeamBreaches({[file]: ownEntry}, {upstream: true, atBase: upstream text}). Also refuse any listed line whose count is above the head's copies over upstream. Together these make "accepted here ⇒ fork-follow passes" exact for moves. If the fetch fails, keep today's behaviour and print a note.

3. follow-up: one condition has no test. Only added counts toward the move (:393); announced does not. A mutant that counts seamLines(seam) (added plus announced) passes all 81 tests.

  • Failure that mutant would allow: want = 2, with added: ["forkA();"] and announced: ["forkB();"]. That would pass the PR run. fork-follow would later refuse it as a landed announcement.
  • Fix: add one case to the "leaves a fork line out" test with a fork line under announced, and expect (it lists 1;.
  • The other conditions are covered. Dropping want > ceiling, listed !== want or has < count, or weakening !== to <, each fails a test.
  • Related, today's behaviour, no change needed: S4 (an upstream line in added and the fork line under announced) passes the PR run. fork-follow's landed check refuses it, and so does the stale-list test on the PR's tree.

4. follow-up (wording):

  • :379 together with :388 and :397: when the only parts item is the lost one, the message reads "and this change its own "lost" names 1 upstream line gone…". The verb is missing, as the expected text at fork-seam-check.test.cjs:2246 shows. Fix: start that part with "sets its own "lost" to name…".
  • A list-only move is described as "this change changes its lines" even though the file's text is unchanged. Fix: say "moves it" when !edited.
  • docs/fork/updates.md:71: one line now runs far past the wrap width. Re-wrap it.

State question (runs again / stops half-way / old or empty state)

  • Runs again: pure function, same result.
  • Stops half-way: writes nothing (a PR run never lowers).
  • Old list without the new shape: there is no new shape; ownFiles defaults to {}.
  • Empty or missing entry: refused, as described above.
  • A later PR on a promoted file: it is held as a seam, and a listed line it removes is caught by the stale-list test on the PR tree.

The fork-follow end-to-end test (PR run, then --from-upstream both plain and --after-rebase --lowered-list) matches what I traced in seam_run and lowerList.

Verdict: MERGE. Findings 1 to 4 are follow-ups. I suggest doing 1 in this PR, because it is a 3-line guard and #542 already meets it.

@scuttletoby

scuttletoby commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner Author

Review of 4d4bd7a (merge-path lens): no blocking findings

node --test .github/scripts/fork-seam-check.test.cjs: 81 pass. Beyond that I ran probes through the exported findUnlistedChanges / findLostLines / findSeamBreaches (the PR run with main's list and the change's own list, then the run from upstream on the merged head with that list), and ran mutants of the new branch.

Point 1: can the move widen the gate? No, not past fork-follow. The PR run needs the listed count to equal want, needs every listed copy to be in the head, and refuses want > ceiling. I tried these:

  • an upstream line listed in place of a fork line (the case the PR body admits);
  • a swap whose own lost is not updated;
  • an own gone set too high to make room for a spare upstream line in added;
  • padded or whitespace variants (both sides go through lineCounts, which trims; CR/LF in a listed line is refused by parseConfig);
  • duplicate copies (counted per copy);
  • several files in one PR (each one is judged on its own).

Each variant whose list is wrong still passes the PR run, but fork-follow's first, plain seam run on main refuses it (fork-follow.sh:269). That is either the unlisted fork line in findSeamBreaches, or lost being higher than the real count, which a plain run refuses rather than notes. So a wrong list fails closed: the nightly stops, the series is left as it is, and a list-only PR fixes it, which this checker accepts. No fork line ends up allowed that the owner did not see in the new entry.

Point 3: fork-follow and main. A correct move passes both plain and --after-rebase --lowered-list, and nothing is lowered (the CLI test covers this). A wrong move makes fork-follow refuse main, as described above. lowerList never touches files[].added. So if upstream later takes a moved fork line word for word, the entry keeps listing it. That is harmless on PR runs, because the allowance there is reduced by main's own copies.

Findings (all follow-up)

  1. Follow-up, pre-existing since fork seam check: #506 lens follow-ups (exact pending ceiling, summary, tests) #535, worth folding in here: in the stay-pending path the own list can raise the ceiling. .github/scripts/fork-seam-check.cjs:413

    • Scenario: main has pending {"p.ts": 1}, lost {}, and p.ts is a();\nb();\nforkA();. A PR changes b(); to forkB();. Its own list sets pending {"p.ts": 2} and lost {"p.ts": {"lines": 1, "gone": 1}}. The PR run passes (want = 1 + 0 + 1 - 0 = 2 = own), and so does fork-follow on the merged head. A pending file has gained a fork line through a green PR. I confirmed the same result with origin/main's checker.
    • This contradicts :265 ("On a PR it may not grow") and docs/fork/updates.md:72 ("reads its own list only to refuse, never to widen the gate"). So the answer to point 2 is: the rule is not true everywhere. The move path reads the own added, and by design that is what lets the move pass. That is the same power as any new seam entry, which the owner reviews. The stay-pending raise above is the real exception.
    • This PR closes exactly this case for moves (:387), but not for a file that stays pending.
    • Fix: move the want > ceiling refusal above if (moved) so it applies to both paths, and add the stay-pending swap to the "adds fork lines" test.
  2. Follow-up: the admitted gap (wrong lines listed). The mitigation is enough to merge: the gap fails closed, it can be recovered from, and the owner reviews the entry.

    • A cheap way to close it: the PR run can know the upstream base. Main contains that commit, and fork-follow finds it as git merge-base HEAD <upstream HEAD> (fork-follow.sh, around line 145).
    • In the "Fork lines in upstream files" step, fetch upstream HEAD blobless, then pass --upstream-base "$(git merge-base "$DEFAULT_SHA" FETCH_HEAD)".
    • For a moved file, require lineCounts(added) to equal addedLines(textAt(upstreamBase, file), head) exactly. That is about 15 lines plus a test.
    • Cheaper still: add that one --from-upstream <merge-base> <PR head> command to the docs as the owner's review step for a move.
  3. Follow-up: :385 (if (want === 0) continue;) skips the listed check. Scenario: no fork line is left, and the new entry lists a(); and b(); (upstream lines). Both the PR run and fork-follow pass, leaving a spare seam allowance nobody reviewed as fork lines. docs/fork/updates.md:67 says such a file moves "with "added": []". This is pre-existing on main.

    • Fix: delete line 385. listed !== want then requires added: [], and the existing tests still pass (I ran this mutant: 81/81).
  4. Follow-up: the moved entry's own announced is not checked against the head. Scenario: the move puts announced: {since, added: ["b();"]}, and b(); is already in the file. The PR run passes. After the merge, main's "no announced line is in its file yet" test (findStaleSeamLines, which fork-checks runs on main's tree) fails for every PR, and fork-follow refuses landed.

    • This is pre-existing for any list edit. But this branch already reads the new entry, so refusing an announced line the head has costs 3 lines. A broader fix is to run findStaleSeamLines on the own list's new or changed entries against the head in every PR run.
  5. Follow-up (point 4, state): stale branch. The listed lines are checked against the PR head (:394), but the ceiling comes from main's tip.

    • Scenario: a branch is cut before another PR moves forkC(); out and lowers the ceiling from 3 to 2. The branch then does a list-only move that lists forkA(); and forkC();. Both its count of 2 and its head's lines pass. Once merged, main lists a line it lacks, and main's tree test is red for every PR.
    • The merge queue updating branches makes this unlikely.
    • Fix: also require the copies in the base tip (textAt(base, file), as atTip does for seams).

    On the rest of point 4:

    • An old list needs no new keys, so its shape is unchanged.
    • A missing added is refused by parseConfig. An empty one is refused by count, with a clear message.
    • A rerun is deterministic; only the announcement warnings use the clock.
    • A later PR on the moved file is judged as a seam: a new line needs an announcement first.
  6. Follow-up (point 5, tests). I ran these mutants on the new branch:

    • dropping want > ceiling: killed (1 test);
    • there = lineCounts(base): killed (3 tests);
    • has < count changed to has === 0: killed;
    • listed !== want changed to listed < want: killed.

    Two survive:

    • (a) counting announced in listed (seamLines(ownFiles[file]) instead of .added): 81/81 pass, because no test puts announced in a moved entry. Add one where the right added plus an announced line passes, and one where a fork line listed only under announced is refused.
    • (b) dropping the want === 0 skip: this one is stricter, see finding 3.

Verdict: MERGE. No blocking findings. I suggest folding finding 1 (hoist want > ceiling) and finding 3 (delete :385) in here, since each is a line or two.

- With fork lines left, a move to "files" is allowed only in a list-only
  change (the file's text unchanged), so a stale "lost" cannot hide an
  upstream line swapped for a fork line.
- A pending file may not gain a fork line whether it stays in "pending"
  or moves: the own list's "lost" can no longer raise the ceiling.
- The listed-lines check also runs with no fork line left: the entry
  must then list none.
- An "announced" line in a moved entry that the file already has is
  refused.
- Tests for each new refusal and for "announced" lines in a moved entry;
  wording fixes; docs name the owner's check of a move's listed lines
  (#552 moves that check into CI).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

Review follow-ups folded in (head 662f507)

Both reviews said MERGE. These follow-ups are now in the PR. Each new refusal has a test that fails on the first commit's checker (6 tests fail there). Undoing each change on its own also fails at least one test.

Item Change (.github/scripts/fork-seam-check.cjs) Test (fork-seam-check.test.cjs)
A-1: a move with fork lines left is list-only :397: a move while fork lines are left is refused unless the file's text is unchanged ("only a list-only change … may move it") a move to "files" with fork lines left is a list-only change (:2187): a line moved out, a swap, and reviewer A's stale-lost swap are refused; the unchanged file moves. The property test checks list-only moves against the run from upstream, and edited moves with lines left are refused.
B-1: the own list cannot raise the ceiling, even when the file stays pending :384: the want > ceiling refusal now sits above the move branch, so it covers both paths a move to "files" that also adds fork lines is refused (:2274): reviewer B's stay-pending swap (own pending: 2, lost.gone: 1) is refused, though the run from upstream on the merged head would pass it. The property test asserts that the right pending list is refused whenever the head gains a fork line.
B-3: list check runs with no fork line left the if (want === 0) continue; skip is gone; with none left, the entry must list none (:406) moves to "files" with "added": [] only once no fork line is left (:2079): an upstream line listed with no fork line left is refused
B-4: announced in a promoted entry :421: an announced line the file already has is refused ("…but the file already has it (N× there)…") a move to "files" that leaves a fork line out of its entry is refused (:2222): a fork line put under announced, and an upstream line announced
A-3 / B-6: announced must not count (only added is counted) :2164: a correct list plus an announced line passes; :2222: a fork line only under announced gives "(it lists 2;". The mutant that counts announced fails both.
A-4: wording the lost part now reads "sets its own "lost" to name N …"; a list-only move reads "this change moves it to "files" …" instead of "changes its lines"; the over-long docs line is re-wrapped the expected texts in :2079, :2151, :2222
Docs docs/fork/updates.md: the owner checks a move's listed lines with fork-seam-check.cjs --from-upstream "$(git merge-base origin/main upstream/main)" <pull request head>; also states the list-only and no-gained-line rules follow-up issue #552 ("seam check: verify promoted lines against upstream in CI"), referenced in the PR body

Not folded in: B-5 (a stale branch whose listed lines are checked against the head, not main's tip). The merge queue makes this unlikely. It is left as a possible later addition to #552.

Checks run locally:

@scuttletoby
scuttletoby merged commit 397a47c into main Nov 19, 2026
37 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant