@pithy-sh/media 0.1.0

package/src/http/schemas.ts

@@ -0,0 +1,90 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { MediaType } from "../data/enums";
+
+/**
+ * The request schemas for the media routes. Validation happens at the HTTP boundary (CLAUDE.md §Zod),
+ * declared on the route line with `zValidator(target, Schema, validationHook)` — so reading `routes.ts`
+ * tells you what each route accepts without opening a handler.
+ * The create body is `loose` so an adopter's extension fields pass through to be validated against the
+ * effective record schema; the known client fields are typed and bounded here.
+ */
+
+const HEX = /^[0-9a-f]+$/;
+
+/**
+ * The `:id` path parameter every single-record media route carries. Deliberately a bounded generic
+ * string and NOT `z.uuid()`: ids are minted with `crypto.randomUUID()`, but the shape check exists to
+ * stop an unbounded string reaching the record store — not to pre-empt the store's own lookup. An
+ * unknown-but-well-formed id must still reach the handler and answer `media/not_found` (404), which a
+ * UUID check would turn into a 400.
+ */
+export const MediaIdParam = z
+  .object({
+    id: z.string().min(1).max(128).describe("The media record id from the path — bounded, not shape-checked."),
+  })
+  .describe("The path parameter identifying one media record.");
+export type MediaIdParam = z.output<typeof MediaIdParam>;
+
+/** The client-supplied part of a media record on upload-init. Server fields (id, status, storage) are set by the handler. */
+export const CreateMediaInput = z
+  .object({
+    type: MediaType.describe("The kind of media being uploaded."),
+    name: z.string().min(1).describe("A human-readable display name for the media."),
+    filename: z.string().min(1).describe("The original client filename, including extension."),
+    contentType: z.string().min(1).describe("The MIME type of the bytes being uploaded."),
+    size: z.number().int().positive().nullish().describe("The declared size in bytes, if known."),
+    sha256: z
+      .string()
+      .regex(HEX)
+      .length(64)
+      .nullish()
+      .describe("Client-computed lowercase-hex SHA-256 of the file, for exact-match dedup."),
+    phash: z.string().regex(HEX).nullish().describe("Client-computed perceptual hash (hex) for near-duplicate images."),
+    width: z.number().int().positive().nullish().describe("Original pixel width for images and video."),
+    height: z.number().int().positive().nullish().describe("Original pixel height for images and video."),
+  })
+  .loose()
+  .describe("The client-supplied fields for creating a media record; extra keys are adopter extension fields.");
+export type CreateMediaInput = z.output<typeof CreateMediaInput>;
+
+/** Optional fields a client may supply on finalize (computed after the upload landed). */
+export const FinalizeMediaInput = z
+  .object({
+    size: z.number().int().positive().nullish().describe("The final object size in bytes, now that it is known."),
+    sha256: z.string().regex(HEX).length(64).nullish().describe("The SHA-256 computed over the uploaded bytes."),
+    phash: z.string().regex(HEX).nullish().describe("The perceptual hash computed over the uploaded image."),
+  })
+  .describe("Optional fields supplied when finalizing an upload.");
+export type FinalizeMediaInput = z.output<typeof FinalizeMediaInput>;
+
+/** The duplicate-search request. */
+export const DuplicatesInput = z
+  .object({
+    type: MediaType.describe("The media type to search within."),
+    sha256: z.string().regex(HEX).length(64).describe("The SHA-256 to match exactly."),
+    phash: z.string().regex(HEX).optional().describe("The perceptual hash to match near, for images."),
+    threshold: z
+      .number()
+      .int()
+      .min(0)
+      .max(64)
+      .optional()
+      .describe("The Hamming distance under which two perceptual hashes count as near-duplicates."),
+    limit: z.number().int().min(1).max(50).optional().describe("The maximum number of candidates to return."),
+  })
+  .describe("A request to find exact and near duplicates of a file.");
+export type DuplicatesInput = z.output<typeof DuplicatesInput>;
+
+/** Query parameters for listing media. */
+export const ListMediaQuery = z
+  .object({
+    type: MediaType.optional().describe("Restrict the listing to one media type."),
+    limit: z.coerce.number().int().min(1).max(100).optional().describe("Maximum records per page."),
+    // Bounded, but no `.min(1)`: `?cursor=` (empty) already decodes to offset 0 today and must keep working.
+    cursor: z.string().max(64).optional().describe("Continuation cursor from a previous page."),
+  })
+  .describe("Query parameters for the media list route.");
+export type ListMediaQuery = z.output<typeof ListMediaQuery>;

package/src/index.ts

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The package entrypoint — the surface `pithy add media` wires into `pithy.config.ts`. Deliberately
+ * narrow: the capability factory, its config and options types, the record and dedup API, and the
+ * schemas an app extends. Every other module is imported by deep path (`@pithy-sh/media/src/...`); this
+ * is the documented contract, not a barrel over the package.
+ */
+
+export { isMediaCapability, MEDIA_MIGRATION_ORDER, type MediaCapability, type MediaOptions, media } from "./capability";
+export { MediaConfig, type MediaConfigInput, type MediaDelivery } from "./config/config";
+export {
+  EXTRACTABLE_EXTENSIONS,
+  isExtractableDocument,
+  MediaStatus,
+  MediaType,
+  StorageBackend,
+} from "./data/enums";
+export { extendMediaAsset } from "./data/extend";
+export { MediaAsset } from "./data/mediaAsset";
+export {
+  buildImageUrl,
+  buildStreamDashUrl,
+  buildStreamHlsUrl,
+  buildStreamIframeUrl,
+  buildStreamThumbnailUrl,
+  mediaUrl,
+} from "./deliver/url";
+export {
+  classifyDistance,
+  type DuplicateCandidate,
+  findDuplicates,
+  hammingDistance,
+  SIMILAR_THRESHOLD,
+} from "./hash/duplicates";
+export { computeSha256 } from "./hash/sha256";
+export type { HashStore } from "./record/hashStore";
+export type { MediaRecord, RecordStore } from "./record/store";

package/src/migrations/0001_init.ts

@@ -0,0 +1,104 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/** What the media schema looks like in the app database, which depends on where records live. */
+export interface MediaInitOptions {
+  /**
+   * Whether to create the record table `pithy_media_assets`. True for `recordStore: 'd1'`; false for
+   * `recordStore: 'kv'`, where records live in KV and only the dedup hash table belongs in D1.
+   */
+  readonly withAssets: boolean;
+}
+
+/**
+ * The whole media schema in the app database, in one migration — parameterized rather than chained,
+ * because what media creates there is a function of its record store and not of its history.
+ *
+ * `pithy_media_hashes` is created in **both** modes: dedup is a query workload (an exact `sha256`
+ * lookup and a bounded near-`phash` scan) that KV cannot serve, so the hashes always live in D1. The
+ * record table `pithy_media_assets` is created for the D1 record store only, which is what
+ * `withAssets` selects. One table with a `type` discriminator and nullable per-type derived columns;
+ * `sha256`/`phash` are kept on the record for reference, but dedup queries the dedicated hash table,
+ * so those columns are not indexed here. Adopter extension columns arrive in the generated
+ * `0002_extend` migration (`extend.ts`), which is derived per adopter from their extension schema and
+ * is not part of this authored schema.
+ *
+ * camelCase identifiers; `CamelCasePlugin` snake-cases them in the DDL. `down` is the tested inverse,
+ * dropping in reverse of what `up` created for the same options.
+ *
+ * **`recordStore` is chosen once, not migrated between.** A project that flips `kv` → `d1` after its
+ * first `pithy migrate` gets no record table, because this migration has already run. That was never a
+ * working path: the previous two-migration form would have created an empty table and left every
+ * existing record stranded in KV, unreadable and unlisted. Changing record store means a new database
+ * and a deliberate copy, not a schema step.
+ *
+ * See `CONTRIBUTING.md` §Migrations for why a capability's schema is one migration while nothing is
+ * published, and what changes the day something is.
+ */
+export function media_0001_init({ withAssets }: MediaInitOptions): Migration {
+  return {
+    up: async (db: Kysely<unknown>): Promise<void> => {
+      await db.schema
+        .createTable("pithyMediaHashes")
+        .addColumn("id", "integer", (c) => c.primaryKey().autoIncrement())
+        // One row per media record, so a re-finalize upserts rather than duplicating.
+        .addColumn("mediaId", "text", (c) => c.notNull().unique())
+        .addColumn("mediaType", "text", (c) => c.notNull())
+        .addColumn("sha256", "text", (c) => c.notNull())
+        .addColumn("phash", "text")
+        .addColumn("createdAt", "integer", (c) => c.notNull())
+        .execute();
+
+      // Exact-match dedup looks a row up by sha256; the near-duplicate scan reads the bounded
+      // (mediaType, phash) image set.
+      await db.schema.createIndex("pithyMediaHashesSha256Idx").on("pithyMediaHashes").column("sha256").execute();
+      await db.schema
+        .createIndex("pithyMediaHashesPhashIdx")
+        .on("pithyMediaHashes")
+        .columns(["mediaType", "phash"])
+        .execute();
+
+      if (!withAssets) return;
+
+      await db.schema
+        .createTable("pithyMediaAssets")
+        .addColumn("id", "text", (c) => c.primaryKey())
+        .addColumn("type", "text", (c) => c.notNull())
+        .addColumn("status", "text", (c) => c.notNull())
+        .addColumn("name", "text", (c) => c.notNull())
+        .addColumn("filename", "text", (c) => c.notNull())
+        .addColumn("contentType", "text", (c) => c.notNull())
+        .addColumn("size", "integer")
+        .addColumn("storageBackend", "text", (c) => c.notNull())
+        .addColumn("storageKey", "text", (c) => c.notNull())
+        .addColumn("sha256", "text")
+        .addColumn("phash", "text")
+        .addColumn("width", "integer")
+        .addColumn("height", "integer")
+        .addColumn("altText", "text")
+        .addColumn("caption", "text")
+        .addColumn("transcription", "text")
+        .addColumn("hasTranscription", "integer", (c) => c.notNull().defaultTo(0))
+        .addColumn("extractedText", "text")
+        .addColumn("hasExtractedText", "integer", (c) => c.notNull().defaultTo(0))
+        .addColumn("createdAt", "integer", (c) => c.notNull())
+        .addColumn("updatedAt", "integer", (c) => c.notNull())
+        .execute();
+
+      // List/filter by type is the common query; dedup uses pithy_media_hashes, not this table.
+      await db.schema.createIndex("pithyMediaAssetsTypeIdx").on("pithyMediaAssets").column("type").execute();
+    },
+    down: async (db: Kysely<unknown>): Promise<void> => {
+      if (withAssets) {
+        await db.schema.dropIndex("pithyMediaAssetsTypeIdx").execute();
+        await db.schema.dropTable("pithyMediaAssets").execute();
+      }
+      await db.schema.dropIndex("pithyMediaHashesPhashIdx").execute();
+      await db.schema.dropIndex("pithyMediaHashesSha256Idx").execute();
+      await db.schema.dropTable("pithyMediaHashes").execute();
+    },
+  };
+}

package/src/migrations/extend.ts

@@ -0,0 +1,40 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+import type { ExtensionColumn } from "../data/extend";
+import { MEDIA_ASSETS_TABLE } from "../data/tables";
+
+/**
+ * The generated `0002_extend` migration: it adds one real column to `pithy_media_assets` per adopter
+ * extension field, derived from that field's Zod type (see `data/extend.ts`). This is what makes an
+ * adopter's extra fields (an owning `userId`, a tenant id, tags) real, migrated D1 columns from the same
+ * one schema that validates them on read and write — with no backend-specific work.
+ *
+ * A `NOT NULL` column added by `ALTER TABLE` needs a default in SQLite (existing rows must get a value),
+ * so a required field is added with a type-appropriate default (`0` / `''`); the effective Zod schema
+ * still enforces a real value on every write. Optional fields are added nullable. `down` drops the
+ * columns in reverse order. Returns `null` when there is nothing to add, so no empty migration is
+ * registered.
+ */
+export function mediaExtendMigration(columns: ExtensionColumn[]): Migration | null {
+  if (columns.length === 0) return null;
+  return {
+    up: async (db: Kysely<unknown>): Promise<void> => {
+      for (const column of columns) {
+        await db.schema
+          .alterTable(MEDIA_ASSETS_TABLE)
+          .addColumn(column.name, column.type, (c) =>
+            column.notNull ? c.notNull().defaultTo(column.type === "integer" ? 0 : "") : c,
+          )
+          .execute();
+      }
+    },
+    down: async (db: Kysely<unknown>): Promise<void> => {
+      for (const column of [...columns].reverse()) {
+        await db.schema.alterTable(MEDIA_ASSETS_TABLE).dropColumn(column.name).execute();
+      }
+    },
+  };
+}

package/src/provision/provisionMedia.ts

@@ -0,0 +1,226 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
+import { resourceNames, type ScopedNames } from "@pithy-sh/core/src/naming/resourceNames";
+import { type ManagedEnvironment, managedEnvironments } from "@pithy-sh/secrets/src/scope";
+import { MEDIA_CAPABILITY } from "../workflows/specs";
+
+/**
+ * The provisioning orchestration for the media capability — the live counterpart to `pithy add media`'s
+ * config wiring. `pithy add` writes bindings; this stands up what those bindings point at: the R2 bucket
+ * media objects live in, the `MEDIA` KV namespace when records live in KV, two per-environment secrets,
+ * and the prebuilt media worker that hosts the four enrichment Workflows.
+ *
+ * **Two secrets, because media reads only one of them.** `media-storage-credentials` carries the Images
+ * and Stream token media mints direct-upload URLs with. `media-r2-credentials` carries the R2 key pair
+ * and bucket, and is read by `@pithy-sh/storage`'s `ObjectStore` — media declares the name and never
+ * touches the values. Both are per environment, because the bucket is (see {@link mediaBucketName}).
+ *
+ * The live Cloudflare/wrangler steps are behind the {@link MediaProvisioner} seam, so the orchestration
+ * (order, idempotency contract, per-env fan-out) is unit-tested without touching Cloudflare. **Every step
+ * is idempotent** — find-then-create for resources, create-then-update for the secret, and a deploy that
+ * overwrites — so re-running provisioning is a no-op on an already-provisioned account.
+ *
+ * **What it does not do.** Cloudflare exposes no API for minting an R2 S3 access-key pair, and the
+ * permission catalog carries no Images or Stream keys, so nothing here mints a credential. The scoped API
+ * token and the R2 key pair are supplied by the operator (flags, or `R2_CREDENTIALS` in `.dev.vars`) and
+ * written into the secrets as given. Minting them is a follow-up, not a promise this command keeps today.
+ */
+
+/**
+ * Every name media provisions under, for one project in one environment.
+ *
+ * One call to the facade, so the project is validated once and the environment once — the R2 bucket,
+ * the KV namespace, and the host Worker then each ask for their own kind of resource and get that
+ * namespace's own limit. Media names the same capability three times over, in three namespaces whose
+ * caps are 63, 512, and 63; going through the facade is what stops one number standing in for all
+ * three, and what refuses `production` here rather than quietly provisioning a fourth environment.
+ */
+function mediaNames(project: string, env: ManagedEnvironment): ScopedNames {
+  return resourceNames(project).env(env);
+}
+
+/**
+ * The R2 bucket media objects are stored in, **per project and per environment** —
+ * `acme-staging-media`, `acme-prod-media`.
+ *
+ * One bucket per account would mean staging writes objects into the bucket prod reads, and a
+ * staging teardown deletes prod's media. Buckets are free — the cost is bytes and operations —
+ * so a shared one buys nothing and risks everything. This is the same per-environment posture the
+ * media worker itself takes, and the opposite of `@pithy-sh/email`'s deliberately project-shared
+ * suppression database, which is shared precisely *because* an unsubscribe must apply everywhere.
+ *
+ * The project segment carries ownership. R2's namespace is flat and account-wide, and provisioning
+ * reuses a bucket it finds by name — so without it, a second Pithy project in the same account adopts
+ * this one's bucket instead of creating its own, and either teardown takes both projects' media.
+ *
+ * Named through the facade's `r2` getter, which carries R2's own rule — 3 to 63 characters, starting
+ * and ending alphanumeric — rather than a number this file picked.
+ */
+export function mediaBucketName(project: string, env: ManagedEnvironment): string {
+  return mediaNames(project, env).r2(MEDIA_CAPABILITY);
+}
+
+/**
+ * The title of the KV namespace media records live in when `recordStore: 'kv'`. Per project and per
+ * environment, for the same reasons — KV titles are account-wide too, and reuse keys on the title.
+ *
+ * Same string as the bucket today, and deliberately asked for separately: a KV title may run to 512
+ * characters and a bucket stops at 63, so the two are the same only for as long as the composed name
+ * is short. Asking `kv` for a KV title is what keeps them right when it stops being.
+ */
+export function mediaKvTitle(project: string, env: ManagedEnvironment): string {
+  return mediaNames(project, env).kv(MEDIA_CAPABILITY);
+}
+
+/**
+ * The deployed Worker name for a project's environment — also its resolved config basename. Held to
+ * the Worker rule (63, refused rather than truncated: a script cannot be renamed after a deploy
+ * without orphaning it and every `service` binding pointing at it).
+ */
+export function mediaWorkerName(project: string, env: ManagedEnvironment): string {
+  return mediaNames(project, env).worker(MEDIA_CAPABILITY);
+}
+
+/** The provisioned resources every environment's worker and secret are wired to. */
+export interface MediaResources {
+  /** The R2 bucket media objects live in. */
+  bucketName: string;
+  /** The `MEDIA` KV namespace id, or `null` when records live in D1 and the binding is dropped. */
+  kvNamespaceId: string | null;
+}
+
+/** The live Cloudflare/wrangler seam. Each step must be idempotent. */
+export interface MediaProvisioner {
+  /**
+   * Verify account prerequisites before any resource is created — most importantly a registered
+   * `workers.dev` subdomain, which Cloudflare requires to deploy the Workflow-hosting media worker.
+   * Throws a clear, actionable error so provisioning fails fast and clean rather than mid-deploy.
+   */
+  preflight(): Promise<void>;
+  /** Create (or reuse) this environment's R2 bucket; returns its name. Idempotent. */
+  ensureBucket(env: ManagedEnvironment): Promise<{ bucketName: string }>;
+  /**
+   * Create (or reuse) this environment's `MEDIA` KV namespace, but only when records live in KV;
+   * returns `null` otherwise so the resolver drops the binding rather than pointing it at a namespace
+   * that was never created. Idempotent.
+   */
+  ensureKvNamespace(env: ManagedEnvironment): Promise<{ namespaceId: string } | null>;
+  /**
+   * Write this environment's two secrets: `media-storage-credentials` (the Images + Stream token and the
+   * account id) and `media-r2-credentials` (the R2 key pair and this environment's bucket). Idempotent
+   * (create, else update). Runs before any worker is deployed: a worker that boots without its
+   * credentials fails on its first enrichment.
+   */
+  writeCredentials(env: ManagedEnvironment, resources: MediaResources): Promise<void>;
+  /** Deploy the prebuilt media worker for this environment, wired to the provisioned resources. */
+  deployWorker(env: ManagedEnvironment, resources: MediaResources): Promise<void>;
+}
+
+/** What provisioning produced, per environment. */
+export interface MediaProvisionResult {
+  /** Each environment provisioned, with the resources its worker and secret were wired to. */
+  environments: Array<{ env: ManagedEnvironment } & MediaResources>;
+}
+
+/**
+ * Provision the media infrastructure: check the account, create the bucket and (in KV mode) the
+ * namespace once, write every environment's credentials, then deploy every environment's worker. The
+ * order is the contract — the resources exist before a secret names them, and the secrets exist before a
+ * worker that reads them boots. Idempotent end to end (each step is).
+ *
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
+ */
+export async function provisionMedia(
+  provisioner: MediaProvisioner,
+  environments: DeclaredEnvironments | readonly string[],
+): Promise<MediaProvisionResult> {
+  await provisioner.preflight();
+
+  // Resources first for every environment, then credentials, then workers — the ordering is the
+  // contract. A secret must not name a bucket that does not exist, and a worker must not boot before
+  // the secret it reads. Fanning each phase across all environments (rather than completing one
+  // environment at a time) means a failure in prod's bucket stops the run before staging's
+  // worker is deployed against a half-provisioned account.
+  const resources = new Map<ManagedEnvironment, MediaResources>();
+  for (const env of managedEnvironments(environments)) {
+    const { bucketName } = await provisioner.ensureBucket(env);
+    const namespace = await provisioner.ensureKvNamespace(env);
+    resources.set(env, { bucketName, kvNamespaceId: namespace?.namespaceId ?? null });
+  }
+
+  for (const env of managedEnvironments(environments)) {
+    await provisioner.writeCredentials(env, resourcesFor(resources, env));
+  }
+  for (const env of managedEnvironments(environments)) {
+    await provisioner.deployWorker(env, resourcesFor(resources, env));
+  }
+
+  return {
+    environments: managedEnvironments(environments).map((env) => ({ env, ...resourcesFor(resources, env) })),
+  };
+}
+
+/** Read back an environment's resources. Absent is impossible by construction, so the throw is a bug check. */
+function resourcesFor(resources: Map<ManagedEnvironment, MediaResources>, env: ManagedEnvironment): MediaResources {
+  const found = resources.get(env);
+  if (!found) throw new InternalError({ message: `No provisioned resources for the ${env} environment.` });
+  return found;
+}
+
+/** The teardown seam — the inverse of {@link MediaProvisioner}. Every step idempotent (a missing resource is a no-op). */
+export interface MediaDeprovisioner {
+  /** Delete the env's media worker. Idempotent (a missing worker is a no-op). */
+  deleteWorker(env: ManagedEnvironment): Promise<void>;
+  /**
+   * Delete this environment's R2 bucket **and every object in it**. **Destructive** — nothing here is
+   * recoverable. Idempotent (a missing bucket is a no-op).
+   *
+   * Emptying the bucket is part of the contract, not a nicety: R2 refuses to delete a bucket that still
+   * holds an object, or the parts of a multipart upload that was never completed. An implementation that
+   * only called the control-plane delete would work on an untouched bucket and fail on every bucket
+   * anyone had used.
+   */
+  deleteBucket(env: ManagedEnvironment): Promise<void>;
+  /** Delete this environment's `MEDIA` KV namespace. **Destructive** — every KV-mode record is lost. Idempotent. */
+  deleteKvNamespace(env: ManagedEnvironment): Promise<void>;
+}
+
+/** Teardown options. By default the stored media is **kept** — only the workers come down. */
+export interface MediaDeprovisionOptions {
+  /**
+   * Also delete the R2 bucket — with every object in it — and the `MEDIA` KV namespace. Off by default,
+   * because the objects and records they hold are the adopter's data and no deploy can restore them; the
+   * flag is the confirmation.
+   */
+  deleteStorage?: boolean;
+}
+
+/**
+ * Tear down the media infrastructure, reversing {@link provisionMedia}: delete every environment's worker
+ * first (they bind the bucket and namespace), then — only when `deleteStorage` is set — the storage
+ * itself, objects and all. Stored media is preserved unless explicitly requested. Idempotent end to end.
+ *
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
+ */
+export async function deprovisionMedia(
+  deprovisioner: MediaDeprovisioner,
+  environments: DeclaredEnvironments | readonly string[],
+  options: MediaDeprovisionOptions = {},
+): Promise<void> {
+  for (const env of managedEnvironments(environments)) {
+    await deprovisioner.deleteWorker(env);
+  }
+  if (options.deleteStorage) {
+    for (const env of managedEnvironments(environments)) {
+      await deprovisioner.deleteBucket(env);
+      await deprovisioner.deleteKvNamespace(env);
+    }
+  }
+}

package/src/provision/resolveMediaConfig.ts

@@ -0,0 +1,78 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { hostWorkflowsFor, resolveWorkflowHost, type WorkflowHostTemplate } from "@pithy-sh/core/src/workflow/host";
+import { masterKeySecretName } from "@pithy-sh/secrets/src/provision/provisionSecrets";
+import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
+import type { MediaConfig } from "../config/config";
+import { MEDIA_CAPABILITY, mediaWorkflowRegistry } from "../workflows/specs";
+import type { MediaResources } from "./provisionMedia";
+
+/**
+ * Resolve the media worker's committed `wrangler.jsonc` template into one environment's standalone
+ * config. Every per-environment decision lives here; everything static — the compatibility date, the AI
+ * binding, the four Workflow class names — stays as the template committed it.
+ *
+ * Thin over core's {@link resolveWorkflowHost}: the generic resolver owns the mechanics (clone, fill by
+ * binding name, stamp the worker's identity as `ENVIRONMENT` + `PROJECT`), and this file owns only what
+ * is media's — which bindings map to which provisioned resource, the Workflow names derived from
+ * media's own specs, and the serialized config the worker parses. Pure: the caller parses the template
+ * and writes the result.
+ *
+ * `PROJECT` matters more here than anywhere else the resolver is used: media is the one capability that
+ * creates Cloudflare Images and Stream assets, and those two stores are account-flat with
+ * Cloudflare-minted ids, so the var is what the ownership metadata on each asset is written from.
+ */
+
+/** The resolved resource ids + per-env values for one environment's media-worker deploy. */
+export interface MediaConfigParams {
+  /**
+   * The project name — the `<project>` segment the deployed worker and its four Workflow names lead
+   * with. The root `pithy.config.ts` `name`, resolved by `requireProjectName` and never guessed:
+   * Worker script and Workflow names are account-scoped, so a wrong value overwrites another
+   * project's running host rather than colliding with it.
+   */
+  project: string;
+  /** The target environment. */
+  env: ManagedEnvironment;
+  /** The app database id for this environment — where media records and hashes live. */
+  appDatabaseId: string;
+  /** This environment's secrets database id (`<project>-<env>-secrets`) — holds the storage credentials. */
+  secretsDatabaseId: string;
+  /** The CF Secrets Store id holding the per-env master key. */
+  storeId: string;
+  /** The provisioned bucket and KV namespace the worker binds. */
+  resources: MediaResources;
+  /** The app's resolved media config — serialized into the worker's `MEDIA_CONFIG` var. */
+  mediaConfig: MediaConfig;
+}
+
+/**
+ * Fill the template for one environment.
+ *
+ * The one media-specific subtlety is the `MEDIA` KV binding: the template declares it unconditionally,
+ * because a template describes every binding the capability *might* need. In `recordStore: 'd1'` mode no
+ * namespace is ever created, so the binding is dropped rather than left pointing at nothing — a deploy
+ * that binds a namespace which does not exist fails opaquely at the worker's first request.
+ */
+export function resolveMediaConfig(template: WorkflowHostTemplate, params: MediaConfigParams): WorkflowHostTemplate {
+  const { project, env, appDatabaseId, secretsDatabaseId, storeId, resources, mediaConfig } = params;
+  const kvNamespaceId = resources.kvNamespaceId;
+
+  return resolveWorkflowHost(template, {
+    project,
+    capability: MEDIA_CAPABILITY,
+    env,
+    databaseIds: { DB: appDatabaseId, SECRETS: secretsDatabaseId },
+    ...(kvNamespaceId ? { kvNamespaceIds: { MEDIA: kvNamespaceId } } : { omitKvBindings: ["MEDIA"] }),
+    r2BucketNames: { MEDIA_BUCKET: resources.bucketName },
+    secretsStoreId: storeId,
+    // The master key entry is project- and env-scoped, matching what the secrets manager wrote.
+    masterKeySecretName: masterKeySecretName(project, env),
+    vars: { MEDIA_CONFIG: JSON.stringify(mediaConfig) },
+    // The four enrichment Workflows, derived from the specs rather than from the template's own block.
+    // A Workflow name is account-scoped, so the template's `pithy-media-image-to-text` cannot be made
+    // project-scoped by suffixing — only the registry knows both the project and the job.
+    workflows: hostWorkflowsFor(mediaWorkflowRegistry, { project, capability: MEDIA_CAPABILITY, env }).workflows,
+  });
+}