@substrat-run/control-plane-api 0.139.0 → 0.141.0

package/dist/audited-change.d.ts

@@ -0,0 +1,139 @@
+/**
+ * A change the control plane makes in ANOTHER store, audited around the call (#2064).
+ *
+ * The owner hand-over (#1665) and dashboard member management (#1150) both change state in the
+ * vertical's own deployment, so the admin log cannot record them in the same transaction. Each is
+ * written in two rows paired by `operationId`: an `intent` before the vertical is reached, then
+ * the outcome (`applied`, `refused` or `failed`). The two stores are separate, so no order makes
+ * the pair atomic. This one fails toward "an intent with no outcome", never toward "a change with
+ * no row":
+ *
+ * - the `intent` write failing stops the call, so nothing moves unaudited;
+ * - the `applied` write failing is reported to the caller as exactly that: the change happened
+ *   and its row is missing (`unrecorded`), so nobody retries a change believing it failed;
+ * - the `refused`/`failed` write failing is NOT the caller's answer. The vertical's own status
+ *   still is, because a correctly refused `403`/`409` turned into a `5xx` reads as retryable,
+ *   and each retry would add an intent row. It is logged at error level with the operation id.
+ *
+ * Neither failure is silent any more, and neither is left for a reader to explain: an intent
+ * with no outcome is closed by `settleUnrecordedOutcomes` below, which the scheduled pass runs.
+ * Every control-plane flow of this shape goes through `auditedChange`, so the next one cannot
+ * leave the outcome write in a bare `.catch(() => undefined)` again. Its outcome write is the
+ * kernel's `recordAuditOutcome`, which the schedule and peer kill switches use inside the adapters
+ * too (#2089), and the settle below closes their intents by the same rule.
+ */
+import { type AdminLogEntry, type OpsFailureEntry, type PlatformActorId } from '@substrat-run/contracts';
+import { UNRECORDED_OUTCOME_LOG, type HostAdmin } from '@substrat-run/kernel';
+/** One row of an audited change, before the flow adds its own fields. */
+export type AuditedRow<T> = {
+    phase: 'intent';
+} | {
+    phase: 'applied';
+    result: T;
+} | {
+    phase: 'refused' | 'failed';
+    error: string;
+};
+export interface AuditedChangeSpec<T> {
+    /** Names the flow in the error log line, e.g. `owner-transfer`. */
+    flow: string;
+    operationId: string;
+    /** Writes one row. Throws when the row could not be written. */
+    record: (row: AuditedRow<T>) => Promise<void>;
+    /** The call into the other store. */
+    run: () => Promise<T>;
+    /** Whether a throw from `run` is a refusal (nothing was written there) rather than a failure. */
+    refused: (error: unknown) => boolean;
+    /** Where an unwritten outcome is reported. Defaults to `console.error`. */
+    logError?: (message: string, fields: Record<string, unknown>) => void;
+}
+export type AuditedChange<T> = 
+/** Applied, and recorded. */
+{
+    operationId: string;
+    result: T;
+}
+/** Applied, but the `applied` row could not be written: `unrecorded` is why. */
+ | {
+    operationId: string;
+    result: T;
+    unrecorded: string;
+}
+/** `run` threw; its error, untouched, for the caller to answer with. */
+ | {
+    operationId: string;
+    error: unknown;
+};
+/** The structured line both unwritten outcomes leave: the kernel's, re-exported where it was first. */
+export { UNRECORDED_OUTCOME_LOG };
+/**
+ * Run one audited change: the `intent` row (its failure propagates, and `run` is not called),
+ * the call, then the outcome row. See the module header for what each failure answers.
+ */
+export declare function auditedChange<T>(spec: AuditedChangeSpec<T>): Promise<AuditedChange<T>>;
+export type SettleAdmin = Pick<HostAdmin, 'auditLog' | 'settleUnrecordedOutcome'>;
+export interface SettleOptions {
+    admin: SettleAdmin;
+    actor: PlatformActorId;
+    now?: Date;
+    /**
+     * How old an intent must be before its missing outcome is called unknown. It must exceed
+     * `AUDITED_CALL_DEADLINE_MS`, the longest the vertical call between the two rows may run, so a
+     * live request is never settled; `settleUnrecordedOutcomes` refuses a window that does not.
+     */
+    graceMs?: number;
+    /**
+     * How far back each pass looks. The pass runs every quarter hour, so a week is margin for a
+     * sweep that was down, not the expected lag; it bounds what each pass reads from a log that is
+     * never pruned.
+     */
+    lookbackMs?: number;
+    logError?: LogError;
+}
+/** The structured line a stored id the contract would refuse leaves, once per read (#2064). */
+export declare const MALFORMED_OPERATION_ID_LOG = "audit-operation-id-malformed";
+type LogError = NonNullable<AuditedChangeSpec<unknown>['logError']>;
+export interface SettleResult {
+    /** Intents this pass closed with an `unknown` row. */
+    settled: {
+        action: string;
+        operationId: string;
+        tenantId: string | null;
+        scopeId: string | null;
+    }[];
+    /** Per-intent write failures: the intent stays open, and the next pass tries again. */
+    errors: {
+        operationId: string;
+        error: string;
+    }[];
+    /** Rows whose stored operation id the contract refuses: passed over, by row id. */
+    malformed: string[];
+}
+/** An hour: sixty times the deadline on the call it waits out. */
+export declare const SETTLE_GRACE_MS: number;
+/**
+ * Close every audited change whose intent has no outcome row (#2064). Each intent older than
+ * the grace window and still without an outcome is handed to `HostAdmin.settleUnrecordedOutcome`,
+ * which writes the `unknown` row and its ops-failure row in ONE transaction, and only if no
+ * outcome exists by then. The scan here only nominates. The host's check is the one that holds,
+ * so two concurrent passes, or an outcome landing between the scan and the settle, still leave
+ * one outcome row. A real outcome written later supersedes `unknown` (kernel `audit-outcome.ts`).
+ */
+export declare function settleUnrecordedOutcomes(opts: SettleOptions): Promise<SettleResult>;
+/** The structured line an operation with two real outcomes leaves: the audit's invariant broke. */
+export declare const OUTCOME_CONFLICT_LOG = "audit-outcome-conflict";
+/**
+ * The admin-log read surface's half of the priority rule (#2064). Each row of an audited change
+ * is annotated with the outcome its operation stands at: a real outcome beats `unknown` whatever
+ * the row order, and two real outcomes read `conflicting`. An `unknown` a real outcome beat is
+ * marked `superseded`. The rows are returned as written, so the raw history stays readable.
+ */
+export declare function withAuditedOutcomes(admin: Pick<HostAdmin, 'auditedOperations'>, actor: PlatformActorId, entries: AdminLogEntry[], logError?: AuditedChangeSpec<unknown>['logError']): Promise<AdminLogEntry[]>;
+/**
+ * The digest's half (#2064): of the ops-failure rows the settle wrote for an `unknown` outcome,
+ * the ones whose operation has since recorded ONE real outcome, whatever the order the two rows
+ * landed in. The settle's row names the operation in `reference`. The digest drops these. A
+ * `conflicting` operation is kept and logged: it is the one a person must look at.
+ */
+export declare function supersededUnknowns(admin: Pick<HostAdmin, 'auditedOperations'>, actor: PlatformActorId, failures: readonly OpsFailureEntry[], logError?: AuditedChangeSpec<unknown>['logError']): Promise<Set<string>>;
+//# sourceMappingURL=audited-change.d.ts.map

package/dist/audited-change.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audited-change.d.ts","sourceRoot":"","sources":["../src/audited-change.ts"],"names":[],"mappings":"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"}

package/dist/audited-change.js

@@ -0,0 +1,214 @@
+/**
+ * A change the control plane makes in ANOTHER store, audited around the call (#2064).
+ *
+ * The owner hand-over (#1665) and dashboard member management (#1150) both change state in the
+ * vertical's own deployment, so the admin log cannot record them in the same transaction. Each is
+ * written in two rows paired by `operationId`: an `intent` before the vertical is reached, then
+ * the outcome (`applied`, `refused` or `failed`). The two stores are separate, so no order makes
+ * the pair atomic. This one fails toward "an intent with no outcome", never toward "a change with
+ * no row":
+ *
+ * - the `intent` write failing stops the call, so nothing moves unaudited;
+ * - the `applied` write failing is reported to the caller as exactly that: the change happened
+ *   and its row is missing (`unrecorded`), so nobody retries a change believing it failed;
+ * - the `refused`/`failed` write failing is NOT the caller's answer. The vertical's own status
+ *   still is, because a correctly refused `403`/`409` turned into a `5xx` reads as retryable,
+ *   and each retry would add an intent row. It is logged at error level with the operation id.
+ *
+ * Neither failure is silent any more, and neither is left for a reader to explain: an intent
+ * with no outcome is closed by `settleUnrecordedOutcomes` below, which the scheduled pass runs.
+ * Every control-plane flow of this shape goes through `auditedChange`, so the next one cannot
+ * leave the outcome write in a bare `.catch(() => undefined)` again. Its outcome write is the
+ * kernel's `recordAuditOutcome`, which the schedule and peer kill switches use inside the adapters
+ * too (#2089), and the settle below closes their intents by the same rule.
+ */
+import { AUDIT_ERROR_MAX, auditOperationId } from '@substrat-run/contracts';
+import { AUDITED_CHANGE_ACTIONS, UNRECORDED_OUTCOME_LOG, recordAuditOutcome, operationKeyOf, effectiveOutcomes, isSupersededOutcome, } from '@substrat-run/kernel';
+import { AUDITED_CALL_DEADLINE_MS } from './vertical-client.js';
+const messageOf = (e) => (e instanceof Error ? e.message : String(e));
+const consoleError = (message, fields) => console.error(message, fields);
+/** The structured line both unwritten outcomes leave: the kernel's, re-exported where it was first. */
+export { UNRECORDED_OUTCOME_LOG };
+/**
+ * Run one audited change: the `intent` row (its failure propagates, and `run` is not called),
+ * the call, then the outcome row. See the module header for what each failure answers.
+ */
+export async function auditedChange(spec) {
+    const { flow, operationId, record } = spec;
+    const logError = spec.logError ?? consoleError;
+    await record({ phase: 'intent' });
+    let result;
+    try {
+        result = await spec.run();
+    }
+    catch (error) {
+        const phase = spec.refused(error) ? 'refused' : 'failed';
+        await recordAuditOutcome(() => record({ phase, error: messageOf(error).slice(0, AUDIT_ERROR_MAX) }), { flow, operationId, phase }, logError);
+        return { operationId, error };
+    }
+    const unrecorded = await recordAuditOutcome(() => record({ phase: 'applied', result }), { flow, operationId, phase: 'applied' }, logError);
+    return unrecorded === null ? { operationId, result } : { operationId, result, unrecorded };
+}
+/** The structured line a stored id the contract would refuse leaves, once per read (#2064). */
+export const MALFORMED_OPERATION_ID_LOG = 'audit-operation-id-malformed';
+/**
+ * The audited operation a STORED id names, or `malformed`, or null when it names none (another
+ * action, or no id). ONE predicate for every reader that turns a stored id into a resolved or
+ * enriched one: the admin-log annotation, the digest and the sweep's scan. It is the contract's
+ * own `auditOperationId`. A row written before the contract held ids to well-formed text may
+ * carry one it would now refuse. That row names no operation: it is returned raw, never
+ * enriched, settled or thrown on, and the reader counts it and logs it once.
+ */
+function storedOperationOf(action, operationId, where) {
+    if (!AUDITED_CHANGE_ACTIONS.includes(action) || operationId === undefined || operationId === null)
+        return null;
+    if (!auditOperationId.safeParse(operationId).success)
+        return 'malformed';
+    return { action, operationId: operationId, tenantId: where.tenantId, scopeId: where.scopeId };
+}
+/** One log line for every stored row a reader passed over, by row id. */
+function reportMalformed(logError, reader, rows) {
+    if (rows.length > 0)
+        logError(MALFORMED_OPERATION_ID_LOG, { reader, count: rows.length, rows });
+}
+/** An hour: sixty times the deadline on the call it waits out. */
+export const SETTLE_GRACE_MS = 60 * 60 * 1000;
+const SETTLE_LOOKBACK_MS = 7 * 24 * 60 * 60 * 1000;
+const PAGE = 500;
+if (SETTLE_GRACE_MS <= AUDITED_CALL_DEADLINE_MS) {
+    throw new Error('SETTLE_GRACE_MS must exceed AUDITED_CALL_DEADLINE_MS, or a live call could be settled');
+}
+/**
+ * Close every audited change whose intent has no outcome row (#2064). Each intent older than
+ * the grace window and still without an outcome is handed to `HostAdmin.settleUnrecordedOutcome`,
+ * which writes the `unknown` row and its ops-failure row in ONE transaction, and only if no
+ * outcome exists by then. The scan here only nominates. The host's check is the one that holds,
+ * so two concurrent passes, or an outcome landing between the scan and the settle, still leave
+ * one outcome row. A real outcome written later supersedes `unknown` (kernel `audit-outcome.ts`).
+ */
+export async function settleUnrecordedOutcomes(opts) {
+    const { admin, actor } = opts;
+    const now = (opts.now ?? new Date()).getTime();
+    const graceMs = opts.graceMs ?? SETTLE_GRACE_MS;
+    if (graceMs <= AUDITED_CALL_DEADLINE_MS) {
+        throw new Error(`a settle grace of ${graceMs} ms does not exceed the ${AUDITED_CALL_DEADLINE_MS} ms call deadline`);
+    }
+    const cutoff = new Date(now - graceMs).toISOString();
+    const since = new Date(now - (opts.lookbackMs ?? SETTLE_LOOKBACK_MS)).toISOString();
+    const intents = new Map();
+    const closed = new Set();
+    const malformed = [];
+    for (let cursor;;) {
+        const page = await admin.auditLog(actor, { action: [...AUDITED_CHANGE_ACTIONS], since, limit: PAGE, cursor });
+        for (const row of page) {
+            const after = row.after;
+            const operation = storedOperationOf(row.action, after?.operationId, row);
+            if (operation === 'malformed')
+                malformed.push(row.id);
+            if (operation === null || operation === 'malformed')
+                continue;
+            // The operation's whole identity, as every reader keys it.
+            const key = operationKeyOf(operation);
+            if (after?.phase === 'intent') {
+                if (row.at < cutoff)
+                    intents.set(key, row);
+            }
+            else {
+                closed.add(key);
+            }
+        }
+        if (page.length < PAGE)
+            break;
+        cursor = page[page.length - 1].id;
+    }
+    reportMalformed(opts.logError ?? consoleError, 'settle', malformed);
+    const result = { settled: [], errors: [], malformed };
+    const minutes = Math.round(graceMs / 60_000);
+    for (const [key, intent] of intents) {
+        if (closed.has(key))
+            continue;
+        const operationId = intent.after.operationId;
+        const error = `no outcome was recorded within ${minutes} minutes of the intent (${intent.at}); whether the change happened is not known to this log`;
+        try {
+            if (await admin.settleUnrecordedOutcome(actor, { intentId: intent.id, error })) {
+                result.settled.push({ action: intent.action, operationId, tenantId: intent.tenantId, scopeId: intent.scopeId });
+            }
+        }
+        catch (e) {
+            result.errors.push({ operationId, error: messageOf(e) });
+        }
+    }
+    return result;
+}
+/** The structured line an operation with two real outcomes leaves: the audit's invariant broke. */
+export const OUTCOME_CONFLICT_LOG = 'audit-outcome-conflict';
+/**
+ * Resolve `refs` to their effective outcomes (#2064): ONE batched read of exactly these
+ * operations' rows through the operation-id index, then the kernel's priority rule. An operation
+ * found `conflicting` is logged here, once per read, so a reader never hides it.
+ */
+async function resolveOperations(admin, actor, refs, logError = consoleError) {
+    if (refs.length === 0)
+        return new Map();
+    const effective = effectiveOutcomes(await admin.auditedOperations(actor, refs));
+    for (const [key, outcome] of effective) {
+        if (outcome.outcome === 'conflicting')
+            logError(OUTCOME_CONFLICT_LOG, { operation: JSON.parse(key), outcomes: outcome.real });
+    }
+    return effective;
+}
+/**
+ * The admin-log read surface's half of the priority rule (#2064). Each row of an audited change
+ * is annotated with the outcome its operation stands at: a real outcome beats `unknown` whatever
+ * the row order, and two real outcomes read `conflicting`. An `unknown` a real outcome beat is
+ * marked `superseded`. The rows are returned as written, so the raw history stays readable.
+ */
+export async function withAuditedOutcomes(admin, actor, entries, logError) {
+    const operations = entries.map((row) => storedOperationOf(row.action, row.after?.operationId, row));
+    reportMalformed(logError ?? consoleError, 'admin-log', entries.filter((_, i) => operations[i] === 'malformed').map((row) => row.id));
+    const refs = operations.filter((o) => o !== null && o !== 'malformed');
+    if (refs.length === 0)
+        return entries;
+    const effective = await resolveOperations(admin, actor, refs, logError);
+    return entries.map((row, i) => {
+        const operation = operations[i];
+        if (operation === null || operation === 'malformed')
+            return row;
+        const outcome = effective.get(operationKeyOf(operation));
+        const phase = row.after.phase ?? null;
+        return {
+            ...row,
+            audited: { operationId: operation.operationId, outcome: outcome?.outcome ?? 'pending', superseded: isSupersededOutcome(phase, outcome) },
+        };
+    });
+}
+/**
+ * The digest's half (#2064): of the ops-failure rows the settle wrote for an `unknown` outcome,
+ * the ones whose operation has since recorded ONE real outcome, whatever the order the two rows
+ * landed in. The settle's row names the operation in `reference`. The digest drops these. A
+ * `conflicting` operation is kept and logged: it is the one a person must look at.
+ */
+export async function supersededUnknowns(admin, actor, failures, logError) {
+    const unknowns = new Map();
+    const malformed = [];
+    for (const f of failures) {
+        if (f.stage !== 'outcome-unknown' || !f.operation.startsWith('audit.'))
+            continue;
+        const operation = storedOperationOf(f.operation.slice('audit.'.length), f.reference, f);
+        if (operation === 'malformed')
+            malformed.push(f.id);
+        else if (operation !== null)
+            unknowns.set(f.id, operation);
+    }
+    // A failure row passed over is kept in the digest: it is reported, never dropped as resolved.
+    reportMalformed(logError ?? consoleError, 'digest', malformed);
+    const effective = await resolveOperations(admin, actor, [...unknowns.values()], logError);
+    const superseded = new Set();
+    for (const [id, ref] of unknowns) {
+        const outcome = effective.get(operationKeyOf(ref));
+        if (outcome && outcome.real.length === 1)
+            superseded.add(id);
+    }
+    return superseded;
+}
+//# sourceMappingURL=audited-change.js.map

package/dist/audited-change.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audited-change.js","sourceRoot":"","sources":["../src/audited-change.ts"],"names":[],"mappings":"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"}

package/dist/cf-observability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cf-observability.d.ts","sourceRoot":"","sources":["../src/cf-observability.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqE,KAAK,SAAS,EAAuB,MAAM,uBAAuB,CAAC;AAK/I,OAAO,KAAK,EACV,mBAAmB,EASpB,MAAM,oBAAoB,CAAC;AAG5B;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,kCAAkC,CAAC;AAsOnE;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1B,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/D,OAAO,CAOT;AAyPD;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;;;;OASG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAuED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,sBAAsB,GAAG,mBAAmB,CAywC7F"}
+{"version":3,"file":"cf-observability.d.ts","sourceRoot":"","sources":["../src/cf-observability.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqE,KAAK,SAAS,EAAuB,MAAM,uBAAuB,CAAC;AAM/I,OAAO,KAAK,EACV,mBAAmB,EASpB,MAAM,oBAAoB,CAAC;AAG5B;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,kCAAkC,CAAC;AAsOnE;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1B,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/D,OAAO,CAOT;AAyPD;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;;;;OASG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAuED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,sBAAsB,GAAG,mBAAmB,CAkzC7F"}

package/dist/cf-observability.js

@@ -4,7 +4,8 @@ import { cachedSource, cutOverSource } from './aggregate-source.js';
 import { stableDeploymentRefFor } from './deploy.js';
 import { aggregateReads } from './aggregate-reads.js';
 import { serviceFamilyPattern } from './service-family.js';
-import { FIELD_COVERAGE_ID_FIELD } from '@substrat-run/contracts';
+import { FIELD_COVERAGE_ID_FIELD, ROUTER_SCRIPT_NAMES } from '@substrat-run/contracts';
+import { readFieldCoverage } from './field-coverage-read.js';
 import { TENANT_METRICS_LIMIT, REQUEST_FACET_KEYS, INVOCATION_KINDS, invocationKindOf } from './observability.js';
 /**
  * An HTTP method as RFC 9110 §9.1 defines it: a `token` (§5.6.2), one or more `tchar`.
@@ -931,6 +932,27 @@ export function createCfObservabilityReader(opts) {
         async tenantLogs(input) {
             return queryTenantLogs(input);
         },
+        async fieldCoverage(input) {
+            const window = resolveObservabilityWindow(input);
+            const timeframe = { from: Date.parse(window.since), to: Date.parse(window.until) };
+            const reports = await queryAllFieldEvents([
+                { key: 'tenantId', operation: 'eq', type: 'string', value: input.tenantId },
+                { key: 'substrat', operation: 'eq', type: 'string', value: 'invocation' },
+                { key: 'vertical', operation: 'eq', type: 'string', value: input.vertical },
+                { key: FIELD_COVERAGE_ID_FIELD, operation: 'regex', type: 'string', value: '^[0-9A-HJKMNP-TV-Z]{26}$' },
+                ...serviceFilter(input.services),
+                ...(input.versionId ? [{ key: 'versionId', operation: 'eq', type: 'string', value: input.versionId }] : []),
+            ], timeframe);
+            const router = (await Promise.all(ROUTER_SCRIPT_NAMES.map((service) => queryAllFieldEvents([
+                { key: 'tenantId', operation: 'eq', type: 'string', value: input.tenantId },
+                { key: 'router', operation: 'eq', type: 'string', value: 'request' },
+                { key: 'vertical', operation: 'eq', type: 'string', value: input.vertical },
+                { key: 'scopeId', operation: 'eq', type: 'string', value: input.scopeId },
+                { key: FIELD_COVERAGE_ID_FIELD, operation: 'regex', type: 'string', value: '^[0-9A-HJKMNP-TV-Z]{26}$' },
+                { key: '$metadata.service', operation: 'eq', type: 'string', value: service },
+            ], timeframe)))).flat();
+            return readFieldCoverage(reports, router, input, window);
+        },
         // #1746/#1877: the request histogram, facet counts and log patterns — computed once,
         // from cubes, by `aggregateReads` over the (cached) telemetry source.
         ...aggregateReads(source),
@@ -1534,6 +1556,21 @@ export function createCfObservabilityReader(opts) {
         const outer = json.result?.events;
         return (Array.isArray(outer) ? outer : (outer?.events ?? []));
     }
+    /** Read a complete sampled span, or refuse it; a truncated page must never mean zero fields. */
+    async function queryAllFieldEvents(filters, timeframe, depth = 0) {
+        const page = await queryRaw(filters, timeframe, 2000);
+        if (page.length < 2000)
+            return page;
+        if (depth >= 12 || timeframe.to - timeframe.from <= 1000) {
+            throw new ControlPlaneError(503, 'field coverage window is too busy — choose a shorter window');
+        }
+        const middle = Math.floor((timeframe.from + timeframe.to) / 2);
+        const [left, right] = await Promise.all([
+            queryAllFieldEvents(filters, { from: timeframe.from, to: middle }, depth + 1),
+            queryAllFieldEvents(filters, { from: middle, to: timeframe.to }, depth + 1),
+        ]);
+        return [...left, ...right];
+    }
     /** One telemetry query — narrowed to a single service, or to none (the fleet view). */
     async function queryEvents(service, level, search, hours, limit) {
         const to = Date.now();