@substrat-run/kernel 0.159.0 → 0.161.0

package/dist/scope-host.d.ts

@@ -6,17 +6,21 @@ import type { DeliveryRefusal } from './delivery-refusal.js';
 import type { ScopeRoleHolder } from './scope-role-admin.js';
 import type { ScopeCopyBackfillResult, SubjectErasureFence } from './scope-copy-ledger.js';
 import type { VerticalScopeStore } from './vertical-scope-stores.js';
+import type { DeploymentWireAuthFilter, DeploymentWireAuthInput, WireWalkAudit } from './deployment-wire-auth.js';
 import type { StoreDriverHoldMode, StoreDriverRebuildFailure, StoreDriverRebuildRecord, StoreDriverReleaseRecord, StoreDriverRolloutAction, StoreDriverRolloutRecord, StoreDriverRolloutState, StoreDriverRolloutTarget, StoreDriverState } from './store-driver-releases.js';
 import type { SubjectRedactionCounts } from './subject-redaction.js';
-import type { OnBehalfOf, ExportReadInput, ExportedBatch, ImportBatch, ImportedEvent, ImportResult, ImportState, ImportCursorMove, ImportCursorMoved, AdminAction, BecomeCapabilityInput, CapabilityExchange, CapabilityFilter, CapabilityId, CapabilityPage, MintedCapability, ListPage, ConnectLink, ConnectLinkConsume, ConnectLinkFilter, ConnectLinkKey, ConsumeConnectLinkInput, MintConnectLinkInput, Connection, ConnectionFilter, ConnectionId, ConnectionGrant, ConnectionGrantRecord, ConnectionSecret, CreateConnectionInput, OpenConnection, ProjectedConnectionGrant, ProjectedConnectionKey, AccessLogEntry, DelegatedReadRecord, OwnerTransferAudit, MemberChangeAudit, PeerBindingAudit, ConnectionBindingAudit, CopyMarkAudit, OrphanSweepAudit, BindHostnameInput, AdminLogEntry, OpsFailureEntry, PlatformRequestDrainTotalsEntry, SweepRunEntry, SweepRunKind, SweepRunOutcome, ModelUsageEntry, ModelUsageSummary, CapabilityGrant, CreateTenantInput, Decision, Instant, DomainEvent, DomainEventInput, PlatformRequestInput, PlatformRequestId, PlatformRequestEntry, PlatformRequestFilter, PlatformRequestStatus, PlatformRequestFailure, PlatformOutcomeEvent, EntitlementGrant, EntitlementGrantInput, EntitlementView, MeterReading, ScopeStorageSample, EntityRef, IdentityLink, IdentityPool, Jurisdiction, ModuleId, ModuleManifest, ScheduleSpec, SystemGrant, PeerGrantsStatusEntry, SystemGrantsStatusEntry, SystemSwitchRecord, SystemSwitch, SystemSwitchResult, PeerCoverage, PeerSwitch, PeerSwitchResult, VerticalCaller, VerticalResolution, PeerBinding, PeerInstanceResolution, CreateOrgInput, Node, Org, OrgId, OrgMembership, PermissionKey, PlatformActorId, ChannelName, ExportBreak, ChannelHistoryEntry, DnsRecord, HostnameBinding, HostnameStatus, PromotionAcknowledgement, BindAcknowledgement, PublishVersionInput, RegisterVerticalInput, VerticalServingState, RouteTarget, DirectoryDump, IdentityMembership, PrincipalId, ResolvedIdentity, RoleAssignment, RoleDefinition, QueryScopeInput, ReadScopeTableInput, Scope, ScopeDump, ScopeDumpInput, SubjectShredReceipt, ScopeQueryResult, ScopeId, ScopeStatus, ScopeTable, DenialFilter, DenialSummary, RefusalFilter, RefusalRecord, PermissionDenial, Coverage, BeginImpersonationInput, ImpersonationFilter, ImpersonationSession, ImpersonationSessionId, ScopeTablePage, StorageShape, Tenant, TenantId, TenantRole, TenantStoreHandle, AttachmentRecord, UploadLinkView, BlobStoreHandle, Visibility, Vertical, VerticalChannel, VerticalVersion, TenantStatus, Page, CountedPage, FreshnessSpec, EntityHistoryInput, EventFacetInput, EventCauseInput, EventEffectsInput, EffectsTree, InvocationEventsInput, InvocationEvents, DeadLettersInput, DeadLetter, LifecycleFlowInput, LifecycleFlowResult, OperationSeriesInput, OperationSeriesResult, CauseChain, EventFacetResult, HistoryEntry, ErrorCode, PlatformRequestFailureOrigin, IssueEntry, IssueStatus, IssueStatusInput, FindingEntry, FindingFilter, FindingRuleEntry, FindingRuleInput, FindingStatusInput, DeclaredMigration, CheckSubject, EntityGrantShape } from '@substrat-run/contracts';
+import type { OnBehalfOf, ExportReadInput, ExportedBatch, ImportBatch, ImportedEvent, ImportResult, ImportState, ImportCursorMove, ImportCursorMoved, AdminAction, BecomeCapabilityInput, CapabilityExchange, CapabilityFilter, CapabilityId, CapabilityPage, MintedCapability, ListPage, ConnectLink, ConnectLinkConsume, ConnectLinkFilter, ConnectLinkKey, ConsumeConnectLinkInput, MintConnectLinkInput, Connection, ConnectionFilter, ConnectionId, ConnectionGrant, ConnectionGrantRecord, ConnectionSecret, CreateConnectionInput, OpenConnection, ProjectedConnectionGrant, ProjectedConnectionKey, AccessLogEntry, DelegatedReadRecord, OwnerTransferAudit, MemberChangeAudit, PeerBindingAudit, ConnectionBindingAudit, CopyMarkAudit, OrphanSweepAudit, BindHostnameInput, AdminLogEntry, OpsFailureEntry, PlatformRequestDrainTotalsEntry, SweepRunEntry, SweepRunKind, SweepRunOutcome, ModelUsageEntry, ModelUsageSummary, CapabilityGrant, CreateTenantInput, Decision, Instant, DomainEvent, DomainEventInput, PlatformRequestInput, PlatformRequestId, PlatformRequestEntry, PlatformRequestFilter, PlatformRequestStatus, PlatformRequestFailure, PlatformOutcomeEvent, EntitlementGrant, EntitlementGrantInput, EntitlementView, MeterReading, MeterDay, MeterDayTake, VerticalOwnerPeriod, ScopeStorageSample, RequestDay, RequestRollupDay, EntityRef, IdentityLink, IdentityPool, Jurisdiction, ModuleId, ModuleManifest, ScheduleSpec, SystemGrant, PeerGrantsStatusEntry, SystemGrantsStatusEntry, SystemSwitchRecord, SystemSwitch, SystemSwitchResult, PeerCoverage, PeerSwitch, PeerSwitchResult, VerticalCaller, VerticalResolution, PeerBinding, PeerInstanceResolution, CreateOrgInput, Node, Org, OrgId, OrgMembership, PermissionKey, PlatformActorId, ChannelName, ExportBreak, ChannelHistoryEntry, DnsRecord, HostnameBinding, HostnameStatus, PromotionAcknowledgement, BindAcknowledgement, PublishVersionInput, RegisterVerticalInput, VerticalServingState, DeploymentWireAuth, RouteTarget, DirectoryDump, IdentityMembership, PrincipalId, ResolvedIdentity, RoleAssignment, RoleDefinition, QueryScopeInput, ReadScopeTableInput, Scope, ScopeDump, ScopeDumpInput, SubjectShredReceipt, ScopeQueryResult, ScopeId, ScopeStatus, ScopeTable, DenialFilter, DenialSummary, RefusalFilter, RefusalRecord, PermissionDenial, Coverage, BeginImpersonationInput, ImpersonationFilter, ImpersonationSession, ImpersonationSessionId, ScopeTablePage, StorageShape, Tenant, TenantId, TenantRole, TenantStoreHandle, AttachmentRecord, UploadLinkView, BlobStoreHandle, Visibility, Vertical, VerticalChannel, VerticalVersion, TenantStatus, Page, CountedPage, FreshnessSpec, EntityHistoryInput, EventFacetInput, EventCauseInput, EventEffectsInput, EffectsTree, InvocationEventsInput, InvocationEvents, DeadLettersInput, DeadLetter, LifecycleFlowInput, LifecycleFlowResult, OperationSeriesInput, OperationSeriesResult, CauseChain, EventFacetResult, HistoryEntry, ErrorCode, PlatformRequestFailureOrigin, IssueEntry, IssueStatus, IssueStatusInput, FindingEntry, FindingFilter, FindingRuleEntry, FindingRuleInput, FindingStatusInput, DeclaredMigration, CheckSubject, EntityGrantShape } from '@substrat-run/contracts';
 import type { ConnectionUseOutcome } from './connector-calls.js';
+import { type ByteBody, type ByteStream, type IncrementalSha256, type SizedByteStream } from './byte-stream.js';
 import type { CapabilityVerbs } from './capability.js';
 import type { AttachmentVerbs } from './upload-link.js';
 import type { AuditedOperationRef, AuditedOperationRow } from './audit-outcome.js';
-import { type EntityStateName } from '@substrat-run/contracts';
+import { type AttachmentRecordFields, type EntityStateName } from '@substrat-run/contracts';
 import type { ModelUsageFilter, ModelUsageInput, ModelUsageWindow } from './model-usage.js';
 import type { FindingPruneReport } from './findings.js';
 import type { ScopeStorageAttempt, ScopeStorageFilter, ScopeStorageReadingInput } from './storage-gauge.js';
+import type { RequestDayFilter, RequestDayReadInput, RequestRollupDayFilter } from './request-rollup.js';
+import type { MeterDayFilter, MeterDayTakeFilter, MeterDayTakeInput, MeterDayTakeResult } from './meter-days.js';
 import type { SealedSecret } from './secret-box.js';
 import type { OnSubjectErased } from './module-erasure.js';
 import type { SystemSwitchReassert, SystemSwitchReassertOptions, SystemSwitchRecordFilter } from './system-switch-record.js';
@@ -1197,11 +1201,29 @@ export interface ScheduleRunReport {
      * no such drain (D-40): there the count is reported, and the requests wait for the control
      * plane's sweep. Whatever is not counted waits for the next drain, as it always did. Absent
      * when the count is zero, and from a host that predates the field. A purge horizon's runs
-     * count what the host can see: on the node host every purge is an invoke and counts like
-     * one; on the Durable Object host the purges run inside the scope, so only the deliveries
-     * their events route to the platform are counted, not the requests the purges make themselves.
+     * count the same on both hosts: each committed purge's `ctx.requestPlatform` calls (on the
+     * SQLite host every purge is an invoke and counts like one; on the Durable Object host the
+     * scope reports them as `PurgePass.platformRequests`), plus, on the Durable Object host, the
+     * deliveries their events route to the platform. A purge that threw adds nothing.
      */
     platformRequests?: number;
+    /**
+     * #2517: the part of `platformRequests` the purge horizons' runs enqueued. A sweep running
+     * another module's schedules on the same scope in the same tick passes the running sum on
+     * (`ScheduleTick.earlierPurgeRequests`). Absent when zero, and from a host that predates it.
+     */
+    purgeRequests?: number;
+    /**
+     * #2517: purge runs whose head waits for the next tick because the tick's earlier purges filled
+     * the queue (`PurgePass.deferred`). Each is also in `skipped`, never `fired`, and its run is
+     * `skipped`: it ran nothing and moved no cadence row. Absent when none.
+     */
+    deferred?: number;
+}
+/** #2517: what a sweep tick already did to a scope before a `runDueSchedules` call. */
+export interface ScheduleTick {
+    /** Platform requests the purge runs of the tick's earlier calls on this scope enqueued (their `purgeRequests`). */
+    earlierPurgeRequests?: number;
 }
 /**
  * The web-standard fetch surface, structurally typed.
@@ -1233,8 +1255,21 @@ export interface FetchLike {
  * installs, so no suite in this repo sees the difference; the Fortnox consent
  * callback shipped green and failed every hosted round that way (#1291). Closing
  * over the global here means the receiver is never in play, anywhere downstream.
+ *
+ * A `SizedByteStream` body (#2498) is converted by `fetchLikeOf`, which this is built from.
  */
 export declare const globalFetch: FetchLike;
+/**
+ * A runtime `fetch` (the global, a service binding's, a test's stand-in) as a `FetchLike`
+ * (#2498): the one place a `SizedByteStream` body becomes a request the runtime can send, as
+ * `knownLengthInit` builds it. The runtime takes no such value: handed one as it is, a `fetch`
+ * sends its string form, `"[object Object]"`, and answers as if nothing were wrong. So
+ * `globalFetch` is built from this, and both hosts pass the `fetch` they are given through it,
+ * as `runPlatformSweep` does, so a sized body reaches no runtime `fetch` unconverted whichever
+ * one was injected. Wrapping a `FetchLike` that is already one is harmless: a converted body is
+ * no longer a `SizedByteStream`.
+ */
+export declare function fetchLikeOf(runtimeFetch: (input: string, init?: never) => Promise<ConnectorResponse>): FetchLike;
 /**
  * The host's clock (#812) — what `ctx.now()` reads.
  *
@@ -1274,8 +1309,15 @@ export interface ConnectorRequestInit {
      * string cannot carry without corrupting the file. Web `fetch` accepts both, so
      * this only widens the declared surface — the adapter passes it straight
      * through.
+     *
+     * A {@link SizedByteStream} as well (#2498), for a body too large to hold in memory. The
+     * length is part of the value because a provider wants a `Content-Length`, and a stream
+     * carries none. The runtime cannot take one as it is, so it is converted by `fetchLikeOf`:
+     * `globalFetch` is built from it, and both hosts and `runPlatformSweep` pass the `fetch` they
+     * are given through it. A runtime `fetch` handed straight to a connector is made a
+     * `FetchLike` with `fetchLikeOf` too, never by a cast.
      */
-    body?: string | Uint8Array;
+    body?: string | Uint8Array | SizedByteStream;
     signal?: unknown;
 }
 export interface ConnectorResponse {
@@ -1290,6 +1332,31 @@ export interface ConnectorResponse {
      * only widens the structural surface the adapter passes straight through.
      */
     arrayBuffer(): Promise<ArrayBuffer>;
+    /**
+     * The body as a stream (#2498), for a provider file too large to hold: read it chunk by chunk,
+     * or hand it on to `upload` as a `SizedByteStream`. `null` for a response with no body, as on
+     * a web `Response`, which every adapter's `fetch` returns.
+     *
+     * The stream carries the body as `fetch` delivers it: DECODED. A response sent with a
+     * `Content-Encoding` (gzip, br) is decompressed on the way, while its `Content-Length` still
+     * counts the compressed bytes, so that header is the stream's length only when the response
+     * has no `Content-Encoding`. Otherwise take the length from the provider's own record of the
+     * file (its item metadata); a stream sized by the wrong number is refused, not landed.
+     *
+     * The stream is bounded by IDLENESS, not by total transfer time (#2518). A connection's `fetch`
+     * holds the connector's `timeoutMs` (default 30 s) over the call up to the headers and over a
+     * buffered read, and still holds it while `body` is only looked at or never read. From the first
+     * read of the stream the deadline hands over: it errors (`TimeoutError`) when the provider sends
+     * no byte for `STREAM_IDLE_TIMEOUT_MS` (an empty chunk is not a byte), or when
+     * `STREAM_MAX_DURATION_MS` has passed in all. A transfer that keeps flowing completes within
+     * that. A stalled or endless one errors, the connection is released, and an upload reading it
+     * lands no object and no row.
+     *
+     * OPTIONAL for the reason `headers` is: a hand-built stand-in is an object literal, and most
+     * connectors never read a stream. A caller that needs one falls back to `arrayBuffer()` when it
+     * is absent. Read a body once, by one of these.
+     */
+    readonly body?: ByteStream | null;
     /**
      * The response headers, when the runtime behind this seam has them.
      *
@@ -1385,6 +1452,15 @@ export interface ScopedConnectorConnection extends ConnectorConnection {
      * falls back rather than failing a dispatch over a missing file.
      */
     openAttachment(attachmentId: string): Promise<OpenedAttachment | null>;
+    /**
+     * `openAttachment`, with the bytes as a stream that is never held whole (#2514), for a connector
+     * that sends a file on to a provider. Gated the same way, before any byte is read. The sha256 is
+     * checked as the bytes flow, and a mismatch errors the stream before its last chunk is handed on
+     * (see {@link OpenedAttachmentStream}), so a connector that sends what it read must treat a stream
+     * error as "nothing was read", never as a shorter file. A stream it decides not to read is
+     * cancelled (`body.stream.getReader().cancel()`), which releases the stored object at once.
+     */
+    openAttachmentStream(attachmentId: string): Promise<OpenedAttachmentStream | null>;
     /**
      * What this connection may do in the scope this delivery is for (#726 gap 1) —
      * `connectionGrantsInScope`, narrowed to this connection.
@@ -1450,7 +1526,12 @@ export interface ConnectorContext {
 export type ConnectorHandler = (ctx: ConnectorContext, event: DomainEvent) => void | Promise<void>;
 /** Tuning for one connector's egress. */
 export interface ConnectorOptions extends ExecutorRetryPolicy {
-    /** Per-request timeout. Default 30s. */
+    /**
+     * Per-request timeout. Default 30s. It bounds the call up to the response headers and a
+     * buffered read of the body. A streamed body (`ConnectorResponse.body`) is bounded by an idle
+     * window instead (#2518, `STREAM_IDLE_TIMEOUT_MS`) and an absolute cap (`STREAM_MAX_DURATION_MS`):
+     * it may take longer than this, as long as bytes keep arriving.
+     */
     timeoutMs?: number;
     /**
      * The provider slug this connector operates (#574 phase 3) — the routing key a
@@ -1701,6 +1782,17 @@ export interface HostAdmin {
      * absent writes through the admin it holds, unattributed to a person.
      */
     attributed?(onBehalfOf: OnBehalfOf): HostAdmin;
+    /**
+     * Write a tenant's role definition (an upsert). Throws `forbidden` (#2447,
+     * `reservedRoleDefinitionRefusal`) for a person's role holding a key reserved to a system
+     * principal, or a system-held role holding a key a person may hold, judged against what the
+     * host's modules reserve and declare and the tenant's other roles (a system-held role's keys
+     * count as reserved). A redefinition is judged against the stored row of its key: a stored
+     * system-held role's keys count as reserved when it is redefined as a person's, and a stored
+     * person's role held by anyone but a system principal cannot become `holder: 'system'`. A key the
+     * host knows nothing about is admitted. A refusal writes nothing, so the stored definition and
+     * every seat of it are left as they were.
+     */
     defineRole(actor: PlatformActorId, tenantId: TenantId, role: RoleDefinition): Promise<void>;
     /**
      * Every role the directory holds, ordered by (tenantId, key).
@@ -2239,6 +2331,13 @@ export interface HostAdmin {
      * while the refusal above is being raced. Staff-only, audited.
      */
     deleteVertical(actor: PlatformActorId, slug: string): Promise<void>;
+    /**
+     * Every period of a slug's ownership (#2501), oldest first: opened by `registerVertical`, closed
+     * by `deleteVertical`, each in that write's transaction. Served for a deleted slug too, which is
+     * the point: a past period bills whoever owned the vertical then. Access-logged (K-24).
+     * Optional, so a host built before it still satisfies `HostAdmin`.
+     */
+    listVerticalOwners?(actor: PlatformActorId, slug: string): Promise<VerticalOwnerPeriod[]>;
     /**
      * Promote a version to a channel (#31 step 2) — the moment a change reaches
      * anyone, and therefore where §4's two human checkpoints belong.
@@ -2401,6 +2500,32 @@ export interface HostAdmin {
      * digest of the served version's migrations (#2349) — one read per upload, never a scan.
      */
     versionMigrations(actor: PlatformActorId, verticalSlug: string, versionId: string): Promise<DeclaredMigration[] | null>;
+    /**
+     * Record what one upload gave the script it went to (RFC wire-signing §7, Q8): the capability
+     * record, written by the uploader from what it built and injected, never declared by the
+     * vertical. It replaces that script's earlier record, so it is always the last upload's. Audited.
+     *
+     * Optional, like the gauge's methods: a host that lacks them records nothing, and the readiness
+     * report reads a deployment with no record as unknown, never as ready.
+     */
+    recordWireAuth?(actor: PlatformActorId, input: DeploymentWireAuthInput): Promise<void>;
+    /**
+     * One page of the stored capability records, by script name: `limit` (required, at most
+     * `LIST_PAGE_MAX`), `cursor` the last script name of the page before, `order`. Confined by `reach`,
+     * which is required: one tenant's verticals (`{ tenantId }`, the verticals it owns now) or the
+     * whole fleet (`{ fleet: true }`), so a reader that forgets to confine itself is refused, never
+     * handed every tenant's deployments. A tenant reach follows the vertical's current owner, resolved
+     * at read time (`DeploymentWireAuthReach`). Optionally one vertical's within that. A bad filter is
+     * `validation_failed` (`assertWireAuthFilter`). Access-logged (K-24). Reached through the host API
+     * only today.
+     */
+    listWireAuth?(actor: PlatformActorId, filter: DeploymentWireAuthFilter): Promise<DeploymentWireAuth[]>;
+    /**
+     * Audit one pass of the fleet walk (RFC wire-signing follow-on 4) as `walkWireAuth`: a person's act,
+     * dry run or applied. Each script the pass changed writes its own `recordWireAuth` row as well, with
+     * its record, in one directory transaction.
+     */
+    recordWireWalk?(actor: PlatformActorId, entry: WireWalkAudit): Promise<void>;
     /**
      * Point a scope's ROUTING at the serving script its data now lives in. Per-scope
      * truth, deliberately not derived from the vertical: rerouting a scope whose DOs
@@ -2555,6 +2680,14 @@ export interface HostAdmin {
         binding: string;
         bytes: number;
     }[]>;
+    /**
+     * A CO-LOCATED scope's attachment bytes (#2501): what its attachment rows sum to
+     * (`ATTACHMENT_BYTES_SQL`). Bytes in the blob store that no row names are not in it. Like
+     * `scopeDatabaseSize` it wakes the scope and is access-logged; for a dispatch vertical the
+     * platform reads it through the vertical's `/internal/attachment-size` instead. Optional, so a
+     * host built before it still satisfies `HostAdmin`.
+     */
+    scopeAttachmentBytes?(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId): Promise<number>;
     /**
      * #286's backout: PITR-rewind a scope to a pre-migration bookmark — schema AND
      * data, discarding every write since. Audited (destructive by design). The scope
@@ -2717,6 +2850,17 @@ export interface HostAdmin {
     getTenant(actor: PlatformActorId, tenantId: TenantId): Promise<Tenant | undefined>;
     /** The scope inventory. Ordered by scope_id (ULID = chronological); cursor = scope id. */
     listScopes(actor: PlatformActorId, filter?: ScopeFilter): Promise<Scope[]>;
+    /**
+     * `listScopes` for a fleet-wide pass: the same rows in the same order, except that a row which
+     * does not read as a `Scope` is named in `unreadable` instead of failing the whole list. A
+     * healthy directory answers exactly what `listScopes` does, with `unreadable` empty.
+     *
+     * `listScopes` stays strict: a console or a route showing the directory should fail loudly on
+     * a row it cannot read. A pass over every scope (`runPlatformSweep`) should step over that one
+     * row and say so, which is what this read is for. Optional, so a host that predates it is read
+     * through `listScopes`.
+     */
+    listScopesReadable?(actor: PlatformActorId, filter?: ScopeFilter): Promise<ScopeListing>;
     /**
      * The tenant-store ledger (#301): every platform-minted per-tenant store, optionally
      * narrowed by tenant and/or vertical. The deploy path reads `{ vertical }` to derive
@@ -3404,9 +3548,12 @@ export interface HostAdmin {
      * suspension is an outage, not revenue), and expiry is evaluated at the reading's
      * instant so a lapsed grant reads as lapsed rather than as never-granted.
      *
-     * Computes nothing that needs a data pipeline. Meters 3 and 4 are absent because
-     * they are uncomputable by construction, not because this is a first slice — the
-     * per-scope outbox has no cross-tenant fan-in, and reads emit nothing at all.
+     * Computes nothing that needs a data pipeline, so it carries meters 1 and 2 only.
+     * Meter 4 has no number: it needs the cross-tenant order flow. Meter 3 is not
+     * folded into this reading; its parts are read elsewhere: the storage gauge, the
+     * model usage ledger, and the estimated daily request rollup at `/meters/requests`.
+     * Lake rows carry their bytes, but no reader sums them yet. Exact API counts are
+     * not computable: reads emit nothing on the spine. See control-plane.md §5.
      *
      * Nothing is stored: a reading is recomputed per call. D-30 is meter, do not bill,
      * and a persisted running total is the first half of a billing ledger.
@@ -3742,8 +3889,8 @@ export interface HostAdmin {
         recorded: number;
     }>;
     /**
-     * Stored storage samples (#1524) — the latest per scope, or a bounded history. See
-     * `ScopeStorageFilter`. A directory read that wakes no scope. Access-logged (K-24).
+     * Stored storage samples (#1524) — the latest per scope, or a bounded history,
+     * which includes a reaped scope's kept days (#2515). See `ScopeStorageFilter`. A directory read that wakes no scope. Access-logged (K-24).
      */
     listScopeStorage?(actor: PlatformActorId, filter?: ScopeStorageFilter): Promise<ScopeStorageSample[]>;
     /** Every stored scope's latest storage-read attempt (#1524): the storage phase's due list. Access-logged. */
@@ -3753,6 +3900,49 @@ export interface HostAdmin {
      * `limit` per call, so a backlog drains over passes. Returns how many went. Not audited.
      */
     pruneScopeStorage?(actor: PlatformActorId, limit: number): Promise<number>;
+    /**
+     * The daily request rollup (#2501): record one attempt to read a UTC day's request counts from
+     * the router's datapoints. A successful read replaces the day's rows and marks the day read; a
+     * failed one records only the attempt and its error. Every count is an estimate. Returns how
+     * many rows were written. Not audited, like `recordScopeStorage`: a sweep's own bookkeeping.
+     *
+     * The rollup methods are optional, and the sweep's rollup phase is skipped on a host that lacks
+     * them, so an adapter built before #2501 still satisfies `HostAdmin`.
+     */
+    recordRequestDay?(actor: PlatformActorId, input: RequestDayReadInput): Promise<{
+        recorded: number;
+    }>;
+    /** Stored daily request counts (#2501), every one an estimate. See `RequestDayFilter`. Access-logged (K-24). */
+    listRequestDays?(actor: PlatformActorId, filter?: RequestDayFilter): Promise<RequestDay[]>;
+    /** The rollup's record of each day it tried (#2501): what the phase picks due days by. Access-logged. */
+    listRequestRollupDays?(actor: PlatformActorId, filter?: RequestRollupDayFilter): Promise<RequestRollupDay[]>;
+    /**
+     * Delete day rows older than a retention of `retentionMonths`, oldest first and at most `limit`
+     * per call. `null` deletes nothing (`BILLING_ROLLUP_RETENTION_MONTHS`). Returns how many went.
+     * Not audited, like `pruneScopeStorage`.
+     */
+    pruneRequestDays?(actor: PlatformActorId, limit: number, retentionMonths: number | null): Promise<number>;
+    /**
+     * The daily meter snapshot (#2501): record one attempt at the snapshot of the UTC day of
+     * `input.at`. Without an error it takes the snapshot, in one directory transaction, unless the
+     * day already has one: meters 1 and 2 folded by `foldMeterReading` at `input.at`, one row per
+     * tenant that is not reaped. With an error it records only the failed attempt. Not audited, like
+     * `recordRequestDay`: a sweep's own bookkeeping, and nothing it reads leaves the directory.
+     *
+     * The snapshot methods are optional, and the sweep's snapshot phase is skipped on a host that
+     * lacks them, so an adapter built before #2501's snapshot still satisfies `HostAdmin`.
+     */
+    recordMeterDay?(actor: PlatformActorId, input: MeterDayTakeInput): Promise<MeterDayTakeResult>;
+    /** Stored daily meter snapshots (#2501). See `MeterDayFilter`. Access-logged (K-24). */
+    listMeterDays?(actor: PlatformActorId, filter?: MeterDayFilter): Promise<MeterDay[]>;
+    /** The record of each day a pass tried to snapshot (#2501): what the phase reads its run from. Access-logged. */
+    listMeterDayTakes?(actor: PlatformActorId, filter?: MeterDayTakeFilter): Promise<MeterDayTake[]>;
+    /**
+     * Delete snapshot rows older than a retention of `retentionMonths`, oldest first and at most
+     * `limit` per call. `null` deletes nothing (`BILLING_ROLLUP_RETENTION_MONTHS`). Returns how many
+     * went. Not audited, like `pruneRequestDays`.
+     */
+    pruneMeterDays?(actor: PlatformActorId, limit: number, retentionMonths: number | null): Promise<number>;
     /**
      * A staff verdict on one issue (#1233): resolve, ignore, or reopen. `regressed`
      * is ingest's word and not accepted here. Returns the updated row, or undefined
@@ -3943,6 +4133,15 @@ export interface ProvisionScopeInput {
     name?: string;
     /** Which vertical's deployment executes this scope. Defaults to null. */
     vertical?: string | null;
+    /**
+     * Where `vertical` came from, which decides what it is held to. `'input'` (the default): a
+     * caller named it, and it must be a `verticalSlug`. `'copy'`: it is the stored vertical of a
+     * scope that already exists and this one copies (a snapshot, a sibling), taken as the directory
+     * reads it (any non-empty string), so a scope stored before the grammar was held at provisioning
+     * can still be copied. Platform code sets `'copy'` only with a value it read from the directory;
+     * no request body carries it.
+     */
+    verticalSource?: 'input' | 'copy';
     storageShape?: StorageShape;
     jurisdiction?: Jurisdiction;
     /**
@@ -4027,13 +4226,29 @@ export interface BlobStoreProvisionInput {
  * is what turns "scope/<id>/ is a convention" into "cross-scope keys are unwritable".
  */
 export interface TenantBlobStore {
-    put(key: string, body: Uint8Array, opts?: {
+    /**
+     * Write `body` under `key`. A `SizedByteStream` (#2498) is written as it is read, never
+     * collected first, and refused if it carries other than its declared length. The put
+     * resolves only once the whole stream has been read.
+     */
+    put(key: string, body: ByteBody, opts?: {
         contentType?: string;
     }): Promise<void>;
     get(key: string): Promise<{
         body: Uint8Array;
         contentType?: string;
     } | null>;
+    /**
+     * The object under `key` as a stream (#2514), with the size the store holds for it, read as the
+     * consumer reads it and never collected first. Optional, so a store written before it still
+     * satisfies this interface: an open over such a store reads the object with `get` and hands it on
+     * as a stream, which works but holds the object whole.
+     */
+    getStream?(key: string): Promise<{
+        stream: ByteStream;
+        size: number;
+        contentType?: string;
+    } | null>;
     delete(key: string): Promise<void>;
     /** Keys under `prefix` — the GC/ops walk. */
     list(prefix: string): Promise<string[]>;
@@ -4066,6 +4281,31 @@ export declare function attachmentBlobKey(scopeId: string, attachmentId: string)
  * both adapters' `open`, and the extraction job (#1575).
  */
 export declare function attachmentSha256(body: Uint8Array): Promise<string>;
+/**
+ * Write an upload's bytes to the blob store and answer the record they make (#2498) — the "bytes
+ * first" half of every attachment write, one path for both adapters. The record's fields are
+ * judged before a byte moves, so a record the surface would refuse lands no object. A buffer is
+ * then hashed and written, as before. A stream is hashed and counted while the store reads it, so
+ * it is never held whole; `sha256` is the adapter's running digest, since the kernel has none of
+ * its own. The caller writes the row.
+ *
+ * A streamed write that fails, or whose store answers without reading the stream to its end, has
+ * its object deleted and is refused: no record may witness bytes nobody saw.
+ */
+export declare function putAttachmentBytes(store: TenantBlobStore, key: string, fields: AttachmentRecordFields, body: ByteBody, sha256: () => IncrementalSha256): Promise<AttachmentRecord>;
+/**
+ * The bytes of an attachment the scope has already AUTHORIZED, as a stream held to its record (#2514):
+ * the "bytes" half of every streamed open, one path for both adapters, as {@link putAttachmentBytes}
+ * is for the write. The caller checks the read permission first and calls this only once it passed,
+ * so a refused read never reaches the store.
+ *
+ * The length is the record's `size`, which the upload took from the bytes themselves. The store's own
+ * size for the object is held to it before the first byte, so an object that is not the recorded one
+ * is refused up front. The sha256 is checked as the bytes flow ({@link verifiedStream}): a mismatch
+ * errors the stream before its last chunk is handed on. A store without `getStream` is read whole with
+ * `get` and handed on the same way.
+ */
+export declare function openAttachmentByteStream(store: TenantBlobStore, key: string, record: AttachmentRecord, sha256: () => IncrementalSha256): Promise<OpenedAttachmentStream>;
 /**
  * Who binds an operation, as the §4.3 entitlement gate needs to know it: the owning
  * module, the SKU flag its manifest declares, and the operations that module declares
@@ -4167,7 +4407,13 @@ export interface AttachmentUploadInput {
     filename: string;
     contentType: string;
     visibility: Visibility;
-    body: Uint8Array;
+    /**
+     * The bytes: a buffer, or a `SizedByteStream` for a file too large to hold (#2498). A stream
+     * goes to the blob store as it is read; its sha256 and size are taken on the way through, and
+     * the row is written after the object, as for a buffer. Its declared length is the record's
+     * `size`, and a stream that carries a different number of bytes lands nothing.
+     */
+    body: ByteBody;
 }
 /**
  * Input to `ScopeHost.redeemUploadLink`. No `visibility`: the link carries it, as it carries
@@ -4197,6 +4443,18 @@ export interface OpenedAttachment {
     body: Uint8Array;
     contentType: string;
 }
+/**
+ * An opened attachment whose bytes are a stream (#2514): the metadata fact, and its bytes at the
+ * record's `size`, read as the consumer reads them. The sha256 is checked as they pass, so a
+ * mismatch errors the stream before its last chunk instead of refusing up front: a consumer that
+ * has received all `size` bytes has received bytes that matched the record. One-shot: read it once,
+ * or cancel it, which releases the stored object; a stream that is neither holds it until collected.
+ */
+export interface OpenedAttachmentStream {
+    record: AttachmentRecord;
+    body: SizedByteStream;
+    contentType: string;
+}
 /**
  * The attachment surface a host mints per (principal, scope) — `attachmentTargets`
  * finally consumed (#473). Every method is gated INSIDE the platform by the declared
@@ -4213,6 +4471,12 @@ export interface ScopeAttachments {
     list(entity: EntityRef): Promise<AttachmentRecord[]>;
     /** Record + bytes, or null for an id this scope does not know. Gated per entity. */
     open(attachmentId: string): Promise<OpenedAttachment | null>;
+    /**
+     * `open`, with the bytes as a stream that is never held whole (#2514). The same gate, checked
+     * before the store is touched, and the same `null`; the integrity check moves to the stream (see
+     * {@link OpenedAttachmentStream}).
+     */
+    openStream(attachmentId: string): Promise<OpenedAttachmentStream | null>;
     /** Delete row (and event) first, then bytes; returns the removed record, null if unknown. */
     remove(attachmentId: string): Promise<AttachmentRecord | null>;
     /**
@@ -4262,6 +4526,22 @@ export interface ScopeFilter extends ListPage {
     status?: ScopeStatus | ScopeStatus[];
     vertical?: string;
 }
+/**
+ * A directory row that does not read as a `Scope`. Its ids as stored and the names of the
+ * fields that did not parse, and nothing else of the row: the ids are what an operator needs to
+ * find it, and its contents are not this report's to repeat.
+ */
+export interface UnreadableScopeRow {
+    scopeId: string;
+    tenantId: string;
+    /** Top-level `Scope` field names that did not parse; `['row']` when the failure names none. */
+    fields: string[];
+}
+/** What `HostAdmin.listScopesReadable` answers. */
+export interface ScopeListing {
+    scopes: Scope[];
+    unreadable: UnreadableScopeRow[];
+}
 /**
  * Narrow the admin audit trail (control-plane.md §4.4/§4.5). Every field is a
  * conjunctive AND; omitting all of them reads the whole log, which is why `limit`
@@ -4486,6 +4766,16 @@ export interface OpsFailureInput {
     message: string;
     /** The upstream provider's trace reference, when the message carried one. */
     reference?: string | null;
+    /**
+     * #2540: the failure's own text, when `message` is only what the request was answered. A row
+     * filed under a tenant is read back by that tenant, so a host given `detail` on one writes it on
+     * a second row with no tenant under the same `reference`, which only staff read, and counts the
+     * failure once: the issue takes `detail` as its last message, owned as the platform's (the row it
+     * copies), so a subject erasure reaches it on an id match. Ignored on a row with no tenant, whose
+     * `message` is staff's already. A tenant-readable row never carries an upstream trace handle: a
+     * writer keeps one only at the start of this text (`withUpstreamReference`; `referenceInText`).
+     */
+    detail?: string | null;
 }
 /** How long a recorded copy move owns its pending entries before a sweep may settle them (#1722). */
 export declare const SCOPE_COPY_LEASE_MS: number;
@@ -4549,6 +4839,12 @@ export interface OpsFailureFilter {
     fingerprint?: string;
     /** Exact match — the lookup a CI log's `reference = <id>` line lands on. */
     reference?: string;
+    /**
+     * #2540: with `reference`, also every pair whose row with no tenant names `reference = <reference>`
+     * in its text (an upstream trace handle, which a withheld failure keeps only there), both rows of
+     * it. Staff's search: the text it matches is staff's, so a confined read never sets it.
+     */
+    referenceInText?: boolean;
     since?: string;
     until?: string;
     limit?: number;
@@ -5175,8 +5471,14 @@ export interface ScopeHost {
      * class as `drainDue`/`migrateScope`; the invocation itself is attributed to the
      * system actor. A single schedule's failure is reported, never thrown, so one bad
      * operation cannot stop the others on the scope.
+     *
+     * `tick` (#2517) carries what this sweep tick already did to the scope before this call: a
+     * sweep that runs several modules' schedules on one scope with no drain between them passes the
+     * sum of the earlier calls' `purgeRequests`, so a purge head the cap refuses because those
+     * purges filled the queue is deferred rather than failed (`runPurgePass`). Optional; absent
+     * means none.
      */
-    runDueSchedules(moduleId: ModuleId, tenantId: TenantId, scopeId: ScopeId): Promise<ScheduleRunReport>;
+    runDueSchedules(moduleId: ModuleId, tenantId: TenantId, scopeId: ScopeId, tick?: ScheduleTick): Promise<ScheduleRunReport>;
     /**
      * The declared freshness expectations, per module (#1232). OPTIONAL and
      * feature-detected like `registeredSchedules` is by the sweep: a pre-#1232