ccqa 1.40.8 → 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.
@@ -6422,6 +6440,7 @@ var FrontendResolution = class {
 	coverageDir;
 	roots;
 	fetchText;
+	fetchStoredMap;
 	warn;
 	files = /* @__PURE__ */ new Set();
 	/**
@@ -6448,6 +6467,7 @@ var FrontendResolution = class {
 		this.coverageDir = opts.coverageDir;
 		this.roots = opts.roots;
 		this.fetchText = opts.fetchText;
+		this.fetchStoredMap = opts.fetchStoredMap;
 		this.warn = opts.warn;
 	}
 	async absorb(script) {
@@ -6538,24 +6558,46 @@ var FrontendResolution = class {
 	async fetchSourceMap(script) {
 		const source = await script.source();
 		if (source === void 0) return void 0;
+		for (const load of this.sourceMapLoaders(script, source)) {
+			const json = await load();
+			if (json === void 0) continue;
+			const map = parseSourceMap(json);
+			if (map !== void 0) return prepareSourceMap(map, source);
+		}
+	}
+	/**
+	* Ways to get a map for `script`, most authoritative first and none of them
+	* taken until the one before it fails. A map the script points at describes
+	* the code that ran, so the stored copy is only asked for when that is
+	* absent or turns out not to be a map — a catch-all route answers a missing
+	* `.map` with an HTML page, which is a body but not a map. Reading it
+	* eagerly would put a request on the wire for every script of every spec,
+	* nearly all of them misses on a deployment that pushes nothing.
+	*/
+	sourceMapLoaders(script, source) {
+		const loaders = [];
 		const reference = readSourceMappingUrl(source);
-		if (reference === void 0) return void 0;
-		let json = decodeInlineSourceMap(reference);
-		if (json === void 0) {
-			let target;
-			try {
-				target = new URL(reference, script.url).toString();
-			} catch {
-				return;
+		if (reference !== void 0) {
+			const inline = decodeInlineSourceMap(reference);
+			if (inline !== void 0) loaders.push(() => Promise.resolve(inline));
+			else {
+				const target = absoluteOrUndefined(reference, script.url);
+				if (target !== void 0) loaders.push(() => this.fetchText(target));
 			}
-			json = await this.fetchText(target);
-			if (json === void 0) return void 0;
 		}
-		const map = parseSourceMap(json);
-		if (map === void 0) return void 0;
-		return prepareSourceMap(map, source);
+		const stored = this.fetchStoredMap;
+		if (stored !== void 0) loaders.push(() => stored(script.url));
+		return loaders;
 	}
 };
+/** `reference` resolved against the script's URL, or undefined when it is not a URL. */
+function absoluteOrUndefined(reference, scriptUrl) {
+	try {
+		return new URL(reference, scriptUrl).toString();
+	} catch {
+		return;
+	}
+}
 function message$2(error) {
 	return error instanceof Error ? error.message : String(error);
 }
@@ -7149,6 +7191,7 @@ var Engine = class {
 			coverageDir: opts.coverageDir,
 			roots: opts.roots,
 			fetchText: (url) => this.fetchThroughBrowser(url),
+			fetchStoredMap: (scriptUrl) => this.storedMapFor(scriptUrl),
 			warn: opts.warn
 		});
 	}
@@ -7414,6 +7457,23 @@ var Engine = class {
 			return;
 		}
 	}
+	/**
+	* The map a deploy stored for `scriptUrl`, if this run knows where to ask.
+	* Addressed by the path under the asset origin rather than the URL, so the
+	* push and the read agree without either knowing the other's host.
+	*/
+	async storedMapFor(scriptUrl) {
+		const stored = this.opts.fetchStoredSourceMap;
+		if (stored === void 0) return void 0;
+		const assetPath = assetPathOf(scriptUrl, [...this.opts.origins, ...this.opts.assetOrigins ?? []]);
+		if (assetPath === void 0) return void 0;
+		try {
+			return await stored(`${assetPath}.map`);
+		} catch (err) {
+			this.opts.warn(`could not read the stored source map for ${assetPath}: ${message(err)}`);
+			return;
+		}
+	}
 	async readStream(handle, sessionId) {
 		const parts = [];
 		for (;;) {
@@ -7428,6 +7488,25 @@ var Engine = class {
 function message(error) {
 	return error instanceof Error ? error.message : String(error);
 }
+/**
+* The path a stored map is filed under: the URL with its origin removed, and
+* with any deploy-scoped prefix (`/assets/<sha>/`) left in place — that prefix
+* is part of what the browser asked for, so the push has to have used it too.
+* A URL from an origin the run never declared is not ours to look up.
+*/
+function assetPathOf(url, origins) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return;
+	}
+	const path = `${parsed.origin}${parsed.pathname}`;
+	for (const origin of origins) {
+		const base = origin.replace(/\/+$/, "");
+		if (path.startsWith(`${base}/`)) return path.slice(base.length + 1);
+	}
+}
 //#endregion
 //#region src/coverage/universe.ts
 /**
@@ -7503,8 +7582,20 @@ async function walk(abs, rel, out, warn) {
 const SETTLE_POLL_MS = 250;
 const SETTLE_QUIET_POLLS = 10;
 const SETTLE_CAP_MS = 1e4;
+/**
+* Origins with their `${VAR}`s resolved, refusing anything that is not an
+* absolute http(s) URL. An unset variable resolves to the empty string, which
+* would otherwise match nothing and take the feature down without a word.
+*/
+function resolveAbsoluteOrigins(origins, label) {
+	const resolved = origins.map((origin) => resolveEnvRefs(origin));
+	const unresolved = resolved.filter((origin) => !/^https?:\/\//i.test(origin));
+	if (unresolved.length > 0) throw new Error(`${label} must be absolute http(s) URLs after variable substitution; got ${unresolved.join(", ")}`);
+	return resolved;
+}
 var CoverageSession = class CoverageSession {
 	existing = /* @__PURE__ */ new Map();
+	fetchStoredSourceMap;
 	/**
 	* Undefined in hub mode: nothing binds on the runner, and every read-side
 	* answer here stays empty — interpretation lives in the hub's resolve
@@ -7525,13 +7616,15 @@ var CoverageSession = class CoverageSession {
 	cwd;
 	actors;
 	origins;
+	/** Where this project's assets come from — the cookie never goes here. */
+	assetOrigins;
 	/**
 	* The denominator, enumerated once at start, or undefined when
 	* `coverage.include` is unset — and always in hub mode, where it travels as
 	* a `universe` event instead of riding the report envelope.
 	*/
 	universe;
-	constructor(sink, inbox, runId, root, cwd, actors, origins, universe) {
+	constructor(sink, inbox, runId, root, cwd, actors, origins, assetOrigins, universe, fetchStoredSourceMap) {
 		this.sink = sink;
 		this.inbox = inbox;
 		this.runId = runId;
@@ -7539,12 +7632,12 @@ var CoverageSession = class CoverageSession {
 		this.cwd = cwd;
 		this.actors = actors;
 		this.origins = origins;
+		this.assetOrigins = assetOrigins;
 		this.universe = universe;
+		this.fetchStoredSourceMap = fetchStoredSourceMap;
 	}
 	static async start(options) {
-		const origins = options.config.instrumentedOrigins.map((origin) => resolveEnvRefs(origin));
-		const unresolved = origins.filter((origin) => !/^https?:\/\//i.test(origin));
-		if (unresolved.length > 0) throw new Error(`coverage.instrumentedOrigins must be absolute http(s) URLs after variable substitution; got ${unresolved.join(", ")}`);
+		const origins = resolveAbsoluteOrigins(options.config.instrumentedOrigins, "coverage.instrumentedOrigins");
 		const actors = options.actors ?? NO_ACTORS;
 		let sink;
 		if (options.inbox === void 0) {
@@ -7560,7 +7653,7 @@ var CoverageSession = class CoverageSession {
 			include: [...universe.include],
 			files: [...universe.files]
 		});
-		return new CoverageSession(sink, options.inbox, options.runId, root, options.cwd, actors, origins, options.inbox === void 0 ? universe : void 0);
+		return new CoverageSession(sink, options.inbox, options.runId, root, options.cwd, actors, origins, resolveAbsoluteOrigins(options.config.assetOrigins ?? [], "coverage.assetOrigins"), options.inbox === void 0 ? universe : void 0, options.fetchStoredSourceMap);
 	}
 	/**
 	* Ties the stream's run id to the hub's run record. The session starts
@@ -7635,12 +7728,14 @@ var CoverageSession = class CoverageSession {
 			cdpUrl,
 			specId: specIdFor(this.runId, ref),
 			origins: this.origins,
+			assetOrigins: this.assetOrigins,
 			coverageDir,
 			roots: {
 				base: this.cwd,
 				root: this.root
 			},
-			warn: (text) => warn(`coverage: ${text}`)
+			warn: (text) => warn(`coverage: ${text}`),
+			fetchStoredSourceMap: this.fetchStoredSourceMap
 		});
 	}
 	/**
@@ -7828,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 {
@@ -10244,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
 /**
@@ -10843,6 +10952,177 @@ function readOctal(buf, offset, fieldLen) {
 	return str === "" ? 0 : parseInt(str, 8);
 }
 //#endregion
+//#region src/hub/core/storage/file/fs-helpers.ts
+/**
+* Defense-in-depth for a name this layer joins into a file path. The API's
+* `SAFE_SEGMENT` (api/validate.ts) is deliberately stricter — it also fixes a
+* charset and a length — and stays the rule for what a client may name; this
+* only refuses traversal, so it also covers callers that never came through
+* HTTP (tests, a library embedding the hub).
+*/
+function assertSafeName(value, label) {
+	if (value.length === 0 || value === "." || value === ".." || value.includes("/") || value.includes("\\")) throw new Error(`invalid ${label}: must be a bare name without path separators or '..'`);
+}
+/** Read and JSON-parse a file, returning `null` when it doesn't exist. Malformed JSON throws. */
+async function readJson(path) {
+	let raw;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (err) {
+		if (isNotFound(err)) return null;
+		throw err;
+	}
+	try {
+		return JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`corrupt JSON at ${path}: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+/**
+* Write `data` to a temp file in the same directory, then atomically rename it
+* into place, so a concurrent reader only ever observes the old file or the
+* fully-written new one — never the empty/partial window a plain
+* truncate-then-write leaves open (e.g. a `putActualCause` writing a run's
+* triage file while an API request reads it). The temp file lives in the same
+* directory as its target to keep the rename on one filesystem, where it is
+* atomic.
+*/
+async function atomicWrite(path, data) {
+	await mkdir(dirname(path), { recursive: true });
+	const tmp = `${path}.${randomUUID()}.tmp`;
+	await writeFile(tmp, data);
+	await rename(tmp, path);
+}
+/** Write `value` as pretty JSON, creating parent directories as needed. */
+async function writeJson(path, value) {
+	await atomicWrite(path, JSON.stringify(value, null, 2) + "\n");
+}
+/**
+* Per-path serialization for read-modify-write JSON updates. Two concurrent
+* `updateJson` calls on the same path (e.g. two `putActualCause` calls racing
+* on the same run's triage file) would otherwise both read the same starting
+* state and the second writer's change would silently clobber the first's —
+* this queues the second call's read until the first's write has landed, so
+* updates apply in the order they were issued rather than racing. Scoped by
+* path (a `Map` of chained promises), not globally, so unrelated records still
+* update concurrently.
+*/
+const updateChains = /* @__PURE__ */ new Map();
+/**
+* Queue `work` behind whatever is already in flight for `path`. A delete takes
+* the same chain as the updates it removes: `writeJson` recreates the parent
+* directory, so an unordered delete would be silently undone by an update that
+* was already queued.
+*/
+async function serialize(path, work) {
+	const next = (updateChains.get(path) ?? Promise.resolve()).catch(() => {}).then(work);
+	updateChains.set(path, next);
+	try {
+		return await next;
+	} finally {
+		if (updateChains.get(path) === next) updateChains.delete(path);
+	}
+}
+async function updateJson(path, mutate) {
+	return await serialize(path, async () => {
+		const updated = mutate(await readJson(path));
+		await writeJson(path, updated);
+		return updated;
+	});
+}
+/** Read a raw file, returning `null` when it doesn't exist. */
+async function readBytesOrNull(path) {
+	try {
+		const buf = await readFile(path);
+		return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+	} catch (err) {
+		if (isNotFound(err)) return null;
+		throw err;
+	}
+}
+async function writeBytes(path, bytes) {
+	await atomicWrite(path, bytes);
+}
+/** List entry names (files or dirs) directly under `dir`, or `[]` when it doesn't exist. */
+async function listDirOrEmpty(dir) {
+	try {
+		return await readdir(dir);
+	} catch (err) {
+		if (isNotFound(err)) return [];
+		throw err;
+	}
+}
+/**
+* Subdirectory names directly under `dir`, or `[]` when it doesn't exist.
+* Skips files and dot-entries so stray filesystem litter (e.g. a Finder
+* `.DS_Store`) never surfaces as a record id or project name.
+*/
+async function listSubdirsOrEmpty(dir) {
+	try {
+		return (await readdir(dir, { withFileTypes: true })).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name);
+	} catch (err) {
+		if (isNotFound(err)) return [];
+		throw err;
+	}
+}
+/** Every file path under `dir`, relative to `dir`, posix-separated. */
+async function listFilesRecursive(dir) {
+	const out = [];
+	async function walk(current) {
+		let entries;
+		try {
+			entries = await readdir(current, { withFileTypes: true });
+		} catch (err) {
+			if (isNotFound(err)) return;
+			throw err;
+		}
+		for (const entry of entries) {
+			const abs = join(current, entry.name);
+			if (entry.isDirectory()) await walk(abs);
+			else if (entry.isFile()) out.push(relative(dir, abs).split(sep).join("/"));
+		}
+	}
+	await walk(dir);
+	return out;
+}
+async function removePath(path) {
+	await rm(path, {
+		recursive: true,
+		force: true
+	});
+}
+function isNotFound(err) {
+	return err instanceof Error && "code" in err && err.code === "ENOENT";
+}
+//#endregion
+//#region src/coverage/frontend/reduce-map.ts
+/**
+* `json` reduced to the readable fields, or undefined when it is not a source
+* map this side can use — the same refusals `parseSourceMap` makes, applied at
+* push time so an unusable map is never stored.
+*/
+function reduceSourceMap(json) {
+	let parsed;
+	try {
+		parsed = JSON.parse(json);
+	} catch {
+		return;
+	}
+	if (typeof parsed !== "object" || parsed === null) return void 0;
+	const map = parsed;
+	if (map.sections !== void 0) return void 0;
+	if (map.version !== 3) return void 0;
+	if (typeof map.mappings !== "string") return void 0;
+	if (!Array.isArray(map.sources)) return void 0;
+	return {
+		version: 3,
+		sources: map.sources,
+		mappings: map.mappings,
+		...typeof map.sourceRoot === "string" ? { sourceRoot: map.sourceRoot } : {},
+		...typeof map.file === "string" ? { file: map.file } : {}
+	};
+}
+//#endregion
 //#region src/runtime/session-state.ts
 /** Default per-profile sessions root, relative to the project (`--cwd`). */
 const SESSIONS_SUBDIR = ".ccqa/sessions";
@@ -11401,6 +11681,7 @@ const CoverageActorsSchema = z.record(z.string().regex(/^[a-z0-9][a-z0-9._-]*$/i
 */
 const CoverageConfigSchema = z.object({
 	instrumentedOrigins: z.array(z.string().min(1)).min(1),
+	assetOrigins: z.array(z.string().min(1)).optional(),
 	sink: z.string().min(1).default("http://127.0.0.1:4757"),
 	projectRoot: z.string().min(1).optional(),
 	include: z.array(z.string().min(1)).optional(),
@@ -11470,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;
@@ -11566,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,
@@ -11662,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;
@@ -11713,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.
@@ -11741,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;
@@ -11767,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
 			});
 		}
@@ -12307,6 +12619,49 @@ const varRm = new Command("rm").description("Delete a variable from the hub.").a
 	info(`deleted variable "${name}" from the hub`);
 }));
 const varCommand = new Command("var").description("Manage environment variables stored on the hub (fetched at run time by `ccqa run` / `ccqa record`).").addCommand(varSet).addCommand(varLs).addCommand(varRm);
+const sourcemapPush = new Command("push").description("Upload the source maps a build produced, so `ccqa run --coverage` can name frontend files when the build keeps its maps off the CDN. Only the fields coverage reads are sent — the original source each map carries is dropped rather than stored.").argument("<dir>", "Directory holding the build output (e.g. `.next/static`).").requiredOption("--sha <sha>", "Commit these assets were built from — the same one the deploy is recorded under.").option("--asset-prefix <path>", "Path the files are served under, prepended to each stored path (e.g. `_next/static`). Match what the browser requests, minus the origin.", "").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption).option(...cwdOption).action(withHubErrors(async (dirArg, opts) => {
+	const project = resolveProject(opts);
+	const hub = connect$2(opts);
+	const dir = resolve(resolveCwd(opts.cwd), dirArg);
+	if (!existsSync(dir)) throw new Error(`no such directory: ${dir}`);
+	const maps = (await listFilesRecursive(dir)).filter((f) => f.endsWith(".map"));
+	const prefix = opts.assetPrefix.replace(/^\/+|\/+$/g, "");
+	header("hub sourcemap push", `${project}@${opts.sha.slice(0, 12)}`);
+	meta("dir", dir);
+	if (maps.length === 0) {
+		warn(`no *.map under ${dir} — nothing to push (was the build run with source maps enabled?)`);
+		return;
+	}
+	let pushed = 0;
+	let bytes = 0;
+	const unusable = [];
+	for (const rel of maps) {
+		const reduced = reduceSourceMap(await readFile(join(dir, rel), "utf8"));
+		if (reduced === void 0) {
+			unusable.push(rel);
+			continue;
+		}
+		const body = new TextEncoder().encode(JSON.stringify(reduced));
+		await hub.putSourceMap(project, opts.sha, prefix ? `${prefix}/${rel}` : rel, body);
+		pushed++;
+		bytes += body.length;
+	}
+	if (unusable.length > 0) warn(`${unusable.length} map(s) were not source maps this side can read, e.g. ${unusable[0]}`);
+	await hub.sweepSourceMaps(project);
+	info(`pushed ${pushed} source map(s), ${Math.round(bytes / 1024)} KiB`);
+}));
+const sourcemapLs = new Command("ls").description("List the source maps stored for a commit.").requiredOption("--sha <sha>", "The commit to list.").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption).option(...cwdOption).action(withHubErrors(async (opts) => {
+	const project = resolveProject(opts);
+	const paths = await connect$2(opts).listSourceMaps(project, opts.sha);
+	header("hub sourcemap ls", `${project}@${opts.sha.slice(0, 12)}`);
+	if (paths.length === 0) {
+		info("no source maps stored for this commit");
+		return;
+	}
+	for (const path of paths) meta("", path);
+	info(`${paths.length} source map(s)`);
+}));
+const sourcemapCommand = new Command("sourcemap").description("Manage the source maps coverage reads when a build keeps its maps off the CDN (pushed at deploy time, fetched during `ccqa run --coverage`).").addCommand(sourcemapPush).addCommand(sourcemapLs);
 function validatePromptName(rawName) {
 	if (!isPromptName(rawName)) {
 		error(`invalid prompt name "${rawName}"`);
@@ -12595,7 +12950,7 @@ async function runCoverageInspect(opts) {
 	const outside = Object.entries(h.outsideWindowEvents);
 	if (outside.length > 0) warn(`outside-window events (identity was driven while unclaimed): ${outside.map(([key, count]) => `${key}: ${count}`).join(", ")}`);
 }
-const hubCommand = new Command("hub").description("Client for a ccqa hub: push run results and manage sessions/variables/prompts used by `ccqa run`. See docs/hub.md.").addCommand(pushCommand).addCommand(deployCommand).addCommand(costCommand).addCommand(coverageCommand).addCommand(sessionCommand).addCommand(varCommand).addCommand(promptCommand).addCommand(attestCommand).addCommand(dismissCommand);
+const hubCommand = new Command("hub").description("Client for a ccqa hub: push run results and manage sessions/variables/prompts used by `ccqa run`. See docs/hub.md.").addCommand(pushCommand).addCommand(deployCommand).addCommand(costCommand).addCommand(coverageCommand).addCommand(sessionCommand).addCommand(varCommand).addCommand(sourcemapCommand).addCommand(promptCommand).addCommand(attestCommand).addCommand(dismissCommand);
 /** Loose check that a fetched session is agent-browser storage-state, mirroring loadStorageState. */
 function isStorageStateShape(state) {
 	return typeof state === "object" && state !== null && Array.isArray(state.cookies) && Array.isArray(state.origins);
@@ -16334,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;
@@ -16360,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");
@@ -16585,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");
@@ -16637,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;
@@ -16668,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 {
@@ -16730,7 +17024,7 @@ async function executeRun(targets, opts) {
 	const liveSpecs = withMode.filter((s) => s.mode === "live");
 	meta("modes", `${detSpecs.length} deterministic / ${liveSpecs.length} live`);
 	if (dispatch.external.length > 0) meta("external", dispatch.external.map((g) => `${g.targetId} ${g.specs.length}`).join(" / "));
-	const coverage = opts.coverage && forExecution ? await startCoverage(cwd, projectConfig.coverage, actors, dispatch, opts.teardown, coverageInbox) : void 0;
+	const coverage = opts.coverage && forExecution ? await startCoverage(cwd, projectConfig.coverage, actors, dispatch, opts.teardown, coverageInbox, storedSourceMapReader(hubCtx, deployedSha), hubCtx !== null) : void 0;
 	if (liveSpecs.length === 0) {
 		const why = "it only applies to agent-browser 'mode: live' specs, and this run has none";
 		if (typeof opts.liveStepRetry === "number" && opts.liveStepRetry > 0) warn(`--live-step-retry is ignored: ${why}`);
@@ -16842,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;
@@ -16887,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({
@@ -16933,13 +17232,7 @@ async function executeRun(targets, opts) {
 		reportDir
 	};
 }
-/**
-* Starts the run's coverage measurement before any spec runs: the sink has to
-* be listening before the first request reaches the application, and the set
-* of spec ids it will accept is only known once dispatch has resolved. With
-* an `inbox`, nothing binds — the run streams its events to the hub instead.
-*/
-async function startCoverage(cwd, config, actors, dispatch, teardown, inbox) {
+async function startCoverage(cwd, config, actors, dispatch, teardown, inbox, fetchStoredSourceMap, hubConfigured) {
 	if (config === void 0) throw new RunUsageError("--coverage needs a `coverage:` block in .ccqa/config.yaml whose `instrumentedOrigins` names the origins the spec cookie may be attached to");
 	let session;
 	try {
@@ -16949,11 +17242,13 @@ async function startCoverage(cwd, config, actors, dispatch, teardown, inbox) {
 			config,
 			actors,
 			specs: dispatch.external.flatMap((g) => g.specs),
-			...inbox ? { inbox } : {}
+			...inbox ? { inbox } : {},
+			...fetchStoredSourceMap ? { fetchStoredSourceMap } : {}
 		});
 	} catch (err) {
 		throw new RunUsageError(`could not start coverage collection: ${errMessage(err)}`);
 	}
+	if (fetchStoredSourceMap === void 0 && hubConfigured) warn("coverage: source maps pushed for this deploy cannot be read — the deployed commit is unknown here. Pass --hub-profile so the deploy log can be consulted.");
 	if (inbox !== void 0) meta("coverage", `streaming to hub inbox → ${session.origins.join(", ")}`);
 	else meta("coverage", `sink ${session.sinkUrl} → ${session.origins.join(", ")}`);
 	const unmeasured = dispatch.external.filter((g) => g.browserCoverage.browser === "none").length;
@@ -16962,6 +17257,28 @@ async function startCoverage(cwd, config, actors, dispatch, teardown, inbox) {
 	return session;
 }
 /**
+* Starts the run's coverage measurement before any spec runs: the sink has to
+* be listening before the first request reaches the application, and the set
+* of spec ids it will accept is only known once dispatch has resolved. With
+* an `inbox`, nothing binds — the run streams its events to the hub instead.
+*/
+/**
+* Needs both a hub and the commit under test: without either there is nothing
+* to address a stored map by, and reading some other commit's maps would name
+* the wrong files. See `SourceMapStore`.
+*/
+function storedSourceMapReader(hubCtx, deployedSha) {
+	if (hubCtx === null || deployedSha === null) return void 0;
+	const seen = /* @__PURE__ */ new Map();
+	return async (assetPath) => {
+		const cached = seen.get(assetPath);
+		if (cached !== void 0 || seen.has(assetPath)) return cached;
+		const map = await hubCtx.hub.getSourceMap(hubCtx.project, deployedSha, assetPath) ?? void 0;
+		seen.set(assetPath, map);
+		return map;
+	};
+}
+/**
 * A run that measured coverage still leaves rows without any — a spec on a
 * target that declares no browser, or one that never executed. Saying why keeps
 * the reader from reading a blank as "this spec reached nothing".
@@ -16979,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));
@@ -16987,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);
@@ -17010,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) {
@@ -17630,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. */
@@ -21193,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
@@ -21233,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,
@@ -21241,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);
@@ -21466,6 +21807,20 @@ function mergeBucket(into, from) {
 //#endregion
 //#region src/hub/core/retention.ts
 /**
+* Drop the source maps of every commit past the newest `maxCommits`.
+*
+* Hung off a push for the same reason run retention hangs off a terminal run:
+* the hub whose disk grows is the one written to constantly and never
+* restarted. Best-effort — a lost sweep costs disk, while failing the push it
+* runs beside would cost the deploy.
+*/
+async function sweepSourceMapRetention(storage, project, maxCommits) {
+	try {
+		const commits = await storage.sourceMaps.listCommits(project);
+		for (const commit of commits.slice(maxCommits)) await storage.sourceMaps.delete(project, commit);
+	} catch {}
+}
+/**
 * Drop everything past the newest `maxRuns` of the (project, branch) that
 * `run` belongs to, taking each evicted run's artifacts and triage records
 * with it.
@@ -22402,6 +22757,58 @@ function createGetDriftLedgerHandler(storage) {
 	};
 }
 //#endregion
+//#region src/hub/api/handlers/sourcemaps.ts
+/**
+* A source map is roughly the size of the code it describes, and a single
+* bundle chunk can be a few MB. Generous, but still a ceiling: a push is many
+* small requests rather than one archive, so no single body should approach it.
+*/
+const MAX_MAP_BYTES = 32 * 1024 * 1024;
+function createPutSourceMapHandler(storage) {
+	return async (ctx) => {
+		const project = requireSafeSegment(ctx.params.project, "project");
+		const commit = requireSafeSegment(ctx.params.commit, "commit");
+		const assetPath = requireSafeRelPath(ctx.params.path, "source map path");
+		const body = await readBody(ctx.req, MAX_MAP_BYTES);
+		await storage.sourceMaps.put(project, commit, assetPath, body);
+		ctx.res.statusCode = 204;
+		ctx.res.end();
+	};
+}
+function createGetSourceMapHandler(storage) {
+	return async (ctx) => {
+		const project = requireSafeSegment(ctx.params.project, "project");
+		const commit = requireSafeSegment(ctx.params.commit, "commit");
+		const assetPath = requireSafeRelPath(ctx.params.path, "source map path");
+		const bytes = await storage.sourceMaps.read(project, commit, assetPath);
+		if (!bytes) throw new HttpError(404, "not_found", `no source map stored for "${assetPath}" at ${commit}`);
+		sendBytes(ctx.res, 200, bytes, "application/json; charset=utf-8");
+	};
+}
+/**
+* Ends a push: everything for this commit has landed, so older commits can go.
+* Separate from the PUTs because a push is hundreds of them, and sweeping on
+* each would walk the whole project every time.
+*/
+function createSweepSourceMapsHandler(storage) {
+	return async (ctx) => {
+		await sweepSourceMapRetention(storage, requireSafeSegment(ctx.params.project, "project"), 10);
+		ctx.res.statusCode = 204;
+		ctx.res.end();
+	};
+}
+function createListSourceMapsHandler(storage) {
+	return async (ctx) => {
+		const project = requireSafeSegment(ctx.params.project, "project");
+		const commit = requireSafeSegment(ctx.params.commit, "commit");
+		sendJson(ctx.res, 200, {
+			project,
+			commit,
+			paths: await storage.sourceMaps.list(project, commit)
+		});
+	};
+}
+//#endregion
 //#region src/hub/api/handlers/deploys.ts
 /** `changedPaths` for a wide refactor can run to tens of thousands of entries. */
 const MAX_DEPLOY_BODY_BYTES = 8 * 1024 * 1024;
@@ -23095,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
 /**
@@ -30364,6 +30797,10 @@ function registerRoutes(router, config, queue) {
 	router.get("/api/v1/projects/:project/deploys", createGetDeployLogHandler(storage));
 	router.get("/api/v1/projects/:project/rerun", createGetRerunHandler(storage));
 	router.get("/api/v1/projects/:project/audit-needed", createGetAuditNeedHandler(storage));
+	router.put("/api/v1/projects/:project/sourcemaps/:commit/*path", createPutSourceMapHandler(storage));
+	router.post("/api/v1/projects/:project/sourcemaps/sweep", createSweepSourceMapsHandler(storage));
+	router.get("/api/v1/projects/:project/sourcemaps/:commit", createListSourceMapsHandler(storage));
+	router.get("/api/v1/projects/:project/sourcemaps/:commit/*path", createGetSourceMapHandler(storage));
 	router.post("/api/v1/projects/:project/locks", createAcquireLocksHandler(storage));
 	router.delete("/api/v1/projects/:project/locks", createReleaseLocksHandler(storage));
 	router.get("/api/v1/projects/:project/attestations", createGetAttestationsHandler(storage));
@@ -30401,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,
@@ -30418,149 +30858,6 @@ function registerRoutes(router, config, queue) {
 	router.get("/api/v1/projects/:project/learning-jobs/:jobId", createGetLearningJobHandler(storage));
 }
 //#endregion
-//#region src/hub/core/storage/file/fs-helpers.ts
-/**
-* Defense-in-depth for a name this layer joins into a file path. The API's
-* `SAFE_SEGMENT` (api/validate.ts) is deliberately stricter — it also fixes a
-* charset and a length — and stays the rule for what a client may name; this
-* only refuses traversal, so it also covers callers that never came through
-* HTTP (tests, a library embedding the hub).
-*/
-function assertSafeName(value, label) {
-	if (value.length === 0 || value === "." || value === ".." || value.includes("/") || value.includes("\\")) throw new Error(`invalid ${label}: must be a bare name without path separators or '..'`);
-}
-/** Read and JSON-parse a file, returning `null` when it doesn't exist. Malformed JSON throws. */
-async function readJson(path) {
-	let raw;
-	try {
-		raw = await readFile(path, "utf8");
-	} catch (err) {
-		if (isNotFound(err)) return null;
-		throw err;
-	}
-	try {
-		return JSON.parse(raw);
-	} catch (err) {
-		throw new Error(`corrupt JSON at ${path}: ${err instanceof Error ? err.message : String(err)}`);
-	}
-}
-/**
-* Write `data` to a temp file in the same directory, then atomically rename it
-* into place, so a concurrent reader only ever observes the old file or the
-* fully-written new one — never the empty/partial window a plain
-* truncate-then-write leaves open (e.g. a `putActualCause` writing a run's
-* triage file while an API request reads it). The temp file lives in the same
-* directory as its target to keep the rename on one filesystem, where it is
-* atomic.
-*/
-async function atomicWrite(path, data) {
-	await mkdir(dirname(path), { recursive: true });
-	const tmp = `${path}.${randomUUID()}.tmp`;
-	await writeFile(tmp, data);
-	await rename(tmp, path);
-}
-/** Write `value` as pretty JSON, creating parent directories as needed. */
-async function writeJson(path, value) {
-	await atomicWrite(path, JSON.stringify(value, null, 2) + "\n");
-}
-/**
-* Per-path serialization for read-modify-write JSON updates. Two concurrent
-* `updateJson` calls on the same path (e.g. two `putActualCause` calls racing
-* on the same run's triage file) would otherwise both read the same starting
-* state and the second writer's change would silently clobber the first's —
-* this queues the second call's read until the first's write has landed, so
-* updates apply in the order they were issued rather than racing. Scoped by
-* path (a `Map` of chained promises), not globally, so unrelated records still
-* update concurrently.
-*/
-const updateChains = /* @__PURE__ */ new Map();
-/**
-* Queue `work` behind whatever is already in flight for `path`. A delete takes
-* the same chain as the updates it removes: `writeJson` recreates the parent
-* directory, so an unordered delete would be silently undone by an update that
-* was already queued.
-*/
-async function serialize(path, work) {
-	const next = (updateChains.get(path) ?? Promise.resolve()).catch(() => {}).then(work);
-	updateChains.set(path, next);
-	try {
-		return await next;
-	} finally {
-		if (updateChains.get(path) === next) updateChains.delete(path);
-	}
-}
-async function updateJson(path, mutate) {
-	return await serialize(path, async () => {
-		const updated = mutate(await readJson(path));
-		await writeJson(path, updated);
-		return updated;
-	});
-}
-/** Read a raw file, returning `null` when it doesn't exist. */
-async function readBytesOrNull(path) {
-	try {
-		const buf = await readFile(path);
-		return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
-	} catch (err) {
-		if (isNotFound(err)) return null;
-		throw err;
-	}
-}
-async function writeBytes(path, bytes) {
-	await atomicWrite(path, bytes);
-}
-/** List entry names (files or dirs) directly under `dir`, or `[]` when it doesn't exist. */
-async function listDirOrEmpty(dir) {
-	try {
-		return await readdir(dir);
-	} catch (err) {
-		if (isNotFound(err)) return [];
-		throw err;
-	}
-}
-/**
-* Subdirectory names directly under `dir`, or `[]` when it doesn't exist.
-* Skips files and dot-entries so stray filesystem litter (e.g. a Finder
-* `.DS_Store`) never surfaces as a record id or project name.
-*/
-async function listSubdirsOrEmpty(dir) {
-	try {
-		return (await readdir(dir, { withFileTypes: true })).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name);
-	} catch (err) {
-		if (isNotFound(err)) return [];
-		throw err;
-	}
-}
-/** Every file path under `dir`, relative to `dir`, posix-separated. */
-async function listFilesRecursive(dir) {
-	const out = [];
-	async function walk(current) {
-		let entries;
-		try {
-			entries = await readdir(current, { withFileTypes: true });
-		} catch (err) {
-			if (isNotFound(err)) return;
-			throw err;
-		}
-		for (const entry of entries) {
-			const abs = join(current, entry.name);
-			if (entry.isDirectory()) await walk(abs);
-			else if (entry.isFile()) out.push(relative(dir, abs).split(sep).join("/"));
-		}
-	}
-	await walk(dir);
-	return out;
-}
-async function removePath(path) {
-	await rm(path, {
-		recursive: true,
-		force: true
-	});
-}
-function isNotFound(err) {
-	return err instanceof Error && "code" in err && err.code === "ENOENT";
-}
-//#endregion
 //#region src/hub/core/storage/file/paths.ts
 /**
 * On-disk layout for the local-directory `HubStorage` backend, all rooted
@@ -30598,6 +30895,12 @@ function runMetaPath(root, id) {
 function artifactsRunDir(root, runId) {
 	return join(root, "artifacts", runId);
 }
+function sourceMapProjectDir(root, project) {
+	return join(root, "sourcemaps", project);
+}
+function sourceMapCommitDir(root, project, commit) {
+	return join(sourceMapProjectDir(root, project), commit);
+}
 function jobsDir(root) {
 	return join(root, "jobs");
 }
@@ -30643,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);
 }
@@ -30966,6 +31272,56 @@ function parseLine(rawLine) {
 	};
 }
 //#endregion
+//#region src/hub/core/storage/file/sourcemap-store.ts
+/**
+* Defense-in-depth: the HTTP layer validates the asset path before it gets
+* here, but this store joins it onto a directory, so it re-checks rather than
+* trusting the caller.
+*/
+function assertSafeAssetPath(assetPath) {
+	const segments = assetPath.split("/");
+	if (assetPath.length === 0 || assetPath.startsWith("/") || assetPath.includes("\\") || segments.includes("..") || segments.includes(".")) throw new Error("invalid source map path: must be relative, without '.' or '..' segments");
+}
+/** Marks when a commit last received a push; see `listCommits`. */
+const PUSHED_AT = "pushed-at.json";
+function createFileSourceMapStore(root) {
+	return {
+		async put(project, commit, assetPath, bytes) {
+			assertSafeName(project, "project");
+			assertSafeName(commit, "commit");
+			assertSafeAssetPath(assetPath);
+			const dir = sourceMapCommitDir(root, project, commit);
+			await writeBytes(join(dir, assetPath), bytes);
+			await writeJson(join(dir, PUSHED_AT), { at: Date.now() });
+		},
+		async read(project, commit, assetPath) {
+			assertSafeName(project, "project");
+			assertSafeName(commit, "commit");
+			assertSafeAssetPath(assetPath);
+			return readBytesOrNull(join(sourceMapCommitDir(root, project, commit), assetPath));
+		},
+		async list(project, commit) {
+			assertSafeName(project, "project");
+			assertSafeName(commit, "commit");
+			return (await listFilesRecursive(sourceMapCommitDir(root, project, commit))).filter((file) => file !== PUSHED_AT);
+		},
+		async listCommits(project) {
+			assertSafeName(project, "project");
+			const dir = sourceMapProjectDir(root, project);
+			const commits = await listSubdirsOrEmpty(dir);
+			return (await Promise.all(commits.map(async (commit) => ({
+				commit,
+				at: (await readJson(join(dir, commit, PUSHED_AT)).catch(() => null))?.at ?? 0
+			})))).sort((a, b) => b.at - a.at).map((entry) => entry.commit);
+		},
+		async delete(project, commit) {
+			assertSafeName(project, "project");
+			assertSafeName(commit, "commit");
+			await removePath(sourceMapCommitDir(root, project, commit));
+		}
+	};
+}
+//#endregion
 //#region src/hub/core/storage/file/deploy-store.ts
 function createFileDeployStore(root) {
 	const readLog = async (project, profile) => await readJson(deployLogPath(root, project, profile)) ?? emptyDeployLog();
@@ -31094,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
@@ -31400,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),
@@ -31409,7 +31807,8 @@ function createFileHubStorage(dataDir) {
 		spend: createFileSpendStore(dataDir),
 		attestations: createFileAttestationStore(dataDir),
 		auditDismissals: createFileAuditDismissalStore(dataDir),
-		coverageEvents: createFileCoverageEventStore(dataDir)
+		coverageEvents: createFileCoverageEventStore(dataDir),
+		sourceMaps: createFileSourceMapStore(dataDir)
 	};
 }
 //#endregion