ccqa 1.41.0 → 1.42.0

package/dist/bin/ccqa.mjs

@@ -5661,6 +5661,24 @@ function actorGroups(plan) {
 	return (ref) => (plan.windowsForSpec.get(specKey(ref)) ?? []).map((window) => window.key);
 }
 //#endregion
+//#region src/coverage/spec-id.ts
+/**
+* `<runId>.<feature>/<spec>`. The run id keeps a stale cookie from an earlier
+* run out; the spec half is `specKey`, so an id here and a report row name the
+* same spec the same way.
+*/
+function specIdFor(runId, ref) {
+	return `${runId}.${specKey(ref)}`;
+}
+/**
+* Inverse of `specIdFor`: the `feature/spec` half, or null when the id was
+* minted under another run. The runId itself may contain `.`, so the known
+* prefix is stripped by length, never by splitting on the dot.
+*/
+function specKeyFromSpecId(specId, runId) {
+	return specId.startsWith(`${runId}.`) ? specId.slice(runId.length + 1) : null;
+}
+//#endregion
 //#region src/coverage/contract.ts
 /**
 * The names and shapes ccqa agrees on with the instrumented application.
@@ -7905,14 +7923,6 @@ async function resolveRoot(cwd, declared) {
 function specCoverageDir(reportDir, feature, spec) {
 	return join(reportDir, "coverage", feature, spec);
 }
-/**
-* `<runId>.<feature>/<spec>`. The run id keeps a stale cookie from an earlier
-* run out; the spec half is `specKey`, so an id here and a report row name the
-* same spec the same way.
-*/
-function specIdFor(runId, ref) {
-	return `${runId}.${specKey(ref)}`;
-}
 async function readFrontend(coverageDir, specId) {
 	let raw;
 	try {
@@ -10321,6 +10331,28 @@ z.object({
 	totalUsd: z.number(),
 	entries: z.array(SpendEntrySchema)
 });
+/**
+* The coverage-edge ledger: per spec, the most recent measured reach — the
+* input measured spec selection intersects a diff with (ADR-0026). One
+* document per project; entries never expire, they are only replaced by a
+* newer measurement. `measuredAt` is stamped by the hub on merge, so entries
+* written by different runs stay comparable on one clock.
+*/
+const CoverageEdgeEntrySchema = z.object({
+	files: z.array(z.string()),
+	measuredAt: z.number(),
+	runId: z.string().optional()
+});
+const CoverageEdgesDocSchema = z.object({ specs: z.record(z.string(), CoverageEdgeEntrySchema) });
+/**
+* Body of `PUT /projects/:project/coverage-edges` — the specs one run
+* measured. Merged into the stored document, never replacing other specs'
+* entries; an empty file set is not a measurement and is rejected per entry.
+*/
+const CoverageEdgesUpsertSchema = z.object({ specs: z.record(z.string(), z.object({
+	files: z.array(z.string()).min(1),
+	runId: z.string().optional()
+})).refine((specs) => Object.keys(specs).length > 0, "at least one spec entry is required") });
 //#endregion
 //#region src/run/hub-selection.ts
 /**
@@ -11719,8 +11751,9 @@ function enrichZodError(error, source) {
 * means that spec must re-run — reach cannot see the test's own definition,
 * so no measurement is consulted for it. Everything else intersects the diff
 * with the files the spec's last measured run actually reached (ADR-0024);
-* a spec with no measurement stays `unknown`, because an unmeasured edge is
-* not an unreached one.
+* a spec with no measurement is `needed` — it runs until a measurement
+* lands, which is also what records its first edge (ADR-0026). Only when
+* the measurements could not be read does absence degrade to `unknown`.
 */
 async function selectSpecs(input) {
 	const { changed, specs, cwd, base, head, edges } = input;
@@ -11815,27 +11848,37 @@ function isCcqaPath(path) {
 /**
 * Hold each undecided spec's last measured reach against the diff.
 *
-* Three outcomes, and only the middle one is a positive claim: no
-* measurement means `unknown` (an unmeasured edge is not an unreached one —
-* the absence of evidence runs the spec); a non-empty intersection means
-* `needed`, with the intersecting paths as the reason; an empty one means
-* `notNeeded` — the measurement accounts for everything the spec reached,
-* and the diff missed all of it. Changes outside the measured root fall out
+* Three outcomes, and only one is a positive claim: a non-empty intersection
+* means `needed`, with the intersecting paths as the reason; an empty one
+* means `notNeeded` — the measurement accounts for everything the spec
+* reached, and the diff missed all of it; no measurement at all is also
+* `needed` — the spec runs until a measurement records its reach (ADR-0026)
+* — unless the read was degraded, in which case absence proves nothing and
+* the spec is left `unknown`. Changes outside the measured root fall out
 * of the comparison entirely: the root is the declared boundary of what
 * measurement governs, so what lies beyond it clears specs quietly — one
 * warning names the dropped paths, because a root configured too narrow
 * looks exactly like this and hides real reach (see docs/coverage.md).
 */
 async function judgeWithCoverage(input) {
-	const { pending, productChanges, cwd, edges } = input;
-	const noMeasurement = "no measurement to consult: the hub holds no measured reach for this spec";
-	if (edges.size === 0) return pending.map((s) => unknownSelection(s, noMeasurement));
+	const { pending, productChanges, cwd } = input;
+	const { edges, degraded } = input.edges;
+	const unreadable = "the hub's measured reach could not be read; not guessing";
 	const measuredChanges = rerootChangesForCoverage(productChanges, await resolveCoverageRoots(productChanges, cwd));
 	const dropped = productChanges.length - measuredChanges.length;
 	if (dropped > 0) warn(`select-specs: ${dropped} of ${productChanges.length} changed files fall outside coverage.projectRoot and cannot be compared against measured reach`);
 	return pending.map((spec) => {
 		const edge = edges.get(specKey(spec));
-		if (!edge) return unknownSelection(spec, noMeasurement);
+		if (!edge) {
+			if (degraded) return unknownSelection(spec, unreadable);
+			return {
+				featureName: spec.featureName,
+				specName: spec.specName,
+				verdict: "needed",
+				source: "coverage",
+				reason: "never measured: the spec runs until a measurement records its reach"
+			};
+		}
 		const touchedBy = measuredChanges.filter((c) => edge.files.has(c.measured)).map((c) => c.original);
 		if (touchedBy.length > 0) return {
 			featureName: spec.featureName,
@@ -11911,46 +11954,74 @@ async function resolveCoverageRoots(changed, cwd) {
 //#endregion
 //#region src/select/coverage-edges.ts
 /**
-* How many recent hub runs are probed for report-row coverage. Bounded
-* because every probe downloads a whole report.json; past this many runs a
-* measurement is old enough that treating it as absent — `unknown`, so the
-* spec runs — is the safer answer anyway. The stream side carries its own
-* bound: the hub lists at most its newest twenty measured runs.
+* How many recent hub runs are probed for legacy report-row coverage.
+* Bounded because every probe downloads a whole report.json; anything this
+* far back has usually been superseded by the ledger anyway.
 */
 const MAX_REPORT_RUNS = 20;
 /**
-* How old a measurement may be and still decide a spec. The same fourteen
-* days the stream store retains events for (`COVERAGE_RETENTION_DAYS`): past
-* it an edge is too stale to clear a spec with confidence, so it is not
-* adopted and the spec degrades to `unknown` — which runs.
-*/
-const EDGE_MAX_AGE_MS = 336 * 60 * 60 * 1e3;
-/**
-* Read every spec's most recent measured reach from the hub.
-*
-* Never throws: a hub that cannot be read yields an empty map (warned), which
-* the selection degrades to `unknown` across the board — the caller runs
-* those specs, so an unreadable hub costs runs, never a skipped regression.
+* Read every spec's most recent measured reach from the hub. Never throws: a
+* source that cannot be read warns, and `degraded` flips when the failure
+* leaves absence ambiguous (the ledger itself, or the legacy sources while
+* no ledger answers).
 */
 async function loadCoverageEdges(input) {
-	const edges = /* @__PURE__ */ new Map();
-	const freshAfter = Date.now() - EDGE_MAX_AGE_MS;
-	const merge = (key, edge) => {
-		if (edge.measuredAt < freshAfter) return;
-		const existing = edges.get(key);
-		if (!existing || edge.measuredAt > existing.measuredAt) edges.set(key, edge);
-	};
-	const results = await Promise.allSettled([collectStreamEdges(input, merge), collectReportEdges(input, merge)]);
+	if (input == null) return {
+		edges: /* @__PURE__ */ new Map(),
+		degraded: true
+	};
+	const candidates = /* @__PURE__ */ new Map();
+	const merge = (key, candidate) => {
+		const existing = candidates.get(key);
+		if (!existing || candidate.measuredAt > existing.measuredAt) candidates.set(key, candidate);
+	};
+	const [ledger, ...legacy] = await Promise.allSettled([
+		collectLedgerEdges(input, merge),
+		collectStreamEdges(input, merge),
+		collectReportEdges(input, merge)
+	]);
 	let skipped = 0;
-	for (const result of results) if (result.status === "rejected") warn(`select-specs: could not read coverage measurements from the hub (${errMessage(result.reason)})`);
-	else skipped += result.value;
-	if (skipped > 0) warn(`select-specs: ${skipped} measured run(s) on the hub could not be read; their reach is treated as absent`);
-	return edges;
+	let legacyBroken = false;
+	for (const result of legacy) if (result.status === "rejected") {
+		legacyBroken = true;
+		warn(`select-specs: could not read coverage measurements from the hub (${errMessage(result.reason)})`);
+	} else skipped += result.value;
+	if (skipped > 0) {
+		legacyBroken = true;
+		warn(`select-specs: ${skipped} measured run(s) on the hub could not be read; treating the measurements as unreadable rather than absent`);
+	}
+	if (ledger.status === "rejected") warn(`select-specs: could not read the hub's coverage-edge ledger (${errMessage(ledger.reason)})`);
+	const ledgerAnswered = ledger.status === "fulfilled" && ledger.value;
+	const degraded = ledger.status === "rejected" || !ledgerAnswered && legacyBroken;
+	return {
+		edges: new Map([...candidates].map(([key, c]) => [key, {
+			files: new Set(c.files),
+			measuredAt: c.measuredAt
+		}])),
+		degraded
+	};
+}
+/**
+* The ledger itself; true when a document answered. A 404 is an older hub or
+* a project that never wrote one, not a failure: the legacy sources answer.
+*/
+async function collectLedgerEdges(input, merge) {
+	const doc = await input.hub.getCoverageEdges(input.project);
+	if (doc === null) return false;
+	for (const [key, entry] of Object.entries(doc.specs)) {
+		if (entry.files.length === 0) continue;
+		merge(key, {
+			files: entry.files,
+			measuredAt: entry.measuredAt
+		});
+	}
+	return true;
 }
 /**
-* Edges from the coverage event stream. The plain read answers for the most
-* recently measured run and lists every run the stream retains; each older
-* run is then resolved individually. Returns how many runs could not be read.
+* Legacy: edges from the coverage event stream. The plain read answers for
+* the most recently measured run and lists every run the stream retains;
+* each older run is then resolved individually. Returns how many runs could
+* not be read.
 */
 async function collectStreamEdges(input, merge) {
 	const { hub, project } = input;
@@ -11962,24 +12033,16 @@ async function collectStreamEdges(input, merge) {
 function ingestResolved(resolved, merge) {
 	if (!resolved) return;
 	for (const spec of resolved.specs) {
-		const key = stripRunIdPrefix(spec.specId, resolved.runId);
+		const key = specKeyFromSpecId(spec.specId, resolved.runId);
 		if (key === null) continue;
 		if (spec.files.length === 0) continue;
 		merge(key, {
-			files: new Set(spec.files),
+			files: spec.files,
 			measuredAt: resolved.asOf
 		});
 	}
 }
 /**
-* A stream specId is `<runId>.<feature>/<spec>` (src/coverage/session.ts).
-* The runId itself may contain `.`, so the known prefix is stripped by
-* length, never by splitting on the dot.
-*/
-function stripRunIdPrefix(specId, runId) {
-	return specId.startsWith(`${runId}.`) ? specId.slice(runId.length + 1) : null;
-}
-/**
 * The one slice of report.json this consumer reads. Parsed with its own
 * narrow schema rather than the full report schema so a report from another
 * ccqa version still yields its edges as long as this shape holds.
@@ -11990,10 +12053,10 @@ const ReportCoverageRowsSchema = z.object({ results: z.array(z.object({
 	coverage: z.object({ files: z.array(z.string()) }).optional()
 })) });
 /**
-* Edges from pushed run reports, newest first. Only `kind: run` runs are
-* probed — audits and recordings execute no specs, so they carry no reach —
-* and a still-`running` run is skipped: its rows are still arriving, so its
-* measurement is not settled. Returns how many reports could not be read.
+* Legacy: edges from pushed run reports, newest first. Only `kind: run` runs
+* are probed — audits and recordings execute no specs — and a still-`running`
+* run is skipped: its rows are still arriving. Returns how many reports
+* could not be read.
 */
 async function collectReportEdges(input, merge) {
 	const { hub, project } = input;
@@ -12016,7 +12079,7 @@ async function collectReportEdges(input, merge) {
 		for (const row of parsed.data.results) {
 			if (!row.coverage || row.coverage.files.length === 0) continue;
 			merge(`${row.feature}/${row.spec}`, {
-				files: new Set(row.coverage.files),
+				files: row.coverage.files,
 				measuredAt
 			});
 		}
@@ -16626,22 +16689,21 @@ async function collectChangedSpecs(specs, opts) {
 		specs: [],
 		base: resolved
 	};
+	if (!hub) warn(`${flag}: no hub connection, so coverage measurements cannot be consulted — undecided specs will run`);
+	const edgesPromise = loadCoverageEdges(hub);
 	let inventory;
 	try {
 		inventory = await loadSpecInventory(cwd);
 	} catch (e) {
 		throw new RunUsageError(e.message);
 	}
-	let edges = /* @__PURE__ */ new Map();
-	if (hub) edges = await loadCoverageEdges(hub);
-	else warn(`${flag}: no hub connection, so coverage measurements cannot be consulted — undecided specs will run`);
 	const report = await selectSpecs({
 		changed,
 		specs: inventory,
 		cwd,
 		base: resolved.sha,
 		head: "HEAD",
-		edges
+		edges: await edgesPromise
 	});
 	const toRun = new Set(specsToRun(report).map(specKey));
 	const undecided = report.specs.filter((s) => s.verdict === "unknown").length;
@@ -16652,53 +16714,6 @@ async function collectChangedSpecs(specs, opts) {
 	};
 }
 //#endregion
-//#region src/run/measure-backfill.ts
-/**
-* `ccqa run --measure-backfill <n>`: keep the measured-reach edges alive.
-*
-* Selection (ADR-0024) consumes each spec's most recent measured reach, and
-* an edge expires after `EDGE_MAX_AGE_MS`. Nothing else re-measures: an
-* unmeasured spec answers `unknown`, `unknown` marks nothing due (ADR-0023),
-* and a suite can settle into a state where no run ever fires — the seed
-* deadlock. Appending a few unmeasured-or-aging specs to every selected run
-* breaks that loop and keeps the whole suite inside the freshness window
-* without a scheduled full sweep.
-*/
-/**
-* Re-measure once an edge has spent half its lifetime. Half, not "expired":
-* a spec re-measured only after expiry answers `unknown` for the gap between
-* expiry and the next run, which is exactly the window this flag exists to
-* close.
-*/
-const REMEASURE_AFTER_MS = EDGE_MAX_AGE_MS / 2;
-/**
-* Picks up to `limit` specs from `inventory` worth re-measuring: ones with no
-* edge at all first (they cost an `unknown` verdict today), then the oldest
-* measured ones. Specs already selected for this run are never doubled.
-*/
-function chooseMeasureBackfill(inventory, selected, edges, limit, now) {
-	const alreadyRunning = new Set(selected.map(specKey));
-	const missing = [];
-	const aging = [];
-	for (const spec of inventory) {
-		if (alreadyRunning.has(specKey(spec))) continue;
-		const edge = edges.get(specKey(spec));
-		if (edge === void 0) missing.push(spec);
-		else if (now - edge.measuredAt > REMEASURE_AFTER_MS) aging.push({
-			spec,
-			measuredAt: edge.measuredAt
-		});
-	}
-	aging.sort((a, b) => a.measuredAt - b.measuredAt);
-	const specs = [...missing, ...aging.map((entry) => entry.spec)].slice(0, limit);
-	const missingTaken = Math.min(missing.length, specs.length);
-	return {
-		specs,
-		missing: missingTaken,
-		aging: specs.length - missingTaken
-	};
-}
-//#endregion
 //#region src/run/pipeline.ts
 async function resolveVitestConfig(cwd) {
 	const userConfig = resolve(cwd, ".ccqa/vitest.config.ts");
@@ -16877,10 +16892,6 @@ async function executeRun(targets, opts) {
 	if (rerunProfile !== null && hubCtx == null) throw new RunUsageError(needsHubConnection("--only-hub-rerun-needed"));
 	if (opts.reportToHub && hubCtx == null) throw new RunUsageError(REPORT_TO_HUB_NEEDS_CONNECTION);
 	if (opts.learnHubLivePrompt && hubCtx == null) throw new RunUsageError(needsHubConnection("--learn-hub-live-prompt"));
-	if ((opts.measureBackfill ?? 0) > 0) {
-		if (opts.coverage !== true) throw new RunUsageError("--measure-backfill does nothing without --coverage — there is no measurement to keep fresh");
-		if (!filtering) throw new RunUsageError("--measure-backfill needs a selection flag (--only-hub-rerun-needed / --only-affected-by); an explicit spec list runs exactly what was asked");
-	}
 	let coverageInbox;
 	if (opts.coverageInbox === "hub") {
 		if (opts.coverage !== true) throw new RunUsageError("--coverage-inbox hub does nothing without --coverage — there is no measurement to stream");
@@ -16929,7 +16940,6 @@ async function executeRun(targets, opts) {
 	};
 	const enumerateAll = () => listAllSpecsWithSpecFile(cwd);
 	let specs = dedupeSpecs((await Promise.all((targets.length ? targets : [void 0]).map((t) => resolveSpecTargets(t, enumerateAll, cwd)))).flat());
-	const inventory = specs;
 	if (filtering) {
 		const before = specs.length;
 		let inProgress = 0;
@@ -16960,14 +16970,6 @@ async function executeRun(targets, opts) {
 			throw new RunUsageError("nothing was selected and no spec was cleared to run: exiting non-zero rather than reporting a green run that verified nothing");
 		}
 	}
-	if (filtering && (opts.measureBackfill ?? 0) > 0 && hubCtx != null) {
-		const edges = await loadCoverageEdges(hubCtx);
-		const pick = chooseMeasureBackfill(inventory, specs, edges, opts.measureBackfill ?? 0, Date.now());
-		if (pick.specs.length > 0) {
-			specs = [...specs, ...pick.specs];
-			meta("measure-backfill", `${pick.specs.length} spec(s) appended (${pick.missing} unmeasured / ${pick.aging} aging)`);
-		}
-	}
 	if (specs.length === 0) {
 		warn("no specs to run");
 		return {
@@ -17134,8 +17136,9 @@ async function executeRun(targets, opts) {
 		report: incrementalReport
 	};
 	const live = await runLiveSpecs(liveSpecs, liveOpts);
+	let streamedEdges = {};
 	if (coverage && !coverage.streamsToHub) reportCoverageHealth(coverage, [...externalRows, ...live.reportResults]);
-	else if (coverage && hubCtx != null) await reportStreamedCoverageHealth(coverage, hubCtx);
+	else if (coverage && hubCtx != null) streamedEdges = await reportStreamedCoverageHealth(coverage, hubCtx);
 	let overallExitCode = det.exitCode !== 0 ? 1 : 0;
 	if (live.failedCount > 0) overallExitCode = 1;
 	if (externalRows.some((r) => r.status === "failed")) overallExitCode = 1;
@@ -17179,6 +17182,10 @@ async function executeRun(targets, opts) {
 			coverage
 		});
 		completedNormally = true;
+		if (coverage && hubCtx != null) {
+			if (coverage.streamsToHub) await upsertMeasuredEdges(hubCtx, streamedEdges);
+			else if (hubRunId != null && coverage.heardFromApplication()) await upsertMeasuredEdges(hubCtx, Object.fromEntries(report.results.filter((row) => (row.coverage?.files.length ?? 0) > 0).map((row) => [`${row.feature}/${row.spec}`, { files: row.coverage.files }])));
+		}
 		if (hubRunId) {
 			const finalStatus = overallExitCode === 0 ? "passed" : "failed";
 			const reportMeta = buildReportEnvelope({
@@ -17289,6 +17296,10 @@ function explainMissingCoverage(row) {
 * Best-effort — the measurement already left as events, so a failed read-out
 * loses visibility, never data. Application pushes may still land for
 * `GRACE_MS` after the last window closed, so the counts here are a floor.
+*
+* Returns the specs the resolve measured, keyed `feature/spec` — the caller
+* merges them into the ledger alongside the local mode's rows, so the "run
+* end records measured reach" step lives in one place for both modes.
 */
 async function reportStreamedCoverageHealth(coverage, hubCtx) {
 	await new Promise((resolve) => setTimeout(resolve, 3e3));
@@ -17297,11 +17308,11 @@ async function reportStreamedCoverageHealth(coverage, hubCtx) {
 		resolved = (await hubCtx.hub.getCoverage(hubCtx.project, { runId: coverage.streamRunId })).resolved;
 	} catch (error) {
 		warn(`coverage: could not read this run's resolve from the hub (${errMessage(error)})`);
-		return;
+		return {};
 	}
 	if (resolved == null) {
 		warn("coverage: the hub resolved nothing for this run — its events never reached the stream, so every spec's measured reach is absent");
-		return;
+		return {};
 	}
 	const measured = resolved.specs.filter((spec) => spec.files.length > 0);
 	const empty = resolved.specs.filter((spec) => spec.files.length === 0);
@@ -17320,6 +17331,30 @@ async function reportStreamedCoverageHealth(coverage, hubCtx) {
 	const outside = Object.entries(h.outsideWindowEvents);
 	if (outside.length > 0) trouble.push(`outside-window=${outside.map(([key, count]) => `${key}:${count}`).join(",")}`);
 	if (trouble.length > 0) warn(`coverage: stream health flags — ${trouble.join(" ")}`);
+	if (!h.heardFromApplication) return {};
+	return Object.fromEntries(measured.flatMap((spec) => {
+		const key = specKeyFromSpecId(spec.specId, resolved.runId);
+		return key === null ? [] : [[key, {
+			files: spec.files,
+			runId: resolved.runId
+		}]];
+	}));
+}
+/**
+* Merge what this run measured into the hub's coverage-edge ledger
+* (ADR-0026) — the document selection reads. Best-effort: the measurement
+* also lives in the stream or the report, so a failed merge loses freshness,
+* not data. A hub without the endpoint (predating it) warns once and moves on.
+*/
+async function upsertMeasuredEdges(hubCtx, specs) {
+	const count = Object.keys(specs).length;
+	if (count === 0) return;
+	try {
+		await hubCtx.hub.putCoverageEdges(hubCtx.project, { specs });
+		meta("coverage", `${count} spec edge(s) recorded on the hub's ledger`);
+	} catch (error) {
+		warn(`coverage: could not record measured edges on the hub (${errMessage(error)})`);
+	}
 }
 /** Everything the measurement could not place; silence here reads as "never reached". */
 function reportCoverageHealth(coverage, rows) {
@@ -17940,11 +17975,7 @@ const runCommand = addHubOptions(addProfileOption(addLanguageOption(new Command(
 }, "text").option("--report-to-hub", "Incrementally push the run report to the hub as the run progresses (open → patch per spec → finalize). Requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN). Without it, hub credentials are used only to fetch variables/sessions/prompts, not to push.").option("--coverage", "Measure what each spec actually reached in the application under test, and record it on the spec's report row. Needs a `coverage:` block in .ccqa/config.yaml naming the instrumented origins the spec cookie may go to. The browser half attaches to the target's browser from outside (nothing is emitted into generated tests; needs node 22+); the server half needs the application running with ccqa-tools.").option("--coverage-inbox <where>", "With --coverage: where the measurement's two sides meet. 'local' (default) binds a loopback inbox on this machine for the run's duration; 'hub' appends every event to the hub's durable coverage inbox instead — nothing listens on the runner, report.json carries no coverage, and the hub resolves per-spec results on read (requires a hub connection).", (raw) => {
 	if (COVERAGE_INBOX_MODES.includes(raw)) return raw;
 	throw new Error(`--coverage-inbox must be one of ${COVERAGE_INBOX_MODES.join(" | ")}`);
-}, "local").option("--measure-backfill <n>", "With --coverage and a selection flag (--only-hub-rerun-needed / --only-affected-by): also run up to <n> specs whose measured reach is missing or past half its freshness window, unmeasured-first then oldest-first. This is what keeps selection's edges alive — without it an unmeasured spec answers `unknown` forever, because `unknown` marks nothing due and nothing else re-measures.", (raw) => {
-	const n = Number(raw);
-	if (!Number.isInteger(n) || n < 0) throw new Error("--measure-backfill must be a non-negative integer");
-	return n;
-}).optionsGroup("Learning:").option("--learn-hub-live-prompt", "(live only) After the run finishes, ask Claude to refresh the \"live.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(async (targets, opts) => {
+}, "local").optionsGroup("Learning:").option("--learn-hub-live-prompt", "(live only) After the run finishes, ask Claude to refresh the \"live.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(async (targets, opts) => {
 	await runCliAction(targets, opts);
 });
 /** Parse --concurrency: a positive integer. Rejects 0, negatives, non-integers. */
@@ -21503,7 +21534,7 @@ async function runSelectSpecs(opts) {
 		project: opts.project,
 		cwd: opts.cwd
 	});
-	const [specsResult, changedResult, edges] = await Promise.all([
+	const [specsResult, changedResult, edgesReadout] = await Promise.all([
 		loadSpecInventory(cwd).then((specs) => ({
 			ok: true,
 			specs
@@ -21543,7 +21574,7 @@ async function runSelectSpecs(opts) {
 		meta("project", project);
 		meta("changed-files", changed.length);
 		meta("specs", specs.length);
-		meta("measured-specs", edges.size);
+		meta("measured-specs", edgesReadout.edges.size);
 	}
 	const report = await selectSpecs({
 		changed,
@@ -21551,7 +21582,7 @@ async function runSelectSpecs(opts) {
 		cwd,
 		base: opts.base,
 		head,
-		edges
+		edges: edgesReadout
 	});
 	process.stdout.write(format === "json" ? `${JSON.stringify(report, null, 2)}\n` : renderText(report));
 	process.exit(0);
@@ -23471,6 +23502,32 @@ function requireSinceSeqParam(url) {
 	if (!Number.isInteger(value) || value < 0) throw new HttpError(400, "invalid_param", "invalid sinceSeq: must be a non-negative integer");
 	return value;
 }
+const MAX_EDGES_BODY_BYTES = 8 * 1024 * 1024;
+/**
+* PUT /api/v1/projects/:project/coverage-edges — the specs one run measured,
+* merged into the ledger newest-wins. `measuredAt` is stamped here with the
+* hub's clock, so entries written by different runners stay comparable.
+* Bearer-authenticated like every project route; the append-only coverage
+* token cannot write here.
+*/
+function createPutCoverageEdgesHandler(config) {
+	return async (ctx) => {
+		const project = requireSafeSegment(ctx.params.project, "project");
+		const body = await readJsonBody(ctx.req, MAX_EDGES_BODY_BYTES, CoverageEdgesUpsertSchema, "coverage-edges body");
+		await config.store.merge(project, body.specs, Date.now());
+		ctx.res.statusCode = 204;
+		ctx.res.end();
+	};
+}
+/** GET /api/v1/projects/:project/coverage-edges — the ledger, or 404. */
+function createGetCoverageEdgesHandler(config) {
+	return async (ctx) => {
+		const project = requireSafeSegment(ctx.params.project, "project");
+		const doc = await config.store.get(project);
+		if (doc === null) throw new HttpError(404, "not_found", `no coverage edges stored for project "${project}"`);
+		sendJson(ctx.res, 200, doc);
+	};
+}
 //#endregion
 //#region src/hub/core/rerun.ts
 /**
@@ -30781,6 +30838,9 @@ function registerRoutes(router, config, queue) {
 	router.get("/api/v1/projects/:project/perspectives", createGetPerspectivesHandler(perspectivesConfig));
 	router.patch("/api/v1/projects/:project/perspectives", createPatchPerspectivesNoteHandler(perspectivesConfig));
 	router.delete("/api/v1/projects/:project/perspectives", createDeletePerspectivesHandler(perspectivesConfig));
+	const coverageEdgesConfig = { store: storage.coverageEdges };
+	router.put("/api/v1/projects/:project/coverage-edges", createPutCoverageEdgesHandler(coverageEdgesConfig));
+	router.get("/api/v1/projects/:project/coverage-edges", createGetCoverageEdgesHandler(coverageEdgesConfig));
 	const coverageConfig = {
 		store: storage.coverageEvents,
 		encryptionKey: config.encryptionKey,
@@ -30886,6 +30946,9 @@ function perspectivesKindDir(root) {
 function perspectivesPath(root, project) {
 	return join(perspectivesKindDir(root), `${project}.json`);
 }
+function coverageEdgesPath(root, project) {
+	return join(root, "coverage-edges", `${project}.json`);
+}
 function ledgerProfileDir(root, project, profile) {
 	return join(root, "last-green", project, profile);
 }
@@ -31387,6 +31450,47 @@ function createFileSpecLedgerStore(root) {
 	};
 }
 //#endregion
+//#region src/hub/core/storage/file/coverage-edge-store.ts
+/**
+* Coverage-edge ledger (ADR-0026): one JSON document per project. `merge`
+* goes through `updateJson`, so two runs finishing at once queue their
+* read-modify-writes instead of clobbering each other, and each entry only
+* ever moves forward — a run's measurement replaces a spec's entry, never
+* deletes another spec's.
+*/
+function createFileCoverageEdgeStore(root) {
+	return {
+		async get(project) {
+			assertSafeName(project, "project");
+			const raw = await readJson(coverageEdgesPath(root, project));
+			return raw === null ? null : parseDoc(raw, project);
+		},
+		async merge(project, specs, measuredAt) {
+			assertSafeName(project, "project");
+			await updateJson(coverageEdgesPath(root, project), (current) => {
+				const doc = current === null ? { specs: {} } : parseDoc(current, project);
+				for (const [key, entry] of Object.entries(specs)) doc.specs[key] = {
+					files: [...entry.files].sort(),
+					measuredAt,
+					...entry.runId === void 0 ? {} : { runId: entry.runId }
+				};
+				return doc;
+			});
+		}
+	};
+}
+/**
+* A present document that does not parse is an error, never an empty ledger:
+* treating it as empty would let the next merge silently discard every other
+* spec's edge, and the data is regenerated only by running every spec
+* measured again.
+*/
+function parseDoc(raw, project) {
+	const parsed = CoverageEdgesDocSchema.safeParse(raw);
+	if (!parsed.success) throw new Error(`coverage-edges document for project "${project}" does not match the schema`);
+	return parsed.data;
+}
+//#endregion
 //#region src/hub/core/storage/file/perspectives-store.ts
 /**
 * Perspectives storage: one JSON document per project, plain UTF-8 with no
@@ -31693,6 +31797,7 @@ function createFileHubStorage(dataDir) {
 		triage: createFileTriageStore(dataDir),
 		prompts: createFilePromptStore(dataDir),
 		perspectives: createFilePerspectivesStore(dataDir),
+		coverageEdges: createFileCoverageEdgeStore(dataDir),
 		jobs: createFileJobStore(dataDir),
 		ledger: createFileSpecLedgerStore(dataDir),
 		driftLedger: createFileDriftLedgerStore(dataDir),

package/dist/hub-client/index.d.mts

@@ -547,6 +547,26 @@ declare const SpendLogResponseSchema: z.ZodObject<{
   }, z.core.$strip>>;
 }, z.core.$strip>;
 type SpendLogResponse = z.infer<typeof SpendLogResponseSchema>;
+declare const CoverageEdgesDocSchema: z.ZodObject<{
+  specs: z.ZodRecord<z.ZodString, z.ZodObject<{
+    files: z.ZodArray<z.ZodString>;
+    measuredAt: z.ZodNumber;
+    runId: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type CoverageEdgesDoc = z.infer<typeof CoverageEdgesDocSchema>;
+/**
+ * Body of `PUT /projects/:project/coverage-edges` — the specs one run
+ * measured. Merged into the stored document, never replacing other specs'
+ * entries; an empty file set is not a measurement and is rejected per entry.
+ */
+declare const CoverageEdgesUpsertSchema: z.ZodObject<{
+  specs: z.ZodRecord<z.ZodString, z.ZodObject<{
+    files: z.ZodArray<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type CoverageEdgesUpsert = z.infer<typeof CoverageEdgesUpsertSchema>;
 //#endregion
 //#region src/coverage/resolve-stream.d.ts
 /**
@@ -1159,6 +1179,13 @@ interface HubClient {
   getCoverage(project: string, q?: {
     runId?: string;
   }): Promise<HubCoverageAnswer>;
+  /**
+   * Merge one run's measured reach into the project's coverage-edge ledger
+   * (ADR-0026). The hub stamps `measuredAt` with its own clock.
+   */
+  putCoverageEdges(project: string, upsert: CoverageEdgesUpsert): Promise<void>;
+  /** The coverage-edge ledger, or `null` when nothing is stored (or the hub predates it). */
+  getCoverageEdges(project: string): Promise<CoverageEdgesDoc | null>;
   /**
    * Source maps for what a commit deployed, addressed by the asset path the
    * browser requests. Coverage falls back to these when the build keeps its

package/dist/hub-client/index.mjs

@@ -153,6 +153,21 @@ function createHubClient(opts) {
 				runId: q.runId
 			})}`);
 		},
+		putCoverageEdges(project, upsert) {
+			return request(`/api/v1/projects/${encodeURIComponent(project)}/coverage-edges`, {
+				method: "PUT",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(upsert)
+			}).then(() => void 0);
+		},
+		async getCoverageEdges(project) {
+			try {
+				return await json(`/api/v1/projects/${encodeURIComponent(project)}/coverage-edges`);
+			} catch (err) {
+				if (err instanceof HubApiError && err.status === 404) return null;
+				throw err;
+			}
+		},
 		putSourceMap(project, commit, assetPath, map) {
 			return request(`${sourceMapPath(project, commit)}/${encodeAssetPath(assetPath)}`, {
 				method: "PUT",

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.41.0",
+  "version": "1.42.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.41.0",
+  "version": "1.42.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {