fix(pathways): never register a pathway instance in development

[jbiskur]

Description

runtimeEnv: "development" performed the by-name pathway upsert whenever autoProvision.pathway was true, then started pulse and command polling against the returned pathwayId.

Every developer boot therefore:

• created a shared control-plane resource and left a stray pathway row behind — nothing cleans them up,
• pulsed that pathway continuously from a laptop,
• polled for datapumpRestart commands that may be aimed at a real deployment.

It was silent, because NoopLogger is the library default.

Two docs disagreed on the intended behaviour and the library followed the wrong one:

• 79a08d39-e7b5-44ec-a3c0-262f292a1b22 (Declarative Registration & Auto-Provisioning) — "development never provisions a pathway instance". This is the intended contract.
• 4888704b-9166-4145-83c0-2b35544ab58e (April 2026 Runtime Split) — runtime table listed development registration as opt-in. Wrong; being corrected separately.

Reported in 861eec82-a79b-4c95-b101-3aebaae3c9d8. Decision taken by @jbiskur on 2026-08-16: development must not auto-provision a pathway instance.

Changes

• registerPathwayInstance() now returns early when runtimeEnv === "development". The guard sits in one place, so provision(), startPump(), and the leader bootstrap path are all covered.
• With no pathwayId, auto-pulse and the command poller stay off in development by themselves.
• New allowDevelopmentPathwayRegistration builder option — an explicit escape hatch for local control-plane work. It is deliberately separate from autoProvision.pathway and logs at warn on every boot.
• Moved the "Registering pathway instance" log into registerPathwayInstance(), so it can no longer report a registration that did not happen.
• README runtime table: development row opt-in → skipped, plus a note explaining why.

Type of Change

• Bug fix (non-breaking change)

Behaviour change for consumers: anyone relying on development registration loses it on upgrade. allowDevelopmentPathwayRegistration: true restores it.

Testing

• Tests pass locally (deno test -A --ignore=tests/postgres-pathway-state.test.ts; the postgres suites need port 5432, which was occupied locally — CI runs its own service)
• Added regression tests

New steps in tests/pump-runtime-behavior.test.ts:

• development + autoProvision: { pathway: true } → no PUT /api/v1/pathways/by-name/{name}, pump still starts
• development + per-startPump() override → also ignored
• development + provision() → no by-name upsert either
• allowDevelopmentPathwayRegistration: true → registers, and warns
• production + managed override still registers — guards against over-blocking

Two existing steps asserted the defective behaviour and were inverted.

Checklist

• deno fmt, deno lint, deno check src/mod.ts clean
• deno run -A bin/build-npm.ts succeeds
• Documentation updated

🤖 Generated with Claude Code