docs(plans): correct Step 1's entry to what the step ships

What

Two edits to the shared internal/virtual collection mode plan, carried here rather than in a step MR because guardrail 4 gives the plan file a single writer.

Step 1's Status row was never recorded

Guardrail 4: "whoever opens a step MR records its row in that batch or standing MR in the same sitting", and "an empty cell means 'not yet recorded', not 'not started'". !2481 (merged) has been open through a full review round with row 1's MR cell empty, so the table has been reading as though the step had no MR. Step 3's row already carries !2422 (merged), from a259f27ac, so this follows the precedent the plan set rather than inventing one.

# Step MR
1 per-position outcome vocabulary !2481 (merged)

The unhealthy row homed the token on the wrong thing

The Step 1 table homed unhealthy on "PositionRecord's health-mark field". What shipped in !2481 (merged) homes the token nowhere and keeps the mark as a field beside it. Those are different claims, and the row stated only the second while sitting in the column that answers the first.

Each spec scopes unhealthy to the winner path and routes a health-marked merge position to its cached copy or to that format's omission token: S30-maven-virtual.md:379, :474, :549, :710 and :801, and S31-npm-virtual.md:1872-1873 and :1879-1880. So a collection mints no value for it, and !2481 (merged) carries an absent row per spec with its own reason. The row now says that, and keeps every true sentence it already had about the mark riding the record rather than the aggregate.

This matters because the plan is what Steps 2, 4 and 5 read. Guardrail 4 forbids !2481 (merged) from editing the plan file, and it correctly does not, so the stale row could only be fixed from here.

The same rationale is restated once more, with only its cost half

Where the plan compares the mark to Elapsed, it gives the reason as "Collect holds it already, so recording it costs nothing". That is why the mark is cheap to carry, not why it is carried. The operating reason is the one ## Context already derives higher up: without the mark, a position omitted under it and one omitted after a consulted failure are the same record, which is where a slice derives all_unhealthy from rather than reporting every upstream unreachable. The passage now names both and points at the section that derives it.

Step 1's Files list and Shared seams denied a file it ships

A second review round of !2481 (merged) found the entry disagreeing with the diff. Step 1's Files list carries one bullet, internal/virtual/position.go (Create), and its Shared seams field reads "none. A new file in a package whose other files this step does not open." !2481 (merged) also edits internal/virtual/result.go.

The edit is right. ResolveResult.Position concluded the index was safe as a metric label from a bound that does not exist, and Step 1 writes the same claim on PositionRecord.Position with a doc link pointing at it, so leaving the sibling would have the two disagreeing while cross-referencing each other. What was wrong is the record: once Step 1 merges, Shared seams is where a Step 2 or Step 4 author goes to ask whether Step 1 opened a shared file, and it answered no. Both fields now say what shipped, and the seams field is written in the past tense as the settled record it becomes.

The data-error paragraph called S30 silent, and one S30 sentence is not

The arm that records a PositionDataError position holding a cached copy as PositionContributedFromCache justified itself by following S31 and calling S30-maven-virtual.md "silent rather than contrary", citing :554. That is true of :554. It is not true of :701, which lists the merged_partial causes as "a failed leg, an unhealthy remote without a cached copy, or a malformed or over-cap input": the qualifier on one item and not the next, which is the shape a reader takes as deliberate. Read strictly it makes a malformed input partial whatever the position holds, which is the opposite of the arm.

Leaving :701 out made the ruling look unopposed. It is now named, weighed and ruled against, with the reason, the cost of being wrong booked at the token (a Maven slice emits contributed_stale, whose gloss names an outage, for a data error), and what would have to change if S30's author reads :701 as written.

Merge order

This MR should merge before !2481 (merged), or in the same wave. The two do not conflict textually, and both descriptions previously called them order-free on that basis. That is the wrong test. If !2481 (merged) merges first, Step 1's merged Acceptance describes an unhealthy mapping that did not ship and a Files list missing a file that did, and that entry is what the next step's author reads to build a file set. The window is the only cost, so this is a stated order rather than a hard gate.

Testing

Documentation only. No Go file, no schema, no configuration, and no step's scope changes: the Status table gains one reference, and four passages are narrowed to what already merged or ruled on a sentence that was left out. No step's scope changes. markdownlint, lychee and vale pass; vale wanted the US spelling of one word.

Related to #1244 (closed)

Edited by Dzmitry (Dima) Meshcharakou

Merge request reports

Loading
Loading