@substrat-run/kernel 0.147.0 → 0.149.0

package/dist/scope-host.d.ts

@@ -1,13 +1,17 @@
+import type { OrphanSweepReport, OrphanSweepRequest } from './attachment-sweep.js';
 import type { ScopeStoreStubOptions, StoreErasureReplay, StoreStub } from './scope-store.js';
 import type { ModuleLog } from './module-log.js';
 import type { BoundOperations } from './module-operations.js';
 import type { DeliveryRefusal } from './delivery-refusal.js';
 import type { ScopeRoleHolder } from './scope-role-admin.js';
-import type { ScopeCopyBackfillResult } from './scope-copy-ledger.js';
+import type { ScopeCopyBackfillResult, SubjectErasureFence } from './scope-copy-ledger.js';
+import type { VerticalScopeStore } from './vertical-scope-stores.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, CopyMarkAudit, 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, 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, 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 { ConnectionUseOutcome } from './connector-calls.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 { ModelUsageFilter, ModelUsageInput, ModelUsageWindow } from './model-usage.js';
@@ -577,6 +581,14 @@ export interface OperationContext {
      * like `ctx.grant`.
      */
     readonly capabilities: CapabilityVerbs;
+    /**
+     * Attachment verbs an operation may use — today, minting a single-use URL through which a
+     * caller with no session uploads ONE file to an entity (`mintUploadUrl`). The bytes
+     * themselves never ride an operation: they go to the redemption route, which writes them
+     * through `ScopeHost.attachments`' own upload as the principal who minted the link.
+     * See {@link AttachmentVerbs}.
+     */
+    readonly attachments: AttachmentVerbs;
     /**
      * Run `fn` as a SUB-TRANSACTION of this operation (#770,
      * docs/architecture/sub-transactions.md) — the boundary that makes catching an
@@ -800,6 +812,23 @@ export interface SqlMigration {
     /** Ordered, unique per module, e.g. '0001-init'. Journaled per (module, version). */
     version: string;
     sql: string;
+    /**
+     * Data this migration MOVES, verified (#115): `{ source: target }`, both `table` or both
+     * `table.column`. The kernel refuses a migration that loses rows or values a scope holds
+     * (`migration-fence.ts`); a move excuses the source's loss only when the target gained at least
+     * what the source held, and a table moved whole only when each of its columns that held values
+     * arrives under the same name or is declared by name. Reviewed in the migration diff beside the SQL, and not part of the
+     * SQL's digest. The planner never writes it: a generated migration loses nothing.
+     */
+    moves?: Readonly<Record<string, string>>;
+    /**
+     * Data this migration deliberately LOSES (#115): `{ target: why }`, where target is `table`
+     * (its rows, or the table itself) or `table.column` (its values, or their storage class — a
+     * deliberate retype, a widening included, is declared here). The
+     * reason is required and is what a reviewer reads. Anything lost and not declared here or in
+     * `moves` refuses the migration in a scope that holds it.
+     */
+    discards?: Readonly<Record<string, string>>;
 }
 /**
  * The deployed migration frontier — what "up to date" means for THIS host build
@@ -2058,6 +2087,9 @@ export interface HostAdmin {
      * permission diffs are the admission gates, and binding a scope is a separate step
      * (`bindScopeVersion`), so the two human checkpoints fire where the blast radius is
      * rather than where the typing was.
+     *
+     * Refuses (`conflict`) a version that declares a scope-store binding the vertical already
+     * declared as another driver (#2286): see `verticalScopeStores`.
      */
     publishVersion(actor: PlatformActorId, input: PublishVersionInput): Promise<void>;
     /** Ordered by id (ULID = publish order), `asc` unless `page.order` says otherwise. */
@@ -2203,6 +2235,16 @@ export interface HostAdmin {
      * (`bindExportBreaksOf`), asked of one install. Judged on what the scope RUNS before and
      * after, so re-pointing a scope that runs its vertical's serving script, a fork, a preview,
      * or a first bind is never refused. `bindingImpact` is the listing.
+     *
+     * **#2347: a rebind across lineages moves the route and the pointer in ONE write.**
+     * `opts.servingRef` routes the scope onto that serving script in the same write as the bind
+     * (judged for what the scope runs there, as `bindingImpact` with `servingRef` is), and
+     * `opts.expectedServing` makes that write conditional on the target lineage's serving script
+     * still running the version the rebind was judged against. Two writes would leave a window
+     * where a promote on the target lands between them: the route on the new script, the pointer
+     * on the old lineage. When `expectedServing` is given, losing either compare-and-set (it, or
+     * `expectedVersionId`) is refused as `rebind_review_stale`. Both options are additive: a
+     * caller that sends neither binds exactly as before.
      */
     bindScopeVersion(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, versionId: string, opts?: {
         snapshot?: boolean;
@@ -2211,6 +2253,14 @@ export interface HostAdmin {
         expectedErasureEpoch?: number;
         /** #1722: the copy move this bind routes the scope onto, confirmed in the same write. */
         confirmMove?: ScopeCopyMoveConfirmation;
+        /** #2347: the serving script the scope routes to from this same write. */
+        servingRef?: string;
+        /** #2347: what the target lineage's serving script must still run for the write to land. */
+        expectedServing?: {
+            vertical: string;
+            ref: string;
+            versionId: string;
+        };
     }): Promise<void>;
     /**
      * Which apps in the scope's tenant binding `versionId` would break (#1756): the answer
@@ -2269,13 +2319,24 @@ export interface HostAdmin {
      * version can be bound per-version but never served in place.
      */
     versionManifest(actor: PlatformActorId, verticalSlug: string, versionId: string): Promise<string | null>;
+    /**
+     * Every scope-store binding any version of the vertical has declared, with its driver (#2286,
+     * RFC scope-stores L17): what export, wipe, erasure and the meter reach, so an object under a
+     * binding a later version dropped is still reached. Read by its keys, with no per-version work
+     * once the vertical is indexed. A binding keeps its driver for the life of the vertical:
+     * `publishVersion` refuses a version that moves one to another driver, or declares one twice (`conflict`).
+     * Refuses (`unavailable`) when a version's manifest cannot be read, since that version may
+     * declare a store nobody can name. Empty for an unknown vertical.
+     */
+    verticalScopeStores(actor: PlatformActorId, verticalSlug: string): Promise<VerticalScopeStore[]>;
     /**
      * One version's SQL migrations (#1764), in the order the host runs them. They are stored
      * apart from the manifest, which `versionManifest` returns without them. Null for a version
      * that carries none that can be shown (pushed before #1677, or over the push's caps), which
      * a reader must show as "not available", never as "no migrations". `[]` is a version whose
      * modules ship none. Refuses a version of another vertical, like `versionManifest`.
-     * Access-logged: an owner read for the promote review, never a bulk or background path.
+     * Access-logged. Read by the promote review, and by every serving upload, which injects the
+     * 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>;
     /**
@@ -2461,8 +2522,15 @@ export interface HostAdmin {
      * the append-only admin log (K-21 protects tuples, not the route table).
      * Idempotent: unbinding an unknown hostname is a silent no-op, not an error —
      * so a cleanup pass can re-run over a partial failure.
+     *
+     * `owner` (#2285): remove the binding only while it still names this tenant and scope,
+     * decided by the delete itself. A name rebound to another scope since the caller listed it
+     * is left bound to that scope, and the call is a silent no-op, as for an unknown name.
      */
-    unbindHostname(actor: PlatformActorId, hostname: string): Promise<void>;
+    unbindHostname(actor: PlatformActorId, hostname: string, owner?: {
+        tenantId: TenantId;
+        scopeId: ScopeId;
+    }): Promise<void>;
     /**
      * Ordered by hostname; the cursor is a hostname.
      *
@@ -2587,6 +2655,154 @@ export interface HostAdmin {
         tenantId?: TenantId;
         vertical?: string;
     }): Promise<BlobStoreRecord[]>;
+    /**
+     * Record that a store driver's release bytes are stored, keyed by their sha256 (D-63, #2300).
+     * Insert-only: the same sha256 again answers the row as it stands, and from another source
+     * commit is refused (`conflict`). Audited `uploadStoreDriverRelease` when it writes.
+     */
+    recordStoreDriverRelease(actor: PlatformActorId, input: {
+        driver: string;
+        sha256: string;
+        sourceCommit: string;
+    }): Promise<StoreDriverReleaseRecord>;
+    /** One stored release, or undefined. */
+    getStoreDriverRelease(actor: PlatformActorId, driver: string, sha256: string): Promise<StoreDriverReleaseRecord | undefined>;
+    /**
+     * A driver's current good release, every rollout of it, oldest first, and where a rollback goes.
+     * A `rolling` row whose holder holds the driver no longer reads as `diverged`.
+     */
+    storeDriverState(actor: PlatformActorId, driver: string): Promise<StoreDriverState>;
+    /**
+     * Every vertical any version of which declared a store of `driver`, with those bindings: the
+     * scripts a rollout reaches, and in `unreadable` every vertical that cannot say (a manifest that
+     * does not parse, or versions from before the record that moved a binding to another driver): the caller that
+     * must reach every script refuses while it is not empty.
+     */
+    storeDriverDeclarations(actor: PlatformActorId, driver: string): Promise<{
+        verticals: {
+            vertical: string;
+            stores: VerticalScopeStore[];
+        }[];
+        unreadable: string[];
+    }>;
+    /**
+     * What the next request of a rollout of `sha256` (or a rollback to it) walks (#2312): the first
+     * `limit` verticals, in (vertical, binding) order, holding a declaration of the driver the attempt
+     * it would continue has not walked yet; `pending` counts them all and `walked` the verticals that
+     * attempt walked. A request that continues no attempt (the rows before it are not `paused` at the
+     * same release and action) walks every declaration. `unreadable` as `storeDriverDeclarations`.
+     */
+    storeDriverRolloutPending(actor: PlatformActorId, input: {
+        driver: string;
+        sha256: string;
+        action: StoreDriverRolloutAction;
+        limit: number;
+    }): Promise<{
+        verticals: StoreDriverRolloutTarget[];
+        pending: number;
+        walked: number;
+        unreadable: string[];
+    }>;
+    /**
+     * What the attempt of the rollout at `seq` walked in its earlier requests, in (vertical, binding)
+     * order, at most `limit` (#2312): what a failure part way returns besides its own request's.
+     */
+    storeDriverRolloutWalked(actor: PlatformActorId, input: {
+        driver: string;
+        seq: number;
+        limit: number;
+    }): Promise<{
+        verticals: StoreDriverRolloutTarget[];
+        walked: number;
+    }>;
+    /**
+     * Take or renew a lease on a driver (#2300): `exclusive` for a rollout or rollback, `shared` for
+     * a push or serve rebuilding a script. False when a live hold of another holder excludes it.
+     * `renew` extends only a hold the holder still holds (a lapsed one answers false, never a fresh
+     * hold), and `rolloutSeq` also needs that rollout to be `rolling` still.
+     */
+    holdStoreDriver(actor: PlatformActorId, input: {
+        driver: string;
+        holder: string;
+        mode: StoreDriverHoldMode;
+        ttlMs: number;
+        renew?: boolean;
+        rolloutSeq?: number;
+    }): Promise<boolean>;
+    releaseStoreDriverHold(actor: PlatformActorId, input: {
+        driver: string;
+        holder: string;
+    }): Promise<void>;
+    /**
+     * Begin a rollout (or a rollback) of a stored release, as the driver's exclusive holder; refused
+     * (`conflict`) otherwise. A rollback must name `storeDriverState`'s `rollbackTarget`. Audited
+     * under `rollOutStoreDriver` / `rollBackStoreDriver`.
+     */
+    beginStoreDriverRollout(actor: PlatformActorId, input: {
+        driver: string;
+        sha256: string;
+        action: StoreDriverRolloutAction;
+        holder: string;
+    }): Promise<StoreDriverRolloutRecord>;
+    /**
+     * End a rollout as its exclusive holder; a `good` end makes its release current. Audited as its
+     * begin. A `paused` end records `walked`, what its request walked, in the attempt's ledger, in
+     * the same transaction (#2312); any other end drops the ledger, and `walked` with it is refused.
+     */
+    finishStoreDriverRollout(actor: PlatformActorId, input: {
+        driver: string;
+        seq: number;
+        holder: string;
+        state: Exclude<StoreDriverRolloutState, 'rolling'>;
+        detail: string | null;
+        walked?: readonly StoreDriverRolloutTarget[];
+    }): Promise<StoreDriverRolloutRecord>;
+    /** The platform's rebuild of every script of a driver (#2309), or undefined before its first. */
+    storeDriverRebuild(actor: PlatformActorId, driver: string): Promise<StoreDriverRebuildRecord | undefined>;
+    /**
+     * Take the lease on a driver's fleet rebuild towards `fingerprint` (#2309): the rebuild as it
+     * stands, started over when it was towards another fingerprint (or, with `restart`, when it is
+     * done; with `attestedBy`, always, carrying that attestation), or null while another holder's
+     * lease is live.
+     */
+    claimStoreDriverRebuild(actor: PlatformActorId, input: {
+        driver: string;
+        fingerprint: string;
+        holder: string;
+        ttlMs: number;
+        restart?: boolean;
+        attestedBy?: string;
+    }): Promise<StoreDriverRebuildRecord | null>;
+    /**
+     * Record the lease holder's progress and renew its lease (or drop it with `release`); refused
+     * (`conflict`) once another pass claimed the row or it was restarted at another fingerprint.
+     */
+    advanceStoreDriverRebuild(actor: PlatformActorId, input: {
+        driver: string;
+        fingerprint: string;
+        holder: string;
+        cursor: string | null;
+        failures: readonly StoreDriverRebuildFailure[];
+        done: boolean;
+        /** With `done`: the walk proved every script current. */
+        verified?: boolean;
+        ttlMs: number;
+        release?: boolean;
+    }): Promise<StoreDriverRebuildRecord>;
+    /**
+     * Audit a staff-run pass of a driver's fleet rebuild (#2309) as `rebuildStoreDriver`: the driver,
+     * how the pass ended and what it walked, and `deployFinished` when the person attested that no
+     * control-plane deploy was rolling out. The scheduled pass writes no admin row; its failures are
+     * ops-failure rows.
+     */
+    recordStoreDriverRebuildRun(actor: PlatformActorId, entry: {
+        driver: string;
+        outcome: string;
+        walked: readonly string[];
+        uploaded: readonly string[];
+        error?: string;
+        deployFinished?: true;
+    }): Promise<void>;
     /**
      * One scope's directory record. Cross-checks the (tenantId, scopeId) pair and
      * returns undefined on a mismatch rather than another tenant's scope (K-3) —
@@ -3019,8 +3235,13 @@ export interface HostAdmin {
      * A scope store is reached, by `substrat.erase`, after the scope-side redaction and
      * before the key is destroyed. A store that answers with an error throws, and the key
      * stays, so a retry converges. The receipt's `storeErasures` names each binding.
+     *
+     * `fence` (#2285): the scope state the caller read before it erased the platform's stores. Given,
+     * the shred takes the same claim `finalizeSubjectShred` takes, just before the key goes, and
+     * refuses (`precondition_failed`) with the key kept when the scope moved. Omitted, nothing is
+     * claimed: the caller reached no store outside this host.
      */
-    shredSubject(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, subjectId: string): Promise<SubjectShredReceipt>;
+    shredSubject(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, subjectId: string, fence?: SubjectErasureFence): Promise<SubjectShredReceipt>;
     /**
      * Subjects whose key row is tombstoned (`shredded_at` set), in subject-id order.
      * A page is at most 100. `cursor` is the last id the caller already has.
@@ -3034,12 +3255,7 @@ export interface HostAdmin {
     /** Finish an orchestrated erasure only after every script holding a copy has redacted it.
      * The copy count fences a move that was recorded after the coordinator listed scripts;
      * ledger rows are append-only, so a changed count means that inventory is stale. */
-    finalizeSubjectShred(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, subjectId: string, redactions: readonly SubjectRedactionCounts[], expected: {
-        versionId: string | null;
-        servingRef: string | null;
-        epoch: number;
-        copyCount: number;
-    }, 
+    finalizeSubjectShred(actor: PlatformActorId, tenantId: TenantId, scopeId: ScopeId, subjectId: string, redactions: readonly SubjectRedactionCounts[], expected: SubjectErasureFence, 
     /**
      * What the serving script's stores erased (#2068). The coordinator calls
      * `substrat.erase` once — store objects are per vertical, not per script copy —
@@ -3565,6 +3781,14 @@ export interface HostAdmin {
      * cannot be written.
      */
     recordCopyMark(actor: PlatformActorId, entry: CopyMarkAudit): Promise<void>;
+    /**
+     * Record one pass of the platform's orphan-attachment sweep over one scope (#2314) on the admin
+     * log, as `sweepOrphanAttachments`. The pass runs in the vertical's deployment, so the platform's
+     * sweep writes this after it, when the pass found or deleted an orphan. A dry-run row is also
+     * what licenses a later destructive pass on the scope (`OrphanAttachmentSweepOptions`).
+     * `recordCopyMark`'s shape. Throws when the row cannot be written.
+     */
+    recordOrphanSweep(actor: PlatformActorId, entry: OrphanSweepAudit): Promise<void>;
     /**
      * Record one phase of a dashboard member change (#1150) — an invite, a role move or a removal
      * on an installed vertical's scope — as `manageScopeMember`. The change runs in the vertical's
@@ -3574,6 +3798,7 @@ export interface HostAdmin {
      */
     recordMemberChange(actor: PlatformActorId, entry: MemberChangeAudit): Promise<void>;
     /** One intent or outcome of a tenant's peer-instance binding change (#1720). */
+    recordConnectionBindingChange(actor: PlatformActorId, entry: ConnectionBindingAudit): Promise<void>;
     recordPeerBindingChange(actor: PlatformActorId, entry: PeerBindingAudit): Promise<void>;
     /**
      * Close one audited change whose intent has no outcome (#2064): in ONE transaction, read the
@@ -3863,6 +4088,28 @@ export interface AttachmentUploadInput {
     visibility: Visibility;
     body: Uint8Array;
 }
+/**
+ * Input to `ScopeHost.redeemUploadLink`. No `visibility`: the link carries it, as it carries
+ * the author. `entity` is what the URL named, and must be the link's own.
+ */
+export interface UploadLinkRedeemInput {
+    entity: EntityRef;
+    filename: string;
+    contentType: string;
+    body: Uint8Array;
+    /**
+     * #2315: the redeemer's own id for this redemption (the route reads `Idempotency-Key`). The
+     * spend records its hash; a later redemption of the SAME link with the same key, the same
+     * bytes and inside the link's lifetime plus `UPLOAD_LINK_REPLAY_GRACE_SECONDS` gets the stored
+     * record back (`replayed: true`) and writes nothing. Without it, a spent link is 410 forever.
+     */
+    idempotencyKey?: string;
+}
+/** What `ScopeHost.redeemUploadLink` answers: the record, and whether it was stored by an earlier request. */
+export type RedeemedUploadLink = AttachmentRecord & {
+    /** Present only on a replay (#2315): the file was stored by the request that spent the link, and nothing was written now. */
+    replayed?: true;
+};
 /** An opened attachment: the metadata fact plus the bytes it witnesses. */
 export interface OpenedAttachment {
     record: AttachmentRecord;
@@ -4392,6 +4639,51 @@ export interface ScopeHost {
      * extraction job has no reason to mutate attachment metadata or bytes.
      */
     getSystemAttachments(moduleId: ModuleId, tenantId: TenantId, scopeId: ScopeId): Promise<Pick<ScopeAttachments, 'open'>>;
+    /**
+     * Look an upload link up WITHOUT spending it, so the route can refuse an oversize body or a
+     * wrong type before it reads a byte. `not_found` for a secret that names nothing (and for
+     * one that cannot be ours); `not_found` with reason `upload_link_wrong_target` when `target`
+     * is given and the link was minted for another, judged before its state, so a wrong path is
+     * the same 404 for a pending link and a spent one; `conflict` with reason `upload_link_gone`
+     * for one that is used, expired or revoked. The mint is `ctx.attachments.mintUploadUrl`.
+     *
+     * Optional, like `getCapabilityAttachments`: a host that has not wired the link table says so
+     * by leaving it out, and `mountUploadLinkRedeem` refuses to mount over one.
+     */
+    inspectUploadLink?(tenantId: TenantId, scopeId: ScopeId, secret: string, target?: EntityRef, idempotencyKey?: string): Promise<UploadLinkView>;
+    /**
+     * Redeem an upload link: write the bytes as ONE attachment, AS the principal who minted the
+     * link — the target's `writePermission` is checked as them now, they are the author, and
+     * `attachment.added` is emitted exactly as for any upload. The link is spent in the same
+     * transaction as the attachment row, so a redemption that fails anywhere leaves it unspent;
+     * the size and the type are the LINK's to refuse (`validation_failed`, reasons
+     * `upload_link_too_large` / `upload_link_type_refused`) and a link used by another request
+     * first is `conflict` / `upload_link_gone`. The bytes are written to the blob store before
+     * the row, as an upload's are, and removed again if the row is refused.
+     *
+     * #2315: with `input.idempotencyKey`, a link spent by a redemption that carried the same key
+     * is a REPLAY — `inspectUploadLink` with that key answers the view instead of 410, and this
+     * answers the stored record with `replayed: true` once the body matches it by size and
+     * SHA-256 (`conflict` / `upload_link_replay_mismatch` when it does not). A replay puts no
+     * bytes, writes no row and emits nothing. A retry that races the first request and loses the
+     * spend has its own bytes removed and is answered as a replay too.
+     */
+    redeemUploadLink?(tenantId: TenantId, scopeId: ScopeId, secret: string, input: UploadLinkRedeemInput): Promise<RedeemedUploadLink>;
+    /**
+     * One orphan-sweep pass over a scope's attachment bytes (#2314): delete the objects under the
+     * scope's attachment prefix that no `_substrat_attachments` row names, once they are older than
+     * the grace period and the scope is clear of its restore fence. The scope tombstones each id
+     * before its object is deleted, and the attachment insert refuses a tombstoned id, so a row
+     * that commits never loses its bytes (`sweepOrphanAttachments`, attachment-sweep.ts).
+     *
+     * Platform-only, and judged by THIS host's copy of the scope: only an active primary of
+     * `tenantId` that this host holds is swept, and anything else refuses (`conflict`), as does a
+     * scope with an unsettled copy in another script. On a host whose scopes live in several
+     * deployments, the caller asks only the deployment serving the scope. The age floor and the
+     * fence are judged against the host's own clock, never the caller's.
+     * Optional: a host that has not wired the sweep leaves it out.
+     */
+    sweepOrphanAttachments?(tenantId: TenantId, scopeId: ScopeId, request?: OrphanSweepRequest): Promise<OrphanSweepReport>;
     /**
      * Provision a NEW scope and load a `ScopeDump` into it — the write side of
      * `exportScope` and the fork primitive (docs/architecture/preview-and-snapshots.md §3):