TenantAtlas/specs/300-internal-tenant-model-naming-consolidation/spec.md

Feature Specification: Internal Tenant Model Naming Consolidation

Feature Branch: 300-internal-tenant-model-naming-consolidation
Created: 2026-05-13
Status: Ready
Input: User-provided Spec 300 draft for a narrow structural rename after Specs 297-299

Spec Candidate Check (mandatory — SPEC-GATE-001)

• Problem: Runtime routes and customer-facing copy are now workspace/environment-first, but active technical owners still use Tenant names for the platform-managed environment object.
• Today's failure: Developers can still reach for TenantResource, TenantDashboard, {tenant} route parameters, tenant_* tables, or tenant-named helpers and accidentally stabilize platform-owned tenant-first architecture.
• User-visible improvement: Future environment work remains provider-neutral and less likely to leak old Tenant wording back into URLs, navigation, tests, reports, or admin workflows.
• Smallest enterprise-capable version: Classify every remaining tenant reference, rename only platform-owned Managed Environment references, preserve provider/framework/historical/negative-guard references, and prove canonical routes/RBAC remain equivalent.
• Explicit non-goals: No new product feature, navigation redesign, provider abstraction rewrite, OperationRun architecture change, localization sweep, compatibility layer, /admin/t/... route, /admin/tenants/... route, or TenantPanel restoration.
• Permanent complexity imported: No new runtime abstraction or feature framework. The implementation imports rename/migration review cost, guard tests, and two spec-local classification artifacts.
• Why now: Current platform-dev has feat: finalize managed environment cutover seal (#354), and Specs 297, 298, and 299 carry completed-task/review signals. This is the right structural cleanup after the cutover seal, not a cutover fix.
• Why not local: The drift spans Filament resources/pages/widgets, route parameters, services, migrations, indexes, tables, tests, helpers, audit/metadata keys, and provider payload boundaries.
• Approval class: Cleanup
• Red flags triggered: Broad structural rename blast radius. Defense: no blind search/replace, mandatory inventory, provider/framework allowlist, focused route/RBAC guards, and no compatibility aliases in final state.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 1 | Komplexität: 1 | Produktnähe: 1 | Wiederverwendung: 2 | Gesamt: 9/12
• Decision: approve as a bounded cleanup spec

Spec Scope Fields (mandatory)

• Scope: workspace + managed-environment core naming
• Primary Routes:
  • /admin/workspaces/{workspace}/environments
  • /admin/workspaces/{workspace}/environments/{environment}
  • /admin/workspaces/{workspace}/environments/{environment}/...
  • /admin/workspaces/{workspace}/operations
  • /admin/provider-connections
• Data Ownership: No new persisted truth. Existing Managed Environment-owned and tenant-owned-by-history tables/columns may be renamed only when they refer to the platform Managed Environment object.
• RBAC: Workspace membership remains the authority boundary; Managed Environment membership remains narrowing-only; non-entitled workspace/environment access remains deny-as-not-found; member-without-capability remains forbidden.

For canonical-view specs:

• Default filter behavior when tenant-context is active: Existing workspace/environment filters remain equivalent; any renamed query parameter must preserve current scoping semantics.
• Explicit entitlement checks preventing cross-tenant leakage: Existing policies, Gates, ManagedEnvironmentAccessScopeResolver, route binding, and test helpers must continue enforcing workspace + environment entitlement.

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes
• Interaction class(es): canonical links, route helpers, global search/resource ownership, navigation registration, audit event names, OperationRun metadata keys, evidence/report/review links, guard tests
• Systems touched: ManagedEnvironmentLinks, workspace intended URL handling, Filament admin panel discovery/routes, route bindings, resources/pages/widgets, RBAC helpers, audit and OperationRun metadata emitters, test helpers
• Existing pattern(s) to extend: Existing workspace/environment route helpers and guard-test patterns from Specs 297-299
• Shared contract / presenter / builder / renderer to reuse: App\Support\ManagedEnvironmentLinks, existing workspace route owners, existing RBAC/policy helpers, existing Filament v5 action/resource conventions
• Why the existing shared path is sufficient or insufficient: Existing helpers already own canonical environment URLs; this spec renames technical owners around those helpers rather than introducing a new link or navigation framework.
• Allowed deviation and why: Provider-specific and Filament framework-required tenant APIs may remain after classification.
• Consistency impact: Routes, route parameters, class names, test helpers, audit metadata, and report/evidence links must remain environment-first unless provider/framework/historical/negative-guard classification applies.
• Review focus: Reviewers must verify no active platform-owned Tenant* technical owner remains unclassified and no legacy route/helper is revived.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: no
• Shared OperationRun UX contract/layer reused: Existing OperationRunLinks and OperationRun service truth remain unchanged if touched.
• Delegated start/completion UX behaviors: N/A - no run start, completion, notification, dedupe, or link UX semantics are introduced.
• Local surface-owned behavior that remains: Existing operation initiation inputs only.
• Queued DB-notification policy: N/A
• Terminal notification path: N/A
• Exception required?: none

Provider Boundary / Platform Core Check (mandatory)

• Shared provider/platform boundary touched?: yes
• Boundary classification: mixed
• Seams affected: platform Managed Environment identifiers/classes/tables, provider connection target-scope metadata, Graph/Entra tenant IDs, onboarding provider identity fields, audit/OperationRun metadata keys
• Neutral platform terms preserved or introduced: workspace, environment, managed_environment, managed_environment_id, ManagedEnvironment, ManagedEnvironmentLinks
• Provider-specific semantics retained and why: Microsoft tenant, Entra tenant, Azure tenant, tenantId, entra_tenant_id, microsoft_tenant_id, provider tenant id, target tenant remain where they describe external provider truth or raw API payloads.
• Why this does not deepen provider coupling accidentally: The spec moves platform-owned naming away from Tenant while explicitly quarantining provider-owned tenant terms instead of deleting them.
• Follow-up path: document-in-feature through tenant-reference-inventory.md and allowed-tenant-references.md; escalate only if an ambiguous active platform-owned term cannot be safely classified.

UI / Surface Guardrail Impact (mandatory)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Filament environment resources/pages technical rename	no expected copy/layout change	Native Filament	navigation/routes/global search	route, page class, resource class	no	Technical owner rename only; visible copy remains from Specs 298-299
Route parameter rename from {tenant} to {environment} where platform-owned	no URL shape change	N/A	canonical route helpers	route binding, URL generation	no	Segment remains /environments/...
Provider-specific tenant labels	no	Native Filament / existing copy	provider identity	provider payload/copy	yes, allowed classification	Keep Microsoft/Entra terms

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

N/A - no new operator-facing surface and no new decision workflow. Existing surfaces must remain equivalent.

Audience-Aware Disclosure (mandatory when operator-facing surfaces are changed)

N/A - no new detail or status surface. Existing diagnostics/support/raw disclosure tiers must remain unchanged.

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

N/A - no new operator-facing list/detail/queue/report surface. Any touched Filament resource/page keeps its current surface class and action hierarchy.

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

N/A - no new operator-facing page. Any renamed page/resource keeps the existing operator question, default-visible content, diagnostics-only content, actions, destructive-action handling, and RBAC.

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no
• New persisted entity/table/artifact?: no new product truth; possible table/column/index/constraint renames only
• New abstraction?: no
• New enum/state/reason family?: no
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: The platform core still looks Tenant-first internally, making future environment/workspace/provider work error-prone and increasing regression risk after the cutover.
• Existing structure is insufficient because: Specs 297-299 intentionally stopped short of structural DB/model/resource consolidation. Leaving active Tenant* owners in place keeps the old architecture as the easiest path for future work.
• Narrowest correct implementation: Rename only platform-owned Managed Environment references and classify everything else; do not generalize provider architecture or rewrite unrelated domains.
• Ownership cost: High review and test cost from a broad rename; mitigated by inventory, phased tasks, focused validation lanes, and no compatibility layer.
• Alternative intentionally rejected: Leave internal names as-is and rely on docs. Rejected because active class/table/helper names shape future code and tests more strongly than comments.
• Release truth: Current-release cleanup after the managed-environment cutover pack

Compatibility posture

This feature assumes a pre-production environment with no live customer data and no compatibility requirement. No legacy aliases, dual-write/read paths, or old route compatibility layers should remain in final state unless a blocking production-data fact is discovered and the spec is stopped.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Feature guard tests, Filament/Livewire page/action tests, focused Unit tests for pure helpers, targeted Browser smoke anchors for visible flows
• Validation lane(s): Feature/Guards, Feature/Workspaces, Feature/ProviderConnections, Feature/RequiredPermissions, Feature/Filament, Feature/Rbac, Browser anchors, Pint dirty, git diff --check
• Why this classification and these lanes are sufficient: The change is structural naming with route/RBAC equivalence requirements; focused guards and impacted feature lanes prove the contract without a broad suite repair loop.
• New or expanded test families: Narrow guard tests for no stale Tenant* active owner/helper/route regression; no new heavy family by default.
• Fixture / helper cost impact: Helpers must be renamed without making workspace/provider/browser setup implicit. Expensive context remains opt-in.
• Heavy-family visibility / justification: Browser smokes are explicit anchors only because canonical route and visible navigation regressions are high-impact.
• Special surface test profile: route-contract, standard-native-filament, global-context-shell, browser-smoke only for touched visible anchors
• Standard-native relief or required special coverage: Standard Filament/Livewire tests are enough for class/resource rename behavior; browser coverage is limited to existing smoke anchors.
• Reviewer handoff: Verify route contract, old route absence, RBAC isolation, stale helper absence, provider terminology preservation, and no unclassified active platform-owned tenant references.
• Budget / baseline / trend impact: Expected focused-lane runtime increase only; document if broad lane cost shifts.
• Escalation needed: document-in-feature; follow-up-spec only if migration/schema risk or unresolved platform-owned tenant references block cleanup.
• Active feature PR close-out entry: Guardrail / Structural Tenant Naming Consolidation / Smoke Coverage
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan route:list | rg "admin/t|admin/tenants|workspaces/.*/environments|provider-connections|required-permissions|operations"
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/RequiredPermissions
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac
  • cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
  • git diff --check

User Scenarios & Testing (mandatory)

User Story 1 - Platform Maintainer Renames Active Managed Environment Owners (Priority: P1)

As a platform maintainer, I need active platform-owned technical names to say ManagedEnvironment/Environment when they refer to the platform managed target, so future code does not rebuild Tenant-first architecture.

Why this priority: This is the core structural cleanup and the strongest dependency-unblocking value.

Independent Test: Run the final tenant-reference scan and verify every remaining tenant reference is classified as provider-specific, framework-required, historical, or regression-guard.

Acceptance Scenarios:

1. Given a platform-owned Filament resource/page/service/helper that refers to the Managed Environment object, When Spec 300 is complete, Then the active class/helper/table/column name is environment-first or is documented as a blocker.
2. Given a remaining tenant reference in active code, When the final inventory is reviewed, Then it has an explicit allowed category and reason.

---

User Story 2 - Operator Routes And Access Stay Equivalent (Priority: P2)

As an operator, I need workspace/environment routes and access rules to behave exactly as before, so the cleanup does not change product behavior.

Why this priority: The structural rename must not weaken route stability, RBAC, or workspace/environment isolation.

Independent Test: Run canonical route, retired route, workspace/environment isolation, and impacted Filament/RBAC tests.

Acceptance Scenarios:

1. Given an entitled user opens /admin/workspaces/{workspace}/environments/{environment}, When the page resolves, Then the same environment detail behavior is available under canonical routes.
2. Given a user is not entitled to the workspace or environment, When they access renamed routes or actions, Then deny-as-not-found semantics still apply.
3. Given retired /admin/t/... or /admin/tenants/... URLs, When they are requested, Then no product route is resurrected.

---

User Story 3 - Provider Tenant Terminology Remains Correct (Priority: P3)

As a provider integration maintainer, I need Microsoft/Entra/Graph tenant terminology to remain intact where it represents external provider truth, so the platform cleanup does not corrupt API contracts or admin meaning.

Why this priority: The goal is platform-owned cleanup, not deleting the word tenant everywhere.

Independent Test: Run provider-specific scans and verify allowed references remain in provider-owned fields/copy/payloads.

Acceptance Scenarios:

1. Given a provider connection field named entra_tenant_id, When Spec 300 is complete, Then the field remains if it represents the external Entra tenant ID.
2. Given a raw Graph payload or target-scope metadata contains tenantId, When classification is performed, Then the provider-owned key is preserved and documented.

Edge Cases

• ManagedEnvironment already exists as the active model and managed_environments already exists as the active table; implementation must consolidate remaining names rather than assume a greenfield Tenant model/table rename.
• Migration filenames and index/constraint names can still carry tenant even when table/columns already use managed_environment; these must be classified and renamed where safe under the pre-production posture.
• Filament tenancy APIs such as Filament::getTenant() are framework-required and must not be renamed.
• Historical specs and negative guard regex literals may keep tenant wording only when the file/category makes that reason explicit.
• Provider identity fields such as entra_tenant_id may appear beside platform managed_environment_id; only the platform-owned key should be renamed.

Requirements (mandatory)

Functional Requirements

• FR-300-001: The implementation MUST refresh tenant-reference-inventory.md before runtime edits and classify every relevant tenant hit as platform-managed-environment, provider-specific, framework-required, historical, regression-guard, test-fixture-stale, or blocked/unclear.
• FR-300-002: No active App\Models\Tenant model or TenantFactory may remain. Current repo truth already uses App\Models\ManagedEnvironment and ManagedEnvironmentFactory; implementation must not add a compatibility alias.
• FR-300-003: Platform-owned Filament owners such as TenantResource, TenantDashboard, TenantRequiredPermissions, TenantDiagnostics, ManageTenantMemberships, and TenantMembershipsRelationManager MUST be renamed to ManagedEnvironment/Environment equivalents unless a repo-real blocker is documented.
• FR-300-004: Platform-owned route parameters under canonical environment routes MUST use {environment} where feasible, or document the repo-real blocker, while preserving public URL segments as /environments/....
• FR-300-005: Platform-owned services/helpers/support classes such as TenantMembershipManager, TenantDiagnosticsService, TenantPageCategory, TenantAction*, TenantOperability*, TenantDashboard*, and tenant-owned workspace-isolation helpers MUST be renamed when they refer to the platform Managed Environment object.
• FR-300-006: Database table, column, index, constraint, model, factory, and migration names that refer to the platform Managed Environment object MUST be environment-first where safe under LEAN-001. Existing active managed_environments, managed_environment_id, and managed_environment_memberships truth MUST remain source of truth.
• FR-300-007: Tenant-named review, evidence, report, baseline, finding, backup, restore, and OperationRun metadata references MUST be renamed only when they point to the platform Managed Environment object. Provider payload keys remain provider-specific.
• FR-300-008: Provider-specific tenant terminology MUST remain intact where it represents Microsoft/Entra/Azure/Graph/provider target truth, including tenantId, entra_tenant_id, microsoft_tenant_id, and provider-facing copy such as Microsoft tenant ID.
• FR-300-009: Framework-required Filament tenant APIs MUST be kept and documented, including Filament::getTenant(), Filament::setTenant(), and tenancy contracts/method names.
• FR-300-010: Stale test helpers such as setTenantPanelContext, panel: 'tenant', and active platform-owned TenantFactory references MUST be removed except for explicit negative guard literals.
• FR-300-011: Existing canonical routes MUST remain active and no /admin/t/..., /admin/tenants/..., or active route named filament.admin.resources.tenants.* may return as a product route.
• FR-300-012: RBAC semantics MUST remain unchanged: workspace membership remains role authority, environment membership remains narrowing-only, non-entitlement stays 404, and missing capability stays 403.
• FR-300-013: Audit/event names and OperationRun metadata keys MAY be renamed only when they represent platform Managed Environment truth; no silent dual-writing is allowed unless a separate migration-risk decision changes this spec.
• FR-300-014: Final scans MUST show no unclassified active platform-owned tenant references.

Non-Functional Requirements

• NFR-300-001: The implementation MUST use a phased rename and tests; blind global search/replace is forbidden.
• NFR-300-002: No compatibility layer, alias class, dual-read, dual-write, or legacy route should remain in final state under the repo's pre-production posture.
• NFR-300-003: Filament v5 / Livewire v4.0+ compliance MUST be explicit; no Livewire v3 or Filament v3/v4 APIs may be introduced.
• NFR-300-004: Laravel 12 panel provider registration remains in apps/platform/bootstrap/providers.php; do not register panel providers in bootstrap/app.php.
• NFR-300-005: Globally searchable resources must either retain View/Edit pages or disable global search after renaming.
• NFR-300-006: Destructive actions touched by the rename must keep ->action(...), ->requiresConfirmation(), server-side authorization, and audit behavior.
• NFR-300-007: Asset strategy is unchanged; if implementation unexpectedly registers Filament assets, deployment notes must include cd apps/platform && php artisan filament:assets.

Acceptance Criteria

• AC-300-001: No active platform-owned model/resource/page/helper/factory named Tenant* remains unless explicitly classified as provider-specific, framework-required, historical, or regression-guard.
• AC-300-002: Active platform-owned DB naming is environment-first. managed_environments, managed_environment_id, and managed_environment_memberships remain source-of-truth names; old tenant-named active FKs/tables/constraints are removed or documented as allowed non-platform references.
• AC-300-003: Active Filament technical owners for environment management are environment-named and global search behavior remains valid under Filament v5 rules.
• AC-300-004: /admin/workspaces/{workspace}/environments/... routes remain active; /admin/t/... and /admin/tenants/... remain retired.
• AC-300-005: Provider-specific Microsoft/Entra/provider tenant language remains intact and documented.
• AC-300-006: No stale helper names remain except negative guard literals documented in the inventory.
• AC-300-007: Workspace/environment RBAC and isolation tests prove no access widening.
• AC-300-008: OperationRun remains execution truth; only platform-owned metadata names change if needed.
• AC-300-009: Evidence/report/review semantics remain unchanged; only platform-owned references are renamed.
• AC-300-010: tenant-reference-inventory.md and allowed-tenant-references.md classify all remaining tenant references at close-out.

Out Of Scope

• New product features or navigation redesign
• Customer Review Workspace, Governance Inbox, Localization v1, package execution, guided operations, or broader provider abstraction work
• Microsoft Graph contract refactor or OperationRun architecture change
• Reintroducing TenantPanelProvider, /admin/t/..., /admin/tenants/..., or old TenantResource product routes
• Production online migration/backfill strategy for live customer data
• Permanent aliases, compatibility routes, dual-write, or dual-read behavior

Assumptions

• Specs 297-299 are merged into the current branch or this branch is based on their final state.
• There is no production customer data requiring online backward-compatible migration.
• Local/dev/test data may be migrated or rebuilt.
• Provider-specific tenant concepts and Filament framework-required tenant APIs are allowed when classified.
• The current repo source of truth is App\Models\ManagedEnvironment and table managed_environments; the cleanup targets remaining technical debt.

Open Questions

• None blocking for preparation. If implementation discovers production-data migration risk or an ambiguous active platform-owned tenant reference that cannot be classified, stop and report blocked by migration/schema risk or blocked by unresolved platform-owned tenant references.