@voltro/plugin-storage 0.86.0 → 0.87.0

package/dist/renditionProof.js

@@ -0,0 +1,82 @@
+import { StorageError as e } from "./types.js";
+import { retainedSourceDigest as t } from "./sourceIdentity.js";
+import { createHash as n } from "node:crypto";
+import { canonicalJson as r } from "@voltro/protocol";
+//#region src/renditionProof.ts
+var i = (e) => n("sha256").update(r(e)).digest("hex"), a = (e) => n("sha256").update(e).digest("hex"), o = (e) => typeof e == "string" && /^[a-f0-9]{64}$/.test(e), s = (e, t) => typeof e == "string" && e.length > 0 && e.length <= t, c = () => {
+	throw new e({
+		provider: "transcode",
+		message: "Rendition provenance does not match the selected input and stored output",
+		status: 409,
+		transient: !1
+	});
+}, l = (e) => !s(e?.recipe?.format, 128) || !o(e.recipe.digest) || !s(e.engine?.name, 128) || !s(e.engine.version, 512) || !o(e.engine.digest) ? c() : {
+	recipe: {
+		format: e.recipe.format,
+		digest: e.recipe.digest
+	},
+	engine: {
+		name: e.engine.name,
+		version: e.engine.version,
+		digest: e.engine.digest
+	}
+}, u = (e, n, r, u) => {
+	if (r.derivation === void 0) return;
+	let d = a(n);
+	if (!s(e.id, 64) || !s(e.checksum, 512) || e.size !== n.length || !s(e.contentType, 512) || !s(r.contentType, 512)) return c();
+	if (o(e.checksum)) {
+		if (e.checksum !== d) return c();
+	} else if (![u?.before, u?.after].every((t) => t != null && t.size === e.size && t.etag?.replace(/^"|"$/g, "") === e.checksum)) return c();
+	let f = {
+		version: 1,
+		...l(r.derivation),
+		source: {
+			id: e.id,
+			metadataDigest: t(e),
+			checksum: d,
+			size: e.size,
+			contentType: e.contentType
+		},
+		output: {
+			checksum: a(r.bytes),
+			size: r.bytes.length,
+			contentType: r.contentType
+		}
+	};
+	return {
+		...f,
+		digest: i(f)
+	};
+}, d = (e) => {
+	if (e == null) return null;
+	let t = e, n = t.source, r = t.output;
+	if (t.version !== 1 || !o(t.digest) || !n || !r || !s(n.id, 64) || !o(n.metadataDigest) || !o(n.checksum) || !Number.isSafeInteger(n.size) || n.size < 0 || !s(n.contentType, 512) || !o(r.checksum) || !Number.isSafeInteger(r.size) || r.size < 0 || !s(r.contentType, 512)) return c();
+	let a = {
+		version: 1,
+		...l(t),
+		source: {
+			id: n.id,
+			metadataDigest: n.metadataDigest,
+			checksum: n.checksum,
+			size: n.size,
+			contentType: n.contentType
+		},
+		output: {
+			checksum: r.checksum,
+			size: r.size,
+			contentType: r.contentType
+		}
+	};
+	return i(a) === t.digest ? {
+		...a,
+		digest: t.digest
+	} : c();
+}, f = (e, t) => {
+	let n = d(e);
+	return n.source.id !== t.derivedFrom || n.output.checksum !== t.checksum || n.output.size !== t.size || n.output.contentType !== t.contentType ? c() : n;
+}, p = (e) => e.renditionProof == null ? e : {
+	...e,
+	renditionProof: f(e.renditionProof, e)
+};
+//#endregion
+export { f as assertRenditionOutput, l as copyRenditionDerivation, u as makeRenditionProof, p as ownRenditionRef, d as readRenditionProof };

package/dist/retainedCapture.js

@@ -0,0 +1,391 @@
+import { requireStorageReferenceScope as e } from "./storageNamespaces.js";
+import { STORAGE_REFS_TABLE as t } from "./table.js";
+import { storageMetadataError as n } from "./metadataError.js";
+import { makeStorageObjectWriter as r } from "./objectWriter.js";
+import { dataStoreRefStore as i, toRef as a } from "./service.js";
+import { makeStorageObjectMetadata as o } from "./objectMetadata.js";
+import { abandonStorageObject as s } from "./objectAbandon.js";
+import { readRetainedStorageObject as c, retainStorageObject as l, retainedPinMatches as u } from "./retainedObjects.js";
+import { pinStorageSource as d } from "./sourcePin.js";
+import { Effect as f, Schema as p, Stream as m } from "effect";
+import { createHash as h, randomUUID as g } from "node:crypto";
+import { and as _, eq as v, gt as y, integer as b, json as x, table as S, text as C } from "@voltro/database";
+import { canonicalJson as w } from "@voltro/protocol";
+//#region src/retainedCapture.ts
+var T = "_voltro_storage_retained_captures", E = "_voltro_storage_retained_capture_items", D = [S(T, {
+	id: C().maxLength(64),
+	captureId: C().maxLength(64),
+	instance: C().maxLength(256),
+	tenantId: C().maxLength(64).nullable(),
+	bucket: C().maxLength(128),
+	contextDigest: C().maxLength(64),
+	state: C().oneOf([
+		"capturing",
+		"complete",
+		"abandoned"
+	]),
+	nonce: C().maxLength(64),
+	config: x(),
+	count: b(),
+	digest: C().maxLength(64).nullable(),
+	cleanupOrdinal: b().default(0)
+}).primaryKey(["id"]).nonReactive(), S(E, {
+	id: C().maxLength(64),
+	captureId: C().maxLength(64),
+	ordinal: b(),
+	sourceId: C().maxLength(64),
+	sourceDigest: C().maxLength(64),
+	operationId: C().maxLength(64),
+	pin: x().nullable()
+}).primaryKey(["id"]).index("storage_retained_capture_page", ["captureId", "ordinal"]).nonReactive()], O = class extends p.TaggedError()("RetainedCaptureUnavailable", { reason: p.Literals([
+	"scope",
+	"identity",
+	"state",
+	"source",
+	"bounds",
+	"incomplete",
+	"integrity"
+]) }) {}, k = (e) => {
+	throw new O({ reason: e });
+}, A = (e) => ({
+	id: e.id,
+	instance: e.instance,
+	objectNamespace: e.objectNamespace,
+	tenantId: e.tenantId,
+	bucket: e.bucket,
+	contextDigest: e.contextDigest,
+	...e.source === void 0 ? {} : { source: {
+		instance: e.source.instance,
+		objectNamespace: e.source.objectNamespace,
+		bucket: e.source.bucket
+	} }
+}), j = (e) => h("sha256").update(w(e)).digest("hex"), M = (e) => typeof e == "string" && /^[a-f0-9]{64}$/.test(e), N = (e, t) => typeof e == "string" && e.length > 0 && e.length <= t, P = (e) => N(e.id, 64) && N(e.instance, 256) && M(e.objectNamespace) && (e.tenantId === null || N(e.tenantId, 64)) && N(e.bucket, 128) && M(e.contextDigest) && (e.source === void 0 || N(e.source.instance, 256) && M(e.source.objectNamespace) && N(e.source.bucket, 128)), F = (e) => f.tryPromise({
+	try: e,
+	catch: (e) => n(e, "metadata")
+}), I = (e) => j([
+	e.instance,
+	e.objectNamespace,
+	e.tenantId,
+	e.bucket,
+	e.id
+]), L = (e) => `retained-capture:${I(e)}`, R = (e, t) => j([I(e), t]), z = (e, t) => j([
+	"retained-capture/v1",
+	I(e),
+	t
+]), B = async (e, t, n = !1) => {
+	if (!P(t)) return k("scope");
+	let [r] = await e.query({
+		table: T,
+		predicate: v("id", I(t)),
+		order: [],
+		take: 1,
+		skip: void 0,
+		projection: void 0,
+		...n ? { lock: "update" } : {}
+	});
+	if (r === void 0 || r.id !== I(t) || r.captureId !== t.id || r.instance !== t.instance || r.tenantId !== t.tenantId || r.bucket !== t.bucket || r.contextDigest !== t.contextDigest) return k("identity");
+	let i = r.config;
+	return typeof i != "object" || !i || !Number.isSafeInteger(i.maxBytes) || Number(i.maxBytes) < 0 || !Number.isSafeInteger(r.count) || Number(r.count) < 0 || !Number.isSafeInteger(r.cleanupOrdinal) || Number(r.cleanupOrdinal) < 0 || Number(r.cleanupOrdinal) > Number(r.count) || ![
+		"capturing",
+		"complete",
+		"abandoned"
+	].includes(String(r.state)) ? k("integrity") : i.objectNamespace !== t.objectNamespace || w(i.source ?? null) !== w(t.source ?? null) || n && await e.update("_voltro_storage_retained_captures", I(t), { nonce: g() }) === null ? k("identity") : {
+		state: r.state,
+		count: Number(r.count),
+		maxBytes: Number(i.maxBytes),
+		digest: r.digest,
+		cleanupOrdinal: Number(r.cleanupOrdinal)
+	};
+}, V = (e, t) => {
+	if (t.captureId !== I(e) || !N(t.sourceId, 64) || t.id !== R(e, t.sourceId) || t.operationId !== z(e, t.sourceId) || !M(t.sourceDigest) || !Number.isSafeInteger(t.ordinal) || Number(t.ordinal) < 1) return k("integrity");
+	let n = t.pin;
+	return n !== null && (typeof n != "object" || n.version !== 1 || n.tenantId !== e.tenantId || n.bucket !== e.bucket || n.operationId !== t.operationId || n.sourceId !== t.sourceId || n.sourceDigest !== t.sourceDigest || !M(n.checksum) || !N(n.refId, 64) || !Number.isSafeInteger(n.size) || n.size < 0 || !N(n.contentType, 512)) ? k("integrity") : {
+		id: String(t.id),
+		ordinal: Number(t.ordinal),
+		sourceId: t.sourceId,
+		sourceDigest: t.sourceDigest,
+		operationId: String(t.operationId),
+		pin: n
+	};
+}, H = async function* (e, t, n) {
+	let r = 0;
+	for (; r < n;) {
+		let i = await e.query({
+			table: E,
+			predicate: _(v("captureId", I(t)), y("ordinal", r)),
+			order: [{
+				column: "ordinal",
+				direction: "asc"
+			}],
+			take: Math.min(100, n - r),
+			skip: void 0,
+			projection: void 0
+		});
+		if (i.length !== Math.min(100, n - r)) return k("integrity");
+		for (let e of i) {
+			let n = V(t, e);
+			if (n.ordinal !== ++r) return k("integrity");
+			yield n;
+		}
+	}
+}, U = async (n, r, i) => {
+	if (e({
+		storageInstance: r.instance,
+		objectNamespace: r.objectNamespace
+	}), !N(i, 64) || !N(r.instance, 256) || !N(r.bucket, 128) || r.tenantId !== null && !N(r.tenantId, 64)) return k("scope");
+	let [o] = await n.query({
+		table: t,
+		predicate: _(v("id", i), v("storageInstance", r.instance), v("objectNamespace", r.objectNamespace)),
+		lock: "update",
+		order: [],
+		take: 1,
+		skip: void 0,
+		projection: void 0
+	});
+	if (o === void 0) return k("source");
+	let s = a(o);
+	return !N(s.checksum, 512) || !N(s.contentType, 512) ? k("source") : s.tenantId !== r.tenantId || s.bucket !== r.bucket ? k("scope") : d(s, r.instance);
+}, W = async (e, t, n) => {
+	let r = A(t), i = n.maxBytes, a = n.sources;
+	if (!P(r)) return k("scope");
+	if (!Number.isSafeInteger(i) || i < 0) return k("bounds");
+	let [o] = await e.query({
+		table: T,
+		predicate: v("id", I(r)),
+		order: [],
+		take: 1,
+		skip: void 0,
+		projection: void 0
+	});
+	if (o !== void 0) {
+		let t = await B(e, r, !0);
+		return t.maxBytes === i ? t.state === "abandoned" ? k("state") : { count: t.count } : k("identity");
+	}
+	await e.insert(T, {
+		id: I(r),
+		captureId: r.id,
+		instance: r.instance,
+		tenantId: r.tenantId,
+		bucket: r.bucket,
+		contextDigest: r.contextDigest,
+		state: "capturing",
+		config: {
+			maxBytes: i,
+			objectNamespace: r.objectNamespace,
+			...r.source === void 0 ? {} : { source: r.source }
+		},
+		nonce: g(),
+		count: 0,
+		digest: null,
+		cleanupOrdinal: 0
+	});
+	let s = 0;
+	for await (let t of a()) {
+		let n = typeof t == "string" ? void 0 : JSON.parse(w(t)), a = typeof t == "string" ? t : n?.id;
+		if (!N(a, 64)) return k("source");
+		let o = R(r, a), [c] = await e.query({
+			table: E,
+			predicate: v("id", o),
+			order: [],
+			take: 1,
+			skip: void 0,
+			projection: ["id", "sourceDigest"]
+		});
+		if (c !== void 0 && n === void 0) continue;
+		let l = await U(e, {
+			instance: r.source?.instance ?? r.instance,
+			objectNamespace: r.source?.objectNamespace ?? r.objectNamespace,
+			tenantId: r.tenantId,
+			bucket: r.source?.bucket ?? r.bucket
+		}, a);
+		if (n !== void 0 && w(l) !== w(n)) return k("source");
+		if (c !== void 0) {
+			if (c.sourceDigest !== l.sourceDigest) return k("source");
+		} else {
+			if (l.size > i || s === 2147483647) return k("bounds");
+			await e.insert(E, {
+				id: o,
+				captureId: I(r),
+				ordinal: ++s,
+				sourceId: a,
+				sourceDigest: l.sourceDigest,
+				operationId: z(r, a),
+				pin: null
+			});
+		}
+	}
+	return await e.update(T, I(r), { count: s }), { count: s };
+}, G = (e, t) => async (n, r) => {
+	if ((await B(n, e, !0)).state !== "capturing") return k("state");
+	if (r.tenantId !== e.tenantId || r.bucket !== e.bucket || r.operationId !== t.operationId || r.retainedSource?.refId !== t.sourceId || r.retainedSource.digest !== t.sourceDigest) return k("identity");
+}, K = (e, t, n, r, i) => f.gen(function* () {
+	let a = A(n), o = yield* t.objectNamespace;
+	if (o !== a.objectNamespace) return yield* f.fail(new O({ reason: "scope" }));
+	let s = i === void 0 ? o : yield* i.provider.objectNamespace;
+	if (w(a.source ?? {
+		instance: a.instance,
+		objectNamespace: a.objectNamespace,
+		bucket: a.bucket
+	}) !== w(i === void 0 ? {
+		instance: a.instance,
+		objectNamespace: a.objectNamespace,
+		bucket: a.bucket
+	} : {
+		instance: i.instance,
+		objectNamespace: s,
+		bucket: i.bucket
+	})) return yield* f.fail(new O({ reason: "scope" }));
+	let u = yield* F(() => B(e, a));
+	if (u.state === "abandoned") return yield* f.fail(new O({ reason: "state" }));
+	if (u.state === "complete") {
+		if (!M(u.digest)) return yield* f.fail(new O({ reason: "integrity" }));
+		let n = Y(e, {
+			...A(a),
+			count: u.count,
+			digest: u.digest
+		});
+		for (;;) {
+			let r = yield* F(() => n.next());
+			if (r.done) break;
+			let i = yield* c(e, t, r.value, {
+				storageInstance: a.instance,
+				tenantId: a.tenantId,
+				bucket: a.bucket,
+				maxBytes: u.maxBytes
+			});
+			yield* m.runDrain(i.stream);
+		}
+		return;
+	}
+	let d = H(e, a, u.count);
+	for (;;) {
+		let n = yield* F(() => d.next());
+		if (n.done) break;
+		let o = n.value, s = yield* l(e, t, {
+			storageInstance: a.instance,
+			tenantId: a.tenantId,
+			bucket: a.bucket,
+			maxBytes: u.maxBytes,
+			namespace: a.instance,
+			sourceId: o.sourceId,
+			expectedSourceDigest: o.sourceDigest,
+			operationId: o.operationId,
+			claim: L(a),
+			admit: G(a, o),
+			...r === void 0 ? {} : { quota: r },
+			...i === void 0 ? {} : { source: {
+				...i,
+				storageInstance: i.instance
+			} }
+		});
+		yield* F(() => e.transactional(async (e) => {
+			if ((await B(e, a, !0)).state !== "capturing") return k("state");
+			await e.update(E, o.id, { pin: s });
+		}));
+	}
+}), q = async (e, t) => {
+	let n = A(t), r = await B(e, n, !0);
+	if (r.state === "abandoned") return k("state");
+	let a = h("sha256").update(w({
+		...A(n),
+		count: r.count
+	}) + "\n"), s = o(e, {
+		storageInstance: n.instance,
+		objectNamespace: n.objectNamespace
+	});
+	for await (let t of H(e, n, r.count)) {
+		if (t.pin === null) return k("incomplete");
+		let r = await s.operation({
+			tenantId: n.tenantId,
+			bucket: n.bucket,
+			operationId: t.operationId
+		});
+		if (r?.state !== "ready" || !u(t.pin, r.identity, r.ref)) return k("integrity");
+		let o = await f.runPromise(i(e, {
+			storageInstance: n.instance,
+			objectNamespace: n.objectNamespace
+		}).getById(t.pin.refId));
+		if (o === null || o.key !== r.ref.key || !u(t.pin, r.identity, o)) return k("integrity");
+		a.update(j({
+			ordinal: t.ordinal,
+			pin: t.pin
+		}) + "\n");
+	}
+	let c = a.digest("hex");
+	return r.state === "complete" && r.digest !== c ? k("integrity") : (await e.update(T, I(n), {
+		state: "complete",
+		digest: c
+	}), {
+		...A(n),
+		count: r.count,
+		digest: c
+	});
+}, J = (e, t, n) => f.gen(function* () {
+	let i = A(n);
+	if ((yield* t.objectNamespace) !== i.objectNamespace) return yield* f.fail(new O({ reason: "scope" }));
+	let a = yield* F(() => e.transactional(async (e) => {
+		let t = await B(e, i, !0);
+		return await e.update(T, I(i), { state: "abandoned" }), t;
+	})), c = r({
+		metadata: o(e, {
+			storageInstance: i.instance,
+			objectNamespace: i.objectNamespace
+		}),
+		provider: t
+	}), l = a.cleanupOrdinal;
+	for (let n = 0; n < a.count; n++) {
+		let n = l % a.count + 1, r = yield* F(() => e.transactional(async (e) => {
+			let t = await B(e, i, !0);
+			return t.state !== "abandoned" || t.count !== a.count ? k("integrity") : (t.cleanupOrdinal === l && await e.update(T, I(i), { cleanupOrdinal: n }), e.query({
+				table: E,
+				predicate: _(v("captureId", I(i)), v("ordinal", n)),
+				order: [],
+				take: 2,
+				skip: void 0,
+				projection: void 0
+			}));
+		})), o = yield* F(async () => r.length === 1 ? V(i, r[0]) : k("integrity")), u = yield* s(e, t, {
+			storageInstance: i.instance,
+			objectNamespace: i.objectNamespace,
+			tenantId: i.tenantId,
+			bucket: i.bucket,
+			operationId: o.operationId
+		});
+		u.state === "ready" && (yield* c.delete(u.refId, i.tenantId, L(i))), l = n;
+	}
+}), Y = async function* (e, t) {
+	let n = {
+		...A(t),
+		count: t.count,
+		digest: t.digest
+	}, r = await B(e, n);
+	if (r.state !== "complete" || r.digest !== n.digest || r.count !== n.count) return k("state");
+	let i = h("sha256").update(w({
+		...A(n),
+		count: n.count
+	}) + "\n");
+	for await (let t of H(e, n, r.count)) {
+		if (t.pin === null) return k("integrity");
+		i.update(j({
+			ordinal: t.ordinal,
+			pin: t.pin
+		}) + "\n"), yield t.pin;
+	}
+	if (i.digest("hex") !== n.digest) return k("integrity");
+}, X = async (e, t, n) => {
+	let r = await B(e, t);
+	if (r.state !== "complete" || r.digest !== t.digest || r.count !== t.count) return k("state");
+	let [i] = await e.query({
+		table: E,
+		predicate: v("id", R(t, n.sourceId)),
+		order: [],
+		take: 1,
+		skip: void 0,
+		projection: void 0
+	});
+	if (i === void 0) return k("identity");
+	let a = V(t, i);
+	if (a.pin === null || w(a.pin) !== w(n)) return k("integrity");
+};
+//#endregion
+export { T as RETAINED_CAPTURES, E as RETAINED_CAPTURE_ITEMS, O as RetainedCaptureUnavailable, J as abandonRetainedCapture, X as admitRetainedCaptureObject, U as inspectRetainedSource, W as registerRetainedCapture, Y as retainedCaptureItems, D as retainedCaptureTables, K as runRetainedCapture, q as sealRetainedCapture };

package/dist/retainedObjects.js

@@ -0,0 +1,190 @@
+import { StorageError as e } from "./types.js";
+import { getObjectStream as t, putObjectStream as n } from "./streamBridge.js";
+import { storageMetadataError as r } from "./metadataError.js";
+import { filesystemProvider as i } from "./providers.js";
+import { retainedSourceDigest as a } from "./sourceIdentity.js";
+import { makeStorageObjectWriter as o } from "./objectWriter.js";
+import { dataStoreRefStore as s } from "./service.js";
+import { makeAdmittedStorageObjectMetadata as c, makeStorageObjectMetadata as l } from "./objectMetadata.js";
+import { Effect as u, Schema as d, Stream as f } from "effect";
+import { createHash as p } from "node:crypto";
+import { join as m } from "node:path";
+import { canonicalJson as h } from "@voltro/protocol";
+import { mkdtemp as g, rm as _ } from "node:fs/promises";
+import { tmpdir as v } from "node:os";
+//#region src/retainedObjects.ts
+var y = class extends d.TaggedError()("RetainedObjectUnavailable", { reason: d.Literals([
+	"scope",
+	"source",
+	"operation",
+	"integrity",
+	"bounds",
+	"private-storage",
+	"temporary-storage"
+]) }) {}, b = (e) => u.fail(new y({ reason: e })), x = (e) => p("sha256").update(h(e)).digest("hex"), S = (e) => u.tryPromise({
+	try: e,
+	catch: (e) => r(e, "metadata")
+}), C = (e) => typeof e == "string" && /^[a-f0-9]{64}$/.test(e), w = (e) => typeof e == "string" && e.length > 0, T = (e) => (e.tenantId === null || w(e.tenantId)) && w(e.bucket) && Number.isSafeInteger(e.maxBytes) && e.maxBytes >= 0, E = (e, t) => ({
+	version: 1,
+	tenantId: e.tenantId,
+	bucket: e.bucket,
+	operationId: e.operationId,
+	sourceId: e.retainedSource.refId,
+	sourceDigest: e.retainedSource.digest,
+	refId: t.id,
+	checksum: t.checksum,
+	size: t.size,
+	contentType: t.contentType
+}), D = (e, t, n) => e.version === 1 && w(e.sourceId) && C(e.sourceDigest) && C(e.checksum) && Number.isSafeInteger(e.size) && e.size >= 0 && w(e.contentType) && t.retainedSource !== void 0 && h(E(t, n)) === h(e) && n.visibility === "private" && n.ownerId === null && n.passwordHash === null && n.accessPolicy === null && n.derivedFrom == null, O = (t, n, r) => f.suspend(() => {
+	let i = 0, a = p("sha256"), o = () => new e({
+		provider: "integrity",
+		message: "Retained storage bytes do not match their pinned identity",
+		transient: !1,
+		status: 409
+	});
+	return t.pipe(f.mapEffect((e) => u.suspend(() => {
+		if (e.length > n - i) return u.fail(o());
+		let t = Uint8Array.from(e);
+		return i += t.length, a.update(t), u.succeed(t);
+	})), f.concat(f.fromEffect(u.suspend(() => {
+		let e = a.digest("hex");
+		return i !== n || r !== void 0 && e !== r ? u.fail(o()) : u.succeed(/* @__PURE__ */ new Uint8Array());
+	}))));
+}), k = (e, n, r, i) => u.gen(function* () {
+	if (!T(i) || r.tenantId !== i.tenantId || r.bucket !== i.bucket) return yield* b("scope");
+	if (!Number.isSafeInteger(r.size) || r.size < 0 || r.size > i.maxBytes) return yield* b("bounds");
+	let a = yield* n.objectNamespace, o = {
+		storageInstance: i.storageInstance,
+		objectNamespace: a
+	}, c = yield* S(() => l(e, o).operation({
+		tenantId: i.tenantId,
+		bucket: i.bucket,
+		operationId: r.operationId
+	}));
+	if (c === void 0 || c.state !== "ready" || !D(r, c.identity, c.ref)) return yield* b("operation");
+	let d = yield* s(e, o).getById(r.refId);
+	return d === null || !D(r, c.identity, d) || d.key !== c.ref.key ? yield* b("integrity") : n.publicUrl?.(d.key) == null ? {
+		stream: f.unwrap(t(n, d.key).pipe(u.map((e) => O(e.stream, r.size, r.checksum)))),
+		contentType: r.contentType,
+		size: r.size
+	} : yield* b("private-storage");
+}), A = (e, r, d) => u.gen(function* () {
+	if (!T(d) || !w(d.sourceId) || !w(d.operationId) || !w(d.claim) || d.namespace !== void 0 && !w(d.namespace)) return yield* b("scope");
+	let h = (e) => `_retained/${x([
+		d.tenantId,
+		d.bucket,
+		d.namespace ?? null,
+		e
+	])}`;
+	if (d.expectedSourceDigest !== void 0 && !C(d.expectedSourceDigest)) return yield* b("source");
+	let D = yield* r.objectNamespace, A = {
+		storageInstance: d.storageInstance,
+		objectNamespace: D
+	}, j = d.admit === void 0 ? l(e, A) : c(e, A, d.admit), M = o({
+		metadata: j,
+		provider: r
+	}), N = yield* S(() => j.operation(d));
+	if (N !== void 0) {
+		if (N.identity.retainedSource?.refId !== d.sourceId || !C(N.identity.retainedSource.digest) || d.expectedSourceDigest !== void 0 && N.identity.retainedSource.digest !== d.expectedSourceDigest || N.identity.logicalKey !== h(N.identity.checksum) || N.state === "deleting" || N.state === "deleted") return yield* b("operation");
+		let n = E(N.identity, N.ref);
+		if (n.size > d.maxBytes) return yield* b("bounds");
+		if (r.publicUrl?.(N.ref.key) != null) return yield* b("private-storage");
+		if (N.state === "ready") {
+			let t = yield* k(e, r, n, d);
+			return yield* f.runDrain(t.stream), yield* M.putStream({
+				identity: N.identity,
+				ref: N.ref,
+				stream: f.empty,
+				claim: d.claim,
+				...d.quota === void 0 ? {} : { quota: d.quota }
+			}), n;
+		}
+		if ((yield* r.head(N.ref.key)) !== null) {
+			let e = f.unwrap(t(r, N.ref.key).pipe(u.map((e) => e.stream))), n = yield* M.putStream({
+				identity: N.identity,
+				ref: N.ref,
+				stream: e,
+				claim: d.claim,
+				...d.quota === void 0 ? {} : { quota: d.quota }
+			});
+			return E(N.identity, n.ref);
+		}
+	}
+	let P = d.source?.provider ?? r, F = d.source?.bucket ?? d.bucket, I = {
+		storageInstance: d.source?.storageInstance ?? d.storageInstance,
+		objectNamespace: yield* P.objectNamespace
+	}, L = yield* s(e, I).getById(d.sourceId);
+	if (L === null) return yield* b("source");
+	if (L.tenantId !== d.tenantId || L.bucket !== F) return yield* b("scope");
+	if (!Number.isSafeInteger(L.size) || L.size < 0 || L.size > d.maxBytes) return yield* b("bounds");
+	let R = a(L);
+	if (d.expectedSourceDigest !== void 0 && R !== d.expectedSourceDigest) return yield* b("source");
+	if (N !== void 0 && N.identity.retainedSource?.digest !== R) return yield* b("operation");
+	let z = yield* u.tryPromise({
+		try: () => g(m(v(), "voltro-retained-input-")),
+		catch: () => new y({ reason: "temporary-storage" })
+	});
+	return yield* u.gen(function* () {
+		let e = i({ root: z }), a = L.checksum !== "" && !C(L.checksum), o = (e) => e !== void 0 && e.replace(/^"|"$/g, "") === L.checksum;
+		if (a) {
+			let e = yield* P.head(L.key);
+			if (e === null || e.size !== L.size || !o(e.etag)) return yield* b("integrity");
+		}
+		let s = p("sha256"), c = N?.identity.checksum ?? (C(L.checksum) ? L.checksum : void 0), l = f.unwrap(t(P, L.key).pipe(u.map((e) => O(e.stream, L.size, c)))).pipe(f.tap((e) => u.sync(() => {
+			s.update(e);
+		})));
+		if (yield* n(e, "body", l, {
+			contentType: L.contentType,
+			totalSize: L.size
+		}), a) {
+			let e = yield* P.head(L.key);
+			if (e === null || e.size !== L.size || !o(e.etag)) return yield* b("integrity");
+		}
+		let m = s.digest("hex"), g = N?.identity ?? {
+			tenantId: d.tenantId,
+			bucket: d.bucket,
+			operationId: d.operationId,
+			checksum: m,
+			logicalKey: h(m),
+			retainedSource: {
+				refId: L.id,
+				digest: R
+			},
+			fingerprint: x({
+				kind: "retained-storage-input/v1",
+				logicalKey: h(m),
+				sourceDigest: R,
+				checksum: m,
+				size: L.size,
+				contentType: L.contentType
+			})
+		};
+		if (r.publicUrl?.(g.logicalKey) != null) return yield* b("private-storage");
+		let _ = N?.ref ?? {
+			id: "reserved",
+			tenantId: d.tenantId,
+			bucket: d.bucket,
+			key: g.logicalKey,
+			checksum: m,
+			ownerId: null,
+			contentType: L.contentType,
+			size: L.size,
+			visibility: "private",
+			accessPolicy: null,
+			passwordHash: null,
+			createdAt: /* @__PURE__ */ new Date()
+		}, v = f.unwrap(t(e, "body").pipe(u.map((e) => e.stream)));
+		return E(g, (yield* M.putStream({
+			identity: g,
+			ref: _,
+			stream: v,
+			claim: d.claim,
+			...d.quota === void 0 ? {} : { quota: d.quota }
+		})).ref);
+	}).pipe(u.ensuring(u.promise(() => _(z, {
+		recursive: !0,
+		force: !0
+	}))));
+});
+//#endregion
+export { y as RetainedObjectUnavailable, k as readRetainedStorageObject, A as retainStorageObject, D as retainedPinMatches };

package/dist/rpc.d.ts

@@ -3,6 +3,7 @@ import { MutationProcedureDescriptor } from '@voltro/protocol';
 import { PluginRpcClientDescriptor } from '@voltro/protocol';
 import { QueryProcedureDescriptor } from '@voltro/protocol';
 import { Schema } from 'effect';
+import { StorageError } from '@voltro/kv/storage';
 import { YieldableError } from 'effect/Cause';
 
 export declare const abortMultipartUploadDescriptor: ActionProcedureDescriptor<"storage.abortMultipartUpload", Schema.Struct<{
@@ -255,21 +256,6 @@ 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', …)`.
- */
-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>;
-
 /** An upload was rejected by a constraint (size / content-type / magic-byte
  *  mismatch). `reason` is a stable code; `detail` is human-readable. */
 declare class StorageRejected extends StorageRejected_base {