@everystack/server 0.4.26 → 0.4.28

package/CHANGELOG.md

@@ -0,0 +1,300 @@
+# Changelog
+
+All notable changes to `@everystack/server` are documented here.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.4.28] - 2026-09-02
+
+### Added
+
+- wire proveDescent into db:apply — ledger read shares the lock session
+- retire --force-descent for the git-native escape + a proven-lineage-lost attestation
+- the stage lane's fast-forward rule is structurally non-droppable (q1-fail-closed)
+- version the db:apply wire contract, both directions (q1-contract-version)
+
+### Fixed
+
+- split-brain belt + correct the version-skew remedy (closing gate)
+
+### Changed
+
+- delete the orphaned recompile-descent helpers, rewire the illusion of coverage (F1)
+
+## [0.4.26] - 2026-08-15
+
+### Fixed
+
+- route rotation DB ops through the ops Lambda (VPC)
+
+## [0.4.25] - 2026-08-15
+
+### Fixed
+
+- resolve all closing-gate findings (F1-F8) on Phase B
+- resolve re-review findings N1-N4
+
+## [0.4.24] - 2026-08-15
+
+### Added
+
+- auto-call initCredentials on Lambda cold start
+
+### Changed
+
+- read credentials from SST secret store, not individual SSM params
+
+## [0.4.23] - 2026-08-15
+
+### Added
+
+- runtime SSM credential resolution for live rotation
+- A/B rotation pair provisioning for credential rotation
+- A/B rotation logic — detect, provision, retire, drain
+
+## [0.4.22] - 2026-08-14
+
+### Added
+
+- emit x-everystack-release/runtime/created headers from SSR
+
+### Fixed
+
+- clear Metro module registry on SSR bundle swap
+
+## [0.4.21] - 2026-08-14
+
+### Fixed
+
+- the destructive-apply gate refuses an image-computed fingerprint
+- close the closing-gate findings on the backup fingerprint path
+- bind the fixes to checks that fail, and correct the retraction order
+
+### Documentation
+
+- the operator credential is the ops channel only
+- db:provision cannot split a local developer's credentials
+
+## [0.4.20] - 2026-08-12
+
+### Fixed
+
+- the example app compiled its tests with type checking off
+
+## [0.4.19] - 2026-08-05
+
+### BREAKING CHANGES
+
+- seed and db:reset are declared, not inferred from a stage name
+
+### Added
+
+- a cheat gate for stage-name-as-trust-boundary, and the sweep that found two more
+
+## [0.4.18] - 2026-08-05
+
+### Fixed
+
+- a 500 returns a request id, never the error text
+
+## [0.4.17] - 2026-08-04
+
+### Fixed
+
+- db:doctor printed two remediations that break what they protect
+
+## [0.4.16] - 2026-08-04
+
+### Added
+
+- db:session — N statements, one connection, one transaction
+
+### Fixed
+
+- route every introspection through one session, and delete the bare SET
+
+## [0.4.15] - 2026-07-28
+
+### Added
+
+- expose WAF/caching as an MCP resource — fix the 403-every-PostgREST trap
+
+### Fixed
+
+- TCP keepalives on every long-running pg binary
+
+## [0.4.14] - 2026-07-23
+
+### Added
+
+- the bring-your-own-database operator path — direct db:provision + optional migrations
+- sstResource() — read any SST link without importing sst
+- credential-free db:reconcile — the derived-edge ops lane — server 0.4.8 + cli 0.4.22
+- credential-free operator lanes — db:refresh --stage + db:doctor direct venue — server 0.4.9 + cli 0.4.23
+- db:refresh --verify-nonempty — the credential-free dark-panel gate — server 0.4.11 + cli 0.4.25
+- db:operator-url ops action — the --direct/db:swap --stage foundation
+- db:apply --direct — the credential-free unbounded-clock write lane
+- db:backfill --stage — the missing stage lane for data jobs
+- search_path lives on the role, not the URL (the real fix)
+- db:exec — DML-only by semantic catalog digest, no role or superuser
+- db data-movement Phase 2 — ephemeral Fargate Task lane for pg-binary work
+- db data-movement Phase 3a — db:backup/db:export run in the ephemeral Task lane
+- db data-movement Phase 3b foundation — snapshot-verify gate + shared live fingerprint
+- db data-movement Phase 3b — destructive apply gated on a verified backup
+- db data-movement — restore→Fargate + delete the pg-tools layer
+
+### Fixed
+
+- drop the `sst` import — read SST links from process.env, unbreak every bundle — 0.4.5
+- resolve SST links delivered via the encrypted key file — 0.4.7
+- db:reconcile --only <ids> — the recovery exit from a mistaken --rebaseline — server 0.4.10 + cli 0.4.24
+- opaque the expo-router loader-data blob so crawlers can't harvest /index URLs
+- db data-movement — Fable build-gate fixes (Task S3 grant + provable fp)
+- full backup excludes the everystack ops schema (restore --clean choked on it)
+
+## [0.4.4] - 2026-07-17
+
+### Fixed
+
+- createDb honors an explicit sslmode in the connection URL
+
+## [0.4.3] - 2026-07-16
+
+### Added
+
+- canonical-sync artifact verbs (gap B)
+
+## [0.4.2] - 2026-07-16
+
+### Added
+
+- pgDumpLayer() declarative layer resource; deprecate PGDUMP_LAYER_ARN
+- zero-config backup-layer guidance — probe/doctor/apply preflight
+
+### Fixed
+
+- the flip guidance can no longer dark-site an API — rides server 0.4.0
+- admin role grants are cycle-safe and adoptive — 0.4.1
+
+## [0.4.0] - 2026-07-15
+
+### Added
+
+- credential-free staged db:apply
+- ingest pipeline framework (Phase 3, Bricks 1-3)
+- surface pipeline last-run in db:sync/db:plan (Phase 3, Brick 4)
+- credential-free pipeline:run --stage (Phase 3, Brick 5)
+- WAF rate limiting answers 429 + Retry-After, not the default 403
+- live drift + doctor — what the content hashes can't see (Brick B4, read-model-everywhere)
+- built-in _health action; the seed module loads lazily — 0.3.6
+- db:provision provisions BOTH sides of the credential split — 0.3.7
+- forward-port afterRpc + read-replica routing from the 0.2.x line
+
+### Fixed
+
+- optional-peer AWS clients fail clean
+
+## [0.3.3] - 2026-07-04
+
+### Added
+
+- IAM auth for web deploys, replace Sharp layer with SST bundling
+- rename @everystack/updates → @everystack/cli, add db:migrate/db:seed, remove AdminSecret
+- add StorageAdapter head(), ETag-based SSR reload, SigV4a for KVS
+- add mode: postgres — pgcrypto auth via postgres.js
+- configurable per-origin cache headers + image EXIF fix
+- consolidate drizzle migrations + logging schema updates
+- add afterExtract hook to WebHandlerOptions
+- EAS-compatible OTA updates — branches, groups, channels, SSR
+- add web publish versioning matching mobile pattern
+- add X-Bundle-Key response header to SSR for debugging
+- add optional logSink for structured request logging
+- cdn auth helper — verify JWTs at the edge (no Lambda hop)
+- composeViewerRequest + Feature interface + minifier
+- cookie-based SSR authentication
+- compact CFF verifier + dead code stripping for 10KB budget
+- move hydration fixes into framework, remove auth cache splitting
+- add `everystack diag` command for deployed page freshness diagnostics
+- add plugin architecture for composable Lambda handlers
+- extract ssrPlugin into @everystack/server/plugin
+- extract generic actions into package plugins
+- add auth plugin with layered security and client credentials
+- replace publicPaths with requireAuth pattern
+- add publicMethods to authFeature for anonymous reads at edge
+- add SQS adapter for progressive job dispatch
+- S3 origin cache for processed images
+- HEIC decode fallback via heic-decode, passthrough for unsupported formats
+- content-addressed asset deduplication, fix Metro resolution
+- add EventBridge Scheduler support for cancel/reschedule
+- add createSecrets helper and transparent naming support
+- expose ctx, notifications, and rpc in console eval scope
+- add ActiveRecord-style model layer for console
+- add dot commands and schema introspection
+- add auth context with login, asUser, and pgSettings
+- add sandbox mode for safe exploration
+- add .login with hidden password, current_user in scope, history redaction
+- add content-hash fingerprinting for media assets
+- split operator credential from the API connection
+- add cache-state + timing observability headers to image handler
+- edge request id as traceId + shared timing headers
+- migration runner that cannot lie
+- fail-closed bundle-boundary guard (@everystack/server/testing)
+- web bundle guard (assertWebBundleClean)
+- withRole/roleFor + explicit DATABASE_URL precedence
+- db:doctor — verify the DB is least-privilege + RLS-subject
+- db:provision — the role provisioner + db:doctor remediation
+- least-priv client auth (invoker+RLS) + db:doctor auth.users carve-out
+- make db:doctor FORCE-RLS carve-outs app-configurable
+- ship jest-preset so consumers can import @everystack/server/testing
+- db:authz:test + the db:authz:probe ops action — red-team a deployed stage
+- db:doctor enforces "app-reachable tables require RLS"
+- db:backup B1 — pg_dump layer + version-gate probe
+- db:backup B2 — pg_dump/pg_restore ops actions, streamed to S3
+- db:doctor functions teeth + derive every FORCE carveout
+- db:fork — branch stages fork the database, not just the code (branch-stages brick 1+2)
+
+### Fixed
+
+- replace crossfilter2 with plain JS, fix ESM test failures
+- drop immutable from image default — use consistent 60s browser TTL
+- require crypto module in CFF verifiers, strip routeSite
+- skip edge auth for non-API paths when tableFromPath is enabled
+- psql Lambda-only queries, composite key notify, logging defaults
+- include stubs directory in published package
+- resolve 5 deployment issues from first external testing
+- resolve 7 high-priority security findings from red team audit
+- fix sharp mock and S3Client mock for ESM test compatibility
+- resolve auth test failures and logging build error
+- pin all dependency versions to lockfile-resolved values
+- strip _a auth flag from CFF query params
+- upscale source to fill box when fit=cover, passthrough non-image files
+- handle HEIC decode failures, oversized passthrough, uncached errors
+- replace infrastructure headers with single X-Server-Debug timestamp
+- version bumps and publish fixes for cli, server, jobs
+- enforce RLS by default and handle unstringifiable results
+- ops Lambda boots the full app so the console keeps rpc/jobs
+- short edge TTL for SSR HTML so it refreshes within 60s
+- never public-cache cookie-authenticated SSR responses
+- release-unique SSR build dir so warm Lambdas pick up new releases
+- operator connection falls back to master, never the authenticator
+- correct jest-preset usage example in doc comment
+- jest-preset self-pins @everystack/server/testing (cold-cache TS2307)
+- detect HEIC by magic bytes, not Sharp
+
+### Changed
+
+- extract server infra into @expo-stack/server + @expo-stack/auth packages
+- migrate all package schemas to everyschema canonical tables
+- consolidate authorization to PostgreSQL as single source of truth
+- extract generic code to packages, remove dead code
+- drop type module from all packages, switch Jest to CJS mode
+- consolidate Jest configs into shared base
+- fold ops handler into createPluginLambdaHandler({ http: false })
+
+### Documentation
+
+- rewrite documentation around V1→V2→V3 progressive complexity model
+- prepare documentation for open-source release
+- close remaining security punchlist items (L6, M3)
+- warn that jest-preset owns `transform` (the TS2307 footgun)
+- v3 (0.3.0) documentation review — accurate READMEs + guides

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.4.26",
+  "version": "0.4.28",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -20,7 +20,8 @@
     "src",
     "stubs",
     "jest-preset.js",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "exports": {
     ".": {
@@ -186,8 +187,8 @@
     "sst": "4.13.1",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/cli": "0.4.65",
-    "@everystack/auth": "0.4.3"
+    "@everystack/cli": "0.4.70",
+    "@everystack/auth": "0.4.4"
   },
   "scripts": {
     "test": "jest",

package/src/plugin.ts

@@ -12,6 +12,18 @@ import type {
   APIGatewayProxyEventV2,
   APIGatewayProxyStructuredResultV2,
 } from 'aws-lambda';
+import type { ApplyPlanOptions } from '@everystack/cli/apply';
+
+/**
+ * The stage lane's apply options, with `checkDescent` made REQUIRED. The fast-forward rule is the
+ * one gate that crosses the wire on every stage apply (additive included); typing it non-optional
+ * here forbids the conditional spread that once let a missing descent verdict silently skip it.
+ * verifyAuthority/verifySnapshot stay optional — they are destructive-only, and the stage lane
+ * refuses destructive plans outright, so they never arise on this lane.
+ */
+type StageApplyOptions = ApplyPlanOptions & {
+  checkDescent: NonNullable<ApplyPlanOptions['checkDescent']>;
+};
 import {
   createRouter,
   eventToRequest,
@@ -191,11 +203,17 @@ export function createPluginLambdaHandler(
       // the action lookup (it must answer even when initialization itself is the failure) and
       // reserved: an app action named `_health` is never reached.
       if (event._action === '_health') {
+        // q1-contract-version direction B: advertise the db:apply wire-contract version so a NEWER
+        // CLI detects an OLDER deployed stage BEFORE it dispatches a write (prevention, not a
+        // post-write alarm). Stamped on BOTH branches, so a stage whose DB init is failing still
+        // tells the CLI its contract — an absent field means the deployed server predates the
+        // handshake. Old servers simply omit it; the CLI reads absent as "redeploy the stage".
+        const { APPLY_CONTRACT_VERSION } = await import('@everystack/cli/apply');
         try {
           const { actions } = await ensureInitialized();
-          return { ok: true, mode: httpEnabled ? 'http' : 'ops', actions: Object.keys(actions).sort() };
+          return { ok: true, mode: httpEnabled ? 'http' : 'ops', actions: Object.keys(actions).sort(), applyContract: APPLY_CONTRACT_VERSION };
         } catch (error) {
-          return { ok: false, error: String(error) };
+          return { ok: false, error: String(error), applyContract: APPLY_CONTRACT_VERSION };
         }
       }
       const { ctx, actions } = await ensureInitialized();
@@ -800,9 +818,9 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
     // --- db:provision — BOTH sides of the credential split, in the safe order ---
     // Runs as the operator and creates ONLY roles (no database, no tables, no schema), so
     // it is safe on an existing database: an app that brings its own DATABASE_URL can run
-    // this to adopt the least-privilege split without re-provisioning anything. The
-    // auto-provisioning construct invokes it at deploy time with a generated password.
-    // With adminPassword, also creates the operator login (migrator) and VERIFIES its
+    // this to adopt the least-privilege split without re-provisioning anything. It is
+    // ADDITIVE-ONLY: an already-live login role keeps its password (only db:provision --rotate
+    // changes an existing one). With adminPassword, also creates the operator login (migrator) and VERIFIES its
     // real connectivity BEFORE the authenticator password is set — the ordering that
     // keeps a BYO-database app from sawing off its own ops plane (see provision.ts).
     actions['db:provision'] = async (payload, _ctx) => {
@@ -829,6 +847,15 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
         {
           execute: async (statement) => opsDb.execute(sql.raw(statement)),
           connection,
+          // Additive-only: an already-live login role keeps its password (never reset on re-provision).
+          roleHasLogin: async (role) => {
+            const res: any = await opsDb.execute(sql`SELECT 1 FROM pg_roles WHERE rolname = ${role} AND rolcanlogin`);
+            if (Array.isArray(res)) return res.length > 0;
+            if (Array.isArray(res?.rows)) return res.rows.length > 0;
+            // Unrecognized driver shape — PRESERVE the credential. Skipping a password is recoverable
+            // (the CLI half-done guard catches it); resetting a live one on a false-negative is the lockout.
+            return true;
+          },
           connectProbe: async (url) => {
             const { default: postgres } = await import('postgres');
             // 'prefer' handles both TLS-required RDS and plain local Postgres.
@@ -949,12 +976,21 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
     // direct --database-url path runs, only here the connection never leaves the
     // Lambda. A destructive plan snapshots first (db:backup), in order.
     actions['db:apply'] = async (payload, ctx) => {
-      const { plan, actor, gitRef, descentVerdict, authorityVerdict, stage, snapshotRef } =
+      const { plan, contractVersion, actor, gitRef, dirty, descentVerdict, descentAttested, authorityVerdict, stage, snapshotRef } =
         (payload ?? {}) as {
           plan?: any;
+          /** The CLI's db:apply wire-contract version. Checked for EXACT equality against this
+           *  server's APPLY_CONTRACT_VERSION — a skew refuses before any write (direction A). */
+          contractVersion?: number;
           actor?: string | null;
           gitRef?: string | null;
+          /** The CLI applied from a dirty worktree — recorded on the schema_log witness so a
+           *  later descent ignores this row's git_ref. */
+          dirty?: boolean;
           descentVerdict?: { ok: boolean; reason?: string };
+          /** When the CLI honoured a --attest-lineage-lost waiver, the note to record in the
+           *  schema_log outcome — the durable audit of the deliberate descent waiver. */
+          descentAttested?: string;
           authorityVerdict?: { ok: boolean; reason?: string };
           stage?: string;
           /** An explicit backup id to verify; absent → the gate auto-resolves the stage's newest. */
@@ -963,10 +999,29 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       if (!plan || typeof plan !== 'object' || !Array.isArray(plan.statements)) {
         return { error: 'db:apply requires { plan } — a reviewed edge minted by db:plan' };
       }
-      const { executeApplyPlan, PLAN_VERSION } = await import('@everystack/cli/apply');
+      const { executeApplyPlan, PLAN_VERSION, APPLY_CONTRACT_VERSION } = await import('@everystack/cli/apply');
       if (plan.v !== PLAN_VERSION) {
         return { error: `plan version ${plan.v} is not this server's ${PLAN_VERSION} — re-mint with a matching db:plan` };
       }
+      // q1-contract-version direction A: the db:apply WIRE CONTRACT (payload keys + the gates this
+      // server runs from them) is versioned apart from the plan. An exact-equality mismatch — an
+      // older CLI that declares none, or a bumped one — refuses before any write, so a renamed or
+      // dropped payload key can never ride through as a silently skipped gate. Redeploying the
+      // stage's ops Lambda ships the matching cli it bundles, so the versions realign together.
+      if (contractVersion !== APPLY_CONTRACT_VERSION) {
+        // This fires only for an OLDER CLI: a current CLI catches the skew at the _health handshake and
+        // never dispatches. So the remedy leads with upgrading the CLI, not redeploying the (current) stage.
+        return { error: `this db:apply payload declares apply-contract v${contractVersion ?? '(none)'} but this stage's ops Lambda enforces v${APPLY_CONTRACT_VERSION} — your everystack CLI is older than the deployed stage. Upgrade the CLI to match (or, if the stage was rolled back, redeploy it); nothing was applied.` };
+      }
+      // q1-fail-closed: descent (the fast-forward rule) is the one gate that crosses the wire on
+      // EVERY stage apply, additive included. It is NOT waivable by omission. A payload with no
+      // well-formed descent verdict is an older CLI or a malformed client — refuse before any write,
+      // never silently skip the rule. (The conditional-spread that let a missing verdict skip
+      // checkDescent was the INFO-1 bug; StageApplyOptions now forbids dropping the hook, and this
+      // guards the evidence that feeds it.)
+      if (!descentVerdict || typeof descentVerdict.ok !== 'boolean') {
+        return { error: 'this db:apply payload carries no descent verdict — the fast-forward rule cannot be waived by omission. Upgrade the everystack CLI (an older CLI omits it), or this is a client bug.' };
+      }
 
       const { sql } = await import('drizzle-orm');
       const runner = async (query: string): Promise<any[]> => {
@@ -986,14 +1041,17 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       const SNAPSHOT_FRESHNESS_MS = 60 * 60_000;
       let snapshotId: string | undefined;
       try {
-        const result = await executeApplyPlan(runner, session, plan, {
+        // checkDescent is REQUIRED by StageApplyOptions — no conditional spread can drop it. The
+        // verdict is guaranteed well-formed by the guard above; the hook enforces + records it here,
+        // in order, atomic with the lock. Authority/snapshot stay conditional (destructive-only, and
+        // the stage lane refuses destructive outright, so they never light up on this lane).
+        const applyOptions: StageApplyOptions = {
           actor: actor ?? null,
           gitRef: gitRef ?? null,
-          // Descent/authority are decided by the CLI (checkout + caller identity)
-          // and enforced + recorded here, in order, atomic with the lock.
-          ...(descentVerdict
-            ? { verifyDescent: async () => (descentVerdict.ok ? { ok: true as const } : { ok: false as const, reason: descentVerdict.reason ?? 'descent refused' }) }
-            : {}),
+          dirty: dirty === true,
+          checkDescent: async () => (descentVerdict.ok ? { ok: true as const } : { ok: false as const, reason: descentVerdict.reason ?? 'descent refused' }),
+          // A honoured --attest-lineage-lost waiver is recorded in the schema_log outcome.
+          ...(descentAttested ? { descentNote: () => descentAttested } : {}),
           ...(destructive && authorityVerdict
             ? { verifyAuthority: async () => (authorityVerdict.ok ? { ok: true as const } : { ok: false as const, reason: authorityVerdict.reason ?? 'authority refused' }) }
             : {}),
@@ -1021,8 +1079,11 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
                 },
               }
             : {}),
-        });
-        return snapshotId ? { ...result, snapshotId } : result;
+        };
+        const result = await executeApplyPlan(runner, session, plan, applyOptions);
+        // Echo the contract version the write ran under (SHOULD, legibility — the safety mechanism is
+        // the pre-transaction refusal above, not this field).
+        return { ...result, contractVersion: APPLY_CONTRACT_VERSION, ...(snapshotId ? { snapshotId } : {}) };
       } catch (err: any) {
         return { error: err?.message || String(err) };
       }

package/src/provision.ts

@@ -48,6 +48,16 @@ export interface ProvisionDeps {
   connection?: { host: string; port?: number | string; database: string } | null;
   /** Real login attempt as the admin role — resolves on success, throws on failure. */
   connectProbe?: (url: string) => Promise<void>;
+  /**
+   * Does this role ALREADY exist with LOGIN? When it does, provision is ADDITIVE-ONLY:
+   * it preserves the live password instead of resetting it. A plain `db:provision` used to
+   * `ALTER ROLE … WITH LOGIN PASSWORD` unconditionally, so re-running it on a stage whose
+   * secrets already matched rewrote the live password to a fresh value — and if the CLI
+   * then failed to write the secret, the stage was locked out (needed the RDS master to
+   * recover). Only `--rotate` changes an existing password. Absent → treated as
+   * not-existing (the role is being created now, so its password IS set).
+   */
+  roleHasLogin?: (role: string) => Promise<boolean>;
 }
 
 export interface ProvisionResult {
@@ -89,9 +99,16 @@ export async function runProvision(
     return { error: err?.message || String(err) };
   }
 
+  // Existence check BEFORE the role chain runs — the chain CREATEs the roles, so after it
+  // every role "exists". A role that already had LOGIN *before* this run is a live credential
+  // we must not reset (additive-only); one created now gets its password set.
+  const login = loginRole ?? 'authenticator';
+  const admin = adminRole ?? 'migrator';
+  const authExisted = !!authPassword && !!deps.roleHasLogin && (await deps.roleHasLogin(login));
+  const adminExisted = !!adminPassword && !!deps.roleHasLogin && (await deps.roleHasLogin(admin));
+
   await deps.execute(roleSql);
 
-  const login = loginRole ?? 'authenticator';
   const result: ProvisionResult = {
     provisioned: true,
     loginRole: login,
@@ -107,35 +124,43 @@ export async function runProvision(
 
   // Admin side FIRST — created and verified before the authenticator swap can happen.
   if (adminPassword && adminSql) {
-    const admin = adminRole ?? 'migrator';
     await deps.execute(adminSql);
-    await deps.execute(`ALTER ROLE ${admin} WITH LOGIN PASSWORD '${adminPassword}';`);
+    result.adminRole = admin;
     // The operator role gets the same role-default search_path — this is the role db:swap/apply/
     // reconcile --direct connect as, so a clean URL (no ?search_path=) still resolves bare refs.
+    // Safe + idempotent even when adopting an existing role.
     const adminSearchPathSql = searchPath ? generateSearchPathSQL(admin, searchPath) : null;
     if (adminSearchPathSql) await deps.execute(adminSearchPathSql);
-    result.adminRole = admin;
-    result.adminPasswordSet = true;
-
-    if (deps.connection && deps.connectProbe) {
-      const { host, port, database } = deps.connection;
-      const url = `postgresql://${admin}:${adminPassword}@${host}:${port ?? 5432}/${database}`;
-      try {
-        await deps.connectProbe(url);
-        result.adminVerified = true;
-      } catch (err: any) {
-        // The whole point of the ordering: a broken admin login must abort the swap,
-        // or a BYO-database app loses its only privileged path.
-        return {
-          error:
-            `admin login verification failed for role '${admin}': ${err?.message || String(err)} — ` +
-            'the authenticator password was NOT set and DATABASE_URL must not be rewritten.',
-          adminRole: admin,
-          adminVerified: false,
-        };
-      }
+
+    if (adminExisted) {
+      // Additive-only: the operator login already exists with a password the app is using.
+      // Do NOT reset it, and do NOT probe with a password we never set (--rotate changes it).
+      result.adminPasswordSet = false;
+      result.adminVerified = null; // unchanged — verify via db:doctor
     } else {
-      result.adminVerified = null; // no way to probe — caller should verify via db:doctor
+      await deps.execute(`ALTER ROLE ${admin} WITH LOGIN PASSWORD '${adminPassword}';`);
+      result.adminPasswordSet = true;
+
+      if (deps.connection && deps.connectProbe) {
+        const { host, port, database } = deps.connection;
+        const url = `postgresql://${admin}:${adminPassword}@${host}:${port ?? 5432}/${database}`;
+        try {
+          await deps.connectProbe(url);
+          result.adminVerified = true;
+        } catch (err: any) {
+          // The whole point of the ordering: a broken admin login must abort the swap,
+          // or a BYO-database app loses its only privileged path.
+          return {
+            error:
+              `admin login verification failed for role '${admin}': ${err?.message || String(err)} — ` +
+              'the authenticator password was NOT set and DATABASE_URL must not be rewritten.',
+            adminRole: admin,
+            adminVerified: false,
+          };
+        }
+      } else {
+        result.adminVerified = null; // no way to probe — caller should verify via db:doctor
+      }
     }
   }
 
@@ -154,7 +179,6 @@ export async function runProvision(
     }
 
     if (adminSql) {
-      const admin = adminRole ?? 'migrator';
       // Admin pairs need owner membership to run DDL (F4 fix)
       const adminPairSql = generateRotationPairSQL(admin, 'INHERIT NOBYPASSRLS');
       await deps.execute(adminPairSql);
@@ -176,7 +200,9 @@ export async function runProvision(
   }
 
   // Authenticator LAST — only reached when the admin side (if requested) held up.
-  if (authPassword) {
+  // Additive-only: skip the password when the authenticator already exists as a live login,
+  // so a re-provision never rewrites the credential the app is currently using.
+  if (authPassword && !authExisted) {
     await deps.execute(`ALTER ROLE ${login} WITH LOGIN PASSWORD '${authPassword}';`);
     result.passwordSet = true;
   }