@pithy-sh/media 0.1.0

package/src/hash/duplicates.ts

@@ -0,0 +1,129 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { MediaType } from "../data/enums";
+import type { HashStore } from "../record/hashStore";
+
+/**
+ * Duplicate detection — one exact key, one fuzzy key.
+ *
+ * Two records are the *same bytes* when their SHA-256 matches: an exact-duplicate is a single equality
+ * lookup. Two images are *visually alike* when their perceptual hashes are close: a near-duplicate is a
+ * Hamming distance under a threshold. This module ports the CMS dedup pass into pithy conventions — the
+ * exact check runs for every type, the fuzzy check runs only for images that carry a perceptual hash.
+ */
+
+/**
+ * The default perceptual-hash distance under which two images count as near-duplicates. A Hamming distance
+ * of `0` is a pixel-identical image; small distances are crops, re-encodes, or watermarks; large distances
+ * are unrelated images. Five is a conservative starting point tuned in the CMS — override per call when a
+ * corpus wants a tighter or looser match.
+ */
+export const SIMILAR_THRESHOLD = 5;
+
+/** How a perceptual-hash distance reads: an exact match, a near match under threshold, or unrelated. */
+export type HammingResult = "identical" | "similar" | "different";
+
+/**
+ * Classify a perceptual-hash distance. `0` is `identical` (the same hash); a distance within `threshold`
+ * is `similar` (a near-duplicate); anything further is `different`. The one place a raw distance becomes a
+ * decision, so the scan and any caller agree on where the lines fall.
+ */
+export function classifyDistance(distance: number, threshold = SIMILAR_THRESHOLD): HammingResult {
+  if (distance === 0) return "identical";
+  if (distance <= threshold) return "similar";
+  return "different";
+}
+
+/**
+ * The Hamming distance between two equal-length hex perceptual hashes: the count of positions whose
+ * characters differ. Both hashes come from the same phash algorithm, so they are always the same length;
+ * a length mismatch means the inputs were produced differently and cannot be compared — an internal
+ * invariant, so it throws rather than returning a meaningless number.
+ */
+export function hammingDistance(a: string, b: string): number {
+  if (a.length !== b.length) {
+    throw new InternalError({
+      message: "Perceptual hashes must be equal length.",
+      detail: `lengths ${a.length} vs ${b.length}`,
+    });
+  }
+  let distance = 0;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) distance++;
+  }
+  return distance;
+}
+
+/** A record that matches the query, with why: `identical` bytes (SHA-256) or a `similar` image (phash). */
+export interface DuplicateCandidate {
+  /** The matching record's id. */
+  id: string;
+  /** The matching record's media type. */
+  mediaType: MediaType;
+  /** The perceptual-hash distance: `0` for an exact byte match, a small count for a near image match. */
+  distance: number;
+  /** Whether the match is the same bytes (`identical`) or a visually close image (`similar`). */
+  kind: "identical" | "similar";
+}
+
+/** The query for a duplicate scan: the new object's hashes, its type, and optional scan tuning. */
+export interface FindDuplicatesParams {
+  /** The SHA-256 of the new object's bytes — the exact-duplicate key. */
+  sha256: string;
+  /** The new image's perceptual hash, when it has one. Absent for non-images; enables the near scan. */
+  phash?: string;
+  /** The new object's media type. The near scan runs only for `image`. */
+  type: MediaType;
+  /** Override the near-match distance threshold. Defaults to {@link SIMILAR_THRESHOLD}. */
+  threshold?: number;
+  /** Cap the number of candidates returned. Defaults to 10, closest first. */
+  limit?: number;
+}
+
+/**
+ * Find the records that duplicate a new object. Runs two passes against the D1 {@link HashStore} — dedup
+ * is always D1, whatever the record store (KV cannot serve these queries):
+ *
+ * 1. **Exact.** Every record with the same SHA-256 is a byte-identical duplicate (`kind: "identical"`,
+ *    `distance: 0`), for any media type.
+ * 2. **Near.** Only for an `image` that carries a `phash`: compare against every stored image phash,
+ *    skipping records already matched exactly and any hash of a different length, and keep the ones whose
+ *    Hamming distance is not `different` (`kind: "similar"`).
+ *
+ * The two sets are combined — exact matches never double-counted as near — sorted closest first (exact
+ * matches lead at distance `0`), and capped to `limit`. Inputs are not mutated.
+ */
+export async function findDuplicates(hashes: HashStore, params: FindDuplicatesParams): Promise<DuplicateCandidate[]> {
+  const threshold = params.threshold ?? SIMILAR_THRESHOLD;
+  const limit = params.limit ?? 10;
+
+  // Pass 1 — exact byte matches by SHA-256. The id → type map also lets pass 2 skip records already exact.
+  const exactMatches = await hashes.findBySha256(params.sha256);
+  const exactIds = new Set<string>();
+  for (const match of exactMatches) exactIds.add(match.mediaId);
+
+  const exact: DuplicateCandidate[] = exactMatches.map((match) => ({
+    id: match.mediaId,
+    mediaType: match.mediaType,
+    distance: 0,
+    kind: "identical",
+  }));
+
+  // Pass 2 — near image matches by perceptual hash. Only when this is an image with a phash to compare.
+  const near: DuplicateCandidate[] = [];
+  if (params.type === "image" && params.phash) {
+    const phash = params.phash;
+    for (const entry of await hashes.listImagePhashes()) {
+      if (exactIds.has(entry.mediaId)) continue;
+      if (entry.phash.length !== phash.length) continue;
+      const distance = hammingDistance(phash, entry.phash);
+      if (classifyDistance(distance, threshold) === "different") continue;
+      near.push({ id: entry.mediaId, mediaType: "image", distance, kind: "similar" });
+    }
+  }
+
+  // Combine, closest first, capped. A stable sort keeps the exact matches (distance 0) ahead of near ones.
+  return [...exact, ...near].sort((a, b) => a.distance - b.distance).slice(0, limit);
+}

package/src/hash/sha256.ts

@@ -0,0 +1,34 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * SHA-256 content hashing — the exact-duplicate key.
+ *
+ * Every stored object gets a SHA-256 of its bytes. Identical uploads produce an identical hash, so an
+ * exact-duplicate check is a single equality lookup on this value (see {@link findDuplicates}). The digest
+ * is computed with Web Crypto (`crypto.subtle`), which is a global in the Workers runtime and on Node 22+
+ * — no import, no dependency, same code everywhere the package runs.
+ */
+
+/** Lowercase hex alphabet, indexed by nibble. Precomputed so the encode loop does no per-byte formatting. */
+const HEX = "0123456789abcdef";
+
+/** Encode raw digest bytes as a lowercase-hex string. Two hex chars per byte, high nibble first. */
+function toHex(bytes: Uint8Array): string {
+  let out = "";
+  for (const byte of bytes) {
+    out += HEX.charAt(byte >> 4) + HEX.charAt(byte & 0x0f);
+  }
+  return out;
+}
+
+/**
+ * Compute the lowercase-hex SHA-256 of a byte payload. Accepts a `Uint8Array` or a raw `ArrayBuffer`, so
+ * a caller can hand over either a decoded view or the buffer straight off an upload. The result is a
+ * stable 64-character hex string — the exact-duplicate key stored on every record.
+ */
+export async function computeSha256(bytes: Uint8Array | ArrayBuffer): Promise<string> {
+  const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  const digest = await crypto.subtle.digest("SHA-256", view);
+  return toHex(new Uint8Array(digest));
+}

package/src/http/dispatch.ts

@@ -0,0 +1,86 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Logger } from "@pithy-sh/core/src/logger/logger";
+import { noopLogger } from "@pithy-sh/core/src/logger/logger";
+import { triggerWorkflow } from "@pithy-sh/core/src/workflow/dispatch";
+import { workflowKey } from "@pithy-sh/core/src/workflow/naming";
+import type { MediaConfig } from "../config/config";
+import { isExtractableDocument } from "../data/enums";
+import { MEDIA_CAPABILITY, mediaWorkflowRegistry } from "../workflows/specs";
+import type { EnrichmentDispatcher } from "./handlers";
+
+/**
+ * A Cloudflare Workflow binding this capability dispatches to. The enrichment Workflows live in the
+ * prebuilt media worker (`workflows/worker.ts`); the app worker holds their bindings and starts an
+ * instance on finalize.
+ */
+export interface EnrichmentWorkflowBinding {
+  /** Start a Workflow instance for one media record. */
+  create(options: { params: { id: string } }): Promise<unknown>;
+}
+
+/** The enrichment Workflow bindings, each optional so a project that disables a feature omits it. */
+export interface EnrichmentBindings {
+  /** Image → alt text / caption. */
+  MEDIA_IMAGE_TO_TEXT?: EnrichmentWorkflowBinding;
+  /** Audio → transcription. */
+  MEDIA_AUDIO_TRANSCRIBE?: EnrichmentWorkflowBinding;
+  /** Video → transcription (Stream readiness + HLS batching). */
+  MEDIA_VIDEO_TRANSCRIBE?: EnrichmentWorkflowBinding;
+  /** Document → extracted text. */
+  MEDIA_DOC_EXTRACT?: EnrichmentWorkflowBinding;
+}
+
+/**
+ * Which job enriches which media type. The binding is no longer named here — the spec map owns it, so
+ * this table only has to answer "what runs for a video?".
+ */
+const JOB_FOR_TYPE = {
+  image: "image-to-text",
+  audio: "audio-transcribe",
+  video: "video-transcribe",
+  document: "doc-extract",
+} as const;
+
+/**
+ * Build the enrichment dispatcher: on finalize it starts the configured Workflow for the record's type,
+ * and only when the feature is enabled. Each AI feature is independently opt-in and a true no-op (no
+ * dispatch, no cost) when disabled.
+ *
+ * Dispatch itself goes through core's {@link triggerWorkflow} rather than reaching for `env.X?.create()`.
+ * That buys two things the hand-rolled version could not: the `{ id }` payload is validated against the
+ * job's own schema before the binding is touched, and an **absent** binding — an unprovisioned project —
+ * is logged rather than silently skipped. Enrichment quietly doing nothing, with no error and no log, was
+ * the harder failure to diagnose by far.
+ */
+export function makeEnrichmentDispatcher(
+  env: EnrichmentBindings,
+  config: MediaConfig,
+  log: Logger = noopLogger,
+): EnrichmentDispatcher {
+  // The bindings are declared as named optional fields for the reader's sake; dispatch reads them by
+  // the spec's binding name, which is what a Worker env is.
+  const bindings = env as unknown as Record<string, unknown>;
+
+  return async (record) => {
+    if (!enabledFor(record.type, record.filename, config)) return;
+    const key = workflowKey(MEDIA_CAPABILITY, JOB_FOR_TYPE[record.type]);
+    await triggerWorkflow(bindings, mediaWorkflowRegistry, key, { id: String(record.id) }, log);
+  };
+}
+
+/** Whether the record's enrichment feature is on — and, for a document, whether the file is extractable. */
+function enabledFor(type: keyof typeof JOB_FOR_TYPE, filename: string, config: MediaConfig): boolean {
+  switch (type) {
+    case "image":
+      return config.images.imageToText;
+    case "audio":
+      return config.audio.transcribe;
+    case "video":
+      return config.video.transcribe;
+    case "document":
+      // Only pdf/doc/docx are extractable — never enqueue a Workflow for an unsupported extension.
+      return config.documents.extractText && isExtractableDocument(filename);
+  }
+}

package/src/http/guard.ts

@@ -0,0 +1,25 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { UnauthorizedError } from "@pithy-sh/core/src/error/pithyError";
+import type { MiddlewareHandler } from "hono";
+
+/**
+ * The media routes' identity gate. Every media route declares the `bearer`/`session` verification
+ * strategy; this middleware enforces it through the core `AuthContext` seam (`c.var.auth`), which
+ * `@pithy-sh/auth` populates. It never validates a credential itself — it only asserts one resolved,
+ * so the media package depends on the seam, not on auth internals. With no auth capability composed,
+ * `c.var.auth` is always null and every media route is denied — the correct default.
+ */
+export function requireAuth(): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    if (!c.var.auth) {
+      throw new UnauthorizedError({
+        message: "Authentication required.",
+        action: "Sign in and retry with a valid session or bearer token.",
+      });
+    }
+    await next();
+  };
+}

package/src/http/handlers.ts

@@ -0,0 +1,205 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { fromZodError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { z } from "zod";
+import type { MediaConfig } from "../config/config";
+import { BASE_COLUMN_NAMES } from "../data/extend";
+import { MediaNotFoundError } from "../error/errors";
+import { findDuplicates } from "../hash/duplicates";
+import type { HashStore } from "../record/hashStore";
+import type { MediaRecord, RecordStore } from "../record/store";
+import { backendForType } from "../storage/backend";
+import type { MediaStorage } from "../storage/storage";
+import type { CreateMediaInput, DuplicatesInput, FinalizeMediaInput, ListMediaQuery } from "./schemas";
+
+/**
+ * The media request handlers — pure functions over injected dependencies, so every branch is unit-tested
+ * against real D1/KV bindings without standing up a Worker. The route shell (`routes.ts`) resolves these
+ * deps from the request env. Every mutating route is gated by `requireAuth` at the router; ownership
+ * scoping is an adopter concern via an extension field (e.g. `userId`).
+ *
+ * Request shape is NOT validated here. Each route declares its own schema with
+ * `zValidator(target, Schema, validationHook)` and hands the handler the already-parsed value, so a
+ * malformed request is rejected before any dependency is resolved. What survives in these handlers is
+ * validation the schema cannot express: the R2 size rule (a cross-field, config-dependent check) and
+ * `validateRecord`, which validates the *assembled* record against the effective (adopter-extended)
+ * schema — neither is a property of the request body alone.
+ */
+
+/** Triggers the configured enrichment Workflow(s) for a finalized record. A no-op when nothing applies. */
+export type EnrichmentDispatcher = (record: MediaRecord) => Promise<void>;
+
+/** The dependencies the handlers need, all injectable. */
+export interface HandlerDeps {
+  /** The record store (D1 or KV), already bound to the effective schema. */
+  store: RecordStore;
+  /** The D1 dedup hash store — written on finalize, queried by duplicate search, cleared on delete. */
+  hashes: HashStore;
+  /** The storage seam (mint, delete, read). */
+  storage: MediaStorage;
+  /** The effective record schema (base + adopter extension) — validates the assembled record. */
+  schema: z.ZodObject;
+  /** The resolved media config. */
+  config: MediaConfig;
+  /** Triggers enrichment Workflows on finalize. */
+  dispatchEnrichment: EnrichmentDispatcher;
+  /** Mints a new record id. */
+  newId: () => string;
+  /** The current time. */
+  now: () => Date;
+}
+
+/** The response to an upload-init: where to upload and the record's coordinates. */
+export interface UploadInitResult {
+  /** The created record id. */
+  id: string;
+  /** The URL the client uploads the bytes to. */
+  uploadUrl: string;
+  /** The backend the bytes will live in. */
+  storageBackend: string;
+  /** The backend-specific storage handle. */
+  storageKey: string;
+}
+
+/**
+ * Extract only the adopter's extension fields from a create body: every key that is NOT a base column.
+ * Excluding the full base column set — not just the client-input keys — is a security boundary: it stops
+ * a client from smuggling a server-owned base field (`id`, `status`, `storageKey`, timestamps, derived
+ * text) in through the extension bag and overriding it (mass assignment).
+ */
+function splitExtension(parsed: Record<string, unknown>): Record<string, unknown> {
+  const extension: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (!BASE_COLUMN_NAMES.has(key)) extension[key] = value;
+  }
+  return extension;
+}
+
+/** Validate an assembled record against the effective schema, mapping a Zod failure to a 400. */
+function validateRecord(schema: z.ZodObject, record: MediaRecord): MediaRecord {
+  const result = schema.safeParse(record);
+  if (!result.success) throw fromZodError(result.error);
+  return result.data as MediaRecord;
+}
+
+/**
+ * Upload-init: mint a direct-upload URL, create a `pending` record (with the client-computed sha256/phash
+ * and any extension fields), and return where to upload. The bytes go straight to the backend — never
+ * through the Worker.
+ */
+export async function createMedia(deps: HandlerDeps, input: CreateMediaInput): Promise<UploadInitResult> {
+  const extension = splitExtension(input);
+  // An R2 presigned PUT signs the content length, so the client must upload exactly that many bytes — a
+  // size is required for any R2-backed upload (audio and documents always; images/video when `store: 'r2'`).
+  if (backendForType(input.type, deps.config) === "r2" && input.size == null) {
+    throw new ValidationError({
+      message: "A file size is required to upload this media type.",
+      detail: `size is required for the R2-backed ${input.type} upload; the presigned PUT signs the content length`,
+    });
+  }
+  const id = deps.newId();
+  const target = await deps.storage.mintUpload({
+    type: input.type,
+    id,
+    contentType: input.contentType,
+    size: input.size ?? undefined,
+  });
+  const now = deps.now();
+  // Server-owned fields are written LAST so the extension bag (already stripped of base keys) can never
+  // override the minted id, the lifecycle status, or the storage coordinates — defense in depth.
+  const record = validateRecord(deps.schema, {
+    ...extension,
+    id,
+    type: input.type,
+    status: "pending",
+    name: input.name,
+    filename: input.filename,
+    contentType: input.contentType,
+    size: input.size ?? null,
+    storageBackend: target.storageBackend,
+    storageKey: target.storageKey,
+    sha256: input.sha256 ?? null,
+    phash: input.phash ?? null,
+    width: input.width ?? null,
+    height: input.height ?? null,
+    altText: null,
+    caption: null,
+    transcription: null,
+    hasTranscription: false,
+    extractedText: null,
+    hasExtractedText: false,
+    createdAt: now,
+    updatedAt: now,
+  } as MediaRecord);
+  await deps.store.create(record);
+  return { id, uploadUrl: target.uploadUrl, storageBackend: target.storageBackend, storageKey: target.storageKey };
+}
+
+/**
+ * Finalize: mark the record `stored`, fold in any client-computed size/sha256/phash, and dispatch the
+ * configured enrichment Workflow(s). Returns the updated record.
+ */
+export async function finalizeMedia(deps: HandlerDeps, id: string, input: FinalizeMediaInput): Promise<MediaRecord> {
+  const existing = await deps.store.get(id);
+  if (!existing) throw new MediaNotFoundError({ detail: `finalize: no media record ${id}` });
+  const changes: Partial<MediaRecord> = { status: "stored", updatedAt: deps.now() };
+  if (input.size != null) changes.size = input.size;
+  if (input.sha256 != null) changes.sha256 = input.sha256;
+  if (input.phash != null) changes.phash = input.phash;
+  const updated = await deps.store.patch(id, changes);
+  // Write the dedup hash to D1 (always) now the upload is confirmed, so duplicate search can find it.
+  const sha256 = typeof updated.sha256 === "string" ? updated.sha256 : null;
+  if (sha256) {
+    const phash = typeof updated.phash === "string" ? updated.phash : null;
+    await deps.hashes.upsert({ mediaId: id, mediaType: updated.type, sha256, phash });
+  }
+  await deps.dispatchEnrichment(updated);
+  return updated;
+}
+
+/** Fetch one record by id, or 404. */
+export async function getMedia(deps: HandlerDeps, id: string): Promise<MediaRecord> {
+  const record = await deps.store.get(id);
+  if (!record) throw new MediaNotFoundError({ detail: `get: no media record ${id}` });
+  return record;
+}
+
+/** List records, newest first, optionally filtered by type. */
+export function listMedia(deps: HandlerDeps, query: ListMediaQuery) {
+  return deps.store.list({ type: query.type, limit: query.limit, cursor: query.cursor });
+}
+
+/** Delete a record and best-effort delete its stored object. */
+export async function deleteMedia(deps: HandlerDeps, id: string): Promise<{ id: string; deleted: true }> {
+  const record = await deps.store.get(id);
+  if (!record) throw new MediaNotFoundError({ detail: `delete: no media record ${id}` });
+  // Best-effort object cleanup — a storage hiccup must not leave the record undeletable.
+  await deps.storage
+    .deleteObject({ storageBackend: record.storageBackend, storageKey: record.storageKey })
+    .catch(() => {});
+  await deps.hashes.deleteByMedia(id);
+  await deps.store.delete(id);
+  return { id, deleted: true };
+}
+
+/**
+ * Find exact (sha256) and near (phash) duplicates of a file. Detection runs against the D1 hash store;
+ * each candidate is then hydrated from the record store so the caller gets the full record (a hash whose
+ * record was deleted out from under it is skipped).
+ */
+export async function searchDuplicates(deps: HandlerDeps, input: DuplicatesInput) {
+  const candidates = await findDuplicates(deps.hashes, {
+    type: input.type,
+    sha256: input.sha256,
+    phash: input.phash,
+    threshold: input.threshold,
+    limit: input.limit,
+  });
+  const matches = [];
+  for (const candidate of candidates) {
+    const record = await deps.store.get(candidate.id);
+    if (record) matches.push({ id: candidate.id, distance: candidate.distance, kind: candidate.kind, record });
+  }
+  return { matches };
+}

package/src/http/routes.ts

@@ -0,0 +1,119 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { zValidator } from "@hono/zod-validator";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { validationHook } from "@pithy-sh/core/src/http/validation";
+import type { Context, Hono } from "hono";
+import type { z } from "zod";
+import type { MediaConfig } from "../config/config";
+import { type RecordStoreEnv, resolveHashStore, resolveRecordStore } from "../record/resolve";
+import { resolveStorage, type StorageEnv } from "../storage/resolve";
+import { type EnrichmentBindings, makeEnrichmentDispatcher } from "./dispatch";
+import { requireAuth } from "./guard";
+import {
+  createMedia,
+  deleteMedia,
+  finalizeMedia,
+  getMedia,
+  type HandlerDeps,
+  listMedia,
+  searchDuplicates,
+} from "./handlers";
+import { CreateMediaInput, DuplicatesInput, FinalizeMediaInput, ListMediaQuery, MediaIdParam } from "./schemas";
+
+/**
+ * The media routes, their declared verification strategies, and what each accepts:
+ *
+ *   POST   /media               → upload-init      (bearer | session) json: CreateMediaInput
+ *   POST   /media/duplicates    → duplicate search (bearer | session) json: DuplicatesInput
+ *   POST   /media/:id/finalize  → finalize upload  (bearer | session) param: MediaIdParam, json: FinalizeMediaInput
+ *   GET    /media/:id           → fetch one        (bearer | session) param: MediaIdParam
+ *   GET    /media               → list             (bearer | session) query: ListMediaQuery
+ *   DELETE /media/:id           → delete           (bearer | session) param: MediaIdParam
+ *
+ * Every route is gated by {@link requireAuth} — there is no public media surface. The validators sit
+ * AFTER the guard on purpose: an unauthenticated request with a malformed body is a 401, not a 400 —
+ * shape is never leaked to a caller who has not been verified. Bytes never proxy through the Worker:
+ * upload-init returns a direct-upload URL the client uploads to. Ownership scoping (e.g. filtering by a
+ * `userId` extension field) is an adopter concern layered over these routes.
+ */
+export interface MediaRoutesOptions {
+  /** The resolved media config. */
+  config: MediaConfig;
+  /** The effective record schema (base + adopter extension). */
+  schema: z.ZodObject;
+  /** The path the routes mount under. Defaults to `/media`. */
+  basePath?: string;
+  /** Test seam: resolve handler deps from the request context. Defaults to the env-based resolver. */
+  resolveDeps?: (c: Context<PithyHonoEnv>) => Promise<HandlerDeps>;
+}
+
+/** The full request env the media routes read. */
+type MediaEnv = RecordStoreEnv & StorageEnv & EnrichmentBindings;
+
+/** Build the default per-request dependency resolver from config and the effective schema. */
+function defaultResolveDeps(
+  config: MediaConfig,
+  schema: z.ZodObject,
+): (c: Context<PithyHonoEnv>) => Promise<HandlerDeps> {
+  return async (c) => {
+    const env = c.env as unknown as MediaEnv;
+    const store = resolveRecordStore(env, config, schema);
+    const hashes = resolveHashStore(env);
+    const storage = await resolveStorage(env, config);
+    return {
+      store,
+      hashes,
+      storage,
+      schema,
+      config,
+      // The request logger, so an enrichment skipped for a missing binding says so in the request's log.
+      dispatchEnrichment: makeEnrichmentDispatcher(env, config, c.var.log),
+      newId: () => crypto.randomUUID(),
+      now: () => new Date(),
+    };
+  };
+}
+
+/** Register the media sub-router. Returned as the capability's `routes` hook. */
+export function registerMediaRoutes(options: MediaRoutesOptions): (app: Hono<PithyHonoEnv>) => void {
+  const base = options.basePath ?? "/media";
+  const resolve = options.resolveDeps ?? defaultResolveDeps(options.config, options.schema);
+
+  return (app) => {
+    app.post(`${base}/duplicates`, requireAuth(), zValidator("json", DuplicatesInput, validationHook), async (c) => {
+      const result = await searchDuplicates(await resolve(c), c.req.valid("json"));
+      return c.json(result);
+    });
+
+    app.post(base, requireAuth(), zValidator("json", CreateMediaInput, validationHook), async (c) => {
+      const result = await createMedia(await resolve(c), c.req.valid("json"));
+      return c.json(result, 201);
+    });
+
+    app.post(
+      `${base}/:id/finalize`,
+      requireAuth(),
+      zValidator("param", MediaIdParam, validationHook),
+      zValidator("json", FinalizeMediaInput, validationHook),
+      async (c) => {
+        const record = await finalizeMedia(await resolve(c), c.req.valid("param").id, c.req.valid("json"));
+        return c.json(record);
+      },
+    );
+
+    app.get(`${base}/:id`, requireAuth(), zValidator("param", MediaIdParam, validationHook), async (c) => {
+      const record = await getMedia(await resolve(c), c.req.valid("param").id);
+      return c.json(record);
+    });
+
+    app.get(base, requireAuth(), zValidator("query", ListMediaQuery, validationHook), async (c) => {
+      return c.json(await listMedia(await resolve(c), c.req.valid("query")));
+    });
+
+    app.delete(`${base}/:id`, requireAuth(), zValidator("param", MediaIdParam, validationHook), async (c) => {
+      return c.json(await deleteMedia(await resolve(c), c.req.valid("param").id));
+    });
+  };
+}