TenantAtlas/specs/405-json-to-jsonb-data-layer-hardening/tasks.md

# Tasks: Spec 405 - JSON-to-JSONB Data-layer Hardening

**Input**: `specs/405-json-to-jsonb-data-layer-hardening/spec.md`, `plan.md`, `checklists/requirements.md`, user-provided Spec 405 draft, Spec 400 P1 data-layer risk, related Specs 401-404 proof context, live PostgreSQL schema inspection, and repo truth.

**Tests**: Required. This is a runtime data-layer change. Use Pest 4, PostgreSQL lane for JSONB/migration/index proof, focused feature tests for domain behavior, and focused browser proof for existing payload-backed rendered surfaces.

## Test Governance Checklist

- [x] Lane assignment is `PostgreSQL + Feature + focused Browser`, with no full browser/runtime audit claim.
- [x] New or changed tests stay in the smallest honest family; browser coverage is explicit and focused.
- [x] Shared helpers, factories, seeds, fixtures, workspace/member context, and provider setup stay cheap by default or explicitly opt in.
- [x] Planned validation commands cover the change without broad unrelated suite cost.
- [x] Browser proof is required for representative existing payload-backed surfaces even though no UI file changes.
- [x] Human Product Sanity confirms unchanged trust semantics and no raw payload exposure.
- [x] Any material budget, baseline, trend, or escalation note is recorded in `implementation-report.md`.

## Phase 1: Preparation And Safety

**Purpose**: Establish repo safety, read the active package, and prevent scope drift.

- [x] T001 Read `specs/405-json-to-jsonb-data-layer-hardening/spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md`.
- [x] T002 Record current branch, HEAD, dirty state, tracked changed files, untracked files, and `git diff --check` in `specs/405-json-to-jsonb-data-layer-hardening/implementation-report.md`.
- [x] T003 Re-read `AGENTS.md`, `.specify/memory/constitution.md`, `docs/ai-coding-rules.md`, `docs/architecture-guidelines.md`, `docs/performance-guidelines.md`, `docs/security-guidelines.md`, `docs/testing-guidelines.md`, and `docs/product/standards/product-surface-contract.md`.
- [x] T004 Re-read Specs 400, 401, 402, 403, and 404 implementation reports as read-only context and record their gate results/conditions in `implementation-report.md`.
- [x] T005 Confirm no UI surfaces, routes, navigation, product concepts, authorization model, lifecycle semantics, provider semantics, normalized replacement tables, or completed specs will be edited.
- [x] T006 Create `specs/405-json-to-jsonb-data-layer-hardening/implementation-report.md` with sections A through P from `spec.md`.

## Phase 2: Schema Inventory And Usage Mapping

**Purpose**: Prove every JSON column decision is intentional before migration work begins.

- [x] T007 Query PostgreSQL `information_schema.columns` for all live `json` and `jsonb` columns and add each row to the JSON/JSONB Inventory Matrix in `implementation-report.md`.
- [x] T008 For every inventory row, add row count, null count, nullable state, default, indexes, constraints, foreign-key context where relevant, table-size signal, lock/runtime-risk assessment, and direct-vs-online migration decision.
- [x] T009 [P] Map model casts and model ownership for alert, audit, backup, restore, policy, provider/environment, settings, review/report, evidence, finding, and OperationRun-related rows in `apps/platform/app/Models/`.
- [x] T010 [P] Map factory and fixture usage for inventoried columns under `apps/platform/database/factories/` and `apps/platform/tests/`.
- [x] T011 [P] Map query usage for JSON paths, `whereJson*`, `->` key predicates, raw SQL JSON expressions, and JSONB index candidates under `apps/platform/app/` and `apps/platform/tests/`.
- [x] T012 [P] Map rendered/regression consumers for evidence, OperationRun, provider, backup, restore, review pack, stored report, audit, and alert payloads under `apps/platform/app/Filament/` and `apps/platform/resources/views/`.
- [x] T013 Classify each inventory row as `CONVERT`, `KEEP_JSON`, `ALREADY_JSONB`, `DEPRECATED`, or `DECISION_REQUIRED` with risk `P0`, `P1`, `P2`, `P3`, or `None`.
- [x] T014 Stop before migrations if any live `json` column lacks classification, reason, and risk.

## Phase 3: User Story 1 - Inventory and classify structured payload columns (Priority: P1)

**Goal**: Deliver a complete schema and usage matrix that lets reviewers verify every storage decision.

**Independent Test**: The inventory matrix includes every live PostgreSQL `json` and `jsonb` column exactly once and every `json` column has an explicit action/reason/risk.

### Tests for User Story 1

- [x] T015 [P] [US1] Add a PostgreSQL schema inventory assertion for live JSON/JSONB columns in `apps/platform/tests/Feature/Database/JsonbDataLayerHardeningTest.php`.
- [x] T016 [P] [US1] Add a report-coverage assertion or manual checklist entry ensuring every live `json` column is represented in `specs/405-json-to-jsonb-data-layer-hardening/implementation-report.md`.

### Implementation for User Story 1

- [x] T017 [US1] Complete implementation report section D with the JSON/JSONB Inventory Matrix.
- [x] T018 [US1] Mark high-risk columns for policy snapshots, backup payloads, restore previews/results, audit metadata, provider permission/readiness details, review/report payloads, and alert delivery payloads as `CONVERT` or explicitly justified non-conversions.
- [x] T019 [US1] Mark unclear ownership/product-decision columns as `DECISION_REQUIRED` instead of converting by assumption.
- [x] T020 [US1] Record existing `ALREADY_JSONB` trust-layer columns so implementation reviewers can verify consistency and avoid duplicate work.

## Phase 4: User Story 2 - Convert selected trust-layer payloads safely (Priority: P1)

**Goal**: Convert selected existing `json` payload columns to `jsonb` while preserving semantic payload content and behavior.

**Independent Test**: Migrations run on PostgreSQL, selected columns become `jsonb`, semantic payload checks pass, null/default behavior is preserved, and rollback limitations are documented.

### Tests for User Story 2

- [x] T021 [P] [US2] Add PostgreSQL migration/type assertions for every converted column in `apps/platform/tests/Feature/Database/JsonbDataLayerHardeningTest.php`.
- [x] T022 [P] [US2] Add semantic payload preservation tests with non-sensitive samples for policy, backup, restore, audit, provider/environment, settings, and alert/report payload categories in `apps/platform/tests/Feature/Database/JsonbDataLayerHardeningTest.php`.
- [x] T023 [P] [US2] Add model read/write tests for converted columns whose casts or factories require explicit proof in `apps/platform/tests/Feature/Database/JsonbDataLayerHardeningTest.php`.
- [x] T024 [P] [US2] Add query-path tests for any changed JSON key query or new JSONB index in `apps/platform/tests/Feature/Database/JsonbDataLayerHardeningTest.php`.

### Implementation for User Story 2

- [x] T025 [US2] Create one or more focused migrations under `apps/platform/database/migrations/` converting only `CONVERT` columns to `jsonb`.
- [x] T026 [US2] Preserve nullability, defaults, and constraints in each conversion migration.
- [x] T027 [US2] Add rollback SQL or explicit rollback limitations to each conversion migration.
- [x] T028 [US2] Add justified JSONB indexes only where an existing query path is documented in `implementation-report.md`.
- [x] T029 [US2] Update model casts in `apps/platform/app/Models/` only where tests prove current behavior needs a cast adjustment.
- [x] T030 [US2] Update query code only where tests prove textual JSON assumptions break after conversion.
- [x] T031 [US2] Update factories or fixtures only where required by the new targeted tests and avoid broad seed/default changes.
- [x] T032 [US2] Complete implementation report sections E, F, G, and I with migrations, indexes, runtime changes, and data validation.

## Phase 5: User Story 3 - Prove existing behavior and report readiness honestly (Priority: P2)

**Goal**: Prove the conversion did not regress existing trust-layer behavior and produce a gate result.

**Independent Test**: Targeted domain tests, PostgreSQL tests, focused browser proof, and staging-like validation status are recorded; final report uses `PASS`, `PASS WITH CONDITIONS`, or `FAIL` honestly.

### Tests for User Story 3

- [x] T033 [P] [US3] Prove evidence/currentness regression paths with existing focused browser smoke and Spec405 storage tests; no converted evidence/report/review columns required new feature tests.
- [x] T034 [P] [US3] Add OperationRun/audit regression proof for converted audit and OperationRun-adjacent payload paths in the focused Spec405 test plus browser proof.
- [x] T035 [P] [US3] Add provider readiness/freshness/permission regression proof for converted provider/environment payload paths in the focused Spec405 test plus browser proof.
- [x] T036 [P] [US3] Add backup payload regression proof in the focused Spec405 test plus browser proof.
- [x] T037 [P] [US3] Add restore preview/result payload regression proof in the focused Spec405 test plus browser proof.
- [x] T038 [P] [US3] Prove review pack, stored report, management-report PDF/runtime, and customer-output regression paths with existing focused browser smoke; those columns were already `jsonb`.
- [x] T039 [P] [US3] Confirm no authorization/scope query path changed beyond the JSONB-safe `BackupItem` scope; covered by targeted tests and no RBAC edits.
- [x] T040 [US3] Run focused existing browser smoke tests for representative existing payload-backed surfaces; no new UI smoke artifact was needed because no rendered surface changed.

### Implementation for User Story 3

- [x] T041 [US3] Browser-proof Evidence Overview or evidence anchor rendering after conversion and record route, actor, workspace/environment, expected state, actual state, and console/runtime result.
- [x] T042 [US3] Browser-proof Monitoring -> Operations or OperationRun detail payload-backed rendering after conversion.
- [x] T043 [US3] Browser-proof provider detail/readiness/freshness payload-backed rendering after conversion.
- [x] T044 [US3] Browser-proof backup or restore payload-backed proof rendering after conversion.
- [x] T045 [US3] Browser-proof Review Pack, Stored Report, management-report PDF/runtime, or report receipt payload-backed rendering after conversion.
- [x] T046 [US3] Record Human Product Sanity result in `implementation-report.md`: no stronger proof claims, no raw payload exposure, unchanged current/released/failed/partial semantics.
- [x] T047 [US3] Run local PostgreSQL migration validation and record migration success, row counts, null counts, converted types, and sample semantic checks in `implementation-report.md`.
- [x] T048 [US3] Run rollback validation in a disposable local/test database where safe, or record exact rollback limitation and risk.
- [x] T049 [US3] Run staging-like PostgreSQL validation if accessible and record migration/app boot/tests/browser/payload-read-write results.
- [x] T050 [US3] If staging/Dokploy validation is not accessible, record the blocker and ensure final gate result is no stronger than `PASS WITH CONDITIONS`.
- [x] T051 [US3] Complete implementation report sections H, J, K, L, M, N, O, and P.

## Phase 6: Final Validation And Close-Out

**Purpose**: Confirm the package is ready for review and no unrelated work entered the slice.

- [x] T052 Run `git diff --check` from repo root and record result in `implementation-report.md`.
- [x] T053 Run project formatting for changed PHP files according to repo convention and record result.
- [x] T054 Run focused PostgreSQL Spec405 tests and record exact command/results.
- [x] T055 Run targeted feature/domain regression tests and record exact command/results.
- [x] T056 Run focused browser proof and record exact command/results, or exact blocker without claiming browser proof.
- [x] T057 Verify reports, logs, screenshots, and fixtures do not include secrets, tokens, raw credential payloads, sensitive raw provider payloads, or customer-sensitive raw payloads.
- [x] T058 Record final dirty state, tracked changed files, and untracked files in `implementation-report.md`.
- [x] T059 Confirm no completed historical specs were rewritten or stripped of close-out/validation/task/smoke/browser history.
- [x] T060 Confirm `implementation-report.md` and the final response state Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, tests/browser result, deployment impact, visible complexity outcome, no completed-spec rewrite assertion, and explicit application implementation status.

## Non-Goals Checklist

- [x] NT001 Do not add product features, report templates, navigation, UI surfaces, actions, modals, forms, tables, or customer output.
- [x] NT002 Do not change authorization model, roles, capabilities, policies, or global search posture except to fix a direct regression caused by this conversion and already covered by the spec.
- [x] NT003 Do not add governance lifecycle, retention, export, delete, hold, or artifact-state semantics.
- [x] NT004 Do not add new persisted entities/tables, normalized replacement tables, status families, taxonomies, provider frameworks, or broad abstractions.
- [x] NT005 Do not add speculative indexes.
- [x] NT006 Do not rename payload keys or reinterpret payload meaning.
- [x] NT007 Do not print or commit sensitive raw payload samples.
- [x] NT008 Do not rewrite completed specs or remove historical implementation evidence.

## Dependencies And Execution Order

- Phase 1 must complete before any migration or runtime edit.
- Phase 2 inventory and classification must complete before Phase 4 conversion.
- User Story 1 is the required MVP and blocks migration implementation.
- User Story 2 depends on completed classification and creates the conversion.
- User Story 3 depends on converted columns and proves behavior/readiness.
- Final validation depends on all in-scope tests, browser proof, and implementation report completion.

## Parallel Execution Examples

- After T007/T008, T009 through T012 can run in parallel because they inspect different surfaces.
- T021 through T024 can be drafted in parallel after conversion decisions are known.
- T033 through T039 can run in parallel by domain test family after migrations exist.
- T041 through T045 can run as separate focused browser paths if fixture setup is independent.

## Recommended Implementation Strategy

Deliver User Story 1 first and stop if the inventory is incomplete or reveals unresolved product/schema decisions. Then convert the smallest justified group of high-risk trust-layer columns, prove semantic preservation, and add only the narrow tests/browser proof required for the changed columns. Treat staging validation as a release gate: if unavailable, report `PASS WITH CONDITIONS`, not full readiness.