TenantAtlas/specs/415-generic-content-backed-capture/implementation-report.md

# Implementation Report: Spec 415 - Generic Content-Backed Capture

## Preflight

- Branch: `415-generic-content-backed-capture`
- Baseline HEAD: `dfda397e feat: migrate tcm first coverage core cutover (#481)`
- Initial dirty state: `specs/415-generic-content-backed-capture/` untracked as the active spec artifact set.
- Spec 414 dependency: treated as completed/validated context only; no files under `specs/414-tcm-first-coverage-core-cutover/` were modified.
- Existing equivalent check: no existing `tenant_configuration_resources` or `tenant_configuration_resource_evidence` tables/models were present before implementation.

## Implementation Scope

- Added `tenant_configuration_resources` and `tenant_configuration_resource_evidence` persistence with `workspace_id`, `managed_environment_id`, `provider_connection_id`, and `resource_type_id`; no `tenant_id` fields.
- Added PostgreSQL composite scope constraints for managed environment/workspace, provider connection/workspace/environment, evidence/resource/provider/type, evidence/latest-resource/provider/type, and evidence/operation-run/workspace/environment integrity while keeping SQLite-compatible migrations for tests.
- Added a database-level `provider_connections(managed_environment_id, workspace_id)` binding so provider connections cannot be attached to a managed environment from another workspace.
- Added a scoped `latest_evidence_id` foreign key so a resource can only point at evidence for the same resource, workspace, managed environment, provider connection, and resource type.
- Added models and factories for concrete resources and append-only evidence.
- Added bounded capture outcomes only: `captured`, `capture_blocked_missing_contract`, `capture_blocked_permission`, `capture_blocked_beta`, `capture_blocked_unsupported`, `capture_failed`.
- Added contract resolution through `GraphContractRegistry` with explicit mappings only:
  - `deviceAndAppManagementAssignmentFilter` -> `assignmentFilter` -> captured when Graph succeeds.
  - `notificationMessageTemplate` -> `notificationMessageTemplate` -> captured when Graph succeeds.
  - `roleScopeTag` -> beta-backed and blocked by default.
  - Other initial TCM types remain `capture_blocked_missing_contract` until explicit contracts are introduced.
- Added deterministic normalization, configured volatile-field stripping, SHA-256 payload hashes, and recursive secret/token/header/cookie redaction for metadata/context.
- Added `tenant_configuration.capture` operation type/catalog label and a queued capture job.
- Added defense-in-depth scope validation before remote provider work: the job resolves provider connections only inside the OperationRun workspace/environment, and the capture service validates tenant/provider/run/context scope before calling the provider gateway.

## Capture Eligibility Matrix

| Canonical type | Source class | Source contract key | Default outcome |
| --- | --- | --- | --- |
| `deviceAndAppManagementAssignmentFilter` | `tcm` | `assignmentFilter` | `captured` when Graph succeeds |
| `deviceEnrollmentLimitRestriction` | `tcm` | none | `capture_blocked_missing_contract` |
| `deviceEnrollmentPlatformRestriction` | `tcm` | none | `capture_blocked_missing_contract` |
| `deviceEnrollmentStatusPageWindows10` | `tcm` | none | `capture_blocked_missing_contract` |
| `appProtectionPolicyAndroid` | `tcm` | none | `capture_blocked_missing_contract` |
| `appProtectionPolicyiOS` | `tcm` | none | `capture_blocked_missing_contract` |
| `notificationMessageTemplate` | `graph_v1_fallback` | `notificationMessageTemplate` | `captured` when Graph succeeds |
| `roleScopeTag` | `graph_beta_experimental` | `roleScopeTag` | `capture_blocked_beta` unless beta capture is explicitly enabled |

## Operation And RBAC

- Start capability: existing `Capabilities::EVIDENCE_MANAGE`.
- Authorization behavior:
  - non-member and excluded explicit environment entitlement -> 404.
  - workspace member without capability / readonly -> 403.
  - same workspace/environment/provider connection -> allowed.
- OperationRun behavior:
  - creates/reuses `tenant_configuration.capture` queued runs from idempotent provider/resource-type inputs.
  - remote/provider work is queued through the central OperationRun lifecycle.
  - the central queued execution gate validates `provider_connection_id` against both the OperationRun workspace and managed environment before provider work is allowed.
  - the capture job and capture service also fail closed before Graph access when the provider connection, managed environment, OperationRun columns, or OperationRun target scope do not match.
  - summary keys are existing canonical keys only: `total`, `processed`, `succeeded`, `skipped`, `failed`, `errors_recorded`.
  - raw payloads and Graph credential options are not written into OperationRun context or audit metadata.
  - exception messages are reduced to bounded `RunFailureSanitizer` reason codes for resource outcomes; dispatch/job failure audit messages are sanitized before persistence.
- Audit action IDs used:
  - `tenant_configuration.capture.started`
  - `tenant_configuration.capture.completed`
  - `tenant_configuration.capture.failed`

## Product Surface

- No rendered UI surface changed.
- No Filament resources, pages, widgets, relation managers, routes, panel providers, navigation entries, views, assets, review/report/evidence pages, or restore readiness surfaces were added or modified.
- Browser proof: `N/A - no rendered UI surface changed`.
- Human Product Sanity: `N/A - no product surface changed`.
- Visible complexity outcome: unchanged.
- Product Surface exceptions: none.
- No completed historical spec was rewritten or stripped of validation/task/review history.

## Filament V5 Contract

- Livewire v4.0+ compliance: no Livewire/Filament runtime UI code changed; application package baseline remains Livewire v4.
- Provider registration location: unchanged; Laravel 11+/12 panel provider registration remains `bootstrap/providers.php`.
- Global search: no globally searchable resource was added; `N/A`.
- Destructive/high-impact actions: no UI action added; queued capture start is backend service only and RBAC-gated.
- Asset strategy: no assets registered; no `filament:assets` requirement from this spec.
- Testing plan: Unit/Feature/PostgreSQL lanes only; no Livewire page/widget/relation-manager/action tests required.

## Files Changed

- Persistence:
  - `apps/platform/database/migrations/2026_06_25_000415_create_tenant_configuration_capture_tables.php`
  - `apps/platform/app/Models/TenantConfigurationResource.php`
  - `apps/platform/app/Models/TenantConfigurationResourceEvidence.php`
  - `apps/platform/database/factories/TenantConfigurationResourceFactory.php`
  - `apps/platform/database/factories/TenantConfigurationResourceEvidenceFactory.php`
- Capture support/services:
  - `apps/platform/app/Support/TenantConfiguration/CaptureOutcome.php`
  - `apps/platform/app/Services/TenantConfiguration/CoverageSourceContractResolver.php`
  - `apps/platform/app/Services/TenantConfiguration/CoverageSourceContractDecision.php`
  - `apps/platform/app/Services/TenantConfiguration/GenericPayloadNormalizer.php`
  - `apps/platform/app/Services/TenantConfiguration/CoveragePayloadRedactor.php`
  - `apps/platform/app/Services/TenantConfiguration/CoverageCaptureOutcomeSummarizer.php`
  - `apps/platform/app/Services/TenantConfiguration/CoverageResourceUpserter.php`
  - `apps/platform/app/Services/TenantConfiguration/CoverageEvidenceWriter.php`
  - `apps/platform/app/Services/TenantConfiguration/GenericContentEvidenceCaptureService.php`
  - `apps/platform/app/Services/TenantConfiguration/StartTenantConfigurationCapture.php`
  - `apps/platform/app/Jobs/TenantConfiguration/CaptureTenantConfigurationEvidenceJob.php`
- Operation/audit registry:
  - `apps/platform/app/Services/Operations/QueuedExecutionLegitimacyGate.php`
  - `apps/platform/app/Support/OperationRunType.php`
  - `apps/platform/app/Support/OperationCatalog.php`
  - `apps/platform/app/Support/Audit/AuditActionId.php`
- Tests:
  - `apps/platform/tests/Unit/Support/TenantConfiguration/Spec415CoverageSourceContractResolverTest.php`
  - `apps/platform/tests/Unit/Support/TenantConfiguration/Spec415GenericPayloadNormalizerTest.php`
  - `apps/platform/tests/Unit/Support/TenantConfiguration/Spec415CoverageRedactionTest.php`
  - `apps/platform/tests/Unit/Support/TenantConfiguration/Spec415CoverageCaptureOutcomeTest.php`
  - `apps/platform/tests/Unit/Support/TenantConfiguration/Spec415CoverageCaptureOperationRunSummaryTest.php`
  - `apps/platform/tests/Feature/TenantConfiguration/Spec415CoverageEvidencePersistenceTest.php`
  - `apps/platform/tests/Feature/TenantConfiguration/Spec415ProviderConnectionScopeTest.php`
  - `apps/platform/tests/Feature/TenantConfiguration/Spec415CoverageCaptureAuthorizationTest.php`
  - `apps/platform/tests/Feature/TenantConfiguration/Spec415CoverageCaptureOperationRunTest.php`
  - `apps/platform/tests/Feature/TenantConfiguration/Spec415GenericContentBackedCaptureTest.php`
  - `apps/platform/tests/Feature/TenantConfiguration/Spec415NoLegacyNoUiActivationTest.php`
  - `apps/platform/tests/Unit/Operations/QueuedExecutionLegitimacyGateTest.php`

## Validation

- `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` -> pass.
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/TenantConfiguration` -> 22 passed, 69 assertions.
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Operations/QueuedExecutionLegitimacyGateTest.php` -> 12 passed, 106 assertions.
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantConfiguration/Spec415GenericContentBackedCaptureTest.php` -> 4 passed, 50 assertions.
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantConfiguration` -> 24 passed, 7 skipped, 129 assertions.
- `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest -c phpunit.pgsql.xml tests/Feature/TenantConfiguration` -> 31 passed, 141 assertions.
- PostgreSQL migration smoke on `tenantatlas_testing`: `migrate:fresh --force` -> pass; targeted rollback of `2026_06_25_000415_create_tenant_configuration_capture_tables.php` -> pass; final `migrate:fresh --force` -> pass.
- PostgreSQL latest-evidence lifecycle coverage: scoped pointer mismatch is rejected, same-scope pointer is accepted, and resource deletion cascades linked evidence without constraint failure.
- `git diff --check` -> pass.
- Additional untracked-file whitespace scan -> pass.

## Deployment Impact

- Migrations: yes, adds two new tenant configuration capture tables with PostgreSQL JSONB/check constraints and composite scope foreign keys; also adds a provider-connection environment/workspace binding constraint on the existing `provider_connections` table.
- Queue worker: yes, new queued capture job.
- Environment variables: no new variables.
- Scheduler: no change.
- Storage/volumes: no change.
- Assets: no change; `filament:assets` not required by this spec.
- Staging/production: run migrations before enabling any future caller; ensure queue workers are running; validate staging data has no existing provider-connection workspace/environment mismatches before production promotion.

## Deferred Work

- Add explicit source contracts for the remaining TCM-backed resource types before claiming captured evidence for them.
- Add any UI start surface only through a future UI-affecting spec with Product Surface review.