Architecture: deepen platform lifecycle seams

[ElbertePlinio]

Pickforge Platform architecture master plan

Goal

Deepen the highest-risk shared platform behavior without changing product UI, publishing identity, migration history, or package layout by assumption.

Why

Recent checkout/deletion and hosted-router work spans durable state, package implementation, Deno adapters, and release tooling. The priority is to concentrate policy behind testable interfaces, preserve release compatibility, and reduce lockstep choreography.

Top priority

PR 1 — checkout lifecycle local-Postgres interface. Replace lifecycle policy duplicated in the billing test fake with characterization against the durable lifecycle. This is the prerequisite for safely changing checkout/deletion orchestration.

Architecture constraints

• Credit ledger remains the balance source of truth.
• Checkout/deletion durable state remains in Supabase; authentication identity is deleted last.
• Preserve idempotency, refund recovery, tombstones, and existing public package consumers.
• Use additive forward migrations only; never renumber/rewrite history.
• Keep packages UI-free. Shared update presentation is out of scope.
• Keep release artifacts, signatures, and latest.json mutually compatible.
• Do not introduce a new published package or generic persistence layer without Pro stack as platform packages: billing, sync, flags, shared edge utilities #10 approval and two real adapters.

Scope / acceptance checklist

• Lifecycle contract cases run through local Postgres and cover replay, deletion races, refunds, cleanup, and finalization.
• Checkout/deletion orchestration has one accountable owner; Deno adapters retain only request/environment/response work.
• Sync last-writer-wins decision is one durable operation with real concurrent push/push and push/delete proof.
• Router work is durably claimed before provider invocation; retries/replays do not duplicate provider work or debits.
• AppImage repair is success-or-no-change for artifact, signature, and updater feed.
• Touched Deno adapters are checked with their import maps; published consumer compatibility is proven before removing exports.
• Every SQL change is forward-only and covered by local database validation.

Dependency-ordered PR plan

PR 1 — Lifecycle persistence characterization

• Depends on: none
• Touches: billing tests; lifecycle database tests/fixtures
• Prove: production billing behavior and durable lifecycle agree for races, replays, recovery, and cleanup.
• Validation: focused billing test; PICKFORGE_ALLOW_LOCAL_DB_TESTS=1 bun run test:supabase; bun run typecheck.
• Link: pending

PR 2 — Consolidate checkout/deletion orchestration

• Depends on: PR 1; Pro stack as platform packages: billing, sync, flags, shared edge utilities #10 approval for any published export placement; chore: reconcile hosted Supabase migration history #35 if a forward migration is necessary
• Touches: billing, edge-shared, checkout/delete/webhook Deno adapters, possibly one forward migration
• Prove: lifecycle ordering is hidden behind one owner; no duplicate credit/refund; existing pinned Deno consumers remain release-compatible.
• Validation: local lifecycle suite; focused billing and edge-shared suites; touched Deno import-map checks; typecheck and package build.
• Link: pending

PR 3 — Durable sync last-writer-wins

• Depends on: chore: reconcile hosted Supabase migration history #35 migration coordination
• Touches: sync package, one forward migration, local database tests
• Prove: one durable decision returns compatible written/stale results under concurrent writes and tombstones.
• Validation: focused sync tests; local Supabase suite; database advisor check; typecheck.
• Link: pending

PR 4 — Durable router attempt ownership

• Depends on: chore: reconcile hosted Supabase migration history #35 migration coordination; Pro stack as platform packages: billing, sync, flags, shared edge utilities #10 review if an export moves
• Touches: edge-shared, operator-router Deno adapter, one forward migration, local database tests
• Prove: one same-key provider invocation and debit, resilient replay/recovery, and compatibility with already-completed ledger rows.
• Validation: focused router tests; local database concurrency cases; operator-router Deno import-map check; typecheck.
• Link: pending

PR 5 — Transactional AppImage repair

• Depends on: none
• Touches: tauri-release implementation and tests
• Prove: signer/feed/commit failures leave the complete prior release set unchanged.
• Validation: focused release tests; typecheck; tauri-release build.
• Link: pending

Existing issue coordination

• Pro stack as platform packages: billing, sync, flags, shared edge utilities #10: package direction and published export placement.
• Migrate npm publishing to trusted publishing (OIDC) — kill NPM_TOKEN rotation #23: trusted publishing; do not change identity, provenance, or credentials.
• chore: reconcile hosted Supabase migration history #35: migration history; additive forward migrations only.
• Standardize the in-app update dialog across Studio apps #36: shared update dialog; excluded from this plan.

Non-goals

• No update UI work.
• No remote flags or rollout platform.
• No package explosion, shared fake package, generic repository layer, or migration-history rewrite.
• No publishing-credential work.

No-feature-flag decision

No feature flag is planned. These slices are implementation integrity, characterization, durable-state, and release-compatibility work rather than incomplete user-facing capability. Each slice must be fully validated before its release; do not merge a partially enabled behavior behind a new flag.

Audit commit snapshot

358aa6b2bb2a2a2a34be44ec3f837f57f3ae59a9 on main.

Current status

Planned

Next action

Open this as the master tracking issue, link #10/#23/#35/#36, then start PR 1 with local-Postgres lifecycle characterization.

[ElbertePlinio]

CAND-1 progress: PR 1 (checkout lifecycle local-Postgres interface) is up.

PR #47 adds a contract-test lane (packages/billing/test/checkout-lifecycle.contract.test.ts) that runs the production processStripeEvent/getCreditBalanceCents billing policy against the real checkout_lifecycle_* SQL RPCs in supabase/migrations/20260712193633_checkout_deletion_lifecycle.sql on a local Supabase Postgres, with only Stripe mocked. Covers concurrent completion/deletion races, missing vs. fenced users, registered/unregistered sessions, refund states (partial/pending/failed/canceled/succeeded), crash-window recovery, and replayed events.

• Skips cleanly (clear log message) when Postgres/Supabase isn't reachable, so plain bun test/CI's check job stay green.
• Runs for real via bun run test:supabase in CI's database job; verified locally end-to-end (supabase db reset + test:supabase + security advisors), all green.
• Removed the lifecycle-policy cases now duplicated in the MemorySupabase billing fake (billing.test.ts), keeping the fake and its fast non-lifecycle unit tests.
• No new migrations; no shared fake or provider-neutral repository interface introduced.

PR 2 (consolidate checkout/deletion orchestration) is now unblocked.

[ElbertePlinio]

CAND-2 progress: PR 2 slice 1 (fence/register/expire ownership) is up.

PR #48 moves the checkout_lifecycle_is_deletion_fenced / checkout_lifecycle_register_session / checkout_lifecycle_mark_expired RPC calls out of create-credit-checkout (which was hand-rolling all three) into edge-shared, exported next to createRegisteredCheckoutSession/createDeleteAccountHandler as isCheckoutDeletionFenced, registerCheckoutSession, and markCheckoutSessionExpired. create-credit-checkout now only wires those exports into createRegisteredCheckoutSession's DI callbacks — it no longer owns any RPC name or call order.

• createRegisteredCheckoutSession's public signature and choreography are unchanged, so no export removal and every existing contract/unit test passes unmodified.
• Bumped @pickforge/* 0.10.0 -> 0.11.0 and re-pinned every Deno function's npm: import (existing publish-then-pin convention).
• Added direct unit tests for the three new/exported functions (success, RPC error, invalid-result-shape).
• Validated: bun run typecheck, bun run test (352/352), bun run build; supabase db start + PICKFORGE_ALLOW_LOCAL_DB_TESTS=1 bun run test:supabase (pgTAP + welcome-credits concurrency + the CAND-1 checkout-lifecycle.contract.test.ts lane, 20/20) all green against real local Postgres; supabase db advisors --local --type security --fail-on warn clean. deno check against the real npm registry isn't possible pre-publish (published @pickforge/* is still 0.9.0, matching main's existing gap for every Deno function); verified the new call sites' typing directly against package src with tsc --strict instead.

Scope note: this is intentionally the first coherent slice — it does not yet consolidate billing's completion/refund reconciliation with edge-shared's deletion fencing/fixpoint/finalization into one module. That merge (money-path vs. account-path lifecycle ownership) is a larger, separately reviewable change; splitting it out keeps this PR's diff small (16 files, +132/-54) and behavior-preserving. Happy to open a follow-up PR for that consolidation if it's still wanted.

[ElbertePlinio]

CAND-3 progress: PR 3 (durable sync last-writer-wins) is up.

PR #50 replaces the settings-sync LWW choreography (conditional .update() guarded by updated_at <, falling back to an ignoreDuplicates .upsert(), falling back to a third read to learn the outcome) with one durable settings_sync_lww_write SQL function (new forward migration supabase/migrations/20260720000000_settings_sync_lww.sql, additive only per #35) that locks the (user_id, field_group) row, compares/writes/tombstones, and always returns the authoritative row in the same call — no follow-up read needed.

• pushGroup/deleteGroup keep all validation/sanitization in TS and just call the durable RPC; written/stale result semantics are unchanged.
• security invoker, staying inside the table's existing RLS boundary, same pattern as public.credit_balance_cents.
• New local-Postgres contract lane (packages/sync/test/lww.contract.test.ts), following PR test(billing): checkout lifecycle contract tests against local Postgres #47's convention: skips cleanly without Postgres, wired into test:supabase. Covers real concurrent push/push, first-insert/first-insert, and push/delete races, equal-timestamp ties (first writer wins), and older data racing in after a newer tombstone.
• pgTAP coverage adds microsecond canonicalization, the existing future-timestamp check constraint, and per-user isolation.

Validated: bun run typecheck; bun run test (353/353); supabase db reset (all migrations apply cleanly); PICKFORGE_ALLOW_LOCAL_DB_TESTS=1 bun run test:supabase against real local Postgres — pgTAP (155 tests), welcome-credits concurrency, the CAND-1 checkout-lifecycle.contract.test.ts lane (20/20, still green), and the new sync LWW contract lane (8/8) all pass; supabase db advisors --local --type security --fail-on warn clean.