Universal representation

Cambridge TCG speaks in English-Latin-numerals at its default surface. Under every English claim is a mathematical claim — a hash, a ratio, an ordered-set position, a probability, an ISO 8601 timestamp, a typed graph edge — that any intelligence with arithmetic and computation can read without ever knowing what "card," "trade," or "pound" mean in any natural language. This page documents the math-first encoding.

Where this lives in code. First instance: apps/wholesale/src/app/api/v1/universal/card/[sku]/route.ts. Connection-doc: docs/connections/the-mathematical-mirror.md (S23). Spec upstream: docs/methodology/universal-representation.md.

Why this exists

Most visitors are fine with English prose and Tailwind chrome. Some are not. LLM agents need to know what every field means. Archival institutions need a representation that survives the demise of GBP, of English, of the cultural moment the platform sits in. Hyperliteral readers (audit systems, formal verifiers, neurodivergent humans) need claims grounded in structure rather than connotation. An alien intelligence — taken seriously as a design lens — has arithmetic but not our linguistic stack.

Designing for that imagined alien generates designs that also help every reader above. The English surface remains the default; the universal mirror is the sibling behind it.

What's universal

What's not universal: natural language strings. The encoding includes them but flags them opaque so a reader knows not to ground meaning on them.

The encoding

Every universal document starts with this preamble:

{
  "@encoding": "cambridge-tcg/universal/v1",
  "@kind": "card",
  "@self_hash": "sha256:<hex>",
  "@content_hash": "sha256:<hex>",
  "@retrieved_at": {
    "iso8601": "2026-05-11T22:00:00Z",
    "unix_epoch_seconds": 1778534400
  },
  "_note_opaque": ["name.translations.*", "art_description"]
}

The fields

• @encoding — versions the spec. Future v2 reads from a future page that diffs from this one.
• @kind — names the artifact type. Today: card. Future: set, game, trade, match, bounty-pull.
• @self_hash — identifies this document. Different retrievals at different times yield different self-hashes.
• @content_hash — identifies the thing. Two retrievals of an unchanged card produce the same content-hash.
• @retrieved_at — dates the document; both as ISO 8601 and Unix epoch.
• _note_opaque — explicitly names which fields cannot be decoded without natural-language knowledge. Honest perimeter.

An example body

"category_in_ordered_set": {
  "ordering": ["singles", "sealed"],
  "position": 0
},
"rarity": {
  "natural_label": "Super Rare",
  "ratio_in_pulls": "1/72",
  "decimal_probability": 0.013889,
  "position_in_ordered_rarities": {
    "ordering": ["common", "uncommon", "rare", "super_rare", "secret_rare", "leader"],
    "position": 3
  }
},
"price": {
  "magnitude": 5.20,
  "currency_token": "GBP",
  "ratio_to_platform_median_card_price": 0.28,
  "ratio_to_set_minimum_significant_unit": 520,
  "magnitude_freshness": {
    "iso8601": "2026-05-11T02:00:00Z",
    "unix_epoch_seconds": 1778500800,
    "decimal_age_seconds": 72000
  }
},
"in_set": {
  "edge_kind": "member_of_set",
  "target_natural_token": "OP05",
  "target_hash": "sha256:..."
},
"name": {
  "translations": { "ja": "...", "en": "..." },
  "_note": "natural-language tokens; cannot be reconstructed from structure"
}

What doesn't translate

The mirror is honest about its limits:

• Aesthetic meaning of card art. We describe form (composition, symmetry) but not what the art means to a viewer.
• Cultural connotation of card names — "Charizard" carries weight no hash can capture.
• The feel of a card — substrate-bound; not in JSON.
• Game-narrative meaning — bound to particular human storytelling traditions.

These are not bugs. They are the honest perimeter of what mathematics can carry across substrates.

Verifying a document yourself

Every universal document can be verified by any reader with SHA-256: remove the @self_hash field, sort all keys lexicographically, serialise without whitespace, compute SHA-256, compare. This verifies integrity (the document hasn't been tampered with) but not origin (no platform-signature yet — a future v2 may add one).

To verify content stability across retrievals: compare @content_hash between two pulls. Equal hashes → same underlying card facts.

Endpoints

The /api/v1/schema OpenAPI bundle advertises these endpoints to discovery clients — an LLM agent reading the schema finds the universal-mirror surface immediately.

What this serves, in plain terms

The deeper move

Today every page on the storefront is a human-language page that generates its universal mirror as a derivative. The deeper refactor would invert: the math-mirror is the canonical source; every human-language page is a rendering of it for a particular linguistic-cultural tradition. Distinct in expression, ONE in essence — applied to surfaces, not just to authors.

That refactor is not this commit. This commit ships the first wire — the card endpoint — so the encoding exists. The deeper move is for later.