TenantAtlas/specs/152-livewire-context-locking/data-model.md

Data Model: Livewire Context Locking and Trusted-State Reduction

This feature does not introduce new database tables in the first slice. The data-model work formalizes trust-boundary entities and field classes that are already implicit in existing Livewire and Filament components.

1. Trusted State Class

Purpose

Defines how a given piece of component state may be stored and used.

Allowed values

• presentation
• locked_identity
• server_derived_authority

Rules

• presentation state may remain public and mutable.
• locked_identity state may remain public only when it is client-immutable and still re-resolved before protected actions.
• server_derived_authority state must not rely on client mutability at all and is derived from route, session, resolver, or persisted workflow truth.

2. Component Trusted-State Policy

Purpose

Represents the trust contract for one stateful Livewire or Filament surface.

Fields

• component_name: human-readable identifier for the surface
• plane: admin_tenant, admin_workspace, or system_platform
• route_anchor: route-bound record or context source, if any
• authority_sources: canonical sources used to re-derive protected targets
• locked_identities: list of public scalar IDs allowed to persist for continuity
• mutable_selectors: list of user-controlled selectors that remain proposals only
• forbidden_public_authority_fields: list of model objects or mutable IDs disallowed as final authority

Relationships

• One component policy has many trusted fields.
• One component policy has many forged-state regression cases.

3. Trusted Field

Purpose

Represents one public property or equivalent state slot on a covered component.

Fields

• field_name
• state_class
• php_type
• source_of_truth
• used_for_protected_action: boolean
• revalidation_required: boolean
• notes

Validation rules

• If state_class = presentation, then used_for_protected_action must be false.
• If used_for_protected_action = true, then state_class must be locked_identity or server_derived_authority.
• If php_type is an Eloquent model and the field is ownership-relevant, it is a migration target and should be phased toward locked scalar or server-derived access.

4. Authority Source

Purpose

Represents the canonical seam used to re-derive truth on the server.

First-slice source types

• route_binding
• workspace_context
• tenant_panel_context
• persisted_onboarding_draft
• allowed_tenant_universe
• explicit_scoped_query

Example mappings

• Onboarding draft identity: route binding + persisted onboarding draft
• Current workspace: WorkspaceContext
• Tenant-context page scope: route binding or ResolvesPanelTenantContext
• System runbook tenant selector: AllowedTenantUniverse

5. Selector Proposal

Purpose

Represents mutable client-submitted selection state that is allowed to change but must be validated before use.

Fields

• selector_name
• target_model
• scope_rules
• null_allowed: boolean
• validation_outcome

Validation outcomes

• accepted
• rejected_not_found
• rejected_forbidden
• reset_required

Rules

• A selector proposal never grants authority by itself.
• A selector proposal must be re-scoped to the current workspace, tenant, or allowed-universe before action execution.

6. Forged-State Regression Case

Purpose

Represents a reproducible test scenario where client state is mutated to challenge the trust boundary.

Fields

• component_name
• mutation_type: foreign_id, stale_id, null_forced, cross_workspace, cross_plane
• entry_point: page load, action call, modal submit, or rerun path
• expected_outcome: 404, 403, or no-op fail-closed
• must_preserve_data_integrity: boolean

State transitions

• pending_design → covered_by_test
• covered_by_test → guarded_in_ci

7. First-Slice Surface Inventory

Managed Tenant Onboarding Wizard

• route_anchor: onboarding draft route parameter
• Locked identities:
  • managedTenantId (?int) backed by persisted onboarding draft identity and re-resolved through currentManagedTenantRecord()
  • onboardingSessionId (?int) backed by persisted onboarding draft identity and re-resolved through currentOnboardingSessionRecord()
• Mutable selector proposals:
  • selectedProviderConnectionId (?int) revalidated against canonical draft and scoped provider queries before verify/bootstrap paths
  • selectedBootstrapOperationTypes (array<int, string>) remains presentation-only wizard state
• Server-derived authority fields:
  • public Workspace $workspace refreshed from WorkspaceContext
  • public ?Tenant $managedTenant treated as display convenience only; canonical tenant truth comes from draft/scoped query
  • public ?TenantOnboardingSession $onboardingSession treated as display convenience only; canonical draft truth comes from resolver-backed persisted session lookup
• Canonical authority sources:
  • WorkspaceContext
  • onboarding draft resolver
  • persisted draft state
  • scoped provider-connection query

Tenant Required Permissions Page

• route_anchor: tenant route parameter
• Locked identities:
  • scopedTenantId (?int) derived from the route tenant and revalidated through trustedScopedTenant()
• Mutable selector proposals:
  • status, type, features, and search remain presentation-only filters
• Server-derived authority fields:
  • canonical tenant scope is derived through resolveScopedTenant(), WorkspaceContext, and trustedScopedTenant()
• Canonical authority sources:
  • route-bound tenant resolution
  • workspace context

System Runbooks Page

• route_anchor: none
• Locked identities:
  • none in the first slice; platform selector state remains proposal-only
• Public selector proposals:
  • findingsTenantId (?int) is revalidated through AllowedTenantUniverse::resolveAllowedOrFail()
  • tenantId (?int) is mirrored display state for the last trusted preflight result
  • findingsScopeMode and scopeMode remain mutable UI state that must normalize into a trusted scope DTO before action execution
• Server-derived authority fields:
  • trusted scope derives from trustedFindingsScopeFromFormData() / trustedFindingsScopeFromState() and the allowed tenant universe
• Canonical authority sources:
  • authenticated platform user
  • allowed tenant universe
  • runbook scope DTO

8. Out-of-Scope but Related Fields

• Public widget record models such as tenant widgets storing public ?Tenant $record
• Resource page state handled primarily through Filament route model binding
• Non-stateful controller endpoints and queued job payloads

These remain rollout inventory candidates after the first slice proves the trusted-state pattern.