php-tenant/FINDINGS.md

# Phase 0 Findings — core/php-tenant

**Date:** 2026-02-20
**Branch:** feat/phase-0-assessment
**Analyst:** Clotho (darbs-claude)
**Issue:** #2

---

## 1. Environment

| Tool     | Version     | Status  |
|----------|-------------|---------|
| PHP      | 8.3.6       | OK      |
| Composer | 2.9.5       | OK      |
| Vendor   | —           | MISSING |

### 1.1 Composer Install

```
composer install --no-interaction
```

**Result: FAILED**

```
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Root composer.json requires host-uk/core, it could not be found in any version,
      there may be a typo in the package name.
```

**Root cause:** `host-uk/core` (the host framework) is a private package. The `composer.json` has no `repositories` section to point Composer at the private registry or a local path.

**Resolution needed:** One of:
1. Add a `repositories` entry pointing to the Forgejo package registry (`darbs.lthn.ai`), or
2. Set `COMPOSER_AUTH` env var with appropriate credentials, or
3. Add a local path repository for development if `core` is checked out alongside this package.

Until resolved, **all tooling that requires `vendor/` is blocked** (tests, Pint, PHPStan).

---

## 2. Test Baseline

**Status: CANNOT RUN** — vendor directory is empty.

### Test inventory (static count)

| File | Lines |
|------|-------|
| `tests/Feature/AccountDeletionTest.php` | ~120 |
| `tests/Feature/AuthenticationTest.php` | ~160 |
| `tests/Feature/EntitlementApiTest.php` | ~700 |
| `tests/Feature/EntitlementServiceTest.php` | ~800 |
| `tests/Feature/ProfileTest.php` | ~100 |
| `tests/Feature/ResetBillingCyclesTest.php` | ~180 |
| `tests/Feature/SettingsTest.php` | ~120 |
| `tests/Feature/TwoFactorAuthenticatableTest.php` | ~140 |
| `tests/Feature/UsageAlertServiceTest.php` | ~180 |
| `tests/Feature/WaitlistTest.php` | ~120 |
| `tests/Feature/WorkspaceCacheTest.php` | ~300 |
| `tests/Feature/WorkspaceInvitationTest.php` | ~255 |
| `tests/Feature/WorkspaceSecurityTest.php` | ~433 |
| `tests/Feature/WorkspaceTenancyTest.php` | ~165 |
| `tests/Feature/Guards/AccessTokenGuardTest.php` | ~180 |
| **Total** | **~4,053 lines across 15 files** |

Tests use Pest with Orchestra Testbench. Coverage appears comprehensive for workspace- and entitlement-level tests.

**Pass/fail counts:** Cannot determine — blocked by missing vendor.

---

## 3. Code Quality (Static Review)

### 3.1 Pint / PHPStan

Cannot run — vendor missing. Tools (`vendor/bin/pint`, `vendor/bin/phpstan`) not available.

### 3.2 Missing `declare(strict_types=1)` — identified via static scan

The following files are missing the strict types declaration despite this being a documented coding standard:

| File | Priority |
|------|----------|
| `Models/AccountDeletionRequest.php` | P3 |
| `Models/Boost.php` | P3 |
| `Models/EntitlementLog.php` | P3 |
| `Models/Feature.php` | P3 |
| `Models/Package.php` | P3 |
| `Models/UsageRecord.php` | P3 |
| `Models/WaitlistEntry.php` | P3 |
| `Models/WorkspacePackage.php` | P3 |
| `Services/EntitlementResult.php` | P3 |

> NOTE: TODO DX-001 records this as fixed for `Models/Workspace.php`, `Models/User.php`, and `Services/EntitlementService.php` — but 9 other files still lack the declaration.

---

## 4. Architecture Review

### 4.1 Workspace Isolation — BelongsToWorkspace Trait

**File:** `Concerns/BelongsToWorkspace.php`

The trait is the primary tenancy enforcement mechanism for Eloquent models.

**Isolation mechanisms:**
1. `bootBelongsToWorkspace()` registers an Eloquent `creating` hook that:
   - Reads the current workspace from request attributes (`workspace_model`) or the authenticated user's default workspace
   - Auto-assigns `workspace_id` if not already set
   - Throws `MissingWorkspaceContextException` if workspace context is absent and strict mode is on

2. `scopeOwnedByCurrentWorkspace(Builder $query)` filters queries to the current workspace. In non-strict mode it returns `whereRaw('1 = 0')` (empty, fail-safe).

3. Cache invalidation is wired to `saved` and `deleted` model events via `clearWorkspaceCache()`.

**Opt-out:** Setting `protected bool $workspaceContextRequired = false;` on a model disables the exception — useful for legacy code but discouraged.

**Workspace resolution order:**
```
request()->attributes->get('workspace_model')   // set by ResolveWorkspaceFromSubdomain
  → auth()->user()->defaultHostWorkspace()       // falls back to auth user
  → null → MissingWorkspaceContextException
```

### 4.2 WorkspaceScope — Global Query Scope

**File:** `Scopes/WorkspaceScope.php`

An Eloquent global scope (implements `Scope`) that automatically filters all queries by the current workspace.

Key design decisions:
- `static bool $strictModeEnabled = true` — global toggle
- `withoutStrictMode(callable $callback)` — safe scoped disable (restores on exit)
- Builder macros: `forWorkspace(Workspace|int)`, `acrossWorkspaces()`, `currentWorkspaceId()`
- Console commands bypass strict mode automatically (`runningInConsole()` + not unit tests)
- Models can opt out: `public bool $workspaceScopeStrict = false;`

### 4.3 Middleware for Tenant Resolution

**Files:** `Middleware/`

| Middleware | Purpose |
|-----------|---------|
| `ResolveWorkspaceFromSubdomain` | Resolves workspace from `{slug}.host.uk.com` subdomain. Hardcoded mappings (hub→main, bio→bio, etc.). Sets `workspace_model` on request attributes. |
| `RequireWorkspaceContext` | Validates workspace exists; validates user has access. Resolution order: subdomain attr → `Workspace::current()` → `workspace_id` input → `X-Workspace-ID` header → `?workspace` query param. Logs denied attempts. |
| `CheckWorkspacePermission` | Per-permission authorisation within a resolved workspace. |
| `RequireAdminDomain` | Restricts routes to admin subdomains (hub, www, hestia). |
| `ResolveNamespace` | Resolves current namespace from `?namespace` query, `X-Namespace` header, or session. |

**Subdomain hardcoding concern:** `ResolveWorkspaceFromSubdomain` contains a hardcoded mapping of subdomains → workspace slugs. Adding a new service workspace requires a code change. Consider moving to database/config.

### 4.4 Migration Patterns

**Files:** `Migrations/`

| Migration | Tables created/modified |
|-----------|------------------------|
| `0001_01_01_000000_create_tenant_tables.php` | 15 tables: users, workspaces, namespaces, entitlement_features, entitlement_packages, entitlement_package_features, entitlement_workspace_packages, entitlement_namespace_packages, entitlement_boosts, entitlement_usage_records, entitlement_logs, user_two_factor_auth, sessions, password_reset_tokens, user_workspace |
| `2026_01_26_000000_create_workspace_invitations_table.php` | workspace_invitations |
| `2026_01_26_120000_create_usage_alert_history_table.php` | usage_alert_history |
| `2026_01_26_140000_create_entitlement_webhooks_tables.php` | entitlement_webhooks, entitlement_webhook_deliveries |
| `2026_01_26_140000_create_workspace_teams_table.php` | workspace_teams |
| `2026_01_29_000000_add_performance_indexes.php` | Indexes on users.tier, namespaces.slug, workspaces.{is_active,type,domain}, user_workspace.team_id, entitlement_usage_records.user_id, entitlement_logs.user_id |

All tables use appropriate composite indexes on commonly filtered columns.

---

## 5. Critical Bug: Missing `namespace_id` Columns in Entitlement Tables

**Severity: P1 — Runtime crash**

### 5.1 Description

The namespace-level entitlement features (`recordNamespaceUsage`, `provisionNamespaceBoost`) will fail at runtime with a database error because the underlying tables are missing the `namespace_id` column.

**Models that declare `namespace_id` as fillable:**

| Model | File |
|-------|------|
| `UsageRecord` | `Models/UsageRecord.php:18` |
| `Boost` | `Models/Boost.php:17` |

**Service methods that write `namespace_id`:**

| Method | File |
|--------|------|
| `EntitlementService::recordNamespaceUsage()` | `Services/EntitlementService.php:453` |
| `EntitlementService::provisionNamespaceBoost()` | `Services/EntitlementService.php:1861` |

**Migrations that DO NOT create the column:**

- `entitlement_usage_records` — `0001_01_01_000000_create_tenant_tables.php:248-261`
- `entitlement_boosts` — `0001_01_01_000000_create_tenant_tables.php:226-245`

**Query methods that filter by `namespace_id` without it existing:**

- `EntitlementService::getNamespaceCurrentUsage()` lines 1605, 1615, 1622 — `WHERE namespace_id = ?`
- `Namespace_::boosts()` relationship — references a non-existent FK

### 5.2 Impact

Any call to:
- `$entitlementService->recordNamespaceUsage($namespace, 'links')`
- `$entitlementService->provisionNamespaceBoost($namespace, 'links', [...])`
- `$entitlementService->canForNamespace($namespace, 'links')` (usage query path)

will throw:
```
SQLSTATE[HY000]: General error: 1 table entitlement_usage_records has no column named namespace_id
```

The test suite in `tests/Feature/EntitlementServiceTest.php` likely exercises these paths and would be failing if runnable.

### 5.3 Fix Required

A migration is needed to add `namespace_id` (nullable FK → namespaces, null on delete) to:
1. `entitlement_usage_records`
2. `entitlement_boosts`

Plus indexes: `(namespace_id, feature_code, recorded_at)` on usage records, `(namespace_id, feature_code, status)` on boosts.

---

## 6. Summary of Open Issues

| ID | Severity | Description | Status |
|----|----------|-------------|--------|
| BUG-001 | **P1** | `namespace_id` column missing from `entitlement_usage_records` and `entitlement_boosts` migrations — runtime crash | **NEW** |
| DX-003 | P3 | 9 model/service files missing `declare(strict_types=1)` | NEW |
| ENV-001 | P0-blocker | `composer install` fails — `host-uk/core` repository not configured | NEW |
| ARCH-001 | P4 | `ResolveWorkspaceFromSubdomain` hardcodes subdomain→workspace mappings; new services require code change | NEW |

Existing items from `TODO.md` P1–P3 (SEC-001 through SEC-006, DX-001, DX-002, TEST-001, TEST-002, PERF-001, PERF-002) are marked Fixed in the TODO and have corresponding code in place. These will be verifiable once `composer install` succeeds and tests run.

---

## 7. Recommended Next Steps

1. **Immediate:** Fix `composer.json` to resolve `host-uk/core` (add repository entry or document setup instructions in README).
2. **Immediate:** Add migration for `namespace_id` columns on `entitlement_usage_records` and `entitlement_boosts` — this is a production crash bug.
3. **Short-term:** Once vendor installs, run full test suite and document pass/fail baseline.
4. **Short-term:** Add `declare(strict_types=1)` to the 9 remaining files.
5. **Medium-term:** Consider moving subdomain→workspace mapping to config/database.