TenantAtlas/specs/207-shared-test-fixture-slimming/data-model.md

Data Model: Shared Test Fixture Slimming

This feature introduces no new runtime database tables. The data-model work formalizes repository-level fixture-governance objects that describe how shared helpers, factories, migration packs, and lane measurements should behave. Field names are conceptual and may later map to PHP arrays, guard tests, or documentation rather than to persisted runtime records.

1. Fixture Profile

Purpose

Represents one named level of setup cost and side effects for shared test support.

Fields

• profile_id: stable identifier such as minimal, standard, or full
• display_name: contributor-facing name
• cost_class: minimal, standard, or integration-heavy
• creates_workspace: boolean
• creates_workspace_membership: boolean
• creates_tenant_membership: boolean
• sets_session_context: boolean
• clears_capability_caches: boolean
• creates_provider_connection: boolean
• creates_provider_credential: boolean
• sets_ui_context: boolean
• legacy_aliases: optional list such as provider-enabled, credential-enabled, or ui-context
• notes: short guidance for when the profile is appropriate

Validation Rules

• The catalog must contain at least minimal, standard, and full.
• Exactly one profile may be the default profile for a given helper binding.
• minimal must not create provider, credential, cache-clearing, or UI-context side effects.
• full may create integration-heavy side effects, but those side effects must be declared explicitly.

2. Helper Entry Point

Purpose

Represents one shared helper or helper alias that resolves to a fixture profile contract.

Fields

• helper_name: example createUserWithTenant
• default_profile_id: the profile used when no explicit profile is requested
• supported_profile_ids: list of allowed profiles
• legacy_aliases: transitional helper names or profile aliases
• announces_heavy_context: boolean indicating whether the name itself signals heavy behavior
• side_effect_contract: list of side effects promised by this helper when a given profile is selected
• transition_status: current, legacy-transition, or planned-removal

Validation Rules

• Every shared helper must resolve to exactly one default profile.
• Heavy behavior must be reachable through an explicit profile or clearly named helper, not only hidden booleans.
• Legacy aliases must map to a declared profile, remain temporary, and point to a declared removal trigger in the transition-path model.

3. Factory Cascade Finding

Purpose

Represents one audited place where a factory, model hook, or callback creates hidden extra context.

Fields

• finding_id: stable identifier
• subject_name: factory or model name such as TenantFactory or Tenant::booted
• cascade_source: definition, attribute-callback, afterCreating, model-event, or support-helper
• trigger_condition: what causes the extra context to appear
• created_objects: list of related models or state written as a side effect
• cost_class: standard or heavy
• disposition: remove, make-explicit, retain-documented, or follow-up
• notes: rationale and migration concerns

Validation Rules

• Every audited high-usage subject must have at least one explicit disposition.
• A finding marked retain-documented must explain why the behavior is materially required.

4. Factory State Contract

Purpose

Represents the expected cost posture of a factory default or named state.

Fields

• factory_name
• state_name
• cost_class: minimal, standard, or integration-heavy
• default_state: boolean
• creates_relationships: related models or graph expansions
• forbidden_side_effects: side effects that must not happen in this state
• intended_usage: short explanation of what the state is for

Validation Rules

• A touched high-usage factory must have a declared default cost class.
• A minimal state must not create undeclared relationships or repair missing workspace/provider context behind the scenes.
• An integration-heavy state must document the graph it creates.

5. Legacy Transition Path

Purpose

Represents how an old helper or heavy default remains temporarily available during migration.

Fields

• transition_id
• legacy_entry_point: helper name, alias, or factory default being preserved temporarily
• resolved_profile_id: the explicit profile or state it maps to
• visibility_mode: named-alias, warning-comment, or guard-tested
• removal_trigger: condition for retiring the transition path
• notes

Validation Rules

• A transition path must remain visibly heavier than the new default behavior.
• A transition path must have a declared removal trigger so it does not become permanent accidental API.

6. Caller Migration Pack

Purpose

Represents one batch of high-usage callers migrated together.

Fields

• pack_id
• target_lanes: one or more of fast-feedback, confidence, browser, or heavy-governance
• selection_basis: high-usage, high-cost, shared-surface, or legacy-dependency
• caller_selectors: directories, files, or patterns identifying the pack
• target_profile_id: preferred fixture profile after migration
• legacy_fallback_allowed: boolean
• expected_lane_impact: narrative or numeric expectation

Validation Rules

• The first slice must include at least one migration pack affecting either fast-feedback or confidence.
• Packs migrated to minimal or standard must not silently fall back to full context without an explicit reason.

7. Fixture Guard Contract

Purpose

Represents a guard test that protects fixture behavior from regression.

Fields

• guard_id
• subject_type: helper, factory, builder, or lane-measurement
• subject_name
• asserts_absent_context: list of context that must not appear
• asserts_present_context: list of context that must appear
• covers_transition_path: boolean
• failure_signal: brief description of what regression should be obvious in CI

Validation Rules

• Minimal-path guards must assert absence of hidden heavy context.
• Heavy-path guards must assert presence of promised heavy context.
• Transition-path guards must remain explicit about what legacy behavior is being preserved.

8. Lane Impact Measurement

Purpose

Represents before and after measurement for a migration pack using the Spec 206 reporting seams.

Fields

• measurement_id
• lane_id: example fast-feedback or confidence
• baseline_seconds: pre-migration wall-clock value
• post_migration_seconds: post-migration wall-clock value
• budget_threshold_seconds: current Spec 206 budget for the lane
• status: improved, stable, or regressed
• notes

Validation Rules

• Standard-lane measurements must reference the existing Spec 206 budgets.
• A lane marked regressed must explain whether the regression is temporary, justified, or blocking.

9. First-Slice Governance Inventory

Current Shared Fixture Surface

• apps/platform/tests/Pest.php now exposes a canonical minimal, standard, and full profile catalog plus explicit transition helpers for provider-enabled, credential-enabled, ui-context, and heavy callers.
• apps/platform/app/Models/Tenant.php still contains a test-only boot hook that auto-provisions a workspace when workspace_id is null.
• apps/platform/database/factories/TenantFactory.php uses afterCreating() workspace provisioning by default and only partially suppresses it in minimal().
• apps/platform/database/factories/OperationRunFactory.php now keeps the default path userless and requires an explicit withUser() opt-in for interactive initiator context.
• apps/platform/database/factories/ProviderConnectionFactory.php now exposes explicit minimal, standard, and full provider graph states instead of leaving the cost posture implicit.
• apps/platform/database/factories/ProviderCredentialFactory.php now exposes an explicit verified-connection state and keeps legacy-migrated credentials visible through a named state.
• apps/platform/database/factories/BackupSetFactory.php now keeps the default path item-free and uses explicit full, staleCompleted(), and degradedCompleted() states for backup-item graphs.
• apps/platform/tests/Feature/Concerns/BuildsBaselineCompareMatrixFixtures.php and similar builders create intentionally rich multi-record graphs that should remain explicit heavy helpers.

Recorded Cascade Dispositions

• Tenant::booted workspace auto-provisioning: make-explicit via Tenant::skipTestWorkspaceProvisioning() and TenantFactory::minimal().
• TenantFactory::configure() default workspace provisioning: retain-documented for legacy callers, with minimal() as the lean escape hatch.
• OperationRunFactory implicit initiator user creation: remove from the default path, now restored only through withUser().
• OperationRunFactory workspace repair when a tenant lacks workspace context: follow-up; guarded through lean caller migration rather than silently broadening helper defaults further in this slice.
• ProviderConnectionFactory provider credential graph inflation: make-explicit through full() and withCredential().
• ProviderCredentialFactory verified dedicated connection graph: make-explicit through verifiedConnection().
• BackupSetFactory backup-item graph creation: retain-documented on named states only (full, staleCompleted, degradedCompleted).

First-Slice Migration Packs

• console-navigation-pack: tests/Feature/Console/ReconcileOperationRunsCommandTest.php, tests/Feature/Console/ReconcileBackupScheduleOperationRunsCommandTest.php, and tests/Feature/Navigation/RelatedNavigationResolverMemoizationTest.php now use explicit minimal helpers or lean operation-run factory states.
• rbac-drift-pack: tests/Feature/Spec080WorkspaceManagedTenantAdminMigrationTest.php and tests/Feature/BaselineDriftEngine/FindingFidelityTest.php now call createMinimalUserWithTenant() directly instead of depending on the generic default helper entry point.
• heavy-builder-pack: BuildsBaselineCompareMatrixFixtures and BuildsPortfolioTriageFixtures now make the chosen minimal actor-setup path explicit while still remaining intentionally graph-heavy builders.

First-Slice Target Objects

• Canonical fixture-profile vocabulary and helper bindings
• Tenant and workspace provisioning cascade audit
• Lean state contracts for the touched high-usage factories
• Legacy transition paths for heavy historical callers
• High-usage migration packs for fast-feedback and confidence
• Guard contracts for lean, heavy, and legacy-path behavior
• Lane impact measurements against Spec 206 budgets