@substrat-run/kernel 0.120.0 → 0.121.0

package/dist/platform-sweep.js

@@ -1,4 +1,4 @@
-import { drainedEvent, instant } from '@substrat-run/contracts';
+import { drainedEvent, errorCodeOf, instant, substratError } from '@substrat-run/contracts';
 import { backoffAt } from './scope-host.js';
 import { MIGRATION_FLAG_THRESHOLD, migrationFleet, migrationProgress, scopeMigrationState } from './migration-progress.js';
 import { UNDRAINED_SKIPPED_IDS } from './outbox-event.js';
@@ -134,6 +134,21 @@ export function runningVersionOf(scope, serving) {
         return serving.versionId;
     return scope.verticalVersionId;
 }
+/**
+ * Every vertical's serving pointer, for `runningVersionOf` — one `listVerticals` read, and only
+ * when some scope is actually on a serving script, since nothing else can differ from its
+ * binding. Shared by the provision reconcile (#1653) and the cross-vertical narrowing (#1705).
+ */
+async function servingPointersFor(admin, actor, scopes) {
+    const serving = new Map();
+    if (!scopes.some((s) => s.servingRef))
+        return serving;
+    for (const v of await admin.listVerticals(actor)) {
+        if (v.servingRef && v.servingVersionId)
+            serving.set(v.slug, { ref: v.servingRef, versionId: v.servingVersionId });
+    }
+    return serving;
+}
 /**
  * This pass's share of the behind scopes: at most `batch`, as a contiguous window over
  * the id order, starting at `rng()` of the way round and wrapping. Deterministic for a
@@ -374,16 +389,7 @@ export async function runPlatformSweep(host, options) {
             deferred: 0,
         };
         const scopes = (await host.admin.listScopes(options.actor, { status: 'active' })).filter((s) => isPrimaryScope(s) && !failedThisPass.has(s.id));
-        // One directory read for every vertical's serving pointer — and only when some scope
-        // is actually on a serving script, since nothing else can differ from its binding.
-        const serving = new Map();
-        if (scopes.some((s) => s.servingRef)) {
-            for (const v of await host.admin.listVerticals(options.actor)) {
-                if (v.servingRef && v.servingVersionId) {
-                    serving.set(v.slug, { ref: v.servingRef, versionId: v.servingVersionId });
-                }
-            }
-        }
+        const serving = await servingPointersFor(host.admin, options.actor, scopes);
         const behind = [];
         for (const s of scopes) {
             const running = runningVersionOf(s, s.vertical ? serving.get(s.vertical) : null);
@@ -736,7 +742,9 @@ export async function runPlatformSweep(host, options) {
  * One pass over every cross-vertical edge (#1705). Bounded like the event drain: one batch per
  * edge per pass, reported rather than looped, so one busy producer cannot starve the rest.
  */
-async function sweepCrossVertical(host, options, cv, failedThisPass, report) {
+async function sweepCrossVertical(host, options, cv, failedThisPass, report, 
+/** Run only this producer's outgoing edges (the router kick). Absent: every edge. */
+only) {
     const out = {
         edges: [],
         delivered: 0,
@@ -763,7 +771,21 @@ async function sweepCrossVertical(host, options, cv, failedThisPass, report) {
     // fork is a copy of somebody's data. Delivering into it would feed a copy as though it were
     // the install, and reading from it would publish a copy's history to another vertical. A
     // preview is not the install either.
-    const scopes = (await host.admin.listScopes(options.actor, { status: 'active' })).filter((s) => isPrimaryScope(s) && s.vertical !== null);
+    //
+    // A producer-scoped run reads only that tenant's scopes: both ends of an edge are in one
+    // tenant, so nothing outside it can be a consumer of this producer or change how it resolves.
+    const scopes = (await host.admin.listScopes(options.actor, { status: 'active', ...(only ? { tenantId: only.tenantId } : {}) })).filter((s) => isPrimaryScope(s) && s.vertical !== null);
+    // The kick names a scope, and the edges run are the ones whose producer RESOLVES to it. A
+    // fork, a preview, a second install or a scope of another tenant is not a producer, so a
+    // kick naming one runs nothing (the sweep would resolve the same way).
+    let from = null;
+    if (only) {
+        const named = scopes.find((s) => s.id === only.scopeId && s.tenantId === only.tenantId);
+        const resolved = named ? resolveVerticalInstanceFrom(scopes, named.tenantId, named.vertical) : null;
+        if (!named || resolved?.outcome !== 'resolved' || resolved.instance.scopeId !== named.id)
+            return out;
+        from = named.vertical;
+    }
     const record = (edge) => {
         out.edges.push(edge);
         out.delivered += edge.delivered;
@@ -782,6 +804,12 @@ async function sweepCrossVertical(host, options, cv, failedThisPass, report) {
         // Idle writes no row: one green row per edge per tick would bury the ones that matter.
         if (edge.state === 'idle')
             return;
+        // A kick pass (`only`) can run every few seconds for a busy producer. It writes a row only
+        // for an edge that moved or paused. A standing failure (an old consumer, an unresolved
+        // producer) is the scheduled sweep's to record, once per tick, rather than once per kick:
+        // otherwise one broken consumer beside a busy producer files thousands of identical rows.
+        if (only && edge.state !== 'delivered' && edge.state !== 'paused')
+            return;
         options.recordSweepRun?.({
             kind: 'vertical-events',
             unit: `${edge.consumer.scopeId}:${edge.producer.vertical}`,
@@ -799,7 +827,47 @@ async function sweepCrossVertical(host, options, cv, failedThisPass, report) {
     };
     // Narrowed BEFORE any scope is called, then capped. The resolution below still needs every
     // primary scope (a producer is any of them), and that is the one directory read above.
-    const candidates = await candidatesOf(scopes);
+    // Contained: the narrowing may read the version registry (the control plane's reach), and a
+    // failed read must cost this phase one pass, not sink the phases after it. No scope is called,
+    // every watermark holds, and the next pass asks again.
+    // Scopes kept only because the narrowing could not judge them: their "imports nothing" is an answer.
+    const doubtful = new Set();
+    // Scopes the narrowing KNOWS import: their "imports nothing" contradicts the registry.
+    const knownImporters = new Set();
+    let candidates;
+    try {
+        candidates = await candidatesOf(scopes, {
+            ...(from !== null ? { from } : {}),
+            known: (scopeIds) => {
+                for (const id of scopeIds)
+                    knownImporters.add(id);
+            },
+            doubt: (unit, reason, scopeIds) => {
+                for (const id of scopeIds)
+                    doubtful.add(id);
+                // A kick pass leaves doubt to the sweep: see the filter below and `record`.
+                if (only)
+                    return;
+                options.recordSweepRun?.({
+                    kind: 'vertical-events',
+                    unit: `version:${unit}`,
+                    outcome: 'failed',
+                    operation: 'sweep.vertical-events:narrowing',
+                    error: `the version registry cannot say whether ${unit} imports anything (${reason}); ` +
+                        `its scopes are asked directly this pass`,
+                });
+            },
+        });
+    }
+    catch (err) {
+        report.errors.push({ kind: 'vertical-events', id: 'candidates', error: message(err) });
+        return out;
+    }
+    // A kick pass calls only the consumers the registry KNOWS import from this producer. A scope
+    // kept as doubt is asked by the scheduled sweep, once per tick. Asking it on every kick would
+    // cost a call, and a row, per flagged response.
+    if (only)
+        candidates = candidates.filter((c) => !doubtful.has(c.id));
     out.candidates = candidates.length;
     const configuredCap = cv.maxConsumers ?? CROSS_VERTICAL_CONSUMERS_PER_PASS;
     const cap = Number.isFinite(configuredCap) && configuredCap >= 0 ? Math.floor(configuredCap) : CROSS_VERTICAL_CONSUMERS_PER_PASS;
@@ -808,20 +876,38 @@ async function sweepCrossVertical(host, options, cv, failedThisPass, report) {
     await mapBounded(visiting, options.concurrency ?? 8, async (consumer) => {
         if (failedThisPass.has(consumer.id))
             return;
+        // The consumer side, failing before any producer is named: an edge to `*`, so it lands in
+        // the sweep-run rows under `<scope>:*` beside the per-producer edges, not only in `errors`.
+        const consumerFailed = (reason) => record({
+            tenantId: consumer.tenantId,
+            consumer: { scopeId: consumer.id, vertical: consumer.vertical ?? '' },
+            producer: { vertical: '*', scopeId: null },
+            state: 'failed',
+            delivered: 0,
+            deadLettered: 0,
+            withheld: 0,
+            duplicates: 0,
+            reason,
+        });
         let state;
         try {
             state = await reach.importState(consumer.tenantId, consumer.id);
         }
         catch (err) {
-            report.errors.push({ kind: 'vertical-events', id: consumer.id, error: message(err) });
+            consumerFailed(`could not read the consumer's imports: ${message(err)}`);
             return;
         }
-        const bySource = new Map();
-        for (const c of state.consumes) {
-            const list = bySource.get(c.from) ?? [];
-            list.push({ type: c.type, schemaVersion: c.schemaVersion });
-            bySource.set(c.from, list);
+        // A scope the narrowing KNOWS imports (`hint.known`) whose deployment answers that it imports
+        // NOTHING: the two disagree, and the scope is not running the code the registry describes (a
+        // push that did not reach it, or a reconcile still owed). Said, not skipped: skipping would
+        // make every edge into this scope disappear without a trace. Any other candidate (a superset
+        // narrowing, which the contract allows, or a doubtful scope) answering "nothing" has answered.
+        if (state.consumes.length === 0 && knownImporters.has(consumer.id)) {
+            consumerFailed("the version registry says this scope's code imports events, but its deployment answers that it " +
+                'imports nothing — it is not running the version the registry names; redeploy or reconcile it');
+            return;
         }
+        const bySource = wantsBySource(state.consumes, (f) => from === null || f === from);
         // Sequential per consumer: its edges share the consumer's serialization queue anyway,
         // and one consumer with many sources must not hold more than one slot of the pass.
         for (const [from, wants] of [...bySource.entries()].sort(([a], [b]) => a.localeCompare(b))) {
@@ -830,46 +916,259 @@ async function sweepCrossVertical(host, options, cv, failedThisPass, report) {
     });
     return out;
 }
-async function sweepEdge(reach, scopes, consumer, from, wants, state, budget) {
-    const vertical = consumer.vertical;
-    const edge = (rest) => ({
-        tenantId: consumer.tenantId,
-        consumer: { scopeId: consumer.id, vertical },
-        producer: { vertical: from, scopeId: null },
-        delivered: 0,
-        deadLettered: 0,
-        withheld: 0,
-        duplicates: 0,
-        ...rest,
+/**
+ * Run ONE producer's outgoing edges now (#1705 PR 2): the half of the router kick that makes a
+ * cross-vertical event arrive in seconds rather than at the next sweep.
+ *
+ * The same phase, under the same rules, narrowed. It reads the producer's tenant only, runs only
+ * edges whose producer RESOLVES to `producer` (so a fork, a preview or a second install runs
+ * nothing), asks `candidates` with `{ from }` so a consumer that imports nothing from this
+ * vertical is never called, and keeps the per-pass consumer cap. What it moves is exactly what
+ * the next sweep would have moved: the watermark's compare-and-set makes the two safe to overlap,
+ * and an edge a kick has taken reads as `idle` to the sweep that follows.
+ */
+export async function runCrossVerticalFrom(host, options, producer) {
+    const report = { errors: [] };
+    const crossVertical = await sweepCrossVertical(host, options, options.crossVertical, new Set(), report, producer);
+    return { crossVertical, errors: report.errors };
+}
+/**
+ * The control plane's `CrossVerticalReach.candidates` (#1705 PR 2): narrow the listed scopes to
+ * those whose RUNNING version may import, read from the version registry and never from a scope.
+ *
+ * Per pass: one `listVerticals` (the serving pointers, only when some scope is on a serving
+ * script), and one `readImports` per DISTINCT running version, at most `concurrency` in flight.
+ * The control plane's reader is an unaudited directory read behind a cache keyed (slug,
+ * version), since a pushed version's manifest never changes. So after the first pass it costs
+ * no read at all.
+ *
+ * Only a version that says it imports nothing is dropped (`none`: no manifest, no registry, no
+ * `imports` key). A version the registry cannot answer for (`unreadable`: a manifest that does
+ * not parse, a malformed row, a version the registry does not know, a failed read) keeps its
+ * scopes as candidates, and the scope's own `importState` decides. Excluding a consumer wrongly
+ * loses its edge with no trace. Including one wrongly costs one call. Each such version is
+ * reported once per pass through `hint.doubt`, and a failure on one version never stops the
+ * others.
+ */
+/**
+ * What each scope's RUNNING version imports, from the registry (#1705): one `listVerticals` when
+ * a scope is on a serving script, then one `readImports` per distinct running version, at most
+ * `concurrency` in flight. A failure on one version never stops the others: a read that throws is
+ * reported as `threw` beside the fact, since a caller may treat "the registry could not be asked"
+ * differently from "the manifest does not parse". A scope bound to no version gets no fact. The narrowing and the promote gate
+ * both ask it, so the two cannot come to disagree about which code a scope runs.
+ */
+async function runningImportsOf(admin, actor, scopes, readImports, concurrency) {
+    const serving = await servingPointersFor(admin, actor, scopes);
+    const versions = new Map();
+    const keyed = [];
+    for (const s of scopes) {
+        if (!s.vertical)
+            continue;
+        const versionId = runningVersionOf(s, serving.get(s.vertical));
+        const key = `${s.vertical}@${versionId ?? '(no version)'}`;
+        if (versionId && !versions.has(key))
+            versions.set(key, { slug: s.vertical, versionId });
+        keyed.push({ scope: s, key, versionId });
+    }
+    const facts = new Map();
+    const threw = new Map();
+    await mapBounded([...versions], concurrency, async ([key, v]) => {
+        try {
+            facts.set(key, await readImports(v.slug, v.versionId));
+        }
+        catch (err) {
+            facts.set(key, { kind: 'unreadable', reason: message(err) });
+            threw.set(key, message(err));
+        }
     });
-    if (from === vertical) {
-        return edge({ state: 'unresolved', reason: `'${vertical}' imports from itself — an import names ANOTHER vertical` });
+    return keyed.map((k) => ({ ...k, fact: facts.get(k.key), ...(threw.has(k.key) ? { threw: threw.get(k.key) } : {}) }));
+}
+export function registryImportCandidates(input) {
+    return async (scopes, hint) => {
+        const running = await runningImportsOf(input.admin, input.actor, scopes, input.readImports, input.concurrency ?? 8);
+        const doubted = new Map();
+        const known = [];
+        const out = [];
+        for (const { scope, key, fact: read } of running) {
+            const fact = read ?? {
+                kind: 'unreadable',
+                reason: 'the scope names no version the registry could be asked about',
+            };
+            if (fact.kind === 'none')
+                continue;
+            if (fact.kind === 'imports') {
+                const from = hint?.from;
+                if (from !== undefined ? fact.rows.some((r) => r.from === from) : fact.rows.length > 0) {
+                    out.push(scope);
+                    known.push(scope.id);
+                }
+                continue;
+            }
+            out.push(scope);
+            const d = doubted.get(key) ?? { reason: fact.reason, scopeIds: [] };
+            d.scopeIds.push(scope.id);
+            doubted.set(key, d);
+        }
+        for (const [key, d] of doubted)
+            hint?.doubt?.(key, d.reason, d.scopeIds);
+        if (known.length > 0)
+            hint?.known?.(known);
+        return out;
+    };
+}
+/**
+ * Who a promote breaks (#1705 PR 3): the installed consumers whose RUNNING code imports an
+ * exported (type, schemaVersion) that the outgoing version promised and the incoming one drops
+ * or exports at another version. The promote gate refuses on a non-empty answer unless it is
+ * acknowledged (`exportBreak`), and the refusal lists them.
+ *
+ * - **What changed** is outgoing versus incoming, from the two versions' registries. An outgoing
+ *   version whose registry states no exports (a first promote, or a push by a CLI older than
+ *   0.34.0) promised nothing the registry can name, so nothing is judged broken. Nothing it
+ *   exported at run time could be listed either, which is what the permission-digest gate
+ *   beside this one is for.
+ * - **Who is a consumer** is the edge's own rule: a primary, active scope of ANOTHER vertical, in
+ *   a tenant where the producer is installed (any primary, active install, so two installs still
+ *   count), whose running version (`runningVersionOf`) declares the import. That over-approximates
+ *   on purpose, for a listed vertical's tenants still pinned to an older producer version: a
+ *   refusal that names one tenant too many costs an acknowledgement, and one that names too few
+ *   costs a silent stall.
+ * - **A consumer version whose manifest does not parse** is not judged. It cannot be said to
+ *   break, and refusing every promote over a manifest nobody can parse would make the gate one
+ *   nobody can pass. A read that THREW is different: the registry could not be asked, so whom the
+ *   promote breaks is unknown, and this throws. The gate then refuses rather than failing open.
+ *   A failed directory read throws the same way.
+ *
+ * Cost: nothing at all unless an export changed. Then one fleet `listScopes`, one
+ * `listVerticals` when a scope is on a serving script, and one `readImports` per distinct
+ * running consumer version, at most `concurrency` in flight.
+ */
+export async function exportBreaksOf(input) {
+    // An outgoing manifest that does not parse promised SOMETHING nobody can read. Judging it as
+    // "promised nothing" would pass every break unacknowledged, so it refuses, as a thrown read does.
+    if (input.outgoing.kind === 'unreadable') {
+        throw substratError('unavailable', `cannot say whom this promotion breaks: the outgoing version's exports could not be read (${input.outgoing.reason})`);
+    }
+    if (input.outgoing.kind !== 'exports')
+        return [];
+    const incoming = new Map(input.incoming.kind === 'exports' ? input.incoming.rows.map((r) => [r.type, r.schemaVersion]) : []);
+    const changed = new Map();
+    for (const r of input.outgoing.rows) {
+        const now = incoming.get(r.type) ?? null;
+        if (now !== r.schemaVersion)
+            changed.set(r.type, { schemaVersion: r.schemaVersion, incoming: now });
+    }
+    if (changed.size === 0)
+        return [];
+    const scopes = (await input.admin.listScopes(input.actor, { status: 'active' })).filter((s) => isPrimaryScope(s) && s.vertical !== null);
+    const installedIn = new Set(scopes.filter((s) => s.vertical === input.producer).map((s) => s.tenantId));
+    const consumers = scopes.filter((s) => s.vertical !== input.producer && installedIn.has(s.tenantId));
+    if (consumers.length === 0)
+        return [];
+    const out = [];
+    for (const { scope, key, versionId, fact, threw } of await runningImportsOf(input.admin, input.actor, consumers, input.readImports, input.concurrency ?? 8)) {
+        if (threw !== undefined) {
+            throw substratError('unavailable', `cannot say whom this promotion breaks: the registry could not be asked what ${key} imports (${threw}) — retry`);
+        }
+        if (fact?.kind !== 'imports')
+            continue;
+        for (const row of fact.rows) {
+            const hit = row.from === input.producer ? changed.get(row.type) : undefined;
+            if (!hit || hit.schemaVersion !== row.schemaVersion)
+                continue;
+            out.push({
+                tenantId: scope.tenantId,
+                scopeId: scope.id,
+                vertical: scope.vertical,
+                version: versionId,
+                type: row.type,
+                schemaVersion: row.schemaVersion,
+                incoming: hit.incoming,
+            });
+        }
     }
-    // Both ends must be the tenant's one primary instance of their vertical, by #1706's one rule
-    // (`resolveVerticalInstanceFrom`: same tenant, active, primary; two are `ambiguous`, refused
-    // rather than guessed). The producer is who is read. The consumer is who the producer's grant
-    // names, and a grant naming a slug cannot tell two installs of it apart.
+    return out.sort((a, b) => a.tenantId.localeCompare(b.tenantId) || a.scopeId.localeCompare(b.scopeId) || a.type.localeCompare(b.type));
+}
+/** How `exportBreakRefusal` begins: what lets the promote route recognise it and add the listing. */
+export const EXPORT_BREAK_REFUSAL = 'promotion drops or re-versions';
+/** Whether a throw is the promote gate's export-break refusal (`exportBreakRefusal`). */
+export function isExportBreakRefusal(err) {
+    return errorCodeOf(err) === 'precondition_failed' && err instanceof Error && err.message.startsWith(EXPORT_BREAK_REFUSAL);
+}
+/**
+ * The refusal a promote gets for a non-empty `exportBreaksOf` (#1705 PR 3). Counts only: the
+ * adapters do not know who is promoting, and a builder must not learn from an error which other
+ * tenants import its events. The route that knows the caller lists what they may see.
+ */
+export function exportBreakRefusal(breaks) {
+    const types = new Set(breaks.map((b) => b.type)).size;
+    const apps = new Set(breaks.map((b) => b.scopeId)).size;
+    const tenants = new Set(breaks.map((b) => b.tenantId)).size;
+    return (`${EXPORT_BREAK_REFUSAL} ${types} exported event type(s) that ${apps} installed app(s) in ` +
+        `${tenants} tenant(s) import — their edges would stop delivering it. Acknowledge it explicitly ` +
+        `(exportBreak) to promote, or keep the export and bump its consumers first`);
+}
+/**
+ * The two ends of the edge from `from` into `consumer`, by #1706's one rule
+ * (`resolveVerticalInstanceFrom`: same tenant, active, primary; two are `ambiguous`, refused rather
+ * than guessed). The producer is who is read. The consumer is who the producer's grant names, and a
+ * grant naming a slug cannot tell two installs of it apart. Shared by the sweep and the health read,
+ * so the view cannot disagree with the next pass about where an edge points, or why it points
+ * nowhere.
+ */
+function edgeEnds(scopes, consumer, from) {
+    const vertical = consumer.vertical;
+    if (from === vertical)
+        return { reason: `'${vertical}' imports from itself — an import names ANOTHER vertical` };
     const self = resolveVerticalInstanceFrom(scopes, consumer.tenantId, vertical);
     if (self.outcome !== 'resolved' || self.instance.scopeId !== consumer.id) {
-        return edge({
-            state: 'unresolved',
+        return {
             reason: `this tenant has more than one primary instance of '${vertical}', so the producer cannot tell which one its grant names`,
-        });
+        };
     }
     const producer = resolveVerticalInstanceFrom(scopes, consumer.tenantId, from);
     if (producer.outcome !== 'resolved') {
-        return edge({
-            state: 'unresolved',
+        return {
             reason: producer.outcome === 'not-installed'
                 ? `'${from}' is not installed in this tenant`
                 : `this tenant has more than one primary instance of '${from}' — delivery waits until one is chosen`,
-        });
+        };
+    }
+    return { source: { vertical: from, scopeId: producer.instance.scopeId } };
+}
+/** A consumer's declared imports, grouped by the vertical they come from. */
+function wantsBySource(consumes, only = () => true) {
+    const bySource = new Map();
+    for (const c of consumes) {
+        if (!only(c.from))
+            continue;
+        const list = bySource.get(c.from) ?? [];
+        list.push({ type: c.type, schemaVersion: c.schemaVersion });
+        bySource.set(c.from, list);
     }
-    const source = { vertical: from, scopeId: producer.instance.scopeId };
+    return bySource;
+}
+async function sweepEdge(reach, scopes, consumer, from, wants, state, budget) {
+    const vertical = consumer.vertical;
+    const edge = (rest) => ({
+        tenantId: consumer.tenantId,
+        consumer: { scopeId: consumer.id, vertical },
+        producer: { vertical: from, scopeId: null },
+        delivered: 0,
+        deadLettered: 0,
+        withheld: 0,
+        duplicates: 0,
+        ...rest,
+    });
+    const ends = edgeEnds(scopes, consumer, from);
+    if ('reason' in ends)
+        return edge({ state: 'unresolved', reason: ends.reason });
+    const { source } = ends;
     const at = { producer: source };
     const after = state.cursors.find((c) => c.source === source.scopeId)?.cursor ?? null;
     try {
-        const batch = await reach.readExports(producer.instance.tenantId, source.scopeId, {
+        const batch = await reach.readExports(consumer.tenantId, source.scopeId, {
             consumer: vertical,
             after,
             wants,
@@ -921,6 +1220,236 @@ async function sweepEdge(reach, scopes, consumer, from, wants, state, budget) {
         return edge({ ...at, state: 'failed', reason: message(err) });
     }
 }
+/**
+ * Where every cross-vertical edge of one tenant stands, read LIVE (#1705 PR 3): the view behind
+ * the console's and the dashboard's edge health.
+ *
+ * It is the sweep's own walk with the delivery taken out. It uses the same reach, the same
+ * narrowing (`candidates`, which keeps it off scopes that import nothing), and the same resolution
+ * of both ends (`edgeEnds`). So it cannot disagree with the next pass about which edges exist or
+ * where they point. Per edge it makes one probe read of the producer after the watermark,
+ * `limit: 1`, which tells behind from caught up and dates the oldest waiting event. That read is the
+ * producer's own `readExportedEvents`, gated and audited as on a pass, and nothing it returns is
+ * delivered or kept. The consumer's door is read from its peer switch (`peerGrantsStatus`), because
+ * a consumer refusing the producer is visible only at delivery otherwise. The tenant's recent
+ * `vertical-events` sweep-run rows add the last pass that delivered and the last that did not.
+ *
+ * `focus` narrows it to one scope's edges, the ones into it and out of it: a per-app view asks
+ * nothing about the rest of the tenant. Out of it means consumers the narrowing names for the
+ * focus's vertical (`hint.from`), so the registry, not a scope, decides who is asked.
+ *
+ * Cost per view: one directory read, the narrowing, then per importing scope one `importState`
+ * and one door read, per edge one probe read and one or two sweep-run reads. It is bounded by the
+ * tenant, never the fleet.
+ *
+ * Who the reads are audited as: the directory, door and history reads as `actor`, the viewer the
+ * caller names. The reach's reads (`importState`, the probe) are audited as whatever actor the
+ * reach was built with. On the control plane that is the sweep's own actor, since it is the
+ * sweep's reach, so those rows read as the platform's, not the viewer's.
+ *
+ * `unavailable` is its own state: a side that could not be asked gets no health, and no
+ * surface may show it as healthy.
+ */
+export async function crossVerticalHealth(host, options) {
+    const { actor, tenantId } = options;
+    const now = options.now ?? Date.now;
+    const concurrency = options.concurrency ?? 8;
+    const report = {
+        tenantId,
+        checkedAt: new Date(now()).toISOString(),
+        edges: [],
+        unavailable: null,
+        history: { available: true, reason: null },
+    };
+    const cv = options.crossVertical ?? {};
+    // No reach, on a host whose apps live in their own deployments (the shared control plane without
+    // DISPATCH): this host's own verbs cannot see a single hosted scope, and its registered modules
+    // import nothing, so the default would report "no edges". That is an answer it cannot give.
+    if (!cv.reach && host.servesScopesElsewhere?.()) {
+        report.unavailable =
+            "edge health cannot reach the deployments that serve this tenant's apps: no cross-vertical reach is " +
+                'configured on this control plane (DISPATCH / PLATFORM_SECRET)';
+        return report;
+    }
+    const reach = cv.reach ?? {
+        importState: (t, s) => host.admin.importState(actor, t, s),
+        readExports: (t, s, input) => host.admin.readExportedEvents(actor, t, s, input),
+        deliver: () => Promise.reject(new Error('edge health never delivers')),
+    };
+    const candidatesOf = reach.candidates?.bind(reach) ??
+        ((scopes) => ((host.registeredImports?.() ?? []).length > 0 ? scopes : []));
+    const doorOf = options.door ?? ((t, s) => host.admin.peerGrantsStatus(actor, { tenantId: t, scopeId: s }));
+    const knownImporters = new Set();
+    const known = (ids) => {
+        for (const id of ids)
+            knownImporters.add(id);
+    };
+    const listed = await (async () => {
+        const scopes = (await host.admin.listScopes(actor, { status: 'active', tenantId })).filter((s) => isPrimaryScope(s) && s.vertical !== null);
+        if (options.focus === undefined)
+            return { scopes, candidates: await candidatesOf(scopes, { known }) };
+        const focus = scopes.find((s) => s.id === options.focus);
+        if (!focus)
+            return { scopes, candidates: [] };
+        const [into, outOf] = await Promise.all([
+            candidatesOf([focus], { known }),
+            candidatesOf(scopes, { from: focus.vertical, known }),
+        ]);
+        return { scopes, focus, candidates: [...into, ...outOf.filter((c) => c.id !== focus.id)] };
+    })().then((v) => ({ ok: true, ...v }), (err) => ({ ok: false, error: message(err) }));
+    if (!listed.ok) {
+        report.unavailable = `could not list this tenant's apps that import events: ${listed.error}`;
+        return report;
+    }
+    const { scopes, candidates } = listed;
+    const focusScope = 'focus' in listed ? listed.focus : undefined;
+    const focusVertical = focusScope?.vertical;
+    // Which sweep-run unit each edge's history is filed under: `<consumer>:<producer vertical>`,
+    // or `<consumer>:*` for a consumer that could not be asked (whatever the view tags it with).
+    const unitOf = new Map();
+    await mapBounded(candidates, concurrency, async (consumer) => {
+        const vertical = consumer.vertical ?? '';
+        const edge = (from, rest) => ({
+            tenantId,
+            consumer: { scopeId: consumer.id, vertical },
+            producer: { vertical: from, scopeId: null },
+            reason: null,
+            watermark: null,
+            oldestPending: null,
+            lagMs: null,
+            unexported: [],
+            lastDelivered: null,
+            lastProblem: null,
+            ...rest,
+        });
+        const filed = (e, unitFrom) => {
+            unitOf.set(e, `${consumer.id}:${unitFrom}`);
+            return e;
+        };
+        // Into the focus, every source. Into anyone else, only the focus's own vertical.
+        const wanted = (from) => focusVertical === undefined || consumer.id === options.focus || from === focusVertical;
+        // The consumer's imports and its door, together: the door read is wasted only on a consumer
+        // that turns out to import nothing, which the narrowing has already made rare.
+        const [stateRead, doorRead] = await Promise.all([
+            reach.importState(tenantId, consumer.id).then((state) => ({ ok: true, state }), (err) => ({ ok: false, error: message(err) })),
+            doorOf(tenantId, consumer.id).then((entries) => ({ ok: true, entries }), (err) => ({ ok: false, error: message(err) })),
+        ]);
+        // A consumer that could not be asked names no producer ('*'). Seen from a focused PRODUCER,
+        // though, it is one of that producer's consumers (the narrowing named it for the focus's
+        // vertical), so it is tagged with the focus: a view of the producer must show the failure
+        // rather than filter out an edge whose other end is unknown.
+        const unasked = (reason) => filed(focusScope && consumer.id !== focusScope.id
+            ? edge(focusScope.vertical, { state: 'unavailable', reason, producer: { vertical: focusScope.vertical, scopeId: focusScope.id } })
+            : edge('*', { state: 'unavailable', reason }), '*');
+        if (!stateRead.ok) {
+            report.edges.push(unasked(`could not ask this app what it imports: ${stateRead.error}`));
+            return;
+        }
+        const state = stateRead.state;
+        if (state.consumes.length === 0) {
+            if (knownImporters.has(consumer.id)) {
+                report.edges.push(unasked("the version registry says this app's code imports events, but its deployment answers that it " +
+                    'imports nothing — it is not running the version the registry names; redeploy or reconcile it'));
+            }
+            return;
+        }
+        // Unreadable is not "open": the edge keeps its probe's state, and the reason says so.
+        const door = doorRead.ok
+            ? new Map(doorRead.entries.map((e) => [e.vertical, { calls: e.calls, reason: e.switchedOff?.reason ?? null }]))
+            : null;
+        const sources = [...wantsBySource(state.consumes, wanted)];
+        await mapBounded(sources, concurrency, async ([from, wants]) => {
+            report.edges.push(filed(await edgeHealthOf(from, wants), from));
+        });
+        async function edgeHealthOf(from, wants) {
+            const ends = edgeEnds(scopes, consumer, from);
+            if ('reason' in ends)
+                return edge(from, { state: 'unresolved', reason: ends.reason });
+            const { source } = ends;
+            const cursor = state.cursors.find((c) => c.source === source.scopeId) ?? null;
+            const at = {
+                producer: source,
+                watermark: cursor?.cursor ? { cursor: cursor.cursor, updatedAt: cursor.updatedAt } : null,
+            };
+            let probe;
+            try {
+                probe = await reach.readExports(tenantId, source.scopeId, {
+                    consumer: vertical,
+                    after: cursor?.cursor ?? null,
+                    wants,
+                    limit: 1,
+                });
+            }
+            catch (err) {
+                return edge(from, { ...at, state: 'unavailable', reason: `could not ask '${from}' what is waiting: ${message(err)}` });
+            }
+            const unexported = probe.unexported;
+            if (probe.paused) {
+                return edge(from, {
+                    ...at,
+                    unexported,
+                    state: 'paused',
+                    reason: `'${from}' does not grant vertical:${vertical} ${probe.paused.missing.join(', ')} — nothing moves; the backlog waits in its outbox`,
+                });
+            }
+            const first = [...probe.events, ...probe.withheld].sort((a, b) => (a.id < b.id ? -1 : 1))[0];
+            const oldestPending = first ? { id: first.id, occurredAt: first.occurredAt } : null;
+            const occurred = first ? Date.parse(first.occurredAt) : NaN;
+            const lagMs = first && Number.isFinite(occurred) ? Math.max(0, Math.floor(now() - occurred)) : null;
+            const pending = { ...at, unexported, oldestPending, lagMs };
+            const gate = door?.get(from);
+            if (gate && gate.calls !== 'on') {
+                return edge(from, {
+                    ...pending,
+                    state: 'paused',
+                    reason: gate.calls === 'off'
+                        ? `this app has '${from}' switched off${gate.reason ? ` (${gate.reason})` : ''} — nothing is delivered; the backlog waits in the producer's outbox`
+                        : `this app holds no grant for '${from}' — its door refuses the delivery; the backlog waits in the producer's outbox`,
+                });
+            }
+            // Caught up means nothing is waiting, which an unread door cannot change, so its reason is
+            // null as the contract says. Behind with an unread door says so: whether the next pass
+            // delivers depends on it.
+            if (!first)
+                return edge(from, { ...pending, state: 'caught-up', reason: null });
+            const doorNote = doorRead.ok ? '' : ` (whether this app admits '${from}' could not be read: ${doorRead.error})`;
+            return edge(from, {
+                ...pending,
+                state: 'behind',
+                reason: `events are waiting past the watermark; the next pass takes them${doorNote}`,
+            });
+        }
+    });
+    // The history, read per edge: the last pass that delivered, and the last that did not when it is
+    // newer. Per edge rather than one window over the tenant, so a noisy edge's rows cannot push a
+    // quiet edge's last delivery out of the read. One read when the newest row is a delivery, two
+    // otherwise. A failed read costs the history, never the live state.
+    await mapBounded(report.edges, concurrency, async (e) => {
+        const unit = unitOf.get(e);
+        if (unit === undefined)
+            return;
+        try {
+            const runs = (filter) => host.admin.listSweepRuns(actor, { kind: 'vertical-events', tenantId, unit, limit: 1, ...filter });
+            const [latest] = await runs({});
+            if (!latest)
+                return;
+            if (latest.outcome === 'ok') {
+                e.lastDelivered = { at: latest.at };
+                return;
+            }
+            const [ok] = await runs({ outcome: 'ok' });
+            e.lastDelivered = ok ? { at: ok.at } : null;
+            e.lastProblem = { at: latest.at, outcome: latest.outcome, error: latest.error ?? null };
+        }
+        catch (err) {
+            report.history = { available: false, reason: `the sweep history could not be read: ${message(err)}` };
+        }
+    });
+    report.edges.sort((a, b) => a.consumer.vertical.localeCompare(b.consumer.vertical) ||
+        a.consumer.scopeId.localeCompare(b.consumer.scopeId) ||
+        a.producer.vertical.localeCompare(b.producer.vertical));
+    return report;
+}
 /**
  * One read→ship→stamp cycle over ONE scope's outbox (#1334). Returns how many
  * events shipped, so the caller can tell a full batch (more waiting) from a