Plan United's PocketBase-only replatform

[nathanhruby]

Destination

Produce a decision-complete, implementation-ready migration plan for a fresh implementation from main that replaces Gin, S3/KMS, and Redis with one single-writer PocketBase server. PocketBase will own group-scoped authentication, encrypted versioned state, and configurable lock leases while preserving the Terraform HTTP backend contract.

Notes

• Planning only: this map resolves decisions and stops before implementation.
• Do not reuse code from the nrh/plan-two branch. It is non-normative evidence only.
• Existing S3 state is not imported by United; users migrate it by switching Terraform backends.
• Production topology is one active process and one writer. Host infrastructure owns durable storage, backups, availability, and replication outside the application.
• Each group identifies one state namespace and has one shared Terraform credential.
• Human PocketBase users belong to groups with roles and manage access according to those roles.
• Successful writes create immutable state versions. DELETE tombstones the logical state.
• State documents use per-group data keys wrapped by a runtime master key.
• State locks are transactional leases with an operator-configurable expiry.
• Treat paths, credentials, key material, state documents, and lock behavior as security- and data-sensitive.

Decisions so far

• Document Terraform HTTP backend compatibility requirements: preserve the documented raw-state and locking wire contract, lock-ID propagation, accepted statuses, retries, Basic Auth boundary, and serialized mutation behavior; S3 migration is separate.
• Establish PocketBase transaction and file consistency guarantees: SQLite record transactions serialize and atomically commit database writes, but files are a separate failure domain requiring immutable objects, metadata-authoritative publication, fencing, and reconciliation.
• Establish PocketBase authentication and authorization extension points: use human PocketBase users with relation-backed memberships plus one non-session group credential validated natively in custom Terraform request handling.
• Define group roles and membership lifecycle: use invite-only owner/member memberships with explicit acceptance, at least one active owner, owner-only administration and raw-state access, operator suspension and exceptional recovery, and recoverable pending retirement.
• Define the shared Terraform credential lifecycle: automatically issue one immutable route-bound Basic Auth identity per group with a one-time 32-byte secret, immediate no-overlap rotation, reversible disabling, group-scoped locks, generic auth failures, and atomic operator-only lifecycle audit events.
• Define logical-state deletion, retention, and path reuse: reserve each state lineage permanently, use explicit owner restoration and uniform query-driven per-version retention, purge metadata-authoritatively without manual acceleration, and never modify state documents or renumber surviving history.
• Define group retirement and retained-state disposition: use dynamic retention-based recovery followed by automatic metadata-authoritative purge, leaving only reserved identities, lifecycle timestamps, and permanent operator audit history.

Not yet specified

• The exact crash-safe publication, missing-file recovery, and lease-fencing experiments; these become precise after the persistence and lock designs settle.
• The operational backup, restore, and disaster-recovery validation that binds PocketBase data to its runtime master key and prevents restored backups from silently reactivating retired groups; this depends on persistence and key-lifecycle decisions.
• State-size limits and resource controls; these depend on the persistence decision.
• The final implementation module boundaries and execution slicing; these follow the completed domain, persistence, protocol, and rollout decisions.

Out of scope

• Reusing or merging implementation code from nrh/plan-two.
• Automatic S3 import, dual reads or writes, and in-application migration of existing state.
• Active-active serving, application-level clustering, leader election, and replication.
• Provisioning the host-level durable volume, backup system, or replication mechanism.
• Step-up authentication or MFA for credential lifecycle operations in the initial replatform.
• Implementing the migration while this map is being resolved.