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

package/dist/connection-relay.js

@@ -1,5 +1,5 @@
 import { isPrimaryScope, ulid } from '@substrat-run/kernel';
-import { connectionId, connectionRelayRequest, } from '@substrat-run/contracts';
+import { instant, connectionId, connectionRelayRequest, } from '@substrat-run/contracts';
 /**
  * The connection relay (connections.md §3.5.2) — the credential half of #574's routed
  * connector dispatch. A hosted CP-less vertical's tenant admin holds a provider credential
@@ -76,21 +76,39 @@ export async function relayConnectionUpsert(host, actor, body, options = {}) {
         throw new ConnectionRelayError(PREVIEW_CONNECTIONS_REFUSAL, 403);
     }
     const vertical = rec.vertical;
-    // Ask the provider before touching the store (#605). Deliberately here, ahead of every
-    // write below: a refused rotation must leave the live credential exactly as it was.
-    const probe = await options.probeCandidate?.(input.provider, input.secret);
-    if (probe && !probe.ok && probe.refused) {
-        throw new ConnectionRelayError(probe.error ?? `${input.provider} refused these credentials`, 422, probe);
-    }
     // `listConnections` already excludes revoked rows; expired/errored rows are still the
     // live row for this key — rotation is what revives them. The account leg matches
     // exactly (absent matches absent): a multi-account provider's second account is a new
-    // connection, not a rotation of the first.
+    // connection, not a rotation of the first. Read before the probe because a provider that
+    // finishes its own credential (#2100) needs the one this upsert would replace.
     const live = (await host.admin.listConnections(actor, {
         tenantId: input.tenantId,
         vertical,
         provider: input.provider,
     })).filter((c) => c.externalAccountRef === (input.externalAccountRef ?? null));
+    // #2100: the platform's half of the credential, made here — before the probe, so what is
+    // probed is exactly what is stored.
+    let secret = input.secret;
+    let expiresAt = input.expiresAt;
+    const prepare = options.prepareCandidate?.(input.provider);
+    if (prepare) {
+        const previous = live.length === 1
+            ? (await host.admin.openConnection(input.tenantId, vertical, input.provider, input.externalAccountRef))?.secret
+            : undefined;
+        const prepared = await prepare(input.secret, previous);
+        secret = prepared.secret;
+        // Parsed: a provider's date becomes the same branded instant a caller's would be. `null` is
+        // the provider clearing an expiry whose credential it dropped (a certificate → a client secret).
+        expiresAt =
+            input.expiresAt ??
+                (prepared.expiresAt === undefined || prepared.expiresAt === null ? prepared.expiresAt : instant.parse(prepared.expiresAt));
+    }
+    // Ask the provider before touching the store (#605). Deliberately here, ahead of every
+    // write below: a refused rotation must leave the live credential exactly as it was.
+    const probe = await options.probeCandidate?.(input.provider, secret);
+    if (probe && !probe.ok && probe.refused) {
+        throw new ConnectionRelayError(probe.error ?? `${input.provider} refused these credentials`, 422, probe);
+    }
     let id;
     let created;
     if (live.length === 0) {
@@ -103,9 +121,10 @@ export async function relayConnectionUpsert(host, actor, body, options = {}) {
             label: input.label ?? input.provider,
             externalAccountRef: input.externalAccountRef,
             scopes: input.scopes,
-            // Whatever the caller supplies; no shipped connector does (connections.md §3.6), so today this is undefined and the row reads "not reported".
-            expiresAt: input.expiresAt,
-            secret: input.secret,
+            // Whatever the caller supplies, else what the provider's own preparation knows (#2100: a
+            // generated certificate's end). Undefined reads "not reported" (connections.md §3.6).
+            expiresAt: expiresAt ?? undefined,
+            secret,
             // §3.5.1 — the authorizing tenant principal, proven by the vertical's own
             // `ctx.check` before the secret ever left the operation.
             createdBy: input.createdBy,
@@ -114,7 +133,7 @@ export async function relayConnectionUpsert(host, actor, body, options = {}) {
     }
     else if (live.length === 1) {
         id = live[0].id;
-        await host.admin.updateConnectionSecret(actor, id, input.secret, input.expiresAt, {
+        await host.admin.updateConnectionSecret(actor, id, secret, expiresAt, {
             rotatedBy: input.createdBy,
         });
         created = false;

package/dist/connection-relay.js.map

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

package/dist/email-intent.d.ts

@@ -0,0 +1,71 @@
+import { type SendEmailRequest, type TenantId, type ScopeId } from '@substrat-run/contracts';
+import type { PlatformRequestHandler } from './platform-drain.js';
+/**
+ * The drain's handler for `send-email` (#2102): one mail a vertical requested inside an
+ * operation, delivered after that operation committed.
+ *
+ * It routes as the synchronous relay does — no `from` sends as the platform, a `from` sends
+ * through the tenant connection whose `MailSender` covers that address — and it retries what a
+ * provider deferred: a `429`, a `5xx`, or a failure with no status at all. Any other 4xx is a
+ * refusal and is final. Each outcome that ends the request is written into the scope as an
+ * event, with the provider's message id when it gives one.
+ *
+ * **Retries wait.** The drain runs on every kick and every sweep, and a kick follows any
+ * operation that requested something — so a throttled mailbox would otherwise be retried as
+ * fast as the vertical writes. A failed attempt records the earliest time to try again in the
+ * intent's `result` (`Retry-After` when the provider gave one, else a doubling backoff), and a
+ * pass before then defers it without trying, which counts no attempt. Within one pass, a
+ * sender that answered `429` is not tried again: the rest of its mail defers to the next pass.
+ *
+ * **At least once.** A send the provider accepted whose settle is then lost is sent again on
+ * the next pass. Mail has no idempotency key a provider honours across all of them, so this is
+ * the honest guarantee; the alternative — settle before sending — loses mail instead.
+ */
+/** Attempts before a send that keeps failing transiently dead-letters. Well under the drain's ceiling. */
+export declare const MAX_EMAIL_SEND_ATTEMPTS = 10;
+/** The first retry's wait when the provider named none; doubled per attempt. */
+export declare const EMAIL_RETRY_BASE_MS = 30000;
+/** The longest wait between attempts the backoff alone will choose. */
+export declare const EMAIL_RETRY_MAX_MS: number;
+/** What a sender returns. `messageId` when the provider gives one. */
+export interface EmailSent {
+    messageId?: string;
+}
+export interface SendEmailDeps {
+    /** Does this vertical hold the `emailSender` grant? Read per pass, so a revoke takes effect. */
+    mayEmail(vertical: string): Promise<boolean>;
+    /**
+     * Send as the platform's own address. A refusal throws an error carrying `status` (and
+     * `retryAfter` seconds for a throttle), read structurally.
+     */
+    sendAsPlatform(mail: Omit<SendEmailRequest, 'from' | 'attachments' | 'about'>): Promise<EmailSent>;
+    /**
+     * Send as a tenant address, through the connection that covers it. Same error contract; a
+     * wrapper that rewords a provider's failure keeps the original as `cause`.
+     */
+    sendAsTenant(input: {
+        tenantId: TenantId;
+        scopeId: ScopeId;
+        vertical: string;
+        from: string;
+        fromName?: string;
+        to: string;
+        subject: string;
+        html: string;
+        text: string;
+        attachmentIds: string[];
+    }): Promise<EmailSent>;
+    now?(): Date;
+    maxAttempts?: number;
+}
+/** One handler per drain pass: the throttles it learns last only as long as the pass. */
+export declare function sendEmailHandler(deps: SendEmailDeps): PlatformRequestHandler;
+/**
+ * The status that decides a retry: the provider's, when a wrapper kept it as `cause`, else the
+ * wrapper's own. A tenant send that failed in the provider surfaces as a 502 around the
+ * provider's answer — the 502 says "the provider failed", the cause says whether it will again.
+ */
+export declare function sendFailureStatus(e: unknown): number | undefined;
+/** `retryAfter` (seconds) wherever along the cause chain a sender put it; 0 when nobody did. */
+export declare function retryAfterSecondsOf(e: unknown): number;
+//# sourceMappingURL=email-intent.d.ts.map

package/dist/email-intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-intent.d.ts","sourceRoot":"","sources":["../src/email-intent.ts"],"names":[],"mappings":"AAAA,OAAO,EAUL,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACb,KAAK,OAAO,EACb,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,sBAAsB,EAA0B,MAAM,qBAAqB,CAAC;AAG1F;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,0GAA0G;AAC1G,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAC1C,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,QAAc,CAAC;AAE9C,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,aAAa,GAAG,OAAO,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACnG;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE;QAClB,QAAQ,EAAE,QAAQ,CAAC;QACnB,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,EAAE,MAAM,EAAE,CAAC;KACzB,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACvB,GAAG,CAAC,IAAI,IAAI,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAOD,yFAAyF;AACzF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,sBAAsB,CAgG5E;AAoDD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEhE;AAED,gGAAgG;AAChG,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAQtD"}

package/dist/email-intent.js

@@ -0,0 +1,186 @@
+import { EMAIL_DEAD_LETTERED, EMAIL_REFUSED, EMAIL_SENT, PLATFORM_REQUEST_ENTITY_TYPE, sendEmailRequest, } from '@substrat-run/contracts';
+import { attributeFailure } from './failure-attribution.js';
+import { isTerminalDispatchFailure, providerErrorStatus } from './provider-error.js';
+/**
+ * The drain's handler for `send-email` (#2102): one mail a vertical requested inside an
+ * operation, delivered after that operation committed.
+ *
+ * It routes as the synchronous relay does — no `from` sends as the platform, a `from` sends
+ * through the tenant connection whose `MailSender` covers that address — and it retries what a
+ * provider deferred: a `429`, a `5xx`, or a failure with no status at all. Any other 4xx is a
+ * refusal and is final. Each outcome that ends the request is written into the scope as an
+ * event, with the provider's message id when it gives one.
+ *
+ * **Retries wait.** The drain runs on every kick and every sweep, and a kick follows any
+ * operation that requested something — so a throttled mailbox would otherwise be retried as
+ * fast as the vertical writes. A failed attempt records the earliest time to try again in the
+ * intent's `result` (`Retry-After` when the provider gave one, else a doubling backoff), and a
+ * pass before then defers it without trying, which counts no attempt. Within one pass, a
+ * sender that answered `429` is not tried again: the rest of its mail defers to the next pass.
+ *
+ * **At least once.** A send the provider accepted whose settle is then lost is sent again on
+ * the next pass. Mail has no idempotency key a provider honours across all of them, so this is
+ * the honest guarantee; the alternative — settle before sending — loses mail instead.
+ */
+/** Attempts before a send that keeps failing transiently dead-letters. Well under the drain's ceiling. */
+export const MAX_EMAIL_SEND_ATTEMPTS = 10;
+/** The first retry's wait when the provider named none; doubled per attempt. */
+export const EMAIL_RETRY_BASE_MS = 30_000;
+/** The longest wait between attempts the backoff alone will choose. */
+export const EMAIL_RETRY_MAX_MS = 30 * 60_000;
+/** One handler per drain pass: the throttles it learns last only as long as the pass. */
+export function sendEmailHandler(deps) {
+    const throttledUntil = new Map();
+    const now = () => deps.now?.() ?? new Date();
+    const maxAttempts = deps.maxAttempts ?? MAX_EMAIL_SEND_ATTEMPTS;
+    return async (ctx, request) => {
+        const attempts = request.attempts + 1;
+        const parsed = sendEmailRequest.safeParse(request.payload);
+        if (!parsed.success) {
+            // Module code goes through `requestEmail`, which parses first; this is a row written some
+            // other way. Final: the same bytes fail the same parse on every pass.
+            return over(request, EMAIL_REFUSED, null, 'platform', attempts, {
+                error: `not sent: the send-email payload is invalid (${parsed.error.issues[0]?.message ?? 'unknown'})`,
+                failure: { origin: 'platform', code: 'validation_failed', permission: null },
+            });
+        }
+        const mail = parsed.data;
+        const about = mail.about ?? null;
+        const sender = mail.from === undefined ? 'platform' : 'tenant';
+        const waitUntil = retryAtOf(request);
+        if (waitUntil !== null && waitUntil > now().getTime())
+            return { status: 'deferred' };
+        const key = mail.from === undefined ? 'platform' : `tenant:${mail.from.toLowerCase()}`;
+        if ((throttledUntil.get(key) ?? 0) > now().getTime())
+            return { status: 'deferred' };
+        if (!(await deps.mayEmail(ctx.vertical))) {
+            return over(request, EMAIL_REFUSED, about, sender, attempts, {
+                error: `not sent: vertical '${ctx.vertical}' does not hold the email-sender capability — staff ` +
+                    'grants it in the console (setVerticalEmailSender)',
+                failure: { origin: 'platform', code: 'permission_denied', permission: null },
+            });
+        }
+        let sent;
+        try {
+            sent =
+                mail.from === undefined
+                    ? await deps.sendAsPlatform({
+                        to: mail.to,
+                        subject: mail.subject,
+                        html: mail.html,
+                        text: mail.text,
+                        ...(mail.fromName ? { fromName: mail.fromName } : {}),
+                    })
+                    : await deps.sendAsTenant({
+                        tenantId: ctx.tenantId,
+                        scopeId: ctx.scopeId,
+                        vertical: ctx.vertical,
+                        from: mail.from,
+                        ...(mail.fromName ? { fromName: mail.fromName } : {}),
+                        to: mail.to,
+                        subject: mail.subject,
+                        html: mail.html,
+                        text: mail.text,
+                        attachmentIds: (mail.attachments ?? []).map((a) => a.attachmentId),
+                    });
+        }
+        catch (e) {
+            const status = sendFailureStatus(e);
+            const failure = attributeFailure(innermost(e));
+            const error = e instanceof Error ? e.message : String(e);
+            if (status !== undefined && isTerminalDispatchFailure({ status })) {
+                return over(request, EMAIL_REFUSED, about, sender, attempts, { error, failure, status });
+            }
+            if (attempts >= maxAttempts) {
+                return over(request, EMAIL_DEAD_LETTERED, about, sender, attempts, {
+                    error: `gave up after ${attempts} attempts — last error: ${error}`,
+                    failure,
+                    status,
+                });
+            }
+            const retryAfterMs = retryAfterSecondsOf(e) * 1000;
+            if (status === 429)
+                throttledUntil.set(key, now().getTime() + Math.max(retryAfterMs, 1));
+            const backoff = Math.min(EMAIL_RETRY_BASE_MS * 2 ** (attempts - 1), EMAIL_RETRY_MAX_MS);
+            const retry = { retryAt: new Date(now().getTime() + Math.max(retryAfterMs, backoff)).toISOString() };
+            return { status: 'pending', result: retry, error, failure };
+        }
+        return {
+            status: 'done',
+            result: { sent: true, sender, messageId: sent.messageId ?? null },
+            event: {
+                type: EMAIL_SENT,
+                entity: entityOf(request, about),
+                payload: {
+                    request: request.id,
+                    about,
+                    sender,
+                    messageId: sent.messageId ?? null,
+                    attempts,
+                    code: null,
+                    status: null,
+                },
+            },
+        };
+    };
+}
+/** A terminal outcome and the event that says so. */
+function over(request, type, about, sender, attempts, why) {
+    return {
+        status: 'failed',
+        error: why.error,
+        failure: why.failure,
+        event: {
+            type,
+            entity: entityOf(request, about),
+            payload: {
+                request: request.id,
+                about,
+                sender,
+                messageId: null,
+                attempts,
+                code: why.failure.code,
+                status: why.status ?? null,
+            },
+        },
+    };
+}
+const entityOf = (request, about) => about ?? { entityType: PLATFORM_REQUEST_ENTITY_TYPE, entityId: request.id };
+function retryAtOf(request) {
+    const at = request.result?.retryAt;
+    if (typeof at !== 'string')
+        return null;
+    const ms = Date.parse(at);
+    return Number.isFinite(ms) ? ms : null;
+}
+/** The error a wrapper kept as `cause`, followed to the bottom: the provider's own, if any. */
+function innermost(e) {
+    let current = e;
+    for (let depth = 0; depth < 5; depth++) {
+        const cause = current?.cause;
+        if (cause === undefined || cause === null)
+            return current;
+        current = cause;
+    }
+    return current;
+}
+/**
+ * The status that decides a retry: the provider's, when a wrapper kept it as `cause`, else the
+ * wrapper's own. A tenant send that failed in the provider surfaces as a 502 around the
+ * provider's answer — the 502 says "the provider failed", the cause says whether it will again.
+ */
+export function sendFailureStatus(e) {
+    return providerErrorStatus(innermost(e)) ?? providerErrorStatus(e);
+}
+/** `retryAfter` (seconds) wherever along the cause chain a sender put it; 0 when nobody did. */
+export function retryAfterSecondsOf(e) {
+    let current = e;
+    for (let depth = 0; depth < 6 && current !== null && typeof current === 'object'; depth++) {
+        const value = current.retryAfter;
+        if (typeof value === 'number' && Number.isFinite(value) && value > 0)
+            return value;
+        current = current.cause;
+    }
+    return 0;
+}
+//# sourceMappingURL=email-intent.js.map

package/dist/email-intent.js.map

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

package/dist/field-coverage-read.d.ts

@@ -0,0 +1,44 @@
+import { type FieldCoverageScope } from './field-coverage-tally.js';
+export interface FieldCoverageWindow {
+    since: string;
+    until: string;
+}
+/** One row is a count of sampled SERIALISATIONS, with its provenance beside the numbers. */
+export interface ObservedFieldRow {
+    field: string;
+    present: number;
+    empty: number;
+    absent: number;
+    /** Present or null; absent optional fields do not enter this denominator. */
+    eligible: number;
+    sampleRate: number | null;
+    window: FieldCoverageWindow;
+}
+export interface FieldCoverageRead {
+    tenantId: string;
+    vertical: string;
+    versionId: string | null;
+    source: 'vertical-asserted';
+    window: FieldCoverageWindow;
+    /** Empty means the router armed no request in this window. */
+    groups: Array<{
+        sampleRate: number | null;
+        armedRequests: number;
+        operations: Array<{
+            operation: string;
+            responses: number;
+            fields: ObservedFieldRow[];
+        }>;
+        /** Zero present and zero null in an armed sample: a candidate, never a proof of no use. */
+        notObservedReturned: Array<{
+            operation: string;
+            field: string;
+        }>;
+        refused: number;
+    }>;
+}
+/** The only public read shape over the raw report: declared names, counts, and no request detail. */
+export declare function readFieldCoverage(reports: Iterable<unknown>, routerLines: Iterable<unknown>, scope: FieldCoverageScope & {
+    versionId?: string;
+}, window: FieldCoverageWindow): FieldCoverageRead;
+//# sourceMappingURL=field-coverage-read.d.ts.map

package/dist/field-coverage-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-coverage-read.d.ts","sourceRoot":"","sources":["../src/field-coverage-read.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE9F,MAAM,WAAW,mBAAmB;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AAErE,4FAA4F;AAC5F,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,8DAA8D;IAC9D,MAAM,EAAE,KAAK,CAAC;QACZ,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,KAAK,CAAC;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,gBAAgB,EAAE,CAAA;SAAE,CAAC,CAAC;QACxF,2FAA2F;QAC3F,mBAAmB,EAAE,KAAK,CAAC;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjE,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ;AAED,qGAAqG;AACrG,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,EAC1B,WAAW,EAAE,QAAQ,CAAC,OAAO,CAAC,EAC9B,KAAK,EAAE,kBAAkB,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,EAClD,MAAM,EAAE,mBAAmB,GAC1B,iBAAiB,CA0CnB"}

package/dist/field-coverage-read.js

@@ -0,0 +1,45 @@
+import { tallyFieldCoverageByRate } from './field-coverage-tally.js';
+/** The only public read shape over the raw report: declared names, counts, and no request detail. */
+export function readFieldCoverage(reports, routerLines, scope, window) {
+    const groups = tallyFieldCoverageByRate(reports, routerLines, scope).map((group) => {
+        const byOperation = new Map(group.operations.map((op) => [op.operation, op]));
+        const declared = scope.declared ?? {};
+        const operations = Object.entries(declared).map(([operation, fields]) => {
+            const observed = byOperation.get(operation);
+            const byField = new Map(observed?.fields.map((f) => [f.field, f]) ?? []);
+            return {
+                operation,
+                responses: observed?.responses ?? 0,
+                fields: fields.map((field) => {
+                    const count = byField.get(field);
+                    const present = count?.present ?? 0;
+                    const empty = count?.empty ?? 0;
+                    return {
+                        field, present, empty, absent: count?.absent ?? 0,
+                        eligible: present + empty,
+                        sampleRate: group.sampleRate,
+                        window,
+                    };
+                }),
+            };
+        });
+        return {
+            sampleRate: group.sampleRate,
+            armedRequests: group.armedRequests,
+            operations,
+            notObservedReturned: operations.flatMap((op) => op.responses > 0
+                ? op.fields.filter((f) => f.eligible === 0).map((f) => ({ operation: op.operation, field: f.field }))
+                : []),
+            refused: group.refused,
+        };
+    });
+    return {
+        tenantId: scope.tenantId,
+        vertical: scope.vertical,
+        versionId: scope.versionId ?? null,
+        source: 'vertical-asserted',
+        window,
+        groups,
+    };
+}
+//# sourceMappingURL=field-coverage-read.js.map

package/dist/field-coverage-read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-coverage-read.js","sourceRoot":"","sources":["../src/field-coverage-read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAA2B,MAAM,2BAA2B,CAAC;AAiC9F,qGAAqG;AACrG,MAAM,UAAU,iBAAiB,CAC/B,OAA0B,EAC1B,WAA8B,EAC9B,KAAkD,EAClD,MAA2B;IAE3B,MAAM,MAAM,GAAG,wBAAwB,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACjF,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QAC9E,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;QACtC,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,EAAE;YACtE,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC5C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YACzE,OAAO;gBACL,SAAS;gBACT,SAAS,EAAE,QAAQ,EAAE,SAAS,IAAI,CAAC;gBACnC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAoB,EAAE;oBAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;oBACjC,MAAM,OAAO,GAAG,KAAK,EAAE,OAAO,IAAI,CAAC,CAAC;oBACpC,MAAM,KAAK,GAAG,KAAK,EAAE,KAAK,IAAI,CAAC,CAAC;oBAChC,OAAO;wBACL,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;wBACjD,QAAQ,EAAE,OAAO,GAAG,KAAK;wBACzB,UAAU,EAAE,KAAK,CAAC,UAAU;wBAC5B,MAAM;qBACP,CAAC;gBACJ,CAAC,CAAC;aACH,CAAC;QACJ,CAAC,CAAC,CAAC;QACH,OAAO;YACL,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,aAAa,EAAE,KAAK,CAAC,aAAa;YAClC,UAAU;YACV,mBAAmB,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAC7C,EAAE,CAAC,SAAS,GAAG,CAAC;gBACd,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;gBACrG,CAAC,CAAC,EAAE,CAAC;YACT,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO;QACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;QAClC,MAAM,EAAE,mBAAmB;QAC3B,MAAM;QACN,MAAM;KACP,CAAC;AACJ,CAAC"}

package/dist/field-coverage-tally.d.ts

@@ -27,12 +27,22 @@ export interface FieldCoverageTally {
      */
     refused: number;
 }
+/** Counts for router-armed requests at one effective rate. Null means an older router did not record it. */
+export interface RatedFieldCoverageTally extends FieldCoverageTally {
+    sampleRate: number | null;
+    armedRequests: number;
+}
 /** What the tally is for. Every field is the CALLER's resolution, never a line's. */
 export interface FieldCoverageScope {
     /** The tenant, forced from the principal the way every tenant read forces it. */
     tenantId: string;
     /** The app's vertical slug, as the router resolves it onto its line (`vertical`). */
     vertical: string;
+    /**
+     * The one installed app (`scopeId` on the router's line), when the read is for a single
+     * scope. Omitted, every scope of this vertical in the tenant counts.
+     */
+    scopeId?: string;
     /** The app's script family stems. Empty names no script, so nothing counts. */
     services: readonly string[];
     /**
@@ -55,4 +65,6 @@ export declare const FIELD_COVERAGE_OPERATIONS_MAX = 1000;
  * the tally is the thing a view trusts, and a query is one forgotten parameter from fleet-wide.
  */
 export declare function tallyFieldCoverage(events: Iterable<unknown>, routerEvents: Iterable<unknown>, scope: FieldCoverageScope): FieldCoverageTally;
+/** Partition by the router's own rate before tallying, so a changed rate is never averaged away. */
+export declare function tallyFieldCoverageByRate(events: Iterable<unknown>, routerEvents: Iterable<unknown>, scope: FieldCoverageScope): RatedFieldCoverageTally[];
 //# sourceMappingURL=field-coverage-tally.d.ts.map

package/dist/field-coverage-tally.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field-coverage-tally.d.ts","sourceRoot":"","sources":["../src/field-coverage-tally.ts"],"names":[],"mappings":"AAuDA,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,mFAAmF;AACnF,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,MAAM,EAAE,kBAAkB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,8FAA8F;IAC9F,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,UAAU,EAAE,sBAAsB,EAAE,CAAC;IACrC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;CACxD;AAgCD;;;GAGG;AACH,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAyBlD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,EACzB,YAAY,EAAE,QAAQ,CAAC,OAAO,CAAC,EAC/B,KAAK,EAAE,kBAAkB,GACxB,kBAAkB,CAqGpB"}
+{"version":3,"file":"field-coverage-tally.d.ts","sourceRoot":"","sources":["../src/field-coverage-tally.ts"],"names":[],"mappings":"AAuDA,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,mFAAmF;AACnF,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,MAAM,EAAE,kBAAkB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,8FAA8F;IAC9F,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,UAAU,EAAE,sBAAsB,EAAE,CAAC;IACrC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,4GAA4G;AAC5G,MAAM,WAAW,uBAAwB,SAAQ,kBAAkB;IACjE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;CACxD;AA0CD;;;GAGG;AACH,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAyBlD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,EACzB,YAAY,EAAE,QAAQ,CAAC,OAAO,CAAC,EAC/B,KAAK,EAAE,kBAAkB,GACxB,kBAAkB,CAqGpB;AAED,oGAAoG;AACpG,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,EACzB,YAAY,EAAE,QAAQ,CAAC,OAAO,CAAC,EAC/B,KAAK,EAAE,kBAAkB,GACxB,uBAAuB,EAAE,CA2B3B"}

package/dist/field-coverage-tally.js

@@ -66,23 +66,33 @@ function serviceOf(event) {
 function dispatchIdsFor(routerEvents, scope) {
     const ids = new Set();
     for (const event of routerEvents) {
-        if (event === null || typeof event !== 'object')
-            continue;
-        const service = serviceOf(event);
-        if (typeof service !== 'string' || !ROUTER_SCRIPT_NAMES.includes(service))
-            continue;
-        const source = event['source'];
-        if (source === null || typeof source !== 'object')
-            continue;
-        const line = source;
-        if (line['router'] !== 'request' || line['tenantId'] !== scope.tenantId || line['vertical'] !== scope.vertical)
-            continue;
-        const id = line[FIELD_COVERAGE_ID_FIELD];
-        if (typeof id === 'string' && DISPATCH_ID.test(id))
-            ids.add(id);
+        const vouched = routerDispatch(event, scope);
+        if (vouched)
+            ids.add(vouched.id);
     }
     return ids;
 }
+/**
+ * One router request line that vouches for a dispatch in `scope`, or `undefined`. Tenant, app
+ * and scope are read off the ROUTER's line only, never off the vertical's report.
+ */
+function routerDispatch(event, scope) {
+    if (event === null || typeof event !== 'object')
+        return undefined;
+    const service = serviceOf(event);
+    if (typeof service !== 'string' || !ROUTER_SCRIPT_NAMES.includes(service))
+        return undefined;
+    const source = event['source'];
+    if (source === null || typeof source !== 'object')
+        return undefined;
+    const line = source;
+    if (line['router'] !== 'request' || line['tenantId'] !== scope.tenantId || line['vertical'] !== scope.vertical)
+        return undefined;
+    if (scope.scopeId !== undefined && line['scopeId'] !== scope.scopeId)
+        return undefined;
+    const id = line[FIELD_COVERAGE_ID_FIELD];
+    return typeof id === 'string' && DISPATCH_ID.test(id) ? { id, line } : undefined;
+}
 /**
  * How many distinct operations one tally keeps. Past it, a report on a new operation is
  * refused: a vertical cannot grow the answer without bound by inventing names.
@@ -231,4 +241,35 @@ export function tallyFieldCoverage(events, routerEvents, scope) {
         refused,
     };
 }
+/** Partition by the router's own rate before tallying, so a changed rate is never averaged away. */
+export function tallyFieldCoverageByRate(events, routerEvents, scope) {
+    const reports = [...events];
+    const groups = new Map();
+    const ids = new Map();
+    const assigned = new Set();
+    for (const event of routerEvents) {
+        const vouched = routerDispatch(event, scope);
+        if (!vouched)
+            continue;
+        const { id, line } = vouched;
+        // A duplicate router line cannot assign one response to several rates.
+        if (assigned.has(id))
+            continue;
+        assigned.add(id);
+        // The rate comes only from this router line, never from the vertical's report.
+        const candidate = line['fieldCoverageRate'];
+        const rate = typeof candidate === 'number' && Number.isFinite(candidate) && candidate > 0 && candidate <= 1
+            ? candidate : null;
+        const group = groups.get(rate) ?? [];
+        group.push(event);
+        groups.set(rate, group);
+        const known = ids.get(rate) ?? new Set();
+        known.add(id);
+        ids.set(rate, known);
+    }
+    return [...groups].map(([sampleRate, vouched]) => {
+        const counted = tallyFieldCoverage(reports, vouched, scope);
+        return { ...counted, sampleRate, armedRequests: ids.get(sampleRate).size };
+    });
+}
 //# sourceMappingURL=field-coverage-tally.js.map