TenantAtlas/specs/200-filament-surface-rules/data-model.md

# Data Model: UI/UX Constitution Extension: Filament Nativity & Custom Surface Rules

## Overview

Spec 200 is a docs-only governance feature. Its data model is conceptual rather than persisted: it describes the rule objects, vocabulary, and mappings that the constitution amendment must carry so reviewers can classify future UI work consistently.

No application database schema, runtime DTO, or transport contract is introduced by this feature.

## Entities

### 1. ConstitutionAmendmentTarget

Represents one existing constitution section that Spec 200 extends.

**Fields**

| Field | Type | Description |
|---|---|---|
| `section_id` | string | Existing rule ID or section anchor, for example `UI-SURF-001` or `UI-EX-001` |
| `target_file` | string | File path, always `.specify/memory/constitution.md` for this feature |
| `amendment_type` | enum | `clarification`, `extension`, or `new-clause` |
| `problem_classes` | list<string> | The drift classes this amendment addresses |
| `source_specs` | list<string> | Evidence specs feeding the amendment, limited here to Specs 196 through 199 |
| `expected_outputs` | list<string> | Vocabulary, anti-pattern, exception, or state-layer additions contributed by this target |
| `deferred_enforcement` | list<string> | What remains reserved for Spec 201 |

**Validation rules**

- `section_id` must reference an already existing constitution section.
- `amendment_type` must not imply a new parallel rulebook.
- Every target must cite at least one source spec or one direct repo problem class.

### 2. SurfaceVocabularyTerm

Represents a named concept that future specs and reviews must use consistently.

**Fields**

| Field | Type | Description |
|---|---|---|
| `name` | string | Canonical term, such as `Native Surface` or `Fake-Native Surface` |
| `definition` | text | Reviewable product definition |
| `positive_examples` | list<string> | Example surfaces or surface families that fit the term |
| `negative_examples` | list<string> | Nearby cases that must not be misclassified under the term |
| `governing_sections` | list<string> | Constitution sections that must mention or support the term |
| `source_specs` | list<string> | Adjacent specs that proved the need for the term |

**Validation rules**

- Every term must map to at least one amended constitution section.
- Terms must describe product-review concepts, not implementation jargon.
- Terms must be classifiable from real repo cases.

### 3. AntiPattern

Represents a named failure mode the constitution must forbid or flag.

**Fields**

| Field | Type | Description |
|---|---|---|
| `name` | string | Canonical anti-pattern name, such as `Filament Costume` |
| `definition` | text | What the anti-pattern looks like in practice |
| `trigger_signals` | list<string> | Observable characteristics that let reviewers identify it |
| `default_review_outcome` | enum | `reject`, `document-exception`, or `defer-to-follow-up-spec` |
| `allowed_exception_path` | string | Exception type or `none` when no escape is expected |
| `source_specs` | list<string> | Spec evidence behind the anti-pattern |

**Validation rules**

- Every anti-pattern must have at least one trigger signal.
- Every anti-pattern must either forbid the pattern directly or point to a bounded exception path.
- Anti-pattern names must remain stable enough for future guardrails in Spec 201.

### 4. ExceptionType

Represents a bounded, legitimate deviation from the default rules.

**Fields**

| Field | Type | Description |
|---|---|---|
| `name` | string | Canonical exception name |
| `allowed_when` | text | Product reason that makes the exception legitimate |
| `required_justification` | list<string> | Mandatory explanation points in the governing spec or PR |
| `boundaries` | list<string> | What the exception does not allow |
| `standardized_parts` | list<string> | What must remain consistent despite the exception |
| `governing_section` | string | Expected home in `UI-EX-001` |
| `deferred_enforcement` | list<string> | Which parts Spec 201 may later operationalize |

**Validation rules**

- Every exception type must stay inside the existing exception model.
- `allowed_when` must describe product need, not convenience.
- Every exception must state what stays standardized.

### 5. StateOwnershipRule

Represents the review contract for shell, page, or detail state.

**Fields**

| Field | Type | Description |
|---|---|---|
| `layer` | enum | `shell`, `page`, or `detail` |
| `owns_truth` | text | What this layer is authoritative for |
| `allowed_inputs` | list<string> | Inputs the layer may consume, such as route state, query seed, or local viewer state |
| `query_role` | enum | `initialization-only`, `durable`, `deeplink-only`, or `unsupported` |
| `forbidden_overlaps` | list<string> | Competing truths or cross-layer conflicts that are not allowed |
| `source_specs` | list<string> | Spec 198 and/or 199 evidence |

**Validation rules**

- Each rule must assign exactly one owner layer.
- A rule may describe inputs from other layers, but it may not assign equal authority to multiple layers.
- Query role must be explicit whenever the layer can be initialized from URL or remembered state.

### 6. CrossSpecMapping

Represents how one adjacent spec feeds the constitution amendment and where follow-up work goes.

**Fields**

| Field | Type | Description |
|---|---|---|
| `source_spec` | string | `196`, `197`, `198`, `199`, or `201` |
| `problem_class` | string | Problem family contributed by that spec |
| `constitution_targets` | list<string> | Which amendment targets consume that evidence |
| `status` | enum | `evidence-source`, `consumed-by-spec-200`, or `deferred-to-201` |
| `notes` | text | Short mapping summary |

**Validation rules**

- Specs 196 through 199 must map into at least one amendment target.
- Spec 201 must appear only as a deferred enforcement consumer, not as an implementation dependency within Spec 200.

## Relationships

- A `ConstitutionAmendmentTarget` produces zero or more `SurfaceVocabularyTerm` entries.
- A `ConstitutionAmendmentTarget` may define zero or more `AntiPattern` and `ExceptionType` entries.
- `StateOwnershipRule` entries are a specialized conceptual rule family that feed both vocabulary terms and amendment targets.
- `CrossSpecMapping` connects the adjacent evidence specs to the exact constitution targets that absorb them.

## Lifecycle

### Amendment Lifecycle

1. **Identified**: A rule gap is proven by a current repo case.
2. **Mapped**: The gap is assigned to an existing constitution section.
3. **Integrated**: The constitution text is amended with vocabulary, anti-patterns, or exceptions.
4. **Reviewable**: Representative cases from Specs 196 through 199 can be classified through the amended language.
5. **Operationalized later**: Spec 201 may add checklist, grep, lint, or test enforcement based on the integrated rule.

### Exception Lifecycle

1. **Requested**: A surface claims that native-by-default or shared-contract rules do not fit.
2. **Justified**: The spec states the product reason, boundaries, and standardized parts.
3. **Accepted or rejected**: Review uses the exception type and anti-pattern catalog.
4. **Potentially enforceable later**: Spec 201 may formalize recurring exception checks.

## Derived Outputs

The conceptual data model must support these concrete outputs in the constitution amendment:

- glossary terms for the required vocabulary
- named anti-pattern entries
- explicit exception types or exception clauses
- state ownership guidance for shell/page/detail separation
- a mapping note connecting Specs 196 through 199 to the amended rule family

## Out of Scope

- database tables
- Eloquent models
- runtime registries or service abstractions
- REST or GraphQL transport schemas
- executable state machines
- template or CI enforcement logic in this spec

## Amendment Target Inventory

| Amendment target | Amendment type | Problem classes absorbed | Source specs | Expected outputs | Deferred enforcement |
|---|---|---|---|---|---|
| `UI-FIL-001` | extension | native-by-default, fake-native drift, simple-overview nativity | 196 | `Native Surface`, `Custom Surface`, `Fake-Native Surface`, anti-pattern anchors | Spec 201 guardrails for fake-native patterns |
| `UI-HARD-001` | extension | forbidden fake-native behavior, one-primary-interaction-model, state/inspect conflict classes | 196, 198 | anti-pattern catalog, hard prohibitions, state-layer violation names | Spec 201 grep/test checks for forbidden patterns |
| `UI-EX-001` | extension | bounded legitimate custom surfaces, nativity exceptions, host variation, state special cases | 196, 197, 198 | finalized exception families and guardrails | Spec 201 checklist and exception review enforcement |
| `UI-SURF-001` | extension | shared detail family taxonomy, host terminology | 197 | `Shared Detail Micro-UI`, `Host` | Spec 201 metadata/review guardrails |
| `ACTSURF-001` | extension | one primary interaction model, host/family action ownership, shell/page separation pressure | 197, 199 | host/core action rules, `Parallel Inspect Worlds` review questions | Spec 201 action-surface enforcement |
| `HDR-001` | clarification | host-owned header discipline for embedded shared families | 197 | header-specific host boundary language | Spec 201 header review prompts |
| `Filament UI — Action Surface Contract` | extension | native simple-overview rule, shared-family contract ownership, explicit state ownership disclosure | 196, 197, 198 | Filament-facing execution rules | Spec 201 checklist/guard uptake |
| `UX-001` | extension | shell/page/detail ownership, requested/active/draft/inspect/restorable roles | 198, 199 | state vocabulary and owner-layer rules | Spec 201 review and doc enforcement |
| `UI-REVIEW-001` | extension | reviewer-facing classification, anti-pattern checks, state-owner questions | 196, 197, 198, 199 | explicit review questions and red flags | Spec 201 operationalization |

## Final Vocabulary Inventory

| Term | Governing sections | Source specs | Role in the amendment |
|---|---|---|---|
| `Native Surface` | `UI-SURF-001`, `UI-FIL-001`, `UI-HARD-001` | 196 | Default classification for standard Filament/shared-primitives work |
| `Fake-Native Surface` | `UI-HARD-001`, `UI-FIL-001`, `UI-REVIEW-001` | 196 | Forbidden violation class for Filament-looking but contract-foreign UI |
| `Custom Surface` | `UI-SURF-001`, `UI-EX-001`, `UI-FIL-001` | 196 | Legitimate non-native surface only with bounded product reason |
| `Legitimate Exception` | `UI-EX-001`, `UI-REVIEW-001` | 196 | Shared language for approved deviations |
| `Shared Detail Micro-UI` | `UI-SURF-001`, `ACTSURF-001`, `Filament UI — Action Surface Contract` | 197 | Repeated embedded family that must keep one shared contract |
| `Host` | `UI-SURF-001`, `ACTSURF-001`, `HDR-001` | 197 | Parent page/resource/workbench owning route, auth, and host-only actions |
| `Global Context State` | `UX-001`, `UI-REVIEW-001` | 199 | Shell-owned workspace/tenant truth |
| `Page State` | `UX-001`, `UI-REVIEW-001` | 198 | Page-owned filter/tab/mode/selection truth |
| `Detail State` | `UX-001`, `UI-REVIEW-001` | 197, 198 | Embedded viewer or inner inspect truth subordinate to page/shell |
| `Requested State` | `UX-001`, `UI-REVIEW-001` | 198, 199 | Input state before validation or hydration |
| `Active State` | `UX-001`, `UI-REVIEW-001` | 198, 199 | Current governing validated state |
| `Draft State` | `UX-001`, `UI-REVIEW-001` | 198 | Pending local state not yet applied |
| `Inspect State` | `UI-HARD-001`, `UX-001`, `UI-REVIEW-001` | 198 | Selected-record/detail focus truth |
| `Restorable State` | `UX-001`, `UI-REVIEW-001` | 198 | The shareable subset intentionally recreated |
| `Host Drift` | `UI-HARD-001`, `UI-REVIEW-001` | 197 | Forbidden host-side rewrite of shared-family core semantics |
| `State Layer Collapse` | `UI-HARD-001`, `UX-001`, `UI-REVIEW-001` | 198, 199 | Forbidden multi-layer ownership of the same truth |
| `Parallel Inspect Worlds` | `ACTSURF-001`, `UI-HARD-001`, `UI-REVIEW-001` | 198 | Forbidden competing inspect/view models for one concern |

## Final Anti-pattern Catalog

| Anti-pattern | Trigger signals | Default review outcome | Allowed exception path | Source specs |
|---|---|---|---|---|
| `Filament Costume` | Raw HTML/Tailwind controls mimic Filament semantics that native/shared primitives already provide | reject | `Nativity Exception` only when the semantic gap is explicit and narrow | 196 |
| `Blade Request UI` | Primary body-state contract depends on `request()`, GET forms, or manual query parsing inside an active Filament surface | reject | `Nativity Exception` only for initialization-only request input | 196 |
| `Hand-Rolled Simple Overview` | Simple report/overview with ordinary columns, filters, empty states, and navigation is rebuilt as bespoke markup | reject | `Legitimate Custom Surface Exception` only when the product need is materially richer than a table/list | 196 |
| `Hidden Exception` | Custom behavior survives through history or convenience without a named exception block | reject | none | 196 |
| `Host Drift` | One host changes core family zones, view semantics, or diagnostics contract without declaring host-scoped variation | reject | `Shared Detail Host Variation Exception` | 197 |
| `State Layer Collapse` | Shell, page, or detail state each claim the same active truth or restoration role | reject | `State-Layer Special-case Exception` only when the owner hierarchy stays explicit | 198, 199 |
| `Parallel Inspect Worlds` | Two same-concern inspect/open/select/view contracts coexist as peers | reject | none | 198 |

## Final Exception Relationships

| Exception type | Solves | Governing section | Standardized parts that must remain intact | Related anti-patterns |
|---|---|---|---|---|
| `Legitimate Custom Surface Exception` | Rich visualization, diagnostic/review work, multi-zone evidence, or shell-context-specific UI that does not fit standard CRUD/overview semantics | `UI-EX-001` | canonical nouns, scope clarity, explicit action hierarchy, explicit state ownership | `Hand-Rolled Simple Overview`, `Hidden Exception` |
| `Nativity Exception` | Filament/shared primitives cannot express the required semantics cleanly | `UI-EX-001` | native/shared surrounding controls, no local status language, no request-owned primary body state | `Filament Costume`, `Blade Request UI`, `Hidden Exception` |
| `Shared Detail Host Variation Exception` | A known shared family needs bounded host framing, assist entry, or optional-zone variation | `UI-EX-001` | family core zones, next-step contract, diagnostics contract, primary view/inspect model | `Host Drift` |
| `State-Layer Special-case Exception` | A page legitimately needs explicit requested/active/draft/inspect/restorable distinctions beyond the simple default | `UI-EX-001` | one owner per layer, explicit restorable subset, explicit query role, no silent shell/page overlap | `State Layer Collapse`, `Parallel Inspect Worlds` |

## Final State Ownership Rules

| Layer | Owns truth | Allowed inputs | Query role | Forbidden overlaps | Source specs |
|---|---|---|---|---|---|
| `shell` | workspace/tenant context, tenantless state, shell recovery state | route context, explicit switch/select/clear flows, valid restore candidates | durable only when the shell contract explicitly allows restore | page tabs/filters owning workspace truth, detail viewers owning tenant scope | 199 |
| `page` | filters, tabs, active modes, selected-record/page-level inspect state, applied analysis state | shell context, deeplink/init state, local interactions, explicit draft/apply actions | initialization-only, durable, or unsupported exactly as declared by the page contract | shell precedence logic, detail-local state redefining page truth | 198 |
| `detail` | embedded viewer state, inner section/tab choice, family-local assist or reveal state | host/page state, local viewer controls | usually unsupported or local-only unless an exception documents otherwise | shell or page ownership of the same active inspect/view truth | 197, 198 |

## Final Cross-Spec Mapping

| Source spec | Problem class | Constitution targets | Status | Notes |
|---|---|---|---|---|
| `196` | Fake-native drift and simple-overview nativity | `UI-FIL-001`, `UI-HARD-001`, `UI-EX-001`, `UI-REVIEW-001` | consumed-by-spec-200 | Produces native/custom/fake-native language and the anti-pattern anchors |
| `197` | Shared detail micro-UI host/core boundaries | `UI-SURF-001`, `ACTSURF-001`, `HDR-001`, `Filament UI — Action Surface Contract`, `UI-REVIEW-001` | consumed-by-spec-200 | Produces shared-family, host, host-drift, and header-boundary language |
| `198` | Page-state ownership and inspect/restoration semantics | `UI-HARD-001`, `UX-001`, `UI-REVIEW-001` | consumed-by-spec-200 | Produces requested/active/draft/inspect/restorable vocabulary and inspect-conflict rules |
| `199` | Shell-context truth and shell/page separation | `ACTSURF-001`, `UX-001`, `UI-REVIEW-001` | consumed-by-spec-200 | Produces global-context/page/detail ownership clarity |
| `201` | Review, grep, lint, and regression enforcement | all of the above as downstream consumers | deferred-to-201 | Spec 201 consumes the final vocabulary directly and must not invent replacement categories |