# Phase: Experience Component Library & Versioning (11.2)

| Field | Value |
| --- | --- |
| Identifier | `experience-11.2` |
| Status | Complete |
| Owner | Platform |
| Module(s) | Components, Component Versions, Page Component Placements |
| Service(s) | `experience` (Torbat Pages) |
| Depends On | `experience-11.1` |
| ADR(s) | [ADR-016](architecture/adr/ADR-016.md) |
| Manifest | [phase-manifest.yaml](ai-framework/phase-manifest.yaml) |

## Enterprise Phase Discovery Record

| Input | Finding |
| --- | --- |
| Roadmap / manifest | Next unfinished Experience phase = `experience-11.2` Component Library & Versioning |
| Prior handover | [phase-11-1.md](phase-handover/phase-11-1.md) — versioned components only; no theme/layout |
| Boundaries | Experience owns components; no CRM/Hospitality/Marketplace/Storage ownership |
| Existing codebase | Sites/pages complete; `commands/`/`policies/`/`queries/`/`specifications/` were empty shells |
| Missing vs DoD | Immutable versions, composition shells, list filter/sort/search, policies, specs, commands/queries |

Derived capabilities (this phase only): component catalog lifecycle, immutable published versions, page↔version placement pins, permissions/events/audit/tenant isolation. **Not** themes, layouts, templates, SEO, forms.

## Objective

Deliver a production-ready versioned component library on `experience_db` with immutable published revisions and composition shells that pin versions onto pages — without theme/layout engines.

## Scope

### In Scope

- `ExperienceComponent` catalog (kinds, status, category, tags)
- `ExperienceComponentVersion` with draft → published (immutable) → retired
- `PageComponentPlacement` composition shells (slot_key, sort_order, props_override)
- Policies, specifications, commands, queries
- Pagination, filtering, sorting, searching on list APIs
- Permissions `experience.components.*`; events `experience.component*` / `experience.page_component.*`
- Alembic `0003_phase_112_components`; version `0.11.2.0`
- Seed catalog: `component_kinds` via `/capabilities`

### Out of Scope

- Theme / layout engines — Phase 11.3
- Template catalog — Phase 11.4
- Visual page builder UI / section trees
- Forms, SEO, PWA, analytics, AI content

### Models

| Entity | Soft delete | Audit | Tenant | Optimistic lock |
| --- | --- | --- | --- | --- |
| ExperienceComponent | Yes | Yes | Yes | Yes |
| ExperienceComponentVersion | Yes | Yes | Yes | Yes |
| PageComponentPlacement | Yes | Yes | Yes | Yes |

### Permissions

`experience.components.view|create|update|delete|manage`

### Events

`experience.component.created|updated|activated|deprecated|archived`

`experience.component_version.created|updated|published|retired`

`experience.page_component.placed|updated|removed`

### APIs

| Method | Path |
| --- | --- |
| * | `/api/v1/components` (+ activate/deprecate/archive/delete) |
| * | `/api/v1/component-versions` (+ publish/retire) |
| * | `/api/v1/page-component-placements` (+ delete) |

List endpoints support `page`/`page_size`, filters, `q`, `sort_by`/`sort_dir`.

### Artifact coverage (DoD)

| Artifact | Status |
| --- | --- |
| Discovery | This record |
| Policies / Specs / Commands / Queries | Implemented |
| Soft delete / Optimistic lock / Audit / Tenant | Yes |
| Pagination / Filter / Sort / Search | Yes |
| Background jobs | N/A — no async work in phase boundary |
| Themes/layouts | Explicitly out of scope |

### Tests

- [x] Unit policies
- [x] API component/version/placement flow + immutability
- [x] Tenant isolation + optimistic lock
- [x] Architecture / permission / migration / docs

## Completion Criteria

- [x] Component library with immutable versions; tenant isolation tests green
- [x] No theme/layout engine
- [x] Docs / manifests / handover updated

## Related Documents

- [Handover](phase-handover/phase-11-2.md)
- [Phase 11.1](experience-phase-11-1.md)
- [Experience Roadmap](experience-roadmap.md)
- [ADR-016](architecture/adr/ADR-016.md)