@pithy-sh/media 0.1.0

package/src/record/d1Store.ts

@@ -0,0 +1,95 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { z } from "zod";
+import { MEDIA_ASSETS_TABLE, type MediaDatabase } from "../data/tables";
+import { MediaNotFoundError } from "../error/errors";
+import type { ListRecordsOptions, MediaRecord, RecordStore } from "./store";
+
+/** Default page size for {@link RecordStore.list}. */
+const DEFAULT_LIMIT = 50;
+
+/** The row shape after `schema.encode` — a bag of SQLite-primitive columns. */
+type EncodedRow = Record<string, unknown>;
+
+/**
+ * The D1-backed record store — the default. Records live in `pithy_media_assets`, one row each, read
+ * and written through the effective schema's codecs (dates ↔ ms-epoch, booleans ↔ 0|1). Extension
+ * columns ride along automatically: `schema.encode` includes them and Kysely writes every key present,
+ * so an adopter's fields persist with no store changes. Derived text (`transcription`, `extractedText`)
+ * is a real column, so it is queryable — the reason D1 is the default store.
+ */
+export function d1RecordStore(db: MediaDatabase, schema: z.ZodObject): RecordStore {
+  /** Decode a raw D1 row into a validated record. */
+  const decode = (row: unknown): MediaRecord => schema.parse(row) as MediaRecord;
+
+  /** Encode an app-shape record into its SQLite row. */
+  const encode = (record: MediaRecord): EncodedRow => schema.encode(record) as EncodedRow;
+
+  const table = db.selectFrom(MEDIA_ASSETS_TABLE);
+
+  return {
+    async create(record) {
+      const row = encode(record);
+      // Kysely writes every runtime key on the object, so extension columns are inserted too; the cast
+      // narrows the compile-time type to the base table without dropping those keys at runtime.
+      await db
+        .insertInto(MEDIA_ASSETS_TABLE)
+        .values(row as never)
+        .execute();
+      return decode(row);
+    },
+
+    async get(id) {
+      const row = await table.selectAll().where("id", "=", id).executeTakeFirst();
+      return row ? decode(row) : null;
+    },
+
+    async patch(id, changes) {
+      const existing = await table.selectAll().where("id", "=", id).executeTakeFirst();
+      if (!existing) {
+        throw new MediaNotFoundError({ detail: `no media record to patch for id ${id}` });
+      }
+      const merged = { ...(decode(existing) as object), ...(changes as object) } as MediaRecord;
+      const row = encode(merged);
+      await db
+        .updateTable(MEDIA_ASSETS_TABLE)
+        .set(row as never)
+        .where("id", "=", id)
+        .execute();
+      return decode(row);
+    },
+
+    async delete(id) {
+      await db.deleteFrom(MEDIA_ASSETS_TABLE).where("id", "=", id).execute();
+    },
+
+    async list(options: ListRecordsOptions = {}) {
+      const limit = options.limit ?? DEFAULT_LIMIT;
+      const offset = decodeCursor(options.cursor);
+      let query = table.selectAll();
+      if (options.type) query = query.where("type", "=", options.type);
+      const rows = await query
+        .orderBy("createdAt", "desc")
+        .orderBy("id", "desc")
+        .limit(limit + 1)
+        .offset(offset)
+        .execute();
+      const items = rows.slice(0, limit).map(decode);
+      const cursor = rows.length > limit ? encodeCursor(offset + limit) : undefined;
+      return { items, cursor };
+    },
+  };
+}
+
+/** Encode an integer offset as an opaque cursor string. */
+function encodeCursor(offset: number): string {
+  return String(offset);
+}
+
+/** Decode an opaque cursor back to an integer offset; a missing or malformed cursor starts at 0. */
+function decodeCursor(cursor: string | undefined): number {
+  if (!cursor) return 0;
+  const parsed = Number.parseInt(cursor, 10);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
+}

package/src/record/hashStore.ts

@@ -0,0 +1,104 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import type { MediaType } from "../data/enums";
+import { MediaHash } from "../data/mediaHash";
+import { MEDIA_HASHES_TABLE, mediaHashDatabase } from "../data/tables";
+
+/**
+ * The dedup hash store — always D1, independent of where records live. Written on finalize, read by
+ * duplicate search, deleted with the record. Keeping it in its own table (not on the record, not in KV)
+ * is what makes `sha256` exact-match and `phash` near-duplicate detection work in every configuration.
+ */
+
+/** The hash to persist for one media record. */
+export interface HashEntry {
+  /** The media record id. */
+  mediaId: string;
+  /** The media type — scopes the near-duplicate scan to images. */
+  mediaType: MediaType;
+  /** Lowercase-hex SHA-256 of the file. */
+  sha256: string;
+  /** Perceptual hash for near-duplicate images; null/undefined for other types. */
+  phash?: string | null;
+}
+
+/** A `{ mediaId, phash }` pair for near-duplicate scanning. */
+export interface HashPhashEntry {
+  /** The media record id. */
+  mediaId: string;
+  /** The record's perceptual hash. */
+  phash: string;
+}
+
+/** A `{ mediaId, mediaType }` pair returned by an exact-match lookup. */
+export interface HashMatch {
+  /** The media record id. */
+  mediaId: string;
+  /** The media type. */
+  mediaType: MediaType;
+}
+
+/** The dedup hash store seam. */
+export interface HashStore {
+  /** Insert or replace the hash for a media record (idempotent per `mediaId`). */
+  upsert(entry: HashEntry): Promise<void>;
+  /** Delete the hash row for a media record. A miss is a no-op. */
+  deleteByMedia(mediaId: string): Promise<void>;
+  /** Every record whose `sha256` exactly matches — the exact-duplicate lookup. */
+  findBySha256(sha256: string): Promise<HashMatch[]>;
+  /** Every image record carrying a perceptual hash — the bounded set the near-duplicate scan compares. */
+  listImagePhashes(): Promise<HashPhashEntry[]>;
+}
+
+/** Build the D1-backed hash store from the `DB` binding. */
+export function d1HashStore(d1: D1Database, now: () => Date = () => new Date()): HashStore {
+  const db = mediaHashDatabase(d1);
+  return {
+    async upsert(entry) {
+      const row = MediaHash.encode({
+        id: 0, // ignored — auto-increment PK
+        mediaId: entry.mediaId,
+        mediaType: entry.mediaType,
+        sha256: entry.sha256,
+        phash: entry.phash ?? null,
+        createdAt: now(),
+      });
+      // `mediaId` is unique — replace any existing row so a re-finalize doesn't duplicate.
+      await db
+        .insertInto(MEDIA_HASHES_TABLE)
+        .values(row as never)
+        .onConflict((oc) => oc.column("mediaId").doUpdateSet({ sha256: row.sha256, phash: row.phash }))
+        .execute();
+    },
+
+    async deleteByMedia(mediaId) {
+      await db.deleteFrom(MEDIA_HASHES_TABLE).where("mediaId", "=", mediaId).execute();
+    },
+
+    async findBySha256(sha256) {
+      const rows = await db
+        .selectFrom(MEDIA_HASHES_TABLE)
+        .select(["mediaId", "mediaType"])
+        .where("sha256", "=", sha256)
+        .execute();
+      return rows.map((row) => ({ mediaId: row.mediaId, mediaType: row.mediaType as MediaType }));
+    },
+
+    async listImagePhashes() {
+      const rows = await db
+        .selectFrom(MEDIA_HASHES_TABLE)
+        .select(["mediaId", "phash"])
+        .where("mediaType", "=", "image")
+        .where("phash", "is not", null)
+        .execute();
+      const entries: HashPhashEntry[] = [];
+      for (const row of rows) {
+        if (typeof row.phash === "string" && row.phash.length > 0)
+          entries.push({ mediaId: row.mediaId, phash: row.phash });
+      }
+      return entries;
+    },
+  };
+}

package/src/record/kvStore.ts

@@ -0,0 +1,147 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { KVNamespace } from "@cloudflare/workers-types";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { kvMetadata, TypedKv } from "@pithy-sh/core/src/kv/kv";
+import { z } from "zod";
+import { MediaNotFoundError } from "../error/errors";
+import type { ListRecordsOptions, MediaRecord, RecordStore } from "./store";
+
+/** Default page size for {@link RecordStore.list}. */
+const DEFAULT_LIMIT = 50;
+
+/** The KV key: the fixed `media` prefix plus the record id — `media:<id>`. */
+const MediaKey = z
+  .object({ id: z.string().describe("The media record id — the KV key segment.") })
+  .describe("The KV key for a media record: `media:<id>`.");
+
+/** Fields the store always projects into metadata so `list` can filter by type and sort by recency. */
+const REQUIRED_METADATA_FIELDS = ["type", "createdAt"];
+
+/**
+ * The KV-backed record store — the `recordStore: 'kv'` opt-in. Records are typed KV values (`media:<id>`),
+ * validated whole against the effective schema on every read and write, so extension fields round-trip
+ * exactly as in D1 with no columns and no migration.
+ *
+ * KV is a key-value store, not a query engine. `get`/`patch`/`delete` are direct key lookups. `list` is
+ * made scalable by **KV metadata**: `metadataFields` (from `kvMetadata` config) are stored as each entry's
+ * metadata, which rides free on a KV `list` — so `list` filters by type, sorts by recency, and paginates
+ * from metadata alone, then reads only the returned page's values (bounded by the page size, not the
+ * corpus). Put the fields your list views need (an owning `userId`, tags) in `kvMetadata`; KV caps
+ * metadata at 1024 bytes, so keep them small. Duplicate detection is not here — it always uses D1.
+ */
+export function kvRecordStore(namespace: KVNamespace, schema: z.ZodObject, metadataFields: string[] = []): RecordStore {
+  // Always include the fields `list` needs (type, createdAt). Field names are validated against the
+  // effective schema at capability construction (see `assertValidKvMetadata`), so no shape filter here —
+  // the metadata is derived from the value by name, which lets an adopter's extension field ride along
+  // even in the enrichment worker, whose passthrough schema does not carry the extension in its shape.
+  const fields = [...new Set([...REQUIRED_METADATA_FIELDS, ...metadataFields])];
+  // A size-bounded, permissive metadata object: the projected fields (including extension fields the
+  // schema's `shape` may not list) validate as a small denormalized bag for list controls.
+  const metadataSchema = kvMetadata(z.record(z.string(), z.unknown()));
+
+  const kv = new TypedKv(namespace, {
+    prefix: "media",
+    key: MediaKey,
+    value: schema,
+    metadata: metadataSchema,
+    deriveMetadata: (value) => {
+      const record = value as Record<string, unknown>;
+      const meta: Record<string, unknown> = {};
+      for (const field of fields) {
+        if (record[field] !== undefined) meta[field] = record[field];
+      }
+      return meta;
+    },
+  });
+
+  return {
+    async create(record) {
+      await kv.put({ id: String(record.id) }, record);
+      return (await kv.get({ id: String(record.id) })) as MediaRecord;
+    },
+
+    async get(id) {
+      return (await kv.get({ id })) as MediaRecord | null;
+    },
+
+    async patch(id, changes) {
+      const existing = await kv.get({ id });
+      if (!existing) {
+        throw new MediaNotFoundError({ detail: `no media record to patch for id ${id}` });
+      }
+      const merged = { ...(existing as object), ...(changes as object) } as MediaRecord;
+      // A re-derive keeps metadata in step with the merged value.
+      await kv.put({ id }, merged);
+      return merged;
+    },
+
+    async delete(id) {
+      await kv.delete({ id });
+    },
+
+    async list(options: ListRecordsOptions = {}) {
+      const limit = options.limit ?? DEFAULT_LIMIT;
+
+      // List every key with its metadata — cheap, no per-value reads. Filter and sort from metadata.
+      // `createdAt` round-trips through KV as a JSON (ISO) value, so normalize it to an epoch for sorting.
+      const entries: Array<{ id: string; type: unknown; createdAt: number }> = [];
+      let listCursor: string | undefined;
+      do {
+        const page = await kv.list({ cursor: listCursor, limit: 1000 });
+        for (const entry of page.keys) {
+          const meta = entry.metadata as { type?: unknown; createdAt?: unknown } | null;
+          entries.push({ id: entry.key.id, type: meta?.type, createdAt: toEpoch(meta?.createdAt) });
+        }
+        listCursor = page.cursor;
+      } while (listCursor);
+
+      const filtered = options.type ? entries.filter((entry) => entry.type === options.type) : entries;
+      // Newest first — the same order D1 returns.
+      filtered.sort((a, b) => b.createdAt - a.createdAt);
+
+      const offset = decodeCursor(options.cursor);
+      const pageEntries = filtered.slice(offset, offset + limit);
+      // Read only the page's values (bounded by `limit`, not the corpus size).
+      const items: MediaRecord[] = [];
+      for (const entry of pageEntries) {
+        const value = await kv.get({ id: entry.id });
+        if (value) items.push(value as MediaRecord);
+      }
+      const cursor = offset + limit < filtered.length ? String(offset + limit) : undefined;
+      return { items, cursor };
+    },
+  };
+}
+
+/** Decode an opaque cursor back to an integer offset; a missing or malformed cursor starts at 0. */
+function decodeCursor(cursor: string | undefined): number {
+  if (!cursor) return 0;
+  const parsed = Number.parseInt(cursor, 10);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
+}
+
+/** Normalize a metadata `createdAt` (ISO string, epoch number, or Date) to an epoch; 0 when absent/invalid. */
+function toEpoch(value: unknown): number {
+  if (value == null) return 0;
+  const time = new Date(value as string | number | Date).getTime();
+  return Number.isFinite(time) ? time : 0;
+}
+
+/**
+ * Validate the adopter's `kvMetadata` field names against the effective record schema, so a typo or an
+ * unknown field fails fast at capability construction with a clear message — never silently ignored.
+ * Called by `media()`; `type`/`createdAt` are always included by the store and need not be listed.
+ */
+export function assertValidKvMetadata(fields: readonly string[], schema: z.ZodObject): void {
+  const valid = new Set(Object.keys(schema.shape));
+  const unknownFields = fields.filter((field) => !valid.has(field));
+  if (unknownFields.length > 0) {
+    throw new InternalError({
+      message: `Unknown kvMetadata field(s): ${unknownFields.join(", ")}.`,
+      action: "Every kvMetadata entry must be a record field (a base field or one added via media({ extend })).",
+      detail: `Valid record fields: ${[...valid].join(", ")}`,
+    });
+  }
+}

package/src/record/resolve.ts

@@ -0,0 +1,34 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database, KVNamespace } from "@cloudflare/workers-types";
+import type { z } from "zod";
+import type { MediaConfig } from "../config/config";
+import { mediaDatabase } from "../data/tables";
+import { d1RecordStore } from "./d1Store";
+import { d1HashStore, type HashStore } from "./hashStore";
+import { kvRecordStore } from "./kvStore";
+import type { RecordStore } from "./store";
+
+/** The bindings the record store reads from the request env: the app `DB` and the `MEDIA` KV namespace. */
+export interface RecordStoreEnv {
+  /** The app D1 database the `pithy_media_assets` table lives in (used when `recordStore: 'd1'`). */
+  DB: D1Database;
+  /** The KV namespace media records live in (used when `recordStore: 'kv'`). */
+  MEDIA: KVNamespace;
+}
+
+/**
+ * Resolve the configured record store from the request env. `recordStore: 'd1'` (default) builds the
+ * Kysely-backed D1 store; `recordStore: 'kv'` builds the KV-backed store. Both are bound to the effective
+ * schema so extension fields validate and round-trip.
+ */
+export function resolveRecordStore(env: RecordStoreEnv, config: MediaConfig, schema: z.ZodObject): RecordStore {
+  if (config.recordStore === "kv") return kvRecordStore(env.MEDIA, schema, config.kvMetadata);
+  return d1RecordStore(mediaDatabase(env.DB, schema), schema);
+}
+
+/** Resolve the dedup hash store — always the D1 `DB` binding, whatever the record store. */
+export function resolveHashStore(env: RecordStoreEnv, now: () => Date = () => new Date()): HashStore {
+  return d1HashStore(env.DB, now);
+}

package/src/record/store.ts

@@ -0,0 +1,50 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { MediaType } from "../data/enums";
+import type { MediaAsset } from "../data/mediaAsset";
+
+/**
+ * A stored media record: the base {@link MediaAsset} plus whatever fields the adopter added through
+ * `media({ extend })`. The extra fields are unknown at the package's type level but validated at runtime
+ * by the effective schema, so they round-trip through create/get/list unchanged.
+ */
+export type MediaRecord = MediaAsset & Record<string, unknown>;
+
+/** Options for listing records. Filtering by `type` is precise in D1 and a scan-filter in KV. */
+export interface ListRecordsOptions {
+  /** Restrict to one media type. */
+  type?: MediaType;
+  /** Maximum records per page. Defaults to 50. */
+  limit?: number;
+  /** Opaque cursor from a previous page. */
+  cursor?: string;
+}
+
+/** A page of listed records with an optional continuation cursor. */
+export interface RecordPage {
+  /** The records on this page. */
+  items: MediaRecord[];
+  /** Cursor for the next page, or undefined when the listing is complete. */
+  cursor?: string;
+}
+
+/**
+ * The record-store seam: one interface, two backends. `recordStore: 'd1'` (default) persists to the
+ * `pithy_media_assets` table with queryable derived text; `recordStore: 'kv'` persists to a KV namespace
+ * (key lookup; `list` scans, documented as such). Both validate every read and write against the effective
+ * schema, so an adopter's extension fields survive with no backend-specific work. Duplicate detection is
+ * NOT here — it always runs against the D1 {@link HashStore}, independent of the record store.
+ */
+export interface RecordStore {
+  /** Persist a new record. Returns the stored, re-validated record. */
+  create(record: MediaRecord): Promise<MediaRecord>;
+  /** Read a record by id, or null on a miss. */
+  get(id: string): Promise<MediaRecord | null>;
+  /** Merge `changes` over the current record, validate, and write it back. Throws if the id is unknown. */
+  patch(id: string, changes: Partial<MediaRecord>): Promise<MediaRecord>;
+  /** Delete a record by id. A miss is a no-op. */
+  delete(id: string): Promise<void>;
+  /** List records, newest first, optionally filtered by type. */
+  list(options?: ListRecordsOptions): Promise<RecordPage>;
+}

package/src/secret/registry.ts

@@ -0,0 +1,85 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { defineSecretRegistry } from "@pithy-sh/secrets/src/registry";
+import { r2CredentialsRegistry } from "@pithy-sh/storage/src/secret/registry";
+import { z } from "zod";
+
+/**
+ * The secrets the media capability reads (CLAUDE.md §secrets). There are two, because they answer to
+ * two different owners.
+ *
+ * `media-storage-credentials` is media's own: the scoped Cloudflare API token that mints Images and
+ * Stream direct-upload URLs, and the account id it is scoped to. Nothing else.
+ *
+ * `media-r2-credentials` is **declared here and read nowhere in this package**. It is
+ * `@pithy-sh/storage`'s R2 bundle, declared through that package's `r2CredentialsRegistry` factory and
+ * resolved by the `ObjectStore` seam media presigns through. One factory means every declaration of
+ * the name agrees on `backend`, `scope`, `rotatable`, and `valueType` — exactly what
+ * `aggregateSecretRegistries` requires before it will let two capabilities share a name. So media
+ * *names* the R2 secret and never handles an R2 key again.
+ *
+ * The values are **supplied, not minted**: Cloudflare exposes no API for creating an R2 S3 access-key
+ * pair, and the permission catalog carries no Images or Stream keys, so the operator creates both and
+ * hands them to `pithy media provision`. Pithy stores, scopes, and rotates them from there.
+ */
+
+/** The name the Images + Stream credentials are stored and resolved under. */
+export const MEDIA_STORAGE_SECRET = "media-storage-credentials";
+
+/**
+ * Where a human makes the scoped Images + Stream token, and where Cloudflare rolls it.
+ *
+ * **Two pages, because the two axes genuinely differ here.** The kit cannot compose the creation command:
+ * `pithy token mint` works from a permission catalog, and that catalog carries no Images or Stream group,
+ * so an operator picks them in the dashboard. Replacement is not the same act — a Cloudflare API token
+ * rolls through Cloudflare's own API and comes back with its successor, which is what `provider` means
+ * and what the manager's own token already declares.
+ *
+ * This is the pair `media-r2-credentials` does *not* have, and the reason rotation is declared per secret
+ * rather than per issuer: both come from Cloudflare, and only one of them can replace itself.
+ */
+const MEDIA_TOKEN_PAGE = "https://developers.cloudflare.com/fundamentals/api/get-started/create-token/";
+const MEDIA_TOKEN_ROLL = "https://developers.cloudflare.com/api/resources/user/subresources/tokens/methods/update/";
+
+/** The name media's R2 bucket credentials are stored under — the name `objectStore` is pointed at. */
+export const MEDIA_R2_SECRET = "media-r2-credentials";
+
+/** The credential bundle media reads to mint Cloudflare Images and Stream direct-upload URLs. */
+export const MediaStorageCredentials = z
+  .object({
+    apiToken: z
+      .string()
+      .describe("A scoped Cloudflare API token with Images and Stream permissions, for minting direct-upload URLs."),
+    accountId: z.string().describe("The Cloudflare account id the media resources live in."),
+  })
+  .describe("The credentials the media capability reads to mint Cloudflare Images and Stream direct-upload URLs.");
+export type MediaStorageCredentials = z.output<typeof MediaStorageCredentials>;
+
+/**
+ * The R2 half of media's registry — one entry, built by `@pithy-sh/storage`'s factory. Exported on its
+ * own so the provisioner can write the secret against the *declared* schema rather than a second copy
+ * of the shape, which is the only way the two cannot drift.
+ */
+export const mediaR2Registry = r2CredentialsRegistry(MEDIA_R2_SECRET);
+
+/** The media capability's secret-registry slice — aggregated into the shared accessor at startup. */
+export const mediaSecretsRegistry = defineSecretRegistry({
+  [MEDIA_STORAGE_SECRET]: {
+    // An encrypted row in the per-environment secrets D1 — where this value actually lives. No
+    // wrangler template binds it from the Cloudflare Secrets Store; `pithy media provision` writes it
+    // through `dispatchSecretWrite` → the manager Workflow → `SystemSecretsStore`, the D1 path. The
+    // read seam routes strictly on this field, so it has to say where the value really is.
+    backend: "d1",
+    scope: "environment",
+    rotatable: false,
+    valueType: "json",
+    schema: MediaStorageCredentials,
+    origin: { kind: "obtained", issuer: "cloudflare", documentation: MEDIA_TOKEN_PAGE },
+    rotation: { kind: "provider", issuer: "cloudflare", documentation: MEDIA_TOKEN_ROLL },
+  },
+  // Both axes arrive with the entry, from `@pithy-sh/storage`'s factory. Restating them here is how the
+  // two declarations of one name would drift, and `aggregateSecretRegistries` is what would then refuse
+  // to boot a Worker composing both capabilities.
+  ...mediaR2Registry,
+});

package/src/storage/backend.ts

@@ -0,0 +1,29 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { MediaConfig } from "../config/config";
+import type { MediaType, StorageBackend } from "../data/enums";
+
+/**
+ * Resolve which storage backend a media type uses from config. Images and video are configurable
+ * (`r2` | `cf-images`, `r2` | `cf-stream`); audio and documents are always R2.
+ */
+export function backendForType(type: MediaType, config: MediaConfig): StorageBackend {
+  switch (type) {
+    case "image":
+      return config.images.store;
+    case "video":
+      return config.video.store;
+    case "audio":
+    case "document":
+      return "r2";
+  }
+}
+
+/**
+ * The R2 object key for a media record: `media/<type>/<id>`. Namespaced under `media/` so a shared
+ * bucket never collides with an adopter's own objects, and partitioned by type for clarity.
+ */
+export function mediaR2Key(type: MediaType, id: string): string {
+  return `media/${type}/${id}`;
+}

package/src/storage/cloudflare.ts

@@ -0,0 +1,77 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { CloudflareImageManager } from "@pithy-sh/cloudflare/src/media/imageManager";
+import { type AssetOwner, withAssetOwnership } from "@pithy-sh/cloudflare/src/media/ownership";
+import type { CloudflareStreamManager } from "@pithy-sh/cloudflare/src/media/streamManager";
+import type { ObjectStore } from "@pithy-sh/storage/src/object/store";
+import { z } from "zod";
+import type { ImageMinter, R2Minter, VideoMinter } from "./minter";
+
+/**
+ * The adapters that fill the {@link ImageMinter}/{@link VideoMinter}/{@link R2Minter} seams.
+ *
+ * Images and Stream are the SDK-friction boundary: this is the only media file that touches the
+ * `@pithy-sh/cloudflare` managers' SDK-typed responses, and it validates the handful of fields it needs
+ * with a local Zod object so an unexpected shape fails loudly rather than surfacing as `undefined`.
+ *
+ * They are also the one boundary where a **name** cannot isolate a project. An R2 key lives inside a
+ * bucket already called `<project>-<env>-media`; an Images id and a Stream uid are minted by
+ * Cloudflare into one account-flat store. So both minters take an {@link AssetOwner} at construction
+ * and stamp it into every asset they create — `withAssetOwnership` merges it **over** the caller's bag,
+ * so a caller can neither omit nor overwrite it.
+ *
+ * R2 is not adapted from an SDK at all. It comes from `@pithy-sh/storage`'s {@link ObjectStore} — the
+ * object-plane seam built to be pointed at a second bucket under a second credential name. Media holds
+ * no `CloudflareR2Manager`, no key pair, and no bucket name; it holds a store it asks for two URLs.
+ */
+
+/** The default max video duration (seconds) CF Stream requires for a direct upload — 6 hours. */
+const STREAM_MAX_DURATION_SECONDS = 21600;
+
+const ImageUploadResponse = z.object({ id: z.string(), uploadURL: z.string() });
+const StreamUploadResponse = z.object({ uid: z.string(), uploadURL: z.string() });
+
+/** Adapt a {@link CloudflareImageManager} to the {@link ImageMinter} seam, stamped for one owner. */
+export function imageMinter(manager: CloudflareImageManager, owner: AssetOwner): ImageMinter {
+  return {
+    async mintDirectUpload(metadata) {
+      const response = ImageUploadResponse.parse(
+        await manager.createDirectUploadUrl({ metadata: withAssetOwnership(owner, metadata) }),
+      );
+      return { id: response.id, uploadUrl: response.uploadURL };
+    },
+    delete: (id) => manager.deleteImage(id),
+  };
+}
+
+/** Adapt a {@link CloudflareStreamManager} to the {@link VideoMinter} seam, stamped for one owner. */
+export function videoMinter(manager: CloudflareStreamManager, owner: AssetOwner): VideoMinter {
+  return {
+    async mintDirectUpload(metadata) {
+      const response = StreamUploadResponse.parse(
+        await manager.createDirectUpload({
+          maxDurationSeconds: STREAM_MAX_DURATION_SECONDS,
+          meta: withAssetOwnership(owner, metadata),
+        }),
+      );
+      return { uid: response.uid, uploadUrl: response.uploadURL };
+    },
+    delete: (uid) => manager.deleteVideo(uid),
+  };
+}
+
+/**
+ * Adapt an {@link ObjectStore} to the {@link R2Minter} seam — the whole of media's R2 wiring.
+ *
+ * Only the presign paths cross here. `deleteObject` and `readR2Object` stay on the `R2Bucket` binding
+ * in `storage.ts`: a binding read needs no credential, makes no round trip to resolve one, and streams
+ * its body, so routing it through the store would cost something and buy nothing. The store's default
+ * expiry (one hour) is the one media wants for both URLs, so neither call names one.
+ */
+export function objectStoreMinter(store: ObjectStore): R2Minter {
+  return {
+    mintUpload: (key, contentType, contentLength) => store.presignPut(key, contentType, contentLength),
+    mintDownload: (key) => store.presignGet(key),
+  };
+}