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

• Lane assignment is PostgreSQL + Feature + focused Browser, with no full browser/runtime audit claim.
• New or changed tests stay in the smallest honest family; browser coverage is explicit and focused.
• Shared helpers, factories, seeds, fixtures, workspace/member context, and provider setup stay cheap by default or explicitly opt in.
• Planned validation commands cover the change without broad unrelated suite cost.
• Browser proof is required for representative existing payload-backed surfaces even though no UI file changes.
• Human Product Sanity confirms unchanged trust semantics and no raw payload exposure.
• 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.

• T001 Read specs/405-json-to-jsonb-data-layer-hardening/spec.md, plan.md, tasks.md, and checklists/requirements.md.
• 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.
• 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.
• 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.
• T005 Confirm no UI surfaces, routes, navigation, product concepts, authorization model, lifecycle semantics, provider semantics, normalized replacement tables, or completed specs will be edited.
• 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.

• 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.
• 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.
• 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/.
• T010 [P] Map factory and fixture usage for inventoried columns under apps/platform/database/factories/ and apps/platform/tests/.
• 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/.
• 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/.
• T013 Classify each inventory row as CONVERT, KEEP_JSON, ALREADY_JSONB, DEPRECATED, or DECISION_REQUIRED with risk P0, P1, P2, P3, or None.
• 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

• T015 [P] [US1] Add a PostgreSQL schema inventory assertion for live JSON/JSONB columns in apps/platform/tests/Feature/Database/JsonbDataLayerHardeningTest.php.
• 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

• T017 [US1] Complete implementation report section D with the JSON/JSONB Inventory Matrix.
• 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.
• T019 [US1] Mark unclear ownership/product-decision columns as DECISION_REQUIRED instead of converting by assumption.
• 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

• T021 [P] [US2] Add PostgreSQL migration/type assertions for every converted column in apps/platform/tests/Feature/Database/JsonbDataLayerHardeningTest.php.
• 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.
• 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.
• 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

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

• 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.
• T034 [P] [US3] Add OperationRun/audit regression proof for converted audit and OperationRun-adjacent payload paths in the focused Spec405 test plus browser proof.
• T035 [P] [US3] Add provider readiness/freshness/permission regression proof for converted provider/environment payload paths in the focused Spec405 test plus browser proof.
• T036 [P] [US3] Add backup payload regression proof in the focused Spec405 test plus browser proof.
• T037 [P] [US3] Add restore preview/result payload regression proof in the focused Spec405 test plus browser proof.
• 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.
• T039 [P] [US3] Confirm no authorization/scope query path changed beyond the JSONB-safe BackupItem scope; covered by targeted tests and no RBAC edits.
• 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

• 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.
• T042 [US3] Browser-proof Monitoring -> Operations or OperationRun detail payload-backed rendering after conversion.
• T043 [US3] Browser-proof provider detail/readiness/freshness payload-backed rendering after conversion.
• T044 [US3] Browser-proof backup or restore payload-backed proof rendering after conversion.
• T045 [US3] Browser-proof Review Pack, Stored Report, management-report PDF/runtime, or report receipt payload-backed rendering after conversion.
• 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.
• 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.
• T048 [US3] Run rollback validation in a disposable local/test database where safe, or record exact rollback limitation and risk.
• T049 [US3] Run staging-like PostgreSQL validation if accessible and record migration/app boot/tests/browser/payload-read-write results.
• T050 [US3] If staging/Dokploy validation is not accessible, record the blocker and ensure final gate result is no stronger than PASS WITH CONDITIONS.
• 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.

• T052 Run git diff --check from repo root and record result in implementation-report.md.
• T053 Run project formatting for changed PHP files according to repo convention and record result.
• T054 Run focused PostgreSQL Spec405 tests and record exact command/results.
• T055 Run targeted feature/domain regression tests and record exact command/results.
• T056 Run focused browser proof and record exact command/results, or exact blocker without claiming browser proof.
• T057 Verify reports, logs, screenshots, and fixtures do not include secrets, tokens, raw credential payloads, sensitive raw provider payloads, or customer-sensitive raw payloads.
• T058 Record final dirty state, tracked changed files, and untracked files in implementation-report.md.
• T059 Confirm no completed historical specs were rewritten or stripped of close-out/validation/task/smoke/browser history.
• 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

• NT001 Do not add product features, report templates, navigation, UI surfaces, actions, modals, forms, tables, or customer output.
• 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.
• NT003 Do not add governance lifecycle, retention, export, delete, hold, or artifact-state semantics.
• NT004 Do not add new persisted entities/tables, normalized replacement tables, status families, taxonomies, provider frameworks, or broad abstractions.
• NT005 Do not add speculative indexes.
• NT006 Do not rename payload keys or reinterpret payload meaning.
• NT007 Do not print or commit sensitive raw payload samples.
• 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.