# Generation Tier Matrix (§24.1)

This document is the canonical reference for which generation surfaces are
exposed to which audience tier, the entitlement gate, and the provenance / audit
contract that applies.

## Tier Definitions

| Tier              | Audience                          | Entitlement Tag   |
| ----------------- | --------------------------------- | ----------------- |
| `contemplative`   | Consumer of the contemplative app | (default, no tag) |
| `curated-creator` | Light creator on Oshun proper     | `curated-creator` |
| `aaa-creator`     | Professional creator on Yemaya    | `aaa-creator`     |
| `operator-admin`  | Oshun operator + admin            | `operator-admin`  |

The tier resolver lives at `libs/isis/entitlements/src/generation-tier.ts`. BFF,
Admin, and Studio middleware consult it before rendering any generation surface.

## Surface Matrix

| Surface family                       | contemplative | curated-creator | aaa-creator | operator-admin |
| ------------------------------------ | ------------- | --------------- | ----------- | -------------- |
| Curated image / scene / voice clip   | ✓             | ✓               | ✓           | ✓              |
| Curated workflow / asset picker      |               | ✓               | ✓           | ✓              |
| Graph editor (ComfyUI)               |               |                 | ✓           | ✓              |
| Civitai search + LoRA hash picker    |               |                 | ✓           | ✓              |
| LoRA trainer                         |               |                 | ✓           | ✓              |
| Model merger / comparison            |               |                 | ✓           | ✓              |
| RunPod region selector               |               |                 | ✓           | ✓              |
| GPU worker / multi-GPU orchestration |               |                 | ✓           | ✓              |
| Gaussian-splatting / auto-rigging    |               |                 | ✓           | ✓              |
| Topaz / RIFE / AnimateDiff           |               |                 | ✓           | ✓              |
| Voice cloning tool                   |               |                 | ✓           | ✓              |
| Music generation                     |               |                 | ✓           | ✓              |
| 3D generation                        |               |                 | ✓           | ✓              |
| Civitai intake review queue          |               |                 |             | ✓              |
| LoRA training queue (admin)          |               |                 |             | ✓              |
| RunPod operator dashboard            |               |                 |             | ✓              |
| Output gallery (admin)               |               |                 |             | ✓              |
| ComfyUI node registry                |               |                 |             | ✓              |
| Audit trail                          |               |                 |             | ✓              |

## Routes & Surface Mapping

Source of truth: `libs/isis/entitlements/src/generation-tier.ts` →
`TIER_ALLOWLISTS` constant + `GENERATION_SURFACES` enum.

Customer Studio routes live under `apps/oshun/web/src/app/studio/isis/*`; the
routing layer reads the resolved tier and renders the appropriate surface OR
returns 404 (with an AAA-tier upgrade CTA when the user has an upgrade path,
hard-block otherwise).

Admin routes live under `apps/oshun/admin/*` and require `operator-admin` tag;
they apply the same `checkSurfaceAccess` guard so unauthorised admin surface
reads return 404.

## Provenance & Audit Contracts

- Contemplative surfaces: anonymised generation receipts; no Civitai hashes, no
  Runpod identifiers, no LoRA weights surfaced to end users.
- Curated-creator surfaces: as above plus workflow-pick metadata (template name,
  palette, length) — still no raw provider IDs.
- AAA-creator surfaces: full provider metadata (Civitai model id + hash, Runpod
  endpoint id, ComfyUI graph hash) — required for reproducibility.
- Operator-admin surfaces: full audit trail (per-event signer id, attestation
  hash, broadcast txid for any payouts).

## Deny-by-default Guard

Any contemplative-product Studio route that resolves a non-curated surface (raw
graph editor, Civitai LoRA hash picker, RunPod region selector, model-merging,
LoRA-training, GPU-worker, multi-GPU orchestration, gaussian-splatting,
auto-rigging, topaz/RIFE/animatediff, model-comparison) returns 404 + Yemaya
signup disclosure for entitled users, hard-block for the rest.

The guard logic lives in `checkSurfaceAccess`; the BFF + Studio middleware
translate the verdict into the rendered response.

## Placeholder Route Audit

The audit catalog now fail-closes every old placeholder workspace in
`apps/oshun/web/src/app/studio/isis/`. That legacy tree is provider machinery,
not a curated customer surface. `AAA_ONLY_STUDIO_ROUTES` keeps the §24.11
representative route list for diagnostics, while enforcement uses
`isAaaOnlyRoute()` to deny any non-empty `studio/isis/<segment>` unless the
empty `STUDIO_ISIS_ALLOWED_ROUTE_SEGMENTS` list is deliberately expanded in a
reviewed change.

Per the tier matrix, raw Isis provider surfaces belong on Yemaya AAA Studio
only. Oshun Studio exposes the curated cards under `/studio/generation/*` and
the gallery at `/studio/generation-gallery`; direct visits to legacy machinery
are intercepted by middleware before the underlying placeholder page can render.
