* test(#2645): pin failing-first regression coverage for verification-deletion ledger Deleting a *-VERIFICATION.md file after a failing gaps_found/human_needed verdict was recorded silently raises reported workstream completion — the deletion is indistinguishable from "verifier never ran" at the verdict-lookup layer. These tests pin the correct behavior (deletion must never raise completed_phases/progress_percent) and fail against the current code, which has no such protection. * fix(#2645): persist verification verdicts across deletion in workstream rollup FAILING_VERIFICATION_STATUSES gated phase completeness on a verdict read fresh from *-VERIFICATION.md on every call. Deleting that file made "verifier found gaps, report later deleted" indistinguishable from "verifier never ran" (both read the internal 'missing' sentinel), so removing evidence silently raised completed_phases/progress_percent. Persist the last real verdict observed per phase key in a ledger file at the workstream directory level (outside every phase directory, so the same deletion that triggers the hole cannot also erase the memory of it). The ledger is consulted only when a live read comes back 'missing' and is updated whenever a real verdict is observed, so a genuinely re-verified phase is never permanently pinned, and verifier-disabled or not-yet-verified phases are unaffected (no ledger entry is ever created for them). Ledger-winner selection walks phase directories in the same sorted order buildWorkstreamInventory's own duplicate-directory tie-break uses, so a stale same-numbered directory can never clobber the live directory's remembered verdict on an exact mtime tie. Adds fault-injection coverage for the ledger read/write per CONTRIBUTING.md's filesystem-writes rules. * fix(#2645): redesign verification ledger to fail closed, not open The two-state ledger read (any read/parse failure -> "nothing remembered") failed OPEN: deleting the ledger alongside the report, or simply corrupting it while the report was already gone, degraded to the same 'missing' sentinel this issue exists to stop trusting -- silently reopening the completion-inflation hole one level up. Redesigned as a three-state read distinguishing 'absent' (no ledger file at all -- ENOENT specifically, disambiguated from a broken symlink via lstatSync) from 'corrupt' (file exists but unreadable/unparseable/ wrong shape) from 'ok'. Only 'absent' behaves as pre-fix (ungated) -- deliberate, since every existing project is in that state for every workstream on the day this ships. 'corrupt' and 'ok' both fail closed for a phase with no trustworthy entry, via a new internal sentinel 'unrecorded' added to FAILING_VERIFICATION_STATUSES. A corrupt ledger is not a permanent wedge: it is only overwritten when a real verdict is actually observed (never patched with an empty object), so re-verifying even one phase repairs the file. The ledger write is now atomic (temp file + rename, mirroring broken-windows.cts's writeLedgerAtomic/renameWithRetry shape) so this fix does not itself produce the corrupt files it now treats as security-relevant. Disclosed, accepted residual gap, pinned as an explicit test: deleting the ledger file itself (not just the report) still returns a workstream to the pre-adoption 'absent' state. This is inherent to any design where a wholly-absent store must be safe by default -- the alternative is gating every never-verified phase in every project on upgrade. Rail B is prospective only; a phase deleted before this fix shipped cannot be retroactively recovered. Also: dropped 'stale' from the Row 9 property test's REAL_STATUSES (it does not round-trip through readVerificationStatus as written, so including it claimed coverage the test did not have), converted two try/finally test bodies to t.after(), and added the remaining CONTRIBUTING.md fault-injection cases (broken symlink, missing parent directory, rename failure, temp-file cleanup). * fix(#2645): share the rollup winner selection to close a scoping gap BLOCKER: the ledger-winner selection in workstream-inventory.cts compared raw mtimes with no milestone-scoping filter, while the builder's own rollupDirByKey filters out-of-milestone directories before comparing. In a scoped workstream, a stale out-of-milestone duplicate-key directory with a newer mtime could win the ledger's selection while losing the builder's -- so deleting the LIVE directory's report never consulted the ledger, reopening #2645's hole for the phase that actually counts toward completed_phases, reachable with a plain rm. Extracted pickRollupWinners as the single shared implementation both rollupDirByKey and the ledger's winner selection now call, with the identical scoping filter -- two independent hand-written copies of "pick the winner" is what produced the divergence; one implementation makes the bug class structurally impossible rather than merely tested against. Added a unit-level proof (synthetic same-key entries with opposing inclusion/mtime) and an integration-level proof (a scoped workstream asserting an out-of-milestone verdict is never written into the ledger). Also: disclosed a third residual limitation in the changeset (editing a ledger entry by hand plants a permanent false verdict -- worse than deleting the ledger, since it looks like genuine history; not made tamper-proof, that's scope creep here); fixed a non-ENOENT lstatSync failure falling open to 'absent' instead of failing closed like every other path in that function; and fixed two test bugs a real gsd-test run caught -- Row 11's write-failure mock matched only the final ledger path, but the atomic-write refactor moved the real write target to a temp file, so the mock silently stopped intercepting anything and the test's own assertion caught its own staleness. * test(#2645): relabel Row 19 honestly and pin the lstat fail-closed fix Row 19 used two DIFFERENT phase keys (1-old, 2-new), so it never exercised the same-key collision the milestone-scoping blocker fix addresses -- the pre-fix, unshared ledger-winner code would have satisfied it too. Its docstring called it the integration-level proof of the blocker; it is not. Relabeled both rows accurately: Row 18 (synthetic same-key data) is now stated as the only row that proves the collision end to end, and Row 19 is described for what it genuinely covers -- a distinctly-keyed out-of-milestone phase's verdict never reaching the ledger, real coverage but not the collision case. Extensive probing (documented in 10-diagnosis.md) could not construct a natural directory-naming pair that shares a rollup key while diverging in milestone membership under the current roadmap-parser implementation, so the collision proof stays unit-level by necessity, not convenience. Also added a test pinning the lstat fail-closed fix: readVerificationLedger disambiguates a broken symlink (ENOENT from readFileSync) from genuine absence via a follow-up lstatSync call, and only lstatSync itself reporting ENOENT is proof of absence. A double-fault (readFileSync ENOENT, lstatSync a DIFFERENT code) cannot occur on a real filesystem, so it's monkeypatched directly -- without a test, a future edit could re-widen that catch back to "any lstat failure means absent" and fall open again silently. * chore(#2645): backfill changeset PR number to 3016 --------- Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
@@ -21,8 +21,60 @@ function toPosixPath(p: string): string {
|
||||
* EXPLICIT failing verdicts the verifier emits — `missing`/`unknown` (verifier
|
||||
* off / not yet run) and `stale` (mtime-derived, #2348) are intentionally left
|
||||
* untouched so verifier-disabled projects do not regress to never-complete.
|
||||
*
|
||||
* #2645: `'unrecorded'` is NOT a verdict the verifier itself ever emits — it
|
||||
* is an internal sentinel `workstream-inventory.cts`'s verification-deletion
|
||||
* ledger substitutes for `'missing'` once that workstream has ADOPTED the
|
||||
* ledger (a `.verification-ledger.json` file exists for it) but has no
|
||||
* remembered entry for this specific phase. Pre-adoption (no ledger file at
|
||||
* all) still resolves to plain `'missing'`, which stays OUTSIDE this set —
|
||||
* that is what keeps a project untouched by this fix until it actually uses
|
||||
* the verifier at least once. Post-adoption, an unrecorded phase fails
|
||||
* CLOSED (counted here) rather than open, so a corrupt or evidence-absent
|
||||
* ledger entry can no longer be read as "safe to complete" the way a bare
|
||||
* `'missing'` sentinel is.
|
||||
*/
|
||||
const FAILING_VERIFICATION_STATUSES = new Set<string>(['gaps_found', 'human_needed']);
|
||||
const FAILING_VERIFICATION_STATUSES = new Set<string>(['gaps_found', 'human_needed', 'unrecorded']);
|
||||
|
||||
/**
|
||||
* #2562 / Bug #2445 / #2645 review: pick ONE winning item per key from a
|
||||
* PRE-SORTED list — newest `mtimeMs` wins; on an exact tie the incumbent
|
||||
* (first-in-sort-order) wins, since only a STRICTLY greater mtime replaces
|
||||
* it. `includeItem` lets a caller exclude items before comparison (e.g.
|
||||
* out-of-milestone directories) — critically, the filter runs BEFORE the
|
||||
* mtime comparison, so an excluded item can never win a tie or a comparison
|
||||
* against an included one.
|
||||
*
|
||||
* Extracted as the SINGLE shared implementation after a #2645 review found
|
||||
* two independently-written copies of this exact rule had silently
|
||||
* diverged: `workstream-inventory.cts`'s ledger-winner selection compared
|
||||
* raw mtimes with no scoping filter, while this module's own `rollupDirByKey`
|
||||
* (below) filtered out-of-milestone directories first. A stale out-of-
|
||||
* milestone directory with a newer mtime than the live in-milestone one
|
||||
* (plausible after a checkout/rebase resets mtimes) could then win the
|
||||
* LEDGER's selection while losing the BUILDER's — reopening #2645's own
|
||||
* hole for the phase that actually counts toward `completed_phases`,
|
||||
* reachable with a plain `rm` and no ledger tampering. A comment asserting
|
||||
* two hand-written copies "use the same rule" is not a guarantee they do;
|
||||
* one shared function is.
|
||||
*/
|
||||
export function pickRollupWinners<T>(
|
||||
sortedItems: T[],
|
||||
keyOf: (item: T) => string,
|
||||
mtimeOf: (item: T) => number,
|
||||
includeItem: (item: T) => boolean = () => true,
|
||||
): Map<string, T> {
|
||||
const winners = new Map<string, T>();
|
||||
for (const item of sortedItems) {
|
||||
if (!includeItem(item)) continue;
|
||||
const key = keyOf(item);
|
||||
const incumbent = winners.get(key);
|
||||
if (incumbent === undefined || mtimeOf(item) > mtimeOf(incumbent)) {
|
||||
winners.set(key, item);
|
||||
}
|
||||
}
|
||||
return winners;
|
||||
}
|
||||
|
||||
export function isCompletedInventory(status: unknown): boolean {
|
||||
const s = (typeof status === 'string'
|
||||
@@ -220,20 +272,16 @@ export function buildWorkstreamInventory(inputs: BuildWorkstreamInventoryInputs)
|
||||
// each add to the numerator while the denominator counts distinct phases —
|
||||
// pushing completed_phases past it, where the old `Math.min` cap silently
|
||||
// rounded the result up to 100% and hid an unstarted phase. Newest-on-disk
|
||||
// wins, mirroring state.cts's #2445 de-duplication.
|
||||
const rollupDirByKey = new Map<string, string>();
|
||||
for (const dir of [...phaseDirNames].sort()) {
|
||||
const entry = countsMap.get(dir);
|
||||
if (scoped && entry?.inMilestone === false) continue;
|
||||
const key = entry?.phaseKey ?? dir;
|
||||
const incumbent = rollupDirByKey.get(key);
|
||||
if (incumbent === undefined) {
|
||||
rollupDirByKey.set(key, dir);
|
||||
continue;
|
||||
}
|
||||
const incumbentMtime = countsMap.get(incumbent)?.mtimeMs ?? 0;
|
||||
if ((entry?.mtimeMs ?? 0) > incumbentMtime) rollupDirByKey.set(key, dir);
|
||||
}
|
||||
// wins, mirroring state.cts's #2445 de-duplication. `pickRollupWinners` is
|
||||
// the SHARED implementation `workstream-inventory.cts`'s ledger-winner
|
||||
// selection also calls, so the two can never independently diverge again
|
||||
// (#2645 review).
|
||||
const rollupDirByKey = pickRollupWinners(
|
||||
[...phaseDirNames].sort(),
|
||||
(dir) => countsMap.get(dir)?.phaseKey ?? dir,
|
||||
(dir) => countsMap.get(dir)?.mtimeMs ?? 0,
|
||||
(dir) => !(scoped && countsMap.get(dir)?.inMilestone === false),
|
||||
);
|
||||
const rollupDirs = new Set(rollupDirByKey.values());
|
||||
|
||||
const phases: PhaseStatus[] = [];
|
||||
|
||||
@@ -34,7 +34,7 @@ const { phaseKeyFromDir, phaseKeyFromProse, parentPhaseKey } = phaseIdMod;
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports -- roadmap-parser.cjs is an export= CommonJS module
|
||||
import roadmapParserMod = require('./roadmap-parser.cjs');
|
||||
const { getMilestonePhaseFilter, isMilestoneShippedInRoadmap } = roadmapParserMod;
|
||||
import { buildWorkstreamInventory, isCompletedInventory } from './workstream-inventory-builder.cjs';
|
||||
import { buildWorkstreamInventory, isCompletedInventory, pickRollupWinners } from './workstream-inventory-builder.cjs';
|
||||
import type { WorkstreamInventory, StateProjection, MilestoneShippedSignal } from './workstream-inventory-builder.cjs';
|
||||
|
||||
// ─── Types ────────────────────────────────────────────────────────────────────
|
||||
@@ -199,6 +199,208 @@ function countPhaseFiles(phaseDir: string): PhaseFileCounts {
|
||||
return { planCount: scan.planCount, summaryCount: scan.summaryCount };
|
||||
}
|
||||
|
||||
// ─── #2645: verification-deletion ledger ───────────────────────────────────
|
||||
//
|
||||
// #2562's completeness gate (`FAILING_VERIFICATION_STATUSES`,
|
||||
// workstream-inventory-builder.cts) reads a phase's verification verdict
|
||||
// fresh from `*-VERIFICATION.md` on every call. That makes "verifier ran,
|
||||
// found gaps, report later deleted" indistinguishable from "verifier never
|
||||
// ran" — both collapse to the same `'missing'` sentinel
|
||||
// (verification.cts's `missingResult()`), which is deliberately NOT in the
|
||||
// failing set (so verifier-disabled projects can still reach 100%). Deleting
|
||||
// a failing report is therefore sufficient to silently raise the reported
|
||||
// completion percentage — a Goodhart hole (#2645).
|
||||
//
|
||||
// The fix persists the last REAL (non-'missing') verdict this module has
|
||||
// ever observed per phase key, in a small ledger file living at the
|
||||
// WORKSTREAM directory level — never inside the phase directory whose file
|
||||
// is the thing being deleted, so the same `rm` that triggers the hole
|
||||
// cannot also erase the memory of it. When a live read comes back 'missing',
|
||||
// the ledger is consulted as a fallback; when a live read comes back with a
|
||||
// real verdict — including a later 'passed' that supersedes an earlier
|
||||
// failing one — the ledger is updated to match, so a genuinely re-verified
|
||||
// phase is never permanently pinned.
|
||||
//
|
||||
// #2645 review: a NAIVE two-state read ("got entries, or nothing") fails
|
||||
// OPEN — any read/parse failure degraded to `{}`, which is indistinguishable
|
||||
// from "genuinely never verified", so corrupting the ledger (or deleting it
|
||||
// alongside the report) silently reopened the exact hole this fix exists to
|
||||
// close, one level up. THREE states, not two:
|
||||
//
|
||||
// 1. `'absent'` — no `.verification-ledger.json` for this workstream at
|
||||
// all. This is the ONLY state that behaves exactly as pre-#2645 (a
|
||||
// phase with no live report reads `'missing'`, ungated). Deliberate:
|
||||
// on the day this ships, EVERY existing project is in this state for
|
||||
// EVERY workstream, and gating here would drop them all to
|
||||
// `in_progress` at once. A workstream stays here forever if the
|
||||
// verifier is never actually used on it (criterion 2/3 — no entry is
|
||||
// ever written for a `'missing'` live read, so the file itself is
|
||||
// never created).
|
||||
// 2. `'corrupt'` — the file exists but could not be read or parsed (I/O
|
||||
// error, invalid JSON, wrong shape). This is NOT the same as absent:
|
||||
// an unreadable file is evidence something existed. Treated identically
|
||||
// to "present, no entry for this phase" below — fails CLOSED, not open.
|
||||
// 3. `'ok'` — the file exists and parsed. A phase with an entry uses
|
||||
// it; a phase WITHOUT one is "present, no entry" — this workstream has
|
||||
// adopted the ledger (some phase in it has a real verdict on record),
|
||||
// so an unobserved phase can no longer default to the pre-adoption
|
||||
// "ungated" behavior, or the same evidence-erasure hole reopens for
|
||||
// THIS phase specifically. Fails CLOSED: resolves to the `'unrecorded'`
|
||||
// sentinel (`workstream-inventory-builder.cts`'s
|
||||
// `FAILING_VERIFICATION_STATUSES`), not `'missing'`.
|
||||
//
|
||||
// Corrupt-ledger recovery: a corrupt ledger is NOT a permanent wedge. Any
|
||||
// phase with a REAL live verdict on disk still writes/repairs the ledger on
|
||||
// this same call (the corrupt content is fully overwritten, never patched),
|
||||
// so re-running the verifier for even one phase heals the file. A phase with
|
||||
// no live report and no way to re-verify stays `'unrecorded'` (gated) until
|
||||
// someone re-verifies it — a deliberate, disclosed cost of failing closed,
|
||||
// not an accidental one.
|
||||
//
|
||||
// Disclosed, ACCEPTED residual gap (not closed by this fix, and not closable
|
||||
// by ledger design alone): deleting the ledger FILE ITSELF (not just the
|
||||
// phase's report) returns a workstream to state 1 (`'absent'`) and restores
|
||||
// pre-#2645 behavior for it. Any durable store that can fail open when
|
||||
// absent has this property at its own root — the ledger raises the bar from
|
||||
// "delete one file" to "delete two files in two different directories,
|
||||
// including one this issue's own reproduction never needed to touch", but a
|
||||
// deliberately absent ledger is indistinguishable from a never-adopted one
|
||||
// by design (criterion 2/3 depend on that same indistinguishability). Rail B
|
||||
// is PROSPECTIVE ONLY: a phase verified and its report deleted BEFORE this
|
||||
// fix ships has no ledger entry to fall back on and cannot be retroactively
|
||||
// recovered.
|
||||
interface VerificationLedger { [phaseKey: string]: string; }
|
||||
|
||||
interface VerificationLedgerRead {
|
||||
state: 'absent' | 'corrupt' | 'ok';
|
||||
entries: VerificationLedger;
|
||||
}
|
||||
|
||||
function verificationLedgerPath(wsDir: string): string {
|
||||
return path.join(wsDir, '.verification-ledger.json');
|
||||
}
|
||||
|
||||
function readVerificationLedger(wsDir: string): VerificationLedgerRead {
|
||||
const ledgerPath = verificationLedgerPath(wsDir);
|
||||
let raw: string;
|
||||
try {
|
||||
raw = fs.readFileSync(ledgerPath, 'utf-8');
|
||||
} catch (err) {
|
||||
// `fs.readFileSync` FOLLOWS symlinks, so a broken symlink at this path
|
||||
// (the entry exists, its target does not) reports the EXACT SAME
|
||||
// `ENOENT` as genuine absence — `code` alone cannot distinguish
|
||||
// "nothing was ever here" from "something is here and cannot be read".
|
||||
// `fs.lstatSync` does NOT follow symlinks, so it still finds the
|
||||
// symlink entry itself even when its target is gone. Only when NEITHER
|
||||
// call finds anything is this genuinely `'absent'` (pre-adoption); a
|
||||
// present-but-broken symlink is evidence something existed and must
|
||||
// fail CLOSED like any other unreadable ledger, not fall open.
|
||||
const code = (err as NodeJS.ErrnoException)?.code;
|
||||
if (code === 'ENOENT') {
|
||||
try {
|
||||
fs.lstatSync(ledgerPath);
|
||||
return { state: 'corrupt', entries: {} }; // a symlink entry exists; its target does not
|
||||
} catch (lstatErr) {
|
||||
// #2645 review: every OTHER failure path in this function fails
|
||||
// CLOSED — this one must too. A failed `lstatSync` is only proof of
|
||||
// absence when IT ALSO reports `ENOENT`; anything else (a raced
|
||||
// permission change, a path component that became inaccessible
|
||||
// between the two calls, …) is not evidence the file was never
|
||||
// there, and a bare `catch {}` here would silently fall OPEN exactly
|
||||
// like the two-state design this fix replaced.
|
||||
const lstatCode = (lstatErr as NodeJS.ErrnoException)?.code;
|
||||
if (lstatCode === 'ENOENT') return { state: 'absent', entries: {} }; // truly nothing at this path
|
||||
return { state: 'corrupt', entries: {} };
|
||||
}
|
||||
}
|
||||
// Any OTHER read failure (EACCES, EISDIR, …) also means the path EXISTS
|
||||
// in some form but this process cannot see its content right now — that
|
||||
// is corruption from this reader's point of view, not absence, and must
|
||||
// fail closed rather than silently falling back to the ungated
|
||||
// pre-adoption behavior.
|
||||
return { state: 'corrupt', entries: {} };
|
||||
}
|
||||
let parsed: unknown;
|
||||
try {
|
||||
parsed = JSON.parse(raw);
|
||||
} catch {
|
||||
return { state: 'corrupt', entries: {} };
|
||||
}
|
||||
if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
|
||||
return { state: 'corrupt', entries: {} };
|
||||
}
|
||||
const out: VerificationLedger = {};
|
||||
for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
|
||||
if (typeof value === 'string') out[key] = value;
|
||||
}
|
||||
return { state: 'ok', entries: out };
|
||||
}
|
||||
|
||||
// #2645 review: Windows can transiently hold the rename target busy (AV
|
||||
// scanners, indexers) — the SAME retry shape `broken-windows.cts`'s
|
||||
// `writeLedgerAtomic`/`renameWithRetry` already uses for its own ledger
|
||||
// write, mirrored here rather than imported (that function is private to
|
||||
// its module) so this fix does not widen its own blast radius by exporting
|
||||
// a new cross-module utility.
|
||||
const LEDGER_RENAME_RETRY_ERRNOS = new Set(['EPERM', 'EBUSY', 'EACCES']);
|
||||
const LEDGER_RENAME_MAX_ATTEMPTS = 5;
|
||||
const LEDGER_RENAME_BACKOFF_MS = 25;
|
||||
|
||||
function renameVerificationLedgerWithRetry(tmpPath: string, finalPath: string): void {
|
||||
let lastErr: unknown;
|
||||
for (let attempt = 0; attempt < LEDGER_RENAME_MAX_ATTEMPTS; attempt++) {
|
||||
try {
|
||||
fs.renameSync(tmpPath, finalPath);
|
||||
return;
|
||||
} catch (err: unknown) {
|
||||
lastErr = err;
|
||||
const code = (err && typeof err === 'object' && 'code' in err) ? String((err as { code?: unknown }).code) : '';
|
||||
if (code && LEDGER_RENAME_RETRY_ERRNOS.has(code) && attempt < LEDGER_RENAME_MAX_ATTEMPTS - 1) {
|
||||
// Exponential-ish backoff: 25ms, 50ms, 100ms, 200ms. Transient
|
||||
// Windows locks usually clear well inside that window.
|
||||
const delay = LEDGER_RENAME_BACKOFF_MS * Math.pow(2, attempt);
|
||||
const start = Date.now();
|
||||
while (Date.now() - start < delay) {
|
||||
// Deliberate short busy-wait — no async/timer seam is available
|
||||
// in this synchronous read path.
|
||||
}
|
||||
continue;
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
throw lastErr;
|
||||
}
|
||||
|
||||
function writeVerificationLedger(wsDir: string, ledger: VerificationLedger): void {
|
||||
// #2645 review: atomic write. A crash or a concurrent read mid-write
|
||||
// against `verificationLedgerPath(wsDir)` directly would leave (or briefly
|
||||
// expose) TRUNCATED JSON — and now that `'corrupt'` carries real semantic
|
||||
// weight (it fails CLOSED, holding every phase with no live report at
|
||||
// `'unrecorded'`), producing a corrupt file ourselves is a self-inflicted
|
||||
// version of the exact failure mode this fix exists to survive. Write to a
|
||||
// sibling temp file in the SAME directory (same filesystem — `rename` is
|
||||
// only atomic within one) and rename into place: a reader can only ever
|
||||
// observe the prior complete content or the new complete content.
|
||||
const finalPath = verificationLedgerPath(wsDir);
|
||||
const tmpPath = `${finalPath}.${process.pid}.tmp`;
|
||||
try {
|
||||
fs.mkdirSync(wsDir, { recursive: true });
|
||||
fs.writeFileSync(tmpPath, `${JSON.stringify(ledger, null, 2)}\n`, 'utf-8');
|
||||
renameVerificationLedgerWithRetry(tmpPath, finalPath);
|
||||
} catch {
|
||||
// Best-effort persistence: a missing parent directory that `mkdirSync`
|
||||
// itself cannot create, a read-only filesystem, a write failure, or a
|
||||
// rename failure that exhausts its retries must not break inventory
|
||||
// reads, which are otherwise pure. Losing this observation only
|
||||
// re-opens the pre-#2645 window for THIS run; the next successful read
|
||||
// while a report is on disk repairs it. Clean up a half-written temp
|
||||
// file so repeated failures cannot accumulate orphaned
|
||||
// `.verification-ledger.json.<pid>.tmp` files.
|
||||
try { fs.unlinkSync(tmpPath); } catch { /* nothing to clean up, or cleanup itself failed — not fatal */ }
|
||||
}
|
||||
}
|
||||
|
||||
function readStateProjection(statePath: string): StateProjection {
|
||||
try {
|
||||
const stateContent = fs.readFileSync(statePath, 'utf-8');
|
||||
@@ -366,7 +568,18 @@ function inspectWorkstream(cwd: string, name: string, options: InspectWorkstream
|
||||
// Collect per-phase file counts (+ canonical key, milestone membership,
|
||||
// verification verdict). `phaseKey` lets the builder de-duplicate stale
|
||||
// same-numbered directories (Bug #2445's scenario) in the rollup.
|
||||
const phaseFilesCounts = phaseDirNames.map(dir => {
|
||||
//
|
||||
// #2645 review: built from `[...phaseDirNames].sort()`, NOT the raw
|
||||
// `phaseDirNames` (unsorted `readdirSync` order — `readSubdirectories`'s
|
||||
// default). `buildWorkstreamInventory`'s own de-dup (`rollupDirByKey`,
|
||||
// workstream-inventory-builder.cts) iterates the SAME sorted order; the
|
||||
// ledger-winner tie-break below (incumbent wins unless a later entry has a
|
||||
// STRICTLY newer mtime) only agrees with the builder's winner on an exact
|
||||
// mtime tie if both walk entries in the same order. Iterating unsorted
|
||||
// input here let the two independently pick different "winning"
|
||||
// directories for one phase key on a tie — reopening the stale-duplicate-
|
||||
// clobbers-live-verdict hole criterion 4 exists to close.
|
||||
const rawPhaseEntries = [...phaseDirNames].sort().map(dir => {
|
||||
const phaseDir = path.join(p.phases, dir);
|
||||
const counts = countPhaseFiles(phaseDir);
|
||||
return {
|
||||
@@ -376,7 +589,83 @@ function inspectWorkstream(cwd: string, name: string, options: InspectWorkstream
|
||||
planCount: counts.planCount,
|
||||
summaryCount: counts.summaryCount,
|
||||
inMilestone: isDirInCurrentMilestone(dir),
|
||||
verificationStatus: readVerificationStatus(phaseDir).status,
|
||||
liveVerificationStatus: readVerificationStatus(phaseDir).status,
|
||||
};
|
||||
});
|
||||
|
||||
// #2645: only the directory Bug #2445's de-dup rollup would actually pick
|
||||
// for a phase key may read or write that key's ledger entry. Letting every
|
||||
// same-keyed directory (including a stale leftover) write would let a
|
||||
// stale duplicate's stale verdict clobber the live directory's remembered
|
||||
// one.
|
||||
//
|
||||
// #2645 review — CORRECTED: an earlier version of this comment claimed the
|
||||
// milestone-scoping exclusion (`scoped && entry.inMilestone === false`)
|
||||
// was safe to drop here as "out of scope", and hand-wrote a scoping-free
|
||||
// tie-break rule. That was a real bug, not a scope call: in a SCOPED
|
||||
// workstream, a stale OUT-of-milestone directory sharing a phase key with
|
||||
// the live IN-milestone one can have a newer mtime (plausible after a
|
||||
// checkout/rebase resets mtimes) and would then win THIS selection while
|
||||
// the builder's own `rollupDirByKey` — which DOES apply the scoping filter
|
||||
// — picks the live directory instead. `isLedgerWinner` would then be false
|
||||
// for the live directory, so deleting ITS `*-VERIFICATION.md` would never
|
||||
// consult the ledger and would reopen #2645's exact hole for the phase
|
||||
// that actually counts toward `completed_phases` — reachable with a plain
|
||||
// `rm`, no ledger tampering required. Fixed by calling the SAME shared
|
||||
// `pickRollupWinners` the builder's `rollupDirByKey` now also calls, with
|
||||
// the identical scoping filter, rather than a second hand-written copy.
|
||||
const ledgerWinnerByKey = pickRollupWinners(
|
||||
rawPhaseEntries,
|
||||
(entry) => entry.phaseKey,
|
||||
(entry) => entry.mtimeMs,
|
||||
(entry) => !(scoped && entry.inMilestone === false),
|
||||
);
|
||||
|
||||
const ledgerRead = readVerificationLedger(wsDir);
|
||||
// Both `'corrupt'` and `'ok'` start from whatever entries could actually be
|
||||
// trusted (empty for `'corrupt'` — nothing in an unparseable file is
|
||||
// trusted) and get REPAIRED below by any real verdict this call observes;
|
||||
// only `'absent'` skips the ledger mechanism entirely (pre-adoption).
|
||||
const verificationLedger = ledgerRead.entries;
|
||||
let ledgerDirty = false;
|
||||
for (const winner of ledgerWinnerByKey.values()) {
|
||||
if (winner.liveVerificationStatus === 'missing') continue;
|
||||
if (verificationLedger[winner.phaseKey] !== winner.liveVerificationStatus) {
|
||||
verificationLedger[winner.phaseKey] = winner.liveVerificationStatus;
|
||||
ledgerDirty = true;
|
||||
}
|
||||
}
|
||||
// A `'corrupt'` read that observes no real verdict this call has nothing to
|
||||
// repair with — writing an empty `{}` would DESTROY whatever the corrupt
|
||||
// file's bytes might still hold (a human could recover it by hand; this
|
||||
// fix must not foreclose that). Only write when there is something real to
|
||||
// persist, exactly as for `'absent'`/`'ok'`.
|
||||
if (ledgerDirty) writeVerificationLedger(wsDir, verificationLedger);
|
||||
|
||||
const phaseFilesCounts = rawPhaseEntries.map(entry => {
|
||||
const isLedgerWinner = ledgerWinnerByKey.get(entry.phaseKey) === entry;
|
||||
let verificationStatus = entry.liveVerificationStatus;
|
||||
if (entry.liveVerificationStatus === 'missing' && isLedgerWinner) {
|
||||
if (ledgerRead.state === 'absent') {
|
||||
// State 1: pre-adoption. Exactly today's behavior — 'missing' is
|
||||
// NOT in FAILING_VERIFICATION_STATUSES, so this does not gate.
|
||||
verificationStatus = 'missing';
|
||||
} else {
|
||||
// States 2/3 ('corrupt' or 'ok'): this workstream has adopted the
|
||||
// ledger. A remembered entry wins; no entry fails CLOSED to the
|
||||
// 'unrecorded' sentinel rather than falling open to 'missing'.
|
||||
const remembered = verificationLedger[entry.phaseKey];
|
||||
verificationStatus = remembered !== undefined ? remembered : 'unrecorded';
|
||||
}
|
||||
}
|
||||
return {
|
||||
directory: entry.directory,
|
||||
phaseKey: entry.phaseKey,
|
||||
mtimeMs: entry.mtimeMs,
|
||||
planCount: entry.planCount,
|
||||
summaryCount: entry.summaryCount,
|
||||
inMilestone: entry.inMilestone,
|
||||
verificationStatus,
|
||||
};
|
||||
});
|
||||
|
||||
|
||||
Reference in New Issue
Block a user