@pithy-sh/media 0.1.0

package/src/storage/minter.ts

@@ -0,0 +1,57 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The storage minting seams — the clean interfaces the media capability depends on. A test injects a
+ * fake minter; the real adapters live in `storage/cloudflare.ts`.
+ *
+ * {@link ImageMinter} and {@link VideoMinter} are adapted from the `@pithy-sh/cloudflare` managers,
+ * decoupled from those managers' SDK-typed returns. Every direct-upload URL is minted through that
+ * client — no hand-rolled `fetch` to the CF API (CLAUDE.md §Cloudflare access).
+ *
+ * {@link R2Minter} is different in kind, and deliberately so: it is not an SDK adapter but the narrow
+ * two-method slice of `@pithy-sh/storage`'s `ObjectStore` that media consumes. Media owns no R2
+ * mechanism — no bucket, no credential, no S3 client. Stating that slice as its own interface is what
+ * keeps `mediaStorage` testable with two async functions instead of a fifteen-method seam, and what
+ * lets the object plane change shape without reaching into media.
+ */
+
+/** Mints a one-time Cloudflare Images direct-upload URL and deletes stored images. */
+export interface ImageMinter {
+  /**
+   * Mint a direct-upload URL; CF assigns the image id, returned as the storage key.
+   *
+   * The bag is the caller's own; the adapter merges the ownership keys over it, so what reaches
+   * Cloudflare always names the owning project and environment (see `cloudflare.ts`).
+   */
+  mintDirectUpload(metadata?: Record<string, string>): Promise<{ id: string; uploadUrl: string }>;
+  /** Delete a stored image by its CF Images id. */
+  delete(id: string): Promise<void>;
+}
+
+/** Mints a Cloudflare Stream direct-upload URL and deletes stored videos. */
+export interface VideoMinter {
+  /**
+   * Mint a direct-upload URL; CF assigns the video uid, returned as the storage key.
+   *
+   * Takes the same metadata bag as {@link ImageMinter} and for the same reason: Stream is
+   * account-flat and keys a video by a Cloudflare-minted uid, so the `meta` object the mint carries
+   * is the only place ownership can live. The adapter merges the project and environment over
+   * whatever the caller passes.
+   */
+  mintDirectUpload(metadata?: Record<string, string>): Promise<{ uid: string; uploadUrl: string }>;
+  /** Delete a stored video by its CF Stream uid. */
+  delete(uid: string): Promise<void>;
+}
+
+/**
+ * The presign contract media consumes from `@pithy-sh/storage`'s `ObjectStore`. Two methods, because
+ * two are all media needs: reads and deletes go through the `R2Bucket` binding instead, which costs no
+ * credential and no round trip (CLAUDE.md §Cloudflare access — bindings inside the Worker, S3 outside).
+ */
+export interface R2Minter {
+  /** Presigned PUT URL for a client to upload bytes straight to R2. */
+  mintUpload(key: string, contentType: string, contentLength: number): Promise<string>;
+  /** Presigned GET URL for reading an object back (enrichment reads audio/documents this way). */
+  mintDownload(key: string): Promise<string>;
+}

package/src/storage/resolve.ts

@@ -0,0 +1,78 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { R2Bucket } from "@cloudflare/workers-types";
+import { CloudflareImageManager } from "@pithy-sh/cloudflare/src/media/imageManager";
+import type { AssetOwner } from "@pithy-sh/cloudflare/src/media/ownership";
+import { CloudflareStreamManager } from "@pithy-sh/cloudflare/src/media/streamManager";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
+import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
+import { objectStore } from "@pithy-sh/storage/src/object/store";
+import type { MediaConfig } from "../config/config";
+import { MEDIA_R2_SECRET, MEDIA_STORAGE_SECRET, mediaSecretsRegistry } from "../secret/registry";
+import { imageMinter, objectStoreMinter, videoMinter } from "./cloudflare";
+import { type MediaStorage, mediaStorage } from "./storage";
+
+/** The env the storage layer reads: the secrets bindings, the `MEDIA_BUCKET` R2 binding, and the owner. */
+export type StorageEnv = SecretsStoreEnv & {
+  /** The R2 bucket binding media objects are read from and deleted through (bindings-first). */
+  MEDIA_BUCKET: R2Bucket;
+  /**
+   * The project name, stamped into every deployed Worker's vars at provision alongside `ENVIRONMENT`
+   * (`resolveWorkflowHost` in `@pithy-sh/core`). It is the owner written into the metadata of every
+   * Cloudflare Images and Stream asset this Worker mints — the only isolation those two account-flat
+   * stores have, since their assets are keyed by a Cloudflare-minted id rather than by a name we choose.
+   */
+  PROJECT?: string;
+};
+
+/**
+ * Who owns the assets this Worker is about to create.
+ *
+ * `ENVIRONMENT` absent means local dev — the same signal `@pithy-sh/secrets` keys its reader on — so
+ * it falls back to `dev`. `PROJECT` has no such fallback and is never guessed: CLAUDE.md §Resource
+ * naming forbids it for names anything must reproduce later, and a sweep is exactly that. Cloudflare
+ * Images and Stream have no local emulation, so even a `pithy dev` upload writes into the shared,
+ * account-wide store — an unstamped asset there is debris nobody can attribute or delete. Refusing to
+ * mint is the smaller failure.
+ */
+export function assetOwner(env: StorageEnv): AssetOwner {
+  const project = env.PROJECT?.trim();
+  if (!project) {
+    throw new InternalError({
+      message: "This Worker cannot mint a Cloudflare Images or Stream upload: it does not know its project.",
+      action: 'Add "PROJECT" to the Worker\'s wrangler.jsonc vars, set to the root pithy.config.ts name.',
+      detail: "media storage env carries no PROJECT var; Images and Stream assets would be unattributable",
+    });
+  }
+  return { project, env: env.ENVIRONMENT ?? "dev" };
+}
+
+/**
+ * Resolve the storage seam from the request env.
+ *
+ * Images and Stream are media's own: the scoped CF API token is read once through the shared
+ * `@pithy-sh/secrets` accessor (never a raw binding) and the two managers are built from it. Both
+ * minters are constructed with {@link assetOwner}, so every asset they mint carries the project and
+ * environment that created it.
+ *
+ * R2 is not. `objectStore` from `@pithy-sh/storage` owns the bucket, the credential, and the S3 client;
+ * media points it at `MEDIA_BUCKET` under its own secret name and consumes two presign methods through
+ * the `R2Minter` port. Nothing here reads an access key. The store resolves that credential
+ * **lazily**, so a request that only reads or deletes — both of which stay on the bucket binding —
+ * never touches the secrets store at all.
+ */
+export async function resolveStorage(env: StorageEnv, config: MediaConfig): Promise<MediaStorage> {
+  const store = await sharedSecretsStore(env, mediaSecretsRegistry);
+  const credentials = store.get(MEDIA_STORAGE_SECRET);
+  const clientConfig = { apiToken: credentials.apiToken, accountId: credentials.accountId };
+  const owner = assetOwner(env);
+  return mediaStorage({
+    image: imageMinter(new CloudflareImageManager(clientConfig), owner),
+    video: videoMinter(new CloudflareStreamManager(clientConfig), owner),
+    r2: objectStoreMinter(objectStore({ bucket: env.MEDIA_BUCKET, env, secretName: MEDIA_R2_SECRET })),
+    bucket: env.MEDIA_BUCKET,
+    config,
+  });
+}

package/src/storage/storage.ts

@@ -0,0 +1,130 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { R2Bucket } from "@cloudflare/workers-types";
+import type { MediaConfig } from "../config/config";
+import type { MediaType, StorageBackend } from "../data/enums";
+import { MediaStorageError, MediaUnsupportedError } from "../error/errors";
+import { backendForType, mediaR2Key } from "./backend";
+import type { ImageMinter, R2Minter, VideoMinter } from "./minter";
+
+/** The minters and bucket binding the storage layer needs, plus the resolved config. */
+export interface StorageDeps {
+  /** Cloudflare Images minter. */
+  image: ImageMinter;
+  /** Cloudflare Stream minter. */
+  video: VideoMinter;
+  /** R2 presigned-URL minter. */
+  r2: R2Minter;
+  /** The R2 bucket binding, for reading and deleting objects (bindings-first). */
+  bucket: R2Bucket;
+  /** The resolved media config — drives per-type backend selection. */
+  config: MediaConfig;
+}
+
+/** What an upload needs: the target the client uploads to, and where the bytes will live. */
+export interface UploadTarget {
+  /** The URL the client uploads the bytes straight to (bytes never proxy through the Worker). */
+  uploadUrl: string;
+  /** The backend the bytes live in. */
+  storageBackend: StorageBackend;
+  /** The backend-specific handle: the R2 object key, the CF Images id, or the CF Stream uid. */
+  storageKey: string;
+}
+
+/** Parameters for minting an upload URL. */
+export interface MintParams {
+  /** The media type — drives backend selection. */
+  type: MediaType;
+  /** The record id, used to build a stable R2 key. */
+  id: string;
+  /** The MIME type, forwarded to the presigned R2 PUT. */
+  contentType: string;
+  /** The declared size in bytes, forwarded to the presigned R2 PUT; 0 when unknown. */
+  size?: number;
+  /**
+   * Small metadata forwarded to the Cloudflare Images or Stream direct upload — the caller's own keys
+   * (identity, album, whatever the adopter tracks). The minters merge the ownership stamp
+   * (`pithyProject`/`pithyEnv`) over it, so nothing here can omit or displace it.
+   */
+  metadata?: Record<string, string>;
+}
+
+/** A record's storage coordinates, enough to read or delete its object. */
+export interface StorageLocation {
+  /** The backend the bytes live in. */
+  storageBackend: StorageBackend;
+  /** The backend-specific handle. */
+  storageKey: string;
+}
+
+/** The storage seam the routes and workflows use: mint an upload, read bytes, delete an object. */
+export interface MediaStorage {
+  /** Mint a direct-upload URL and resolve where the bytes will live. */
+  mintUpload(params: MintParams): Promise<UploadTarget>;
+  /** Delete a stored object (best-effort cleanup when a record is deleted). */
+  deleteObject(location: StorageLocation): Promise<void>;
+  /** Read a stored R2 object's bytes (enrichment reads audio/documents through the binding). */
+  readR2Object(key: string): Promise<Uint8Array>;
+  /**
+   * A presigned, time-limited GET URL for a private R2-backed record — the consumer URL for audio and
+   * documents (and R2-stored images/video). Throws `media/unsupported` for a Cloudflare Images or Stream
+   * record, which have their own delivery URLs (see `deliver/url.ts`).
+   */
+  presignedDownloadUrl(location: StorageLocation): Promise<string>;
+}
+
+/** Build the storage seam over the injected minters, bucket binding, and config. */
+export function mediaStorage(deps: StorageDeps): MediaStorage {
+  return {
+    async mintUpload(params) {
+      const backend = backendForType(params.type, deps.config);
+      try {
+        if (backend === "cf-images") {
+          const result = await deps.image.mintDirectUpload(params.metadata);
+          return { uploadUrl: result.uploadUrl, storageBackend: "cf-images", storageKey: result.id };
+        }
+        if (backend === "cf-stream") {
+          const result = await deps.video.mintDirectUpload(params.metadata);
+          return { uploadUrl: result.uploadUrl, storageBackend: "cf-stream", storageKey: result.uid };
+        }
+        const key = mediaR2Key(params.type, params.id);
+        const uploadUrl = await deps.r2.mintUpload(key, params.contentType, params.size ?? 0);
+        return { uploadUrl, storageBackend: "r2", storageKey: key };
+      } catch (error) {
+        throw new MediaStorageError({ detail: `mint upload failed for ${params.type}` }, { cause: error });
+      }
+    },
+
+    async deleteObject(location) {
+      try {
+        if (location.storageBackend === "cf-images") return await deps.image.delete(location.storageKey);
+        if (location.storageBackend === "cf-stream") return await deps.video.delete(location.storageKey);
+        await deps.bucket.delete(location.storageKey);
+      } catch (error) {
+        throw new MediaStorageError({ detail: `delete object failed for ${location.storageKey}` }, { cause: error });
+      }
+    },
+
+    async readR2Object(key) {
+      const object = await deps.bucket.get(key);
+      if (!object) {
+        throw new MediaStorageError({ detail: `R2 object not found: ${key}` });
+      }
+      return new Uint8Array(await object.arrayBuffer());
+    },
+
+    async presignedDownloadUrl(location) {
+      if (location.storageBackend !== "r2") {
+        throw new MediaUnsupportedError({
+          detail: `presignedDownloadUrl is R2-only; ${location.storageBackend} has its own delivery URL`,
+        });
+      }
+      try {
+        return await deps.r2.mintDownload(location.storageKey);
+      } catch (error) {
+        throw new MediaStorageError({ detail: `presign download failed for ${location.storageKey}` }, { cause: error });
+      }
+    },
+  };
+}

package/src/version.generated.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+// GENERATED by scripts/stampVersions.ts — do not edit by hand. Regenerate with `bun run stamp-versions`.
+//
+// A Worker cannot read its own package.json, so this is how @pithy-sh/media knows its own version at
+// runtime. The capability attaches it, and `GET /control-plane/manifest` reports it per capability —
+// which is what answers "should this project upgrade" and "is this customer exposed to what we just
+// fixed". Those questions are only answerable per module, because a project composes some capabilities
+// and not others.
+
+/** This package's npm name — the join key against a release feed. */
+export const PACKAGE_NAME = "@pithy-sh/media";
+
+/** This package's version, stamped from its own package.json at generation time. */
+export const PACKAGE_VERSION = "0.1.0";

package/src/workflows/enrich.ts

@@ -0,0 +1,116 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { extractMarkdown, generateImageText, type MediaAi, transcribeAudioBytes } from "../ai/enrich";
+import {
+  type AudioSegment,
+  deduplicateOverlappingTranscripts,
+  groupSegmentsForTranscription,
+} from "../ai/videoBatching";
+import type { MediaRecord, RecordStore } from "../record/store";
+
+/**
+ * The enrichment orchestration — the pure, testable core each Workflow step runs. Every function reads a
+ * record, produces derived content with Workers AI, and writes it back through the record store. Byte
+ * access is an injected seam (`readBytes` / `readDocument` / `fetchVideoAudio`) so the orchestration is
+ * exercised against fakes; the Workflow worker wires the real reads over the R2 binding and the Stream
+ * manager. The AI model is always a parameter, defaulted from config.
+ */
+
+/** One audio segment's bytes and duration, from a Stream HLS audio rendition. */
+export interface AudioSegmentBytes {
+  /** The decoded segment bytes (a fragmented-MP4 media segment). */
+  bytes: Uint8Array;
+  /** The segment's duration in seconds, from the HLS `#EXTINF` tag. */
+  durationSec: number;
+}
+
+/** The audio a video's transcription reads: the shared fMP4 init segment plus the ordered media segments. */
+export interface VideoAudioSource {
+  /** The fragmented-MP4 initialization segment — codec config, prepended to every group. */
+  init: Uint8Array;
+  /** The ordered audio segments. */
+  segments: AudioSegmentBytes[];
+}
+
+/** The dependencies the enrichment functions need, all injectable. */
+export interface EnrichDeps {
+  /** The record store, bound to the effective schema. */
+  store: RecordStore;
+  /** The Workers AI binding. */
+  ai: MediaAi;
+  /** The configured models, per feature. */
+  models: { imageToText: string; transcribe: string };
+  /** Read a stored object's raw bytes (images from R2 or delivery URL; audio from R2). */
+  readBytes: (record: MediaRecord) => Promise<Uint8Array>;
+  /** Read a document as a Blob for `toMarkdown`. */
+  readDocument: (record: MediaRecord) => Promise<{ name: string; blob: Blob }>;
+  /** Fetch a video's HLS audio rendition as an init segment plus ordered media segments. */
+  fetchVideoAudio: (record: MediaRecord) => Promise<VideoAudioSource>;
+}
+
+/** Concatenate byte chunks into one buffer. */
+function concatBytes(chunks: Uint8Array[]): Uint8Array {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return out;
+}
+
+/** Generate alt text and a caption for an image and write them to the record. */
+export async function runImageToText(deps: EnrichDeps, id: string): Promise<void> {
+  const record = await deps.store.get(id);
+  if (record?.type !== "image") return;
+  const bytes = await deps.readBytes(record);
+  const { altText, caption } = await generateImageText(deps.ai, bytes, deps.models.imageToText);
+  await deps.store.patch(id, { altText, caption, updatedAt: new Date() });
+}
+
+/** Transcribe an audio file in one call and write the transcription to the record. */
+export async function runAudioTranscription(deps: EnrichDeps, id: string): Promise<void> {
+  const record = await deps.store.get(id);
+  if (record?.type !== "audio") return;
+  const bytes = await deps.readBytes(record);
+  const transcription = await transcribeAudioBytes(deps.ai, bytes, deps.models.transcribe);
+  await deps.store.patch(id, { transcription, hasTranscription: true, updatedAt: new Date() });
+}
+
+/** Extract markdown text from a document and write it to the record. */
+export async function runDocumentExtraction(deps: EnrichDeps, id: string): Promise<void> {
+  const record = await deps.store.get(id);
+  if (record?.type !== "document") return;
+  const file = await deps.readDocument(record);
+  const extractedText = await extractMarkdown(deps.ai, [file]);
+  await deps.store.patch(id, { extractedText, hasExtractedText: true, updatedAt: new Date() });
+}
+
+/**
+ * Transcribe a video's audio: fetch its HLS audio rendition, group the segments into ~30s overlapping
+ * batches (whisper has a per-call input limit), transcribe each batch with the shared fMP4 init segment
+ * prepended, then stitch the batches back with overlap-dedup. Writes the transcription to the record.
+ */
+export async function runVideoTranscription(deps: EnrichDeps, id: string): Promise<void> {
+  const record = await deps.store.get(id);
+  if (record?.type !== "video") return;
+  const source = await deps.fetchVideoAudio(record);
+  const asSegments: AudioSegment[] = source.segments.map((segment, index) => ({
+    uri: String(index),
+    durationSec: segment.durationSec,
+  }));
+  const groups = groupSegmentsForTranscription(asSegments);
+  const transcripts: string[] = [];
+  for (const group of groups) {
+    const parts: Uint8Array[] = [source.init];
+    for (const segment of group.segments) {
+      const bytes = source.segments[Number(segment.uri)]?.bytes;
+      if (bytes) parts.push(bytes);
+    }
+    transcripts.push(await transcribeAudioBytes(deps.ai, concatBytes(parts), deps.models.transcribe));
+  }
+  const transcription = deduplicateOverlappingTranscripts(transcripts);
+  await deps.store.patch(id, { transcription, hasTranscription: true, updatedAt: new Date() });
+}

package/src/workflows/hls.ts

@@ -0,0 +1,99 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { MediaEnrichmentError } from "../error/errors";
+import type { VideoAudioSource } from "./enrich";
+
+/**
+ * Minimal HLS parsing for Cloudflare Stream's audio rendition. Stream serves a master manifest that
+ * points at an audio-only rendition; that rendition is a fragmented-MP4 playlist — a single `#EXT-X-MAP`
+ * init segment plus `#EXTINF`-timed media segments, each undecodable without the init. The two parsers
+ * are pure and unit-tested; {@link fetchVideoAudio} is the thin fetch orchestrator the Workflow injects.
+ */
+
+/** Extract the audio rendition's playlist URI from a master manifest, or null if none is present. */
+export function parseAudioRenditionUri(master: string): string | null {
+  for (const line of master.split(/\r?\n/)) {
+    if (line.startsWith("#EXT-X-MEDIA:") && /TYPE=AUDIO/.test(line)) {
+      const match = line.match(/URI="([^"]+)"/);
+      if (match?.[1]) return match[1];
+    }
+  }
+  return null;
+}
+
+/** One media segment reference: its URI and duration in seconds. */
+export interface MediaSegmentRef {
+  /** The segment URI, relative to the media playlist. */
+  uri: string;
+  /** The segment duration in seconds, from its `#EXTINF` tag. */
+  durationSec: number;
+}
+
+/** Parse an fMP4 media playlist into its init-segment URI and ordered, timed media segments. */
+export function parseMediaPlaylist(playlist: string): { initUri: string | null; segments: MediaSegmentRef[] } {
+  const lines = playlist.split(/\r?\n/);
+  let initUri: string | null = null;
+  let pendingDuration: number | null = null;
+  const segments: MediaSegmentRef[] = [];
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.startsWith("#EXT-X-MAP:")) {
+      const match = line.match(/URI="([^"]+)"/);
+      if (match?.[1]) initUri = match[1];
+    } else if (line.startsWith("#EXTINF:")) {
+      const value = Number.parseFloat(line.slice("#EXTINF:".length));
+      pendingDuration = Number.isFinite(value) ? value : 0;
+    } else if (line.length > 0 && !line.startsWith("#")) {
+      segments.push({ uri: line, durationSec: pendingDuration ?? 0 });
+      pendingDuration = null;
+    }
+  }
+  return { initUri, segments };
+}
+
+/** A minimal fetcher seam so {@link fetchVideoAudio} is injectable in tests. */
+export type Fetcher = (
+  url: string,
+) => Promise<{ ok: boolean; status: number; text(): Promise<string>; arrayBuffer(): Promise<ArrayBuffer> }>;
+
+/** Fetch and validate a URL, throwing a media enrichment error on a non-OK response. */
+async function fetchOrThrow(
+  fetcher: Fetcher,
+  url: string,
+): Promise<{ text(): Promise<string>; arrayBuffer(): Promise<ArrayBuffer> }> {
+  const response = await fetcher(url);
+  if (!response.ok) {
+    throw new MediaEnrichmentError({ detail: `HLS fetch failed (${response.status}): ${url}` });
+  }
+  return response;
+}
+
+/**
+ * Fetch a Stream video's HLS audio rendition and assemble it into a {@link VideoAudioSource}: the init
+ * segment plus every media segment's bytes and duration, ready for {@link runVideoTranscription} to group.
+ */
+export async function fetchVideoAudio(masterUrl: string, fetcher: Fetcher = globalFetcher): Promise<VideoAudioSource> {
+  const master = await (await fetchOrThrow(fetcher, masterUrl)).text();
+  const renditionUri = parseAudioRenditionUri(master);
+  if (!renditionUri) throw new MediaEnrichmentError({ detail: "no audio rendition in the HLS master manifest" });
+  const renditionUrl = new URL(renditionUri, masterUrl).toString();
+
+  const playlist = await (await fetchOrThrow(fetcher, renditionUrl)).text();
+  const { initUri, segments } = parseMediaPlaylist(playlist);
+  if (!initUri) throw new MediaEnrichmentError({ detail: "no init segment in the HLS audio playlist" });
+
+  const init = new Uint8Array(
+    await (await fetchOrThrow(fetcher, new URL(initUri, renditionUrl).toString())).arrayBuffer(),
+  );
+  const resolved = [];
+  for (const segment of segments) {
+    const url = new URL(segment.uri, renditionUrl).toString();
+    const bytes = new Uint8Array(await (await fetchOrThrow(fetcher, url)).arrayBuffer());
+    resolved.push({ bytes, durationSec: segment.durationSec });
+  }
+  return { init, segments: resolved };
+}
+
+/** The default fetcher — the Workers global `fetch`. */
+const globalFetcher: Fetcher = (url) => fetch(url);

package/src/workflows/retryPolicy.ts

@@ -0,0 +1,56 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { WorkflowRetryPolicy } from "@pithy-sh/core/src/workflow/faults";
+
+/**
+ * **What an enrichment retries, and what it refuses to.**
+ *
+ * Enrichment is the one shape in this kit where terminal is *expensive*. The four Workflows are started
+ * once, on finalize, and nothing starts them again: a fault the step calls terminal is an asset that
+ * silently keeps no alt text and no transcription, and nobody finds out because a missing caption looks
+ * exactly like a caption nobody wanted. So the retryable list here is longer than most, and every entry
+ * on it is a service this capability does not control (pithy-sh/pithy#348).
+ *
+ * ## Retryable, and why
+ *
+ * - **`core/upstream_failed`** — Workers AI rejected the call. Raised at the one seam in `ai/enrich.ts`
+ *   that wraps the binding, and *only* there: a model that answered in a shape the schema refuses is
+ *   `media/enrichment_failed` and stays terminal. The split is by code rather than by phrasing because
+ *   the step can only act on a code. A model that was overloaded for ten seconds answers on the second
+ *   attempt.
+ * - **`cloudflare/request_failed`** — the Stream REST API, unreachable or answering 5xx. Video
+ *   transcription asks Stream for an HLS playback URL before it fetches a single byte, and
+ *   `cloudflareRequest` folds every transport failure into this one code.
+ * - **`media/enrichment_failed`** — **the deliberate exception, and the reason it earns its place is
+ *   `fetchVideoAudio`.** A video whose Stream asset has not finished encoding has no HLS playback URL
+ *   yet, and that is what the enrichment raises: not a refusal, a *not yet*. It is the single most
+ *   likely failure of a video Workflow started the moment an upload finalizes, and it resolves on its
+ *   own within a minute. The cost of admitting it is that the code's other producers — an R2 object that
+ *   is genuinely missing, a manifest with no audio rendition — buy five cheap attempts before failing.
+ *   That is a worse diagnosis and a bounded one; a transcription permanently lost to an encode still in
+ *   progress is neither.
+ * - **A transient D1 fault** — the media table, when records live in D1. Classified in core by
+ *   `withD1Retry`, never restated here.
+ *
+ * ## Terminal, and why
+ *
+ * - **`media/not_found`** — the record is gone. A Workflow instance outliving its row is ordinary, and
+ *   the row does not come back over a backoff.
+ * - **`media/unsupported`** — a type or backend enrichment cannot read. A fact about the asset.
+ * - **`media/storage_failed`** — a mint, a delete, or a presign the storage plane refused. None of them
+ *   run inside an enrichment step; one reaching here is a bug, and a bug should surface.
+ * - **`cloudflare/invalid_response`, `cloudflare/not_configured`** — a Stream response that did not
+ *   match its schema, or a manager with no account id. A shape and a config; neither changes.
+ * - **`validation/invalid_input`** — a config or a payload the schema refuses.
+ */
+export const mediaWorkflowRetry: WorkflowRetryPolicy = {
+  capability: "media",
+  retryable: {
+    "core/upstream_failed":
+      "Workers AI rejected the call rather than answering it; an overloaded model answers next time.",
+    "cloudflare/request_failed": "The Stream API could not be reached; the same read is idempotent and may reach it.",
+    "media/enrichment_failed":
+      "A video's Stream asset may still be encoding, so it has no HLS audio yet — a not-yet rather than a refusal.",
+  },
+};

package/src/workflows/specs.ts

@@ -0,0 +1,75 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { workflowKey } from "@pithy-sh/core/src/workflow/naming";
+import type { WorkflowRegistry, WorkflowSpecMap } from "@pithy-sh/core/src/workflow/spec";
+import { z } from "zod";
+
+/**
+ * The four enrichment jobs media owns, declared once.
+ *
+ * This map is the single description of media's durable work. `capability.ts` derives the four
+ * `workflow` bindings from it, `http/dispatch.ts` dispatches through it, and `pithy media provision`
+ * resolves the host worker's `workflows` array and per-environment names from it. Previously the same
+ * facts were written three times — in the capability's bindings, in the hand-rolled dispatcher, and in
+ * the committed `wrangler.jsonc` — and nothing kept them in agreement.
+ *
+ * Every job is `optional: true`. The Workflows live in the prebuilt media worker, deployed only by
+ * `pithy media provision`, so a project that has not provisioned must still boot and serve every
+ * non-enrichment route. An absent binding degrades to a logged skip, never a startup failure.
+ */
+
+/** The capability name — the first segment of every media dispatch key and deployed workflow name. */
+export const MEDIA_CAPABILITY = "media";
+
+/** The parameters every enrichment job takes: which media record to enrich. */
+export const MediaEnrichmentParams = z
+  .object({
+    id: z
+      .string()
+      .min(1)
+      .describe("The media record's id. The Workflow reads that record, enriches it, and writes the result back."),
+  })
+  .describe("The instance parameters of an enrichment Workflow — the one record it runs against.");
+export type MediaEnrichmentParams = z.infer<typeof MediaEnrichmentParams>;
+
+/** Media's durable jobs, keyed by job name. The key is the second segment of the `media/<job>` dispatch key. */
+export const mediaWorkflows = {
+  "image-to-text": {
+    binding: "MEDIA_IMAGE_TO_TEXT",
+    className: "MediaImageToTextWorkflow",
+    params: MediaEnrichmentParams,
+    optional: true,
+  },
+  "audio-transcribe": {
+    binding: "MEDIA_AUDIO_TRANSCRIBE",
+    className: "MediaAudioTranscribeWorkflow",
+    params: MediaEnrichmentParams,
+    optional: true,
+  },
+  "video-transcribe": {
+    binding: "MEDIA_VIDEO_TRANSCRIBE",
+    className: "MediaVideoTranscribeWorkflow",
+    params: MediaEnrichmentParams,
+    optional: true,
+  },
+  "doc-extract": {
+    binding: "MEDIA_DOC_EXTRACT",
+    className: "MediaDocExtractWorkflow",
+    params: MediaEnrichmentParams,
+    optional: true,
+  },
+} as const satisfies WorkflowSpecMap;
+
+/**
+ * Media's jobs as a dispatch registry, keyed `media/<job>`. Built here rather than through
+ * `composeWorkflows` because the routes dispatch from inside the media capability, before any
+ * project-wide registry exists — and the key format comes from core's {@link workflowKey} either way,
+ * so the two cannot drift.
+ */
+export const mediaWorkflowRegistry: WorkflowRegistry = Object.fromEntries(
+  Object.entries(mediaWorkflows).map(([job, spec]) => {
+    const key = workflowKey(MEDIA_CAPABILITY, job);
+    return [key, { key, capability: MEDIA_CAPABILITY, job, spec }];
+  }),
+);