@substrat-run/kernel 0.148.0 → 0.149.0

package/dist/scope-host.d.ts

@@ -1,3 +1,4 @@
+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';
@@ -5,9 +6,9 @@ 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 { StoreKindHoldMode, StoreKindReleaseRecord, StoreKindRolloutAction, StoreKindRolloutRecord, StoreKindRolloutState, StoreKindState } from './store-kind-releases.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, 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, 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';
@@ -811,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
@@ -2071,7 +2089,7 @@ export interface HostAdmin {
      * rather than where the typing was.
      *
      * Refuses (`conflict`) a version that declares a scope-store binding the vertical already
-     * declared as another kind (#2286): see `verticalScopeStores`.
+     * 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. */
@@ -2217,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;
@@ -2225,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
@@ -2284,11 +2320,11 @@ export interface HostAdmin {
      */
     versionManifest(actor: PlatformActorId, verticalSlug: string, versionId: string): Promise<string | null>;
     /**
-     * Every scope-store binding any version of the vertical has declared, with its kind (#2286,
+     * 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 kind for the life of the vertical:
-     * `publishVersion` refuses a version that re-kinds one, or declares one twice (`conflict`).
+     * 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.
      */
@@ -2299,7 +2335,8 @@ export interface HostAdmin {
      * 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>;
     /**
@@ -2619,29 +2656,29 @@ export interface HostAdmin {
         vertical?: string;
     }): Promise<BlobStoreRecord[]>;
     /**
-     * Record that a store kind's release bytes are stored, keyed by their sha256 (D-63, #2300).
+     * 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 `uploadStoreKindRelease` when it writes.
+     * commit is refused (`conflict`). Audited `uploadStoreDriverRelease` when it writes.
      */
-    recordStoreKindRelease(actor: PlatformActorId, input: {
-        kind: string;
+    recordStoreDriverRelease(actor: PlatformActorId, input: {
+        driver: string;
         sha256: string;
         sourceCommit: string;
-    }): Promise<StoreKindReleaseRecord>;
+    }): Promise<StoreDriverReleaseRecord>;
     /** One stored release, or undefined. */
-    getStoreKindRelease(actor: PlatformActorId, kind: string, sha256: string): Promise<StoreKindReleaseRecord | undefined>;
+    getStoreDriverRelease(actor: PlatformActorId, driver: string, sha256: string): Promise<StoreDriverReleaseRecord | undefined>;
     /**
-     * A kind's current good release, every rollout of it, oldest first, and where a rollback goes.
-     * A `rolling` row whose holder holds the kind no longer reads as `diverged`.
+     * 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`.
      */
-    storeKindState(actor: PlatformActorId, kind: string): Promise<StoreKindState>;
+    storeDriverState(actor: PlatformActorId, driver: string): Promise<StoreDriverState>;
     /**
-     * Every vertical any version of which declared a store of `kind`, with those bindings: the
+     * 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 re-kinded a binding): the caller 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.
      */
-    storeKindDeclarations(actor: PlatformActorId, kind: string): Promise<{
+    storeDriverDeclarations(actor: PlatformActorId, driver: string): Promise<{
         verticals: {
             vertical: string;
             stores: VerticalScopeStore[];
@@ -2649,42 +2686,123 @@ export interface HostAdmin {
         unreadable: string[];
     }>;
     /**
-     * Take or renew a lease on a kind (#2300): `exclusive` for a rollout or rollback, `shared` for
+     * 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.
      */
-    holdStoreKind(actor: PlatformActorId, input: {
-        kind: string;
+    holdStoreDriver(actor: PlatformActorId, input: {
+        driver: string;
         holder: string;
-        mode: StoreKindHoldMode;
+        mode: StoreDriverHoldMode;
         ttlMs: number;
         renew?: boolean;
         rolloutSeq?: number;
     }): Promise<boolean>;
-    releaseStoreKindHold(actor: PlatformActorId, input: {
-        kind: string;
+    releaseStoreDriverHold(actor: PlatformActorId, input: {
+        driver: string;
         holder: string;
     }): Promise<void>;
     /**
-     * Begin a rollout (or a rollback) of a stored release, as the kind's exclusive holder; refused
-     * (`conflict`) otherwise. A rollback must name `storeKindState`'s `rollbackTarget`. Audited
-     * under `rollOutStoreKind` / `rollBackStoreKind`.
+     * 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`.
      */
-    beginStoreKindRollout(actor: PlatformActorId, input: {
-        kind: string;
+    beginStoreDriverRollout(actor: PlatformActorId, input: {
+        driver: string;
         sha256: string;
-        action: StoreKindRolloutAction;
+        action: StoreDriverRolloutAction;
         holder: string;
-    }): Promise<StoreKindRolloutRecord>;
-    /** End a rollout as its exclusive holder; a `good` end makes its release current. Audited as its begin. */
-    finishStoreKindRollout(actor: PlatformActorId, input: {
-        kind: 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<StoreKindRolloutState, 'rolling'>;
+        state: Exclude<StoreDriverRolloutState, 'rolling'>;
         detail: string | null;
-    }): Promise<StoreKindRolloutRecord>;
+        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) —
@@ -3663,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
@@ -3971,7 +4097,19 @@ export interface UploadLinkRedeemInput {
     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;
@@ -4504,13 +4642,15 @@ export interface ScopeHost {
     /**
      * 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); `conflict` with reason `upload_link_gone` for one that is used,
-     * expired or revoked. The mint is `ctx.attachments.mintUploadUrl`.
+     * 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): Promise<UploadLinkView>;
+    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
@@ -4520,8 +4660,30 @@ export interface ScopeHost {
      * `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.
-     */
-    redeemUploadLink?(tenantId: TenantId, scopeId: ScopeId, secret: string, input: UploadLinkRedeemInput): Promise<AttachmentRecord>;
+     *
+     * #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):