@substrat-run/control-plane-api 0.159.0 → 0.161.0

package/dist/vertical-client.js

@@ -1,6 +1,6 @@
 import { z } from '@substrat-run/contracts';
-import { PREVIEW_CLIENT_PATH, attachmentRecord, projectedConnectionGrant, denialFilterParams, capabilityFilterParams, capabilityPage, capabilityRevokeAnswer, capabilityRevokeRequest, mintedPreviewClient, ownerSeat, ownerClaimLink, memberInviteLink, memberRemoval, scopeMembers, ownerTransferResult, previewClientClaim, retiredPreviewClients, peerGrantsEntry, peerSwitchOutcome, systemSwitchOutcome, lifecycleDelivery, systemScheduleEntry, switchedOffInUnit, exportedBatch, importResult, importCursorMoved, importState, substratError, CONNECTOR_ATTACHMENT_RECORD_HEADER, LOAD_STAMP_HEADER, PLATFORM_SECRET_HEADER, WRITE_REVISION_HEADER, mergeDumpPages, scopeDumpPage, } from '@substrat-run/contracts';
-import { ulid, undrainedEventsOf } from '@substrat-run/kernel';
+import { PREVIEW_CLIENT_PATH, attachmentRecord, projectedConnectionGrant, denialFilterParams, capabilityFilterParams, capabilityPage, capabilityRevokeAnswer, capabilityRevokeRequest, mintedPreviewClient, ownerSeat, ownerClaimLink, memberInviteLink, memberRemoval, scopeMembers, ownerTransferResult, previewClientClaim, retiredPreviewClients, peerGrantsEntry, peerSwitchOutcome, systemSwitchOutcome, lifecycleDelivery, systemScheduleEntry, switchedOffInUnit, exportedBatch, importResult, importCursorMoved, importState, substratError, CONNECTOR_ATTACHMENT_META_HEADER, CONNECTOR_ATTACHMENT_META_MAX_BYTES, CONNECTOR_ATTACHMENT_BUFFERED_MAX_BYTES, CONNECTOR_ATTACHMENT_STREAM_MAX_BYTES, connectorAttachmentMetaBytes, connectorAttachmentMetaRefusal, connectorAttachmentBufferedRefusal, connectorAttachmentSizeRefusal, CONNECTOR_ATTACHMENT_RECORD_HEADER, LOAD_STAMP_HEADER, PLATFORM_SECRET_HEADER, WRITE_REVISION_HEADER, mergeDumpPages, scopeDumpPage, } from '@substrat-run/contracts';
+import { STREAM_IDLE_TIMEOUT_MS, STREAM_MAX_DURATION_MS, attachmentSha256, deadlineFetch, isSizedByteStream, knownLengthInit, runtimeSha256, scopeNotHeldRefusal, ulid, undrainedEventsOf, verifiedStream } from '@substrat-run/kernel';
 import { ControlPlaneError } from '@substrat-run/control-plane-client';
 /**
  * A 404 the vertical's router answered because it has no such route: a non-empty body that is
@@ -19,6 +19,116 @@ export function isRouteMiss(err) {
         return true;
     }
 }
+/**
+ * The 409 a deployment answers a size read for a scope it does not hold (#2541): never provisioned
+ * there, reaped, or carried away. Told by its sentence (`scopeNotHeldRefusal`) as well as its status,
+ * since a 409 on the same route could be any other conflict. Whether that is benign is
+ * `notHeldIsBenign`'s question, asked of the directory.
+ */
+export function isScopeNotHeld(err, scopeId) {
+    return err instanceof ControlPlaneError && err.status === 409 && err.message.includes(scopeNotHeldRefusal(scopeId));
+}
+/**
+ * Whether a deployment's "not held" answer is expected, judged against the directory's record read
+ * NOW (#2541): the scope was reaped (or archived) since it was listed, or the directory has no such
+ * scope. Every other status (`provisioning`, `active`, `suspended`, `archiving`) holds a store, so
+ * "not held" there is a real fault and the caller keeps it an error. ONE rule for the storage
+ * gauge (skip) and the on-demand console page (read 0).
+ *
+ * `record` is not caught: a directory read that FAILS rejects here, so the failure is reported
+ * instead of being taken for a gone scope.
+ */
+export async function notHeldIsBenign(record) {
+    const found = await record();
+    return found === undefined || found.status === 'reaped' || found.status === 'archived';
+}
+/**
+ * The record an attachment read's response carries in its header (#711), parsed, not cast: it holds
+ * the sha256 the bytes are checked against, and a shape this side invented would witness nothing.
+ */
+function attachmentRecordOf(res) {
+    const raw = res.headers.get(CONNECTOR_ATTACHMENT_RECORD_HEADER);
+    if (!raw) {
+        throw new Error(`connector-attachment-open: the vertical answered ${res.status} with no ` +
+            `${CONNECTOR_ATTACHMENT_RECORD_HEADER} header — the bytes cannot be trusted without ` +
+            `the record that witnesses them (#711)`);
+    }
+    return attachmentRecord.parse(JSON.parse(raw));
+}
+/** How a refusal of an attachment read ends: what the caller holds of the file when it is thrown (#2514). */
+const NOTHING_READ = 'Nothing was read.';
+/**
+ * A streamed read's refusal can land after most of the file has been handed on: every chunk but the
+ * held-back last one. So it says what those bytes are, and what to do with them, never "nothing".
+ */
+export const STREAMED_ATTACHMENT_UNVERIFIED = 'The bytes delivered before this error are a prefix of an unverified file: discard them, and undo anything written from them.';
+/** An attachment read whose bytes are not the ones its record names (#2514): the deployment's fault. */
+function attachmentIntegrity(record, why, cause, tail = NOTHING_READ) {
+    return new ControlPlaneError(502, `connector-attachment-open: attachment ${record.id} failed its integrity check: ${why} (#2514). ${tail}`, undefined, { code: 'internal', ...(cause !== undefined ? { cause } : {}) });
+}
+/** A `deadlineFetch` bound ran out (#2514): the deployment was slow, which is retryable, never an integrity fault. */
+const isTimeout = (err) => err?.name === 'TimeoutError';
+/** The deployment too slow to answer an attachment read (#2514): a 504, `unavailable`, retryable. */
+function attachmentTimeout(what, err, tail) {
+    const message = err instanceof Error ? err.message : String(err);
+    return new ControlPlaneError(504, `connector-attachment-open: ${what} timed out: ${message} (#2514). ${tail}`, undefined, { code: 'unavailable', cause: err });
+}
+/**
+ * What a streamed attachment read's error becomes (#2514). A bound running out is a 504; anything
+ * else, a body that broke off or bytes that did not match, is the integrity refusal the buffered read
+ * gives. Both end in {@link STREAMED_ATTACHMENT_UNVERIFIED}: by the time they land, the caller may hold
+ * all but the last chunk.
+ */
+function streamRefusal(record, err) {
+    if (err instanceof ControlPlaneError)
+        return err;
+    if (isTimeout(err))
+        return attachmentTimeout(`reading attachment ${record.id}`, err, STREAMED_ATTACHMENT_UNVERIFIED);
+    return attachmentIntegrity(record, err instanceof Error ? err.message : String(err), err, STREAMED_ATTACHMENT_UNVERIFIED);
+}
+/** The longest any one bound of a streamed attachment read may be set to (#2514): an hour. */
+const ATTACHMENT_STREAM_BOUND_MAX_MS = 60 * 60_000;
+/**
+ * `VerticalClientOptions.attachmentStream`'s bounds, with the defaults filled in and each held to a
+ * whole number of milliseconds in (0, an hour] (#2514). Zero, a negative, NaN or Infinity would end
+ * every read at once or never, so it is refused in words instead.
+ */
+function attachmentStreamBounds(given) {
+    const bounds = {
+        timeoutMs: given?.timeoutMs ?? STREAM_IDLE_TIMEOUT_MS,
+        idleMs: given?.idleMs ?? STREAM_IDLE_TIMEOUT_MS,
+        maxStreamMs: given?.maxStreamMs ?? STREAM_MAX_DURATION_MS,
+    };
+    for (const [name, ms] of Object.entries(bounds)) {
+        if (!Number.isSafeInteger(ms) || ms <= 0 || ms > ATTACHMENT_STREAM_BOUND_MAX_MS) {
+            throw new ControlPlaneError(500, `VerticalClientOptions.attachmentStream.${name} must be a whole number of milliseconds from 1 to ` +
+                `${ATTACHMENT_STREAM_BOUND_MAX_MS}, not ${ms}`);
+        }
+    }
+    return { ...bounds, ...(given?.timers ? { timers: given.timers } : {}) };
+}
+/**
+ * `source`, passed through chunk by chunk with its errors made `classify(err)`. Pull-driven with no
+ * queue of its own, as every relay on this path is, so it holds at most the chunk in flight.
+ */
+function classifiedStream(source, classify) {
+    const reader = source.getReader();
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                const { done, value } = await reader.read();
+                if (done)
+                    controller.close();
+                else
+                    controller.enqueue(value);
+            }
+            catch (err) {
+                controller.error(classify(err));
+            }
+        },
+        cancel: (reason) => reader.cancel(reason),
+    }, { highWaterMark: 0 });
+}
 /** The orphan-attachment report as it crosses the wire (#2314): `OrphanSweepReport`, checked. */
 const orphanSweepReportWire = z.object({
     listed: z.number().int().nonnegative(),
@@ -31,6 +141,14 @@ const orphanSweepReportWire = z.object({
     bucket: z.literal('none').optional(),
     consumeFailed: z.literal(true).optional(),
 });
+/** #2446: a scope's role state as it crosses the wire (`RoleState`), checked. */
+const roleShapeWire = z.object({ key: z.string().min(1), permissions: z.array(z.string()), holder: z.enum(['person', 'system']).optional() });
+const roleStateWire = z.object({
+    roles: z.array(roleShapeWire),
+    seated: z.array(z.string()),
+    /** #2531: the tombstones of the roles a projection dropped. Absent from a deployment that predates them. */
+    dropped: z.array(roleShapeWire).optional(),
+});
 /** `routeAnswer`'s word for a deployment that predates the route it was asked (#1722, #2010). */
 const PREDATES = Symbol('predates');
 /** #1722's kept-copy and fenced-wipe verbs: a host without the method answers a 501. */
@@ -265,12 +383,29 @@ export class VerticalClient {
     async listScopeTables(scopeId) {
         return this.getInternal(`/internal/tables?scopeId=${encodeURIComponent(scopeId)}`);
     }
-    /** A bounded page of one of the scope's tables. */
+    /**
+     * A bounded page of one of the scope's tables, for the Data view (#2563). Sends `held=1`: a
+     * deployment that does not hold the scope refuses it (409, `scopeNotHeldRefusal`) instead of
+     * answering an empty store. A vertical deployed before the flag ignores it and answers as it
+     * always did.
+     */
     async readScopeTable(scopeId, input) {
+        return this.tablePage(scopeId, input, true);
+    }
+    /**
+     * A table of a store the deployment may no longer hold, for the carry and its cleanup, which ask
+     * a wiped copy whether it carries the `carried_away` tombstone (#2563). Sends no `held` flag, so
+     * a wiped copy answers. Nothing that shows a person data calls this: `readScopeTable` does.
+     */
+    async readTombstoneTable(scopeId, input) {
+        return this.tablePage(scopeId, input, false);
+    }
+    async tablePage(scopeId, input, held) {
         const q = new URLSearchParams({
             scopeId,
             limit: String(input.limit),
             offset: String(input.offset),
+            ...(held ? { held: '1' } : {}),
         });
         return this.getInternal(`/internal/tables/${encodeURIComponent(input.table)}?${q}`);
     }
@@ -430,11 +565,24 @@ export class VerticalClient {
      * Land provider bytes in the vertical's deployment as a CONNECTION (#574) — the bytes
      * leg (a sealed signed PDF cannot ride the JSON invoke). Multipart: `meta` carries the
      * JSON envelope, `body` the blob; fetch stamps the boundary content-type itself.
+     *
+     * A streamed body (#2498) goes to `/internal/connector-attachment-stream` instead, so it is
+     * never held here. A buffer keeps the multipart route, which every deployment has.
      */
     async connectorUploadAttachment(input) {
         const { body, ...meta } = input;
+        if (isSizedByteStream(body))
+            return this.connectorStreamAttachment(meta, body);
+        const metaJson = JSON.stringify(meta);
+        // The buffer is already held, so its length is known and the route's buffered bound is judged
+        // here, before it is copied into a form (#2538). This covers the typed inputs only: the route
+        // judges the bytes that arrive, so a caller that does not go through this client meets it there.
+        this.assertWithinAttachmentBounds('connector-attachment', connectorAttachmentMetaBytes(metaJson), {
+            length: body.byteLength,
+            held: 'buffered',
+        });
         const form = new FormData();
-        form.append('meta', JSON.stringify(meta));
+        form.append('meta', metaJson);
         form.append('body', new Blob([body], { type: input.contentType }), input.filename);
         const base = this.options.baseUrl ?? 'https://vertical.invalid';
         const res = await this.reach('connector-attachment', () => this.options.fetch(`${base}/internal/connector-attachment`, {
@@ -447,6 +595,66 @@ export class VerticalClient {
             throw await this.refusal('connector-attachment', res);
         return this.parseInternal('connector-attachment', '/internal/connector-attachment', res);
     }
+    /**
+     * Hold an upload to the bounds the far end holds it to (#2516), so it is refused here, with
+     * nothing sent, in the words the route would use. `body` is its length and how it is held: a
+     * buffered one is judged against the buffered bound, a streamed one against the stream bound.
+     */
+    assertWithinAttachmentBounds(verb, metaBytes, body) {
+        if (metaBytes > CONNECTOR_ATTACHMENT_META_MAX_BYTES) {
+            throw new ControlPlaneError(400, `${verb}: ${connectorAttachmentMetaRefusal(metaBytes)}. Nothing was sent.`);
+        }
+        if (body?.held === 'buffered' && body.length > CONNECTOR_ATTACHMENT_BUFFERED_MAX_BYTES) {
+            throw new ControlPlaneError(413, `${verb}: ${connectorAttachmentBufferedRefusal(body.length)}. Nothing was sent.`);
+        }
+        if (body?.held === 'streamed' && body.length > CONNECTOR_ATTACHMENT_STREAM_MAX_BYTES) {
+            throw new ControlPlaneError(413, `${verb}: ${connectorAttachmentSizeRefusal(body.length)}. Nothing was sent.`);
+        }
+    }
+    /**
+     * The bytes leg for a streamed body (#2498): the request body IS the file, sent at its
+     * declared length as it is read, and the metadata rides `CONNECTOR_ATTACHMENT_META_HEADER`.
+     * Its own route rather than a second shape on the multipart one, so a deployment that
+     * predates it answers a route miss, and that becomes a 501 saying to re-push it, rather than
+     * an error from a parser that was handed a file.
+     */
+    async connectorStreamAttachment(meta, body) {
+        const verb = 'connector-attachment-stream';
+        const path = '/internal/connector-attachment-stream';
+        const base = this.options.baseUrl ?? 'https://vertical.invalid';
+        // The metadata is the only header a caller's strings reach. Its characters are always safe:
+        // JSON escapes a control character or a lone surrogate, and URI encoding everything else.
+        // Its SIZE is not, since it grows with the filename, so it is held to a named bound here and
+        // refused before a byte is sent rather than answered with a server's bare 431. (The multipart
+        // route is held to the same bound, #2516.) The file's own type rides inside it (the route
+        // reads `contentType` from there), so the request's own
+        // `content-type` is the plain octet-stream it is.
+        // Counted without `size`, as the multipart route's `meta` is, so one name passes or fails alike.
+        this.assertWithinAttachmentBounds(verb, connectorAttachmentMetaBytes(JSON.stringify(meta)), {
+            length: body.length,
+            held: 'streamed',
+        });
+        const encodedMeta = encodeURIComponent(JSON.stringify({ ...meta, size: body.length }));
+        const init = knownLengthInit({
+            method: 'POST',
+            headers: {
+                'content-type': 'application/octet-stream',
+                [PLATFORM_SECRET_HEADER]: this.options.platformSecret,
+                [CONNECTOR_ATTACHMENT_META_HEADER]: encodedMeta,
+            },
+            body,
+        });
+        const res = await this.reach(verb, () => this.options.fetch(`${base}${path}`, init));
+        if (!res.ok) {
+            const refused = await this.refusal(verb, res);
+            if (isRouteMiss(refused)) {
+                throw new ControlPlaneError(501, `the deployment serving scope ${meta.scopeId} predates streamed connector uploads (#2498) — ` +
+                    `re-push the deployment, then retry. Nothing was stored.`);
+            }
+            throw refused;
+        }
+        return this.parseInternal(verb, path, res);
+    }
     /**
      * Fetch ONE attachment's bytes back OUT of the vertical's deployment as a CONNECTION
      * (#711) — the outbound leg. The platform runs the vertical's signing connector and
@@ -459,37 +667,132 @@ export class VerticalClient {
      * own document rather than failing a dispatch; a refusal is still a throw.
      */
     async connectorOpenAttachment(input) {
-        const q = new URLSearchParams({
-            connectionId: input.connectionId,
-            tenantId: input.tenantId,
-            scopeId: input.scopeId,
-            ...(input.eventId ? { eventId: input.eventId } : {}),
-        });
-        const base = this.options.baseUrl ?? 'https://vertical.invalid';
-        const path = `/internal/connector-attachment/${encodeURIComponent(input.attachmentId)}`;
-        const res = await this.reach('connector-attachment-open', () => this.options.fetch(`${base}${path}?${q}`, {
+        const res = await this.reach('connector-attachment-open', () => this.options.fetch(this.attachmentReadUrl(input), {
             headers: { [PLATFORM_SECRET_HEADER]: this.options.platformSecret },
         }));
         if (res.status === 404)
             return null;
         if (!res.ok)
             throw await this.refusal('connector-attachment-open', res);
-        const raw = res.headers.get(CONNECTOR_ATTACHMENT_RECORD_HEADER);
-        if (!raw) {
-            throw new Error(`connector-attachment-open: the vertical answered ${res.status} with no ` +
-                `${CONNECTOR_ATTACHMENT_RECORD_HEADER} header — the bytes cannot be trusted without ` +
-                `the record that witnesses them (#711)`);
+        const record = attachmentRecordOf(res);
+        // Held to that record here too (#2514). A deployment that streams the read sends its 200 before
+        // the digest is known and cuts the body when the bytes do not match, so a broken body is the
+        // integrity refusal, not a network fault, and is classified as one. The length and the digest are
+        // checked again on the whole body, so no transport's handling of a short body is the only guard.
+        let body;
+        try {
+            body = new Uint8Array(await res.arrayBuffer());
+        }
+        catch (e) {
+            throw attachmentIntegrity(record, `its body broke off before the ${record.size} bytes its record names arrived`, e);
+        }
+        if (body.byteLength !== record.size) {
+            throw attachmentIntegrity(record, `the deployment sent ${body.byteLength} bytes; its record names ${record.size}`);
+        }
+        if ((await attachmentSha256(body)) !== record.sha256) {
+            throw attachmentIntegrity(record, 'the bytes do not match the recorded sha256');
         }
-        // Parsed, not cast: the record carries the sha256 the bytes are checked against at
-        // the far end, and a shape this side invented would witness nothing.
-        const record = attachmentRecord.parse(JSON.parse(raw));
-        const body = new Uint8Array(await res.arrayBuffer());
         return {
             record,
             body,
-            contentType: res.headers.get('content-type') ?? record.contentType,
+            // The record's, not the response's: the response header carries a type only when the
+            // stored one is header-safe (#2519), and the record is the exact stored value.
+            contentType: record.contentType,
         };
     }
+    /**
+     * `connectorOpenAttachment`, with the bytes as a stream read off the response as the caller reads
+     * it, never held here (#2514). The same route, the same `null` for an unknown id, the same refusals
+     * before the first byte. A deployment that predates streamed reads answers the same route in full;
+     * the bytes are still handed on as they arrive.
+     *
+     * - **Integrity.** The stream is held to the record in the response header: its `size`, and its
+     *   sha256, checked as the bytes pass, with the chunk that completes the file held back until the
+     *   digest matches. A body that breaks off (how a streaming deployment refuses bytes that do not
+     *   match), runs short or long, or does not match, errors the stream with a `ControlPlaneError` 502,
+     *   code `internal`, as the buffered read refuses it. A consumer that has received all `size` bytes
+     *   has received the bytes the record names.
+     * - **Time.** `deadlineFetch`'s bounds, as on a connection's own `fetch`. The call's `timeoutMs`
+     *   runs from the request until the caller's FIRST read of the stream, so read promptly once it is
+     *   open: work awaited in between spends it. From that read, the body errors when the deployment
+     *   sends no byte for `STREAM_IDLE_TIMEOUT_MS`, or after `STREAM_MAX_DURATION_MS` in all. Each of
+     *   these, a deployment too slow to answer at all included, is a `ControlPlaneError` 504, code
+     *   `unavailable`, and the call is released. The bounds are `VerticalClientOptions.attachmentStream`,
+     *   each a whole number of milliseconds up to an hour.
+     * - **What an error means.** One thrown before the stream is handed back means nothing was read.
+     *   One the stream errors with ends in {@link STREAMED_ATTACHMENT_UNVERIFIED}: the caller may hold
+     *   all but the last chunk by then, and must discard it.
+     * - **Cancel.** Cancelling the stream cancels the response body, which the deployment reads as its
+     *   reader going away.
+     */
+    async connectorOpenAttachmentStream(input) {
+        const verb = 'connector-attachment-open';
+        const bounds = attachmentStreamBounds(this.options.attachmentStream);
+        // Asked for here, so a runtime that cannot check the bytes sends nothing; made only once there is a
+        // body to check, so a refusal or an unknown id leaves no digest open.
+        const makeDigest = this.options.attachmentStream?.sha256 ?? runtimeSha256();
+        if (!makeDigest) {
+            throw new ControlPlaneError(500, `${verb}: this runtime has no running sha256 to check a streamed attachment with; ` +
+                `pass VerticalClientOptions.attachmentStream.sha256`);
+        }
+        const timed = deadlineFetch(this.options.fetch, bounds.timeoutMs, bounds);
+        const res = (await this.reach(verb, async () => {
+            try {
+                return (await timed(this.attachmentReadUrl(input), {
+                    headers: { [PLATFORM_SECRET_HEADER]: this.options.platformSecret },
+                }));
+            }
+            catch (err) {
+                // The same slowness as a stall in the body, so the same answer, not `reach`'s "unreachable".
+                if (isTimeout(err)) {
+                    throw attachmentTimeout(`attachment ${input.attachmentId}: the deployment's answer`, err, NOTHING_READ);
+                }
+                throw err;
+            }
+        }));
+        if (res.status === 404) {
+            await res.text().catch(() => { });
+            return null;
+        }
+        if (!res.ok)
+            throw await this.refusal(verb, res);
+        let record;
+        try {
+            record = attachmentRecordOf(res);
+        }
+        catch (err) {
+            await res.text().catch(() => { });
+            throw err;
+        }
+        const source = res.body ?? new Response(new Uint8Array(0)).body;
+        let verified;
+        try {
+            verified = verifiedStream({ stream: source, length: record.size }, record, makeDigest());
+        }
+        catch (err) {
+            await source.cancel().catch(() => { });
+            throw attachmentIntegrity(record, err.message, err);
+        }
+        return {
+            record,
+            body: {
+                stream: classifiedStream(verified.stream, (err) => streamRefusal(record, err)),
+                length: record.size,
+            },
+            contentType: record.contentType,
+        };
+    }
+    /** Where one attachment is read from (#711): the id in the path, the rest in the query. */
+    attachmentReadUrl(input) {
+        const q = new URLSearchParams({
+            connectionId: input.connectionId,
+            tenantId: input.tenantId,
+            scopeId: input.scopeId,
+            ...(input.eventId ? { eventId: input.eventId } : {}),
+        });
+        const base = this.options.baseUrl ?? 'https://vertical.invalid';
+        return `${base}/internal/connector-attachment/${encodeURIComponent(input.attachmentId)}?${q}`;
+    }
     /**
      * Deliver a connection's scope-level grant tuple into the vertical's deployment
      * (#574) — the delivery half of `grantToConnection` for a scope served there.
@@ -622,6 +925,29 @@ export class VerticalClient {
             headers: { [PLATFORM_SECRET_HEADER]: this.options.platformSecret },
         }));
     }
+    /**
+     * #2446: the roles the deployment serving `scopeId` stores for `tenantId` there, and the role keys
+     * seated there (`/internal/role-state`): what its reconcile judges a role set against. `'predates'`
+     * on a 404, the deployment's own proof it has no such route, and on its 501, which a vertical-host
+     * carrying the route answers when its scope host predates `roleStateLocal`. Either is a deployment
+     * built before the read, which a promote counts rather than refuses on, since the promote that
+     * upgrades it is judged by it. Every other failure throws, as does a wrong-shaped answer.
+     */
+    async roleState(input) {
+        const verb = 'role-state';
+        const base = this.options.baseUrl ?? 'https://vertical.invalid';
+        const q = new URLSearchParams({ tenantId: input.tenantId, scopeId: input.scopeId });
+        const answer = await this.routeAnswer(verb, { legacy501: true, lost: 'nothing was changed; the read is safe to repeat.' }, () => this.options.fetch(`${base}/internal/role-state?${q}`, {
+            method: 'GET',
+            headers: { [PLATFORM_SECRET_HEADER]: this.options.platformSecret },
+        }));
+        if (answer === PREDATES)
+            return 'predates';
+        const parsed = roleStateWire.safeParse(answer);
+        if (!parsed.success)
+            throw new ControlPlaneError(502, `vertical answered ${verb} with an unexpected shape for scope ${input.scopeId}.`);
+        return parsed.data;
+    }
     /**
      * The read half of the peer kill switch's status (#1706): every peer the deployment
      * serving this scope holds or has held grants for, and where each stands. Mirrors
@@ -1177,9 +1503,21 @@ export class VerticalClient {
      * missing size read as 0 would sit inside a sum and look like a real, small scope.
      */
     async databaseSize(scopeId) {
-        const answer = await this.getInternal(`/internal/database-size?scopeId=${encodeURIComponent(scopeId)}`);
+        return this.internalSize('database-size', scopeId);
+    }
+    /**
+     * What one scope's attachment rows sum to, in bytes (#2501), for the storage gauge. A deployment
+     * built before the route answers 501, or 404 with no route at all; both throw here, and the
+     * caller decides that is a deployment to redeploy, never a size of 0.
+     */
+    async attachmentSize(scopeId) {
+        return this.internalSize('attachment-size', scopeId);
+    }
+    /** One `/internal/<route>?scopeId=` size read; a 200 without a non-negative integer throws. */
+    async internalSize(route, scopeId) {
+        const answer = await this.getInternal(`/internal/${route}?scopeId=${encodeURIComponent(scopeId)}`);
         if (typeof answer.bytes !== 'number' || !Number.isInteger(answer.bytes) || answer.bytes < 0) {
-            throw new ControlPlaneError(502, `vertical answered database-size without a size for scope ${scopeId}`);
+            throw new ControlPlaneError(502, `vertical answered ${route} without a size for scope ${scopeId}`);
         }
         return answer.bytes;
     }
@@ -1236,6 +1574,9 @@ export class VerticalClient {
             return await request();
         }
         catch (e) {
+            // Already classified by the call itself (a streamed read's timeout, #2514): kept as it is.
+            if (e instanceof ControlPlaneError)
+                throw e;
             const detail = e instanceof Error ? e.message : String(e);
             throw new ControlPlaneError(502, `vertical unreachable during ${verb}: ${detail}`);
         }