120 lines
6.9 KiB
Markdown
120 lines
6.9 KiB
Markdown
# [DEF:ADR-0010:ADR]
|
||
# @STATUS ACTIVE
|
||
# @PURPOSE Define the model decomposition gate for Svelte 5 Screen Models: maximum size thresholds, split strategy, and enforcement mechanism to prevent god‑object anti‑pattern in model‑first architecture.
|
||
# @RELATION DEPENDS_ON -> [ADR-0006:ADR]
|
||
# @RELATION REFINES -> [Std.Semantics.Svelte]
|
||
# @RELATION CALLS -> [DashboardHubModel]
|
||
# @RATIONALE Screen Models (`[TYPE Model]` in `.svelte.ts` files) aggregate all screen‑level state and actions. Without a size gate, models accumulate methods indefinitely as features grow — reproducing the same monolith problem that model‑first architecture was designed to solve. The DashboardHubModel (2026‑06‑02, PR 4) is the first model to approach the threshold at 350 lines and 35 public methods. This ADR locks in the decomposition rule before the model crosses the boundary.
|
||
# @RATIONALE 400‑line threshold mirrors INV_7 (module <400 lines) from `semantics‑core` §I, creating a consistent rule across both page files and model files.
|
||
# @RATIONALE 40‑method threshold is based on practical cognitive load: beyond ~40 public methods, an AI agent or human developer cannot hold the full model API in working memory when reasoning about invariants.
|
||
# @REJECTED No size gate — rejected because DashboardHubModel already demonstrates the accumulation pattern (35 atoms, 35 methods from one refactoring pass). Without a gate, future features (batch‑delete, export, saved‑filters) would push it past 600 lines.
|
||
# @REJECTED Arbitrary split (e.g. file‑size only) — rejected because splitting by line count alone ignores method cohesion. The split MUST follow responsibility boundaries (filters, selection, git) to keep invariants within each submodel locally verifiable.
|
||
|
||
# ADR-0010: Model Decomposition Gate
|
||
|
||
## Status
|
||
ACTIVE — enforced for all C4+ Screen Models as of 2026‑06‑02.
|
||
|
||
## Context
|
||
|
||
Screen Models (defined in `semantics‑svelte` §IIIa) are the single source of truth for screen‑level state. They use Svelte 5 runes (`$state`, `$derived`) in `.svelte.ts` files and declare `@STATE`, `@ACTION`, and `@INVARIANT` annotations.
|
||
|
||
The first wave of model extraction (PR 4, June 2026) produced `DashboardHubModel`: 350 lines, 35 `$state` atoms, and 35 public methods. While this is a 51% reduction from the original 2765‑line page, the model already bundles four distinct responsibility domains:
|
||
|
||
1. **Core data** — pagination, loading/error state, environment context
|
||
2. **Filters & sort** — column filter dropdowns, search, sort direction
|
||
3. **Selection & bulk actions** — checkboxes, select‑all, migrate/backup modals
|
||
4. **Git operations** — init, sync, commit, pull, push, status batch
|
||
|
||
Adding future features (batch‑delete, saved‑filters, export) to the same model would push it past 600 lines — reproducing the monolith anti‑pattern at the model layer.
|
||
|
||
## Decision
|
||
|
||
### Thresholds
|
||
|
||
| Criterion | Threshold | Action |
|
||
|-----------|-----------|--------|
|
||
| Model file > **400 lines** | Mandatory | MUST decompose before adding new methods |
|
||
| Model > **40 public methods** (excluding private `_` helpers) | Mandatory | MUST split into submodels by responsibility |
|
||
| Either threshold crossed | Hard gate | New PRs adding methods to the model MUST include the split |
|
||
|
||
### Split Strategy
|
||
|
||
When a model crosses either threshold, split into submodels by **responsibility domain**. Each submodel:
|
||
|
||
- Lives in its own `.svelte.ts` file: `<Domain>Model.svelte.ts`
|
||
- Declares `@RELATION COMPOSED_BY -> [ParentModel]` on the parent model
|
||
- Exports a class with `$state` atoms and public methods for its domain only
|
||
- Is instantiated as a property of the parent model
|
||
|
||
**Concrete split plan for `DashboardHubModel` (when threshold is crossed):**
|
||
|
||
```
|
||
lib/models/
|
||
├── DashboardHubModel.svelte.ts # Core: pagination, load, environment, composes submodels
|
||
├── DashboardFiltersModel.svelte.ts # Search, column filters, sort
|
||
├── DashboardSelectionModel.svelte.ts # Checkbox, select all/visible, bulk modals
|
||
├── DashboardGitModel.svelte.ts # Git init, sync, commit, pull, push, status batch
|
||
```
|
||
|
||
**Parent model composition pattern:**
|
||
|
||
```typescript
|
||
// #region DashboardHubModel [C:4] [TYPE Model] [SEMANTICS dashboard,hub,core]
|
||
// @RELATION COMPOSED_BY -> [DashboardFiltersModel]
|
||
// @RELATION COMPOSED_BY -> [DashboardSelectionModel]
|
||
// @RELATION COMPOSED_BY -> [DashboardGitModel]
|
||
export class DashboardHubModel {
|
||
readonly filters = new DashboardFiltersModel();
|
||
readonly selection = new DashboardSelectionModel();
|
||
readonly git = new DashboardGitModel();
|
||
|
||
// Core atoms only:
|
||
selectedEnv = $state<string | null>(null);
|
||
allDashboards = $state<DashboardRow[]>([]);
|
||
isLoading = $state(true);
|
||
// ... < 10 atoms
|
||
}
|
||
```
|
||
|
||
### Enforcement
|
||
|
||
1. **Documentation** — every C4+ model MUST declare `@INVARIANT DECOMPOSITION GATE: 400 lines, 40 methods` with a comment referencing this ADR.
|
||
2. **Guardrail** — `scripts/audit-frontend-style.mjs` already checks page size; extend with model size check (`>400 lines OR >40 public methods`).
|
||
3. **Code review** — new PRs adding methods to a model near 300+ lines MUST include either a split plan in the PR description or a `@RATIONALE` explaining why split is deferred.
|
||
|
||
### Relationship to Page Size Gate
|
||
|
||
| Level | Threshold | Documented in |
|
||
|-------|-----------|---------------|
|
||
| Page file (`+page.svelte`) | 400 lines (INV_7) | `semantics‑core` §I |
|
||
| Screen Model (`.svelte.ts`) | 400 lines OR 40 methods | This ADR |
|
||
|
||
A page that exceeds 400 lines is decomposed into Model + Components. A Model that exceeds 400 lines is decomposed into submodels. The invariant cascades down.
|
||
|
||
## Consequences
|
||
|
||
### Positive
|
||
- Models stay reviewable and testable (unit tests for each submodel in isolation).
|
||
- AI agents receive a clear instruction via `@INVARIANT DECOMPOSITION GATE` in the model header.
|
||
- Future features map directly to submodels — no ambiguity about where to add code.
|
||
|
||
### Negative
|
||
- Cross‑submodel invariants become harder to declare (e.g., "changing filter resets selection" spans two submodels). Mitigation: the parent model composes submodels and declares cross‑cutting invariants.
|
||
- Slightly more indirection (`m.filters.searchQuery` vs `m.searchQuery`). Mitigation: TypeScript autocomplete resolves this in IDEs.
|
||
|
||
## Migration
|
||
|
||
1. **Done** — `DashboardHubModel` created (350 lines, below threshold). `@INVARIANT DECOMPOSITION GATE` added with split plan.
|
||
2. **Next** — when model crosses 400 lines or 40 methods, execute the split plan documented in the model header.
|
||
3. **Future models** — all new C4+ Screen Models created after this ADR MUST include the `@INVARIANT DECOMPOSITION GATE` annotation.
|
||
|
||
## References
|
||
|
||
- `semantics‑core` §I INV_7 — module < 400 lines
|
||
- `semantics‑svelte` §IIIa — Screen Model contract template
|
||
- `semantics‑svelte` §IIIa.1 — Model Decomposition Gate (added 2026‑06‑02)
|
||
- `ai‑native‑design‑audit.md` §10 — Lessons learned from PR 4
|
||
|
||
# [/DEF:ADR-0010:ADR]
|