Initial commit

2026-07-12 08:15:46 +00:00
commit ee0fec0691
1397 changed files with 127242 additions and 0 deletions
--- a/packages/media/AGENTS.md
+++ b/packages/media/AGENTS.md
@@ -0,0 +1,146 @@
+# AGENTS.md — media
+
+Media upload collection (images, PDFs, etc.) and media-related use cases (get, list, delete). Provides the Media Payload collection and tRPC procedures for asset management.
+
+## Overview
+
+`@repo/media` owns: Media domain model, media-scoped errors, the `IMediaRepository` interface, three use cases, three controllers, a real Payload-backed repository, and the tRPC `mediaRouter`. No query builders today — `./ui` is a placeholder.
+
+## Layer responsibilities
+
+| Layer                              | Key files                                                                                                            |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| **entities/models**                | `media.ts` — `mediaSchema` + `Media` type (filename, mimeType, filesize, url, etc.)                                  |
+| **entities/errors**                | `media.ts` (MediaNotFoundError), `common.ts` (InputParseError)                                                       |
+| **application/use-cases**          | `get-media.use-case.ts`, `list-media.use-case.ts`, `delete-media.use-case.ts` — factory functions + exported schemas |
+| **application/repositories**       | `media.repository.interface.ts` — `IMediaRepository`                                                                 |
+| **infrastructure/repositories**    | `media.repository.ts` (real Payload-backed), `media.repository.mock.ts` (in-memory)                                  |
+| **interface-adapters/controllers** | `get-media.controller.ts`, `list-media.controller.ts`, `delete-media.controller.ts` — one file per use case          |
+| **di**                             | `symbols.ts` (MEDIA_SYMBOLS), `module.ts`, `container.ts`, `bind-production.ts`                                      |
+| **integrations/api**               | `procedures.ts` (mediaProcedure), `router.ts` (mediaRouter), `index.ts`                                              |
+| **integrations/cms**               | `collections/media.ts` — Payload Media CollectionConfig                                                              |
+| **ui**                             | `src/ui/index.ts` — placeholder (no query builders today)                                                            |
+
+### DI symbols
+
+`MEDIA_SYMBOLS` includes: `IMediaRepository`, `IGetMediaUseCase`, `IListMediaUseCase`, `IDeleteMediaUseCase`, `IGetMediaController`, `IListMediaController`, `IDeleteMediaController`.
+
+## Public exports
+
+| Subpath                | Contents                                                                                                                                                                                                                                                                             |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `.`                    | `Media` type; `MediaNotFoundError`, `InputParseError`; `getMediaInputSchema`, `getMediaOutputSchema`, `listMediaInputSchema`, `listMediaOutputSchema`, `deleteMediaInputSchema`; all `XInput`/`XOutput` types + `IXUseCase` aliases; `IXController` type aliases; `MediaRouter` type |
+| `./ui`                 | Placeholder — extend here when media gains React Query builders, never re-add to root                                                                                                                                                                                                |
+| `./api`                | `mediaRouter` (tRPC router)                                                                                                                                                                                                                                                          |
+| `./cms`                | Payload Media collection definition                                                                                                                                                                                                                                                  |
+| `./di/bind-production` | `bindProductionMedia(ctx: BindProductionContext)` — swaps mock impls for real Payload-backed ones at app boot                                                                                                                                                                        |
+| `./di/bind-dev-seed`   | `bindDevSeedMedia(ctx: BindContext)` — replaces the default empty mock with a populated one for dev / Storybook                                                                                                                                                                      |
+
+## Use-case + controller patterns
+
+See `CLAUDE.md` Key Conventions and `docs/architecture/overview.md` for the canonical factory templates.
+
+### Use cases
+
+| Use case             | Input schema                                                      | Output schema                                    | Notes                                                                                        |
+| -------------------- | ----------------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| `getMediaUseCase`    | `getMediaInputSchema` — `{ id: string }`                          | `getMediaOutputSchema` — `= mediaSchema`         | Throws `MediaNotFoundError` when id not found; ends with `getMediaOutputSchema.parse(media)` |
+| `listMediaUseCase`   | `listMediaInputSchema` — `{ limit?: int, offset?: int }` (strict) | `listMediaOutputSchema` — `z.array(mediaSchema)` | Returns paginated list; ends with `listMediaOutputSchema.parse(result)`                      |
+| `deleteMediaUseCase` | `deleteMediaInputSchema` — `{ id: string }`                       | void (no `xOutputSchema`)                        | Throws `MediaNotFoundError` when id not found; no output schema                              |
+
+### Controllers
+
+| Controller              | Presenter          | Return type                                       |
+| ----------------------- | ------------------ | ------------------------------------------------- |
+| `getMediaController`    | identity presenter | `Promise<ReturnType<typeof presenter>>` (Media)   |
+| `listMediaController`   | identity presenter | `Promise<ReturnType<typeof presenter>>` (Media[]) |
+| `deleteMediaController` | none (void)        | `Promise<void>`                                   |
+
+All controllers accept `unknown` input and `safeParse` with the use-case's `xInputSchema`, throwing `InputParseError` on failure.
+
+## Errors → tRPC codes
+
+| Error class          | tRPC code     | Thrown by                               |
+| -------------------- | ------------- | --------------------------------------- |
+| `InputParseError`    | `BAD_REQUEST` | controllers (safeParse failure)         |
+| `MediaNotFoundError` | `NOT_FOUND`   | `getMediaUseCase`, `deleteMediaUseCase` |
+
+Defined in `src/integrations/api/procedures.ts` via `mediaProcedure = t.procedure.use(defineErrorMiddleware([...]))`.
+
+## Tests
+
+- **Factories:** `src/__factories__/media.factory.ts`
+- **Contract suite:** `src/__contracts__/media-repository.contract.ts` — runs against mock and real `MediaRepository`
+- **Unit tests:** colocated `*.test.ts` next to each source file
+- **Feature integration:** `src/integrations/api/router.test.ts` — R26 router error-mapping tests (covers all three procedures)
+- **R25** (output validation): `get-media.use-case.test.ts` and `list-media.use-case.test.ts` each have tests that inject a repository mock returning malformed data and assert `.rejects.toBeInstanceOf(ZodError)`. `deleteMedia` is void — no R25.
+- **R26** (router error mapping): `router.test.ts` asserts `NOT_FOUND` on `getMedia` with nonexistent id, `BAD_REQUEST` on `getMedia` with empty input, `NOT_FOUND` on `deleteMedia` with nonexistent id, and `NOT_FOUND` via an inline `NullMediaRepository` rebind.
+- **R27/R28** (presenter shape): `getMedia` and `listMedia` use identity presenters — no reshape test obligation. `deleteMedia` is void — no presenter.
+
+```bash
+pnpm test --filter @repo/media
+pnpm test --filter @repo/media -- --watch
+```
+
+See `docs/guides/tdd-workflow.md` for the full cycle.
+
+## Directory structure
+
+```
+src/
+  entities/
+    models/
+      media.ts         # mediaSchema, Media type
+    errors/
+      media.ts         # MediaNotFoundError
+      common.ts        # InputParseError
+  application/
+    repositories/
+      media.repository.interface.ts
+    use-cases/
+      get-media.use-case.ts
+      list-media.use-case.ts
+      delete-media.use-case.ts
+  infrastructure/
+    repositories/
+      media.repository.ts          # real Payload-backed
+      media.repository.mock.ts
+  interface-adapters/
+    controllers/
+      get-media.controller.ts
+      list-media.controller.ts
+      delete-media.controller.ts
+  integrations/
+    api/
+      procedures.ts    # mediaProcedure
+      router.ts        # mediaRouter
+      index.ts
+    cms/
+      collections/
+        media.ts
+      index.ts
+  di/
+    symbols.ts         # MEDIA_SYMBOLS
+    module.ts
+    container.ts
+    bind-production.ts
+  ui/
+    index.ts           # placeholder
+  index.ts
+  __factories__/
+    media.factory.ts
+  __contracts__/
+    media-repository.contract.ts
+```
+
+## What it must NOT import
+
+- Any other feature package (`@repo/auth`, `@repo/blog`, etc.)
+- Any app package
+- `@repo/core-api`, `@repo/core-cms`, `@repo/core-trpc`, `@repo/core-ui` directly; only `@repo/core-shared`
+  > Note: `@repo/core-trpc` and `@repo/core-ui` are optional packages scaffolded via `pnpm turbo gen core-package trpc` / `ui`. If not present, these constraints still apply to any future installation.
+
+## Cross-links
+
+- ADR-012 (`docs/decisions/adr-012-feature-conventions.md`) — factory-style use cases, per-use-case controllers, file-naming conventions
+- ADR-013 (`docs/decisions/adr-013-input-output-unification.md`) — schemas-in-use-case, presenter, `./ui` subpath, error middleware
--- a/packages/media/CHANGELOG.md
+++ b/packages/media/CHANGELOG.md
@@ -0,0 +1,11 @@
+# Changelog — @repo/media
+
+All notable changes to the `media` feature package. Maintained by [release-please](https://github.com/googleapis/release-please) on merges to `main`. See [ADR-021](../../docs/decisions/adr-021-versioning-and-changelog.md) and [`docs/guides/releasing.md`](../../docs/guides/releasing.md).
+
+## 0.1.0 (2026-05-13)
+
+### Initial baseline
+
+The `media` feature established at v0.1.0 alongside the hybrid versioning rollout (ADR-021). The feature has been stable since the template-reset cleanup; this is the first formally versioned baseline.
+
+Future entries appear above this section as release-please assembles them from conventional commits scoped to `packages/media/**` since the last release.
--- a/packages/media/eslint.config.js
+++ b/packages/media/eslint.config.js
@@ -0,0 +1,3 @@
+import baseConfig from "@repo/core-eslint/base";
+
+export default baseConfig;
--- a/packages/media/package.json
+++ b/packages/media/package.json
@@ -0,0 +1,36 @@
+{
+  "name": "@repo/media",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./ui": "./src/ui/index.ts",
+    "./cms": "./src/integrations/cms/index.ts",
+    "./api": "./src/integrations/api/index.ts",
+    "./di/bind-production": "./src/di/bind-production.ts",
+    "./di/bind-dev-seed": "./src/di/bind-dev-seed.ts"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@repo/core-shared": "workspace:*",
+    "@trpc/server": "^11.0.0",
+    "inversify": "^6.2.0",
+    "payload": "^3.14.0",
+    "reflect-metadata": "^0.2.2",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@repo/core-eslint": "workspace:*",
+    "@repo/core-testing": "workspace:*",
+    "@repo/core-typescript": "workspace:*",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "vitest": "^3.1.0"
+  }
+}
--- a/packages/media/src/contracts/media-repository.contract.ts
+++ b/packages/media/src/contracts/media-repository.contract.ts
@@ -0,0 +1,95 @@
+import { it, expect, beforeEach, describe } from "vitest";
+import { defineContractSuite } from "@repo/core-testing/contract";
+import type { IMediaRepository } from "../application/repositories/media.repository.interface";
+import { mediaFactory } from "../__factories__/media.factory";
+
+export const mediaRepositoryContract = defineContractSuite<IMediaRepository>(
+  "IMediaRepository",
+  ({ buildSubject, getTracer }) => {
+    let repo: IMediaRepository;
+
+    beforeEach(async () => {
+      mediaFactory.reset();
+      repo = await buildSubject();
+    });
+
+    // --- getMedia ---
+
+    it("getMedia returns undefined for a missing id", async () => {
+      const result = await repo.getMedia("does-not-exist");
+      expect(result).toBeUndefined();
+    });
+
+    // --- listMedia ---
+
+    it("listMedia returns empty array when no media exists", async () => {
+      const result = await repo.listMedia();
+      expect(result).toHaveLength(0);
+    });
+
+    // --- deleteMedia ---
+
+    it("deleteMedia removes the item so getMedia returns undefined", async () => {
+      const seed = mediaFactory.build({ id: "contract-1" });
+      // @ts-expect-error _store is a test helper on MockMediaRepository
+      if (typeof repo._store === "function") {
+        // @ts-expect-error _store is a test helper
+        await repo._store(seed);
+      }
+      await repo.deleteMedia("contract-1");
+      const result = await repo.getMedia("contract-1");
+      expect(result).toBeUndefined();
+    });
+
+    it("listMedia with limit returns at most limit items", async () => {
+      // Only verifiable on mock; for real impl this checks the interface
+      const result = await repo.listMedia({ limit: 0 });
+      expect(Array.isArray(result)).toBe(true);
+    });
+
+    it("listMedia with offset skips items", async () => {
+      const result = await repo.listMedia({ offset: 100 });
+      expect(Array.isArray(result)).toBe(true);
+    });
+
+    it("getMedia returns undefined for empty string id", async () => {
+      const result = await repo.getMedia("");
+      expect(result).toBeUndefined();
+    });
+
+    describe("span emission", () => {
+      it("getMedia emits media.getMedia span with id attribute", async () => {
+        if (!getTracer) return;
+        const tracer = getTracer();
+        tracer.reset();
+        await repo.getMedia("nonexistent");
+        const span = tracer.findSpan("media.getMedia");
+        expect(span).toBeDefined();
+        expect(span!.op).toBe("repository");
+        expect(span!.attributes.id).toBe("nonexistent");
+      });
+
+      it("listMedia emits media.listMedia span with op=repository", async () => {
+        if (!getTracer) return;
+        const tracer = getTracer();
+        tracer.reset();
+        await repo.listMedia({ limit: 10 });
+        const span = tracer.findSpan("media.listMedia");
+        expect(span).toBeDefined();
+        expect(span!.op).toBe("repository");
+        expect(span!.attributes.limit).toBe(10);
+      });
+
+      it("deleteMedia emits media.deleteMedia span with id attribute", async () => {
+        if (!getTracer) return;
+        const tracer = getTracer();
+        tracer.reset();
+        await repo.deleteMedia("nonexistent");
+        const span = tracer.findSpan("media.deleteMedia");
+        expect(span).toBeDefined();
+        expect(span!.op).toBe("repository");
+        expect(span!.attributes.id).toBe("nonexistent");
+      });
+    });
+  },
+);
--- a/packages/media/src/factories/index.ts
+++ b/packages/media/src/factories/index.ts
@@ -0,0 +1,2 @@
+export { mediaFactory } from "./media.factory";
+export type { Media } from "../entities/models/media";
--- a/packages/media/src/factories/media.factory.test.ts
+++ b/packages/media/src/factories/media.factory.test.ts
@@ -0,0 +1,28 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { mediaFactory } from "@/__factories__/media.factory";
+
+describe("mediaFactory", () => {
+  beforeEach(() => mediaFactory.reset());
+
+  it("returns a Media object with stable defaults", () => {
+    const m = mediaFactory.build();
+    expect(m.id).toBe("media-1");
+    expect(m.alt).toBe("Media 1");
+    expect(m.mimeType).toBe("image/png");
+    expect(m.filesize).toBe(1024);
+  });
+
+  it("applies overrides", () => {
+    const m = mediaFactory.build({ alt: "Custom alt", mimeType: "image/jpeg" });
+    expect(m.alt).toBe("Custom alt");
+    expect(m.mimeType).toBe("image/jpeg");
+    expect(m.id).toBe("media-1");
+  });
+
+  it("increments sequence per build", () => {
+    const a = mediaFactory.build();
+    const b = mediaFactory.build();
+    expect(a.id).toBe("media-1");
+    expect(b.id).toBe("media-2");
+  });
+});
--- a/packages/media/src/factories/media.factory.ts
+++ b/packages/media/src/factories/media.factory.ts
@@ -0,0 +1,11 @@
+import { defineFactory } from "@repo/core-testing/factory";
+import type { Media } from "../entities/models/media";
+
+export const mediaFactory = defineFactory<Media>(({ sequence }) => ({
+  id: `media-${sequence}`,
+  alt: `Media ${sequence}`,
+  url: `https://cdn.example.com/media-${sequence}.png`,
+  filename: `media-${sequence}.png`,
+  mimeType: "image/png",
+  filesize: 1024,
+}));
--- a/packages/media/src/seeds/dev.ts
+++ b/packages/media/src/seeds/dev.ts
@@ -0,0 +1,38 @@
+import { mediaFactory } from "../__factories__/media.factory";
+import type { Media } from "../entities/models/media";
+
+/**
+ * Realistic media seed for dev mode + storybook stories.
+ *
+ * Built from `mediaFactory` so factory defaults take care of boring fields
+ * and we only override what makes the data look like a real media library.
+ *
+ * Lazily produced so importing this module is side-effect-free — the
+ * factory's sequence counter only advances when a binder calls
+ * `buildDevMedia()`.
+ */
+export function buildDevMedia(): Media[] {
+  return [
+    mediaFactory.build({
+      id: "placeholder-1",
+      alt: "Hero background image",
+      url: "/dev/placeholder-1.jpg",
+      filename: "placeholder-1.jpg",
+      mimeType: "image/jpeg",
+    }),
+    mediaFactory.build({
+      id: "placeholder-2",
+      alt: "Team photo",
+      url: "/dev/placeholder-2.jpg",
+      filename: "placeholder-2.jpg",
+      mimeType: "image/jpeg",
+    }),
+    mediaFactory.build({
+      id: "placeholder-3",
+      alt: "Product screenshot",
+      url: "/dev/placeholder-3.png",
+      filename: "placeholder-3.png",
+      mimeType: "image/png",
+    }),
+  ];
+}
--- a/packages/media/src/application/repositories/media.repository.interface.ts
+++ b/packages/media/src/application/repositories/media.repository.interface.ts
@@ -0,0 +1,7 @@
+import type { Media } from "../../entities/models/media";
+
+export interface IMediaRepository {
+  getMedia(id: string): Promise<Media | undefined>;
+  listMedia(opts?: { limit?: number; offset?: number }): Promise<Media[]>;
+  deleteMedia(id: string): Promise<void>;
+}
--- a/packages/media/src/application/use-cases/delete-media.use-case.test.ts
+++ b/packages/media/src/application/use-cases/delete-media.use-case.test.ts
@@ -0,0 +1,26 @@
+import { describe, it, expect } from "vitest";
+import { deleteMediaUseCase } from "@/application/use-cases/delete-media.use-case";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import { MediaNotFoundError } from "@/entities/errors/media";
+import { mediaFactory } from "@/__factories__/media.factory";
+
+describe("deleteMediaUseCase", () => {
+  it("deletes media when found", async () => {
+    const repo = new MockMediaRepository();
+    const seed = mediaFactory.build({ id: "m-1" });
+    await repo._store(seed);
+
+    const useCase = deleteMediaUseCase(repo);
+    await useCase({ id: "m-1" });
+
+    const result = await repo.getMedia("m-1");
+    expect(result).toBeUndefined();
+  });
+
+  it("throws MediaNotFoundError when id does not exist", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = deleteMediaUseCase(repo);
+
+    await expect(useCase({ id: "missing" })).rejects.toThrow(MediaNotFoundError);
+  });
+});
--- a/packages/media/src/application/use-cases/delete-media.use-case.ts
+++ b/packages/media/src/application/use-cases/delete-media.use-case.ts
@@ -0,0 +1,23 @@
+import { z } from "zod";
+
+import { MediaNotFoundError } from "../../entities/errors/media";
+import type { IMediaRepository } from "../repositories/media.repository.interface";
+
+// ── Input ────────────────────────────────────────────────────────────────
+export const deleteMediaInputSchema = z.object({ id: z.string().min(1) }).strict();
+export type DeleteMediaInput = z.infer<typeof deleteMediaInputSchema>;
+
+// No output schema — use case returns void.
+
+// ── Use case ─────────────────────────────────────────────────────────────
+export type IDeleteMediaUseCase = ReturnType<typeof deleteMediaUseCase>;
+
+export const deleteMediaUseCase =
+  (mediaRepository: IMediaRepository) =>
+  async (input: DeleteMediaInput): Promise<void> => {
+    const existing = await mediaRepository.getMedia(input.id);
+    if (!existing) {
+      throw new MediaNotFoundError(`Media with id "${input.id}" not found`);
+    }
+    await mediaRepository.deleteMedia(input.id);
+  };
--- a/packages/media/src/application/use-cases/get-media.use-case.test.ts
+++ b/packages/media/src/application/use-cases/get-media.use-case.test.ts
@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest";
+import { ZodError } from "zod";
+import {
+  getMediaUseCase,
+  getMediaOutputSchema,
+} from "@/application/use-cases/get-media.use-case";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import { MediaNotFoundError } from "@/entities/errors/media";
+import { mediaFactory } from "@/__factories__/media.factory";
+
+describe("getMediaUseCase", () => {
+  it("returns media when found", async () => {
+    const repo = new MockMediaRepository();
+    const seed = mediaFactory.build({ id: "m-1" });
+    await repo._store(seed);
+
+    const useCase = getMediaUseCase(repo);
+    const result = await useCase({ id: "m-1" });
+
+    expect(result.id).toBe("m-1");
+    expect(result.alt).toBe(seed.alt);
+  });
+
+  it("throws MediaNotFoundError when id does not exist", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = getMediaUseCase(repo);
+
+    await expect(useCase({ id: "missing" })).rejects.toThrow(
+      MediaNotFoundError,
+    );
+  });
+
+  it("parses valid output without error", async () => {
+    const validMedia = mediaFactory.build({ id: "m-r25" });
+    expect(() => getMediaOutputSchema.parse(validMedia)).not.toThrow();
+  });
+
+  it("throws ZodError when repository returns malformed media", async () => {
+    const repo = new MockMediaRepository();
+    // Store a malformed object (missing required fields) via type cast
+    await repo._store({ id: "bad", alt: "alt", url: "u" } as never);
+
+    const useCase = getMediaUseCase(repo);
+    await expect(useCase({ id: "bad" })).rejects.toBeInstanceOf(ZodError);
+  });
+});
--- a/packages/media/src/application/use-cases/get-media.use-case.ts
+++ b/packages/media/src/application/use-cases/get-media.use-case.ts
@@ -0,0 +1,26 @@
+import { z } from "zod";
+
+import { MediaNotFoundError } from "../../entities/errors/media";
+import { mediaSchema } from "../../entities/models/media";
+import type { IMediaRepository } from "../repositories/media.repository.interface";
+
+// ── Input ────────────────────────────────────────────────────────────────
+export const getMediaInputSchema = z.object({ id: z.string().min(1) }).strict();
+export type GetMediaInput = z.infer<typeof getMediaInputSchema>;
+
+// ── Output ───────────────────────────────────────────────────────────────
+export const getMediaOutputSchema = mediaSchema;
+export type GetMediaOutput = z.infer<typeof getMediaOutputSchema>;
+
+// ── Use case ─────────────────────────────────────────────────────────────
+export type IGetMediaUseCase = ReturnType<typeof getMediaUseCase>;
+
+export const getMediaUseCase =
+  (mediaRepository: IMediaRepository) =>
+  async (input: GetMediaInput): Promise<GetMediaOutput> => {
+    const media = await mediaRepository.getMedia(input.id);
+    if (!media) {
+      throw new MediaNotFoundError(`Media with id "${input.id}" not found`);
+    }
+    return getMediaOutputSchema.parse(media);
+  };
--- a/packages/media/src/application/use-cases/list-media.use-case.test.ts
+++ b/packages/media/src/application/use-cases/list-media.use-case.test.ts
@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { ZodError } from "zod";
+import {
+  listMediaUseCase,
+  listMediaOutputSchema,
+} from "@/application/use-cases/list-media.use-case";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import { mediaFactory } from "@/__factories__/media.factory";
+
+describe("listMediaUseCase", () => {
+  it("returns empty array when no media exists", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = listMediaUseCase(repo);
+    const result = await useCase({});
+    expect(result).toHaveLength(0);
+  });
+
+  it("returns all media when store has items", async () => {
+    const repo = new MockMediaRepository();
+    await repo._store(mediaFactory.build());
+    await repo._store(mediaFactory.build());
+
+    const useCase = listMediaUseCase(repo);
+    const result = await useCase({});
+    expect(result).toHaveLength(2);
+  });
+
+  it("respects limit and offset options", async () => {
+    const repo = new MockMediaRepository();
+    for (let i = 0; i < 5; i++) {
+      await repo._store(mediaFactory.build());
+    }
+
+    const useCase = listMediaUseCase(repo);
+    const result = await useCase({ limit: 2, offset: 1 });
+    expect(result).toHaveLength(2);
+  });
+
+  it("parses valid output without error", async () => {
+    const items = [mediaFactory.build(), mediaFactory.build()];
+    expect(() => listMediaOutputSchema.parse(items)).not.toThrow();
+  });
+
+  it("throws ZodError when repository returns malformed items", async () => {
+    const repo = new MockMediaRepository();
+    // Store a malformed object (missing required fields)
+    await repo._store({ id: "bad", alt: "alt", url: "u" } as never);
+
+    const useCase = listMediaUseCase(repo);
+    await expect(useCase({})).rejects.toBeInstanceOf(ZodError);
+  });
+});
--- a/packages/media/src/application/use-cases/list-media.use-case.ts
+++ b/packages/media/src/application/use-cases/list-media.use-case.ts
@@ -0,0 +1,27 @@
+import { z } from "zod";
+
+import { mediaSchema } from "../../entities/models/media";
+import type { IMediaRepository } from "../repositories/media.repository.interface";
+
+// ── Input ────────────────────────────────────────────────────────────────
+export const listMediaInputSchema = z
+  .object({
+    limit: z.number().int().positive().optional(),
+    offset: z.number().int().nonnegative().optional(),
+  })
+  .strict();
+export type ListMediaInput = z.infer<typeof listMediaInputSchema>;
+
+// ── Output ───────────────────────────────────────────────────────────────
+export const listMediaOutputSchema = z.array(mediaSchema);
+export type ListMediaOutput = z.infer<typeof listMediaOutputSchema>;
+
+// ── Use case ─────────────────────────────────────────────────────────────
+export type IListMediaUseCase = ReturnType<typeof listMediaUseCase>;
+
+export const listMediaUseCase =
+  (mediaRepository: IMediaRepository) =>
+  async (input: ListMediaInput): Promise<ListMediaOutput> => {
+    const result = await mediaRepository.listMedia(input);
+    return listMediaOutputSchema.parse(result);
+  };
--- a/packages/media/src/di/bind-dev-seed.test.ts
+++ b/packages/media/src/di/bind-dev-seed.test.ts
@@ -0,0 +1,75 @@
+import "reflect-metadata";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { NoopTracer, NoopLogger } from "@repo/core-shared/instrumentation";
+import { RecordingEventBus, RecordingJobQueue } from "@repo/core-testing/instrumentation";
+import { bindDevSeedMedia } from "@/di/bind-dev-seed";
+import { mediaContainer } from "@/di/container";
+import { MEDIA_SYMBOLS } from "@/di/symbols";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import type { IMediaRepository } from "@/application/repositories/media.repository.interface";
+
+const noop = { tracer: new NoopTracer(), logger: new NoopLogger() };
+
+describe("bindDevSeedMedia", () => {
+  // Each test starts from the default empty-mock binding and tears down
+  // afterwards so the global mediaContainer state stays clean for siblings.
+  beforeEach(() => {
+    if (mediaContainer.isBound(MEDIA_SYMBOLS.IMediaRepository)) {
+      mediaContainer.unbind(MEDIA_SYMBOLS.IMediaRepository);
+    }
+    mediaContainer
+      .bind<IMediaRepository>(MEDIA_SYMBOLS.IMediaRepository)
+      .to(MockMediaRepository);
+  });
+
+  afterEach(() => {
+    if (mediaContainer.isBound(MEDIA_SYMBOLS.IMediaRepository)) {
+      mediaContainer.unbind(MEDIA_SYMBOLS.IMediaRepository);
+    }
+    mediaContainer
+      .bind<IMediaRepository>(MEDIA_SYMBOLS.IMediaRepository)
+      .to(MockMediaRepository);
+  });
+
+  it("populates the repository with the dev media entries", async () => {
+    await bindDevSeedMedia({ ...noop, bus: new RecordingEventBus(), queue: new RecordingJobQueue() });
+
+    const repo = mediaContainer.get<IMediaRepository>(
+      MEDIA_SYMBOLS.IMediaRepository,
+    );
+    const all = await repo.listMedia();
+
+    expect(all.length).toBeGreaterThan(0);
+  });
+
+  it("seeds placeholder-1 reachable by id", async () => {
+    await bindDevSeedMedia({ ...noop, bus: new RecordingEventBus(), queue: new RecordingJobQueue() });
+
+    const repo = mediaContainer.get<IMediaRepository>(
+      MEDIA_SYMBOLS.IMediaRepository,
+    );
+    const item = await repo.getMedia("placeholder-1");
+
+    expect(item).toBeDefined();
+    expect(item?.url).toBe("/dev/placeholder-1.jpg");
+    expect(item?.alt).toBe("Hero background image");
+  });
+
+  it("is idempotent — calling twice rebuilds a fresh populated repo", async () => {
+    await bindDevSeedMedia({ ...noop, bus: new RecordingEventBus(), queue: new RecordingJobQueue() });
+    const before = mediaContainer.get<IMediaRepository>(
+      MEDIA_SYMBOLS.IMediaRepository,
+    );
+    const beforeCount = (await before.listMedia()).length;
+
+    await bindDevSeedMedia({ ...noop, bus: new RecordingEventBus(), queue: new RecordingJobQueue() });
+    const after = mediaContainer.get<IMediaRepository>(
+      MEDIA_SYMBOLS.IMediaRepository,
+    );
+    const afterCount = (await after.listMedia()).length;
+
+    expect(afterCount).toBe(beforeCount);
+    // It's a fresh instance — not the previous one.
+    expect(after).not.toBe(before);
+  });
+});
--- a/packages/media/src/di/bind-dev-seed.ts
+++ b/packages/media/src/di/bind-dev-seed.ts
@@ -0,0 +1,168 @@
+import {
+  withSpan,
+  withCapture,
+  INSTRUMENTATION_SYMBOLS,
+  type ITracer,
+  type ILogger,
+} from "@repo/core-shared/instrumentation";
+import type { BindContext } from "@repo/core-shared/di";
+import {
+  assertFeatureConformance,
+  wireUseCase,
+} from "@repo/core-shared/conformance";
+import { mediaManifest } from "../feature.manifest";
+import { mediaContainer } from "./container";
+import { MEDIA_SYMBOLS } from "./symbols";
+import { MockMediaRepository } from "../infrastructure/repositories/media.repository.mock";
+import { buildDevMedia } from "../__seeds__/dev";
+import { getMediaUseCase } from "../application/use-cases/get-media.use-case";
+import { listMediaUseCase } from "../application/use-cases/list-media.use-case";
+import { deleteMediaUseCase } from "../application/use-cases/delete-media.use-case";
+import { getMediaController } from "../interface-adapters/controllers/get-media.controller";
+import { listMediaController } from "../interface-adapters/controllers/list-media.controller";
+import { deleteMediaController } from "../interface-adapters/controllers/delete-media.controller";
+import type { IMediaRepository } from "../application/repositories/media.repository.interface";
+
+/**
+ * Replace the default empty mock with a populated one for dev mode + storybook.
+ *
+ * Call this from app boot when `USE_DEV_SEED=true`, mutually exclusive with
+ * `bindProductionMedia(config)`. Tests must NOT call this — they construct
+ * `new MockMediaRepository()` directly and seed via factories per-test.
+ *
+ * Idempotent: safe to call multiple times; each call rebuilds a fresh
+ * populated repo and rebinds the symbol.
+ */
+export async function bindDevSeedMedia(ctx: BindContext): Promise<void> {
+  const { tracer, logger, bus, queue, realtime, realtimeRegistry } = ctx;
+
+  // Bind shared instrumentation into feature container
+  if (mediaContainer.isBound(INSTRUMENTATION_SYMBOLS.TRACER)) {
+    mediaContainer.unbind(INSTRUMENTATION_SYMBOLS.TRACER);
+  }
+  if (mediaContainer.isBound(INSTRUMENTATION_SYMBOLS.LOGGER)) {
+    mediaContainer.unbind(INSTRUMENTATION_SYMBOLS.LOGGER);
+  }
+  mediaContainer
+    .bind<ITracer>(INSTRUMENTATION_SYMBOLS.TRACER)
+    .toConstantValue(tracer);
+  mediaContainer
+    .bind<ILogger>(INSTRUMENTATION_SYMBOLS.LOGGER)
+    .toConstantValue(logger);
+
+  if (mediaContainer.isBound(MEDIA_SYMBOLS.IMediaRepository)) {
+    mediaContainer.unbind(MEDIA_SYMBOLS.IMediaRepository);
+  }
+
+  const repo = new MockMediaRepository(tracer, logger);
+  for (const media of buildDevMedia()) {
+    await repo._store(media);
+  }
+
+  mediaContainer
+    .bind<IMediaRepository>(MEDIA_SYMBOLS.IMediaRepository)
+    .toConstantValue(repo);
+
+  // Use cases
+  const wrappedGetMedia = wireUseCase({
+    container: mediaContainer,
+    symbol: MEDIA_SYMBOLS.IGetMediaUseCase,
+    factory: getMediaUseCase,
+    deps: [repo],
+    feature: "media",
+    layer: "use-case",
+    name: "getMedia",
+    tracer,
+    logger,
+  });
+  const wrappedListMedia = wireUseCase({
+    container: mediaContainer,
+    symbol: MEDIA_SYMBOLS.IListMediaUseCase,
+    factory: listMediaUseCase,
+    deps: [repo],
+    feature: "media",
+    layer: "use-case",
+    name: "listMedia",
+    tracer,
+    logger,
+  });
+  const wrappedDeleteMedia = wireUseCase({
+    container: mediaContainer,
+    symbol: MEDIA_SYMBOLS.IDeleteMediaUseCase,
+    factory: deleteMediaUseCase,
+    deps: [repo],
+    feature: "media",
+    layer: "use-case",
+    name: "deleteMedia",
+    tracer,
+    logger,
+  });
+
+  for (const sym of [
+    MEDIA_SYMBOLS.IGetMediaController,
+    MEDIA_SYMBOLS.IListMediaController,
+    MEDIA_SYMBOLS.IDeleteMediaController,
+  ]) {
+    if (mediaContainer.isBound(sym)) mediaContainer.unbind(sym);
+  }
+
+  mediaContainer
+    .bind(MEDIA_SYMBOLS.IGetMediaController)
+    .toConstantValue(
+      withSpan(
+        tracer,
+        { name: "media.getMedia", op: "controller" },
+        withCapture(
+          logger,
+          { feature: "media", layer: "controller", name: "media.getMedia" },
+          getMediaController(wrappedGetMedia),
+        ),
+      ),
+    );
+  mediaContainer
+    .bind(MEDIA_SYMBOLS.IListMediaController)
+    .toConstantValue(
+      withSpan(
+        tracer,
+        { name: "media.listMedia", op: "controller" },
+        withCapture(
+          logger,
+          { feature: "media", layer: "controller", name: "media.listMedia" },
+          listMediaController(wrappedListMedia),
+        ),
+      ),
+    );
+  mediaContainer
+    .bind(MEDIA_SYMBOLS.IDeleteMediaController)
+    .toConstantValue(
+      withSpan(
+        tracer,
+        { name: "media.deleteMedia", op: "controller" },
+        withCapture(
+          logger,
+          { feature: "media", layer: "controller", name: "media.deleteMedia" },
+          deleteMediaController(wrappedDeleteMedia),
+        ),
+      ),
+    );
+  // bus + queue are passed through; generated handlers consume them at the anchors below.
+  void bus;
+  void queue;
+  void realtime;
+  void realtimeRegistry;
+  // <gen:event-handlers>
+  // <gen:jobs>
+  // <gen:realtime-handlers>
+
+  // Boot-time conformance check (dev-seed mode).
+  assertFeatureConformance(
+    mediaContainer,
+    mediaManifest,
+    {
+      getMedia: MEDIA_SYMBOLS.IGetMediaUseCase,
+      listMedia: MEDIA_SYMBOLS.IListMediaUseCase,
+      deleteMedia: MEDIA_SYMBOLS.IDeleteMediaUseCase,
+    },
+    ctx,
+  );
+}
--- a/packages/media/src/di/bind-production.smoke.test.ts
+++ b/packages/media/src/di/bind-production.smoke.test.ts
@@ -0,0 +1,17 @@
+import "reflect-metadata";
+import { describe, expect, it } from "vitest";
+import type { SanitizedConfig } from "payload";
+import { NoopTracer, NoopLogger } from "@repo/core-shared/instrumentation";
+import { bindProductionMedia } from "@/di/bind-production";
+
+describe("bindProductionMedia — boot-time conformance", () => {
+  it("binds every manifest use case through withSpan + withCapture", () => {
+    expect(() =>
+      bindProductionMedia({
+        config: {} as SanitizedConfig,
+        tracer: new NoopTracer(),
+        logger: new NoopLogger(),
+      }),
+    ).not.toThrow();
+  });
+});
--- a/packages/media/src/di/bind-production.ts
+++ b/packages/media/src/di/bind-production.ts
@@ -0,0 +1,151 @@
+import {
+  withSpan,
+  withCapture,
+  INSTRUMENTATION_SYMBOLS,
+  type ITracer,
+  type ILogger,
+} from "@repo/core-shared/instrumentation";
+import type { BindProductionContext } from "@repo/core-shared/di";
+import {
+  assertFeatureConformance,
+  wireUseCase,
+} from "@repo/core-shared/conformance";
+import { mediaContainer } from "./container";
+import { MEDIA_SYMBOLS } from "./symbols";
+import { mediaManifest } from "../feature.manifest";
+import { MediaRepository } from "../infrastructure/repositories/media.repository";
+import { getMediaUseCase } from "../application/use-cases/get-media.use-case";
+import { listMediaUseCase } from "../application/use-cases/list-media.use-case";
+import { deleteMediaUseCase } from "../application/use-cases/delete-media.use-case";
+import { getMediaController } from "../interface-adapters/controllers/get-media.controller";
+import { listMediaController } from "../interface-adapters/controllers/list-media.controller";
+import { deleteMediaController } from "../interface-adapters/controllers/delete-media.controller";
+
+export function bindProductionMedia(ctx: BindProductionContext): void {
+  const { config, tracer, logger, bus, queue, realtime, realtimeRegistry } =
+    ctx;
+
+  // Bind shared instrumentation into feature container
+  if (mediaContainer.isBound(INSTRUMENTATION_SYMBOLS.TRACER)) {
+    mediaContainer.unbind(INSTRUMENTATION_SYMBOLS.TRACER);
+  }
+  if (mediaContainer.isBound(INSTRUMENTATION_SYMBOLS.LOGGER)) {
+    mediaContainer.unbind(INSTRUMENTATION_SYMBOLS.LOGGER);
+  }
+  mediaContainer
+    .bind<ITracer>(INSTRUMENTATION_SYMBOLS.TRACER)
+    .toConstantValue(tracer);
+  mediaContainer
+    .bind<ILogger>(INSTRUMENTATION_SYMBOLS.LOGGER)
+    .toConstantValue(logger);
+
+  // Real repository
+  if (mediaContainer.isBound(MEDIA_SYMBOLS.IMediaRepository)) {
+    mediaContainer.unbind(MEDIA_SYMBOLS.IMediaRepository);
+  }
+  const repo = new MediaRepository(config, tracer, logger);
+  mediaContainer.bind(MEDIA_SYMBOLS.IMediaRepository).toConstantValue(repo);
+
+  // Use cases
+  const wrappedGetMedia = wireUseCase({
+    container: mediaContainer,
+    symbol: MEDIA_SYMBOLS.IGetMediaUseCase,
+    factory: getMediaUseCase,
+    deps: [repo],
+    feature: "media",
+    layer: "use-case",
+    name: "getMedia",
+    tracer,
+    logger,
+  });
+  const wrappedListMedia = wireUseCase({
+    container: mediaContainer,
+    symbol: MEDIA_SYMBOLS.IListMediaUseCase,
+    factory: listMediaUseCase,
+    deps: [repo],
+    feature: "media",
+    layer: "use-case",
+    name: "listMedia",
+    tracer,
+    logger,
+  });
+  const wrappedDeleteMedia = wireUseCase({
+    container: mediaContainer,
+    symbol: MEDIA_SYMBOLS.IDeleteMediaUseCase,
+    factory: deleteMediaUseCase,
+    deps: [repo],
+    feature: "media",
+    layer: "use-case",
+    name: "deleteMedia",
+    tracer,
+    logger,
+  });
+
+  // Controllers — wrapped with span at bind time
+  for (const sym of [
+    MEDIA_SYMBOLS.IGetMediaController,
+    MEDIA_SYMBOLS.IListMediaController,
+    MEDIA_SYMBOLS.IDeleteMediaController,
+  ]) {
+    if (mediaContainer.isBound(sym)) mediaContainer.unbind(sym);
+  }
+  mediaContainer
+    .bind(MEDIA_SYMBOLS.IGetMediaController)
+    .toConstantValue(
+      withSpan(
+        tracer,
+        { name: "media.getMedia", op: "controller" },
+        withCapture(
+          logger,
+          { feature: "media", layer: "controller", name: "media.getMedia" },
+          getMediaController(wrappedGetMedia),
+        ),
+      ),
+    );
+  mediaContainer
+    .bind(MEDIA_SYMBOLS.IListMediaController)
+    .toConstantValue(
+      withSpan(
+        tracer,
+        { name: "media.listMedia", op: "controller" },
+        withCapture(
+          logger,
+          { feature: "media", layer: "controller", name: "media.listMedia" },
+          listMediaController(wrappedListMedia),
+        ),
+      ),
+    );
+  mediaContainer
+    .bind(MEDIA_SYMBOLS.IDeleteMediaController)
+    .toConstantValue(
+      withSpan(
+        tracer,
+        { name: "media.deleteMedia", op: "controller" },
+        withCapture(
+          logger,
+          { feature: "media", layer: "controller", name: "media.deleteMedia" },
+          deleteMediaController(wrappedDeleteMedia),
+        ),
+      ),
+    );
+  // bus + queue are passed through; generated handlers consume them at the anchors below.
+  void bus;
+  void queue;
+  void realtime;
+  void realtimeRegistry;
+  // <gen:event-handlers>
+  // <gen:jobs>
+  // <gen:realtime-handlers>
+
+  // Boot-time conformance check.
+  assertFeatureConformance(
+    mediaContainer,
+    mediaManifest,
+    {
+      getMedia: MEDIA_SYMBOLS.IGetMediaUseCase,
+      listMedia: MEDIA_SYMBOLS.IListMediaUseCase,
+      deleteMedia: MEDIA_SYMBOLS.IDeleteMediaUseCase,
+    },
+    ctx,
+  );
+}
--- a/packages/media/src/di/container.test.ts
+++ b/packages/media/src/di/container.test.ts
@@ -0,0 +1,52 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mediaContainer } from "@/di/container";
+import { MEDIA_SYMBOLS } from "@/di/symbols";
+import { MediaModule } from "@/di/module";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import type { IMediaRepository } from "@/application/repositories/media.repository.interface";
+
+describe("mediaContainer", () => {
+  beforeEach(() => {
+    mediaContainer.unbindAll();
+    mediaContainer.load(MediaModule);
+  });
+
+  afterEach(() => {
+    mediaContainer.unbindAll();
+  });
+
+  it("resolves IMediaRepository to MockMediaRepository by default binding", () => {
+    const repo = mediaContainer.get<IMediaRepository>(MEDIA_SYMBOLS.IMediaRepository);
+    expect(repo).toBeInstanceOf(MockMediaRepository);
+  });
+
+  it("resolves IGetMediaController as a function", () => {
+    const ctrl = mediaContainer.get(MEDIA_SYMBOLS.IGetMediaController);
+    expect(typeof ctrl).toBe("function");
+  });
+
+  it("resolves IListMediaController as a function", () => {
+    const ctrl = mediaContainer.get(MEDIA_SYMBOLS.IListMediaController);
+    expect(typeof ctrl).toBe("function");
+  });
+
+  it("resolves IDeleteMediaController as a function", () => {
+    const ctrl = mediaContainer.get(MEDIA_SYMBOLS.IDeleteMediaController);
+    expect(typeof ctrl).toBe("function");
+  });
+
+  it("resolves IGetMediaUseCase as a function", () => {
+    const uc = mediaContainer.get(MEDIA_SYMBOLS.IGetMediaUseCase);
+    expect(typeof uc).toBe("function");
+  });
+
+  it("resolves IListMediaUseCase as a function", () => {
+    const uc = mediaContainer.get(MEDIA_SYMBOLS.IListMediaUseCase);
+    expect(typeof uc).toBe("function");
+  });
+
+  it("resolves IDeleteMediaUseCase as a function", () => {
+    const uc = mediaContainer.get(MEDIA_SYMBOLS.IDeleteMediaUseCase);
+    expect(typeof uc).toBe("function");
+  });
+});
--- a/packages/media/src/di/container.ts
+++ b/packages/media/src/di/container.ts
@@ -0,0 +1,6 @@
+import "reflect-metadata";
+import { Container } from "inversify";
+import { MediaModule } from "./module";
+
+export const mediaContainer = new Container({ defaultScope: "Singleton" });
+mediaContainer.load(MediaModule);
--- a/packages/media/src/di/module.ts
+++ b/packages/media/src/di/module.ts
@@ -0,0 +1,69 @@
+import { ContainerModule, type interfaces } from "inversify";
+
+import type { IMediaRepository } from "../application/repositories/media.repository.interface";
+import { MockMediaRepository } from "../infrastructure/repositories/media.repository.mock";
+import {
+  getMediaUseCase,
+  type IGetMediaUseCase,
+} from "../application/use-cases/get-media.use-case";
+import {
+  listMediaUseCase,
+  type IListMediaUseCase,
+} from "../application/use-cases/list-media.use-case";
+import {
+  deleteMediaUseCase,
+  type IDeleteMediaUseCase,
+} from "../application/use-cases/delete-media.use-case";
+import {
+  getMediaController,
+  type IGetMediaController,
+} from "../interface-adapters/controllers/get-media.controller";
+import {
+  listMediaController,
+  type IListMediaController,
+} from "../interface-adapters/controllers/list-media.controller";
+import {
+  deleteMediaController,
+  type IDeleteMediaController,
+} from "../interface-adapters/controllers/delete-media.controller";
+import { MEDIA_SYMBOLS } from "./symbols";
+
+export const MediaModule = new ContainerModule((bind: interfaces.Bind) => {
+  bind<IMediaRepository>(MEDIA_SYMBOLS.IMediaRepository).to(MockMediaRepository);
+
+  bind<IGetMediaUseCase>(MEDIA_SYMBOLS.IGetMediaUseCase).toDynamicValue((ctx) =>
+    getMediaUseCase(
+      ctx.container.get<IMediaRepository>(MEDIA_SYMBOLS.IMediaRepository),
+    ),
+  );
+
+  bind<IListMediaUseCase>(MEDIA_SYMBOLS.IListMediaUseCase).toDynamicValue((ctx) =>
+    listMediaUseCase(
+      ctx.container.get<IMediaRepository>(MEDIA_SYMBOLS.IMediaRepository),
+    ),
+  );
+
+  bind<IDeleteMediaUseCase>(MEDIA_SYMBOLS.IDeleteMediaUseCase).toDynamicValue((ctx) =>
+    deleteMediaUseCase(
+      ctx.container.get<IMediaRepository>(MEDIA_SYMBOLS.IMediaRepository),
+    ),
+  );
+
+  bind<IGetMediaController>(MEDIA_SYMBOLS.IGetMediaController).toDynamicValue((ctx) =>
+    getMediaController(
+      ctx.container.get<IGetMediaUseCase>(MEDIA_SYMBOLS.IGetMediaUseCase),
+    ),
+  );
+
+  bind<IListMediaController>(MEDIA_SYMBOLS.IListMediaController).toDynamicValue((ctx) =>
+    listMediaController(
+      ctx.container.get<IListMediaUseCase>(MEDIA_SYMBOLS.IListMediaUseCase),
+    ),
+  );
+
+  bind<IDeleteMediaController>(MEDIA_SYMBOLS.IDeleteMediaController).toDynamicValue((ctx) =>
+    deleteMediaController(
+      ctx.container.get<IDeleteMediaUseCase>(MEDIA_SYMBOLS.IDeleteMediaUseCase),
+    ),
+  );
+});
--- a/packages/media/src/di/symbols.ts
+++ b/packages/media/src/di/symbols.ts
@@ -0,0 +1,14 @@
+export const MEDIA_SYMBOLS = {
+  IMediaRepository: Symbol.for("media:IMediaRepository"),
+  // Use cases
+  IGetMediaUseCase: Symbol.for("media:IGetMediaUseCase"),
+  IListMediaUseCase: Symbol.for("media:IListMediaUseCase"),
+  IDeleteMediaUseCase: Symbol.for("media:IDeleteMediaUseCase"),
+  // Controllers
+  IGetMediaController: Symbol.for("media:IGetMediaController"),
+  IListMediaController: Symbol.for("media:IListMediaController"),
+  IDeleteMediaController: Symbol.for("media:IDeleteMediaController"),
+  // <gen:event-handler-symbols>
+  // <gen:job-symbols>
+  // <gen:realtime-handler-symbols>
+} as const;
--- a/packages/media/src/entities/errors/common.ts
+++ b/packages/media/src/entities/errors/common.ts
@@ -0,0 +1,6 @@
+export class InputParseError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "InputParseError";
+  }
+}
--- a/packages/media/src/entities/errors/media.test.ts
+++ b/packages/media/src/entities/errors/media.test.ts
@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest";
+import { MediaNotFoundError } from "@/entities/errors/media";
+
+describe("MediaNotFoundError", () => {
+  it("is an instance of Error", () => {
+    const err = new MediaNotFoundError();
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(MediaNotFoundError);
+  });
+
+  it("has default message", () => {
+    const err = new MediaNotFoundError();
+    expect(err.message).toBe("Media not found");
+  });
+
+  it("accepts a custom message", () => {
+    const err = new MediaNotFoundError("Custom message");
+    expect(err.message).toBe("Custom message");
+  });
+});
--- a/packages/media/src/entities/errors/media.ts
+++ b/packages/media/src/entities/errors/media.ts
@@ -0,0 +1,6 @@
+export class MediaNotFoundError extends Error {
+  constructor(message = "Media not found", options?: ErrorOptions) {
+    super(message, options);
+    this.name = "MediaNotFoundError";
+  }
+}
--- a/packages/media/src/entities/models/media.test.ts
+++ b/packages/media/src/entities/models/media.test.ts
@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { mediaSchema } from "@/entities/models/media";
+
+describe("mediaSchema", () => {
+  it("parses a valid media object", () => {
+    const result = mediaSchema.parse({
+      id: "1",
+      alt: "A photo",
+      url: "https://cdn.example.com/photo.png",
+      filename: "photo.png",
+      mimeType: "image/png",
+      filesize: 1024,
+    });
+    expect(result.id).toBe("1");
+    expect(result.alt).toBe("A photo");
+  });
+
+  it("parses a media object with optional width and height", () => {
+    const result = mediaSchema.parse({
+      id: "2",
+      alt: "A photo",
+      url: "https://cdn.example.com/photo.png",
+      filename: "photo.png",
+      mimeType: "image/png",
+      filesize: 2048,
+      width: 1920,
+      height: 1080,
+    });
+    expect(result.width).toBe(1920);
+    expect(result.height).toBe(1080);
+  });
+
+  it("parses without width and height (optional)", () => {
+    const result = mediaSchema.parse({
+      id: "3",
+      alt: "Doc",
+      url: "https://cdn.example.com/doc.pdf",
+      filename: "doc.pdf",
+      mimeType: "application/pdf",
+      filesize: 512,
+    });
+    expect(result.width).toBeUndefined();
+    expect(result.height).toBeUndefined();
+  });
+
+  it("throws for missing required fields", () => {
+    expect(() =>
+      mediaSchema.parse({ id: "1", alt: "x", url: "x" }),
+    ).toThrow();
+  });
+});
--- a/packages/media/src/entities/models/media.ts
+++ b/packages/media/src/entities/models/media.ts
@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+export const mediaSchema = z.object({
+  id: z.string(),
+  alt: z.string(),
+  url: z.string(),
+  filename: z.string(),
+  mimeType: z.string(),
+  filesize: z.number(),
+  width: z.number().optional(),
+  height: z.number().optional(),
+});
+
+export type Media = z.infer<typeof mediaSchema>;
--- a/packages/media/src/feature.manifest.ts
+++ b/packages/media/src/feature.manifest.ts
@@ -0,0 +1,37 @@
+import { defineFeature } from "@repo/core-shared/conformance";
+
+/**
+ * The media feature's conformance manifest.
+ */
+export const mediaManifest = defineFeature({
+  name: "media",
+  requiredCores: [],
+  useCases: {
+    getMedia: { mutates: false, audits: [], publishes: [], consumes: [] },
+    listMedia: { mutates: false, audits: [], publishes: [], consumes: [] },
+    deleteMedia: { mutates: true, audits: [], publishes: [], consumes: [] },
+  },
+  realtimeChannels: [],
+  jobs: [],
+  coverage: {
+    bands: {
+      baseline: { statements: 80, branches: 75, functions: 80, lines: 80 },
+      entities: { statements: 100, branches: 100, functions: 100, lines: 100 },
+      "use-cases": {
+        statements: 100,
+        branches: 95,
+        functions: 100,
+        lines: 100,
+      },
+      controllers: {
+        statements: 100,
+        branches: 95,
+        functions: 100,
+        lines: 100,
+      },
+    },
+    mutationTargets: ["entities", "use-cases"],
+  },
+} as const);
+
+export type MediaManifest = typeof mediaManifest;
--- a/packages/media/src/index.ts
+++ b/packages/media/src/index.ts
@@ -0,0 +1,34 @@
+export type { Media } from "./entities/models/media";
+export { MediaNotFoundError } from "./entities/errors/media";
+export { InputParseError } from "./entities/errors/common";
+export type { MediaRouter } from "./integrations/api/router";
+
+// Use case schemas + types
+export {
+  getMediaInputSchema,
+  getMediaOutputSchema,
+  type GetMediaInput,
+  type GetMediaOutput,
+  type IGetMediaUseCase,
+} from "./application/use-cases/get-media.use-case";
+export {
+  listMediaInputSchema,
+  listMediaOutputSchema,
+  type ListMediaInput,
+  type ListMediaOutput,
+  type IListMediaUseCase,
+} from "./application/use-cases/list-media.use-case";
+export {
+  deleteMediaInputSchema,
+  type DeleteMediaInput,
+  type IDeleteMediaUseCase,
+} from "./application/use-cases/delete-media.use-case";
+
+// Controller type aliases
+export type { IGetMediaController } from "./interface-adapters/controllers/get-media.controller";
+export type { IListMediaController } from "./interface-adapters/controllers/list-media.controller";
+export type { IDeleteMediaController } from "./interface-adapters/controllers/delete-media.controller";
+
+// <gen:events>
+// <gen:realtime-channels>
+export { mediaManifest, type MediaManifest } from "./feature.manifest";
--- a/packages/media/src/infrastructure/repositories/media.repository.mock.test.ts
+++ b/packages/media/src/infrastructure/repositories/media.repository.mock.test.ts
@@ -0,0 +1,12 @@
+import { describe } from "vitest";
+import { RecordingTracer } from "@repo/core-testing/instrumentation";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import { mediaRepositoryContract } from "@/__contracts__/media-repository.contract";
+
+describe("MockMediaRepository", () => {
+  const tracer = new RecordingTracer();
+  mediaRepositoryContract.run(
+    () => new MockMediaRepository(tracer),
+    { tracer: () => tracer },
+  );
+});
--- a/packages/media/src/infrastructure/repositories/media.repository.mock.ts
+++ b/packages/media/src/infrastructure/repositories/media.repository.mock.ts
@@ -0,0 +1,74 @@
+import "reflect-metadata";
+import { injectable } from "inversify";
+import {
+  NoopTracer,
+  NoopLogger,
+  type ITracer,
+  type ILogger,
+} from "@repo/core-shared/instrumentation";
+
+import type { IMediaRepository } from "../../application/repositories/media.repository.interface";
+import type { Media } from "../../entities/models/media";
+
+@injectable()
+export class MockMediaRepository implements IMediaRepository {
+  private _media: Media[] = [];
+  private tracer: ITracer;
+  private logger: ILogger;
+
+  constructor(
+    tracer: ITracer = new NoopTracer(),
+    logger: ILogger = new NoopLogger(),
+  ) {
+    this.tracer = tracer;
+    this.logger = logger;
+    void this.logger; // currently unused; reserved for future mock-thrown captures
+  }
+
+  /** Test helper — seeds the in-memory store directly. */
+  async _store(media: Media): Promise<void> {
+    this._media.push(media);
+  }
+
+  async getMedia(id: string): Promise<Media | undefined> {
+    return this.tracer.startSpan(
+      { name: "media.getMedia", op: "repository", attributes: { id } },
+      async (span) => {
+        const found = this._media.find((m) => m.id === id);
+        span.setAttribute("found", Boolean(found));
+        return found;
+      },
+    );
+  }
+
+  async listMedia(opts?: { limit?: number; offset?: number }): Promise<Media[]> {
+    return this.tracer.startSpan(
+      {
+        name: "media.listMedia",
+        op: "repository",
+        attributes: {
+          limit: opts?.limit ?? null,
+          offset: opts?.offset ?? null,
+        },
+      },
+      async (span) => {
+        const offset = opts?.offset ?? 0;
+        const limit = opts?.limit ?? 50;
+        const result = this._media.slice(offset, offset + limit);
+        span.setAttribute("count", result.length);
+        return result;
+      },
+    );
+  }
+
+  async deleteMedia(id: string): Promise<void> {
+    return this.tracer.startSpan(
+      { name: "media.deleteMedia", op: "repository", attributes: { id } },
+      async (span) => {
+        const before = this._media.length;
+        this._media = this._media.filter((m) => m.id !== id);
+        span.setAttribute("deleted", this._media.length < before);
+      },
+    );
+  }
+}
--- a/packages/media/src/infrastructure/repositories/media.repository.span.test.ts
+++ b/packages/media/src/infrastructure/repositories/media.repository.span.test.ts
@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest";
+import {
+  RecordingTracer,
+  RecordingLogger,
+} from "@repo/core-testing/instrumentation";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import type { Media } from "@/entities/models/media";
+
+const SAMPLE_MEDIA: Media = {
+  id: "m1",
+  alt: "Test image",
+  url: "/test/image.jpg",
+  filename: "image.jpg",
+  mimeType: "image/jpeg",
+  filesize: 1024,
+};
+
+// Mock repo also wraps in spans.
+describe("MockMediaRepository emits spans", () => {
+  it("getMedia emits one span with op='repository' and found attribute", async () => {
+    const tracer = new RecordingTracer();
+    const logger = new RecordingLogger();
+    const repo = new MockMediaRepository(tracer, logger);
+    await repo._store(SAMPLE_MEDIA);
+    await repo.getMedia("m1");
+    expect(tracer.spans).toHaveLength(1);
+    const getSpan = tracer.findSpan("media.getMedia");
+    expect(getSpan).toBeDefined();
+    expect(getSpan).toMatchObject({ name: "media.getMedia", op: "repository" });
+    expect(getSpan!.attributes.found).toBe(true);
+  });
+
+  it("listMedia emits a span with count attribute", async () => {
+    const tracer = new RecordingTracer();
+    const repo = new MockMediaRepository(tracer);
+    await repo._store(SAMPLE_MEDIA);
+    tracer.reset();
+    await repo.listMedia({ limit: 10 });
+    expect(tracer.findSpan("media.listMedia")).toBeDefined();
+    expect(tracer.findSpan("media.listMedia")!.attributes.limit).toBe(10);
+    expect(tracer.findSpan("media.listMedia")!.attributes.count).toBe(1);
+  });
+
+  it("deleteMedia emits a span with deleted=true", async () => {
+    const tracer = new RecordingTracer();
+    const repo = new MockMediaRepository(tracer);
+    await repo._store(SAMPLE_MEDIA);
+    tracer.reset();
+    await repo.deleteMedia("m1");
+    expect(tracer.findSpan("media.deleteMedia")).toBeDefined();
+    expect(tracer.findSpan("media.deleteMedia")!.attributes.deleted).toBe(true);
+    expect(tracer.findSpan("media.deleteMedia")!.attributes.id).toBe("m1");
+  });
+});
--- a/packages/media/src/infrastructure/repositories/media.repository.test.ts
+++ b/packages/media/src/infrastructure/repositories/media.repository.test.ts
@@ -0,0 +1,140 @@
+import { describe, expect, it, vi } from "vitest";
+import { RecordingTracer } from "@repo/core-testing/instrumentation";
+import { MediaRepository } from "@/infrastructure/repositories/media.repository";
+import { mediaRepositoryContract } from "@/__contracts__/media-repository.contract";
+import { stubPayloadConfig } from "@repo/core-testing/payload/stub-config";
+
+// ---------------------------------------------------------------------------
+// In-memory Payload stub
+// ---------------------------------------------------------------------------
+
+function buildPayloadStub() {
+  const store = new Map<string, Record<string, unknown>>();
+
+  return {
+    find: vi.fn(
+      async ({
+        limit,
+        page,
+      }: {
+        collection: string;
+        limit?: number;
+        page?: number;
+        overrideAccess?: boolean;
+      }) => {
+        let docs = Array.from(store.values());
+        const lim = limit ?? 50;
+        const pg = page ?? 1;
+        const offset = (pg - 1) * lim;
+        docs = docs.slice(offset, offset + lim);
+        return { docs };
+      },
+    ),
+    findByID: vi.fn(
+      async ({ id }: { collection: string; id: string; overrideAccess?: boolean }) => {
+        const doc = store.get(String(id));
+        if (!doc) {
+          const err = Object.assign(new Error(`Not found: ${id}`), { status: 404 });
+          throw err;
+        }
+        return doc;
+      },
+    ),
+    delete: vi.fn(
+      async ({ id }: { collection: string; id: string; overrideAccess?: boolean }) => {
+        store.delete(String(id));
+        return { id };
+      },
+    ),
+  };
+}
+
+vi.mock("payload", () => ({
+  getPayload: vi.fn(),
+}));
+
+// ---------------------------------------------------------------------------
+// Contract suite
+// ---------------------------------------------------------------------------
+
+describe("MediaRepository", () => {
+  describe("contract", () => {
+    const tracer = new RecordingTracer();
+    mediaRepositoryContract.run(
+      async () => {
+        const stub = buildPayloadStub();
+        const { getPayload } = await import("payload");
+        (getPayload as ReturnType<typeof vi.fn>).mockResolvedValue(stub);
+        return new MediaRepository(stubPayloadConfig, tracer);
+      },
+      { tracer: () => tracer },
+    );
+  });
+
+  // -------------------------------------------------------------------------
+  // Impl-specific tests: Payload doc → domain mapping
+  // -------------------------------------------------------------------------
+
+  describe("getMedia", () => {
+    it("returns undefined when Payload throws (not found)", async () => {
+      const { getPayload } = await import("payload");
+      (getPayload as ReturnType<typeof vi.fn>).mockResolvedValue({
+        findByID: vi.fn().mockRejectedValue(
+          Object.assign(new Error("Not found"), { status: 404 }),
+        ),
+      });
+
+      const repo = new MediaRepository(stubPayloadConfig);
+      const result = await repo.getMedia("missing-id");
+      expect(result).toBeUndefined();
+    });
+
+    it("maps Payload doc fields to domain Media", async () => {
+      const { getPayload } = await import("payload");
+      (getPayload as ReturnType<typeof vi.fn>).mockResolvedValue({
+        findByID: vi.fn().mockResolvedValue({
+          id: "p-1",
+          alt: "Test image",
+          url: "https://cdn.example.com/test.png",
+          filename: "test.png",
+          mimeType: "image/png",
+          filesize: 2048,
+          width: 800,
+          height: 600,
+        }),
+      });
+
+      const repo = new MediaRepository(stubPayloadConfig);
+      const result = await repo.getMedia("p-1");
+      expect(result?.id).toBe("p-1");
+      expect(result?.alt).toBe("Test image");
+      expect(result?.width).toBe(800);
+      expect(result?.height).toBe(600);
+    });
+  });
+
+  describe("listMedia", () => {
+    it("returns an array of mapped Media docs", async () => {
+      const { getPayload } = await import("payload");
+      (getPayload as ReturnType<typeof vi.fn>).mockResolvedValue({
+        find: vi.fn().mockResolvedValue({
+          docs: [
+            {
+              id: "m-1",
+              alt: "First",
+              url: "https://cdn.example.com/first.png",
+              filename: "first.png",
+              mimeType: "image/png",
+              filesize: 100,
+            },
+          ],
+        }),
+      });
+
+      const repo = new MediaRepository(stubPayloadConfig);
+      const result = await repo.listMedia();
+      expect(result).toHaveLength(1);
+      expect(result[0]?.id).toBe("m-1");
+    });
+  });
+});
--- a/packages/media/src/infrastructure/repositories/media.repository.ts
+++ b/packages/media/src/infrastructure/repositories/media.repository.ts
@@ -0,0 +1,149 @@
+import "reflect-metadata";
+import { injectable } from "inversify";
+import { getPayload } from "payload";
+import type { SanitizedConfig } from "payload";
+import {
+  NoopTracer,
+  NoopLogger,
+  type ITracer,
+  type ILogger,
+} from "@repo/core-shared/instrumentation";
+
+import type { IMediaRepository } from "../../application/repositories/media.repository.interface";
+import type { Media } from "../../entities/models/media";
+
+type PayloadMediaDoc = {
+  id: string | number;
+  alt?: string | null;
+  url?: string | null;
+  filename?: string | null;
+  mimeType?: string | null;
+  filesize?: number | null;
+  width?: number | null;
+  height?: number | null;
+};
+
+function mapDoc(doc: PayloadMediaDoc): Media {
+  return {
+    id: String(doc.id),
+    alt: doc.alt ?? "",
+    url: doc.url ?? "",
+    filename: doc.filename ?? "",
+    mimeType: doc.mimeType ?? "",
+    filesize: doc.filesize ?? 0,
+    ...(doc.width != null && { width: doc.width }),
+    ...(doc.height != null && { height: doc.height }),
+  };
+}
+
+const FEATURE = "media" as const;
+const REPO = "media" as const;
+
+@injectable()
+export class MediaRepository implements IMediaRepository {
+  private config: SanitizedConfig;
+  private tracer: ITracer;
+  private logger: ILogger;
+
+  constructor(
+    config: SanitizedConfig,
+    tracer: ITracer = new NoopTracer(),
+    logger: ILogger = new NoopLogger(),
+  ) {
+    this.config = config;
+    this.tracer = tracer;
+    this.logger = logger;
+  }
+
+  async getMedia(id: string): Promise<Media | undefined> {
+    return this.tracer.startSpan(
+      { name: "media.getMedia", op: "repository", attributes: { id } },
+      async (span) => {
+        try {
+          const payload = await getPayload({ config: this.config });
+          const doc = await payload.findByID({
+            collection: "media",
+            id,
+            overrideAccess: true,
+          });
+          span.setAttribute("found", true);
+          return mapDoc(doc as PayloadMediaDoc);
+        } catch (err) {
+          if (
+            err &&
+            typeof err === "object" &&
+            "status" in err &&
+            (err as { status: unknown }).status === 404
+          ) {
+            span.setAttribute("found", false);
+            return undefined;
+          }
+          this.logger.captureException(err, {
+            tags: { feature: FEATURE, repo: REPO, method: "getMedia" },
+          });
+          span.setStatus("error", err instanceof Error ? err.message : String(err));
+          throw err;
+        }
+      },
+    );
+  }
+
+  async listMedia(opts?: { limit?: number; offset?: number }): Promise<Media[]> {
+    return this.tracer.startSpan(
+      {
+        name: "media.listMedia",
+        op: "repository",
+        attributes: {
+          limit: opts?.limit ?? null,
+          offset: opts?.offset ?? null,
+        },
+      },
+      async (span) => {
+        try {
+          const payload = await getPayload({ config: this.config });
+          const result = await payload.find({
+            collection: "media",
+            limit: opts?.limit ?? 50,
+            page: opts?.offset
+              ? Math.floor(opts.offset / (opts.limit ?? 50)) + 1
+              : 1,
+            overrideAccess: true,
+          });
+          const items = result.docs.map((d) => mapDoc(d as PayloadMediaDoc));
+          span.setAttribute("count", items.length);
+          return items;
+        } catch (err) {
+          this.logger.captureException(err, {
+            tags: { feature: FEATURE, repo: REPO, method: "listMedia" },
+          });
+          span.setStatus("error", err instanceof Error ? err.message : String(err));
+          throw err;
+        }
+      },
+    );
+  }
+
+  async deleteMedia(id: string): Promise<void> {
+    return this.tracer.startSpan(
+      { name: "media.deleteMedia", op: "repository", attributes: { id } },
+      async (span) => {
+        try {
+          const payload = await getPayload({ config: this.config });
+          await payload.delete({
+            collection: "media",
+            id,
+            overrideAccess: true,
+          });
+          span.setAttribute("deleted", true);
+        } catch (err) {
+          span.setAttribute("deleted", false);
+          this.logger.captureException(err, {
+            tags: { feature: FEATURE, repo: REPO, method: "deleteMedia" },
+          });
+          span.setStatus("error", err instanceof Error ? err.message : String(err));
+          throw err;
+        }
+      },
+    );
+  }
+}
--- a/packages/media/src/integrations/api/index.ts
+++ b/packages/media/src/integrations/api/index.ts
@@ -0,0 +1,2 @@
+export { mediaRouter } from "./router";
+export type { MediaRouter } from "./router";
--- a/packages/media/src/integrations/api/procedures.ts
+++ b/packages/media/src/integrations/api/procedures.ts
@@ -0,0 +1,12 @@
+import { t } from "@repo/core-shared/trpc/init";
+import { defineErrorMiddleware } from "@repo/core-shared/trpc/define-error-middleware";
+
+import { MediaNotFoundError } from "../../entities/errors/media";
+import { InputParseError } from "../../entities/errors/common";
+
+export const mediaProcedure = t.procedure.use(
+  defineErrorMiddleware([
+    [InputParseError, "BAD_REQUEST"],
+    [MediaNotFoundError, "NOT_FOUND"],
+  ]),
+);
--- a/packages/media/src/integrations/api/router.test.ts
+++ b/packages/media/src/integrations/api/router.test.ts
@@ -0,0 +1,140 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { TRPCError } from "@trpc/server";
+import { injectable } from "inversify";
+import { mediaContainer } from "@/di/container";
+import { MediaModule } from "@/di/module";
+import { MEDIA_SYMBOLS } from "@/di/symbols";
+import { getMediaUseCase } from "@/application/use-cases/get-media.use-case";
+import { listMediaUseCase } from "@/application/use-cases/list-media.use-case";
+import { deleteMediaUseCase } from "@/application/use-cases/delete-media.use-case";
+import { getMediaController } from "@/interface-adapters/controllers/get-media.controller";
+import { listMediaController } from "@/interface-adapters/controllers/list-media.controller";
+import { deleteMediaController } from "@/interface-adapters/controllers/delete-media.controller";
+import { mediaRouter } from "@/integrations/api/router";
+
+describe("mediaRouter", () => {
+  beforeEach(() => {
+    mediaContainer.unbindAll();
+    mediaContainer.load(MediaModule);
+  });
+
+  afterEach(() => {
+    mediaContainer.unbindAll();
+  });
+
+  it("exposes getMedia, listMedia, deleteMedia procedures", () => {
+    const names = Object.keys(mediaRouter._def.procedures);
+    expect(names).toContain("getMedia");
+    expect(names).toContain("listMedia");
+    expect(names).toContain("deleteMedia");
+  });
+
+  it("listMedia returns empty array by default", async () => {
+    const caller = mediaRouter.createCaller({});
+    const result = await caller.listMedia({});
+    expect(result).toEqual([]);
+  });
+});
+
+describe("mediaRouter error mapping", () => {
+  beforeEach(() => {
+    mediaContainer.unbindAll();
+    mediaContainer.load(MediaModule);
+  });
+
+  afterEach(() => {
+    mediaContainer.unbindAll();
+  });
+
+  it("translates MediaNotFoundError → NOT_FOUND when id is missing", async () => {
+    const caller = mediaRouter.createCaller({});
+    try {
+      await caller.getMedia({ id: "nonexistent-id" });
+      throw new Error("expected throw");
+    } catch (e) {
+      expect(e).toBeInstanceOf(TRPCError);
+      expect((e as TRPCError).code).toBe("NOT_FOUND");
+    }
+  });
+
+  it("translates zod parse failure → BAD_REQUEST on getMedia with empty id", async () => {
+    const caller = mediaRouter.createCaller({});
+    try {
+      await caller.getMedia({} as unknown as { id: string });
+      throw new Error("expected throw");
+    } catch (e) {
+      expect(e).toBeInstanceOf(TRPCError);
+      expect((e as TRPCError).code).toBe("BAD_REQUEST");
+    }
+  });
+
+  it("translates MediaNotFoundError → NOT_FOUND on deleteMedia with missing id", async () => {
+    const caller = mediaRouter.createCaller({});
+    try {
+      await caller.deleteMedia({ id: "nonexistent-id" });
+      throw new Error("expected throw");
+    } catch (e) {
+      expect(e).toBeInstanceOf(TRPCError);
+      expect((e as TRPCError).code).toBe("NOT_FOUND");
+    }
+  });
+
+  it("translates MediaNotFoundError → NOT_FOUND via NullMediaRepository", async () => {
+    @injectable()
+    class NullMediaRepository {
+      async getMedia() {
+        return undefined as never;
+      }
+      async listMedia() {
+        return [] as never;
+      }
+      async deleteMedia() {
+        return;
+      }
+    }
+
+    mediaContainer.unbindAll();
+    mediaContainer.bind(MEDIA_SYMBOLS.IMediaRepository).to(NullMediaRepository);
+    mediaContainer
+      .bind(MEDIA_SYMBOLS.IGetMediaUseCase)
+      .toDynamicValue((ctx) =>
+        getMediaUseCase(ctx.container.get(MEDIA_SYMBOLS.IMediaRepository)),
+      );
+    mediaContainer
+      .bind(MEDIA_SYMBOLS.IListMediaUseCase)
+      .toDynamicValue((ctx) =>
+        listMediaUseCase(ctx.container.get(MEDIA_SYMBOLS.IMediaRepository)),
+      );
+    mediaContainer
+      .bind(MEDIA_SYMBOLS.IDeleteMediaUseCase)
+      .toDynamicValue((ctx) =>
+        deleteMediaUseCase(ctx.container.get(MEDIA_SYMBOLS.IMediaRepository)),
+      );
+    mediaContainer
+      .bind(MEDIA_SYMBOLS.IGetMediaController)
+      .toDynamicValue((ctx) =>
+        getMediaController(ctx.container.get(MEDIA_SYMBOLS.IGetMediaUseCase)),
+      );
+    mediaContainer
+      .bind(MEDIA_SYMBOLS.IListMediaController)
+      .toDynamicValue((ctx) =>
+        listMediaController(ctx.container.get(MEDIA_SYMBOLS.IListMediaUseCase)),
+      );
+    mediaContainer
+      .bind(MEDIA_SYMBOLS.IDeleteMediaController)
+      .toDynamicValue((ctx) =>
+        deleteMediaController(
+          ctx.container.get(MEDIA_SYMBOLS.IDeleteMediaUseCase),
+        ),
+      );
+
+    const caller = mediaRouter.createCaller({});
+    try {
+      await caller.getMedia({ id: "any-id" });
+      throw new Error("expected throw");
+    } catch (e) {
+      expect(e).toBeInstanceOf(TRPCError);
+      expect((e as TRPCError).code).toBe("NOT_FOUND");
+    }
+  });
+});
--- a/packages/media/src/integrations/api/router.ts
+++ b/packages/media/src/integrations/api/router.ts
@@ -0,0 +1,31 @@
+import { router } from "@repo/core-shared/trpc/init";
+
+import { mediaContainer } from "../../di/container";
+import { MEDIA_SYMBOLS } from "../../di/symbols";
+
+import { getMediaInputSchema } from "../../application/use-cases/get-media.use-case";
+import { listMediaInputSchema } from "../../application/use-cases/list-media.use-case";
+import { deleteMediaInputSchema } from "../../application/use-cases/delete-media.use-case";
+
+import type { IGetMediaController } from "../../interface-adapters/controllers/get-media.controller";
+import type { IListMediaController } from "../../interface-adapters/controllers/list-media.controller";
+import type { IDeleteMediaController } from "../../interface-adapters/controllers/delete-media.controller";
+
+import { mediaProcedure } from "./procedures";
+
+export const mediaRouter = router({
+  getMedia: mediaProcedure.input(getMediaInputSchema).query(({ input }) => {
+    const ctrl = mediaContainer.get<IGetMediaController>(MEDIA_SYMBOLS.IGetMediaController);
+    return ctrl(input);
+  }),
+  listMedia: mediaProcedure.input(listMediaInputSchema).query(({ input }) => {
+    const ctrl = mediaContainer.get<IListMediaController>(MEDIA_SYMBOLS.IListMediaController);
+    return ctrl(input);
+  }),
+  deleteMedia: mediaProcedure.input(deleteMediaInputSchema).mutation(({ input }) => {
+    const ctrl = mediaContainer.get<IDeleteMediaController>(MEDIA_SYMBOLS.IDeleteMediaController);
+    return ctrl(input);
+  }),
+});
+
+export type MediaRouter = typeof mediaRouter;
--- a/packages/media/src/integrations/cms/collections/media.ts
+++ b/packages/media/src/integrations/cms/collections/media.ts
@@ -0,0 +1,28 @@
+import type { CollectionConfig } from "payload";
+
+export const media: CollectionConfig = {
+  slug: "media",
+  custom: {
+    retention: {
+      purgeSchedule: "monthly",
+      postDeletion: {
+        duration: "P90D",
+        trigger: "after-deletion",
+        action: "hard-delete",
+      },
+    },
+  },
+  upload: {
+    mimeTypes: ["image/*", "application/pdf"],
+  },
+  admin: {
+    useAsTitle: "filename",
+  },
+  fields: [
+    {
+      name: "alt",
+      type: "text",
+      required: true,
+    },
+  ],
+};
--- a/packages/media/src/integrations/cms/index.ts
+++ b/packages/media/src/integrations/cms/index.ts
@@ -0,0 +1,2 @@
+export { media } from "./collections/media";
+// <gen:job-tasks>
--- a/packages/media/src/interface-adapters/controllers/delete-media.controller.test.ts
+++ b/packages/media/src/interface-adapters/controllers/delete-media.controller.test.ts
@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest";
+import { deleteMediaController } from "@/interface-adapters/controllers/delete-media.controller";
+import { deleteMediaUseCase } from "@/application/use-cases/delete-media.use-case";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import { MediaNotFoundError } from "@/entities/errors/media";
+import { InputParseError } from "@/entities/errors/common";
+import { mediaFactory } from "@/__factories__/media.factory";
+
+describe("deleteMediaController", () => {
+  it("deletes media successfully", async () => {
+    const repo = new MockMediaRepository();
+    const seed = mediaFactory.build({ id: "m-1" });
+    await repo._store(seed);
+
+    const useCase = deleteMediaUseCase(repo);
+    const controller = deleteMediaController(useCase);
+
+    await expect(controller({ id: "m-1" })).resolves.toBeUndefined();
+    const result = await repo.getMedia("m-1");
+    expect(result).toBeUndefined();
+  });
+
+  it("throws InputParseError when id is missing", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = deleteMediaUseCase(repo);
+    const controller = deleteMediaController(useCase);
+
+    await expect(controller({})).rejects.toThrow(InputParseError);
+  });
+
+  it("throws MediaNotFoundError when media does not exist", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = deleteMediaUseCase(repo);
+    const controller = deleteMediaController(useCase);
+
+    await expect(controller({ id: "missing" })).rejects.toThrow(MediaNotFoundError);
+  });
+});
--- a/packages/media/src/interface-adapters/controllers/delete-media.controller.ts
+++ b/packages/media/src/interface-adapters/controllers/delete-media.controller.ts
@@ -0,0 +1,17 @@
+import { InputParseError } from "../../entities/errors/common";
+import {
+  deleteMediaInputSchema,
+  type IDeleteMediaUseCase,
+} from "../../application/use-cases/delete-media.use-case";
+
+export type IDeleteMediaController = ReturnType<typeof deleteMediaController>;
+
+export const deleteMediaController =
+  (deleteMediaUseCase: IDeleteMediaUseCase) =>
+  async (input: unknown): Promise<void> => {
+    const parsed = deleteMediaInputSchema.safeParse(input);
+    if (!parsed.success) {
+      throw new InputParseError("Invalid delete-media input", { cause: parsed.error });
+    }
+    await deleteMediaUseCase(parsed.data);
+  };
--- a/packages/media/src/interface-adapters/controllers/get-media.controller.test.ts
+++ b/packages/media/src/interface-adapters/controllers/get-media.controller.test.ts
@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { getMediaController } from "@/interface-adapters/controllers/get-media.controller";
+import { getMediaUseCase } from "@/application/use-cases/get-media.use-case";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import { MediaNotFoundError } from "@/entities/errors/media";
+import { InputParseError } from "@/entities/errors/common";
+import { mediaFactory } from "@/__factories__/media.factory";
+
+describe("getMediaController", () => {
+  it("returns media on valid input", async () => {
+    const repo = new MockMediaRepository();
+    const seed = mediaFactory.build({ id: "m-1" });
+    await repo._store(seed);
+
+    const useCase = getMediaUseCase(repo);
+    const controller = getMediaController(useCase);
+
+    const result = await controller({ id: "m-1" });
+    expect(result.id).toBe("m-1");
+  });
+
+  it("throws InputParseError when id is missing", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = getMediaUseCase(repo);
+    const controller = getMediaController(useCase);
+
+    await expect(controller({})).rejects.toThrow(InputParseError);
+  });
+
+  it("throws InputParseError when id is empty string", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = getMediaUseCase(repo);
+    const controller = getMediaController(useCase);
+
+    await expect(controller({ id: "" })).rejects.toThrow(InputParseError);
+  });
+
+  it("throws MediaNotFoundError when media does not exist", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = getMediaUseCase(repo);
+    const controller = getMediaController(useCase);
+
+    await expect(controller({ id: "missing" })).rejects.toThrow(MediaNotFoundError);
+  });
+});
--- a/packages/media/src/interface-adapters/controllers/get-media.controller.ts
+++ b/packages/media/src/interface-adapters/controllers/get-media.controller.ts
@@ -0,0 +1,23 @@
+import { InputParseError } from "../../entities/errors/common";
+import {
+  getMediaInputSchema,
+  type GetMediaOutput,
+  type IGetMediaUseCase,
+} from "../../application/use-cases/get-media.use-case";
+
+function presenter(value: GetMediaOutput) {
+  return value;
+}
+
+export type IGetMediaController = ReturnType<typeof getMediaController>;
+
+export const getMediaController =
+  (getMediaUseCase: IGetMediaUseCase) =>
+  async (input: unknown): Promise<ReturnType<typeof presenter>> => {
+    const parsed = getMediaInputSchema.safeParse(input);
+    if (!parsed.success) {
+      throw new InputParseError("Invalid get-media input", { cause: parsed.error });
+    }
+    const result = await getMediaUseCase(parsed.data);
+    return presenter(result);
+  };
--- a/packages/media/src/interface-adapters/controllers/list-media.controller.test.ts
+++ b/packages/media/src/interface-adapters/controllers/list-media.controller.test.ts
@@ -0,0 +1,60 @@
+import { describe, it, expect } from "vitest";
+import { listMediaController } from "@/interface-adapters/controllers/list-media.controller";
+import { listMediaUseCase } from "@/application/use-cases/list-media.use-case";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import { InputParseError } from "@/entities/errors/common";
+import { mediaFactory } from "@/__factories__/media.factory";
+
+describe("listMediaController", () => {
+  it("returns empty array when no media exists", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = listMediaUseCase(repo);
+    const controller = listMediaController(useCase);
+
+    const result = await controller({});
+    expect(result).toHaveLength(0);
+  });
+
+  it("returns all media", async () => {
+    const repo = new MockMediaRepository();
+    await repo._store(mediaFactory.build());
+    await repo._store(mediaFactory.build());
+
+    const useCase = listMediaUseCase(repo);
+    const controller = listMediaController(useCase);
+
+    const result = await controller({});
+    expect(result).toHaveLength(2);
+  });
+
+  it("passes limit and offset to use case", async () => {
+    const repo = new MockMediaRepository();
+    for (let i = 0; i < 5; i++) {
+      await repo._store(mediaFactory.build());
+    }
+
+    const useCase = listMediaUseCase(repo);
+    const controller = listMediaController(useCase);
+
+    const result = await controller({ limit: 2, offset: 1 });
+    expect(result).toHaveLength(2);
+  });
+
+  it("throws InputParseError on unknown fields (strict schema)", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = listMediaUseCase(repo);
+    const controller = listMediaController(useCase);
+
+    await expect(controller({ unknownField: 1 })).rejects.toThrow(
+      InputParseError,
+    );
+  });
+
+  it("throws InputParseError when limit is not a positive integer", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = listMediaUseCase(repo);
+    const controller = listMediaController(useCase);
+
+    await expect(controller({ limit: -1 })).rejects.toThrow(InputParseError);
+  });
+});
--- a/packages/media/src/interface-adapters/controllers/list-media.controller.ts
+++ b/packages/media/src/interface-adapters/controllers/list-media.controller.ts
@@ -0,0 +1,23 @@
+import { InputParseError } from "../../entities/errors/common";
+import {
+  listMediaInputSchema,
+  type ListMediaOutput,
+  type IListMediaUseCase,
+} from "../../application/use-cases/list-media.use-case";
+
+function presenter(value: ListMediaOutput) {
+  return value;
+}
+
+export type IListMediaController = ReturnType<typeof listMediaController>;
+
+export const listMediaController =
+  (listMediaUseCase: IListMediaUseCase) =>
+  async (input: unknown): Promise<ReturnType<typeof presenter>> => {
+    const parsed = listMediaInputSchema.safeParse(input);
+    if (!parsed.success) {
+      throw new InputParseError("Invalid list-media input", { cause: parsed.error });
+    }
+    const result = await listMediaUseCase(parsed.data);
+    return presenter(result);
+  };
--- a/packages/media/src/ui/index.ts
+++ b/packages/media/src/ui/index.ts
@@ -0,0 +1,4 @@
+// Media has no React Query option builders today. This file is the
+// public UI surface for future components and queries — extend rather
+// than re-add to root index.ts.
+export {};
--- a/packages/media/tests/media.feature.test.ts
+++ b/packages/media/tests/media.feature.test.ts
@@ -0,0 +1,83 @@
+// Feature-level test: exercises the full slice
+//   use case factory chain → mock repo
+// Tests the full dependency chain via direct injection (no container rebinding).
+
+import { describe, expect, it } from "vitest";
+import { MockMediaRepository } from "../src/infrastructure/repositories/media.repository.mock";
+import { getMediaUseCase } from "../src/application/use-cases/get-media.use-case";
+import { listMediaUseCase } from "../src/application/use-cases/list-media.use-case";
+import { deleteMediaUseCase } from "../src/application/use-cases/delete-media.use-case";
+import { getMediaController } from "../src/interface-adapters/controllers/get-media.controller";
+import { listMediaController } from "../src/interface-adapters/controllers/list-media.controller";
+import { deleteMediaController } from "../src/interface-adapters/controllers/delete-media.controller";
+import { MediaNotFoundError } from "../src/entities/errors/media";
+import { mediaFactory } from "../src/__factories__/media.factory";
+
+describe("media feature: end-to-end via direct injection", () => {
+  function buildChain() {
+    const repo = new MockMediaRepository();
+    const getUC = getMediaUseCase(repo);
+    const listUC = listMediaUseCase(repo);
+    const deleteUC = deleteMediaUseCase(repo);
+    const getCtrl = getMediaController(getUC);
+    const listCtrl = listMediaController(listUC);
+    const deleteCtrl = deleteMediaController(deleteUC);
+    return { repo, getCtrl, listCtrl, deleteCtrl };
+  }
+
+  it("listMedia returns empty array initially", async () => {
+    const { listCtrl } = buildChain();
+    const result = await listCtrl({});
+    expect(result).toHaveLength(0);
+  });
+
+  it("stores media and retrieves it by id", async () => {
+    const { repo, getCtrl } = buildChain();
+    const seed = mediaFactory.build({ id: "feat-1" });
+    await repo._store(seed);
+
+    const result = await getCtrl({ id: "feat-1" });
+    expect(result.id).toBe("feat-1");
+    expect(result.alt).toBe(seed.alt);
+  });
+
+  it("listMedia returns all stored media", async () => {
+    const { repo, listCtrl } = buildChain();
+    await repo._store(mediaFactory.build());
+    await repo._store(mediaFactory.build());
+    await repo._store(mediaFactory.build());
+
+    const result = await listCtrl({});
+    expect(result).toHaveLength(3);
+  });
+
+  it("deleteMedia removes media so it can no longer be retrieved", async () => {
+    const { repo, getCtrl, deleteCtrl } = buildChain();
+    const seed = mediaFactory.build({ id: "feat-del" });
+    await repo._store(seed);
+
+    await deleteCtrl({ id: "feat-del" });
+
+    await expect(getCtrl({ id: "feat-del" })).rejects.toThrow(MediaNotFoundError);
+  });
+
+  it("getMediaController throws MediaNotFoundError for missing id", async () => {
+    const { getCtrl } = buildChain();
+    await expect(getCtrl({ id: "does-not-exist" })).rejects.toBeInstanceOf(MediaNotFoundError);
+  });
+
+  it("deleteMediaController throws MediaNotFoundError for missing id", async () => {
+    const { deleteCtrl } = buildChain();
+    await expect(deleteCtrl({ id: "does-not-exist" })).rejects.toBeInstanceOf(MediaNotFoundError);
+  });
+
+  it("listMedia with limit respects pagination", async () => {
+    const { repo, listCtrl } = buildChain();
+    for (let i = 0; i < 5; i++) {
+      await repo._store(mediaFactory.build());
+    }
+
+    const result = await listCtrl({ limit: 3 });
+    expect(result).toHaveLength(3);
+  });
+});
--- a/packages/media/tsconfig.json
+++ b/packages/media/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "extends": "@repo/core-typescript/base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": ".",
+    "lib": ["ES2022", "DOM"],
+    "jsx": "preserve",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*", "tests/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
--- a/packages/media/turbo.json
+++ b/packages/media/turbo.json
@@ -0,0 +1,4 @@
+{
+  "extends": ["//"],
+  "tags": ["feature"]
+}
--- a/packages/media/vitest.config.ts
+++ b/packages/media/vitest.config.ts
@@ -0,0 +1,33 @@
+import path from "node:path";
+import { mergeConfig } from "vitest/config";
+import { nodeVitestConfig } from "@repo/core-typescript/vitest.base.node";
+import {
+  DEFAULT_COVERAGE_BANDS,
+  vitestThresholdsFromBands,
+} from "@repo/core-shared/conformance/coverage";
+
+// Coverage thresholds derived from DEFAULT_COVERAGE_BANDS via the shared
+// helper (ADR-020). The feature.manifest.ts `coverage.bands` section
+// declares these for boot-time `assertFeatureConformance`. Edit the
+// manifest when adjusting per-feature bands.
+export default mergeConfig(nodeVitestConfig, {
+  test: {
+    coverage: {
+      exclude: [
+        // DI bootstrap — wires InversifyJS at app startup; not unit-testable
+        "src/di/bind-production.ts",
+        // Pure TypeScript interface files — not executable
+        "src/application/repositories/**",
+        "src/application/services/**",
+        // Payload CMS collection config — declarative data, tested via Payload integration
+        "src/integrations/cms/**",
+        // React Query option builders — integration-tested in apps
+        "src/ui/**",
+      ],
+      thresholds: vitestThresholdsFromBands(DEFAULT_COVERAGE_BANDS),
+    },
+  },
+  resolve: {
+    alias: { "@": path.resolve(__dirname, "./src") },
+  },
+});