[jgoux]

Summary

Stack mode can now:

• run any service version that slim-services has published;
• match the hosted project's versions after supabase link;
• reproduce the whole local stack from one committed file, supabase/supabase.lock.

Before this change, every service version was compiled into the CLI. You couldn't try a hotfix, match production, or keep a team on the same builds without everyone running the same CLI release.

Legacy (docker-compose) mode does not change, except for one fix: a SUPABASE_PROJECT_ID naming another project than the linked one now gets its pooler URL from the Management API, as --project-ref already did, instead of reusing the linked project's saved supabase/.temp/pooler-url. Everything below applies only to stack mode (SUPABASE_EXPERIMENTAL_STACK=1 or [experimental] stack = true).

Version numbers and project refs in the examples are illustrative.

---

The mental model: it works like a package manager

If you know package.json + pnpm-lock.yaml, or Cargo.toml + Cargo.lock, you already know this.

Package manager	Supabase stack mode	Committed?	Purpose
package.json	[local.services] in supabase/config.toml	✅	What you ask for: linked, bundled, v2.197.0, v2.197.0-r1
pnpm-lock.yaml	supabase/supabase.lock	✅	What you got: the exact build of every service, pinned by digest and checksum
—	supabase/.link.json	❌ (gitignored)	Which hosted project or branch this checkout targets
pnpm install	supabase start / supabase stack install		Resolves what changed, then runs or downloads the locked builds
pnpm update	supabase stack update [svc…]		Re-resolves on purpose and rewrites the lock
pnpm outdated	supabase stack outdated		Read-only report of what an update would change
pnpm install --frozen-lockfile	supabase start --frozen / supabase stack install --frozen (implied when CI is set and a lock exists)		Fails instead of changing the lock

flowchart LR
  subgraph git["Committed to git"]
    CFG["supabase/config.toml<br/>[local.services]<br/><i>what you ask for</i>"]
    LOCK["supabase/supabase.lock<br/><i>what you got</i>"]
  end
  subgraph checkout["This checkout only"]
    LINK["supabase/.link.json<br/><i>target hosted project</i>"]
  end
  HOSTED[("Hosted project")]
  RELEASES[("slim-services releases")]

  CFG -->|specifiers| START["supabase start<br/>stack install / stack update"]
  RELEASES -->|published builds + checksums| START
  START -->|writes when stale| LOCK
  HOSTED -->|versions it runs| LINKCMD["supabase link"]
  LINKCMD --> LINK
  LINKCMD -->|records observations,<br/>resolves 'linked'| LOCK
  LOCK -->|exact pins| STACK[("Local stack")]

Loading

---

How a version is asked for

[local.services]
default = { version = "linked" }  # the default: follow the linked hosted project

[local.services.auth]
version = "v2.197.0"              # an upstream version: its highest published revision

[local.services.realtime]
version = "v2.144.2-r1"           # exactly revision 1 of that upstream version

bundled means "the version this CLI ships with". [db] orioledb_version is shorthand for the database specifier, and a database version must match db.major_version.

flowchart TD
  SPEC["specifier of a service"] --> KIND{"which kind?"}
  KIND -->|"linked (default)"| LINKED{"is the project linked,<br/>and does it report a version?"}
  LINKED -->|never linked| B1["bundled pin<br/>unlinked"]
  LINKED -->|service not reported| B2["bundled pin<br/>unobserved"]
  LINKED -->|reported| PUB{"published by<br/>slim-services?"}
  PUB -->|no| B3["bundled pin<br/>unpublished"]
  PUB -->|yes| R1["the hosted release<br/>resolved"]
  KIND -->|bundled| R2["this CLI's bundled pin"]
  KIND -->|"v2.197.0"| R3["highest published revision<br/>of v2.197.0"]
  KIND -->|"v2.197.0-r1"| R4["exactly v2.197.0-r1"]

Loading

The fallback reasons (unlinked, unobserved, unpublished) are recorded in the lock, so nobody has to guess why a service isn't running the hosted version.

What the lock contains

One entry per service (database, rest, auth, realtime, storage, imgproxy, functions, studio, pgmeta, mail, analytics, pooler). Keys are sorted and the document is written atomically, so diffs and merge conflicts stay readable.

{
  "$schema": "https://supabase.com/docs/cli/supabase-lock/v1.schema.json",
  "lockfileVersion": 1,
  "linked": {                                   // the remote the observations came from
    "project": "abcdefghijklmnopqrst",
    "branch": { "ref": "abcdefghijklmnopqrst", "isDefault": true },
    "observedAt": "2026-10-16T09:12:44.000Z"
  },
  "services": {
    "auth": {
      "specifier": "linked",                    // what config.toml asked for
      "linked": { "raw": "v2.196.1", "version": "v2.196.1" },  // what the hosted project reported
      "resolution": "resolved",                 // or unlinked / unobserved / unpublished
      "resolved": {                             // the exact build that runs
        "upstreamVersion": "v2.196.1",
        "revision": 0,
        "upstreamImage": "supabase/gotrue:v2.196.1",
        "image": "ghcr.io/supabase/cli/gotrue:v2.196.1-r0@sha256:…",
        "natives": { "darwin-arm64": { "archive": "…", "manifest": "…" }, "…": {} }
      }
    },
    "database": { "majorVersion": 17, "line": "stock", "…": "…" }
    // …one entry per service
  }
}

---

What supabase start does with the lock

flowchart TD
  S["supabase start"] --> FRESH{"lock exists, and every entry<br/>still matches config.toml?"}
  FRESH -->|yes| RUN["run the locked builds<br/>(no network, no Management API)"]
  FRESH -->|"no (missing or stale)"| FROZEN{"frozen?<br/>--frozen, or CI with a lock"}
  FROZEN -->|yes| FAIL["fail: lock missing or stale<br/>→ run supabase start locally and commit it"]
  FROZEN -->|no| LEASE["take the project lease<br/>(serializes concurrent starts)"]
  LEASE --> RESOLVE["re-resolve only the services<br/>whose specifier changed"]
  RESOLVE --> WRITE["write supabase.lock atomically"]
  WRITE --> RUN

Loading

A start never calls the Management API and needs no login. It only warns when:

• .link.json targets another project or branch than the lock observed (run supabase stack update);
• this CLI bundles a newer revision of a locked version.

---

Typical workflows

1. New project, never linked

$ supabase start
Resolved service versions:
  database  17.11.0.004-r0  (specifier linked; unlinked)
  auth      v2.197.0-r0  (specifier linked; unlinked)
  realtime  v2.144.2-r0  (specifier linked; unlinked)
  …
Created supabase/supabase.lock.

Nothing is linked yet, so linked falls back to the bundled builds and says so. Commit supabase/supabase.lock, and every teammate and CI job now runs exactly these builds, whatever CLI version they have.

2. Match production: supabase link

$ supabase link --project-ref abcdefghijklmnopqrst
Hosted versions:
  service   hosted       locked          resolution
  database  17.6.1.011   17.6.1.011-r0   resolved
  auth      v2.196.1     v2.196.1-r0     resolved
  realtime  v2.143.0     v2.143.0-r2     resolved
  studio    -            2026.10.12-…    unobserved
  …
Updated supabase/supabase.lock: now observing abcdefghijklmnopqrst (5 version changes). Review and commit it.
Finished supabase link.

link probes the hosted project, or the branch, and records what it runs. Every linked service moves to that release. link writes .link.json and the lock together, under the same project lease as start. The next supabase start runs the hosted versions.

Linking a preview branch works the same way. The lock records which project and branch it observed, so start warns if the checkout's link later points elsewhere.

3. Try one specific version, or a hotfix revision

[local.services.auth]
version = "v2.198.0"

$ supabase start
Resolved service versions:
  auth      v2.196.1-r0 → v2.198.0-r0  (specifier v2.198.0 ≠ locked linked)
Updated supabase/supabase.lock.

Only the changed entry is re-resolved, and every other pin stays where it was. Remove the override to go back to linked. Pinning v2.198.0-r1 selects exactly that revision.

4. A teammate clones the repo, and CI

$ git clone … && cd my-app
$ supabase start          # the lock is fresh: runs the committed builds, no resolution

In CI (CI set and a lock present), start, stack install and link are frozen: a stale or missing lock fails instead of being rewritten.

$ CI=1 supabase start
supabase/supabase.lock is stale for: auth (specifier v2.198.0 ≠ locked linked); run supabase start locally and commit the updated lock

supabase stack install --frozen --runtime native downloads everything the lock pins without creating a stack, which makes it handy as a cached CI warm-up step.

5. Upgrading the CLI

Upgrading never changes locked versions. If the new CLI bundles a newer revision of a version you locked, start mentions it:

$ supabase start
This CLI bundles newer revisions of locked versions: realtime v2.144.2-r0 → v2.144.2-r1. Run supabase stack outdated to review, supabase stack update to adopt them.

$ supabase stack outdated
   SERVICE  | SPECIFIER | HOSTED   | LOCKED      | UPDATE      | BUNDLED     | STATUS           
  ----------|-----------|----------|-------------|-------------|-------------|------------------
   auth     | linked    | v2.196.1 | v2.196.1-r0 | -           | v2.197.0-r0 | up to date       
   realtime | bundled   | -        | v2.144.2-r0 | v2.144.2-r1 | v2.144.2-r1 | update available 
   …
Run supabase stack update to adopt the updates.

$ supabase stack update realtime     # or no argument for every service

stack outdated is read-only. stack update re-resolves the named services even when the lock is fresh:

• an upstream version moves to its newest revision;
• bundled moves to the version this CLI bundles;
• linked probes the hosted project again;
• an exact -rN pin stays.

6. Unlinking

supabase unlink removes .link.json and the stored credential under the project lease. The lock is not touched: it stays a valid, reviewed lock, and its linked entry still shows where the observations came from.

---

Your local data is protected when versions change

Changing a version must never silently corrupt a local database.

Change	What happens
A new revision of the same database build	Accepted
Any other database build (another upstream version or Postgres major, or switching between stock and OrioleDB) with initialized data	Refused. The advice offers pinning the recorded build under [local.services.database] to keep the data (setting [db] major_version back or removing [db] orioledb_version where they would conflict with that pin), or supabase stack destroy --stack-id … (this deletes the local data)
The same change on a database that never initialized	Adopted
Moving auth, storage or realtime back to a version older than one that already migrated this database	Refused: a downgrade doesn't restore the old schema

link and stack update still move linked pins, but they warn when a saved stack's data would refuse the new pins.

The database records the build that initialized it. Each schema-owning service records the newest version that migrated it. Snapshots, restores and db reset carry and respect both records.

---

Stack mode no longer uses supabase/.temp

Before (supabase/.temp)	Now in stack mode
Project ref, pooler URL, branch	supabase/.link.json (gitignored)
Postgres and edge-runtime versions	supabase/supabase.lock
Storage uploads	$SUPABASE_HOME/stacks/<id>/uploads, removed by stack destroy
Scratch files (pgdelta debug bundles, Functions bundling)	$SUPABASE_HOME/tmp
Release-check cache	$SUPABASE_HOME/cli-latest

Delegated Go commands skip .temp too. Remote commands resolve the hosted target once per command, in this order:

1. the --project-ref flag;
2. SUPABASE_PROJECT_ID;
3. the link;
4. the interactive picker.

Three commands change with this beyond the .temp move:

• gen keys resolves its project this way, picker included, and passes it to the delegated command;
• the upgrade notice picks its release-check cache by the project's mode, read from the working directory it was handed;
• db pull builds its shadow database from the locked pins, falling back to the bundled database pin of the major a [remotes] block selects.

supabase stack install replaces the experimental supabase stack prepare.

---

Reading this PR

There is one commit per chunk, in dependency order; each builds on the previous one.

Commit	What it adds
docs(stack)	ADRs 0026 and 0017: the lock-based version model
feat(config)	[local.services] specifiers in the config schema
feat(stack) resolve pins	Resolving slim-services releases with checksum, manifest and provenance verification
refactor(cli) .temp layout	One owner for every legacy .temp path
feat(stack) explicit pin	Every service creation carries the exact pin it runs
feat(cli) .link.json	The hosted link file in stack mode
feat(stack) lock format	The supabase.lock schema, deterministic write, typed read errors
feat(stack) test stacks	@supabase/stack test stacks run the project lock
feat(stack) database build guard	Initialized data is tied to its build
feat(cli) hosted target	One hosted-target resolution per command
feat(stack) schema writers	Refuses older schema writers on migrated databases
feat(cli) lock at start	Resolve and lock at start; --frozen and CI behavior
feat(cli) install	stack install, stack prepare removed
feat(cli) update/outdated	stack update and stack outdated
feat(cli) linked versions	link observes hosted versions and resolves linked
feat(cli) no .temp	Stack mode leaves supabase/.temp alone
feat(cli) Go off .temp	Delegated Go commands do the same
test(cli)	Explicit timeouts on owner-spawning destroy tests

Review fixes and merges from develop follow these commits.

User-facing reference: apps/cli/docs/stack-commands.md and the start side effects.

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Verified all seven findings against the checked-out code and trusted conventions. All seven are confirmed, with no duplicates. The highest risks are arbitrary-registry container execution and premature migration-lease release. Verification was static; tests were not run.

Findings

Severity	Location	Category	Sources	Claim
🔴 CRITICAL	packages/stack/src/Lock.ts:31	security	claude	The lock accepts service images from arbitrary registries. An edited lock can therefore make container-based stack commands or slim Functions tooling execute attacker-published images with the service's credentials and mounts.
🟠 MAJOR	packages/stack/src/Owner.ts:526	concurrency	codex	A failed or interrupted readiness check releases the schema-writer lease before the service process has stopped, allowing another initializer to acquire it while the original process may still be migrating.
🟡 MINOR	apps/cli/src/command-internal/stack-lock.ts:418	correctness	claude	Resolving a stale linked entry during a release-host outage writes a bundled fallback as unobserved. Subsequent starts consider that entry fresh and never retry automatically, even though its hosted version was observed.
🟡 MINOR	apps/cli/src/command-internal/stack-config.ts:983	state-management	codex	Start, install, and update can create or rewrite supabase.lock before remaining configuration translation rejects the command.
🟡 MINOR	packages/config/src/local.ts:5	validation	claude	The config schema accepts upstream versions containing +, but release resolution rejects them as unpublished instead of reporting an invalid version during configuration validation.
⚪ NIT	apps/cli/src/commands/experimental/stack/start/SIDE_EFFECTS.md:270	documentation	codex	The start documentation incorrectly promises that a same-major PostgreSQL upstream build change can restart successfully against initialized data.
⚪ NIT	apps/cli/src/commands/services/SIDE_EFFECTS.md:95	documentation	codex	The services mismatch guidance still describes catalog-only versions and misleadingly says supabase link cannot change them, although displayed stack versions now come from the project lock.

Stats

Claude findings: 3 · Codex findings: 4 · Confirmed: 7 · Refuted: 0 · Uncertain: 0

---

Models: claude-opus-5-5 + gpt-6.1-sol · Trigger: auto · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

[jgoux]

/ai-review

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Verified all eight supplied findings against the surrounding PR code and trusted conventions. All eight hold, with the lease-contention finding narrowed because the API client already applies a request timeout. The main risks are blocked reuse of existing database data, unannounced database-build changes during linking, and incompatible dump-client selection. Verification was static; runtime tests were not run.

Findings

Severity	Location	Category	Sources	Claim
🟠 MAJOR	packages/stack/src/internal/database-reuse.ts:54	backward-compatibility	claude	Previously initialized database data without the new identity file is refused after upgrading, even when the requested stock PostgreSQL major matches. The offered recovery destroys local data.
🟠 MAJOR	packages/stack/src/internal/database-reuse.ts:28	backward-compatibility	claude	Linking or updating can change the default linked database pin to another build within the same stock PostgreSQL major, leaving initialized local data unable to start without warning when the pin changes.
🟠 MAJOR	apps/cli/src/command-internal/db-pull-run.ts:492	correctness	codex	An initial migration-mode db pull using migra in stack mode ignores remote PostgreSQL configuration overrides when selecting its dump image, potentially selecting pg_dump older than the target server.
🟡 MINOR	apps/cli/src/command-internal/stack-lock.ts:418	correctness	claude	A transient release-host failure while resolving a stale linked entry can permanently record a bundled fallback as unobserved, although the hosted version was observed. Subsequent ordinary starts do not retry.
🟡 MINOR	apps/cli/src/command-internal/stack-lock.ts:1200	concurrency	claude	Link and update hold the project lease throughout hosted probing and release resolution, which can exceed the 60-second acquisition budget and make concurrent starts fail with lease-busy.
🟡 MINOR	apps/cli/src/command-internal/stack-lock.ts:905	correctness	claude	Bundled-version reporting compares OrioleDB locks against the stock database pin, suppressing warnings about newer bundled revisions of the locked OrioleDB build and displaying a stock bundled version.
🟡 MINOR	apps/cli/src/command-internal/upgrade-notice.ts:483	correctness	codex	After bootstrap creates a stack-enabled template project from a legacy-mode directory, the upgrade hook can create supabase/.temp/cli-latest inside the new stack-mode project.
⚪ NIT	apps/cli/src/command-internal/stack-lock.ts:688	error-messages	claude	Explicit frozen mode reports that the lock is missing when configuration is absent, even if the lock exists.

Stats

Claude findings: 6 · Codex findings: 2 · Confirmed: 8 · Refuted: 0 · Uncertain: 0

---

Models: claude-opus-5-5 + gpt-6.1-sol · Trigger: manual · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

[avallete]

/ai-review

[avallete]

Dogfooded this at 16ba0b1 (unlinked bootstrap, explicit pins, frozen/CI, linked staging project): the main flows work. A review pass turned up these significant issues:

1. Upgrading leaves existing stacks unusable. packages/stack/src/services/Recipe.ts makes pin required in saved stack state with no migration. State saved by an earlier CLI fails to decode (Missing key at ["pin"]), so start and stack destroy --stack-id both fail. Recovery means deleting the stack directory by hand and leaves the Docker volume orphaned. Data created before this PR also has no identity file, so internal/database-reuse.ts refuses it, and uploads move out of .temp/stack-uploads without being migrated.
2. link and stack update can force a destroy. They move database and schema-owner pins (stack-lock.ts ~1247) without checking the existing data, and the next start refuses the change. The documented "start unlinked, then link" flow hits this. docs/stack-commands.md:352 says only a major or release-line change triggers it.
3. supabase.lock is written as 0600. Lock.ts:212 calls publish() without mode, which defaults to 0o600. That's wrong for a committed file. Fix: pass mode: 0o644, as project-link.ts already does for .gitignore.
4. With no lock, [local.services] pins are ignored. readSelectionOrBundled (stack-lock.ts:647) falls back to bundled pins for shadow, db reset and functions serve. For example, an orioledb database pin gives a stock shadow for db diff until the first start.
5. Link is not atomic. The lock is published (stack-lock.ts:1251) before .link.json is written. A failure in between leaves the lock describing the new remote and the link pointing at the old one.
6. (Moderate confidence) stack destroy deletes the Storage uploads bind-mount source. It removes stacks/<id>/uploads (destroy.handler.ts:162), which Registry.ts:193 warns breaks the file share when the same id restarts. destroy && start is the recovery the errors above recommend.

Smaller items:

• The lease file can end up outside .gitignore.
• stack install downloads disabled services.
• An invalid SUPABASE_EXPERIMENTAL_STACK now fails legacy link/unlink.
• The legacy pooler-URL behavior changed, while the description says legacy mode is unchanged.

[github-actions]

🤖 AI Review

Verified all six findings from both reviews: four confirmed and two refuted. Confirmed issues concern database pin changes and destructive recovery advice, external-service schema-writer bookkeeping, the gen keys picker, and caching-test coverage. Refuted the private-state migration requirement under trusted conventions and the pg-schema regression because stack mode rejects that engine before delegation. The picker finding is confirmed only for gen keys.

Findings

Severity	Location	Category	Sources	Claim
🟠 MAJOR	apps/cli/src/command-internal/stack-lock.ts:1247	data-loss	claude	Linking an existing local stack can change its database build and prevent subsequent starts, without warning about data incompatibility; the resulting error recommends destructive recovery and omits restoring the previous pin.
🟠 MAJOR	packages/stack/src/Owner.ts:514	correctness	codex	A standalone schema-writing service using an external database incorrectly checks and advances the composition's local database migration record, potentially blocking the local service's existing version.
🟡 MINOR	apps/cli/src/command-internal/go-proxy-target-env.ts:10	behavior-regression	claude	In stack mode, gen keys loses its interactive project picker when no flag, environment value, or link supplies a project ref.
🟡 MINOR	apps/cli/src/config/remote-target.layer.integration.test.ts:247	test-quality	codex	The caching test checks tracing implementation details without verifying that repeated resolution preserves the original target after the link changes.

Refuted findings (kept for transparency, not posted as review comments)

• packages/stack/src/services/Recipe.ts:40 (backward-compatibility): Earlier managed-stack state cannot decode after pin becomes required; legacy database identities and Storage upload paths also have no migration.
  Refuted: The incompatibility is real, but requiring migration of this private experimental state conflicts with the trusted compatibility scope. trusted/docs/adr/0017-simplified-managed-stack-architecture.md:37-39 identifies the managed document as private, unreleased state, and :323-326 explicitly permits its format to change with the current build. trusted/CLAUDE.md:146-149 permits reshaping unreleased APIs without compatibility scaffolding, while trusted/apps/cli/CLAUDE.md:97-101 excludes experimental paths from the stable compatibility promise. This does not establish a supported cross-version migration regression.
• apps/cli/src/commands/db/diff/diff.handler.ts:125 (behavior-regression): Stack-mode db diff --use-pg-schema --linked reaches Go without forwarding the linked project ref and fails to find the project.
  Refuted: The claimed delegation is unreachable in stack mode. diff.handler.ts:185-195 calls stackRejectNativeDockerDiffEngine whenever usePgSchema is present. command-internal/stack-local-database.ts:177-184 rejects every stack backend with the explicit message that only pg-delta is supported. stack-backend.ts:27-32 and :123-131 route db commands through that backend selection. The same rejection exists in the trusted default-branch code.

Stats

Claude findings: 4 · Codex findings: 2 · Confirmed: 4 · Refuted: 2 · Uncertain: 0

---

Models: claude-opus-5-5 + gpt-6.1-sol · Trigger: manual · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

[Coly010]

Hey @avallete, thanks for dogfooding this, really useful. @jgoux I've pushed fixes for these onto your branch in 72eab92, hope that's ok! I used the PR description's design as the bar for what to change, so a few of these are push-backs.

1. Upgrading existing stacks. Leaving this one. The saved stack document is private experimental state (ADR 0017), and an old stack already fails with the "could not be read … remove its directory" message, which covers leftover containers and says the volume data stays. Data without a recorded identity is never reused by design, and the old uploads belong to a database that can't be reused anyway.
2. link / stack update forcing a destroy. Agreed, and the description's own unlinked-start-then-link flow hits it. The guards stay, but:
   • link and stack update now check this project's stacks and warn when the new pins would be refused
   • the start refusals offer pinning the recorded version under [local.services] before suggesting destroy (or restoring [db] major_version / orioledb_version when those changed)
   • stack-commands.md now says any build change other than a new -rN revision is refused
3. Lock mode. Fixed, it's written as 0644 now. .link.json stays 0600 since it's gitignored.
4. No lock ignores [local.services]. Fixed. The no-lock fallback still never resolves or touches the network, but it now validates the request, serves a database version the CLI bundles, and fails any other explicit pin with "run supabase start to create it". fwiw the [db] orioledb_version shorthand already picked the right line there, it was the [local.services] form that got dropped.
5. Link atomicity. Two files can't be atomic, but the order mattered: with the lock first, the next start's advice (stack update) would revert to the old remote. It now writes .link.json first, then the lock, so a partial state is repaired by the warning's own advice.
6. Destroy removing uploads. Leaving this, I think. start recreates uploads before Storage mounts it, the same way destroy already removes each data/<instance> root that containers bind-mount, and the Registry note is about keeping the stack and data ancestors, which stay. I didn't reproduce it live on Docker Desktop though, so shout if you saw it actually break.

Smaller ones:

• Lease file outside .gitignore. Fixed, taking the lease now adds the entry. Frozen starts read the lock without the lease, so they still leave the project untouched.
• stack install downloading disabled services. Leaving this one, since the description has install fetching everything the lock pins (like pnpm install) as the CI warm-up step.
• Invalid SUPABASE_EXPERIMENTAL_STACK on link/unlink. Keeping the failure. link and unlink now need the mode to know where the link lives, and every routed command already rejected the value on develop. It's documented as an exit code in their SIDE_EFFECTS now, with a test.
• Legacy pooler URL. You're right that it changed. Keeping it, because develop reused the linked project's saved .temp/pooler-url for a different --project-ref or SUPABASE_PROJECT_ID, which connected to the wrong project's pooler. I've documented it in the affected SIDE_EFFECTS. @jgoux might be worth qualifying the "legacy mode does not change" line in the description.

Happy to revisit any of the push-backs if you disagree!

[avallete]

Thanks @Coly010, the fixes in 72eab92 hold up. Approving to unblock; the items below are follow-ups, not blockers.

Verified

• Re-dogfooded at 72eab92 (Docker runtime, one throwaway staging project):
  • Lock is 0644.
  • The lease entry is added to .gitignore.
  • --frozen and CI=1 leave the project untouched.
  • With no lock, a bundled [local.services] pin is served and an unbundled pin fails with "run supabase start to create it".
  • Link writes .link.json before the lock.
  • Link warns about the conflict, and the next start's refusal offers the pin first. Adding that pin lets start reuse the data, and the row survives.
  • Destroy then start: Storage uploads work again. I accept that pushback.
• Pushbacks I agree with: upgrading existing stacks (ADR 0017), install fetching every pinned service, the invalid SUPABASE_EXPERIMENTAL_STACK error, and the legacy pooler URL change.

Remaining edge cases in the new paths

1. packages/stack/src/internal/database-reuse.ts:62
   • The refusal advice suggests restoring [db] major_version / orioledb_version but ignores an explicit [local.services.database] pin.
   • Example: stock data, then a switch to an explicit OrioleDB pin. The advice tells the user to restore a [db] setting that was never changed, which either repeats the refusal or fails validation while the pin is still set.
2. packages/stack/src/internal/data-conflicts.ts:69
   • An interrupted Docker start can leave PG_VERSION and a recorded build but no readiness marker.
   • The link / stack update check treats this as fresh and stays silent, but the next start's storage prepare checks the build and refuses it.
   • The test at data-conflicts.integration.test.ts:108 asserts that silence.
   • Two independent review passes flagged this; I did not reproduce it live.

Cleanup

• bindsDatabaseUrl (Owner.ts:744) is always true, and the Supabase.unit.test.ts test exists only to pin it. Both can go.
• The data-conflict cases are tested in the stack package, in link.lock.integration.test.ts and in update.integration.test.ts.
  • The two handler files could each keep about 3 wiring tests (warns, quiet, unreadable state still succeeds).
  • The interrupted-start case is also duplicated between data-conflicts.integration.test.ts and database-reuse.unit.test.ts.
• The comment at stack-data-conflicts.ts:8 says one warning per stack, but the loop warns once per conflict.
• Changes the reply doesn't mention: the gen keys project picker, the mode lookup in upgrade-notice.ts, and the switch in db-pull-run.ts to remote-aware selection. Worth a line in the PR description.
• Smaller dogfood notes:
  • With no lock and an unbundled pin, supabase services only warns and lists the defaults instead of failing.
  • In the same setup, functions serve ends with "Functions service stopped or became unhealthy" rather than the lock error.