test: make Nx own fresh environments and focused slow checks

[jumski]

Summary

Make Nx the sole owner of pgflow test-environment lifecycle and provide focused execution for expensive test families without bypassing their setup dependencies.

A delivery should start from one fresh pgflow-owned environment, reuse it across correction agents in the same worktree, trust the Nx target graph and cache, and recover interrupted checks through one supported target.

Motivation

Delivery of #647 exposed avoidable test friction:

• The complete edge-worker integration suite ran 10 times and consumed 65.6 minutes.
• Direct full-directory Deno runs bypassed db:ensure and Nx lifecycle ownership.
• A timed-out run left two PostgreSQL start_tasks calls alive; they blocked later reset_db calls.
• Edge-worker E2E readiness accepted a stale Kong listener while the current function server was still restarting.
• Agents added --skip-nx-cache even though this repository deliberately maintains target inputs and dependencies.

The candidate still passed every CI check on the first push in #672. The problem is local execution structure, not missing coverage.

Evidence:

• Source delivery: Remove legacy flow compilation before queue identity and routing #647
• Delivered PR: refactor: make worker startup the only flow compilation path #672
• Relevant targets: pkgs/edge-worker/project.json, pkgs/core/project.json, client/CLI E2E targets, and shared Supabase scripts

Desired workflow

delivery starts
  -> freshen all pgflow-owned test services through Nx once
  -> run focused checks during coherent implementation batches
  -> run affected full integration and E2E targets once at the final round gate
  -> reuse the same environment for correction agents
  -> freshen again only after interruption or failed environment health

This lifecycle covers pgflow's dedicated test instances and ports. It must not stop an unrelated default Supabase project.

Scope

1. One fresh-environment entry point

Add one Nx-owned entry point, provisionally named test-env:fresh, that:

• stops every pgflow project instance exposed through supabase:stop;
• stops and removes the edge-worker integration database and its volumes/orphans;
• coordinates through the existing pgflow test-environment lock;
• succeeds when services are already stopped;
• stops only pgflow-owned test infrastructure;
• leaves startup to the requested test target and its dependency graph.

Run this once per delivery, not once per correction round. An interrupted database/E2E check may run it again before retry.

2. Focused checks that preserve Nx dependencies

Investigate support for the smallest affected check in this order:

1. Pass a file/filter argument through the existing Nx target.
2. Add a focused Nx target that keeps the full target's dependencies.
3. Put a small runner script behind an Nx target.
4. Keep the full target when focused isolation cannot be preserved.

Cover expensive or infrastructure-sensitive families first:

• one pgTAP file;
• one edge-worker integration file;
• one E2E file only when that file is independently runnable.

Do not add a single-file unit target only for symmetry; existing unit targets are cheap. Do not commit speculative target names before checking Nx argument behavior.

3. Trust the target graph and cache

Repository commands should run without agent-added cache flags. Nx decides whether work is valid or cached.

Check that:

• a second unchanged invocation uses the configured cache where caching is valid;
• documentation-only changes do not invalidate runtime E2E work;
• runtime, test, configuration, migration, and dependency changes invalidate the targets they affect;
• database/service lifecycle targets remain uncached where state makes caching unsafe.

Use --skip-nx-cache only when an existing repository command explicitly requires it or while diagnosing cache behavior.

4. Robust readiness and interruption recovery

Fix edge-worker E2E readiness so a listener from an old process cannot satisfy readiness for the function server that the current target is starting.

Define one supported recovery path for interrupted integration/E2E checks. It should remove stale worker processes, database sessions, containers, and volumes through owned scripts/targets rather than ad hoc operator commands.

Prefer process ownership and target cleanup over port-only probes.

5. Bounded failure output

Inspect one representative success and failure from Nx, Deno, pgTAP, and Vitest. Document stable failure markers that an agent can use after complete output is saved, including:

• Nx: Failed tasks: and Running target ... failed;
• Deno: ... FAILED, FAILED |, and the => ./path:line block;
• pgTAP: Result: FAIL, Failed test:, and Looks like you failed;
• Vitest: FAIL, Test Files, and Tests.

Do not solve this with a large logging framework. Add a small shared wrapper only if existing Nx/runner output cannot preserve the log, exit status, and bounded failure summary.

Acceptance criteria

• One Nx command freshens all pgflow-owned test services and succeeds from both stopped and running states.
• The command does not stop an unrelated default Supabase project.
• Existing full integration, pgTAP, and E2E targets still own all required setup/build dependencies.
• Focused pgTAP and integration execution is available through Nx without bypassing lifecycle dependencies, or the implementation documents why a safe focused form is impossible.
• Focused E2E execution exists only if a test file passes an isolation check from a fresh environment.
• E2E readiness cannot pass only because a stale process listens on the expected port.
• The supported interruption-recovery path removes stale resources and allows the next full suite to pass.
• Cache behavior is checked for unchanged inputs, documentation-only changes, and affected runtime inputs.
• No implementation or documentation encourages routine --skip-nx-cache use.
• Full Core pgTAP, edge-worker integration, and affected E2E targets pass through Nx from the fresh environment.

Implementation constraints

• Start from current main in a new Worktrunk worktree.
• Use Nx targets and existing shared scripts as the source of truth.
• Reuse the existing lock and lifecycle design before adding another mechanism.
• Keep the change limited to test lifecycle, focused execution, readiness, and their checks/docs.
• Use Graphite for the commit and pull request with parent main.

Out of scope

• Changing product runtime behavior.
• Reducing CI coverage.
• Stopping non-pgflow Supabase projects.
• Adding focused unit targets without measured need.
• Building a general test orchestration framework.