Phase 2: Medusa Fit Validation — Implementation Plan¶

ExzenTCG/tcg-platform
├── src/
│   ├── modules/
│   │   └── tcg/
│   │       ├── index.ts                         Module() registration
│   │       ├── service.ts                       TcgModuleService (MedusaService + reservation)
│   │       ├── types/
│   │       │   └── enums.ts                     ProductType, Game, Language, Condition, SealedFormat, Grader, SerializedStatus
│   │       ├── models/
│   │       │   ├── variant-metadata.ts          TcgVariantMetadata (model.define)
│   │       │   └── serialized-item.ts           TcgSerializedItem (model.define)
│   │       ├── migrations/
│   │       │   ├── Migration<ts>_<name>.ts      auto-generated by `medusa db:generate tcg`
│   │       │   └── Migration<ts+1>_add_check.ts hand-written CHECK constraint
│   │       ├── __tests__/
│   │       │   └── service.spec.ts              moduleIntegrationTestRunner tests
│   │       └── README.md                        overwrite Phase 1 placeholder
│   ├── links/
│   │   ├── product-variant-tcg-metadata.ts      defineLink 1:1
│   │   └── product-variant-serialized-item.ts   defineLink N:1
│   └── scripts/
│       └── seed-phase-2.ts                      seed script (idempotent)
├── integration-tests/
│   └── http/
│       └── seed-phase-2.spec.ts                 medusaIntegrationTestRunner — seed idempotency + query
└── medusa-config.ts                             register module in modules array

ExzenTCG/ExzenTCG-Homelab
└── tcg-platform/
    └── phase-2-findings.md                      gap analysis output doc
└── homelab/
    └── 05_service_deployments/
        └── tcg-staging.md                       append "Phase 2 applied" entry

// src/modules/tcg/types/enums.ts

export enum ProductType {
  SINGLE = "single",
  SEALED = "sealed",
  GRADED = "graded",
}

export enum Game {
  POKEMON = "pokemon",
  YUGIOH = "yugioh",
  ONE_PIECE = "one_piece",
}

export enum Language {
  EN = "en",
  JA = "ja",
  KO = "ko",
  ZH_S = "zh-s",
  ZH_T = "zh-t",
  DE = "de",
  FR = "fr",
  ES = "es",
  IT = "it",
  PT = "pt",
}

export enum Condition {
  NM = "NM",
  LP = "LP",
  MP = "MP",
  HP = "HP",
  DMG = "DMG",
  SEALED = "SEALED",
}

export enum SealedFormat {
  BOOSTER_PACK = "booster_pack",
  BOOSTER_BOX = "booster_box",
  ETB = "etb",
  BUNDLE = "bundle",
  TIN = "tin",
  PROMO_BOX = "promo_box",
}

export enum Grader {
  PSA = "PSA",
  BGS = "BGS",
  CGC = "CGC",
  ACE = "ACE",
}

export enum SerializedStatus {
  AVAILABLE = "available",
  RESERVED = "reserved",
  SOLD = "sold",
  ON_HOLD = "on_hold",
}

git add src/modules/tcg/types/enums.ts
git commit -m "feat(tcg): add shared enum types for TCG domain

ProductType, Game, Language, Condition, SealedFormat, Grader,
SerializedStatus. Used by both models and service."

// src/modules/tcg/models/variant-metadata.ts

import { model } from "@medusajs/framework/utils"
import {
  ProductType,
  Game,
  Language,
  Condition,
  SealedFormat,
} from "../types/enums"

const TcgVariantMetadata = model.define("tcg_variant_metadata", {
  id: model.id().primaryKey(),
  product_type: model.enum(ProductType),
  game: model.enum(Game),

  // Card-like (singles + graded)
  set_code: model.text().nullable(),
  set_name: model.text().nullable(),
  card_number: model.text().nullable(),
  rarity: model.text().nullable(),
  language: model.enum(Language).nullable(),
  variation: model.text().nullable(),
  foil: model.boolean().nullable(),
  edition: model.text().nullable(),

  // Sealed-specific
  sealed_format: model.enum(SealedFormat).nullable(),
  pack_count: model.number().nullable(),

  // Condition (fungible only; graded per-slab condition on TcgSerializedItem)
  condition: model.enum(Condition).nullable(),

  // Housekeeping
  notes: model.text().nullable(),
})

export default TcgVariantMetadata

git add src/modules/tcg/models/variant-metadata.ts
git commit -m "feat(tcg): add TcgVariantMetadata data model

Per-variant metadata for fungible TCG stock. Single table covering
singles, sealed, and graded placeholder variants; nullable fields
make the shape polymorphic by product_type + game.

One row per Medusa productVariant (enforced via 1:1 Module Link
added later)."

// src/modules/tcg/models/serialized-item.ts

import { model } from "@medusajs/framework/utils"
import { Grader, SerializedStatus } from "../types/enums"

const TcgSerializedItem = model.define("tcg_serialized_item", {
  id: model.id().primaryKey(),

  // Grading
  is_graded: model.boolean().default(false),
  grader: model.enum(Grader).nullable(),
  grade: model.number().nullable(), // numeric precision handled at migration layer if needed
  cert_number: model.text().nullable(),

  // Ungraded premium raws
  condition_notes: model.text().nullable(),

  // Fulfillment state
  status: model.enum(SerializedStatus).default(SerializedStatus.AVAILABLE).index(),
  reserved_by_order_id: model.text().nullable().index(),

  // Media
  photo_urls: model.json().nullable(),

  // Sourcing (Phase 4 wires DCA; leave columns as loose types for now)
  acquired_at: model.dateTime().nullable(),
  acquired_batch_id: model.text().nullable(),
  acquisition_cost: model.number().nullable(),

  // Housekeeping
  sku: model.text().unique().nullable(),
  notes: model.text().nullable(),
})

export default TcgSerializedItem

git add src/modules/tcg/models/serialized-item.ts
git commit -m "feat(tcg): add TcgSerializedItem data model

Per-physical-item record for graded slabs and premium raws. Carries
grader/grade/cert, condition notes, reservation status + reserving
order id, photos, sourcing fields.

status + reserved_by_order_id both indexed for reservation lookups.
sku is unique (internal shop SKU for physical labeling).

Module Link to productVariant (N:1) added in a later task."

// src/modules/tcg/__tests__/service.spec.ts

import { moduleIntegrationTestRunner } from "@medusajs/test-utils"
import { TCG_MODULE } from ".."
import TcgModuleService from "../service"
import TcgVariantMetadata from "../models/variant-metadata"
import TcgSerializedItem from "../models/serialized-item"
import { SerializedStatus } from "../types/enums"

moduleIntegrationTestRunner<TcgModuleService>({
  moduleName: TCG_MODULE,
  moduleModels: [TcgVariantMetadata, TcgSerializedItem],
  resolve: "./src/modules/tcg",
  testSuite: ({ service }) => {
    describe("TcgModuleService.reserveSerializedItem", () => {
      it("transitions available → reserved and records order id", async () => {
        const [item] = await service.createTcgSerializedItems([
          { sku: "TEST-SLAB-001", is_graded: false },
        ])

        const result = await service.reserveSerializedItem(item.id, "order_abc")

        expect(result.status).toBe(SerializedStatus.RESERVED)
        expect(result.reserved_by_order_id).toBe("order_abc")
      })

      it("rejects reservation if item is already reserved", async () => {
        const [item] = await service.createTcgSerializedItems([
          { sku: "TEST-SLAB-002", is_graded: false },
        ])
        await service.reserveSerializedItem(item.id, "order_1")

        await expect(
          service.reserveSerializedItem(item.id, "order_2")
        ).rejects.toThrow(/not available/i)
      })

      it("rejects reservation if item is sold", async () => {
        const [item] = await service.createTcgSerializedItems([
          { sku: "TEST-SLAB-003", status: SerializedStatus.SOLD, is_graded: false },
        ])

        await expect(
          service.reserveSerializedItem(item.id, "order_1")
        ).rejects.toThrow(/not available/i)
      })
    })
  },
})

jest.setTimeout(60 * 1000)

// src/modules/tcg/service.ts

import { MedusaService } from "@medusajs/framework/utils"
import TcgVariantMetadata from "./models/variant-metadata"
import TcgSerializedItem from "./models/serialized-item"

class TcgModuleService extends MedusaService({
  TcgVariantMetadata,
  TcgSerializedItem,
}) {
  async reserveSerializedItem(
    _itemId: string,
    _orderId: string
  ): Promise<any> {
    throw new Error("not implemented")
  }
}

export default TcgModuleService

import { MedusaError } from "@medusajs/framework/utils"
import { SerializedStatus } from "./types/enums"

// inside the class:
async reserveSerializedItem(itemId: string, orderId: string) {
  // Re-read with a lock — Mikro-ORM exposes `transactional` via the inherited
  // service. We do the check-and-update inside a single transaction so two
  // concurrent callers can't both see AVAILABLE.
  return this.withTransaction(async (tx) => {
    const [item] = await this.listTcgSerializedItems(
      { id: itemId },
      { take: 1 }
    )

    if (!item) {
      throw new MedusaError(
        MedusaError.Types.NOT_FOUND,
        `TcgSerializedItem ${itemId} not found`
      )
    }

    if (item.status !== SerializedStatus.AVAILABLE) {
      throw new MedusaError(
        MedusaError.Types.NOT_ALLOWED,
        `TcgSerializedItem ${itemId} is not available (current status: ${item.status})`
      )
    }

    const [updated] = await this.updateTcgSerializedItems([
      {
        id: itemId,
        status: SerializedStatus.RESERVED,
        reserved_by_order_id: orderId,
      },
    ])

    return updated
  })
}

// src/modules/tcg/service.ts

import { MedusaError, MedusaService } from "@medusajs/framework/utils"
import TcgVariantMetadata from "./models/variant-metadata"
import TcgSerializedItem from "./models/serialized-item"
import { SerializedStatus } from "./types/enums"

class TcgModuleService extends MedusaService({
  TcgVariantMetadata,
  TcgSerializedItem,
}) {
  async reserveSerializedItem(itemId: string, orderId: string) {
    return this.withTransaction(async () => {
      const [item] = await this.listTcgSerializedItems(
        { id: itemId },
        { take: 1 }
      )

      if (!item) {
        throw new MedusaError(
          MedusaError.Types.NOT_FOUND,
          `TcgSerializedItem ${itemId} not found`
        )
      }

      if (item.status !== SerializedStatus.AVAILABLE) {
        throw new MedusaError(
          MedusaError.Types.NOT_ALLOWED,
          `TcgSerializedItem ${itemId} is not available (current status: ${item.status})`
        )
      }

      const [updated] = await this.updateTcgSerializedItems([
        {
          id: itemId,
          status: SerializedStatus.RESERVED,
          reserved_by_order_id: orderId,
        },
      ])

      return updated
    })
  }
}

export default TcgModuleService

git add src/modules/tcg/service.ts src/modules/tcg/__tests__/service.spec.ts
git commit -m "feat(tcg): TcgModuleService with reserveSerializedItem

MedusaService extension exposes auto-generated CRUD for both models.
Custom reserveSerializedItem method transitions available → reserved
inside a transaction, rejects reservation if the item is not
available (already reserved, sold, or on hold).

Tests cover the happy path, double-reservation rejection, and
reservation-of-sold rejection. Uses moduleIntegrationTestRunner with
the module's real Postgres models."

// src/modules/tcg/index.ts

import { Module } from "@medusajs/framework/utils"
import TcgModuleService from "./service"

export const TCG_MODULE = "tcgModuleService"

export default Module(TCG_MODULE, {
  service: TcgModuleService,
})

// medusa-config.ts — add to the modules array, after the existing Redis modules:

{
  resolve: "./src/modules/tcg",
},

  modules: [
    { resolve: "@medusajs/medusa/event-bus-redis", options: { redisUrl: process.env.REDIS_URL } },
    { resolve: "@medusajs/medusa/workflow-engine-redis", options: { redis: { redisUrl: process.env.REDIS_URL } } },
    { resolve: "@medusajs/medusa/caching", options: { providers: [{ resolve: "@medusajs/caching-redis", id: "caching-redis", is_default: true, options: { redisUrl: process.env.REDIS_URL } }] } },
    { resolve: "@medusajs/medusa/locking", options: { providers: [{ resolve: "@medusajs/medusa/locking-redis", id: "locking-redis", is_default: true, options: { redisUrl: process.env.REDIS_URL } }] } },
    { resolve: "./src/modules/tcg" },
  ],

git add src/modules/tcg/index.ts medusa-config.ts
git commit -m "feat(tcg): register TCG module in Medusa config

Module() wraps TcgModuleService with the TCG_MODULE name. Added to
the medusa-config.ts modules array after the Redis infra modules.
Module is now resolvable via container.resolve(TCG_MODULE)."

ls src/modules/tcg/migrations/
cat src/modules/tcg/migrations/Migration*.ts | head -80

// src/modules/tcg/migrations/Migration20260423130000_add_serialized_item_check.ts

import { Migration } from "@mikro-orm/migrations"

export class Migration20260423130000 extends Migration {
  async up(): Promise<void> {
    this.addSql(`
      ALTER TABLE tcg_serialized_item
      ADD CONSTRAINT tcg_serialized_item_reserved_order_check
      CHECK (
        status != 'reserved' OR reserved_by_order_id IS NOT NULL
      );
    `)
  }

  async down(): Promise<void> {
    this.addSql(`
      ALTER TABLE tcg_serialized_item
      DROP CONSTRAINT IF EXISTS tcg_serialized_item_reserved_order_check;
    `)
  }
}

psql -c "SELECT conname FROM pg_constraint WHERE conname = 'tcg_serialized_item_reserved_order_check';"
# Expected: returns one row

git add src/modules/tcg/migrations/
git commit -m "feat(tcg): migrations for TCG tables + reservation CHECK

Generated migration (Migration<ts>_<hash>) creates tcg_variant_metadata
and tcg_serialized_item tables plus their indexes.

Hand-written follow-up (Migration<ts+1>_add_serialized_item_check) adds
a CHECK constraint enforcing the invariant:
  status = 'reserved' ⇒ reserved_by_order_id IS NOT NULL

Kept as a separate migration so the generated one stays regenerable."

// src/links/product-variant-tcg-metadata.ts

import TcgModule from "../modules/tcg"
import ProductModule from "@medusajs/medusa/product"
import { defineLink } from "@medusajs/framework/utils"

export default defineLink(
  ProductModule.linkable.productVariant,
  {
    linkable: TcgModule.linkable.tcgVariantMetadata,
    deleteCascade: true,
  }
)

git add src/links/product-variant-tcg-metadata.ts
git commit -m "feat(tcg): link TcgVariantMetadata to productVariant (1:1)

defineLink with deleteCascade on the TCG side so metadata is cleaned
up when its variant is deleted. Queryable via
fields: ['*', 'tcg_variant_metadata.*'] on variant queries."

// src/links/product-variant-serialized-item.ts

import TcgModule from "../modules/tcg"
import ProductModule from "@medusajs/medusa/product"
import { defineLink } from "@medusajs/framework/utils"

export default defineLink(
  ProductModule.linkable.productVariant,
  {
    linkable: TcgModule.linkable.tcgSerializedItem,
    isList: true,
    deleteCascade: true,
  }
)

git add src/links/product-variant-serialized-item.ts
git commit -m "feat(tcg): link TcgSerializedItem to productVariant (N:1)

isList on the TCG side so many serialized items can share a base
variant printing. deleteCascade removes orphan slabs if a variant is
ever deleted. Queryable via
fields: ['*', 'tcg_serialized_items.*'] on variant queries."

# `tcg/` module

TCG-specific product semantics. Shipped in Phase 2.

## Data models

- **`TcgVariantMetadata`** — per-variant metadata for fungible TCG stock. Covers singles, sealed products, and graded placeholder variants via a nullable field set discriminated by `product_type` (`single` / `sealed` / `graded`). 1:1 link to Medusa `productVariant`.
- **`TcgSerializedItem`** — per-physical-item row for graded slabs and premium raws. Carries its own photos, grade, cert, reservation state. N:1 link to `productVariant` (many slabs can share a base printing).

## Links

- `src/links/product-variant-tcg-metadata.ts` — 1:1
- `src/links/product-variant-serialized-item.ts` — N:1

Query with:

    const { data } = await query.graph({
      entity: "product_variant",
      fields: ["*", "tcg_variant_metadata.*", "tcg_serialized_items.*"],
    })

## Service

`TcgModuleService` extends `MedusaService` for auto-generated CRUD on both models, plus:

- `reserveSerializedItem(itemId, orderId)` — atomically transitions a serialized item from `available` → `reserved`. Throws `MedusaError` if the item is not available.

## Out of scope (Phase 2)

- REST endpoints (Phase 5)
- Admin UI (Phase 5)
- Channel listings per platform (Phase 3 — `TCGChannelListing`)
- Per-game attribute extensions (HP, mana cost, etc. — evaluate Phase 5)
- Bulk stock adjustment UX (Phase 5)
- Reservation race stress tests (Phase 5)

See [the Phase 2 kickoff plan](https://docs.exzentcg.com/tcg-platform/phase-2-plan/) for full context.

git add src/modules/tcg/README.md
git commit -m "docs(tcg): replace placeholder README with module overview"

git push -u origin draft/claude-phase-2-module-scaffold
gh pr create --title "feat(tcg): Phase 2 module scaffold + Module Links" --body-file - <<'EOF'
## Summary
Phase 2 data layer: TCG module with two DML models, their migrations (+ a CHECK constraint), two Module Links to `productVariant`, and tests covering the reservation state machine.

See [`tcg-platform/phase-2-plan.md`](https://docs.exzentcg.com/tcg-platform/phase-2-plan/) for scope + design.

## Changes
- `src/modules/tcg/` — module, service, models, enums, migrations, tests.
- `src/links/` — two `defineLink()` definitions.
- `medusa-config.ts` — register module in `modules` array.
- README replaces Phase 1 placeholder.

## Test plan
- [ ] CI green.
- [ ] `yarn test:integration:modules --testPathPattern=tcg` passes locally.
- [ ] `yarn medusa db:migrate` applies cleanly on staging via entrypoint (Task 13).
- [ ] CHECK constraint exists on staging (verify with `pg_constraint`).

## Follow-up
- PR B: seed script (`src/scripts/seed-phase-2.ts`)
- PR C: findings doc + runbook update (homelab repo)
EOF

// src/scripts/seed-phase-2.ts

import { ExecArgs } from "@medusajs/framework/types"
import {
  ContainerRegistrationKeys,
  Modules,
} from "@medusajs/framework/utils"
import {
  createStockLocationsWorkflow,
  linkSalesChannelsToStockLocationWorkflow,
} from "@medusajs/medusa/core-flows"
import { TCG_MODULE } from "../modules/tcg"
import TcgModuleService from "../modules/tcg/service"

const STOCK_LOCATIONS = [
  { name: "Warehouse", address_1: "—", country_code: "sg" },
  { name: "Store", address_1: "—", country_code: "sg" },
  { name: "Event-A", address_1: "—", country_code: "sg" },
]

export default async function seedPhase2({ container }: ExecArgs) {
  const logger = container.resolve(ContainerRegistrationKeys.LOGGER)
  const query = container.resolve(ContainerRegistrationKeys.QUERY)
  const salesChannelService = container.resolve(Modules.SALES_CHANNEL)
  const stockLocationService = container.resolve(Modules.STOCK_LOCATION)
  const tcgService: TcgModuleService = container.resolve(TCG_MODULE)

  logger.info("[phase-2-seed] starting")

  // 1. Default sales channel (idempotent — Medusa creates one on first boot)
  const [defaultChannel] = await salesChannelService.listSalesChannels({
    name: "Default Sales Channel",
  })
  if (!defaultChannel) {
    throw new Error("Default Sales Channel not found — did Phase 1 bootstrap run?")
  }

  // 2. Stock locations (upsert by name)
  const existingLocations = await stockLocationService.listStockLocations({
    name: STOCK_LOCATIONS.map((l) => l.name),
  })
  const existingNames = new Set(existingLocations.map((l) => l.name))
  const toCreate = STOCK_LOCATIONS.filter((l) => !existingNames.has(l.name))

  if (toCreate.length > 0) {
    const { result: created } = await createStockLocationsWorkflow(container).run({
      input: { locations: toCreate },
    })
    logger.info(`[phase-2-seed] created ${created.length} stock locations`)

    // Associate each new location with the default sales channel
    for (const loc of created) {
      await linkSalesChannelsToStockLocationWorkflow(container).run({
        input: {
          id: loc.id,
          add: [defaultChannel.id],
        },
      })
    }
  } else {
    logger.info("[phase-2-seed] stock locations already exist, skipping")
  }

  // 3. Products + variants + TCG metadata (next tasks populate this)
  logger.info("[phase-2-seed] products: (empty scaffold — populated by later tasks)")

  logger.info("[phase-2-seed] done")
}

[phase-2-seed] starting
[phase-2-seed] created 3 stock locations   (or "already exist, skipping" on rerun)
[phase-2-seed] products: (empty scaffold — populated by later tasks)
[phase-2-seed] done

yarn medusa exec ./src/scripts/seed-phase-2.ts

git add src/scripts/seed-phase-2.ts
git commit -m "feat(seed): Phase 2 seed script scaffold

Idempotent entry point. Verifies default sales channel, upserts three
stock locations (Warehouse / Store / Event-A), associates them with
the default channel. Product fixtures added in later tasks.

Run via: yarn medusa exec ./src/scripts/seed-phase-2.ts"

import { createProductsWorkflow } from "@medusajs/medusa/core-flows"
import { ProductStatus } from "@medusajs/framework/utils"
import {
  ProductType,
  Game,
  Language,
  Condition,
} from "../modules/tcg/types/enums"

type SeedDeps = {
  container: ExecArgs["container"]
  logger: ReturnType<typeof (c: any) => any>
  query: any
  tcgService: TcgModuleService
  defaultChannelId: string
}

async function seedPokemonSingles(deps: SeedDeps) {
  const { container, logger, query, tcgService, defaultChannelId } = deps

  // Idempotency: look for products by our stable external key (handle).
  const fixtures = [
    {
      handle: "pokemon-charizard-ex-obsidian-flames-223",
      title: "Charizard ex · Obsidian Flames · 223/197",
      set_code: "OBF",
      set_name: "Obsidian Flames",
      card_number: "223/197",
      rarity: "Special Illustration Rare",
      variants: [
        { language: Language.EN, condition: Condition.NM, foil: false, variation: null },
        { language: Language.EN, condition: Condition.LP, foil: false, variation: null },
        { language: Language.EN, condition: Condition.NM, foil: true, variation: "Reverse Holo" },
        { language: Language.JA, condition: Condition.NM, foil: false, variation: null },
      ],
    },
    {
      handle: "pokemon-pikachu-paldean-fates-rc01",
      title: "Pikachu · Paldean Fates · RC01",
      set_code: "PAF",
      set_name: "Paldean Fates",
      card_number: "RC01",
      rarity: "Illustration Rare",
      variants: [
        { language: Language.EN, condition: Condition.NM, foil: false, variation: null },
        { language: Language.EN, condition: Condition.NM, foil: true, variation: "Full Art" },
      ],
    },
  ]

  const { data: existing } = await query.graph({
    entity: "product",
    fields: ["id", "handle"],
    filters: { handle: fixtures.map((f) => f.handle) },
  })
  const existingHandles = new Set(existing.map((p: any) => p.handle))
  const toCreate = fixtures.filter((f) => !existingHandles.has(f.handle))

  if (toCreate.length === 0) {
    logger.info("[phase-2-seed] pokemon singles already seeded, skipping")
    return
  }

  const productsInput = toCreate.map((f) => ({
    handle: f.handle,
    title: f.title,
    status: ProductStatus.PUBLISHED,
    options: [
      { title: "Language", values: Array.from(new Set(f.variants.map((v) => v.language))) },
      { title: "Condition", values: Array.from(new Set(f.variants.map((v) => v.condition))) },
      { title: "Finish", values: Array.from(new Set(f.variants.map((v) => (v.foil ? "Foil" : "Non-foil")))) },
      { title: "Variation", values: Array.from(new Set(f.variants.map((v) => v.variation ?? "Normal"))) },
    ],
    variants: f.variants.map((v) => ({
      title: `${f.title} — ${v.language} ${v.condition} ${v.foil ? "Foil" : "Non-foil"} ${v.variation ?? "Normal"}`,
      sku: `${f.handle}-${v.language}-${v.condition}-${v.foil ? "F" : "NF"}-${(v.variation ?? "N").toUpperCase().slice(0, 3)}`,
      manage_inventory: true,
      prices: [{ currency_code: "sgd", amount: 1000 }],
      options: {
        Language: v.language,
        Condition: v.condition,
        Finish: v.foil ? "Foil" : "Non-foil",
        Variation: v.variation ?? "Normal",
      },
    })),
    sales_channels: [{ id: defaultChannelId }],
  }))

  const { result: createdProducts } = await createProductsWorkflow(container).run({
    input: { products: productsInput },
  })

  logger.info(`[phase-2-seed] created ${createdProducts.length} pokemon single products`)

  // Create TcgVariantMetadata + link rows for each new variant
  for (let pi = 0; pi < createdProducts.length; pi++) {
    const createdProduct = createdProducts[pi]
    const fixture = toCreate[pi]

    for (let vi = 0; vi < createdProduct.variants.length; vi++) {
      const createdVariant = createdProduct.variants[vi]
      const vFixture = fixture.variants[vi]

      const [metadata] = await tcgService.createTcgVariantMetadatas([
        {
          product_type: ProductType.SINGLE,
          game: Game.POKEMON,
          set_code: fixture.set_code,
          set_name: fixture.set_name,
          card_number: fixture.card_number,
          rarity: fixture.rarity,
          language: vFixture.language,
          variation: vFixture.variation,
          foil: vFixture.foil,
          condition: vFixture.condition,
        },
      ])

      // Link via remoteLink service (container key: ContainerRegistrationKeys.LINK) — this is the pattern for managing Module Link
      // rows programmatically. Inject the link service at top-level:
      const link = container.resolve(ContainerRegistrationKeys.LINK)
      await link.create({
        [Modules.PRODUCT]: { product_variant_id: createdVariant.id },
        [TCG_MODULE]: { tcg_variant_metadata_id: metadata.id },
      })
    }
  }
}

  await seedPokemonSingles({
    container,
    logger,
    query,
    tcgService,
    defaultChannelId: defaultChannel.id,
  })

yarn medusa exec ./src/scripts/seed-phase-2.ts

docker compose exec postgres psql -U medusa -d medusa \
  -c "SELECT p.handle, COUNT(v.id) FROM product p JOIN product_variant v ON v.product_id = p.id WHERE p.handle LIKE 'pokemon-%' GROUP BY p.handle;"
# Expected:
#   pokemon-charizard-...  4
#   pokemon-pikachu-...    2

docker compose exec postgres psql -U medusa -d medusa \
  -c "SELECT product_type, game, condition, foil FROM tcg_variant_metadata WHERE game = 'pokemon' ORDER BY card_number;"
# Expected: 6 rows across both products

git add src/scripts/seed-phase-2.ts
git commit -m "feat(seed): Pokémon singles — condition × foil × language × variation

Two products (Charizard ex OBF 223, Pikachu PAF RC01) with a total of
6 variants exercising the condition, foil, language, and variation
axes of TcgVariantMetadata. Idempotent by product handle.

Each variant gets a TcgVariantMetadata row and a Module Link via
link."

import { SealedFormat } from "../modules/tcg/types/enums"

async function seedPokemonSealed(deps: SeedDeps) {
  const { container, logger, query, tcgService, defaultChannelId } = deps

  const fixtures = [
    {
      handle: "pokemon-surging-sparks-booster-pack-en",
      title: "Surging Sparks Booster Pack (EN)",
      set_code: "SSP",
      set_name: "Surging Sparks",
      language: Language.EN,
      sealed_format: SealedFormat.BOOSTER_PACK,
      pack_count: null,
    },
    {
      handle: "pokemon-surging-sparks-booster-box-en",
      title: "Surging Sparks Booster Box (EN)",
      set_code: "SSP",
      set_name: "Surging Sparks",
      language: Language.EN,
      sealed_format: SealedFormat.BOOSTER_BOX,
      pack_count: 36,
    },
    {
      handle: "pokemon-surging-sparks-etb-en",
      title: "Surging Sparks Elite Trainer Box (EN)",
      set_code: "SSP",
      set_name: "Surging Sparks",
      language: Language.EN,
      sealed_format: SealedFormat.ETB,
      pack_count: 9,
    },
    {
      handle: "pokemon-paldean-fates-booster-box-jp",
      title: "Paldean Fates Booster Box (JP)",
      set_code: "PAF",
      set_name: "Paldean Fates",
      language: Language.JA,
      sealed_format: SealedFormat.BOOSTER_BOX,
      pack_count: 30,
    },
  ]

  const { data: existing } = await query.graph({
    entity: "product",
    fields: ["id", "handle"],
    filters: { handle: fixtures.map((f) => f.handle) },
  })
  const existingHandles = new Set(existing.map((p: any) => p.handle))
  const toCreate = fixtures.filter((f) => !existingHandles.has(f.handle))

  if (toCreate.length === 0) {
    logger.info("[phase-2-seed] pokemon sealed already seeded, skipping")
    return
  }

  const productsInput = toCreate.map((f) => ({
    handle: f.handle,
    title: f.title,
    status: ProductStatus.PUBLISHED,
    options: [{ title: "Pack", values: ["Sealed"] }],
    variants: [
      {
        title: f.title,
        sku: `${f.handle}-sealed`,
        manage_inventory: true,
        prices: [{ currency_code: "sgd", amount: 2000 }],
        options: { Pack: "Sealed" },
      },
    ],
    sales_channels: [{ id: defaultChannelId }],
  }))

  const { result: createdProducts } = await createProductsWorkflow(container).run({
    input: { products: productsInput },
  })
  logger.info(`[phase-2-seed] created ${createdProducts.length} pokemon sealed products`)

  const link = container.resolve(ContainerRegistrationKeys.LINK)
  for (let i = 0; i < createdProducts.length; i++) {
    const variant = createdProducts[i].variants[0]
    const fixture = toCreate[i]

    const [metadata] = await tcgService.createTcgVariantMetadatas([
      {
        product_type: ProductType.SEALED,
        game: Game.POKEMON,
        set_code: fixture.set_code,
        set_name: fixture.set_name,
        language: fixture.language,
        sealed_format: fixture.sealed_format,
        pack_count: fixture.pack_count,
        condition: Condition.SEALED,
      },
    ])

    await link.create({
      [Modules.PRODUCT]: { product_variant_id: variant.id },
      [TCG_MODULE]: { tcg_variant_metadata_id: metadata.id },
    })
  }
}

await seedPokemonSealed({ container, logger, query, tcgService, defaultChannelId: defaultChannel.id })

yarn medusa exec ./src/scripts/seed-phase-2.ts
docker compose exec postgres psql -U medusa -d medusa -c "SELECT product_type, sealed_format, language, pack_count FROM tcg_variant_metadata WHERE product_type = 'sealed';"
# Expected: 4 rows

git add src/scripts/seed-phase-2.ts
git commit -m "feat(seed): Pokémon sealed — pack / box / ETB + JP box (language-as-product)"

import { Grader, SerializedStatus } from "../modules/tcg/types/enums"

async function seedPokemonGraded(deps: SeedDeps) {
  const { container, logger, query, tcgService, defaultChannelId } = deps

  const productHandle = "pokemon-charizard-base-set-unlimited-graded"

  const { data: existing } = await query.graph({
    entity: "product",
    fields: ["id", "handle", "variants.id"],
    filters: { handle: [productHandle] },
  })

  let baseVariantId: string
  if (existing.length > 0) {
    logger.info("[phase-2-seed] pokemon graded base product exists, reusing")
    baseVariantId = existing[0].variants[0].id
  } else {
    const { result: createdProducts } = await createProductsWorkflow(container).run({
      input: {
        products: [{
          handle: productHandle,
          title: "Charizard · Base Set · Unlimited (Graded)",
          status: ProductStatus.PUBLISHED,
          options: [{ title: "Grade", values: ["Per slab"] }],
          variants: [{
            title: "Charizard Base Unlimited — graded placeholder",
            sku: `${productHandle}-placeholder`,
            manage_inventory: false, // real inventory lives in TcgSerializedItem
            prices: [{ currency_code: "sgd", amount: 0 }], // price per-slab, set on serialized items later
            options: { Grade: "Per slab" },
          }],
          sales_channels: [{ id: defaultChannelId }],
        }],
      },
    })

    baseVariantId = createdProducts[0].variants[0].id

    // Metadata on the placeholder variant
    const link = container.resolve(ContainerRegistrationKeys.LINK)
    const [metadata] = await tcgService.createTcgVariantMetadatas([{
      product_type: ProductType.GRADED,
      game: Game.POKEMON,
      set_code: "BS",
      set_name: "Base Set",
      card_number: "4/102",
      rarity: "Holo Rare",
      language: Language.EN,
      edition: "Unlimited",
    }])
    await link.create({
      [Modules.PRODUCT]: { product_variant_id: baseVariantId },
      [TCG_MODULE]: { tcg_variant_metadata_id: metadata.id },
    })
  }

  // Serialized slab instance — idempotent by SKU
  const slabSku = "SLAB-PSA-10-CHARIZ-BASE-001"
  const existingSlab = await tcgService.listTcgSerializedItems({ sku: slabSku })
  if (existingSlab.length > 0) {
    logger.info("[phase-2-seed] graded slab fixture already exists, skipping")
    return
  }

  const [slab] = await tcgService.createTcgSerializedItems([{
    sku: slabSku,
    is_graded: true,
    grader: Grader.PSA,
    grade: 10,
    cert_number: "TEST-12345678",
    status: SerializedStatus.AVAILABLE,
    photo_urls: [],
    notes: "Seed fixture — Phase 2 validation",
  }])

  const link = container.resolve(ContainerRegistrationKeys.LINK)
  await link.create({
    [Modules.PRODUCT]: { product_variant_id: baseVariantId },
    [TCG_MODULE]: { tcg_serialized_item_id: slab.id },
  })

  // Ungraded premium raw — same base variant, second slab row
  const rawSku = "RAW-PREMIUM-CHARIZ-BASE-001"
  const existingRaw = await tcgService.listTcgSerializedItems({ sku: rawSku })
  if (existingRaw.length === 0) {
    const [raw] = await tcgService.createTcgSerializedItems([{
      sku: rawSku,
      is_graded: false,
      condition_notes: "Pristine corners, centering 55/45, candidate for grading",
      status: SerializedStatus.AVAILABLE,
      photo_urls: [],
    }])

    await link.create({
      [Modules.PRODUCT]: { product_variant_id: baseVariantId },
      [TCG_MODULE]: { tcg_serialized_item_id: raw.id },
    })
  }

  logger.info("[phase-2-seed] graded slab + ungraded premium raw created")
}

await seedPokemonGraded({ container, logger, query, tcgService, defaultChannelId: defaultChannel.id })

yarn medusa exec ./src/scripts/seed-phase-2.ts
docker compose exec postgres psql -U medusa -d medusa -c "SELECT sku, is_graded, grader, grade, status FROM tcg_serialized_item ORDER BY sku;"
# Expected: 2 rows (SLAB-PSA-10-..., RAW-PREMIUM-...)

git add src/scripts/seed-phase-2.ts
git commit -m "feat(seed): Pokémon graded slab + ungraded premium raw

Base card printing (Charizard Base Unlimited) modeled as a Medusa
product with one placeholder variant (manage_inventory=false). Two
TcgSerializedItem rows link to that variant:
 - PSA 10 slab with grader/grade/cert
 - Ungraded premium raw with condition_notes"

async function seedYugioh(deps: SeedDeps) {
  // Blue-Eyes White Dragon LOB-001 in 1st Edition + Unlimited (edition axis)
  // Dark Magician LOB-005 in NM + MP (condition axis)
  // LOB Booster Pack (sealed)
  // (Structured exactly like seedPokemonSingles + seedPokemonSealed.)
  // ...
}

async function seedOnePiece(deps: SeedDeps) {
  // Luffy OP01-001 Normal + Alt Art (variation axis)
  // Luffy OP01-001 JP (language-as-product)
  // Zoro OP01-025 Super Rare
  // OP07 Booster Box (sealed)
  // ...
}

async function seedYugioh(deps: SeedDeps) {
  const { container, logger, query, tcgService, defaultChannelId } = deps

  const fixtures = [
    {
      handle: "yugioh-blue-eyes-lob-001",
      title: "Blue-Eyes White Dragon · LOB-001",
      set_code: "LOB",
      set_name: "Legend of Blue Eyes",
      card_number: "LOB-001",
      rarity: "Ultra Rare",
      product_type: ProductType.SINGLE,
      variants: [
        { language: Language.EN, condition: Condition.NM, edition: "1st Edition" },
        { language: Language.EN, condition: Condition.NM, edition: "Unlimited" },
      ],
    },
    {
      handle: "yugioh-dark-magician-lob-005",
      title: "Dark Magician · LOB-005",
      set_code: "LOB",
      set_name: "Legend of Blue Eyes",
      card_number: "LOB-005",
      rarity: "Ultra Rare",
      product_type: ProductType.SINGLE,
      variants: [
        { language: Language.EN, condition: Condition.NM, edition: "Unlimited" },
        { language: Language.EN, condition: Condition.MP, edition: "Unlimited" },
      ],
    },
  ]

  const { data: existing } = await query.graph({
    entity: "product",
    fields: ["id", "handle"],
    filters: { handle: fixtures.map((f) => f.handle) },
  })
  const existingHandles = new Set(existing.map((p: any) => p.handle))
  const toCreate = fixtures.filter((f) => !existingHandles.has(f.handle))

  if (toCreate.length > 0) {
    const productsInput = toCreate.map((f) => ({
      handle: f.handle,
      title: f.title,
      status: ProductStatus.PUBLISHED,
      options: [
        { title: "Condition", values: Array.from(new Set(f.variants.map((v) => v.condition))) },
        { title: "Edition", values: Array.from(new Set(f.variants.map((v) => v.edition))) },
      ],
      variants: f.variants.map((v) => ({
        title: `${f.title} — ${v.condition} ${v.edition}`,
        sku: `${f.handle}-${v.condition}-${v.edition.replace(/\s+/g, "-").toUpperCase()}`,
        manage_inventory: true,
        prices: [{ currency_code: "sgd", amount: 500 }],
        options: { Condition: v.condition, Edition: v.edition },
      })),
      sales_channels: [{ id: defaultChannelId }],
    }))

    const { result: createdProducts } = await createProductsWorkflow(container).run({
      input: { products: productsInput },
    })

    const link = container.resolve(ContainerRegistrationKeys.LINK)
    for (let pi = 0; pi < createdProducts.length; pi++) {
      const cp = createdProducts[pi]
      const f = toCreate[pi]
      for (let vi = 0; vi < cp.variants.length; vi++) {
        const variant = cp.variants[vi]
        const v = f.variants[vi]
        const [metadata] = await tcgService.createTcgVariantMetadatas([{
          product_type: ProductType.SINGLE,
          game: Game.YUGIOH,
          set_code: f.set_code,
          set_name: f.set_name,
          card_number: f.card_number,
          rarity: f.rarity,
          language: v.language,
          condition: v.condition,
          edition: v.edition,
        }])
        await link.create({
          [Modules.PRODUCT]: { product_variant_id: variant.id },
          [TCG_MODULE]: { tcg_variant_metadata_id: metadata.id },
        })
      }
    }

    logger.info(`[phase-2-seed] created ${createdProducts.length} YGO single products`)
  } else {
    logger.info("[phase-2-seed] YGO singles already seeded, skipping")
  }

  // Sealed LOB pack — follow seedPokemonSealed pattern
  const sealedHandle = "yugioh-lob-booster-pack"
  const { data: sealedExists } = await query.graph({
    entity: "product",
    fields: ["id"],
    filters: { handle: [sealedHandle] },
  })

  if (sealedExists.length === 0) {
    const { result: createdProducts } = await createProductsWorkflow(container).run({
      input: {
        products: [{
          handle: sealedHandle,
          title: "Legend of Blue Eyes Booster Pack",
          status: ProductStatus.PUBLISHED,
          options: [{ title: "Pack", values: ["Sealed"] }],
          variants: [{
            title: "Legend of Blue Eyes Booster Pack",
            sku: `${sealedHandle}-sealed`,
            manage_inventory: true,
            prices: [{ currency_code: "sgd", amount: 800 }],
            options: { Pack: "Sealed" },
          }],
          sales_channels: [{ id: defaultChannelId }],
        }],
      },
    })

    const link = container.resolve(ContainerRegistrationKeys.LINK)
    const [metadata] = await tcgService.createTcgVariantMetadatas([{
      product_type: ProductType.SEALED,
      game: Game.YUGIOH,
      set_code: "LOB",
      set_name: "Legend of Blue Eyes",
      language: Language.EN,
      sealed_format: SealedFormat.BOOSTER_PACK,
      condition: Condition.SEALED,
    }])

    await link.create({
      [Modules.PRODUCT]: { product_variant_id: createdProducts[0].variants[0].id },
      [TCG_MODULE]: { tcg_variant_metadata_id: metadata.id },
    })

    logger.info("[phase-2-seed] created YGO sealed pack")
  }
}

async function seedOnePiece(deps: SeedDeps) {
  const { container, logger, query, tcgService, defaultChannelId } = deps

  const fixtures = [
    {
      handle: "onepiece-luffy-op01-001-en",
      title: "Monkey D. Luffy · OP01-001 (EN)",
      set_code: "OP01",
      set_name: "Romance Dawn",
      card_number: "OP01-001",
      rarity: "Leader",
      language: Language.EN,
      variants: [
        { condition: Condition.NM, variation: "Normal" },
        { condition: Condition.NM, variation: "Alt Art" },
      ],
    },
    {
      handle: "onepiece-luffy-op01-001-jp",
      title: "モンキー・D・ルフィ · OP01-001 (JP)",
      set_code: "OP01",
      set_name: "Romance Dawn",
      card_number: "OP01-001",
      rarity: "Leader",
      language: Language.JA,
      variants: [
        { condition: Condition.NM, variation: "Normal" },
      ],
    },
    {
      handle: "onepiece-zoro-op01-025",
      title: "Roronoa Zoro · OP01-025",
      set_code: "OP01",
      set_name: "Romance Dawn",
      card_number: "OP01-025",
      rarity: "Super Rare",
      language: Language.EN,
      variants: [
        { condition: Condition.NM, variation: null },
      ],
    },
  ]

  const { data: existing } = await query.graph({
    entity: "product",
    fields: ["id", "handle"],
    filters: { handle: fixtures.map((f) => f.handle) },
  })
  const existingHandles = new Set(existing.map((p: any) => p.handle))
  const toCreate = fixtures.filter((f) => !existingHandles.has(f.handle))

  if (toCreate.length === 0) {
    logger.info("[phase-2-seed] One Piece singles already seeded, skipping")
  } else {
    const productsInput = toCreate.map((f) => ({
      handle: f.handle,
      title: f.title,
      status: ProductStatus.PUBLISHED,
      options: [
        { title: "Condition", values: Array.from(new Set(f.variants.map((v) => v.condition))) },
        { title: "Variation", values: Array.from(new Set(f.variants.map((v) => v.variation ?? "Normal"))) },
      ],
      variants: f.variants.map((v) => ({
        title: `${f.title} — ${v.condition} ${v.variation ?? "Normal"}`,
        sku: `${f.handle}-${v.condition}-${(v.variation ?? "N").toUpperCase().slice(0, 3)}`,
        manage_inventory: true,
        prices: [{ currency_code: "sgd", amount: 500 }],
        options: { Condition: v.condition, Variation: v.variation ?? "Normal" },
      })),
      sales_channels: [{ id: defaultChannelId }],
    }))

    const { result: createdProducts } = await createProductsWorkflow(container).run({
      input: { products: productsInput },
    })

    const link = container.resolve(ContainerRegistrationKeys.LINK)
    for (let pi = 0; pi < createdProducts.length; pi++) {
      const cp = createdProducts[pi]
      const f = toCreate[pi]
      for (let vi = 0; vi < cp.variants.length; vi++) {
        const variant = cp.variants[vi]
        const v = f.variants[vi]
        const [metadata] = await tcgService.createTcgVariantMetadatas([{
          product_type: ProductType.SINGLE,
          game: Game.ONE_PIECE,
          set_code: f.set_code,
          set_name: f.set_name,
          card_number: f.card_number,
          rarity: f.rarity,
          language: f.language,
          condition: v.condition,
          variation: v.variation,
        }])
        await link.create({
          [Modules.PRODUCT]: { product_variant_id: variant.id },
          [TCG_MODULE]: { tcg_variant_metadata_id: metadata.id },
        })
      }
    }

    logger.info(`[phase-2-seed] created ${createdProducts.length} One Piece single products`)
  }

  // OP07 Booster Box — sealed
  const sealedHandle = "onepiece-op07-booster-box"
  const { data: sealedExists } = await query.graph({
    entity: "product",
    fields: ["id"],
    filters: { handle: [sealedHandle] },
  })

  if (sealedExists.length === 0) {
    const { result: createdProducts } = await createProductsWorkflow(container).run({
      input: {
        products: [{
          handle: sealedHandle,
          title: "One Piece OP07 Booster Box",
          status: ProductStatus.PUBLISHED,
          options: [{ title: "Pack", values: ["Sealed"] }],
          variants: [{
            title: "One Piece OP07 Booster Box",
            sku: `${sealedHandle}-sealed`,
            manage_inventory: true,
            prices: [{ currency_code: "sgd", amount: 10000 }],
            options: { Pack: "Sealed" },
          }],
          sales_channels: [{ id: defaultChannelId }],
        }],
      },
    })

    const link = container.resolve(ContainerRegistrationKeys.LINK)
    const [metadata] = await tcgService.createTcgVariantMetadatas([{
      product_type: ProductType.SEALED,
      game: Game.ONE_PIECE,
      set_code: "OP07",
      set_name: "Romance Dawn",
      language: Language.EN,
      sealed_format: SealedFormat.BOOSTER_BOX,
      pack_count: 24,
      condition: Condition.SEALED,
    }])

    await link.create({
      [Modules.PRODUCT]: { product_variant_id: createdProducts[0].variants[0].id },
      [TCG_MODULE]: { tcg_variant_metadata_id: metadata.id },
    })

    logger.info("[phase-2-seed] created One Piece sealed box")
  }
}