`APPROVAL.md`

76 lines

# TK-11438 — historical first-batch approval specification

Status: FIRST BATCH APPLIED AND REVERIFIED. Overall migration remains BLOCKED.
Owner: codex-run-11438. The specification below is retained as history.
Source commits: showroom a482499, Pattern Design Lab bf33afd. Peer codex-run-11401
persisted two showroom dump fields; fresh verification/reverification.json accepts
that handoff. See NEXT-BATCH.md for the pending scope.

Approve the following first batch only: update the local connection defaults and
effective service environment for interiordesignershowroom and patterndesignlab,
then restart and verify those two PM2 services individually. Keep PostgreSQL TCP
enabled. No catalog/Shopify writes, remote deployment, or bulk fleet restart.

## Exact proposed changes

The two hashed, single-occurrence source replacements are in
`proposed-changes.json`. They were applied in the approved first batch.

| Service | Source default | Effective configuration required |
|---|---|---|
| interiordesignershowroom | `lib/db.js`: fallback URL becomes `postgresql:///idshowroom?host=/tmp` | PM2 currently injects `DATABASE_URL` pointing to localhost:5432/idshowroom. Set its socket host to `/tmp`, preserve database/user/other options, and update its durable configuration source. A source-only edit is insufficient. |
| patterndesignlab | `server.js`: `process.env.PGHOST` fallback becomes `/tmp` | Inspect `.env` and durable service configuration, preserve existing user/database/port, and remove any effective loopback override for this local database. |

Before applying, check file hashes and effective env again, coordinate ownership,
snapshot existing dirty trees without capturing secrets, and privately capture the
two services' exact prior configuration. Do not overwrite changed files. Identify
the durable launcher configuration before changing transient PM2 environment.

## Evidence already obtained

- Original `/tmp/tcp-all.txt` has 218 entries: **217 files and one `./` directory**.
- Broader current grep found 841 candidate files; union with the original list is
851 entries. These include unrelated host configurations, docs, and archives.
Of the union, 634 files contain an explicit local PostgreSQL URL. None of these
counts establishes the number of deployed consumers.
- PostgreSQL 14.23 advertises socket directory `/tmp`, TCP `localhost`, port 5432.
- The later saved baseline contains an active TCP session to database `ken`
from `::1`. This directly disproves readiness to close TCP now.
- Installed pg drivers for showroom, patterndesignlab, and Norma-platform passed
six checks: socket SELECT with read-only enforced, plus missing socket ENOENT
with no TCP fallback, for each driver. All test connections closed.
- Existing PM2 daemon returned 147 service records. Showroom has an effective
localhost DATABASE_URL. Other potential TCP env consumers include
gracie-internal (`PG`) and ken (`KEN_DATABASE_URL`, `DATABASE_URL`).
- hos-web and hos-admin have localhost in their URL but already specify
`host=/tmp`; do not classify these as TCP solely from URL authority.
- Running norma-email uses `~/Projects/Norma`, not `Norma-platform`.
The Norma-platform driver proof does not verify the running Norma application.

## Verification and rollback required after approval

Capture baseline authenticated DB-backed journeys for each service, then migrate
one at a time. Showroom's `/healthz` only says `ok`; it is insufficient. Exercise
an authorized catalog/brand read and correlate its connection with socket
metadata. Exercise patterndesignlab's DB-backed read/health flow, retain its auth
boundary, and verify missing-socket failure without fallback. Confirm database,
role and expected read result remain unchanged. Monitor errors after each restart.
If a step fails, restore only that batch's captured source and effective/durable
env, restart only that service, and repeat its baseline journey. Do not use a
whole-repo reset or restore the fleet's entire PM2 dump over concurrent changes.

## Remaining before the ticket can be done

Classify all original 217 files and expanded candidates by actual runtime,
database, driver, target machine and disposition. Inventory launchd/cron, shell
`psql -h`, inherited/default hosts, compiled artifacts, Docker/SSH-forwarded
connections, secrets-manager routing and dynamic config. Migrate remaining real
local consumers in reviewed batches; explicitly document exclusions. A quiet
pg_stat_activity snapshot does not prove scheduled consumers are safe. Observe
representative scheduled cycles and independently verify the complete operational
journeys. Only then seek a separate approval to disable TCP. No `tk done` yet.

Gate source: Steve's explicit ticket instruction requires a draft and STOP for
customer-facing or production changes. This memo requests that specific first
batch; routine shell/read-only approvals do not authorize the rollout.