Deployment

Constellation is deployed on Vercel as a multi-zone topology:

Zone	Host	Vercel project
Directory (root)	constellation.planetb2b.com	constellation-directory
Project Tracker	/projects/* (rewritten)	constellation-platform
Catalog	/catalog/* (rewritten)	constellation-catalog
Docs	docs.planetb2b.com	constellation-docs

Directory is the root zone and rewrites requests for /projects/* and /catalog/* to the other Vercel projects.

NEXT_PUBLIC_BASE_PATH

Sub-zone apps read this env var at build time:

Environment	Value	Behaviour
Production	/projects or /catalog	Multi-zone: served under prefix, rewrites from Directory
Preview	unset	Standalone: served at / for preview deploys
Local dev	unset	Standalone: turbo dev on app-local port

fetch() and basePath

Next.js auto-prepends basePath to <Link> and router.push, but not to fetch(). Use the apiUrl() helper from each app's src/lib/api-url.ts:

import { apiUrl } from '@/lib/api-url';
const res = await fetch(apiUrl('/api/people')); // '/projects/api/people' in prod

Migration gate on release PRs

Every PR targeting main (release branches and hotfixes) runs the Verify Release Migrations CI job. It fails the merge if either staging (DEV_DATABASE_URL) or production (PROD_DATABASE_URL) is missing a migration that's on the branch. The job is read-only — it never applies migrations. Apply outstanding migrations to both databases via the Supabase dashboard SQL editor or the Supabase MCP (apply_migration / execute_sql) before opening the release PR.

A migration containing CONCURRENTLY cannot go through a transaction

Scan the migrations you are about to apply first — recursively, since an entry can be a directory:

grep -rl CONCURRENTLY apps/<module>/prisma/migrations/<entry>

PostgreSQL rejects CREATE INDEX CONCURRENTLY / DROP INDEX CONCURRENTLY outright inside a transaction block, so a tool that wraps what it is given does not merely apply them more slowly — the migration fails. Those files are written deliberately without BEGIN;/COMMIT; to avoid holding an ACCESS EXCLUSIVE lock on a busy table for the length of a full index build, and they say so in their header.

Apply them with a session that does not wrap, and always with ON_ERROR_STOP=1 — psql's default is to report an error and carry on, which lets a migration fail its DDL and still run its final schema_migrations insert, recording an incomplete migration as applied:

psql "$PROD_DATABASE_URL" -v ON_ERROR_STOP=1 -f <file>

A migration entry can hold more than one file — 033_tasks_backlog_grooming is migration.sql plus post_migration.sql, and the grep points only at the one containing CONCURRENTLY. Apply every .sql in the entry in runner order (migration.sql first) and record the tracking row only once they have all succeeded; stamping the entry after applying one file marks the whole migration as done while the rest never ran.

The raw psql path also bypasses the module runner's tracking-row write, and not every migration self-inserts. Check the file for a schema_migrations insert and add one yourself if it has none, or the release gate stays red against a database that is already up to date — chained to the apply with && so it cannot stamp a migration that failed, into the owning module's schema (see scripts/check-migrations.ts), and keyed on the migration entry name (a directory-based migration is tracked by its directory, not by the inner .sql file).

If you use the dashboard or MCP instead, run the concurrent statement on its own and then confirm the index is valid: a failed concurrent build leaves an INVALID index behind, which a later re-run guarded by IF NOT EXISTS will skip straight past.

SELECT indexrelid::regclass, indisvalid FROM pg_index WHERE NOT indisvalid;

Full procedure: .claude/skills/release-and-migrations/SKILL.md § Migrations Before the PR.

See scripts/check-migrations.ts (invoked with --strict from the gate) for the implementation.

Platform packages carry their own migrations

Migrations do not live only under apps/<module>/prisma/migrations. A shared package can own a schema too, and @constellation-platform/jobs owns jobs — its files are in packages/platform/jobs/migrations, applied by the package's own db:migrate, and tracked in jobs.schema_migrations like any module's. npx turbo run db:migrate picks it up with everything else; turbo.json orders @constellation/project-tracker#db:migrate after it, because both would otherwise create jobs.queue and race.

Baseline adoption on databases that already have jobs.queue

Project Tracker's grandfathered 013_jobs_queue.sql created jobs.queue long before the package had a runner, so on staging, on production and on any machine that has run PT's db:setup, the table exists while jobs.schema_migrations does not. Re-applying 001_jobs.sql there is not what you want, and neither is skipping it silently.

The runner therefore baseline-adopts 001: it records the file as applied without executing it, but only after comparing the deployed table against a reference the same server builds from 001's own declaration — columns, constraints, indexes, RLS flags and every policy's command, kind, role scope and predicate. The reference is a closed set, so an object neither 001 nor 002 declares is refused rather than tolerated: an extra permissive policy is a cross-tenant read path that applying 001 would not remove, and an extra UNIQUE index rejects enqueues the schema permits.

Three outcomes, and each is loud:

• matches — 001 is recorded as applied and never executed, then 002 runs normally;
• differs repairably (a missing index, RLS not forced, a policy 001 recreates) — adoption is declined and 001 is applied, which is written entirely in IF NOT EXISTS / DROP POLICY IF EXISTS form;
• differs unrepairably — the runner aborts and names the difference. Nothing is recorded. Reconcile the database by hand before re-running; a recorded migration is a claim every later migration acts on.

Runtime-role grants travel with the migration

002_worker_claim_policy_and_runtime_grants.sql grants constellation_app schema USAGE plus SELECT, INSERT, UPDATE on jobs.queue — not DELETE — and read-but-not-write on jobs.schema_migrations. This is deliberate and it is why enqueuing works on a deployed database at all: RLS grants nothing on its own, and locally the privileges came from scripts/db-init.sql, which is a dev-only fixture. Without them the symptom is 42501 out of PostgresJobQueue.add() and out of every worker claim.

The grants are guarded on the role existing, and followed by hard postconditions — including a negative one, because REVOKE reports success whether or not a grant existed and so says nothing about write access reaching the role through PUBLIC or through a role it is a member of. If the migration role lacks authority to grant, the file raises instead of being recorded: the shared runner suppresses any statement that fails with 42501 and logs it as a skip, which would otherwise leave the ledger claiming work that never happened.

Upgrade prerequisite: the wiki INTERNAL classification tier

Applies to Dedicated Cloud and On-Prem. On SaaS the platform controls the rollout and there is nothing to do.

The INTERNAL classification tier reaches the wiki across two releases, and they must be installed in order:

Release	What it does
N — the release carrying PLT-502	Every wiki build can read INTERNAL. Nothing can create one: the wiki.classification domain and every write schema still reject it.
N+1 — the release carrying PLT-977	Widens the domain and the write schemas, so INTERNAL pages become creatable.

Release N is the minimum version from which release N+1 may be installed. Upgrading straight from N-1 to N+1 skips the waypoint: the outgoing build then runs a four-value event validator while the incoming one can already publish an INTERNAL payload, and the outgoing dispatcher rejects it. Deliveries are retried rather than lost, but a repeatedly-failing row holds a slot at the head of an oldest-first outbox scan until the old build retires, so a long-tailed upgrade pays throughput for it.

Nothing enforces this mechanically on these tiers — the operator chooses when and from what version to upgrade, and this repository has no sequential- upgrade gate. That is why it is written here as a prerequisite rather than assumed. The reasoning, and the residuals it accepts, are in ADR-032 § The rolling-deploy story.

The exposure begins when somebody classifies a page INTERNAL, which is an operator action against this documented prerequisite — not something the upgrade performs on its own. A deployment that cannot accept that should not take the tier: raise the case rather than skipping the waypoint, since the strategy lives in the artifact and cannot be selected per deployment.

Environment variables per Vercel project

Vercel project	Var	Value	Environments
constellation-platform	NEXT_PUBLIC_BASE_PATH	/projects	Required on production. Standalone preview/dev unset (serves at /)
constellation-catalog	NEXT_PUBLIC_BASE_PATH	/catalog	Required on production. Standalone preview/dev unset
constellation-directory	PROJECTS_ZONE_URL	https://constellation-platform.vercel.app	Required on production. Optional elsewhere (falls back to localhost defaults)
constellation-directory	CATALOG_ZONE_URL	https://constellation-catalog.vercel.app	Required on production. Optional elsewhere (falls back to localhost defaults)

The resolveBasePath() helper in scripts/resolve-base-path.ts fails fast if NEXT_PUBLIC_BASE_PATH is missing on Vercel production — without it the sub-zone app deploys at / and breaks multi-zone routing.

RLS-bypass startup guard (assertNonBypassRole)

Each app's src/instrumentation.ts calls assertNonBypassRole() (from @constellation-platform/db) on server startup. PostgreSQL silently disables every Row-Level Security policy — even with FORCE ROW LEVEL SECURITY set on every table — when the connected role has rolsuper = true or rolbypassrls = true. The guard is the fail-fast tripwire for that: if DATABASE_URL is ever repointed at a SUPERUSER/BYPASSRLS role, the app refuses to boot instead of silently serving cross-tenant data. Production connects as the non-bypass constellation_app runtime role, so the guard passes; it only trips on a regression.

Var	Value	Effect
CONSTELLATION_ALLOW_BYPASS_RLS	1	Fail-closed opt-out — attested CI only. Skips the guard ONLY on an attested ephemeral GitHub Actions runner: it takes effect only when CI=true and GITHUB_ACTIONS=true and DATABASE_URL is a loopback host (localhost/127.0.0.1/::1) and no Vercel signal (VERCEL/VERCEL_ENV) is present. Every deployment tier fails that attestation — SaaS (Vercel), Dedicated Cloud, and On-Prem (Docker/K8s) set neither CI var and use a remote database — so a stray value here is ignored on any deployment and the guard always enforces. (Vercel is additionally an absolute veto, even under full attestation.) Set it only where a privileged/bypass role is used deliberately (the CI end-to-end tests serving the apps as a superuser). Any other value, or unset, always enforces.

Local dev needs nothing: .env.local.example already points the apps at constellation_app. Migration scripts legitimately connect as a privileged role and never call the guard.

Speed Insights — pinned paths, and where the samples are expected to land

Directory, Catalog and Project Tracker mount <SpeedInsights> directly in their root layouts with both props pinned. Wiki mounts the platform adapter instead (apps/agents carries no telemetry at all):

import { WebVitals } from '@constellation-platform/telemetry';

<WebVitals />;

WebVitals takes no props — it owns both transport paths. The three direct call sites still pass them by hand:

<SpeedInsights
  scriptSrc="/_vercel/speed-insights/script.js"
  endpoint="/_vercel/speed-insights/vitals"
/>

Migrating those three to the adapter, and retiring the hand-passed props, is PLT-1106.

Neither prop is optional: dropping either stops collection, and the two fail differently. The v2 SDK defaults to a randomised /<hash>/… path for both the script and the collector. Under the multi-zone rewrite the browser resolves those against the root zone's host, where the script path 404s and the collector path falls through to the Next.js catch-all and answers HTML with status 200 — so sendBeacon reports success, DevTools shows a green request, and Vercel records nothing.

A missing scriptSrc is at least loud — the 404 surfaces as a console error, which is how INF-54 found it. A missing endpoint is the dangerous one: it fails silently and green, with no console error and no failing gate, and the only symptom is a dashboard nobody is watching. Both halves reached production once each and were fixed by hotfix (INF-54, #543 and #545).

Sub-zone samples are expected under the ROOT zone's Vercel project

Directory's rewrites cover /projects/*, /catalog/*, /wiki/* and /agents/* — but not /_vercel/*. Both the script request and the vitals beacon therefore reach Directory's deployment, so Directory's dashboard is where sub-zone field data is expected to land, and the first place to look for it. That follows from the routing, but which project Vercel finally credits has not yet been confirmed against a deploy; treat it as the expected outcome rather than an established one until someone checks.

If it holds, it is dataset location and mixing, not data loss: the beacon carries the page path, so /wiki/* and /projects/* routes stay separable within that project — filter by path. Giving each zone its own project would need a zone-owned absolute endpoint (cross-origin, so CORS) or the SDK's dsn prop, and is a cross-app decision rather than a per-zone one.

Vercel project wiring

The four Vercel projects share a build root (the monorepo) but each has its own Root Directory set to apps/<name> so Vercel runs each build from inside that workspace. installCommand and buildCommand are left blank on three of them (Vercel auto-detects); the docs project overrides them to use Turborepo, see apps/docs/vercel.json. All projects use the framework default output directory (.next for the three Next apps, build for Docusaurus) — apps/docs/vercel.json declares outputDirectory: "build" explicitly, but it matches the Docusaurus default.