@pithy-sh/media 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pithy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @pithy-sh/media
+
+Store, track, and enrich media on your own Cloudflare account. Images, video, audio, documents. Config picks the backend; the package does the rest.
+
+Bytes never proxy through your Worker — the client uploads straight to Cloudflare.
+
+```sh
+pithy add media
+```
+
+**Documentation: [pithy.sh/docs/capabilities/media](https://pithy.sh/docs/capabilities/media).** Overview, adding it, using it, and the reference: the backends, provisioning, AI enrichment.
+
+_Everything else is on the site. `pithy.sh/docs` is canonical — new prose goes there, not here._
+
+## License
+
+MIT — adopter-side app value. The root `LICENSE` covers it.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@pithy-sh/media",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/media"
+  },
+  "files": [
+    "src",
+    "pithy.manifest.json",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:node": "vitest run --project=node",
+    "test:workers": "vitest run --project=workers",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "dependencies": {
+    "@cloudflare/workers-types": "^5.20260729.1",
+    "@hono/zod-validator": "^0.9.0",
+    "@pithy-sh/cloudflare": "workspace:*",
+    "@pithy-sh/core": "workspace:*",
+    "@pithy-sh/secrets": "workspace:*",
+    "@pithy-sh/storage": "workspace:*",
+    "hono": "^4.13.2",
+    "kysely": "^0.29.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@pithy-sh/tsconfig": "workspace:*",
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "kysely-d1": "^0.4.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.0",
+    "wrangler": "^4.115.0"
+  }
+}

package/pithy.manifest.json

@@ -0,0 +1,85 @@
+{
+  "name": "media",
+  "package": "@pithy-sh/media",
+  "requiredBindings": [
+    { "type": "d1", "name": "DB" },
+    { "type": "r2", "name": "MEDIA_BUCKET" },
+    {
+      "type": "workflow",
+      "name": "MEDIA_IMAGE_TO_TEXT",
+      "job": "image-to-text",
+      "className": "MediaImageToTextWorkflow",
+      "optional": true
+    },
+    {
+      "type": "workflow",
+      "name": "MEDIA_AUDIO_TRANSCRIBE",
+      "job": "audio-transcribe",
+      "className": "MediaAudioTranscribeWorkflow",
+      "optional": true
+    },
+    {
+      "type": "workflow",
+      "name": "MEDIA_VIDEO_TRANSCRIBE",
+      "job": "video-transcribe",
+      "className": "MediaVideoTranscribeWorkflow",
+      "optional": true
+    },
+    {
+      "type": "workflow",
+      "name": "MEDIA_DOC_EXTRACT",
+      "job": "doc-extract",
+      "className": "MediaDocExtractWorkflow",
+      "optional": true
+    }
+  ],
+  "peerCapabilities": ["secrets"],
+  "optionalCapabilities": ["auth"],
+  "migrationNamespace": "media",
+  "secrets": [
+    {
+      "name": "media-storage-credentials",
+      "origin": {
+        "kind": "obtained",
+        "issuer": "cloudflare",
+        "documentation": "https://developers.cloudflare.com/fundamentals/api/get-started/create-token/"
+      },
+      "rotation": {
+        "kind": "provider",
+        "issuer": "cloudflare",
+        "documentation": "https://developers.cloudflare.com/api/resources/user/subresources/tokens/methods/update/"
+      }
+    },
+    {
+      "name": "media-r2-credentials",
+      "origin": {
+        "kind": "obtained",
+        "issuer": "cloudflare",
+        "documentation": "https://developers.cloudflare.com/r2/api/tokens/"
+      },
+      "rotation": {
+        "kind": "manual",
+        "issuer": "cloudflare",
+        "documentation": "https://developers.cloudflare.com/r2/api/tokens/"
+      }
+    }
+  ],
+  "whenToEnable": "Store, track, and enrich media — images (R2 or Cloudflare Images), video (R2 or Cloudflare Stream), audio and documents (R2). Uploads use direct-upload URLs, so bytes never proxy through your Worker. Opt in per type to AI alt text, transcription, and text extraction. Records live in D1 by default (derived text is queryable) or KV — but duplicate detection always uses D1, so the DB binding is required in both modes. R2 presigning runs through @pithy-sh/storage's ObjectStore seam pointed at MEDIA_BUCKET, so media owns no bucket mechanics and none of storage's tables or routes come with it. Storage credentials are read through @pithy-sh/secrets, so the secrets capability is required; the routes need an identity, so add auth too.",
+  "scaffold": [
+    "Ensure the secrets capability is provisioned (`pithy add secrets` then `pithy secrets provision`) — the CF API token and R2 credentials are stored and read through @pithy-sh/secrets.",
+    "Create an R2 S3 access-key pair (R2 → Manage API tokens) and an API token with Images and Stream permissions. Cloudflare exposes no API for minting an R2 key pair, so this pair is yours to create — pithy stores and rotates it, but cannot mint it.",
+    "Run `pithy media provision` — it creates the R2 bucket (and the `MEDIA` KV namespace when `recordStore: 'kv'`), writes two per-environment secrets, and deploys the media enrichment worker hosting the four Workflows for each environment. `media-storage-credentials` holds your Images + Stream API token; `media-r2-credentials` holds the R2 key pair and that environment's bucket, and is read by @pithy-sh/storage's ObjectStore, which media presigns through. Pass the credentials with `--api-token`, `--r2-access-key-id`, and `--r2-secret-access-key`, or set `R2_CREDENTIALS` in `.dev.vars`. Every step is idempotent; re-run it freely.",
+    "Add the `DB` (D1) and `MEDIA_BUCKET` (R2) bindings to each wrangler.jsonc env. `DB` is required in every mode — the dedup hash table (`pithy_media_hashes`) always lives in D1. Add the `MEDIA` KV binding when `recordStore: 'kv'`. Add the enrichment Workflow bindings your app dispatches to on finalize: `MEDIA_IMAGE_TO_TEXT`, `MEDIA_AUDIO_TRANSCRIBE`, `MEDIA_VIDEO_TRANSCRIBE`, `MEDIA_DOC_EXTRACT`.",
+    "Set the `delivery` config (public identifiers) so `mediaUrl(record, delivery)` can build consumer URLs: `imagesAccountHash` (Cloudflare Images), `streamCustomerCode` (Cloudflare Stream), and optionally `r2PublicBaseUrl` (a public R2 bucket; otherwise consumers use a presigned download URL).",
+    "Enable AI enrichment per type in `media({ ... })` in pithy.config.ts — `images.imageToText`, `video.transcribe`, `audio.transcribe`, `documents.extractText` (extraction runs for pdf/doc/docx only). Each is independently opt-in and a no-op (no cost) when off. Override any model with the type's `model` field.",
+    "The media routes require an authenticated caller. Add the auth capability (`pithy add auth`) so `c.var.auth` is populated; without it every media route is denied.",
+    "Extend a media record with your own fields — an owning `userId`, a tenant id, tags — by passing an `extend` Zod object to `media({ extend })`. The extra fields become real D1 columns (a generated migration) or a validated KV value, from that one schema. In KV mode, list them in `kvMetadata` to render them in list views without a per-value read."
+  ],
+  "configOptions": [
+    {
+      "key": "recordStore",
+      "default": "d1",
+      "describe": "Where media records live: `d1` (default — transcriptions and extracted text are queryable) or `kv` (key-lookup only; no text search over derived content). Edit the per-type `images`/`video`/`audio`/`documents` blocks by hand to pick backends and toggle AI enrichment."
+    }
+  ]
+}

package/src/ai/enrich.ts

@@ -0,0 +1,187 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { UpstreamError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import { MediaEnrichmentError } from "../error/errors";
+
+/**
+ * The Workers AI enrichment calls, over the `env.AI` binding (bindings-first — CLAUDE.md §Cloudflare
+ * access). Each is a thin, validated wrapper the enrichment Workflows call: image-to-text (alt text and
+ * captions), speech-to-text (audio and video), and document text extraction. The model id is always a
+ * parameter, defaulted from config, so an adopter swaps a model with no code change.
+ *
+ * The binding is typed structurally as {@link MediaAi} rather than depending on the exact `Ai` shape, so
+ * a test injects a fake and the code never reaches for a global.
+ */
+
+/** The subset of the Workers AI binding this module uses. */
+export interface MediaAi {
+  /** Run a model by id with an input body; the response shape varies per model, so it is `unknown`. */
+  run(model: string, input: Record<string, unknown>): Promise<unknown>;
+  /** Convert documents to markdown. Present on the AI binding; optional here so a fake can omit it. */
+  toMarkdown?: (files: MarkdownFile[], options?: Record<string, unknown>) => Promise<unknown>;
+}
+
+/**
+ * Run one call against the binding, turning a rejection into `core/upstream_failed`.
+ *
+ * **The split this enforces is between a wrong answer and no answer** (pithy-sh/pithy#348). Everything
+ * else in this module raises `media/enrichment_failed`, and every one of those is deterministic: a
+ * shape the schema does not recognize, a conversion the converter refused, a binding with no
+ * `toMarkdown`. A rejection out of the binding is the opposite — Workers AI unreachable, overloaded, or
+ * out of time — and it is the only fault here a second attempt can answer differently.
+ *
+ * The durable step can only act on that difference if it arrives as a code. A raw throw is
+ * `unclassified` to `classifyWorkflowFault`, and unclassified is terminal — so without this the one
+ * retryable fault in enrichment would have been the one that never got a retry, and an asset would
+ * silently keep no alt text because the model was busy for ten seconds.
+ *
+ * The binding's own words go in `detail`, which the HTTP codec strips: an account id or a quota
+ * message is not something a caller asking about their own file should be handed.
+ */
+async function callModel<T>(what: string, call: () => Promise<T>): Promise<T> {
+  try {
+    return await call();
+  } catch (error) {
+    throw new UpstreamError(
+      { message: "The enrichment model could not be reached.", detail: `Workers AI rejected ${what}` },
+      { cause: error },
+    );
+  }
+}
+
+/** A document handed to `toMarkdown`: a name and its bytes as a Blob. */
+export interface MarkdownFile {
+  /** The filename, including extension — the converter picks its parser from this. */
+  name: string;
+  /** The document bytes. */
+  blob: Blob;
+}
+
+/** The default alt-text prompt (concise, ≤ 80 tokens). Ported from the CMS. */
+export const DEFAULT_ALT_TEXT_PROMPT = "Describe this image in a concise sentence suitable for alt text.";
+/** The default caption prompt (longer, ≤ 512 tokens). Ported from the CMS. */
+export const DEFAULT_CAPTION_PROMPT =
+  "Generate a concise caption for this image to be used as a description of the image.";
+
+const ALT_TEXT_MAX_TOKENS = 80;
+const CAPTION_MAX_TOKENS = 512;
+
+/** Chunk size for base64-encoding audio without blowing the call stack. */
+const BASE64_CHUNK = 0x8000;
+
+const ImageToText = z
+  .object({ description: z.string().describe("The model's generated description of the image.") })
+  .describe("The shape of a Workers AI image-to-text response.");
+const Transcription = z
+  .object({ text: z.string().describe("The transcribed speech.") })
+  .describe("The shape of a Workers AI speech-to-text response.");
+const MarkdownResults = z
+  .array(
+    z
+      .object({
+        name: z.string().describe("The source document filename."),
+        format: z.string().describe("`markdown` on success, `error` on failure."),
+        data: z.string().optional().describe("The extracted markdown, when the conversion succeeded."),
+        error: z.string().optional().describe("The failure reason, when the conversion failed."),
+      })
+      .describe("One document's conversion result."),
+  )
+  .describe("The shape of a Workers AI toMarkdown response — one result per document.");
+
+/** The alt text and caption generated for one image. */
+export interface ImageText {
+  /** A concise sentence suitable for an `alt` attribute. */
+  altText: string;
+  /** A longer descriptive caption. */
+  caption: string;
+}
+
+/** Base64-encode bytes in chunks — whisper's documented `audio` input is a base64 string. */
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += BASE64_CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + BASE64_CHUNK));
+  }
+  return btoa(binary);
+}
+
+/** Collapse whitespace/newlines and strip surrounding quotes from a model's text output. */
+function cleanText(value: string): string {
+  return value
+    .replace(/[\r\n]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/^["']+|["']+$/g, "")
+    .trim();
+}
+
+/** Run the vision model once for a given prompt and return its cleaned description. */
+async function describeImage(
+  ai: MediaAi,
+  image: Uint8Array,
+  model: string,
+  prompt: string,
+  maxTokens: number,
+): Promise<string> {
+  const raw = await callModel(`image-to-text with model '${model}'`, () =>
+    ai.run(model, { image: [...image], prompt, max_tokens: maxTokens }),
+  );
+  const parsed = ImageToText.safeParse(raw);
+  if (!parsed.success) {
+    throw new MediaEnrichmentError({ detail: `image-to-text model '${model}' returned an unexpected shape` });
+  }
+  return cleanText(parsed.data.description);
+}
+
+/**
+ * Generate alt text and a caption for an image with a vision model. Two calls (alt text is short,
+ * caption is longer). Returns both; the caller writes them to the record.
+ */
+export async function generateImageText(ai: MediaAi, image: Uint8Array, model: string): Promise<ImageText> {
+  const altText = await describeImage(ai, image, model, DEFAULT_ALT_TEXT_PROMPT, ALT_TEXT_MAX_TOKENS);
+  const caption = await describeImage(ai, image, model, DEFAULT_CAPTION_PROMPT, CAPTION_MAX_TOKENS);
+  return { altText, caption };
+}
+
+/**
+ * Transcribe audio bytes with a speech-to-text model. The bytes are base64-encoded per the model's
+ * documented `audio` string input. Returns the trimmed transcription text.
+ */
+export async function transcribeAudioBytes(ai: MediaAi, bytes: Uint8Array, model: string): Promise<string> {
+  const raw = await callModel(`transcription with model '${model}'`, () =>
+    ai.run(model, { audio: bytesToBase64(bytes) }),
+  );
+  const parsed = Transcription.safeParse(raw);
+  if (!parsed.success) {
+    throw new MediaEnrichmentError({ detail: `transcription model '${model}' returned an unexpected shape` });
+  }
+  return parsed.data.text.trim();
+}
+
+/**
+ * Extract text (markdown) from documents via `env.AI.toMarkdown`. Joins every successful conversion,
+ * throws on any conversion error, and sanitizes the result to a safe character set (the CMS rule).
+ */
+export async function extractMarkdown(ai: MediaAi, files: MarkdownFile[]): Promise<string> {
+  if (!ai.toMarkdown) {
+    throw new MediaEnrichmentError({ detail: "the AI binding does not support toMarkdown" });
+  }
+  const toMarkdown = ai.toMarkdown;
+  const raw = await callModel("a document conversion", () => toMarkdown(files, { pdf: { metadata: false } }));
+  const parsed = MarkdownResults.safeParse(raw);
+  if (!parsed.success) {
+    throw new MediaEnrichmentError({ detail: "toMarkdown returned an unexpected shape" });
+  }
+  const errors = parsed.data.filter((result) => result.format === "error");
+  if (errors.length > 0) {
+    throw new MediaEnrichmentError({ detail: `toMarkdown failed: ${errors.map((e) => e.error ?? e.name).join("; ")}` });
+  }
+  const markdown = parsed.data
+    .filter((result) => result.format === "markdown")
+    .map((result) => result.data ?? "")
+    .join("\n");
+  // The CMS sanitization: keep a conservative printable set, drop control/binary noise.
+  return markdown.replace(/[^\-a-zA-Z0-9\s,.!?\n]/g, "").trim();
+}

package/src/ai/videoBatching.ts

@@ -0,0 +1,130 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * Pure batching and overlap-dedup for video/audio transcription. These functions carry the whole
+ * algorithm the transcription Workflow orchestrates — no Cloudflare imports, no I/O, no clock. The
+ * Workflow fetches a Cloudflare Stream HLS audio rendition, hands its segment list here to decide what
+ * to transcribe as one unit, then stitches the per-group transcripts back together here. Keeping the
+ * logic pure is deliberate: this is the unit-testable core, and the Workflow stays a thin durable shell.
+ *
+ * Ported faithfully from the leed-ai CMS `audioUtils.ts`. The grouping is whole-segment (HLS segments
+ * are the atomic unit — you can only fetch and decode a segment in full), greedy to a target length,
+ * with a deliberate backward overlap so a model that drops or garbles words at a group boundary gets a
+ * second look at that audio in the next group. The overlap is then removed from the text by
+ * `removeOverlapPrefix` so the final transcript reads clean.
+ */
+
+/** One audio segment from a Cloudflare Stream HLS audio rendition: its URI and playback duration. */
+export interface AudioSegment {
+  /** The segment's URI, relative to or absolute against the rendition playlist; the fetch handle. */
+  uri: string;
+  /** The segment's playback duration in seconds, read from the HLS `#EXTINF` tag. */
+  durationSec: number;
+}
+
+/** A group of contiguous segments to transcribe as one unit, with the group's total duration. */
+export interface SegmentGroup {
+  /** The contiguous segments in this group, in playlist order; transcribed together as one request. */
+  segments: AudioSegment[];
+  /** The forward-scan duration of the group in seconds — the sum accumulated before the overlap back-up. */
+  durationSec: number;
+}
+
+/** The length a group grows to before the greedy scan stops. Long enough for coherent context. */
+export const TARGET_GROUP_SEC = 30;
+
+/** The minimum audio each group re-covers from the next, so boundary words are never lost. */
+export const OVERLAP_SEC = 3;
+
+/**
+ * Group contiguous segments into transcription units. Greedy: scan whole segments forward until the
+ * accumulated duration reaches `targetGroupSec`, emit that group, then back up over trailing segments
+ * until at least `overlapSec` of audio will be re-covered by the next group — while always leaving at
+ * least one fresh segment (`i > startIdx + 1`) so the next group makes forward progress and the loop
+ * terminates. Empty input yields no groups.
+ *
+ * `SegmentGroup.durationSec` is the forward-scan total for that group, recorded before the overlap
+ * back-up — it is not recomputed after backing up, matching the CMS behavior exactly.
+ */
+export function groupSegmentsForTranscription(
+  segments: AudioSegment[],
+  targetGroupSec = TARGET_GROUP_SEC,
+  overlapSec = OVERLAP_SEC,
+): SegmentGroup[] {
+  const groups: SegmentGroup[] = [];
+  let i = 0;
+
+  while (i < segments.length) {
+    const startIdx = i;
+    let durationSec = 0;
+
+    // Forward scan: accumulate whole segments until the group reaches the target length.
+    while (i < segments.length && durationSec < targetGroupSec) {
+      const seg = segments[i];
+      if (seg === undefined) break;
+      durationSec += seg.durationSec;
+      i++;
+    }
+
+    groups.push({ segments: segments.slice(startIdx, i), durationSec });
+    if (i >= segments.length) break;
+
+    // Back up so the next group re-covers >= overlapSec of audio, keeping >= 1 fresh segment ahead.
+    let overlapDur = 0;
+    while (i > startIdx + 1 && overlapDur < overlapSec) {
+      i--;
+      const seg = segments[i];
+      if (seg === undefined) break;
+      overlapDur += seg.durationSec;
+    }
+  }
+
+  return groups;
+}
+
+/**
+ * Strip from `curr` the leading words it shares with the trailing words of `prev`. Search the LONGEST
+ * overlap first: try `maxWords` trailing/leading words down to `minWords`, and on the first exact match
+ * (case-insensitive) drop that many leading words from `curr`, returning the trimmed remainder. Below
+ * `minWords` the match is too weak to trust, so on no match at any length `curr` is returned unchanged —
+ * content is never dropped on an uncertain overlap.
+ *
+ * Words split on whitespace with empty tokens ignored. Comparison lowercases both sides, but the kept
+ * words preserve `curr`'s own casing (re-joined with single spaces).
+ */
+export function removeOverlapPrefix(prev: string, curr: string, maxWords = 40, minWords = 3): string {
+  const prevWords = prev.split(/\s+/).filter((w) => w.length > 0);
+  const currWords = curr.split(/\s+/).filter((w) => w.length > 0);
+  const maxN = Math.min(maxWords, prevWords.length, currWords.length);
+
+  for (let n = maxN; n >= minWords; n--) {
+    const tail = prevWords.slice(prevWords.length - n);
+    const head = currWords.slice(0, n);
+    const matches = tail.every((word, idx) => word.toLowerCase() === head[idx]?.toLowerCase());
+    if (matches) return currWords.slice(n).join(" ").trim();
+  }
+
+  return curr;
+}
+
+/**
+ * Stitch overlapping transcripts (one per `SegmentGroup`, in order) into one clean string. Fold left:
+ * seed with the first transcript, then for each subsequent transcript append the remainder that
+ * `removeOverlapPrefix` leaves after removing the run it shares with the text so far — joined with a
+ * single space, and only when that remainder is non-empty. The result is whitespace-normalized (runs of
+ * whitespace collapsed to single spaces, trimmed). Empty input yields an empty string.
+ */
+export function deduplicateOverlappingTranscripts(transcripts: string[]): string {
+  if (transcripts.length === 0) return "";
+
+  let accumulated = transcripts[0] ?? "";
+  for (let idx = 1; idx < transcripts.length; idx++) {
+    const next = transcripts[idx];
+    if (next === undefined) continue;
+    const remainder = removeOverlapPrefix(accumulated, next);
+    if (remainder.length > 0) accumulated += ` ${remainder}`;
+  }
+
+  return accumulated.replace(/\s+/g, " ").trim();
+}

package/src/capability.ts

@@ -0,0 +1,129 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { BindingSpecInput } from "@pithy-sh/core/src/capability/bindings";
+import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
+import type { DatabaseSpecMap } from "@pithy-sh/core/src/data/databases";
+import type { KvNamespaceSpecMap } from "@pithy-sh/core/src/kv/namespaces";
+import { workflowBindings } from "@pithy-sh/core/src/workflow/bindings";
+import type { Migration } from "kysely/migration";
+import type { z } from "zod";
+import { MediaConfig, type MediaConfigInput } from "./config/config";
+import { extendMediaAsset, extensionColumns } from "./data/extend";
+import { mediaTables } from "./data/tables";
+import { registerMediaRoutes } from "./http/routes";
+import { media_0001_init } from "./migrations/0001_init";
+import { mediaExtendMigration } from "./migrations/extend";
+import { assertValidKvMetadata } from "./record/kvStore";
+import { mediaSecretsRegistry } from "./secret/registry";
+import { PACKAGE_VERSION } from "./version.generated";
+import { mediaWorkflows } from "./workflows/specs";
+
+/**
+ * Sort order of the media migrations within the app database, relative to other capabilities (core low,
+ * app high). Unique per database; the registry composes keys like `0350_media_0001_init`.
+ *
+ * Sits after auth (300), which holds it: a media record's `ownerId` names a user, so the table that
+ * users live in should exist first. Media was itself at 300 until this was corrected — `pithy migrate`
+ * threw `duplicate migration order 300 in database "app"` for any project composing both, which is
+ * every project that stores media against an identity.
+ */
+export const MEDIA_MIGRATION_ORDER = 350;
+
+/** The options `media()` accepts: the config, an optional adopter schema extension, and a mount path. */
+export type MediaOptions = MediaConfigInput & {
+  /**
+   * Extend a media record with the adopter's own fields (an owning `userId`, a tenant id, tags), as a
+   * `z.ZodObject`. From this one schema the capability derives real D1 columns (a generated `0002_extend`
+   * migration) or a validated KV value — with no backend-specific work. Base fields are never redefined.
+   */
+  extend?: z.ZodObject;
+  /** The path the routes mount under. Defaults to `/media`. */
+  basePath?: string;
+};
+
+/**
+ * The media capability, with its resolved config and effective record schema attached. The workflow
+ * slice is kept literal so a composed project types `c.var.workflows.trigger("media/image-to-text", …)`
+ * precisely — an unregistered key or a mistyped payload is a compile error, not a 500.
+ */
+export interface MediaCapability
+  extends Capability<DatabaseSpecMap, KvNamespaceSpecMap, "media", typeof mediaWorkflows> {
+  /** The resolved media config. */
+  mediaConfig: MediaConfig;
+  /** The effective record schema (base {@link MediaAsset} plus any adopter extension). */
+  schema: z.ZodObject;
+}
+
+/**
+ * The media capability. It contributes the dedup `pithy_media_hashes` table to the app `DB` for **both**
+ * record stores (duplicate detection is a query workload only D1 can serve), plus the `pithy_media_assets`
+ * table when `recordStore: 'd1'` (KV mode keeps records in KV). It mounts the media routes (upload-init,
+ * finalize, get, list, delete, duplicate search — each gated by auth) and declares the enrichment Workflow
+ * bindings the finalize route dispatches to. The Workflows live in the prebuilt media worker
+ * (`workflows/worker.ts`), deployed per environment by `pithy media provision`.
+ *
+ * The `DB` binding is required in every mode (the hash table lives there). Storage credentials are read
+ * through `@pithy-sh/secrets`, so the `secrets` capability must be composed; the routes need an identity,
+ * so `@pithy-sh/auth` should be composed too — without it, `c.var.auth` is null and every route is denied.
+ */
+export function media(options: MediaOptions = {}): MediaCapability {
+  const { extend, basePath, ...configInput } = options;
+  const resolved = MediaConfig.parse(configInput);
+  const schema = extendMediaAsset(extend);
+  // Fail fast on a typo'd or unknown `kvMetadata` field rather than silently ignoring it.
+  assertValidKvMetadata(resolved.kvMetadata, schema);
+  const isKv = resolved.recordStore === "kv";
+
+  // One authored migration, told what to create: the hash table always (dedup is D1-only), plus the
+  // record table for the D1 record store. The extension columns are generated per adopter from their
+  // own schema, so they arrive as a second, synthesised migration rather than as part of the schema
+  // this package authors — the same shape as `@pithy-sh/auth`'s plugin tables.
+  const migrations: Record<string, Migration> = { "0001_init": media_0001_init({ withAssets: !isKv }) };
+  if (!isKv) {
+    const extendMigration = mediaExtendMigration(extensionColumns(extend));
+    if (extendMigration) migrations["0002_extend"] = extendMigration;
+  }
+
+  const requiredBindings: BindingSpecInput[] = [
+    // The app database — the dedup hash table (both modes) and the record table (D1 mode) live here.
+    { type: "d1", name: "DB" },
+    // The KV namespace records live in, when `recordStore: 'kv'`.
+    ...(isKv ? [{ type: "kv" as const, name: "MEDIA" }] : []),
+    // The R2 bucket the routes read and delete objects through (bindings-first).
+    { type: "r2", name: "MEDIA_BUCKET" },
+    // The enrichment Workflow bindings the finalize route dispatches to, derived from the specs rather
+    // than listed again — one declaration, so a binding rename cannot leave the two disagreeing. Each is
+    // optional: the bindings exist only once `pithy media provision` has deployed the media worker, and
+    // an unprovisioned project must still boot and serve every non-enrichment route.
+    ...workflowBindings(mediaWorkflows),
+  ];
+
+  const capability = defineCapability({
+    name: "media",
+    // The package version this capability ships at, stamped by `scripts/stampVersions.ts` — a Worker
+    // cannot read its own package.json. Reported per capability by the control-plane manifest.
+    version: PACKAGE_VERSION,
+    // Storage credentials are read through @pithy-sh/secrets, so secrets must be composed.
+    dependsOn: ["secrets"],
+    secretRegistry: mediaSecretsRegistry,
+    workflows: mediaWorkflows,
+    requiredBindings,
+    databases: {
+      app: {
+        binding: "DB",
+        tables: mediaTables(schema, { withAssets: !isKv }),
+        migrationOrder: MEDIA_MIGRATION_ORDER,
+        migrations,
+      },
+    },
+    routes: registerMediaRoutes({ config: resolved, schema, basePath }),
+  });
+
+  return Object.assign(capability, { mediaConfig: resolved, schema });
+}
+
+/** Whether a capability is the media capability — carries its resolved config and effective schema. */
+export function isMediaCapability(capability: Capability): capability is MediaCapability {
+  return capability.name === "media" && "mediaConfig" in capability;
+}

package/src/cloudflare-test.d.ts

@@ -0,0 +1,15 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/// <reference types="@cloudflare/vitest-plugin/types" />
+
+// Bindings the Workers-runtime test project provides to `*.workers.test.ts`, matching the Miniflare
+// config in `vitest.workers.config.ts`: the app `DB` database the media tables live in, and the `MEDIA`
+// KV namespace the `recordStore: 'kv'` path uses. `cloudflare:test` types its `env` as `Cloudflare.Env`,
+// so test bindings are declared by augmenting that interface.
+declare namespace Cloudflare {
+  interface Env {
+    DB: D1Database;
+    MEDIA: KVNamespace;
+  }
+}