@voltro/plugin-storage 0.85.0 → 0.87.0

package/dist/index.d.ts

@@ -1,16 +1,32 @@
+import { ByteStream } from '@voltro/kv/storage';
 import { ColumnBuilder } from '@voltro/database';
 import { ColumnType } from '@voltro/database';
+import { ConnectionRef } from '@voltro/kv/connection';
+import { ConnectionRegistryShape } from '@voltro/kv/connection';
 import { Context } from 'effect';
 import { DataStore } from '@voltro/database';
 import { Effect } from 'effect';
 import { FieldDefinitions } from '@voltro/database';
+import { isStorageKey } from '@voltro/kv/storage';
 import { Layer } from 'effect';
 import { mixin } from '@voltro/database';
+import { ObjectMeta } from '@voltro/kv/storage';
 import { PluginEgressDeclaration } from '@voltro/protocol';
 import { Readable } from 'node:stream';
 import { Schema } from 'effect';
 import { StorageAccessPolicy } from '@voltro/protocol';
 import { StorageAccessRule } from '@voltro/protocol';
+import { StorageAddress } from '@voltro/kv/storage';
+import { storageAddressIdentity } from '@voltro/kv/storage';
+import { StorageConnectionConnector } from '@voltro/kv/storage';
+import { StorageDestination } from '@voltro/kv/storage';
+import { StorageDestinationRouter } from '@voltro/kv/storage';
+import { StorageError } from '@voltro/kv/storage';
+import { StorageObjectLocation } from '@voltro/kv/storage';
+import { StorageProvider } from '@voltro/kv/storage';
+import { StorageProviderName } from '@voltro/kv/storage';
+import { StoredObject } from '@voltro/kv/storage';
+import { StoredStream } from '@voltro/kv/storage';
 import { Stream } from 'effect';
 import { Subject } from '@voltro/protocol';
 import { Table } from '@voltro/database';
@@ -35,12 +51,24 @@ export declare type AccessPolicy = StorageAccessPolicy;
  */
 export declare type AccessRule = StorageAccessRule;
 
-/**
- * The provider the APP configured, falling back to the env-derived default when no
- * `storagePlugin(...)` is installed. Use this — not `resolveStorageProvider({})` —
- * anywhere outside the plugin that needs "the storage this app actually uses".
- */
-export declare const appStorageProvider: () => StorageProvider;
+/** The app Storage plugin's bound service and durable object metadata. */
+export declare interface AppStorageObjects {
+    readonly service: StorageServiceShape;
+    readonly metadata: StorageObjectMetadata;
+    /** The destination new objects land in. */
+    readonly bucket: string;
+}
+
+/** Borrow the bound service and object metadata of the app's one Storage plugin, for server code that runs
+ * outside the request layer (a Rooms Host, a geometry source). Read it after `bindDataStore`. Refuses with no
+ * or several Storage installs, and before binding or with app-supplied ref/grant stores (no metadata boundary). */
+export declare const appStorageObjects: (plugins: ReadonlyArray<VoltroPlugin>) => AppStorageObjects;
+
+/** Borrow the app's configured destination. Absence is an error, never a fresh memory store. */
+export declare const appStorageProvider: (plugins: ReadonlyArray<VoltroPlugin>) => StorageProvider;
+
+/** Resolve persisted ownership across this app, independently of new defaults. */
+export declare const appStorageRouter: (plugins: ReadonlyArray<VoltroPlugin>) => StorageDestinationRouter;
 
 /** A column binding an entity to a stored asset (a `_voltro_storage_refs` id). */
 export declare function assetRef(options: AssetRefOptions & {
@@ -58,6 +86,20 @@ export declare interface AssetRefOptions {
     readonly nullable?: boolean;
 }
 
+/** The caller owns the after-schema transaction, with serving replicas stopped.
+ * Assignments preserve reference IDs, keys, grants, raw put identities, claims
+ * and quota. No provider I/O or nested transaction occurs. Returned cleanup
+ * targets run through their matching service after boot. */
+export declare const assignStorageObjectNamespacesInTransaction: (store: DataStore, scopes: readonly StorageReferenceScope[], assignments: readonly StorageObjectNamespaceAssignment[]) => Promise<StorageObjectNamespaceMigrationResult>;
+
+/** Run in an after-schema migration with serving replicas stopped. The mapping
+ * comes from the operator, never from provider failures or the default name.
+ * The supplied store belongs to the caller’s transaction. No nested transaction
+ * is opened. Only ownership columns change: IDs, bytes, claims, quota and replay stay put. */
+export declare const assignStorageReferenceInstancesInTransaction: (store: DataStore, instances: readonly string[], assignments: readonly StorageReferenceInstanceAssignment[]) => Promise<{
+    readonly assigned: number;
+}>;
+
 export declare const azureProvider: (options: AzureProviderOptions) => StorageProvider;
 
 export declare interface AzureProviderOptions {
@@ -82,14 +124,7 @@ export declare const buildStorageService: (options: StorageServiceOptions) => St
  *  stream. `subarray` keeps the chunks as views (no copy). */
 export declare const bytesToStream: (bytes: Uint8Array, chunkSize?: number) => ByteStream;
 
-/**
- * A lazy stream of bytes — the streaming counterpart to {@link StoredObject}'s
- * eager `bytes`. Backpressured: chunks are pulled on demand, so a multi-GB blob
- * never fully materialises in memory. The error channel is {@link StorageError}
- * so a stream handed to `putStream` carries the same typed failure the rest of
- * the transport does (callers map their source errors into it).
- */
-export declare type ByteStream = Stream.Stream<Uint8Array, StorageError>;
+export { ByteStream }
 
 /** Check an upload against the limits. Returns `null` when ok, else a
  *  `{ reason, detail }` describing the violation. */
@@ -127,24 +162,13 @@ export declare const collectStream: (stream: ByteStream) => Effect.Effect<Uint8A
 /** Concatenate byte chunks into one contiguous Uint8Array. */
 export declare const concatBytes: (chunks: ReadonlyArray<Uint8Array>) => Uint8Array;
 
-/**
- * The app's provider, or `undefined` when NOBODY named one.
- *
- * `resolveProvider({})` cannot answer this: its final `default:` arm returns an
- * in-process `memoryProvider`, so it is total by construction and every caller
- * checking `if (!provider)` is checking a condition that cannot hold. Three of
- * them existed — the `--assets` refusals in `voltro data backup` / `export` /
- * `restore`, whose whole job is to refuse a flag the app cannot honour. They
- * were dead, and what they let through is worse than an unchecked flag: with no
- * storage configured, `backup --assets` captured from a FRESH memory provider,
- * found nothing in it, and wrote an artefact stamped `assets: { count: 0 }` —
- * a rollback story that says the blobs are in there.
- *
- * "Configured" means one of the two things a person actually did: installed
- * `storagePlugin(...)` (which registers here at construction), or set
- * `STORAGE_PROVIDER`. A memory provider nobody asked for is not a decision.
- */
-export declare const configuredStorageProvider: () => StorageProvider | undefined;
+/** Select only transports contributed by this app's plugin instances.
+ * Multiple destinations require explicit asset routing, never last-writer wins.
+ * An implicit in-memory fallback is never reported as configured storage. */
+export declare const configuredStorageProvider: (plugins: ReadonlyArray<VoltroPlugin>) => StorageProvider | undefined;
+
+/** The CLI injects this server adapter into the leaf registry. No plugin imports enter KV. */
+export declare const connectStorage: StorageConnectionConnector;
 
 /** `image/*` matches `image/png`; exact otherwise. */
 export declare const contentTypeAllowed: (contentType: string, allowed: ReadonlyArray<string> | undefined) => boolean;
@@ -159,10 +183,13 @@ export declare const databaseProvider: () => StorageProvider & {
     bindDataStore: (store: unknown) => void;
 };
 
-export declare const dataStoreGrantStore: (store: DataStore) => GrantStore;
+/** Dynamic grants resolve through a currently visible reference. The concrete
+ * store retains its namespace through cleanup; grant rows alone never authorize
+ * bytes in a newly rebound destination. */
+export declare const dataStoreGrantStore: (store: DataStore, configuredView: StorageReferenceView) => GrantStore;
 
 /** Ref store backed by the app's `DataStore` (`_voltro_storage_refs`). */
-export declare const dataStoreRefStore: (store: DataStore) => RefStore;
+export declare const dataStoreRefStore: (store: DataStore, configuredScope: StorageReferenceView) => RefStore;
 
 /** Decode a `data:<mime>;base64,<data>` URI to bytes + content type. */
 export declare const decodeDataUri: (dataUri: string) => {
@@ -189,6 +216,23 @@ export declare const editImage: (bytes: Uint8Array, contentType: string, edit: I
  *  chunks, terminated by a zero-length chunk. Exposed for testing. */
 export declare const encodeInstream: (bytes: Uint8Array, chunkSize?: number) => Buffer;
 
+/** Boot-time initialization after normal schema reconciliation. This identity
+ * describes the persisted reference catalogue, not its provider bytes or host. */
+export declare const ensureStorageReferenceCatalogue: (store: DataStore) => Promise<void>;
+
+/**
+ * The identity a filesystem volume ALREADY carries — never a new one.
+ *
+ * `filesystemObjectNamespace` mints the marker on an empty root, which is right
+ * for a serving process and wrong for a migration: a migrate job started
+ * without the volume mounted read an empty directory, minted an identity no
+ * serving replica has, and an assignment to it exited 0. A metadata upgrade
+ * resolves the namespace through this function, so a missing volume refuses.
+ */
+export declare const existingFilesystemObjectNamespace: (root: string) => string;
+
+export declare const fetchIngestBody: (url: string, configuredMaxBytes?: number, policy?: IngestPolicy) => Effect.Effect<StoredObject, StorageError | StorageRejected>;
+
 export declare interface FfmpegRenditionSpec {
     /** Derivative class stored on the rendition ref — `'rendition'` / `'poster'`. */
     readonly kind: string;
@@ -291,7 +335,7 @@ export declare interface ImageEdit {
     readonly crop?: Region;
 }
 
-/** Where `ingestUrl` may fetch from — see `ssrfReason` in `@voltro/runtime`. */
+/** Where `ingestUrl` may fetch from — see `ssrfReason` in `@voltro/protocol`. */
 export declare interface IngestPolicy {
     /** Hosts (or `host:port`, or `*.suffix`) reachable although internal — a
      *  deliberate internal source, or a local test server. Everything else that
@@ -299,8 +343,13 @@ export declare interface IngestPolicy {
     readonly allowHosts?: ReadonlyArray<string>;
     /** Redirect hops followed, each checked again. Default 5. */
     readonly maxRedirects?: number;
+    /** Refuse HTTP at the initial source and every redirect before fetching.
+     * Host allowlisting does not bypass this transport requirement. Default false. */
+    readonly requireHttps?: boolean;
 }
 
+export { isStorageKey }
+
 /**
  * Filter + page a `StorageService.listRefs` / media-library query. Every
  * filter is optional and ANDed; omit them all to page the whole (tenant-scoped)
@@ -336,63 +385,117 @@ export declare interface ListRefsResult {
     readonly nextOffset: number | null;
 }
 
-/** DataStore-backed metadata boundary, intentionally no provider access. The
- * service must use reserve -> provider.put -> confirm and retain failed intents. */
-export declare const makeStorageObjectMetadata: (store: DataStore) => {
-    /** The put intent a reference was written under, if it was written through an operation at all. */
+/** Each call captures its request tenant; no request changes the selected cell. */
+export declare const makeStorageDestinationRouter: (binding: StorageDestinationBinding) => StorageDestinationRouter;
+
+/** Resolve every operation to one concrete physical namespace. Metadata-only
+ * discovery stays instance scoped; the persisted intent is validated against
+ * the retained destination before it can authorize reads, claims or deletion. */
+export declare const makeStorageObjectMetadata: (store: DataStore, configuredView: StorageReferenceView, admit?: StorageObjectAdmission) => {
+    scopeFor: (input: {
+        readonly bucket: string;
+        readonly tenantId: string | null;
+    } | {
+        readonly refId: string;
+    }) => Promise<StorageReferenceScope>;
     intent: (refId: string) => Promise<{
         identity: {
             readonly tenantId: string | null;
             readonly bucket: string;
+            readonly objectNamespace: string;
+            readonly fingerprint: string;
+            readonly checksum: string;
+            readonly storageInstance: string;
             readonly operationId: string;
+            readonly logicalKey: string;
+            readonly retainedSource?: {
+                readonly refId: string;
+                readonly digest: string;
+            };
+        };
+        ref: StorageRef;
+    } | undefined>;
+    operationStatus: (input: {
+        readonly bucket: string;
+        readonly tenantId: string | null;
+        readonly operationId: string;
+    }) => Promise<{
+        observation: StorageOperationState;
+        scope: StorageReferenceScope;
+    }>;
+    lookup: (input: Omit<StorageObjectOperationScope, keyof StorageReferenceScope>, claim: string) => Promise<{
+        state: "ready" | "reserved" | "deleting" | "deleted";
+        ref: StorageRef;
+        held: boolean;
+    } | undefined>;
+    operation: (key: StorageObjectOperationKey) => Promise<{
+        state: "ready" | "reserved" | "deleting" | "deleted";
+        identity: {
+            readonly tenantId: string | null;
+            readonly bucket: string;
+            readonly objectNamespace: string;
             readonly fingerprint: string;
             readonly checksum: string;
+            readonly storageInstance: string;
+            readonly operationId: string;
             readonly logicalKey: string;
+            readonly retainedSource?: {
+                readonly refId: string;
+                readonly digest: string;
+            };
         };
         ref: StorageRef;
     } | undefined>;
-    /** `claim` is registered only where the caller receives the ref: here when
-     * the operation is already ready (`joined`), else on `confirm`. A claimant
-     * whose provider write fails therefore holds nothing. */
     reserve: (identity: StorageObjectIdentity, proposed: StorageRef, quota?: StorageQuota, claim?: string) => Promise<{
         ref: StorageRef;
         ready: boolean;
         outcome: PutOutcome;
     }>;
     confirm: (identity: StorageObjectIdentity, claim?: string) => Promise<StorageRef>;
-    /** With a `claim`, releases that claim and deletes the object only when no
-     * other claimant holds it; `released` alone (no `operation`) means another
-     * claimant still does. Without one, the whole object goes, claims included. */
     beginDelete: (refId: string, tenantId?: string | null, claim?: string) => Promise<{
         released: true;
         identity: {
             readonly tenantId: string | null;
             readonly bucket: string;
-            readonly operationId: string;
+            readonly objectNamespace: string;
             readonly fingerprint: string;
             readonly checksum: string;
+            readonly storageInstance: string;
+            readonly operationId: string;
             readonly logicalKey: string;
+            readonly retainedSource?: {
+                readonly refId: string;
+                readonly digest: string;
+            };
         };
         operation?: never;
     } | {
         released: true;
         operation: {
             readonly id: string;
+            readonly storageInstance: string;
+            readonly objectNamespace: string;
             readonly objectId: string;
             readonly fingerprint: string;
             readonly generation: string;
             readonly key: string;
             readonly refId: string;
-            readonly state: "ready" | "reserved" | "deleted" | "deleting";
+            readonly state: "ready" | "reserved" | "deleting" | "deleted";
             readonly deleteKey: string | null;
         };
         identity: {
             readonly tenantId: string | null;
             readonly bucket: string;
-            readonly operationId: string;
+            readonly objectNamespace: string;
             readonly fingerprint: string;
             readonly checksum: string;
+            readonly storageInstance: string;
+            readonly operationId: string;
             readonly logicalKey: string;
+            readonly retainedSource?: {
+                readonly refId: string;
+                readonly digest: string;
+            };
         };
     }>;
     confirmDelete: (identity: StorageObjectIdentity) => Promise<boolean>;
@@ -414,11 +517,7 @@ export declare interface MultipartTicketPayload extends Omit<UploadTicketPayload
     readonly size: number;
 }
 
-/** Result of a provider `put` / `head`. */
-export declare interface ObjectMeta {
-    readonly size: number;
-    readonly etag?: string;
-}
+export { ObjectMeta }
 
 /** Parse a clamd INSTREAM reply: `stream: OK` → clean; `stream: <T> FOUND`
  *  → infected; anything else → throws. Exposed for testing. */
@@ -455,6 +554,8 @@ export declare const putAvatar: (storage: StorageServiceShape, args: {
 
 /** Input to `StorageService.put`. */
 export declare interface PutInput {
+    /** Server-owned logical destination; omitted new writes use this plugin's selection. */
+    readonly destination?: string;
     readonly bytes: Uint8Array;
     readonly contentType: string;
     /** Active org id — scopes the key prefix + the ref row. */
@@ -546,6 +647,13 @@ export declare interface RefStatistics {
 }
 
 export declare interface RefStore {
+    /** Complete metadata-only ownership observation; no pagination or recent limit. */
+    readonly listObjectReferences: () => Effect.Effect<ReadonlyArray<StorageObjectReference>, StorageError>;
+    /** Stable identity of this actual reference view. Shared catalogues expose
+     * the same identity; independent/process-local stores must expose their own. */
+    readonly catalogueId: Effect.Effect<string, StorageError>;
+    /** Durable reservations retain bytes before a reference is confirmed. */
+    readonly hasObjectReservation?: (namespace: string, key: string) => Effect.Effect<boolean, StorageError>;
     /** Aggregate the complete reference index without a recent-object limit. */
     readonly statistics: () => Effect.Effect<RefStatistics, StorageError>;
     readonly insert: (ref: StorageRef) => Effect.Effect<void, StorageError>;
@@ -555,10 +663,8 @@ export declare interface RefStore {
      *  same id refund the tenant counter exactly once. */
     readonly delete: (id: string) => Effect.Effect<boolean, StorageError>;
     readonly listRecent: (limit: number) => Effect.Effect<ReadonlyArray<StorageRef>, StorageError>;
-    /** How many refs (in this bucket) point at this provider key — drives
-     *  refcount-before-delete so a dedup'd object isn't yanked from under a
-     *  sibling ref. */
-    readonly countByKey: (bucket: string, key: string) => Effect.Effect<number, StorageError>;
+    /** Logical address count; physical cleanup also observes other destinations. */
+    readonly countByAddress: (address: StorageAddress) => Effect.Effect<number, StorageError>;
     /** Total bytes + object count for a tenant — LIVE sum over the ref rows
      *  (reporting / dashboards). The quota GATE does not read this — it rides
      *  the atomic `consumeUsage` counter, which a read-then-compare here could
@@ -595,7 +701,7 @@ export declare interface RefStore {
     readonly setVisibility?: ((id: string, visibility: StorageVisibility) => Effect.Effect<StorageRef | null, StorageError>) | undefined;
     /** How many PUBLIC refs point at this provider key — whether the object must
      *  stay publicly readable. */
-    readonly countPublicByKey?: ((bucket: string, key: string) => Effect.Effect<number, StorageError>) | undefined;
+    readonly countPublicByAddress?: ((address: StorageAddress) => Effect.Effect<number, StorageError>) | undefined;
 }
 
 /** A region of an image in pixels. */
@@ -609,6 +715,8 @@ declare interface Region {
 /** One derived output a `Transcoder` produces from a source asset. Each becomes
  *  a normal storage ref linked back to the original via `derivedFrom`. */
 export declare interface Rendition {
+    /** Optional structured producer attestation; unproven outputs keep it absent. */
+    readonly derivation?: RenditionDerivation;
     readonly bytes: Uint8Array;
     readonly contentType: string;
     /** Derivative class — e.g. `'rendition'` (a playable variant) or `'poster'`. */
@@ -617,6 +725,49 @@ export declare interface Rendition {
     readonly label?: string;
 }
 
+/** Producer attestation. Digests bind a normalized recipe and the observed
+ * engine build; the consumer still admits allowed recipes, engines and rights. */
+export declare interface RenditionDerivation {
+    readonly recipe: {
+        readonly format: string;
+        readonly digest: string;
+    };
+    readonly engine: {
+        readonly name: string;
+        readonly version: string;
+        readonly digest: string;
+    };
+}
+
+/** Storage-verified input/output identity around a producer attestation.
+ * Not an approval, rights grant or proof of complete external dependencies. */
+export declare interface RenditionProof extends RenditionDerivation {
+    readonly version: 1;
+    readonly source: {
+        readonly id: string;
+        readonly metadataDigest: string;
+        readonly checksum: string;
+        readonly size: number;
+        readonly contentType: string;
+    };
+    readonly output: {
+        readonly checksum: string;
+        readonly size: number;
+        readonly contentType: string;
+    };
+    readonly digest: string;
+}
+
+/**
+ * Nullable additions deliberately fail closed until the explicit upgrade.
+ *
+ * The refusal names every table still holding unassigned rows and how many,
+ * because the commonest way to meet it AFTER a completed assignment is a
+ * reference a previous-version replica wrote while the assignment ran — and a
+ * recorded file migration does not run again by itself.
+ */
+export declare const requireStorageObjectNamespaces: (store: DataStore) => Promise<void>;
+
 /** A `ListRefsInput` after the service normalizes its defaults / clamps — what
  *  a `RefStore.listRefs` impl receives. `limit` is already the `+1` probe. */
 export declare interface ResolvedListQuery {
@@ -632,11 +783,7 @@ export declare interface ResolvedListQuery {
 
 export declare const resolveStorageProvider: (options: StoragePluginOptions) => StorageProvider;
 
-/**
- * The signing secret. A dedicated `VOLTRO_STORAGE_SECRET` is preferred so
- * grant tokens and session cookies can be rotated independently; absent
- * that we fall back to the session secret so it works out of the box.
- */
+/** The secret new storage tokens are signed with — the first of {@link resolveStorageSecrets}. */
 export declare const resolveStorageSecret: () => string;
 
 /** What a resumable ticket authorizes: one chunked upload session, until `exp`. */
@@ -647,6 +794,63 @@ export declare interface ResumableTicketPayload extends Omit<UploadTicketPayload
     readonly size: number;
 }
 
+export declare interface RetainedCaptureKey {
+    readonly id: string;
+    readonly instance: string;
+    readonly objectNamespace: string;
+    readonly tenantId: string | null;
+    readonly bucket: string;
+    /** Binds the caller's immutable publication/configuration admission. */
+    readonly contextDigest: string;
+    /** Different configured source; absent for same-instance custody. */
+    readonly source?: {
+        readonly instance: string;
+        readonly objectNamespace: string;
+        readonly bucket: string;
+    };
+}
+
+export declare interface RetainedCapturePin extends RetainedCaptureKey {
+    readonly count: number;
+    readonly digest: string;
+}
+
+export declare const retainedCaptureTables: readonly [ Table<"_voltro_storage_retained_captures", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "text", boolean>;
+    readonly captureId: ColumnBuilder<string, "text", boolean>;
+    readonly instance: ColumnBuilder<string, "text", boolean>;
+    readonly tenantId: ColumnBuilder<string | null, "text", boolean>;
+    readonly bucket: ColumnBuilder<string, "text", boolean>;
+    readonly contextDigest: ColumnBuilder<string, "text", boolean>;
+    readonly state: ColumnBuilder<"abandoned" | "complete" | "capturing", "text", boolean>;
+    readonly nonce: ColumnBuilder<string, "text", boolean>;
+    readonly config: ColumnBuilder<unknown, "json", boolean>;
+    readonly count: ColumnBuilder<number, "integer", boolean>;
+    readonly digest: ColumnBuilder<string | null, "text", boolean>;
+    readonly cleanupOrdinal: ColumnBuilder<number, "integer", true>;
+}>, false, never>, Table<"_voltro_storage_retained_capture_items", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "text", boolean>;
+    readonly captureId: ColumnBuilder<string, "text", boolean>;
+    readonly ordinal: ColumnBuilder<number, "integer", boolean>;
+    readonly sourceId: ColumnBuilder<string, "text", boolean>;
+    readonly sourceDigest: ColumnBuilder<string, "text", boolean>;
+    readonly operationId: ColumnBuilder<string, "text", boolean>;
+    readonly pin: ColumnBuilder<unknown, "json", boolean>;
+}>, false, "storage_retained_capture_page">];
+
+export declare interface RetainedStorageObject {
+    readonly version: 1;
+    readonly tenantId: string | null;
+    readonly bucket: string;
+    readonly operationId: string;
+    readonly sourceId: string;
+    readonly sourceDigest: string;
+    readonly refId: string;
+    readonly checksum: string;
+    readonly size: number;
+    readonly contentType: string;
+}
+
 export declare const s3Provider: (options: S3ProviderOptions) => StorageProvider;
 
 export declare interface S3ProviderOptions {
@@ -668,8 +872,7 @@ export declare interface S3ProviderOptions {
     readonly publicAcl?: boolean;
 }
 
-/** Register the app's storage provider (or clear with `undefined`). */
-export declare const setActiveStorageProvider: (provider: StorageProvider | undefined) => void;
+export declare type ScopedStorageObjectIdentity = StorageObjectIdentity & StorageReferenceScope;
 
 /** Sign a finalize token valid for `ttlSeconds`. */
 export declare const signFinalizeTicket: (fields: Omit<FinalizeTicketPayload, "exp" | "version">, ttlSeconds: number, secret?: string) => string;
@@ -694,6 +897,8 @@ export declare const STORAGE_BLOBS_TABLE = "_voltro_storage_blobs";
 
 export declare const STORAGE_GRANTS_TABLE = "_voltro_storage_grants";
 
+export declare const STORAGE_REFERENCE_CATALOGUE_TABLE = "_voltro_storage_reference_catalogue";
+
 export declare const STORAGE_REFS_TABLE = "_voltro_storage_refs";
 
 export declare const STORAGE_USAGE_TABLE = "_voltro_storage_usage";
@@ -711,6 +916,88 @@ declare const StorageAccessDenied_base: Schema.Class<StorageAccessDenied, Schema
     readonly reason: Schema.String;
 }>, YieldableError>;
 
+export { StorageAddress }
+
+export { storageAddressIdentity }
+
+export declare const storageByteSecurityHeaders: (contentType: string) => Readonly<Record<string, string>>;
+
+/** Private-byte custody for trusted server coordinators. storagePlugin supplies
+ * this service only for its exact instance. Pins confer no end-user authority. */
+export declare class StorageCustody extends StorageCustody_base {
+    /** Reconstruct a transfer from configured services on each worker. Both must
+     * use the same application database; only the destination stores custody. */
+    static withSource(input: {
+        readonly source: StorageCustodyShape;
+        readonly destination: StorageCustodyShape;
+    }): Effect.Effect<StorageCustodyShape, StorageError>;
+    static forInstance(selection?: StorageCustodyInstance): Context.Service<StorageCustody, StorageCustodyShape>;
+}
+
+declare const StorageCustody_base: Context.ServiceClass<StorageCustody, string, StorageCustodyShape>;
+
+/** Uses the same instance selector as storagePlugin. */
+export declare interface StorageCustodyInstance {
+    readonly alias?: string;
+    readonly name?: string;
+}
+
+/** Trusted server selection. Source enumeration runs in the caller's DB TX. */
+export declare interface StorageCustodyRegistration {
+    readonly id: string;
+    readonly tenantId: string | null;
+    readonly contextDigest: string;
+    readonly maxBytes: number;
+    readonly sources: () => Iterable<string | StorageSourcePin> | AsyncIterable<string | StorageSourcePin>;
+}
+
+export declare interface StorageCustodyShape {
+    /** Read and lock metadata from this configured source, including rendition
+     * provenance. No provider I/O, access grant or recipe/rights approval.
+     * Bind the pin to the caller's immutable candidate and contextDigest, then
+     * pass it to register in the same application transaction. */
+    readonly inspect: (tx: DataStore, input: {
+        readonly id: string;
+        readonly tenantId: string | null;
+    }) => Effect.Effect<StorageSourcePin, StorageError>;
+    /** Register stable work in the same transaction as the caller's source pin.
+     * The transaction must belong to this plugin's bound application database. */
+    readonly register: (tx: DataStore, input: StorageCustodyRegistration) => Effect.Effect<{
+        readonly key: RetainedCaptureKey;
+        readonly count: number;
+    }, StorageError>;
+    /** Copy/verify bytes outside a DB transaction; retries reuse registered work. */
+    readonly run: (key: RetainedCaptureKey) => Effect.Effect<void, StorageError>;
+    /** Seal with the caller's final manifest and durable result in one DB TX. */
+    readonly seal: (tx: DataStore, key: RetainedCaptureKey) => Effect.Effect<RetainedCapturePin, StorageError>;
+    /** Private pins. Consume through EOF and stage output until digest success.
+     * Pass the same application transaction when enumerating a just-sealed pin. */
+    readonly items: (pin: RetainedCapturePin, tx?: DataStore) => Stream.Stream<RetainedStorageObject, StorageError>;
+    /** Trusted server read of a verified member pin. Not an access grant.
+     * Tenant admission must come from the caller; finish byte verification at EOF. */
+    readonly read: (capture: RetainedCapturePin, object: RetainedStorageObject, scope: {
+        readonly tenantId: string | null;
+        readonly maxBytes: number;
+    }) => Effect.Effect<{
+        readonly stream: ByteStream;
+        readonly contentType: string;
+        readonly size: number;
+    }, StorageError>;
+    /** Close admission before cleanup. Repeat cleanup after uncertain/late I/O. */
+    readonly abandon: (key: RetainedCaptureKey) => Effect.Effect<void, StorageError>;
+}
+
+export { StorageDestination }
+
+declare interface StorageDestinationBinding {
+    readonly selected: () => string;
+    readonly directDestination: string | undefined;
+    readonly directProvider: () => StorageProvider;
+    readonly registry: () => ConnectionRegistryShape | undefined;
+}
+
+export { StorageDestinationRouter }
+
 /**
  * Where the bytes go, read from the same options and env `resolveProvider`
  * reads: an object store is a destination outside the installation; the
@@ -718,20 +1005,7 @@ declare const StorageAccessDenied_base: Schema.Class<StorageAccessDenied, Schema
  */
 export declare const storageEgressOf: (options: StoragePluginOptions) => ReadonlyArray<PluginEgressDeclaration>;
 
-/**
- * Storage failure. `transient` drives retry — `true` for 429 / 5xx /
- * network blips, `false` for 4xx / config / not-found. Surfaced typed so
- * handlers can `Effect.catchTag('StorageError', …)`.
- */
-export declare class StorageError extends StorageError_base {
-}
-
-declare const StorageError_base: Schema.Class<StorageError, Schema.TaggedStruct<"StorageError", {
-    readonly provider: Schema.String;
-    readonly message: Schema.String;
-    readonly transient: Schema.Boolean;
-    readonly status: Schema.optional<Schema.Number>;
-}>, YieldableError>;
+export { StorageError }
 
 /** A persisted, explicit share of one object with one principal. */
 export declare interface StorageGrant {
@@ -761,8 +1035,11 @@ export declare type StorageGuard = (ctx: {
  * and `BASE_NAME` is not exported, so a caller minting a ticket outside the
  * plugin had to guess it. Guessing is exactly what a `string` parameter invites.
  *
+ * Use this name in the ticket's `instance` field. The ticket also captures
+ * the selected destination, owner, tenant, content type and visibility.
+ *     const writeScope = await Effect.runPromise(service.uploadTicketScope({ tenantId, destination }))
  *     const ticket = signUploadTicket(
- *       { instance: storageInstanceName(), key, contentType },
+ *       { writeScope, destination, instance: storageInstanceName(options), key, ct: contentType, sub: ownerId, tenant: tenantId, vis: 'private' },
  *       300,
  *     )
  *
@@ -772,16 +1049,24 @@ export declare type StorageGuard = (ctx: {
  */
 export declare const storageInstanceName: (options?: StoragePluginOptions) => string;
 
-export declare interface StorageObjectIdentity {
-    readonly tenantId: string | null;
-    readonly bucket: string;
-    readonly operationId: string;
+/** Internal database-only admission. Runs under the storage tenant lock, in
+ * the same transaction as reserve/join/confirm. It must lock or write its own
+ * durable owner row; observing a live flag before this transaction is unsafe.
+ * No provider, engine or other external I/O belongs in this callback. */
+declare type StorageObjectAdmission = (tx: DataStore, identity: StorageObjectIdentity, phase: 'reserve' | 'confirm') => Promise<void>;
+
+export declare interface StorageObjectIdentity extends StorageObjectOperationKey {
     /** Hash of all immutable put inputs, including content and access metadata. */
     readonly fingerprint: string;
     /** SHA-256 of the actual normalized provider bytes, separate from metadata. */
     readonly checksum: string;
     /** Already tenant-scoped logical provider key. */
     readonly logicalKey: string;
+    /** Private retained-input provenance; not an access rule or CMS policy. */
+    readonly retainedSource?: {
+        readonly refId: string;
+        readonly digest: string;
+    };
 }
 
 /** Internal persistence substrate. Service wiring must commit quota and refs in
@@ -791,11 +1076,14 @@ export declare const storageObjectLifecycleTables: ( Table<"_voltro_storage_oper
     readonly nonce: ColumnBuilder<string, "text", boolean>;
 }>, false, never> | Table<"_voltro_storage_object_heads", FieldDefinitions<{
     readonly id: ColumnBuilder<string, "text", boolean>;
+    readonly objectNamespace: ColumnBuilder<string | null, "text", boolean>;
     readonly generation: ColumnBuilder<string, "text", boolean>;
     readonly key: ColumnBuilder<string, "text", boolean>;
     readonly reservations: ColumnBuilder<string, "bigint", boolean>;
 }>, false, never> | Table<"_voltro_storage_operations", FieldDefinitions<{
     readonly id: ColumnBuilder<string, "text", boolean>;
+    readonly storageInstance: ColumnBuilder<string | null, "text", boolean>;
+    readonly objectNamespace: ColumnBuilder<string | null, "text", boolean>;
     readonly objectId: ColumnBuilder<string, "text", boolean>;
     readonly fingerprint: ColumnBuilder<string, "text", boolean>;
     readonly generation: ColumnBuilder<string, "text", boolean>;
@@ -809,13 +1097,59 @@ export declare const storageObjectLifecycleTables: ( Table<"_voltro_storage_oper
     readonly claim: ColumnBuilder<string, "text", boolean>;
 }>, false, never>)[];
 
+export { StorageObjectLocation }
+
 export declare type StorageObjectMetadata = ReturnType<typeof makeStorageObjectMetadata>;
 
+/** Credential-independent identity of a physical object-key namespace.
+ * Equal identities mean an equal key addresses the same provider bytes. */
+export declare const storageObjectNamespace: (parts: readonly string[]) => string;
+
+export declare interface StorageObjectNamespaceAssignment extends StorageReferenceScope {
+    readonly refId: string;
+}
+
+export declare interface StorageObjectNamespaceMigrationResult {
+    readonly assigned: number;
+    readonly pendingDeletes: readonly StorageObjectNamespaceAssignment[];
+}
+
+export declare interface StorageObjectOperationKey {
+    readonly tenantId: string | null;
+    readonly bucket: string;
+    readonly operationId: string;
+}
+
+export declare interface StorageObjectOperationScope extends StorageReferenceScope {
+    readonly tenantId: string | null;
+    readonly bucket: string;
+    readonly operationId: string;
+}
+
+export declare type StorageObjectReference = Pick<StorageRef, 'bucket' | 'tenantId' | 'key' | 'visibility'> & Partial<StorageReferenceScope>;
+
+/** A durable metadata observation, not a claim on the object or a provider HEAD. */
+export declare type StorageOperationState = {
+    readonly state: 'absent' | 'reserved' | 'deleting' | 'deleted';
+} | {
+    readonly state: 'ready';
+    readonly ref: StorageRef;
+};
+
+/** Metadata state qualified by the actual selected storage destination. */
+export declare type StorageOperationStatus = StorageOperationState & {
+    /** Configured instance, actual catalogue, physical namespace and logical bucket. */
+    readonly scope: string;
+    /** Selected logical destination; retain it with the scope before minting a ticket. */
+    readonly destination: string;
+};
+
 export declare const storagePlugin: (options?: StoragePluginOptions) => VoltroPlugin;
 
 export declare interface StoragePluginOptions {
     /** `'s3' | 'minio' | 'filesystem' | 'memory'` (built from env) or a
      *  `StorageProvider`. Default: `STORAGE_PROVIDER` env, else `'memory'`. */
+    readonly connection?: ConnectionRef<'storage'>;
     readonly provider?: StorageProviderName | StorageProvider;
     /** Bucket name (s3/minio). Default `S3_BUCKET`/`STORAGE_BUCKET` env, else 'voltro'. */
     readonly bucket?: string;
@@ -959,103 +1293,16 @@ export declare interface StoragePluginOptions {
     readonly name?: string;
 }
 
-/**
- * A backend transport. Keyed by an opaque object key (the service owns key
- * derivation + tenant prefixing); knows nothing about refs, tenants, or
- * access policy.
- */
-export declare interface StorageProvider {
-    /**
-     * Where a FILESYSTEM provider writes. Absent for every other provider.
-     *
-     * It exists so a caller can ask a question this interface otherwise cannot
-     * answer: does what I write here survive the process? A rollback capture
-     * written for a pod that then dies is worthless, and `filesystem` is the one
-     * provider that can be either — a mounted volume or an ephemeral container
-     * directory. A deployment pointed this out: their check for "storage is
-     * configured" passed on a `/tmp` path with no volume behind it.
-     */
-    readonly root?: string;
-    readonly name: string;
-    /** True when `getUrl` returns a real presigned URL (s3/minio). When
-     *  false the service serves bytes via the `/_voltro/storage/:id`
-     *  endpoint instead (filesystem/memory). */
-    readonly presigns: boolean;
-    readonly put: (key: string, bytes: Uint8Array, meta: {
-        readonly contentType: string;
-        readonly public?: boolean;
-    }) => Effect.Effect<ObjectMeta, StorageError>;
-    readonly get: (key: string) => Effect.Effect<StoredObject, StorageError>;
-    readonly delete: (key: string) => Effect.Effect<void, StorageError>;
-    /** Presigned GET (s3/minio) for private reads. */
-    readonly getUrl: (key: string, expiresInSec: number) => Effect.Effect<string, StorageError>;
-    /** A direct, cacheable URL for a PUBLIC object — virtual-hosted bucket
-     *  URL or a configured CDN base. `null` when the provider can't serve
-     *  publicly without the app (filesystem/memory) → the service falls
-     *  back to the `/_voltro/storage/:id` route. */
-    readonly publicUrl?: (key: string) => string | null;
-    /** Make an object publicly readable at the provider, or not (s3/minio with
-     *  per-object ACLs). Absent where the app decides per request (database,
-     *  filesystem, memory) — there a ref's visibility is the whole answer. */
-    readonly setObjectPublic?: (key: string, isPublic: boolean) => Effect.Effect<void, StorageError>;
-    /** Presigned PUT for direct-to-bucket uploads (s3/minio). Absent on
-     *  providers that can't presign uploads. */
-    readonly getUploadUrl?: (key: string, expiresInSec: number, contentType: string) => Effect.Effect<string, StorageError>;
-    readonly createMultipartUpload?: (key: string, contentType: string, opts?: {
-        readonly public?: boolean;
-    }) => Effect.Effect<{
-        readonly uploadId: string;
-    }, StorageError>;
-    readonly presignUploadPart?: (key: string, uploadId: string, partNumber: number, expiresInSec: number) => Effect.Effect<string, StorageError>;
-    readonly completeMultipartUpload?: (key: string, uploadId: string, parts: ReadonlyArray<{
-        readonly partNumber: number;
-        readonly etag: string;
-    }>) => Effect.Effect<{
-        readonly etag?: string;
-    }, StorageError>;
-    readonly abortMultipartUpload?: (key: string, uploadId: string) => Effect.Effect<void, StorageError>;
-    readonly head: (key: string) => Effect.Effect<ObjectMeta | null, StorageError>;
-    /**
-     * Stream an object's bytes in chunks instead of buffering the whole blob
-     * ({@link get}). Present on backends with a real streaming read (filesystem,
-     * s3, azure). OPTIONAL: when a provider omits it, {@link getObjectStream}
-     * transparently falls back to `get` + a chunked in-memory stream — correct
-     * for the small-blob backends (memory / database) that have nothing to
-     * stream from.
-     */
-    readonly getStream?: (key: string) => Effect.Effect<StoredStream, StorageError>;
-    /**
-     * Consume a {@link ByteStream} and store it via the backend's chunked /
-     * multipart upload, so a large upload never fully materialises in memory.
-     * Present on filesystem (streamed atomic write), s3 (multipart via
-     * `@aws-sdk/lib-storage`), azure (`uploadStream`). OPTIONAL: when absent,
-     * {@link putObjectStream} buffers the stream and calls `put`. `totalSize`,
-     * when the caller knows it (e.g. from an export manifest), lets the backend
-     * report an accurate size without a follow-up HEAD.
-     */
-    readonly putStream?: (key: string, stream: ByteStream, meta: {
-        readonly contentType: string;
-        readonly public?: boolean;
-        readonly totalSize?: number;
-    }) => Effect.Effect<ObjectMeta, StorageError>;
-    /**
-     * Read a byte range `[start, endInclusive]` (HTTP Range / fd offset). Enables
-     * seekable + resumable reads. OPTIONAL and best-effort: whole-object resume
-     * already works via content-addressing (skip an asset whose hash is present
-     * at the target), so this is an optimisation, not a correctness requirement.
-     */
-    readonly getRange?: (key: string, start: number, endInclusive: number) => Effect.Effect<Uint8Array, StorageError>;
-    /** Providers that store bytes via the app's DataStore (e.g. `database`)
-     *  receive it here once it exists — bound by the plugin at boot. */
-    readonly bindDataStore?: (store: unknown) => void;
-}
+export { StorageProvider }
 
-export declare type StorageProviderName = 's3' | 'minio' | 'azure' | 'filesystem' | 'memory' | 'database';
+export { StorageProviderName }
 
 export declare const storagePutIntentsTable: Table<"_voltro_storage_put_intents", FieldDefinitions<{
     readonly id: ColumnBuilder<string, "text", boolean>;
     readonly refId: ColumnBuilder<string, "text", boolean>;
-    readonly identity: ColumnBuilder<StorageObjectIdentity, "json", boolean>;
+    readonly storageInstance: ColumnBuilder<string | null, "text", boolean>;
+    readonly objectNamespace: ColumnBuilder<string | null, "text", boolean>;
+    readonly identity: ColumnBuilder<ScopedStorageObjectIdentity, "json", boolean>;
     readonly ref: ColumnBuilder<StorageRef, "json", boolean>;
 }>, false, never>;
 
@@ -1103,8 +1350,38 @@ export declare interface StorageRef {
     readonly derivedFrom?: string | null;
     /** Derivative label — e.g. `'rendition'` / `'poster'`; null on an original. */
     readonly kind?: string | null;
+    /** Immutable provenance for an attested transcode; absent on older/unproven refs. */
+    readonly renditionProof?: RenditionProof | null;
+}
+
+/** Persisted destination ownership is independent of the current write selection. */
+export declare const storageRefAddress: (ref: Pick<StorageRef, "bucket" | "tenantId" | "key">) => StorageAddress;
+
+export declare const storageReferenceCatalogueTable: Table<"_voltro_storage_reference_catalogue", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "text", boolean>;
+    readonly namespace: ColumnBuilder<string, "text", boolean>;
+}>, false, never>;
+
+export declare interface StorageReferenceInstanceAssignment {
+    readonly refId: string;
+    readonly storageInstance: string;
+}
+
+/** A plugin instance may retain several tenant-specific physical destinations.
+ * Resolve the concrete namespace at the boundary; never substitute a sentinel
+ * namespace for a tenant-scoped connection. */
+export declare interface StorageReferenceResolver {
+    readonly storageInstance: string;
+    readonly resolveNamespace: (address: StorageAddress) => Effect.Effect<string, StorageError>;
+}
+
+export declare interface StorageReferenceScope {
+    readonly storageInstance: string;
+    readonly objectNamespace: string;
 }
 
+export declare type StorageReferenceView = StorageReferenceScope | StorageReferenceResolver;
+
 /** An upload was rejected by a constraint (size / content-type / magic-byte
  *  mismatch). `reason` is a stable code; `detail` is human-readable. */
 export declare class StorageRejected extends StorageRejected_base {
@@ -1139,6 +1416,9 @@ export declare interface StorageScanResult {
     readonly threat?: string;
 }
 
+/** A secret, or the set a rotation keeps accepting (the signing one first). */
+declare type StorageSecrets = string | ReadonlyArray<string>;
+
 export declare class StorageService extends StorageService_base {
 }
 
@@ -1151,6 +1431,12 @@ export declare interface StorageServiceOptions {
     readonly refStore: RefStore;
     readonly grantStore: GrantStore;
     readonly bucket: string;
+    /** New writes select a destination; reads retain SQL destination/tenant ownership. */
+    readonly destinations?: StorageDestinationRouter;
+    /** App-owned resolution of each persisted physical reference owner. */
+    readonly resolveObjectReference?: (reference: StorageObjectReference) => Effect.Effect<StorageProvider, StorageError>;
+    /** Canonical plugin instance; separates new plain keys on a shared provider. */
+    readonly storageInstance?: string;
     /** Static prefix prepended to every key (e.g. an app/env namespace). */
     readonly tenantPrefix?: string;
     /** Transient-failure retries (429 / 5xx / network). Default 3. */
@@ -1203,6 +1489,20 @@ export declare interface StorageServiceOptions {
 
 /** The service handlers consume: `const storage = yield* StorageService`. */
 export declare interface StorageServiceShape {
+    /** Trusted server read of one raw durable put identity in this configured
+     * instance/physical namespace/bucket and the explicitly supplied tenant.
+     * No access-policy check, claim, byte read, retry write or provider HEAD.
+     * Unbound/unsupported/corrupt metadata refuses; it never becomes absence. */
+    readonly operationStatus: (input: {
+        readonly operationId: string;
+        readonly tenantId: string | null;
+        readonly destination?: string;
+    }) => Effect.Effect<StorageOperationStatus, StorageError>;
+    /** Opaque destination binding for manually signed upload-family credentials. */
+    readonly uploadTicketScope: (input?: {
+        readonly tenantId?: string | null;
+        readonly destination?: string;
+    }) => Effect.Effect<string, StorageError>;
     /** Store bytes. The result is the ref plus this call's `outcome`. */
     readonly put: (input: PutInput) => Effect.Effect<StoredRef, StorageError | StorageRejected | StorageScanRejected>;
     /** Fetch an object's bytes by id. Enforces the tenant guard ONLY — it does
@@ -1373,9 +1673,9 @@ export declare interface StorageServiceShape {
         readonly contentType: string;
         readonly tenantId?: string | null;
         readonly expiresInSec?: number;
-    }) => Effect.Effect<{
+    }) => Effect.Effect<StorageAddress & {
+        readonly writeScope: string;
         readonly uploadUrl: string;
-        readonly key: string;
         readonly expiresInSec: number;
     }, StorageError>;
     /** Promote a blob the client PUT directly to a TEMP `key` into a real ref:
@@ -1384,6 +1684,7 @@ export declare interface StorageServiceShape {
      *  scanned + a non-degraded ref — out of band from the direct PUT. On a scan
      *  reject the temp bytes are deleted (fail-closed, nothing promoted). */
     readonly finalizeUpload: (input: {
+        readonly destination: string;
         readonly key: string;
         readonly contentType: string;
         readonly tenantId?: string | null;
@@ -1398,6 +1699,7 @@ export declare interface StorageServiceShape {
     /** Store one chunk of a resumable upload as its own durable `_incoming/<id>/
      *  <index>` object. Idempotent — re-PUTting the same index overwrites it. */
     readonly putResumableChunk: (input: {
+        readonly destination: string;
         readonly uploadId: string;
         readonly index: number;
         readonly bytes: Uint8Array;
@@ -1407,6 +1709,7 @@ export declare interface StorageServiceShape {
      *  0 and returns the received byte `offset` + the `nextIndex` to send. Lets a
      *  reconnecting client resume instead of restarting. */
     readonly resumableStatus: (input: {
+        readonly destination: string;
         readonly uploadId: string;
         readonly tenantId?: string | null;
     }) => Effect.Effect<{
@@ -1417,6 +1720,7 @@ export declare interface StorageServiceShape {
      *  concatenate, run the FULL `put()` pipeline, then delete the chunk objects
      *  (on success AND on reject — fail-closed). */
     readonly finalizeResumable: (input: {
+        readonly destination: string;
         readonly uploadId: string;
         readonly count: number;
         readonly contentType: string;
@@ -1448,12 +1752,14 @@ export declare interface StorageServiceShape {
         readonly tenantId?: string | null;
         readonly visibility?: StorageVisibility;
         readonly expiresInSec?: number;
-    }) => Effect.Effect<{
+    }) => Effect.Effect<StorageAddress & {
+        readonly writeScope: string;
         readonly uploadId: string;
-        readonly key: string;
     }, StorageError>;
     /** Presign a PUT for one part (1-based `partNumber`). */
     readonly signMultipartPart: (input: {
+        readonly destination: string;
+        readonly tenantId: string | null;
         readonly key: string;
         readonly uploadId: string;
         readonly partNumber: number;
@@ -1463,6 +1769,7 @@ export declare interface StorageServiceShape {
      *  registered straight from it (size via HEAD, etag as checksum). No fetch-back,
      *  so NO scan/derivatives — scan multi-GB out of band. */
     readonly completeMultipart: (input: {
+        readonly destination: string;
         readonly key: string;
         readonly uploadId: string;
         readonly parts: ReadonlyArray<{
@@ -1481,20 +1788,36 @@ export declare interface StorageServiceShape {
     }) => Effect.Effect<StorageRef, StorageError | StorageRejected>;
     /** Abort a multipart session (client cancelled) — frees the bucket's parts. */
     readonly abortMultipart: (input: {
+        readonly destination: string;
+        readonly tenantId: string | null;
         readonly key: string;
         readonly uploadId: string;
     }) => Effect.Effect<void, StorageError>;
 }
 
+/** Trusted build-input metadata, not a delivery DTO or access grant. The
+ * caller persists this alongside its immutable publication/recipe selection. */
+export declare interface StorageSourcePin {
+    readonly version: 1;
+    readonly instance: string;
+    readonly tenantId: string | null;
+    readonly bucket: string;
+    readonly id: string;
+    readonly sourceDigest: string;
+    readonly checksum: string;
+    readonly size: number;
+    readonly contentType: string;
+    readonly derivedFrom: string | null;
+    readonly kind: string | null;
+    readonly renditionProof: RenditionProof | null;
+    readonly digest: string;
+}
+
 /** `public` = anyone, served direct from bucket/CDN; `private` = gated by
  *  the ref's access policy + grants. Default for a new put is `private`. */
 export declare type StorageVisibility = 'public' | 'private';
 
-/** Bytes + content type as returned by a provider `get`. */
-export declare interface StoredObject {
-    readonly bytes: Uint8Array;
-    readonly contentType: string;
-}
+export { StoredObject }
 
 /** What `put` returns: the stored ref, plus what this call did to it. The
  *  `outcome` is a fact about the CALL, not the row — it is never persisted and
@@ -1503,13 +1826,7 @@ export declare type StoredRef = StorageRef & {
     readonly outcome: PutOutcome;
 };
 
-/** A streamed read from a provider — the object as a {@link ByteStream} plus
- *  its content type and, when the backend reports it up front, its size. */
-export declare interface StoredStream {
-    readonly stream: ByteStream;
-    readonly contentType: string;
-    readonly size?: number;
-}
+export { StoredStream }
 
 /**
  * A ByteStream → Node `Readable`, for SDK uploaders that consume Node streams
@@ -1531,9 +1848,7 @@ export declare type Transcoder = (input: {
     readonly ref: StorageRef;
 }) => ReadonlyArray<Rendition> | Promise<ReadonlyArray<Rendition>> | Effect.Effect<ReadonlyArray<Rendition>>;
 
-/** Transform with a small FIFO cache keyed by `(refId, params)` so repeated
- *  requests for the same variant don't re-encode. */
-export declare const transformCached: (refId: string, bytes: Uint8Array, contentType: string, params: TransformParams) => Promise<Transformed | null>;
+export declare const transformCached: (addressIdentity: string, bytes: Uint8Array, contentType: string, params: TransformParams) => Promise<Transformed | null>;
 
 export declare interface Transformed {
     readonly bytes: Uint8Array;
@@ -1587,13 +1902,17 @@ export declare interface UploadLimits {
  *  owner/tenant/content-type/visibility, until `exp`. */
 export declare interface UploadTicketPayload {
     /** Frozen-policy ticket contract. Previous tickets must be minted again. */
-    readonly version: 1;
+    readonly version: 2;
     /** Optional durable write identity, preserved across ticket renewal. */
     readonly operationId?: string;
-    /** Inspect uploads may be pinned to their issuing process. */
-    readonly replicaId?: string;
+    /** Exact reference catalogue and physical byte destination authorized by the issuer. */
+    readonly writeScope: string;
+    /** Optional signed routing hint for the binary relay; destination authorization still uses writeScope. */
+    readonly issuerReplicaId?: string;
     /** Exact storage plugin instance authorized to accept the bytes. */
     readonly instance: string;
+    /** Logical destination selected before issuing the upload/session. */
+    readonly destination: string;
     /** ownerId (subject id) the stored object is attributed to. */
     readonly sub: string | null;
     /** tenantId that scopes the key prefix + ref row. */
@@ -1624,28 +1943,28 @@ export declare interface UsageDelta {
 
 /** Verify a finalize token. Returns the payload on success, null on any failure
  *  (malformed, bad signature, expired, missing temp key). Never throws. */
-export declare const verifyFinalizeTicket: (token: string, secret?: string) => FinalizeTicketPayload | null;
+export declare const verifyFinalizeTicket: (token: string, secret?: StorageSecrets) => FinalizeTicketPayload | null;
 
 /**
  * Verify a grant token. Returns the payload on success, null on any
  * failure (malformed, bad signature, expired). Never throws.
  */
-export declare const verifyGrant: (token: string, secret?: string) => GrantTokenPayload | null;
+export declare const verifyGrant: (token: string, secret?: StorageSecrets) => GrantTokenPayload | null;
 
 /** Verify a multipart ticket. Returns the payload on success, null on any
  *  failure (malformed, bad signature, expired, missing key/uploadId). */
-export declare const verifyMultipartTicket: (token: string, secret?: string) => MultipartTicketPayload | null;
+export declare const verifyMultipartTicket: (token: string, secret?: StorageSecrets) => MultipartTicketPayload | null;
 
 /** Constant-time check of a plaintext password against a stored hash. */
 export declare const verifyPassword: (password: string | undefined, stored: string | null) => boolean;
 
 /** Verify a resumable ticket. Returns the payload on success, null on any
  *  failure (malformed, bad signature, expired, missing id/size). Never throws. */
-export declare const verifyResumableTicket: (token: string, secret?: string) => ResumableTicketPayload | null;
+export declare const verifyResumableTicket: (token: string, secret?: StorageSecrets) => ResumableTicketPayload | null;
 
 /** Verify an upload ticket. Returns the payload on success, null on any
  *  failure (malformed, bad signature, expired). Never throws. */
-export declare const verifyUploadTicket: (token: string, secret?: string) => UploadTicketPayload | null;
+export declare const verifyUploadTicket: (token: string, secret?: StorageSecrets) => UploadTicketPayload | null;
 
 /**
  * App-supplied media probe for video/audio uploads. The core deliberately does
@@ -1690,4 +2009,7 @@ export declare const _voltroStorageUsageTable: TableLike;
  */
 export declare const withStorage: () => ReturnType<typeof mixin>;
 
+/** All keyed operations share the same namespace, including presigned and multipart paths. */
+export declare const withStorageKeyPrefix: (provider: StorageProvider, prefix?: string) => StorageProvider;
+
 export { }