@voltro/database 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -39,6 +39,133 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.15.0] — 2026-07-27
+
+### ⚠ BREAKING
+
+- **@voltro/cli** — **A rename now carries the ALIASED importers, not only the relative ones.**
+
+  An app's web build stopped compiling after `voltro update`: 84 relative imports were rewritten correctly, 163 aliased ones across 88 files were not, and `tsc` reported 249 errors on names that no longer existed. Nothing in the codemod's output hinted that a whole class of import had been skipped.
+
+  Two independent halves, and each alone leaves the imports stale:
+
+  - The codemod's ts-morph project was built with **no `baseUrl` and no `paths`**, so `@/components/link` resolved to nothing. It now gets the compiler's own shape — the raw `paths`, not the pre-resolved Vite table, because a `paths` target is relative to `baseUrl` by definition and an absolute one does not resolve. - `SourceFile.move()` rewrites relative specifiers and **nothing else**, which is correct on its own terms: ts-morph cannot know whether the alias mapping or the file is meant to change. So the codemods now rewrite the aliased ones themselves, narrowly — only specifiers that RESOLVED to the moved file, and only the trailing stem, which needs no alias table and so cannot disagree with one. The run reports how many it rewrote.
+
+  **A file an exact `paths` entry names is left alone and reported.** Renaming `link.tsx` while `"@/link": ["src/components/link.tsx"]` points at it leaves the mapping resolving to nothing — and the same path is usually repeated in a vite/vitest alias table no codemod owns. One app hit this and then saw a taxonomy violation reported on a file the codemod had itself created.
+
+  **`page/unsuffixed-in-pages` is now an error, not a warning.** The comment justifying the warning contradicted the scanner it described: that bucket is already narrowed to a default export nothing imports, which is what an unmigrated page looks like and what a co-located component never does. The failure it names is invisible everywhere else — an unmigrated route simply 404s, with a clean `tsc` and a green suite. One app finished a migration with 51 of them. `codemod: none`: the rename it asks for already ships as `0.14.0/03_pages-suffix`, and nothing about a user's SOURCE changes here — what changes is that `voltro check` now fails on a route that does not route.
+- **@voltro/protocol, @voltro/client, @voltro/web** — **`errorTag` moves from `@voltro/client` to `@voltro/protocol`.**
+
+  It reads the `_tag` that `toRpc` writes, so it now lives beside `toRpc` — one file owning both ends of that contract. Where it used to live had a cost invisible from inside the framework: an app's shared error handler sat in a package that pulled only `@voltro/i18n`, and reading a tag would have meant depending on the entire client package for seven lines. They declined, and kept parsing message strings with a regex — the exact outcome the helper exists to prevent.
+
+  `@voltro/web` re-exports the client surface, so it loses the symbol too — the same codemod covers an app that imported it from there.
+
+  Not re-exported from `@voltro/client`: two import paths for one helper is how the next reader learns the wrong one. The transform codemod repoints the import, preserving an alias (`errorTag as tagOf`) and the type-only form, and merges into an existing `@voltro/protocol` import rather than adding a second.
+
+  While moving it, its doc comment gained the thing that matters at the call site and was only implied before: **`instanceof` does not hold on the client.** What arrives there was decoded from JSON and never constructed, so match on the tag, not on the class. One team read the old wording as a promise that `instanceof` works and was right to say so.
+
+### Added
+
+- **@voltro/protocol, @voltro/cli** — **An auth strategy reaches the app's DataStore, on `input.store`.**
+
+  ```ts
+  const sessionStrategy: AuthStrategy = {
+    id: 'db-session',
+    resolve: async ({ headers, store }) => {
+      if (store === undefined) return { kind: 'skip' }        // still booting
+      const [row] = await store.query(sessions.byToken(headers.authorization))
+      return row ? { kind: 'matched', subject: toSubject(row) } : { kind: 'skip' }
+    },
+  }
+  ```
+
+  Without it, a DB-backed strategy — a session row, an API-key record, a PAT table — had to open a SECOND connection path beside the framework's, to the same database the request store opens a moment later. One adopter's `auth/db.ts` is 105 lines of exactly that: a second `ManagedRuntime` plus a `MysqlClient`, load-bearing for their session lookup and their ApiKeyStore. Every DB-backed OIDC / SAML / PAT integration rebuilds it, which is what made this a framework gap rather than an app's problem.
+
+  It is the **same value** `auth.resolveScopes` already receives, through the **same lazy getter** — one ref, two consumers, rather than each caller reaching for the store its own way. That is deliberate: `voltro dev` builds the store AFTER the auth chain and `voltro serve` builds it BEFORE, so a value captured at config time would be `undefined` forever in dev and correct in production. The getter is read ONCE per request, not once per strategy.
+
+  `store` is `undefined` only while the store is still being built, and on an app with no store — a strategy should `skip` rather than throw. It is the BOOT store, not a request-scoped one: strategies resolve before a request store exists.
+
+  **Not narrowed to a read-only surface**, and the reason is worth stating: the narrower type would be the better guarantee, `DataStore` is the driver SPI, and giving strategies a different type from the one `resolveScopes` gets would put two views of one object in the same file. A strategy that writes during subject resolution is a design mistake; the type system is not going to catch it for you. Read users / sessions / keys, do not run domain writes.
+
+### Fixed
+
+- **@voltro/cli** — `voltro dev` terminates when its dev server does, instead of living forever.
+
+  The supervisor never watched its child die. `runChild` was an `Effect.acquireUseRelease` whose `use` was `Effect.never`, so `proc.on('exit')` existed ONLY in the release path — and that path runs when the fiber is interrupted (a restart, a signal), never when the child exits by itself. Two more places assumed the same thing: `runSupervisor` was typed `Effect<never>`, and `dev.ts` returned `new Promise(() => {})` after starting it.
+
+  So a boot that aborted — an unreachable database, a refused migration, a failed env gate — left the child dead and the supervisor waiting for a file change that nobody was there to make. Measured, not inferred: one developer machine carried 15 such `voltro dev` process pairs, `ppid=1`, the oldest 7 days old, every one a boot that had failed against a remote database. They hold a watcher and a terminal-less process each; in CI the same shape keeps a runner busy after the job "finished".
+
+  `use` now awaits the child (`awaitChildExit`) and the supervisor races that against the watch loop, so whichever happens first decides. A restart still does NOT end it — `stopChild` interrupts the fiber, so the deferred is never completed on that path. A child killed by a signal reports `code: null`, which is reported as a failure rather than a clean 0.
+
+  What a self-exit MEANS then depends on whether anyone is watching, because the two failure modes pull in opposite directions:
+
+  - **Interactive** (stdout is a TTY) — a crashed boot is something you are about to fix, so the supervisor says so and keeps watching. The next save restarts it, which is what every other dev server does; stopping would throw away the watcher mid-edit and make you retype the command. - **Non-interactive** — nobody is going to fix anything. `voltro dev` exits with the child's code, so a failed boot is a failed command. This is the case that produced the invisible processes, and the one CI actually waits on.
+
+  A CLEAN exit always stops, watched or not. `VOLTRO_DEV_KEEP_ALIVE=1|0` forces the answer for what the TTY check cannot see — a CI runner with a TTY allocated, or a wrapper that pipes output while a human still watches it — and cannot keep a clean exit alive, which would turn a deliberate shutdown into a hang.
+
+  Pinned against REAL child processes, because the defect was an Effect that never settled — a stubbed `once('exit')` that resolves is exactly what would have passed while the bug shipped.
+- **@voltro/database** — **A user-facing message that names an API must have one — now checked in CI.**
+
+  The sibling of the claimed-wiring check. That one asserts a doc comment's claimed caller exists; this one asserts a message's claimed API exists. Same failure shape, worse audience: a doc comment is read by somebody browsing, a refusal by somebody already blocked and looking for the sanctioned way out.
+
+  It exists for a reported bug that nothing could have caught. The drop-table refusal offered, as its FIRST option, *"chain `.dropped()` on it"* — tables have no such marker, only columns do. Doc SAMPLES are typechecked; message strings are not, and cannot be. Three of one release's reported defects lived in that blind spot.
+
+  Three rules, each with an unambiguous answer, because a noisy gate is skipped and then costs more than it saves:
+
+  - a `VOLTRO_*` variable a message tells you to **set** must be read somewhere, - a `` `.method()` `` a message tells you to **chain** must be a callable MEMBER of a published type, - a `--flag` in a `voltro …` instruction must be parsed.
+
+  The member rule is the one that took two attempts. The first version asked "does this name exist in the public surface" and the motivating bug **passed it**: `dropped` is exported, as a free `dropped()` you write as a column's value. A dotted claim is a claim about something chainable, so a free function and a `readonly dropped?: boolean` data property are both correctly rejected now.
+
+  **It immediately found a second instance nobody had reported** — the drop-COLUMN refusal also said "chain `.dropped()`", one level down from the reported one, and the real spelling is `<column>: dropped()` as the field's value. Close enough to guess from, which is why it survived.
+
+  Ships with a `--selftest` that runs first in CI, for the reason the changelog gate has one: a check that has quietly stopped detecting anything still prints green, and green is read as evidence.
+- **@voltro/database** — **Two migration refusals sent people the wrong way** — the worst place for a bad hint, because whoever reads one is already blocked and looking for the sanctioned way out.
+
+  **The drop-table refusal recommended an API that does not exist.** Its first option was *"add it to your declared set + chain `.dropped()` on it"*. There is no table-level `dropped()` — only the column marker. The recommendation was also the conceptually RIGHT one, which is what made it expensive: the two options that do work are both worse, so a reader picks the one they cannot follow.
+
+  There is now a real per-table answer: **`VOLTRO_DESTRUCTIVE_OK` accepts a table list**, not just `1`. `VOLTRO_DESTRUCTIVE_OK=old_things` acknowledges the data loss for that table and leaves every other lossy op in the plan blocked. `1` still means all of them — which is rarely what somebody means, and was previously the only way to say anything. A user with one intended drop and three other lossy ops had to acknowledge all four or hand-write a `DROP TABLE` migration, the path 0.14.0's own upgrade note warns against.
+
+  The message also states why there is deliberately no table marker: a dropped COLUMN leaves a slot worth documenting in the declaration; a dropped TABLE leaves nothing, so the marker would be a dead entry you must remember to delete.
+
+  **The drop-column refusal never mentioned `renamedFrom`.** It offered "chain `.dropped()`" or "restore the field" — and followed literally on a rename, the first costs exactly the data the user was trying to keep. When the plan drops AND adds columns on the same table, the message now leads with *"did you rename one?"* and names both sides. The evidence was in the plan the whole time.
+
+  Finding that required fixing a second thing: the footer read only the BLOCKED operations, and an `add-column` is `safe`. The counterpart of a rename was never in the list it was looking at.
+- **@voltro/cli** — **0.14.0's taxonomy codemod renamed two kinds of file it should not have, and a repo that already upgraded carries the damage with a green build.** Both were found by adopters running it on real projects; both are silent — the rename succeeds, the imports are rewritten, nothing throws.
+
+  **A framework primitive was treated as an undeclared file.** `health.route.tsx` → `health.route.component.tsx`, five times in one app. The codemod kept its OWN list of "suffixes that already carry a contract" instead of reading `fileConventions.ts`, and `.route.` was not on it — the exact drift that module exists to prevent, reproduced inside a file that imports from it. The list is gone; the registry answers now, and it gained `ROUTE_PATTERN` plus a `carriesFrameworkConvention()` every consumer shares.
+
+  The root cause underneath was worse than a missing entry: `export default defineRestRoute({...})` resolved to the placeholder name `Default`, which starts with a capital, and was counted as a COMPONENT on that basis. A default export is now only evidence of a component when the exported thing is callable — so a convention nobody has registered yet is safe too.
+
+  **A file with no exports was called a type file.** `test-setup.ts` → `test-setup.types.ts`, while `vitest.config.ts` still named `./test-setup.ts` as a **string**. Not an import, so nothing rewrote it and nothing failed: that suite would have run without its setup and stayed green. Five more went the same way — a registry module, two migration runners, a `.register.ts`, and a code generator whose `export` tokens live inside template strings.
+
+  `*.types.ts` promises "zero runtime exports", and that promise only means something for a file that exports TYPES. Zero of everything promises nothing, and renames a module whose whole purpose is being imported for effect — where the filename is often the only reference there is. It now requires at least one exported type.
+
+  **The shipped codemod undoes both**, and can only reach files whose content proves the suffix was wrong: a `.component.` on a name that already carries a framework convention, and a `.types.` on a file that exports nothing at all. It also prints the one thing it cannot fix — references by PATH rather than by import (a vitest `setupFiles`, a tsconfig `include`, a Docker `COPY`) were strings on the way out and are strings on the way back.
+- **@voltro/cli** — Three ways `voltro update` failed on a real adopter's host, none of which we could have found ourselves — each needs a machine we do not have.
+
+  **The install could not run here, and the refusal left the tree half-upgraded.** Their install runs in a container against its own store. `voltro update` ran the package manager on the host anyway; pnpm refused (it wanted to remove `node_modules` and had no TTY to ask) and exited — after the version bumps were already written and before any codemod ran. That is the state this command's own documentation calls the worst one to be in, and it was reachable by design.
+
+  `--no-install` now writes the bump and stops, saying plainly that the tree is half-upgraded and naming both remaining steps. The install-failed message points at it too. Note what this is not: a compatibility flag. It is a mode for a host where the install is somebody else's job, and it ends by telling you the job is not done.
+
+  **The codemod scan exhausted a 12 GB heap, and said nothing about why.** The crash was a bare V8 out-of-memory stack. The scan pruned the directories WE know about — `node_modules`, `dist`, `.turbo` — which cannot cover a project's own heavy ignored trees (a build cache, a data dump, a virtualenv).
+
+  Inside a git repository the scan now asks git: `git ls-files --cached --others --exclude-standard` is exactly "files this project considers its own", and a codemod rewrites source — source that git ignores is not source we may rewrite. It also removes the traversal, so there is nothing left to exhaust memory on. Outside a repo the walk remains, now with a ceiling that REPORTS which directory to exclude instead of dying namelessly.
+
+  **"not a Voltro app" was the wrong conclusion.** Said of a directory containing an `app.config.ts`, it sends the reader looking for the wrong problem. Three web apps in a workspace inherited from another tool had their `@voltro/*` dependencies in an ancestor `package.json` — the apps ARE Voltro apps; only the declaration lives elsewhere. With an `app.config.ts` present the message now says that, and names the two ways forward.
+
+  **A monorepo may keep ONE root `package.json`** with its apps carrying only an `app.config.ts`. Running `voltro update` inside such an app used to say "no package.json at <dir>" — true, and useless. It now recognises the layout, says it is supported, and prints the command with the root already filled in.
+- **@voltro/cli** — **`voltro update --only <id>`**, and a summary that stops contradicting itself.
+
+  `--only` runs just the named codemods (repeatable or comma-separated; ids are what `--dry-run` prints). The ask behind it: two of three codemods were load-bearing for one app — without them, 52 type errors and 51 routes that 404 — while the third was elective, and the repairing tool refuses on a dirty tree, so there was no way to take the necessary half first.
+
+  It is deliberately NOT a `--required` flag over a REQUIRED/OPTIONAL axis on each codemod. "Required" would have to mean *this app does not run without it*, and that is a property of the app: `03_pages-suffix` is unavoidable for a project with pages and irrelevant to an api-only one. Marking it on the codemod would encode a guess as a contract. An unknown id is an error listing the ids that ARE available — "it did nothing" and "you typed it wrong" otherwise look identical.
+
+  **The summary counted only edited files, and renames vanished from it.** The before-snapshot is keyed by PATH, so a moved file has no entry under its new one: a pass that renamed 238 files and edited 9 importers reported `(9 files)`, understating the change by a factor of 26 in the line a user plans around. Moves are now paired by content and reported separately — `(238 renamed, 9 edited)`.
+
+  **A dry run no longer speaks in the past tense.** It printed `✓ <id> — <title>`, the same line a real run prints. Now `·` and `[would apply]`.
+
+---
+
 ## [0.14.0] — 2026-07-26
 
 ### ⚠ BREAKING

package/dist/sql.d.ts

@@ -702,6 +702,25 @@ export declare const defaultJsonClause: (value: object, dialect: DialectId) => s
 
 export declare const describeOutcome: (outcome: BootMigrationOutcome, dialectId: string) => string;
 
+/**
+ * Parse `VOLTRO_DESTRUCTIVE_OK`.
+ *
+ * `1` / `true` acknowledges every lossy op in the run. A comma-separated list
+ * acknowledges only those TABLES — which is the form somebody wants far more
+ * often, and its absence was a real complaint: a plan carrying one intended drop
+ * plus three other lossy ops had no way to say yes to the one. `1` said yes to
+ * all four, and the alternative was a hand-written DROP migration, which the
+ * framework's own upgrade note warns against.
+ *
+ * `undefined` = not set at all.
+ */
+export declare const destructiveScope: (raw: string | undefined) => {
+    readonly kind: "all";
+} | {
+    readonly kind: "tables";
+    readonly tables: ReadonlySet<string>;
+} | undefined;
+
 /**
  * Compare declared reactivity against the triggers actually installed.
  *
@@ -2160,23 +2179,7 @@ declare interface TableUnique {
     };
 }
 
-/**
- * Clear the `blocked` flag on every LOSSY operation in a plan.
- *
- * Called only after the destructive opt-in has been established, and it is not
- * cosmetic. `applyPlan` carries its OWN unconditional refusal on any blocked
- * operation, with no override parameter. So a plan that the boot gate has
- * decided may proceed, but which still arrives marked blocked, is refused a
- * second time by the applier — which meant `VOLTRO_DESTRUCTIVE_OK=1` could
- * never actually drop a table. The planner's fix hint names that exact
- * variable, so the documented escape hatch pointed at a wall.
- *
- * Only `lossy` ops are unblocked, and callers must have already established
- * that no other class is blocked. A rename-without-marker or a NOT NULL
- * without backfill stays blocked even in destructive-OK mode: those lose data
- * regardless of intent, so intent is not the question being asked.
- */
-export declare const unblockLossy: (plan: MigrationPlan) => MigrationPlan;
+export declare const unblockLossy: (plan: MigrationPlan, scope?: ReturnType<typeof destructiveScope>) => MigrationPlan;
 
 /**
  * Unique-constraint metadata. Set by `.unique()` (or `.unique({ dedup })`).

package/dist/sql.js

@@ -2416,21 +2416,35 @@ BEGIN
 }), fr = () => {
 	let e = (process.env.VOLTRO_DB_IGNORE_TABLES ?? "").split(",").map((e) => e.trim()).filter((e) => e.length > 0);
 	return e.length > 0 ? { ignoreTables: e } : {};
-}, pr = (e) => ({
+}, pr = (e) => {
+	if (e === void 0) return;
+	let t = e.trim();
+	if (t === "") return;
+	if (t === "1" || t.toLowerCase() === "true") return { kind: "all" };
+	let n = t.split(",").map((e) => e.trim()).filter((e) => e.length > 0);
+	return n.length > 0 ? {
+		kind: "tables",
+		tables: new Set(n)
+	} : void 0;
+}, mr = (e) => typeof e.table == "string" ? e.table : void 0, hr = (e, t = { kind: "all" }) => ({
 	...e,
 	operations: e.operations.map((e) => {
 		if (!e.blocked || e.classification !== "lossy") return e;
-		let { blocked: t, ...n } = e;
-		return n;
+		if (t?.kind === "tables") {
+			let n = mr(e.op);
+			if (n === void 0 || !t.tables.has(n)) return e;
+		}
+		let { blocked: n, ...r } = e;
+		return r;
 	})
-}), mr = (e, t, n) => t === "postgres" ? at(e, n).pipe(d.flatMap((e) => {
+}), gr = (e, t, n) => t === "postgres" ? at(e, n).pipe(d.flatMap((e) => {
 	let t = ot(e);
 	return t === void 0 ? d.void : d.logWarning(`auto-migrate: ${t}`).pipe(d.annotateLogs({ scope: "voltro:migrate" }));
-}), d.catchAll(() => d.void)) : d.void, hr = (e, t, n) => d.gen(function* () {
+}), d.catchAll(() => d.void)) : d.void, _r = (e, t, n) => d.gen(function* () {
 	let r = sr(e), i = t.filter((e) => !I(e.tableName));
 	if (process.env.VOLTRO_MIGRATE_FORCE !== "1") {
 		let t = N(F(i, r));
-		if ((yield* or(e)) === t) return yield* mr(e, r, i), {
+		if ((yield* or(e)) === t) return yield* gr(e, r, i), {
 			kind: "up-to-date",
 			fingerprint: t
 		};
@@ -2447,12 +2461,11 @@ BEGIN
 		...fr()
 	});
 	if (s.summary.blocked > 0) {
-		let e = s.operations.filter((e) => e.blocked).every((e) => e.classification === "lossy");
-		if (process.env.VOLTRO_DESTRUCTIVE_OK !== "1" || !e) return {
+		let e = s.operations.filter((e) => e.blocked).every((e) => e.classification === "lossy"), t = pr(process.env.VOLTRO_DESTRUCTIVE_OK);
+		if (t === void 0 || !e || (s = hr(s, t), s.operations.some((e) => e.blocked))) return {
 			kind: "refused-blocked",
 			plan: s
 		};
-		s = pr(s);
 	}
 	return s.operations.length === 0 ? {
 		kind: "up-to-date",
@@ -2476,10 +2489,10 @@ BEGIN
 		}),
 		plan: s
 	};
-}), gr = (e, t, n) => process.env.VOLTRO_AUTO_MIGRATE === "0" ? d.succeed({
+}), vr = (e, t, n) => process.env.VOLTRO_AUTO_MIGRATE === "0" ? d.succeed({
 	kind: "skipped",
 	reason: "VOLTRO_AUTO_MIGRATE=0"
-}) : n.environment === "prod" ? cr(e, t) : hr(e, t, n), _r = (e, t) => {
+}) : n.environment === "prod" ? cr(e, t) : _r(e, t, n), yr = (e, t) => {
 	switch (e.kind) {
 		case "skipped": return `auto-migrate: skipped (${e.reason})`;
 		case "up-to-date": return `auto-migrate: schema up to date (${t}, fingerprint=${P(e.fingerprint)})`;
@@ -2489,11 +2502,24 @@ BEGIN
 		}
 		case "prod-mismatch": return `auto-migrate: SCHEMA FINGERPRINT MISMATCH — declared=${P(e.expected)}` + (e.actual ? ` live=${P(e.actual)}` : " live=<no _voltro_migration_plans row>") + ". Run `voltro db apply --plan plan.json` from the deploy pipeline before serving.";
 		case "refused-blocked": {
-			let t = e.plan.operations.filter((e) => e.blocked), n = t.filter((e) => e.op.kind === "drop-table").length, r = t.filter((e) => e.op.kind === "add-column").length, i = t.filter((e) => e.op.kind === "drop-column").length, a = t.filter((e) => e.classification === "needs-rename-annotation").length, o = `auto-migrate: REFUSED — ${e.plan.summary.blocked} blocked operation(s):\n` + ar(e.plan), s = [""];
-			return n > 0 && s.push(`${n} table(s) exist in the live DB but aren't in your declared schema.`, "This is usually one of three things:", "  (a) You're iterating on the schema — the table file got renamed, moved, or temporarily commented out.", "      → Restore the declaration. Your data stays intact.", "  (b) You want to KEEP the table but NOT manage it with Voltro (a leftover from another tool —", "      a Strapi/Rails/legacy migration artifact, or an externally-owned table).", `      → Set \`VOLTRO_DB_IGNORE_TABLES=${t.filter((e) => e.op.kind === "drop-table").map((e) => "table" in e.op ? e.op.table : "").filter(Boolean).join(",")}\` (comma-separated).`, "        The planner excludes those tables from the diff entirely — it never drops them, and they", "        stop blocking your OTHER (additive) changes. This is the fix when a leftover freezes your schema.", "  (c) You actually want to drop the table.", "      → Add it to your declared set + chain `.dropped()` on it, OR", "        write a file-based migration in `migrations/` that DROPs it, OR", "        set `VOLTRO_DESTRUCTIVE_OK=1` for ONE `voltro dev` run (acknowledges data loss).", "  Soft-drop: set `VOLTRO_SOFT_DROP=1` alongside DESTRUCTIVE_OK to RENAME instead of DROP", "  (data survives as `<name>__dropped_<ts>` for ~7d; restorable via `voltro db restore-snapshot`)."), r > 0 && s.push(`${r} required column(s) need a backfill strategy before adding to a populated table.`, "  → Annotate the column: `.backfill(sql`<expr>`)` or `.backfill(row => <fn>)` or `.default(<value>)`.", "  Existing rows get the backfill value; the column then lands as NOT NULL."), i > 0 && s.push(`${i} column(s) are missing from your declared schema.`, "  → If intentional: chain `.dropped()` on the column slot in the table declaration.", "  → If a typo: restore the field. Data survives until you drop it."), a > 0 && s.push(`${a} column(s) look like renames (one column gone + a new one of same shape appeared).`, "  → On the NEW column add `.renamedFrom('<oldName>')` so the planner emits RENAME instead of DROP+ADD."), s.push("", "See `voltro db plan` for the full machine-readable diff."), o + "\n" + s.join("\n");
+			let t = e.plan.operations.filter((e) => e.blocked), n = t.filter((e) => e.op.kind === "drop-table").length, r = t.filter((e) => e.op.kind === "drop-table").map((e) => "table" in e.op ? e.op.table : "").filter(Boolean), i = t.filter((e) => e.op.kind === "add-column").length, a = t.filter((e) => e.op.kind === "drop-column").length, o = t.filter((e) => e.classification === "needs-rename-annotation").length, s = `auto-migrate: REFUSED — ${e.plan.summary.blocked} blocked operation(s):\n` + ar(e.plan), c = [""];
+			if (n > 0 && c.push(`${n} table(s) exist in the live DB but aren't in your declared schema.`, "This is usually one of three things:", "  (a) You're iterating on the schema — the table file got renamed, moved, or temporarily commented out.", "      → Restore the declaration. Your data stays intact.", "  (b) You want to KEEP the table but NOT manage it with Voltro (a leftover from another tool —", "      a Strapi/Rails/legacy migration artifact, or an externally-owned table).", `      → Set \`VOLTRO_DB_IGNORE_TABLES=${r.join(",")}\` (comma-separated).`, "        The planner excludes those tables from the diff entirely — it never drops them, and they", "        stop blocking your OTHER (additive) changes. This is the fix when a leftover freezes your schema.", "  (c) You actually want to drop the table.", `      → Set \`VOLTRO_DESTRUCTIVE_OK=${r.join(",")}\` for ONE run — it acknowledges`, "        the data loss for THOSE tables only; every other lossy op in this plan stays blocked.", "        (`VOLTRO_DESTRUCTIVE_OK=1` acknowledges all of them, which is rarely what you mean.)", "      There is deliberately no `dropped()` marker for a TABLE, unlike for a column: a", "      dropped column leaves a slot worth documenting in the declaration, a dropped table", "      leaves nothing — the marker would be a dead entry you must remember to delete.", "  Soft-drop: set `VOLTRO_SOFT_DROP=1` alongside DESTRUCTIVE_OK to RENAME instead of DROP", "  (data survives as `<name>__dropped_<ts>` for ~7d; restorable via `voltro db restore-snapshot`)."), i > 0 && c.push(`${i} required column(s) need a backfill strategy before adding to a populated table.`, "  → Annotate the column: `.backfill(sql`<expr>`)` or `.backfill(row => <fn>)` or `.default(<value>)`.", "  Existing rows get the backfill value; the column then lands as NOT NULL."), a > 0) {
+				let t = /* @__PURE__ */ new Map(), n = /* @__PURE__ */ new Map();
+				for (let r of e.plan.operations) {
+					let e = "table" in r.op ? r.op.table : void 0;
+					if (e === void 0) continue;
+					let i = "column" in r.op ? String(r.op.column) : void 0;
+					if (i === void 0) continue;
+					let a = r.op.kind === "drop-column" ? t : r.op.kind === "add-column" ? n : void 0;
+					a !== void 0 && a.set(e, [...a.get(e) ?? [], i]);
+				}
+				let r = [...t.entries()].filter(([e]) => (n.get(e)?.length ?? 0) > 0).map(([e, t]) => `${e}: ${t.join(", ")} gone, ${n.get(e).join(", ")} new`);
+				c.push(`${a} column(s) are missing from your declared schema.`), r.length > 0 && c.push("  → DID YOU RENAME ONE? This plan drops AND adds columns on the same table:", ...r.map((e) => `      ${e}`), "    If so, add `.renamedFrom('<oldName>')` to the NEW column — the planner then emits a", "    RENAME and the data moves with it. Dropping and re-adding loses every value."), c.push("  → If intentional: give the field the `dropped()` marker as its VALUE —", "    `<column>: dropped()` (import it from `@voltro/database`). It is not a method", "    chained onto the column; the slot stays, documenting the hole.", "  → If a typo: restore the field. Data survives until you drop it.");
+			}
+			return o > 0 && c.push(`${o} column(s) look like renames (one column gone + a new one of same shape appeared).`, "  → On the NEW column add `.renamedFrom('<oldName>')` so the planner emits RENAME instead of DROP+ADD."), c.push("", "See `voltro db plan` for the full machine-readable diff."), s + "\n" + c.join("\n");
 		}
 	}
-}, vr = /* @__PURE__ */ new Set([
+}, br = /* @__PURE__ */ new Set([
 	"node_modules",
 	"dist",
 	"build",
@@ -2502,11 +2528,11 @@ BEGIN
 	".next",
 	".git",
 	".framework"
-]), yr = async (e) => {
+]), xr = async (e) => {
 	let t = [], n = async (e) => {
 		let r = await h.readdir(e, { withFileTypes: !0 }).catch(() => []);
 		for (let i of r) {
-			if (vr.has(i.name)) continue;
+			if (br.has(i.name)) continue;
 			let r = g(e, i.name);
 			i.isDirectory() ? await n(r) : i.isFile() && l.test(i.name) && t.push(r);
 		}
@@ -2515,7 +2541,7 @@ BEGIN
 		let n = e.split("/").pop() ?? e, r = t.split("/").pop() ?? t;
 		return n.localeCompare(r);
 	});
-}, br = async (e) => {
+}, Sr = async (e) => {
 	let t = [];
 	for (let n of e) {
 		let e = (await import(ee(n).href)).default;
@@ -2529,11 +2555,11 @@ BEGIN
 		});
 	}
 	return t;
-}, xr = (e) => e`
+}, Cr = (e) => e`
     SELECT ${e("id")}
     FROM ${e("_voltro_migration_plans")}
     WHERE ${e("source")} = 'file'
-  `.pipe(d.map((e) => e.map((e) => e.id)), d.catchAll(() => d.succeed([]))), Sr = (e, t, n, r) => d.gen(function* () {
+  `.pipe(d.map((e) => e.map((e) => e.id)), d.catchAll(() => d.succeed([]))), wr = (e, t, n, r) => d.gen(function* () {
 	let i = Date.now(), a = (/* @__PURE__ */ new Date()).toISOString(), o = {
 		sql: e,
 		log: {
@@ -2566,9 +2592,9 @@ BEGIN
          ${r}, ${n}, ${"file"},
          ${c}, ${a}, ${t.migration.description})
     `, { durationMs: c };
-}), Cr = (e, t) => d.gen(function* () {
+}), Tr = (e, t) => d.gen(function* () {
 	let n = yield* d.tryPromise({
-		try: () => yr(g(t, "migrations")),
+		try: () => xr(g(t, "migrations")),
 		catch: (e) => e
 	});
 	if (n.length === 0) return {
@@ -2576,20 +2602,20 @@ BEGIN
 		skipped: []
 	};
 	let r = yield* d.tryPromise({
-		try: () => br(n),
+		try: () => Sr(n),
 		catch: (e) => e
 	});
 	if (r.length === 0) return {
 		pending: [],
 		skipped: []
 	};
-	let i = new Set(yield* xr(e));
+	let i = new Set(yield* Cr(e));
 	return {
 		pending: r.filter((e) => !i.has(e.migration.id)),
 		skipped: r.filter((e) => i.has(e.migration.id)).map((e) => e.migration.id)
 	};
-}), wr = (e, t) => Cr(e, t).pipe(d.map((e) => e.pending.map((e) => e.migration.id))), Tr = (e, t) => d.gen(function* () {
-	let { pending: n, skipped: r } = yield* Cr(e, t.projectRoot);
+}), Er = (e, t) => Tr(e, t).pipe(d.map((e) => e.pending.map((e) => e.migration.id))), Dr = (e, t) => d.gen(function* () {
+	let { pending: n, skipped: r } = yield* Tr(e, t.projectRoot);
 	if (n.length === 0) return {
 		applied: [],
 		skipped: r
@@ -2603,7 +2629,7 @@ BEGIN
 				id: r.migration.id,
 				file: r.file
 			}));
-			let { durationMs: n } = yield* Sr(e, r, t.env, t.appliedBy);
+			let { durationMs: n } = yield* wr(e, r, t.env, t.appliedBy);
 			i.push({
 				id: r.migration.id,
 				durationMs: n
@@ -2620,18 +2646,18 @@ BEGIN
 		applied: i,
 		skipped: r
 	};
-}), Er = (e, t) => e`
+}), Or = (e, t) => e`
     SELECT ${e("id")}
     FROM ${e("_voltro_migration_plans")}
     WHERE ${e("id")} = ${t} AND ${e("source")} = 'file'
     LIMIT 1
-  `, Dr = (e, t) => d.gen(function* () {
-	if (!(yield* Er(e, t.id))[0]) return yield* d.fail(/* @__PURE__ */ Error(`rollback: ${t.id} not found in _voltro_migration_plans (file source)`));
+  `, kr = (e, t) => d.gen(function* () {
+	if (!(yield* Or(e, t.id))[0]) return yield* d.fail(/* @__PURE__ */ Error(`rollback: ${t.id} not found in _voltro_migration_plans (file source)`));
 	let n = yield* d.tryPromise({
-		try: () => yr(g(t.projectRoot, "migrations")),
+		try: () => xr(g(t.projectRoot, "migrations")),
 		catch: (e) => e
 	}), r = (yield* d.tryPromise({
-		try: () => br(n),
+		try: () => Sr(n),
 		catch: (e) => e
 	})).find((e) => e.migration.id === t.id);
 	if (!r) return yield* d.fail(/* @__PURE__ */ Error(`rollback: file for migration ${t.id} not found on disk under ${t.projectRoot}/migrations/`));
@@ -2664,7 +2690,7 @@ BEGIN
 	} finally {
 		yield* E(e).pipe(d.orDie);
 	}
-}), Or = (e) => d.gen(function* () {
+}), Ar = (e) => d.gen(function* () {
 	let t = yield* p.SqlClient, n = yield* t`
       SELECT id, fingerprint, appliedAt FROM _voltro_migration_plans
       WHERE source = 'auto-diff'
@@ -2709,10 +2735,10 @@ BEGIN
 		snapshotFingerprint: e.fingerprint,
 		snapshotId: i
 	};
-}), kr = (e, ...t) => ({
+}), jr = (e, ...t) => ({
 	_tag: "RawSqlFragment",
 	strings: [...e],
 	values: [...t]
-}), Ar = (e) => typeof e == "object" && !!e && e._tag === "RawSqlFragment";
+}), Mr = (e) => typeof e == "object" && !!e && e._tag === "RawSqlFragment";
 //#endregion
-export { l as FILE_MIGRATION_PATTERN, it as REACTIVE_TRIGGER_PREFIX, te as VOLTRO_MIGRATION_LOCK_KEY, ft as _internalCmp, T as acquireMigrationLock, Ke as applyNamespacedSchema, ir as applyPlan, Be as applySchema, zt as chunkTables, F as declaredSnapshot, ve as defaultArrayClause, _e as defaultClause, k as defaultJsonClause, _r as describeOutcome, at as detectReactiveTriggerDrift, tn as emitDropColumnDdl, nn as emitDropColumnDdlMysql, ze as emitFrameworkBootstrapSql, Le as emitNamespaceProvisionDdl, Re as emitNamespacedSchemaSql, M as emitSchemaSql, N as fingerprintSchema, ot as formatReactiveTriggerDrift, fr as ignoreTablesFromEnv, Yt as introspectSchema, o as isFileMigration, Ar as isRawSqlFragment, Pt as mapPgType, s as migration, A as numericIdSql, Nt as parseEnumCheck, wr as pendingFileMigrationIds, Mt as planMigrations, qe as provisionTenantNamespace, E as releaseMigrationLock, gn as renderColumnMysql, pn as renderColumnPg, Dr as rollbackFileBasedMigration, Tr as runFileBasedMigrations, Je as runFrameworkBootstrap, Ge as runMigrate, gr as runPlannedMigrations, P as shortFingerprint, et as snapshotColumn, kr as sql, O as sqlType, Or as squashMigrationPlans, pr as unblockLossy, he as withMigrationLock };
+export { l as FILE_MIGRATION_PATTERN, it as REACTIVE_TRIGGER_PREFIX, te as VOLTRO_MIGRATION_LOCK_KEY, ft as _internalCmp, T as acquireMigrationLock, Ke as applyNamespacedSchema, ir as applyPlan, Be as applySchema, zt as chunkTables, F as declaredSnapshot, ve as defaultArrayClause, _e as defaultClause, k as defaultJsonClause, yr as describeOutcome, pr as destructiveScope, at as detectReactiveTriggerDrift, tn as emitDropColumnDdl, nn as emitDropColumnDdlMysql, ze as emitFrameworkBootstrapSql, Le as emitNamespaceProvisionDdl, Re as emitNamespacedSchemaSql, M as emitSchemaSql, N as fingerprintSchema, ot as formatReactiveTriggerDrift, fr as ignoreTablesFromEnv, Yt as introspectSchema, o as isFileMigration, Mr as isRawSqlFragment, Pt as mapPgType, s as migration, A as numericIdSql, Nt as parseEnumCheck, Er as pendingFileMigrationIds, Mt as planMigrations, qe as provisionTenantNamespace, E as releaseMigrationLock, gn as renderColumnMysql, pn as renderColumnPg, kr as rollbackFileBasedMigration, Dr as runFileBasedMigrations, Je as runFrameworkBootstrap, Ge as runMigrate, vr as runPlannedMigrations, P as shortFingerprint, et as snapshotColumn, jr as sql, O as sqlType, Ar as squashMigrationPlans, hr as unblockLossy, he as withMigrationLock };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/database",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Browser-safe schema DSL, query builder, and cross-dialect migration planner for Voltro — one schema, every SQL backend.",
   "keywords": [
     "voltro",
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@effect/sql": "^0.51.1",
-    "@voltro/logger": "0.14.0",
+    "@voltro/logger": "0.15.0",
     "typeid-js": "^1.2.0",
     "ulidx": "^2.4.1"
   },