@substrat-run/kernel 0.147.0 → 0.149.0

package/dist/platform-sweep.js

@@ -1,197 +1,20 @@
-import { drainedEvent, errorCodeOf, instant, substratError } from '@substrat-run/contracts';
+import { drainedEvent, instant, substratError } from '@substrat-run/contracts';
 import { STORAGE_GAUGE_PRUNE_BATCH, STORED_SCOPE_STATUSES, holdsStore } from './storage-gauge.js';
 import { assertRowLimit, backoffAt, TELEMETRY_PRUNE_BATCH } from './scope-host.js';
 import { MIGRATION_FLAG_THRESHOLD, migrationFleet, migrationProgress, scopeMigrationState } from './migration-progress.js';
 import { UNDRAINED_SKIPPED_IDS } from './outbox-event.js';
 import { resolveVerticalInstanceFrom } from './peer.js';
+import { isPrimaryScope, runningVersionOf, servingPointersFor } from './scope-identity.js';
+import { mapBounded, message } from './map-bounded.js';
+import { runningImportsOf } from './export-break.js';
 /** How many access rows one pass ships, and one pass prunes, by default. */
 const ACCESS_LOG_BATCH = 500;
 /** How many events one pass drains PER SCOPE by default. */
 const EVENT_DRAIN_BATCH = 200;
-/**
- * The platform sweep's per-scope gating state (#383), as both adapters build it.
- *
- * Shared rather than spelled twice because `lint:spine-ddl` can compare the copies
- * only where they are DDL a `KERNEL_DDL` executes — and this table is also rebuilt
- * by `SCHEDULE_STATE_REBUILD` below, on a store that predates the key. One
- * definition is what keeps the rebuilt shape and the created shape the same shape;
- * the gate then holds each adapter to including it.
- */
-export const SCHEDULE_STATE_DDL = `
-  CREATE TABLE IF NOT EXISTS _substrat_schedule_state (
-    -- #1288: WHICH of the two families this row belongs to, named with the same two
-    -- words _substrat_sweep_runs already records its entries under:
-    --   * 'schedule'  -- keyed by the operation (module/verb). last_run_at and
-    --     last_status are when that operation RAN here and how it ended.
-    --   * 'freshness' -- keyed freshness:<eventType> (#1232). last_run_at and
-    --     last_status are when the evaluator last RECORDED a verdict for that event
-    --     type and what it was. Nothing ran; the row gates what the sweep records.
-    kind TEXT NOT NULL,
-    schedule_op TEXT NOT NULL,
-    last_run_at TEXT,
-    last_status TEXT,
-    -- #1525: the invocation this row's last run happened in, or null. Null is a fact
-    -- here, not a gap: a 'freshness' row never invokes anything (the evaluator only
-    -- records a verdict), a 'schedule' row a pass SKIPPED carries no fresh call to
-    -- attribute and keeps whatever it already held, and a row written before this
-    -- column existed predates the possibility. Only a due schedule's own invoke
-    -- mints one and writes it here, in the same call that stamps it onto whatever
-    -- the operation emits — see runDueSchedules in each adapter.
-    invocation_id TEXT,
-    -- #2096: a purge horizon's lap in progress (entity-trash.ts, PurgeLap) -- where its
-    -- next pass resumes in the bin, and how many purges failed earlier in the lap. Only a
-    -- 'schedule' row of a purge schedule holds one, and only mid-lap: NULL is the start
-    -- of a lap, which is also the honest reading of every row written before the column.
-    purge_cursor TEXT,
-    -- The key LEADS with kind, and that is the point of #1288 rather than a tidy-up.
-    -- Until it did, the two families were told apart by the spelling of one column:
-    -- a freshness key could never LOOK like an operation (an event type has passed
-    -- contracts' eventType regex -- lowercase ns.verb, no colon, no slash), but the
-    -- other direction was convention only, because scheduleSpec.operation is
-    -- z.string().min(1). A module declaring a schedule literally named
-    -- "freshness:orders.placed" shared the evaluator's row and nothing refused it:
-    -- each write clobbered the other's verdict, and the sweep read back whichever
-    -- ran last. With kind in the key those are two rows that cannot meet.
-    PRIMARY KEY (kind, schedule_op)
-  );
-`;
-/**
- * The `kind` a pre-#1288 row belongs to, derived from its `schedule_op` — the backfill's one
- * rule, shared by `SCHEDULE_STATE_REBUILD` below and by a restore of a dump taken before the
- * column (`spineRowsInsert`, #1883), so the two cannot file the same row differently.
- */
-export const SCHEDULE_STATE_KIND_OF_OP = "CASE WHEN substr(schedule_op, 1, 10) = 'freshness:' THEN 'freshness' ELSE 'schedule' END";
-/**
- * `_substrat_schedule_state`, rebuilt with its #1288 key on a store created before
- * it. Create-copy-drop-rename, because `kind` joins the PRIMARY KEY and SQLite
- * cannot widen a key in place — the same shape the directory's `ensureIdentityKey`
- * uses, and detected the same way (from `sqlite_master.sql`, which DO SQLite serves
- * and `PRAGMA` does not, so both adapters migrate by one strategy).
- *
- * The new table is `SCHEDULE_STATE_DDL` under a temporary name, so the rebuilt shape
- * cannot drift from the created one.
- *
- * The backfill derives `kind` from the `freshness:` prefix because that prefix IS how
- * the two families were told apart until now: every row the evaluator ever wrote
- * carries it, and no operation name in existence does. `substr(...) = 'freshness:'`
- * rather than `LIKE`, which is case-insensitive over ASCII in SQLite and would file a
- * schedule named `FRESHNESS:x` under the evaluator.
- *
- * Keys are copied VERBATIM, prefix included. What changes is which rows can coexist,
- * not what any row says — so a deployment rolled back to code that looks a freshness
- * key up under its old name still finds it.
- *
- * **Run these inside the adapter's transaction API**, which is what both callers do —
- * `db.transaction` on the pure side, `ctx.storage.transactionSync` on the DO side.
- * Un-wrapped, a stop between the CREATE and the DROP leaves the scratch table behind
- * and the NEXT wake dies on `table _substrat_schedule_state_new already exists`, which
- * is a scope that cannot open; a stop between the DROP and the RENAME is worse and
- * quieter, because the next wake's `CREATE TABLE IF NOT EXISTS` puts an EMPTY table
- * of the new shape in place, the detection below then reads it as already migrated,
- * and every copied row stays orphaned in the scratch table. Atomically, neither state
- * is reachable — which is why there is no recovery path here to go with them.
- *
- * The leading `DROP TABLE IF EXISTS` is belt to that braces, not the fix: it costs one
- * statement and makes the rebuild idempotent against a scratch table left by anything
- * below the transaction (a torn copy of the file). A restore cannot carry one in: since
- * #1883 it refuses a spine table the kernel does not build.
- *
- * A restore never reaches this rebuild either: it builds the table from the current DDL and
- * derives `kind` for a legacy dump's rows with `SCHEDULE_STATE_KIND_OF_OP`. This runs only
- * for a store that already holds the old table when it wakes.
- */
-export const SCHEDULE_STATE_REBUILD = `
-  DROP TABLE IF EXISTS _substrat_schedule_state_new;
-  ${SCHEDULE_STATE_DDL.replace('CREATE TABLE IF NOT EXISTS _substrat_schedule_state', 'CREATE TABLE _substrat_schedule_state_new')}
-  -- #1525: invocation_id is not in this column list, deliberately — this rebuild runs
-  -- only on a pre-#1288 table, which predates invocation_id too, so there is nothing
-  -- to copy. The new table's default (NULL) is the honest answer for every such row.
-  INSERT INTO _substrat_schedule_state_new (kind, schedule_op, last_run_at, last_status)
-    SELECT ${SCHEDULE_STATE_KIND_OF_OP}, schedule_op, last_run_at, last_status
-      FROM _substrat_schedule_state;
-  DROP TABLE _substrat_schedule_state;
-  ALTER TABLE _substrat_schedule_state_new RENAME TO _substrat_schedule_state;
-`;
-/**
- * Whether a store's `_substrat_schedule_state` already carries the #1288 key, read
- * off the `sql` column of `sqlite_master`. `false` means the rebuild is due.
- */
-export function scheduleStateHasKind(tableSql) {
-    return tableSql.includes('PRIMARY KEY (kind, schedule_op)');
-}
 /** The #1172 phase's per-pass bound when `provisionReconcileBatch` is unset (#1653). */
 export const PROVISION_RECONCILE_BATCH = 50;
 /** How many `unsupported` scope ids one report carries — the count stays exact. */
 export const PROVISION_RECONCILE_REPORTED_IDS = 50;
-/**
- * A scope the platform may treat as the REAL install, rather than a copy of one (#1172,
- * #1653). The directory is the only oracle for this, and it takes BOTH tests, not one.
- *
- * A fork is an archive or a preview of somebody else's data, and re-provisioning one
- * runs the vertical's install-side hook against a copy, minting a second set of whatever
- * it mints — or, since #1656, putting a copy of production on a sweeper that reaps and
- * assigns. But a CLEAN-ROOM preview (#509) is an empty scope with no source to copy, so
- * it carries `kind: 'preview'` and NO `forkedFrom` — the reap sweep keys on `kind` for
- * exactly that reason. Filtering on lineage alone would let those through, which is the
- * one shape of scope where the hook's effects are least wanted.
- */
-export function isPrimaryScope(scope) {
-    return !scope.forkedFrom && scope.kind !== 'preview';
-}
-/**
- * `isPrimaryScope` over a raw directory row, in the snake_case both adapters store (#2005) —
- * so a reader holding a row asks the same one rule rather than restating it. No row is not
- * primary: the answer that runs effects with platform authority is the one to be proven.
- */
-export function isPrimaryScopeRow(row) {
-    return row !== undefined && isPrimaryScope({ kind: row.kind ?? '', forkedFrom: row.forked_from });
-}
-/**
- * Why an effect a NON-primary scope asked for was settled without running (#2005). A fork,
- * a snapshot and a preview of either kind are inert: they cause no outbound effects, so
- * whatever they queue — a platform intent, an executor or connector delivery — is journaled
- * as not executed, with this reason, rather than left pending forever or run off a copy.
- * One string for every door, so a reader who has seen it once recognizes it everywhere.
- */
-export const INERT_SCOPE_REASON = 'not executed: this scope is a preview or a fork, and those cause no outbound effects';
-/**
- * The version whose code actually executes for `scope` (#1653) — which is not always the
- * one it is bound to.
- *
- * A scope on its vertical's stable serving script (`servingRef`, #286) runs whatever that
- * script serves, and a promote re-uploads the script in place: the code changes under
- * the scope at that moment, whatever its version pointer says. For a PRIVATE vertical
- * the promote moves the pointer too, so the two agree. For a LISTED one it does not —
- * the pointer is the tenant's, and moves only on their Update — so an install can run
- * version N+1 with its provision state still at N. Measuring against the running version
- * is what lets the reconcile follow the code instead of the pointer.
- *
- * Falls back to the bound version whenever the serving script cannot be named: a scope
- * with no `servingRef` (legacy per-version dispatch, where the bound version's own
- * script IS what runs), a vertical with nothing served in place yet, or a `servingRef`
- * that is not the vertical's current one. The fallback is exactly the pre-#1653 answer,
- * so an unknown never manufactures a reconcile.
- */
-export function runningVersionOf(scope, serving) {
-    if (scope.servingRef && serving && scope.servingRef === serving.ref)
-        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;
-}
 /**
  * #2185: the slots of a #1172 window owed to installs behind on their retirements alone: a quarter,
  * at least one. A window of one slot cannot be split, so it goes to them on a quarter of the passes.
@@ -247,6 +70,12 @@ export const STORAGE_SAMPLE_BATCH = 100;
 export const STORAGE_SAMPLE_MAX_AGE_MS = 86_400_000;
 /** How long one scope's store read may take before it counts as failed, by default (#2212). */
 export const STORE_READ_TIMEOUT_MS = 15_000;
+/** The orphan-attachment phase's per-pass bound when `batch` is unset (#2314). */
+export const ORPHAN_ATTACHMENT_SWEEP_BATCH = 25;
+/** How recent a scope's dry-run row must be before a pass deletes its bytes, by default (#2314). */
+export const ORPHAN_SWEEP_DRY_RUN_WINDOW_MS = 7 * 86_400_000;
+/** How many scope ids each standing-condition count of the report carries; the count stays exact. */
+const ORPHAN_ATTACHMENT_REPORTED_IDS = 50;
 /**
  * How many consumer scopes one pass of the cross-vertical phase visits, by default (#1705).
  *
@@ -257,20 +86,6 @@ export const STORE_READ_TIMEOUT_MS = 15_000;
  * makes none.
  */
 export const CROSS_VERTICAL_CONSUMERS_PER_PASS = 100;
-const message = (err) => (err instanceof Error ? err.message : String(err));
-/**
- * Run `fn` over `items` with at most `limit` in flight. `fn` owns its errors —
- * this never rejects, so one unit's failure cannot abort the pass.
- */
-async function mapBounded(items, limit, fn) {
-    let next = 0;
-    const workers = Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, async () => {
-        while (next < items.length) {
-            await fn(items[next++]);
-        }
-    });
-    await Promise.all(workers);
-}
 /**
  * One pass of the platform's scheduled work: drain every active scope's due
  * executor deliveries, then reconcile every live connection against its provider.
@@ -308,6 +123,13 @@ function assertSweepBatches(options) {
     if (gauge?.batch !== undefined && !(Number.isInteger(gauge.batch) && gauge.batch >= 0)) {
         throw substratError('validation_failed', `storageGauge.batch must be a non-negative integer, got ${String(gauge.batch)}`);
     }
+    const orphans = options.orphanAttachments;
+    if (orphans?.batch !== undefined && !(Number.isInteger(orphans.batch) && orphans.batch >= 0)) {
+        throw substratError('validation_failed', `orphanAttachments.batch must be a non-negative integer, got ${String(orphans.batch)}`);
+    }
+    if (orphans && orphans.mode !== 'dry-run' && orphans.mode !== 'delete') {
+        throw substratError('validation_failed', `orphanAttachments.mode must be 'dry-run' or 'delete', got ${String(orphans.mode)}`);
+    }
 }
 export async function runPlatformSweep(host, options) {
     assertSweepBatches(options);
@@ -330,6 +152,7 @@ export async function runPlatformSweep(host, options) {
         telemetry: null,
         findings: null,
         storage: null,
+        orphanAttachments: null,
         errors: [],
     };
     // -- migration reconciliation (kernel-design §5.3, #49) ---------------------
@@ -691,6 +514,13 @@ export async function runPlatformSweep(host, options) {
             });
         }
     }
+    // -- orphan attachment bytes (#2314) ------------------------------------------
+    // After the migration phase and skipping what failed there, like every phase that reaches a
+    // vertical. Opt-in, and its own window per pass: it lists a bucket prefix and wakes a scope.
+    if (options.orphanAttachments) {
+        const scopes = (await host.admin.listScopes(options.actor, { status: 'active' })).filter((s) => isPrimaryScope(s) && !failedThisPass.has(s.id));
+        report.orphanAttachments = await sweepOrphanAttachmentWindow(host, options, options.orphanAttachments, scopes, report);
+    }
     if (options.gcSnapshots !== false) {
         // Reap expired previews (§3/§9). Two shapes qualify, both throwaway-by-construction:
         // a FORK (`forkedFrom` set — a snapshot of another scope) and a clean-room PREVIEW
@@ -1124,40 +954,6 @@ export async function runCrossVerticalFrom(host, options, producer) {
  * 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));
-        }
-    });
-    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);
@@ -1191,338 +987,6 @@ export function registryImportCandidates(input) {
         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) {
-    const act = input.act ?? 'promotion';
-    // 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 ${act} 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', tenantId: input.tenantId })).filter((s) => isPrimaryScope(s) && s.vertical !== null);
-    // Narrowed to one tenant, every scope read is already in a tenant that runs the producer.
-    const installedIn = input.tenantId === undefined
-        ? new Set(scopes.filter((s) => s.vertical === input.producer).map((s) => s.tenantId))
-        : null;
-    const consumers = scopes.filter((s) => s.vertical !== input.producer && (installedIn?.has(s.tenantId) ?? true));
-    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 ${act} 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,
-            });
-        }
-    }
-    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. */
-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`);
-}
-/** How `bindExportBreakRefusal` begins: what lets the bind route recognise it (#1756). */
-export const BIND_EXPORT_BREAK_REFUSAL = 'this bind drops or re-versions';
-/** Whether a throw is the bind gate's export-break refusal (`bindExportBreakRefusal`). */
-export function isBindExportBreakRefusal(err) {
-    return errorCodeOf(err) === 'precondition_failed' && err instanceof Error && err.message.startsWith(BIND_EXPORT_BREAK_REFUSAL);
-}
-/**
- * The refusal a bind gets for a non-empty `bindExportBreaksOf` (#1756). Every break is in the
- * bound scope's own tenant, which the caller addressed, so it names no one else — but it stays in
- * counts, as the promote refusal does, and the route that knows the caller adds the listing.
- */
-export function bindExportBreakRefusal(breaks) {
-    const types = new Set(breaks.map((b) => b.type)).size;
-    const apps = new Set(breaks.map((b) => b.scopeId)).size;
-    return (`${BIND_EXPORT_BREAK_REFUSAL} ${types} exported event type(s) that ${apps} installed app(s) in ` +
-        `this tenant import — their edges would stop delivering it. Acknowledge it explicitly ` +
-        `(exportBreak) to bind, or bind a version that keeps the export`);
-}
-/**
- * What a bind or a route change moves `scope` between (#1756, #2178): the version it runs before
- * and the one it runs after (`runningVersionOf` on both of its inputs), or null when the move
- * changes nothing it runs — a re-point that stays on the serving script — or it ran nothing before
- * (a first bind). `servingRef` omitted: the route is unchanged.
- */
-export function scopeMoveOf(scope, incomingVersionId, servingRef, serving) {
-    const before = runningVersionOf(scope, serving);
-    const after = runningVersionOf({ verticalVersionId: incomingVersionId, servingRef: servingRef === undefined ? scope.servingRef : servingRef }, serving);
-    return before === null || after === null || before === after ? null : { before, after };
-}
-/**
- * #2178: the versions the active primary scopes of a vertical that a promote or a serve moves were
- * last provisioned against (`provisionedVersionId`, written only after a provision or reconcile
- * succeeds): those routed on a serving ref, and those of an owner tenant. A retirement reaches a
- * scope only at its reconcile, so a scope provisioned behind the retiring version still holds the
- * keys. #2185: and whether that reconcile FINISHED the version's retirements
- * (`retirementsFinishedVersionId` equal to the receipt), since one that left a retirement open still
- * writes the receipt. One row per (version, finished), with how many installs and one of them to
- * name, however many installs there are. Installs with NO receipt are a row too (`version_id` null):
- * a switch clears the receipt (#2045), a rewind and a restore do (#2185), and a new install has none until its first
- * reconcile. The sweep reconciles every unfinished or receiptless install on its next pass, so a
- * refusal they cause is transient unless that reconcile keeps failing, answers 'unsupported', or
- * cannot report its retirements (an `adapter-cloudflare` or `vertical-host` that predates the report). Binds
- * `(vertical, servingRef, ownerTenant)`; a null matches nothing. The directory has no index on
- * `vertical`, so this scans its scopes table: once per promote or serve.
- *
- * #2184: and which binding shapes the reconcile reported the installs have bound through a link
- * (`bound_shapes`, JSON `{version, types}`), counted only while its version is the receipt's, else
- * null (unknown). Grouped by it too: each set is a subset of one version's table-held bootstrap
- * shapes, sorted, so a fleet of one vertical has a handful.
- *
- * Review of #2220: and by the version each install RUNS (`runningVersionOf`: the served version on
- * the serving script, else its pointer), since a receipt behind it speaks for neither the bindings
- * nor the retirements of what it runs now. Bind its parameters with {@link provisionedVersionsParams}.
- *
- * So the rows are at most (receipt versions × running versions × 2 × distinct type sets), still
- * independent of how many installs there are.
- */
-export const PROVISIONED_VERSIONS_SQL = `SELECT provisioned_version_id AS version_id,
-    CASE WHEN serving_ref = ? THEN ? ELSE vertical_version_id END AS running_version_id,
-    COALESCE(retirements_finished_version_id = provisioned_version_id, 0) AS finished,
-    CASE WHEN json_extract(bound_shapes, '$.version') = provisioned_version_id
-      THEN json_extract(bound_shapes, '$.types') END AS bound_types,
-    COUNT(*) AS installs, MIN(scope_id) AS example
-  FROM scopes
-  WHERE vertical = ? AND status = 'active' AND forked_from IS NULL AND COALESCE(kind, '') != 'preview'
-    AND (serving_ref = ? OR tenant_id = ?)
-  GROUP BY provisioned_version_id, running_version_id, finished, bound_types`;
-/**
- * `PROVISIONED_VERSIONS_SQL`'s parameters: the installs of `vertical` on `serving`'s script (which
- * run its version) or owned by `ownerTenant`. Null for either matches nothing.
- */
-export function provisionedVersionsParams(vertical, serving, ownerTenant) {
-    return [serving?.ref ?? null, serving?.versionId ?? null, vertical, serving?.ref ?? null, ownerTenant];
-}
-/**
- * #2184: the directory's `bound_shapes` value — the version the reconcile ran against and the types
- * it reported bound, as one JSON value, so the pair is written and cleared together and a receipt
- * rewritten without it (a control plane that predates the column) reads as unknown. Null when
- * there is no receipt or the outcome does not say.
- */
-export function boundShapesColumn(versionId, types) {
-    return versionId !== null && types ? JSON.stringify({ version: versionId, types: [...new Set(types)].sort() }) : null;
-}
-/** #2184: `Scope.boundShapes` from the directory's `bound_shapes` value; null for null or anything unreadable. */
-export function boundShapesOfColumn(raw) {
-    if (!raw)
-        return null;
-    try {
-        const v = JSON.parse(raw);
-        const ok = typeof v.version === 'string' && Array.isArray(v.types) && v.types.every((t) => typeof t === 'string');
-        return ok ? { versionId: v.version, types: v.types } : null;
-    }
-    catch {
-        return null;
-    }
-}
-/** `PROVISIONED_VERSIONS_SQL`'s rows, as either adapter's driver returns them. */
-export function installsReconciledOf(rows) {
-    return rows.map((r) => ({
-        versionId: r.version_id == null ? null : String(r.version_id),
-        runningVersionId: r.running_version_id == null ? null : String(r.running_version_id),
-        retirementsFinished: Number(r.finished) === 1,
-        boundShapes: r.bound_types == null ? null : JSON.parse(String(r.bound_types)),
-        installs: Number(r.installs),
-        example: String(r.example),
-    }));
-}
-/**
- * #2185: one install's own receipt as a {@link InstallsReconciled} group, for a bind or a route of
- * that install, judged by the same rule as the promote's `PROVISIONED_VERSIONS_SQL` rows, with the
- * version it runs before the move (`scopeMoveOf`'s `before`).
- */
-export function installReconciled(scope, runningVersionId) {
-    const versionId = scope.provisionedVersionId;
-    return {
-        versionId,
-        runningVersionId,
-        retirementsFinished: versionId !== null && scope.retirementsFinishedVersionId === versionId,
-        boundShapes: versionId !== null && scope.boundShapes?.versionId === versionId ? scope.boundShapes.types : null,
-        installs: 1,
-        example: scope.id,
-    };
-}
-/**
- * #2184: what the gate counts as bound for a group: the types its reconcile reported, or every
- * table-held bootstrap shape (`'unknown'`) when it did not, or when the group has no receipt.
- */
-export function boundEverOf(g) {
-    return g.versionId !== null && g.boundShapes !== null ? g.boundShapes : 'unknown';
-}
-/** Review of #2220: whether a group's receipt is behind the version its installs run. */
-const receiptLags = (g) => g.versionId !== null && g.runningVersionId !== null && g.runningVersionId !== g.versionId;
-/**
- * What the binding-shape gate judges a move onto `afterId` from, for one group of installs, given
- * the versions the move leaves (`froms`). One rule for both adapters' doors:
- *
- * - no receipt: every one of `froms`, as if nothing about it had run or been reported (the installs
- *   run one of them; judging the others too can only over-refuse, and only while it lasts);
- * - a receipt behind the version they run (review of #2220): that running version the same way,
- *   since whatever it bound or retired since the receipt is not in it — a version that added `bind`
- *   may have reconciled and been claimed through without its receipt landing;
- * - a receipt: its own version, from its own report (#2185, #2184).
- *
- * Each is transient: the sweep reconciles every such install on its next pass.
- */
-export function strandJudgmentsOf(g, froms, afterId) {
-    const judgedFrom = installsReconciledNote(g);
-    const unreported = { judgedFrom, retiredStillHeld: true, boundEver: 'unknown' };
-    if (g.versionId === null)
-        return froms.filter((f) => f !== afterId).map((from) => ({ from, opts: unreported }));
-    const out = [];
-    if (receiptLags(g) && g.runningVersionId !== afterId)
-        out.push({ from: g.runningVersionId, opts: unreported });
-    if (g.versionId !== afterId) {
-        out.push({ from: g.versionId, opts: { judgedFrom, retiredStillHeld: !g.retirementsFinished, boundEver: boundEverOf(g) } });
-    }
-    return out;
-}
-/** What a refusal judged from installs' receipts says it was judged from. */
-export function installsReconciledNote(g) {
-    // #2184: the types a link has bound people to, where the reconcile reported any.
-    const bound = g.versionId !== null && g.boundShapes?.length ? `, where links have bound people to ${g.boundShapes.join(', ')}` : '';
-    const unfinished = g.versionId !== null && !g.retirementsFinished;
-    const unknown = g.versionId !== null && g.boundShapes === null;
-    // Review of #2220: a receipt behind what they run speaks for none of it.
-    const lags = receiptLags(g)
-        ? `, and run ${g.runningVersionId}, which that receipt does not speak for: every bootstrap shape of ${g.runningVersionId} ` +
-            'with a table holder counts as bound and its retirements as not run'
-        : '';
-    if (unfinished || unknown) {
-        const gaps = [unfinished && 'with its retirements not finished', unknown && 'without reporting which binding shapes links have bound'];
-        const waits = [unfinished && 'their retirements to finish', unknown && 'their report'];
-        const report = unfinished && unknown ? 'retirement and binding reports (#2185, #2184)' : unfinished ? 'retirement report (#2185)' : 'binding report (#2184)';
-        return (`${g.installs} install(s) that reconciled ${g.versionId} ${gaps.filter(Boolean).join(' and ')}${bound} (one is ${g.example})${lags}` +
-            (unknown ? `, so every bootstrap shape of ${g.versionId} with a table holder counts as bound` : '') +
-            `; the drop waits for ${waits.filter(Boolean).join(' and ')}: the sweep reconciles them again each pass. ` +
-            "An install whose vertical's @substrat-run/adapter-cloudflare or @substrat-run/vertical-host predates the " +
-            `${report} stays here: push a version built on current releases of both packages`);
-    }
-    const which = g.versionId === null ? 'with no reconcile receipt (a switch, a rewind or a restore cleared it, or none was written yet)' : `that last reconciled ${g.versionId}${bound}`;
-    return (`${g.installs} install(s) ${which} (one is ${g.example})${lags}; the drop waits for their reconcile. ` +
-        "If that install's reconcile keeps failing or answers 'unsupported' (a vertical built on a vertical-host " +
-        'that cannot reconcile), no sweep writes its receipt: fix the reconcile or push a version built on a ' +
-        'current vertical-host, so the retirement reaches it');
-}
-/**
- * Whom moving `scope` breaks (#1756): the promote gate's question (`exportBreaksOf`), asked of
- * ONE install in its own tenant, since an edge never crosses one.
- *
- * A scope's exports leave from the code it RUNS, and `runningVersionOf` names that code from two
- * inputs: the version pointer and the serving ref. So a move is either or both of them changing —
- * a bind (`next.versionId`), or a route onto or off a serving script (`next.servingRef`, which is
- * how an adopt moves a scope before its pointer ever does). Both are judged by the same rule, on
- * the running version before against the running version after, the rule the consumers are judged
- * on too:
- *
- * - **Re-pointing a scope that stays on its vertical's serving script** changes nothing it runs,
- *   so it is never refused. The change reached it when the serving script was replaced — at a
- *   promote, which judged every tenant then. A route ONTO the serving script is not that case:
- *   the scope goes from its own version to whatever is served, and that is judged.
- * - **A fork or a preview** is never an edge's producer (`resolveVerticalInstanceFrom` takes the
- *   primary install only), so nothing it runs can break an edge.
- * - **A scope still provisioning** has never been active, so no edge has ever delivered from it.
- * - **A first bind** runs nothing before it, so it promised nothing.
- * - **A lineage crossing** (the version belongs to another vertical than the scope's, or the route
- *   goes onto a script that is not this vertical's serving script) is not judged here, and nothing
- *   else judges it either: every consumer importing `from` the old slug
- *   loses its producer, and `rebind-vertical`'s acknowledgements are about migrations, not about
- *   that. A known gap, older than this gate.
- */
-export async function bindExportBreaksOf(input) {
-    const { scope } = input;
-    if (!isPrimaryScope(scope) || scope.status === 'provisioning')
-        return [];
-    if (scope.vertical === null || scope.vertical !== input.incoming.verticalSlug)
-        return [];
-    // A route onto a script that is not this vertical's serving script is a lineage crossing (or a
-    // ref this host cannot name), and what the scope runs there is not this vertical's code at all:
-    // the same known gap as above, never a phantom move judged against the wrong vertical.
-    if (typeof input.servingRef === 'string' && input.servingRef !== input.serving?.ref)
-        return [];
-    const move = scopeMoveOf(scope, input.incoming.id, input.servingRef, input.serving);
-    if (move === null)
-        return [];
-    const [outgoing, incoming] = await Promise.all([input.readExports(move.before), input.readExports(move.after)]);
-    return exportBreaksOf({
-        admin: input.admin,
-        actor: input.actor,
-        producer: scope.vertical,
-        outgoing,
-        incoming,
-        readImports: input.readImports,
-        tenantId: scope.tenantId,
-        act: 'bind',
-    });
-}
 /** A tenant read with names matched exactly — the edges' rule (see `edgeEnds`). */
 const exactIn = (id) => ({ id, slug: null });
 /**
@@ -2116,4 +1580,113 @@ async function sweepStorageGauge(admin, options, gauge, reachedThisPass, report)
     }
     return out;
 }
+const pushCapped = (bucket, id) => {
+    bucket.count += 1;
+    if (bucket.scopeIds.length < ORPHAN_ATTACHMENT_REPORTED_IDS)
+        bucket.scopeIds.push(id);
+};
+/**
+ * Whether the admin log holds a dry-run row for the scope from within the window: the licence for
+ * a destructive pass (`OrphanAttachmentSweepOptions`). A delete row in the same window is not one.
+ *
+ * One read per visited scope, in delete mode only, and on a host that records directory reads it is
+ * one more access-log row each (K-24): at the default batch and a 15-minute cron, 2,400 a day. The
+ * control plane's reach already reads the scope, its tenant, and its serving pointer or its bound
+ * version per visit, which is three such rows, so this adds a quarter. It stays an audited
+ * read on purpose: a quiet read of the admin log would be the one platform read K-24 does not see.
+ * One read per pass for the whole window is not cheaper, since a row carries up to the pass's limit
+ * of keys and the window holds a week of them.
+ */
+async function hasRecentDryRun(host, actor, scope, since) {
+    const rows = await host.admin.auditLog(actor, {
+        tenantId: scope.tenantId,
+        scopeId: scope.id,
+        action: 'sweepOrphanAttachments',
+        since,
+        order: 'desc',
+        limit: 100,
+    });
+    return rows.some((r) => r.after?.dryRun === true);
+}
+/** The orphan-attachment phase (#2314): one window of scopes, each swept where it is served. */
+async function sweepOrphanAttachmentWindow(host, options, phase, scopes, report) {
+    const batch = phase.batch ?? ORPHAN_ATTACHMENT_SWEEP_BATCH;
+    const out = {
+        mode: phase.mode,
+        eligible: scopes.length,
+        visited: 0,
+        deferred: 0,
+        dryRuns: 0,
+        deletes: 0,
+        awaitingDryRun: 0,
+        noStore: { count: 0, scopeIds: [] },
+        fenced: 0,
+        orphans: 0,
+        deleted: 0,
+        refused: { count: 0, scopeIds: [] },
+        unsupported: { count: 0, scopeIds: [] },
+    };
+    const window = reconcileWindow(scopes, batch, phase.rng ?? Math.random);
+    out.visited = window.length;
+    out.deferred = scopes.length - window.length;
+    const nowMs = Date.parse(phase.now?.() ?? new Date().toISOString());
+    const since = new Date(nowMs - (phase.dryRunWindowMs ?? ORPHAN_SWEEP_DRY_RUN_WINDOW_MS)).toISOString();
+    await mapBounded(window, options.concurrency ?? 8, async (s) => {
+        try {
+            let dryRun = true;
+            if (phase.mode === 'delete') {
+                dryRun = !(await hasRecentDryRun(host, options.actor, s, since));
+                if (dryRun)
+                    out.awaitingDryRun += 1;
+            }
+            const outcome = await phase.sweepScopeFn(s.tenantId, s.id, { dryRun });
+            if ('refused' in outcome)
+                return pushCapped(out.refused, s.id);
+            if ('unsupported' in outcome)
+                return pushCapped(out.unsupported, s.id);
+            const r = outcome.swept;
+            // The deployment's word on what it did, never the mode asked for: a deployment that ignored
+            // the flag is reported as what it was.
+            if (r.dryRun)
+                out.dryRuns += 1;
+            else
+                out.deletes += 1;
+            if (r.bucket === 'none')
+                pushCapped(out.noStore, s.id);
+            if (r.fencedUntil !== undefined)
+                out.fenced += 1;
+            out.orphans += r.orphans;
+            out.deleted += r.deleted;
+            if (r.orphans > 0 || r.deleted > 0) {
+                const entry = {
+                    tenantId: s.tenantId,
+                    scopeId: s.id,
+                    dryRun: r.dryRun,
+                    listed: r.listed,
+                    candidates: r.candidates,
+                    orphans: r.orphans,
+                    deleted: r.deleted,
+                    keys: r.keys,
+                    ...(r.fencedUntil !== undefined ? { fencedUntil: r.fencedUntil } : {}),
+                };
+                try {
+                    await host.admin.recordOrphanSweep(options.actor, entry);
+                }
+                catch (err) {
+                    // The bytes are already gone when a real pass deleted any: this line is then the only
+                    // record of which ones, so it carries the whole entry, keys and all, before the error.
+                    if (r.deleted > 0) {
+                        console.error(`orphan-attachment sweep: deleted ${r.deleted} object(s) but the admin-log row was not written: ${JSON.stringify(entry)}`);
+                    }
+                    throw new Error(`the admin-log row was not written (${message(err)})` +
+                        (r.deleted > 0 ? `; ${r.deleted} object(s) were deleted, and the log line names them` : ''));
+                }
+            }
+        }
+        catch (err) {
+            report.errors.push({ kind: 'attachment-sweep', id: s.id, error: message(err) });
+        }
+    });
+    return out;
+}
 //# sourceMappingURL=platform-sweep.js.map