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	The drift classes this amendment addresses
source_specs	list	Evidence specs feeding the amendment, limited here to Specs 196 through 199
expected_outputs	list	Vocabulary, anti-pattern, exception, or state-layer additions contributed by this target
deferred_enforcement	list	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	Example surfaces or surface families that fit the term
negative_examples	list	Nearby cases that must not be misclassified under the term
governing_sections	list	Constitution sections that must mention or support the term
source_specs	list	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	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	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	Mandatory explanation points in the governing spec or PR
boundaries	list	What the exception does not allow
standardized_parts	list	What must remain consistent despite the exception
governing_section	string	Expected home in UI-EX-001
deferred_enforcement	list	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	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	Competing truths or cross-layer conflicts that are not allowed
source_specs	list	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	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