[EPIC] Deployment evolution: release discipline + platform consolidation (Cloudflare)

[4444J99]

Tracking issue for the deployment-architecture & release-discipline evolution. Full plan: docs/logos/evolution-plan.md. The locked decision below governs where historical plan sections still describe alternatives.

Historical starting state

main == production with no gate; releasing == merging; breaking-without-config changes become live incidents; infra is spread across Vercel + Render + Terraform/AWS + k8s (too much surface for a solo operator). Cloudflare account already runs 9 Workers / 3 D1 / 1 R2 — an underused strength.

Decision already locked

Option E: full Cloudflare, including D1, with a $0 floor was recorded on 2026-05-25 and remains explicit in the main-branch evolution plan and telos. See the original decision receipt. Implement through the existing cloudflare/ foundation and incremental endpoint migration. Later comments or historical phases that reopen hybrid/Render/Railway selection do not replace this recorded decision.

Release discipline (any option) — §4

• Merge ≠ release: main → staging auto; prod = manual promote
• Environments: local → PR preview → staging → prod
• Branch protection on main: full CI (typecheck + server tests + build) + review required
• Per-env secrets; feature-flag breaking changes; expand-contract migrations; Sentry + health checks

Phases (sequences every open item)

• P0 Guardrails — branch protection, CI gates, staging target (main→staging)
• P1 Safe-merge backlog — chore(deps): bump ip-address from 10.1.0 to 10.2.0 in the npm_and_yarn group across 1 directory #233, chore(deps): bump the npm_and_yarn group across 1 directory with 10 updates #229, Harden: server/index.ts auto-starts the server on import (add main-module guard) #237; flag-gate + merge Audit remediation: security, compliance, and correctness fixes #234; tick Deploy prerequisites for PR #234 security hardening (breaking without config) #235 per-env
• P2 Platform consolidation — execute the approved Workers/Hono + D1 migration incrementally; verify workload parity and rollback before retiring legacy infrastructure
• P3 Debt — Frontend TypeScript debt: 4 current diagnostics after CI syntax repair #236 (frontend TS), Sentry, test gates
• P4 Meta — Propagate PR #234 completions to meta-organvm universal indices (IRF / omega / seed / concordance) #238 (IRF/omega/seed/concordance)
• Full Cloudflare completion — migrate remaining API/data/job workloads under Option E; retain Cron + D1 job drain at the free-tier floor. Paid services require their own existing spend boundary.

Related: #234 #235 #230 #237 #236 #238 #233 #229

Current implementation ownership — 2026-09-09

Credential provisioning, credential scope and durable delivery are owned by Limen CLAVIS / credential wall #320, with merged implementations #1062 and #551. Use that existing owner; do not create another credential system or turn this technical dependency into a repeated user consent/platform-choice request.

This UCC epic owns provisioned D1/KV/Access bindings, migration, Worker deployment and live acceptance. Merged UCC #410 repaired account configuration and guards. Its staging execution verified the active token/account, observed D1 metadata 401/code10000 and unresolved D1/KV/Access bindings, then skipped migration and deployment. Preserve that evidence until an owner-executed successor supplies actual bindings and successful staging readback. A source merge or secret-presence check alone does not close this epic.

Accepted-main staging execution — 2026-09-09

Merged #419 implements dedicated resource reconciliation, generated real-binding configuration, schema migration/readback and live source/authentication verification. The final PR head and accepted main both passed CI Gate and dependency validation. Merge revision: 2a65f91435c3ca9d8c5852287f01d6ac71ae07a6.

The actual accepted-main staging run 34377834223 passed frozen installation and current-main verification, then attempted provisioning in apply mode. Provider receipt: exact account GET 200; Workers inventory GET 200; D1 inventory GET 401, code 10000. Only these three GET requests occurred; no resources were created. Migrations, deployment and live verification were skipped. The sanitized cloudflare-staging-34377834223-1 artifact preserves this receipt. Staging deployment remains unverified.

Limen #2595 adds the missing exact UCC sink, verifies candidate account/D1 capability before replacement, and attempts delivery through the exact authorized App principal. Its accepted-main execution is the credential-owner continuation; no repeat platform decision or user consent is needed. After successful delivery, rerun this staging workflow only while its source is still current main.

[4444J99]

Decision locked: full Cloudflare (Option E), elevated route

Two constraints settled it: $0 budget (no Railway/Render facility) + existing Cloudflare fluency (9 Workers), and an explicit choice for the ideal form over the easy hybrid.

• Target is now specified in docs/logos/telos.md: Pages (SPA) + Workers/Hono (API) + D1 (FTS5 replaces pg_trgm, json1 replaces JSONB) + Cron Triggers + D1-backed job drain (→ Queues/Durable Objects on the $5 plan) + KV + R2 + Workers AI/Vectorize (scoring) + Cloudflare Access (auth — supplies org_id, dissolving most of Deploy prerequisites for PR #234 security hardening (breaking without config) #235). Plan §3 updated and committed (81abb65).
• Reframe: nothing currently runs, so the objective is first working deploy on free infra, not protecting a prod that doesn't exist. P0 = stand up a green Cloudflare environment, not pipeline guardrails.
• Method: strangler — a self-contained cloudflare/ foundation (Hono Worker + D1 + Cron + Access + the Audit remediation: security, compliance, and correctness fixes #234 security logic ported) is being scaffolded now; then port server/ endpoints one at a time, security-critical first; retire Vercel/Render/Terraform/k8s at parity.

Issue fates under E: #230 (Render) and #237 (index.ts auto-start) become obsolete at parity; #236 folds into the Pages migration; #235 largely dissolves via Cloudflare Access; #234 logic carries forward.

---

Generated by Claude Code

[4444J99]

Session Handoff — 2026-05-28

Branch claude/issue-discovery-reporting-2R1GO merged to main and deleted. All work is on main at commit 11df24a.

---

What landed this session

Security hardening (Express/server layer — PR #234 work)

• Multi-tenant IDOR fix: org_id derived exclusively from verified JWT claim; client-supplied org_id must match or 403. Covers deals.ts, contacts.ts, all job routes.
• Plaid webhook ES256/JWK verification via jose (createRemoteJWKSet + jwtVerify); all other webhook verifiers fail-closed when secrets are unset (previously fail-open).
• dataTier middleware: real entitlement from organizations.subscription_tier (TTL-cached); x-data-tier header ignored.
• Per-tenant job scoping: BullMQ jobs carry orgId; read/list/delete are org-filtered; 404 on cross-org (no existence leak).
• PortfolioService: SQL injection in ORDER BY fixed via ALLOWED_SORT_COLUMNS allowlist.
• orgContextMiddleware + AsyncLocalStorage wired; SET app.current_org_id GUC ready for RLS.
• Migrations 014–019: org_id NOT NULL + backfill, bounded CHECK constraints, deal_number UNIQUE, TRUNCATE guard on audit_logs, RLS tenant policies, JSONB CHECK constraints.

Cloudflare Workers edge scaffold (cloudflare/)

• wrangler.toml — staging + production envs, distinct placeholder IDs, non-prod top-level R2 bucket.
• workers/api/src/: Hono app (index.ts), typed D1 helpers (db.ts), auth.ts (Cloudflare Access JWT verification, fail-closed), scheduled.ts ($0 cron + D1 jobs drain, atomic claim, no silent-done), types.ts (Env, Identity, AppBindings).
• migrations/0001_init.sql: organizations, prospects, jobs, FTS5 virtual table + ai/ad/au sync triggers.
• .github/workflows/deploy-cloudflare.yml: push→staging auto; workflow_dispatch confirm=DEPLOY→production; D1 migrations applied before each deploy.
• cloudflare/.gitignore: .wrangler/, .dev.vars, secrets excluded.

Docs/logos layer

• docs/logos/telos.md — idealized form (Pages + Workers/Hono + D1 + Cron + DO + Workers AI + Access) with 5 invariants.
• docs/logos/pragma.md — honest concrete state post-audit.
• docs/logos/praxis.md — this file; §C ✅ Plaid/dataTier/job-scoping resolved; Auth0 + RLS remain pending-external-config.
• docs/logos/evolution-plan.md — Options A–F evaluated; Option E (full Cloudflare including D1) locked.

---

Still pending (external config required — cannot be done from this container)

Item	What's needed
wrangler.toml D1/KV IDs	wrangler d1 create ucc-mca → paste ID; wrangler kv namespace create KV → paste ID. Repeat per env (staging ≠ production).
Cloudflare Access AUD	Create a Zero Trust Access Application → paste the Audience tag into wrangler.toml [vars] per env.
Wrangler secrets	wrangler secret put JWT_SECRET --env staging etc.
Auth0 org_id claim	Add org_id to Auth0 token (Action/Rule). Edge auth.ts + server authMiddleware.ts already read it.
Non-owner DB role	Create a Postgres app user that is NOT the table owner; RLS policies are wired but only bite non-owners.
IRF / meta-organvm	See praxis.md §A — needs organvm CLI + meta-organvm filesystem access.

---

Next-session entry points (in order)

1. Fill wrangler.toml with real resource IDs (see table above) → wrangler deploy --env staging → verify /health returns 200.
2. P0 Guardrails — add branch protection to main (require CI: typecheck + server tests + build + review). Creates the staging→prod gate.
3. P1 merges — chore(deps): bump ip-address from 10.1.0 to 10.2.0 in the npm_and_yarn group across 1 directory #233 (ip-address patch, safe to merge), chore(deps): bump the npm_and_yarn group across 1 directory with 10 updates #229 (Dependabot 10-package, check for majors before merging), Harden: server/index.ts auto-starts the server on import (add main-module guard) #237 (auto-start guard on server/index.ts), Frontend TypeScript debt: 4 current diagnostics after CI syntax repair #236 (frontend TS debt — recharts@3/resizable@4 drift, missing papaparse/winston deps).
4. P2 Platform — CF Pages deploy for apps/web; back-end stays on current host until strangler migration is ready.

Docs: docs/logos/evolution-plan.md | docs/logos/telos.md | docs/logos/praxis.md

---

Generated by Claude Code

[4444J99]

Progress on the repo-actionable parts of this epic (PR #263):

P0 guardrails — documented & partially shipped

• docs/DEPLOYMENT.md §5 captures the release-discipline model (merge≠release, local→PR preview→staging→prod) and a branch-protection checklist naming the existing checks to mark required on main (ci.yml, backend-tests, validate-dependencies, CodeQL/secret-scan + review). Marking checks required is a repo Settings → Branches action that only an admin can do — flagging rather than guessing.
• Release/promote already exists for the edge (deploy-cloudflare.yml: push→staging, manual confirm=DEPLOY→prod) and is now mirrored by tag-based release artifacts + the Pages deploy added in this PR.

Platform direction — recommendation recorded (decision still yours)
§6 documents the recommended Cloudflare-hybrid now → full-Cloudflare later path. I deliberately did not execute P2's "retire terraform/ + k8s/" — that's a destructive, direction-dependent call for you to make. Happy to open a strangler-migration PR once you pick a direction.

Remaining items (#236 frontend TS, Sentry, test gates, #238 meta propagation) are tracked separately; #238 specifically needs the organvm CLI + meta-organvm filesystem, which aren't reachable from the cloud container.

---

Generated by Claude Code

[4444J99]

Engaged triage: still current as the umbrella for release discipline and platform direction. The repo-local activation work lives in draft PR #263, but that branch is now conflicting/stale rather than landable as-is.

Next concrete step: rebase/split #263 into reviewable deploy-doc/workflow slices, then use this issue to track only the remaining operator/infra decisions (required branch protection, staging/prod promotion policy, platform consolidation choice).

[4444J99]

Item-specific execution plan

Outcome
Replace merge-equals-production with an auditable staged release system, then consolidate deployment surface through an explicitly approved Cloudflare-hybrid path while preserving rollback and avoiding a forced rewrite.

Dependencies
This epic owns sequencing across #233, #229, #234, #235, #230, #237, #236, and #238. It depends on a platform decision, current infrastructure/cost inventory, protected-branch controls, staging credentials, data/queue compatibility, and a migration/rollback architecture.

Ordered work packets

1. Re-probe every linked issue/PR and the current Vercel, Render, AWS/Terraform, Kubernetes, Cloudflare, database, Redis, queue, DNS, and observability footprint; produce a dependency and ownership ledger.
2. Record an ADR choosing Cloudflare-hybrid, Render consolidation, or Railway, with costs, operational burden, runtime constraints, security, exit path, and explicit owner approval.
3. Implement P0 guardrails: protected main, required exact-head CI, PR previews, automatic staging, manual production promotion, environment-scoped secrets, and release/rollback receipts.
4. Complete P1 safe-merge work in dependency order: chore(deps): bump ip-address from 10.1.0 to 10.2.0 in the npm_and_yarn group across 1 directory #233, chore(deps): bump the npm_and_yarn group across 1 directory with 10 updates #229, Harden: server/index.ts auto-starts the server on import (add main-module guard) #237, feature-gated Audit remediation: security, compliance, and correctness fixes #234, and the environment prerequisite matrix in Deploy prerequisites for PR #234 security hardening (breaking without config) #235.
5. Execute P2 consolidation behind DNS/traffic controls; prove API, worker, queue, database, cron, asset, webhook, and rollback behavior before retiring any legacy surface.
6. Complete P3 type-safety, Sentry/health, test-gate, and operational-runbook debt; establish measurable release SLOs.
7. Complete P4 canonical propagation through Propagate PR #234 completions to meta-organvm universal indices (IRF / omega / seed / concordance) #238 only after runtime and release status are evidenced.
8. Treat P5 full-Cloudflare migration as a separately approved strangler program with workload-specific equivalence tests; do not infer it from the hybrid milestone.
9. Close or supersede child items only from linked merge, deployment, and verification receipts; publish a final architecture and decommission record.

Verification / acceptance evidence

• Focused tests for the changed behavior; repository lint/typecheck/build/test commands where applicable; clean diff and exact commit SHA in the owning PR.
• A final evidence comment must name the exact head SHA, commands/checks and results, changed paths or artifacts, external receipts, and any residual risk.

Human / external gates
A named owner must approve platform direction, spend, accounts, DNS/traffic changes, secret custody, production promotion, and destructive infrastructure retirement.

Next valid action
Produce the current-state infrastructure/cost/dependency ledger and route the platform ADR for an explicit decision before changing deployment topology.

This plan is a coordination contract, not completion evidence. Keep this epic open until release discipline, the approved consolidation milestone, child dispositions, and rollback evidence are complete.