@voltro/plugin-storage 0.86.0 → 0.87.0

package/dist/transcodeVideo.js

@@ -1,53 +1,91 @@
-import { join as e } from "node:path";
-import { spawn as t } from "node:child_process";
-import { mkdtemp as n, readFile as r, rm as i, writeFile as a } from "node:fs/promises";
-import { tmpdir as o } from "node:os";
+import { createHash as e } from "node:crypto";
+import { join as t } from "node:path";
+import { canonicalJson as n } from "@voltro/protocol";
+import { mkdtemp as r, readFile as i, rm as a, writeFile as o } from "node:fs/promises";
+import { tmpdir as s } from "node:os";
+import { spawn as c } from "node:child_process";
 //#region src/transcodeVideo.ts
-var s = (e, n, r) => new Promise((i, a) => {
-	let o = t(e, [...n], { stdio: [
-		"ignore",
+var l = (e, t, n) => new Promise((r, i) => {
+	let a = c(e, [...t], { stdio: [
 		"ignore",
+		"pipe",
 		"pipe"
-	] }), s = "", c = setTimeout(() => {
-		o.kill("SIGKILL"), a(/* @__PURE__ */ Error("ffmpeg timed out"));
-	}, r);
-	o.stderr?.on("data", (e) => {
-		s += String(e);
-	}), o.on("error", (e) => {
-		clearTimeout(c), a(e);
-	}), o.on("close", (e) => {
-		clearTimeout(c), e === 0 ? i() : a(/* @__PURE__ */ Error(`ffmpeg exited ${String(e)}: ${s.slice(-400)}`));
+	] }), o = "", s = "", l, u = (e) => {
+		l === void 0 && (l = Error(e), a.kill("SIGKILL"));
+	}, d = setTimeout(() => u("ffmpeg timed out"), n);
+	a.stdout?.on("data", (e) => {
+		if (o.length + e.length > 65536) return u("ffmpeg output exceeds its metadata bound");
+		o += String(e);
+	}), a.stderr?.on("data", (e) => {
+		s = (s + String(e)).slice(-400);
+	}), a.on("error", (e) => {
+		clearTimeout(d), i(e);
+	}), a.on("close", (e) => {
+		clearTimeout(d), l === void 0 ? e === 0 ? r(o) : i(/* @__PURE__ */ Error(`ffmpeg exited ${String(e)}: ${s}`)) : i(l);
 	});
-}), c = (t) => async ({ bytes: c }) => {
-	let l = t.ffmpegPath ?? "ffmpeg", u = t.timeoutMs ?? 3e5, d = await n(e(o(), "voltro-tc-")), f = e(d, "in"), p = [];
-	try {
-		await a(f, c);
-		for (let n of t.renditions) {
-			let t = e(d, `out.${n.ext}`);
-			try {
-				await s(l, [
-					"-y",
-					"-i",
-					f,
-					...n.args,
-					t
-				], u);
-				let e = await r(t);
-				p.push({
-					bytes: new Uint8Array(e),
-					contentType: n.contentType,
-					kind: n.kind,
-					...n.label === void 0 ? {} : { label: n.label }
-				}), await i(t, { force: !0 });
-			} catch {}
+}), u = (t) => e("sha256").update(t).digest("hex"), d = (e) => {
+	let t = e.replace(/\r\n/g, "\n").trim(), n = t.split("\n")[0] ?? "";
+	if (!n.startsWith("ffmpeg version ") || n.length > 512) throw Error("ffmpeg version metadata unavailable");
+	return {
+		name: "ffmpeg",
+		version: n.slice(15),
+		digest: u(t)
+	};
+}, f = (e) => {
+	let c = e.ffmpegPath ?? "ffmpeg", f = e.timeoutMs ?? 3e5, p = e.renditions.map((e) => ({
+		...e,
+		args: [...e.args]
+	}));
+	return async ({ bytes: e }) => {
+		let m = await r(t(s(), "voltro-tc-")), h = t(m, "in"), g = [];
+		try {
+			await o(h, e);
+			for (let e of p) {
+				let r = t(m, `out.${e.ext}`);
+				try {
+					let t = performance.now() + f, o = (e) => {
+						let n = Math.ceil(t - performance.now());
+						if (n <= 0) throw Error("ffmpeg rendition timed out");
+						return l(c, e, n);
+					}, s = d(await o(["-version"]));
+					await o([
+						"-y",
+						"-i",
+						h,
+						...e.args,
+						r
+					]);
+					let p = d(await o(["-version"]));
+					if (s.digest !== p.digest) throw Error("ffmpeg build changed during rendition");
+					let m = await i(r);
+					g.push({
+						bytes: new Uint8Array(m),
+						contentType: e.contentType,
+						kind: e.kind,
+						derivation: {
+							engine: s,
+							recipe: {
+								format: "ffmpeg-cli/v1",
+								digest: u(n({
+									kind: e.kind,
+									contentType: e.contentType,
+									ext: e.ext,
+									args: e.args
+								}))
+							}
+						},
+						...e.label === void 0 ? {} : { label: e.label }
+					}), await a(r, { force: !0 });
+				} catch {}
+			}
+		} finally {
+			await a(m, {
+				recursive: !0,
+				force: !0
+			}).catch(() => void 0);
 		}
-	} finally {
-		await i(d, {
-			recursive: !0,
-			force: !0
-		}).catch(() => void 0);
-	}
-	return p;
+		return g;
+	};
 };
 //#endregion
-export { c as ffmpegTranscoder };
+export { f as ffmpegTranscoder };

package/dist/transform.js

@@ -1,6 +1,7 @@
 import { createTransformCache as e } from "./transformCache.js";
+import { createHash as t } from "node:crypto";
 //#region src/transform.ts
-var t = (e, t, n, r, i, a) => {
+var n = (e, t, n, r, i, a) => {
 	let o = n / r, s = Math.min(e, Math.round(t * o)), c = Math.min(t, Math.round(s / o)), l = (e, t) => Math.max(0, Math.min(t, e));
 	return {
 		left: l(Math.round(i * e - s / 2), e - s),
@@ -8,13 +9,13 @@ var t = (e, t, n, r, i, a) => {
 		width: s,
 		height: c
 	};
-}, n = {
+}, r = {
 	webp: "image/webp",
 	avif: "image/avif",
 	jpeg: "image/jpeg",
 	jpg: "image/jpeg",
 	png: "image/png"
-}, r = (e) => {
+}, i = (e) => {
 	if (!e) return null;
 	let t = new URLSearchParams(e), n = (e) => {
 		let n = t.get(e);
@@ -33,28 +34,28 @@ var t = (e, t, n, r, i, a) => {
 		...s ? { fit: s } : {},
 		...l ? { fp: l } : {}
 	};
-}, i = (e) => e.startsWith("image/") && !e.includes("svg"), a, o = async () => (a ??= import("sharp").then((e) => e.default ?? e, () => null), a), s = async (e, t) => t ? null : i(e) ? await o() === null ? "no-sharp" : "failed" : "not-an-image", c = async (e, r, a) => {
-	if (!i(r)) return null;
-	let s = await o();
-	if (!s) return null;
+}, a = (e) => e.startsWith("image/") && !e.includes("svg"), o, s = async () => (o ??= import("sharp").then((e) => e.default ?? e, () => null), o), c = async (e, t) => t ? null : a(e) ? await s() === null ? "no-sharp" : "failed" : "not-an-image", l = async (e, t, i) => {
+	if (!a(t)) return null;
+	let o = await s();
+	if (!o) return null;
 	try {
-		let i = s(Buffer.from(e), { failOn: "none" }), o = a.fit ?? "cover";
-		if (a.fp !== void 0 && a.w !== void 0 && a.h !== void 0 && o === "cover") {
-			let e = await i.metadata();
-			e.width !== void 0 && e.height !== void 0 && (i = i.extract(t(e.width, e.height, a.w, a.h, a.fp.x, a.fp.y)));
+		let a = o(Buffer.from(e), { failOn: "none" }), s = i.fit ?? "cover";
+		if (i.fp !== void 0 && i.w !== void 0 && i.h !== void 0 && s === "cover") {
+			let e = await a.metadata();
+			e.width !== void 0 && e.height !== void 0 && (a = a.extract(n(e.width, e.height, i.w, i.h, i.fp.x, i.fp.y)));
 		}
-		(a.w !== void 0 || a.h !== void 0) && (i = i.resize({
-			...a.w === void 0 ? {} : { width: a.w },
-			...a.h === void 0 ? {} : { height: a.h },
-			fit: a.fit ?? "cover",
+		(i.w !== void 0 || i.h !== void 0) && (a = a.resize({
+			...i.w === void 0 ? {} : { width: i.w },
+			...i.h === void 0 ? {} : { height: i.h },
+			fit: i.fit ?? "cover",
 			withoutEnlargement: !0
 		}));
-		let c = a.format && n[a.format] ? a.format : void 0, l = r;
+		let c = i.format && r[i.format] ? i.format : void 0, l = t;
 		if (c) {
 			let e = c === "jpg" ? "jpeg" : c;
-			i = i.toFormat(e, a.q === void 0 ? {} : { quality: a.q }), l = n[c];
-		} else a.q !== void 0 && (r === "image/jpeg" || r === "image/webp") && (i = i.toFormat(r === "image/webp" ? "webp" : "jpeg", { quality: a.q }));
-		let u = await i.toBuffer();
+			a = a.toFormat(e, i.q === void 0 ? {} : { quality: i.q }), l = r[c];
+		} else i.q !== void 0 && (t === "image/jpeg" || t === "image/webp") && (a = a.toFormat(t === "image/webp" ? "webp" : "jpeg", { quality: i.q }));
+		let u = await a.toBuffer();
 		return {
 			bytes: new Uint8Array(u),
 			contentType: l
@@ -62,9 +63,9 @@ var t = (e, t, n, r, i, a) => {
 	} catch {
 		return null;
 	}
-}, l = async (e, t, n) => {
-	if (!i(t) || n.rotate === void 0 && n.flip !== !0 && n.flop !== !0 && n.grayscale !== !0 && n.crop === void 0) return null;
-	let r = await o();
+}, u = async (e, t, n) => {
+	if (!a(t) || n.rotate === void 0 && n.flip !== !0 && n.flop !== !0 && n.grayscale !== !0 && n.crop === void 0) return null;
+	let r = await s();
 	if (!r) return null;
 	try {
 		let i = r(Buffer.from(e), { failOn: "none" });
@@ -75,7 +76,7 @@ var t = (e, t, n, r, i, a) => {
 	} catch {
 		return null;
 	}
-}, u = e(), d = (e, t, n) => JSON.stringify([
+}, d = (e, t, n) => JSON.stringify([
 	e,
 	t,
 	n.w,
@@ -85,6 +86,9 @@ var t = (e, t, n, r, i, a) => {
 	n.fit,
 	n.fp?.x,
 	n.fp?.y
-]), f = async (e, t, n, r) => u.getOrCreate(d(e, n, r), () => c(t, n, r));
+]), f = () => {
+	let n = e();
+	return async (e, r, i, a) => n.getOrCreate(d(JSON.stringify([e, t("sha256").update(r).digest("hex")]), i, a), () => l(r, i, a));
+}, p = f();
 //#endregion
-export { l as editImage, t as focalRegion, i as isTransformable, o as loadSharp, r as parseTransformParams, f as transformCached, s as transformFallbackReason, c as transformImage, d as transformKey };
+export { f as createTransformCache, u as editImage, n as focalRegion, a as isTransformable, s as loadSharp, i as parseTransformParams, p as transformCached, c as transformFallbackReason, l as transformImage, d as transformKey };

package/dist/types.d.ts

@@ -1,9 +1,21 @@
+import { ByteStream } from '@voltro/kv/storage';
 import { Context } from 'effect';
 import { Effect } from 'effect';
+import { isStorageKey } from '@voltro/kv/storage';
+import { ObjectMeta } from '@voltro/kv/storage';
 import { Schema } from 'effect';
 import { StorageAccessPolicy } from '@voltro/protocol';
 import { StorageAccessRule } from '@voltro/protocol';
-import { Stream } from 'effect';
+import { StorageAddress } from '@voltro/kv/storage';
+import { storageAddressIdentity } 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 { Subject } from '@voltro/protocol';
 import { YieldableError } from 'effect/Cause';
 
@@ -17,14 +29,7 @@ export declare type AccessPolicy = StorageAccessPolicy;
  */
 export declare type AccessRule = StorageAccessRule;
 
-/**
- * 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 }
 
 /** Input to `StorageService.grant`. */
 export declare interface GrantInput {
@@ -40,6 +45,8 @@ export declare type GrantPermission = 'read' | 'write';
 
 export declare type GrantPrincipalType = 'user' | 'group' | 'apiKey';
 
+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)
@@ -75,17 +82,15 @@ export declare interface ListRefsResult {
     readonly nextOffset: number | null;
 }
 
-/** Result of a provider `put` / `head`. */
-export declare interface ObjectMeta {
-    readonly size: number;
-    readonly etag?: string;
-}
+export { ObjectMeta }
 
 /** A ref with the server-only `passwordHash` removed — safe to serialize. */
 export declare type PublicStorageRef = Omit<StorageRef, 'passwordHash'>;
 
 /** 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. */
@@ -148,6 +153,8 @@ export declare type PutOutcome = 'created' | 'resumed' | 'joined';
 /** 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'`. */
@@ -156,6 +163,39 @@ 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;
+}
+
 /**
  * Access to a private object was refused. Distinct from `StorageError` so
  * handlers can tell "not allowed" (403) from "backend blew up" (5xx) and
@@ -169,20 +209,15 @@ declare const StorageAccessDenied_base: Schema.Class<StorageAccessDenied, Schema
     readonly reason: Schema.String;
 }>, YieldableError>;
 
-/**
- * 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 {
-}
+export { StorageAddress }
 
-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 { storageAddressIdentity }
+
+export { StorageDestination }
+
+export { StorageDestinationRouter }
+
+export { StorageError }
 
 /** A persisted, explicit share of one object with one principal. */
 export declare interface StorageGrant {
@@ -202,100 +237,27 @@ export declare type StorageGuard = (ctx: {
     readonly ref: StorageRef;
 }) => boolean | Promise<boolean> | Effect.Effect<boolean>;
 
-/**
- * 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 {
-    /** Stable physical object-key namespace; exclude credentials and plugin aliases. */
-    readonly objectNamespace: Effect.Effect<string, StorageError>;
-    /**
-     * 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 { StorageObjectLocation }
+
+/** 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 type StorageProviderName = 's3' | 'minio' | 'azure' | 'filesystem' | 'memory' | 'database';
+export { StorageProvider }
+
+export { StorageProviderName }
 
 /**
  * Metadata row for a stored blob — the bytes live in object storage; this
@@ -335,8 +297,13 @@ 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;
+
 /** 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 {
@@ -378,8 +345,20 @@ declare const StorageService_base: Context.ServiceClass<StorageService, "@voltro
 
 /** 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: () => Effect.Effect<string, StorageError>;
+    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
@@ -550,9 +529,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:
@@ -561,6 +540,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;
@@ -575,6 +555,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;
@@ -584,6 +565,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<{
@@ -594,6 +576,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;
@@ -625,12 +608,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;
@@ -640,6 +625,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<{
@@ -658,6 +644,8 @@ 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>;
@@ -667,11 +655,7 @@ export declare interface StorageServiceShape {
  *  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
@@ -680,13 +664,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 }
 
 /**
  * App-supplied (or first-party `ffmpegTranscoder`) transcode step. Given a