@voltro/database 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -39,6 +39,99 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.13.0] — 2026-07-25
+
+### ⚠ BREAKING
+
+- **@voltro/protocol, @voltro/plugin-scim, @voltro/plugin-prometheus** — SCIM was served UNAUTHENTICATED whenever its token was an empty string.
+
+  `checkBearer(headers, expected)` returned `true` when `expected` was unset or empty, documented as "no token configured = open; the caller decided not to gate this surface". Its one production caller had decided the opposite: `scimPlugin` declares `token: string`, and `scimPlugin({ token: process.env.SCIM_TOKEN ?? '' })` — the shape anyone writes — turned the gate off silently. The result was SCIM 2.0 Users and Groups readable with no credentials: a full directory dump plus the provisioning surface that can deactivate accounts. Likeliest exactly where it hurts, too: an env var set in production and missing in a preview environment.
+
+  `checkBearer` is now fail-closed by default, with the permissive behaviour available as an explicit `{ openWhenUnset: true }` — a two-argument helper cannot know its caller's intent, so it must not assume the permissive one. `@voltro/plugin-prometheus` passes it (its token is documented as optional), and `scimPlugin` now throws at construction — i.e. at boot — rather than answering the first anonymous request.
+- **@voltro/database, @voltro/cli** — `voltro db apply` and boot auto-migrate could report success while applying nothing, and then record a fingerprint that made every later boot short-circuit on "schema up to date".
+
+  Reported from a live pod: `applied 31 op(s)` on every boot for two releases, with none of the 31 present in the database. Nothing was wrong with the transport, the lock or the transaction — the applier emitted statements that postgres accepted and that changed nothing. Two independent causes:
+
+  - A `ColumnSnapshot` carried no `vector` dimension / `array` element / `enum` name, so the applier's type renderers collapsed all three to `text`. A declared `vector(1536)` over a live `text` column planned an `alter-column-type` that emitted `ALTER COLUMN … TYPE text`. Valid, applied, no-op, re-planned forever. (Also meant an `add-column` for a vector, array, enum or PostGIS column created a plain `text` column.) - The default-clause renderers excluded ARRAYS, returning `null`, and the call site turned that into `SET DEFAULT NULL`. A declared `.default([])` on a `json()` column therefore never landed — thirty columns were stuck this way in the reporting schema.
+
+  Fixed: the snapshot carries the type parameters and the renderers delegate to `migrate.ts`'s canonical `sqlType`, so the applier and the CREATE-TABLE emitter cannot disagree; array defaults render (a real `text[]` literal on a native `array()` column, a jsonb literal otherwise); and a default the renderer cannot express now FAILS instead of degrading to `DEFAULT NULL`.
+
+  And the structural guard, which is the part that matters: **`applyPlan` re-plans against the live schema before it records a fingerprint, and refuses to record one if any operation remains.** DDL that changes nothing succeeds exactly as quietly as DDL that works, so the only evidence a plan applied is that the same planner has nothing left to do. `ApplyPlanCtx` gains a required `replan`; `AppliedMigration` gains `appliedOps` (what EXECUTED, not `plan.operations.length`), and the boot log quotes that.
+- **@voltro/plugin-storage** — `storage.share`, `storage.revoke` and `storage.listGrants` performed no authorization at all.
+
+  Each took an object id straight off the wire and passed it to a service method that (correctly, for a trusted server-side API) checks nothing, with nothing in between. Any authenticated caller could grant themselves read or write on any object in the installation, revoke anyone else's grants, and enumerate who an object is shared with.
+
+  All three now require that the caller owns the object, or carries `admin:full`. A missing object and an unowned object report the same 403 — a 404 would let an unauthorized caller probe which ids exist. `GrantStore` gains `getById`, which `revoke` needs to resolve a grant id back to its object.
+
+### Added
+
+- **@voltro/runtime, @voltro/database** — API keys carry app-owned `metadata` — the second ownership axis.
+
+  `tenantId` and `onBehalfOf` are the two relationships the framework models. Plenty of apps have a third that actually authorizes the key: a team, a project, an environment. `ApiKeyRecord` in `@voltro/protocol` has carried a `metadata` slot all along — its doc comment even names `teamId` as the example — but the SERVICE had nowhere to store it and nowhere to return it. So an app with a team axis could authenticate through the built-in strategy and still not authorize, and `apiKeys: true` was unusable for it. Reported as the one thing that stopped an otherwise complete adoption; their alternatives were a second table joined on the hot auth path, or smuggling `team:<id>` into `scopes`, where `hasScope` would then see a scope that is not a scope.
+
+  `IssueInput`, `ApiKeyRow` and `ResolvedApiKey` now carry it, stored as JSON on `_voltro_api_keys`, and it survives `rotate` — a rotated key is the same credential with a new secret, so dropping it would silently de-authorize every rotated key.
+
+  It is app data, never identity. The strategy merges it UNDER the framework's own claims: `provider` and the acting `userId` are written afterwards from `onBehalfOf` and always win, including when the answer is "none". A bag that could set `userId` would let whoever minted the key choose who the request is. Pinned end-to-end, not just at the protocol layer.
+
+  `PublicApiKey` also gains `createdBy` and `onBehalfOf`, so `service.list` can answer the two questions an admin actually asks about a shared credential. Neither is a secret — they are the accountability record, and omitting them hid them from the person responsible for the key.
+- **@voltro/protocol, @voltro/cli** — A boot warning when two auth strategies claim the same bearer-token prefix.
+
+  The chain is first-match-wins, so a duplicate claim is not a harmless redundancy: whichever strategy runs first decides the Subject. An app that already has its own `sk_` keys and then sets `apiKeys: true` gets the framework strategy appended on the same prefix — resolving without the app's own team binding — and *which strategy answered* decides whether authorization works. Reported by an app that had to pin a test asserting it never enables the flag.
+
+  `AuthStrategy` gains an optional `claimsBearerPrefix`, set by `apiKeyStrategy` from its `prefix` option. Making the claim declarative is what makes the collision detectable at all — the same "only what is declared can be checked" argument the scope rules run on. Checked in `buildResolveSubject`, which both `voltro dev` and `voltro serve` call, so the two boot paths cannot drift.
+
+  A warning rather than a refusal: two strategies on one prefix can be deliberate (a migration window where old and new keys share a shape). What must not happen is that it goes unmentioned.
+- **@voltro/protocol, @voltro/cli** — `auth.resolveScopes` — add scopes to an authenticated Subject from your own data, so ROLE-based authorization becomes declarable.
+
+  An app whose authorization is a database role (`requireCallerAdmin(ctx)` reading an `employees.role` column) is invisible to every static check the framework has: `voltro check`'s `rbac/unguarded-mutation` reports its writes as unguarded, and it is right to — nothing about the decision is declared. But the declarative alternative was unusable for exactly those apps: their subjects come from an external IdP's JWTs and carry no scopes, so `requireScope('employee:admin')` would lock out every real user. One app measured 1566 findings it had no way to act on.
+
+  Lifting the role into `subject.scopes` makes the SAME authorization declarable, visible in the manifest and checkable in CI. Deliberately narrow: the hook returns SCOPES, never a Subject — it cannot change `id` or `tenantId` (identity belongs to the auth strategy), and the result is unioned with the strategy's own scopes, so it can grant but never revoke. It runs per matched request, so cache the lookup yourself; the framework does not, because only the app knows how fast a role change must take effect. Wired identically in `voltro dev` and `voltro serve`.
+- **@voltro/cli** — `voltro doctor` reports packages resolved at more than one version.
+
+  A consumer reported type errors inside the GENERATED `rpcGroup.generated.ts` — `Property '[TypeId]' is missing`, `typeof Never is not assignable to All`, an `Rpc<…, Stream<…>, …>` refused where `Any` was expected — and reasonably concluded the framework emits bad types, because the errors land in a file they cannot edit and did not write. That is the signature of two copies of `effect` in one install: Effect's types are nominal, so a Schema built by one copy is not the type the other expects.
+
+  It deserves its own check because the RUNTIME usually stays green — two instances only diverge where identity matters — so an app boots, serves and passes its tests while `tsc` is red, which sends people looking at the compiler instead of the dependency tree. The report names the versions, the paths, and the errors it explains. Only identity-sensitive packages count (`effect`, `@effect/*`, `@voltro/*`, react/react-dom); a duplicated string utility is wasteful, not a bug class.
+- **@voltro/cli** — `voltro doctor` flags an executor that never names its own descriptor.
+
+  Descriptor/executor pairing is by FILENAME, which is right — and it means a `*.server.ts` can be a complete, correct executor with no reference at all to the contract it implements. Those are exactly the files where a hand-written input drifts from the wire.
+
+  Reported after a 426-executor migration to `ExecutorInput<typeof descriptor>`: three files were skipped by the app's own codemod for a reason no reviewer would guess — they never imported their descriptor, so there was no `typeof` to point at. In the same codebase, six executors had written `boardPurpose: string` where their descriptor declared `Schema.Literal(...)`, discarding the contract at the executor boundary. Only imports of a SIBLING module clear the finding: an executor importing nothing but `@voltro/*` and `node:*` has still not named its contract.
+- **@voltro/database** — `updateManyRow(store, table, patch, { where })` — the last untyped write is now typed against its table.
+
+  `insertRow` and `upsertRow` already were; `ctx.store.updateMany(table, row, { where })` still took a string table name and an untyped row literal. Worth closing because the typed versions were measured: migrating 29 `store.upsert` call sites to `upsertRow` produced 15 `tsc` errors across 8 distinct defects that no test had caught — including seven per-user mutations with no authentication check at all (they wrote `ctx.request.subject.id`, typed `string | null`, into a NOT NULL column, so an anonymous caller reached the database and got a raw statement failure instead of a typed refusal).
+
+### Fixed
+
+- **@voltro/runtime** — A `cache:` declared on a query whose handler returns a COMPUTED value was silently ignored; it now says so.
+
+  The snapshot cache wraps the store read, and a computed query has none — its handler has already run by the time the binding is built. Caching one would mean wrapping the handler invocation, which is a different feature. Until that exists, the honest failure is a loud one: silently ignoring the config is how an author ends up believing a hot query is cached while every subscriber re-runs it. The data stays correct, so nothing else would ever tell them. Warned once per query name, not per subscribe.
+- **@voltro/cli** — The minted `.env.local` is handed to the workspace's owner, and an unreadable env file explains itself.
+
+  A dev container running as root with the host workspace bind-mounted wrote `apps/api/.env.local` as `root:root 0600` INTO THE SHARED WORKSPACE. On the host, everything that loads env then died with EACCES — vitest, `voltro doctor`, the editor — and the developer could not even read the file, while the next container boot recreated it. Container-with-bind-mount is the ordinary dev shape, not an edge case.
+
+  `0600` stays (the file holds a real signing key), because loosening it to `0644` would make that key readable by every account on the machine for the far more common single-user case. Ownership was the wrong variable, so that is the one corrected: the mint chowns the file to whoever owns the directory, which root can do — exactly the case that needs it — and reports loudly when it cannot. A plain EACCES while loading an env file now names the owning uid, the mode and the current uid, because that pair IS the diagnosis and none of it appears in node's message.
+- **@voltro/cli** — Framework-generated output is handed to the workspace's owner, not left owned by whoever the process happens to be.
+
+  The previous release fixed this for the minted `.env.local`. The report that followed showed the scope was wrong: it is EVERY directory the framework generates. A dev pod running as root with the host monorepo bind-mounted leaves `.framework/` and `app.graph.observed.*` as `root:root` inside the developer's own tree, and on the host:
+
+  ```
+  voltro build . → EACCES: permission denied, open '…/apps/display/.framework/index.html'
+  ```
+
+  That is the harder failure. `.env.local` broke env loading; this breaks the production build of every web app outright, with no workaround short of chown-ing by hand after each pod boot. One team could only verify their frontends through test suites and live requests against the running pods.
+
+  `voltro dev` and `voltro build` now hand their generated output — `.framework`, `.env.local`, every `*.generated.*` — to the uid that owns the app root, and say so loudly when they cannot. A no-op on every ordinary run and in any container started with `--user <uid>:<gid>`: when the process already owns the root it returns without touching the tree. Only generated state is claimed; the framework never chowns a file a human wrote.
+- **@voltro/cli** — The observed app-graph no longer restarts the dev server.
+
+  `app.graph.observed.json` was written into the watched app root every 10 seconds, and the supervisor's watcher fired on each write. A downstream pod measured two restarts before every boot over 2000 log lines — the rule, not an outlier — and paid a ~46 s boot three times per save.
+
+  The watcher excludes `<name>.generated.<ext>`, a substring rule chosen precisely because a per-extension whitelist had already let a generated file slip twice. This file slipped it a third time by not carrying the segment at all. It is now `app.graph.observed.generated.json`, which matches the convention instead of adding a fourth special case to a list that has drifted three times; a stale un-suffixed file from an older dev server is removed on boot so it cannot keep triggering restarts.
+- **@voltro/cli** — Four tooling fixes, all from downstream reports:
+
+  - **`voltro check --offline` crashed on any app that declares a workflow.** It built workflow entries as `{ name }` behind an `as never` while `InspectWorkflowEntry` is keyed by `tag`, so the manifest's sort read `undefined` and threw — surfacing as "could not assemble the graph from source" rather than the type error underneath. The cast is what let the two shapes disagree. - **`voltro check --offline` reported plugin tables as `dangling-source`.** It collected only the app's own `*.entity.ts` tables, so a query reading `_voltro_storage_refs` was an `error` — which sets the exit code, failing the CI gate the offline mode exists for. It now uses the same `assembleFrameworkTables` the migrator does. - **`voltro test` now derives `resolve.alias` from the app's tsconfig `paths`.** An app mapping `@/* → ./src/*` could not test any module importing through it (`Cannot find package '@/locales/en'`), and the workaround was a local `vitest.config.ts` restating what tsconfig already said. - **The `raw-fetch` doctor rule follows the import graph.** Keyed on filename conventions it caught 9 of 39 outbound calls on the reporting app; the other 30 were in `lib/*.ts` helpers only server code imports. A file reachable from a server-convention file and from nothing else is server code; one a page also imports is not, and stays unflagged.
+
+---
+
 ## [0.12.0] — 2026-07-25
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -5273,6 +5273,13 @@ export declare interface TypedInsertStore {
     readonly insert: (table: string, row: Row) => Promise<Row>;
 }
 
+/** The minimal store surface `updateManyRow` needs. */
+export declare interface TypedUpdateManyStore {
+    readonly updateMany: (table: string, patch: Readonly<Record<string, unknown>>, options: {
+        where: Predicate;
+    }) => Promise<number>;
+}
+
 /** The minimal store surface `upsertRow` needs. */
 export declare interface TypedUpsertStore {
     readonly upsert: (table: string, row: Row, options: {
@@ -5314,6 +5321,32 @@ export declare interface UniqueSpec {
     readonly dedup?: 'fail' | 'suffix-counter' | Statement.Fragment;
 }
 
+/**
+ * Bulk-update rows matching `where`, typed against the table: the patch is a
+ * `Partial<InferRow<T>>`, so a misspelled column or a value of the wrong type
+ * is a compile error instead of a dialect error at runtime (or, worse, a write
+ * that silently does nothing).
+ *
+ * This closes the last untyped write. It is worth stating what the typed
+ * versions actually bought, because it is not theoretical: migrating 29
+ * `store.upsert` call sites to `upsertRow` produced 15 `tsc` errors across 8
+ * distinct defects that no test had caught — among them seven per-user
+ * mutations with no authentication check at all (they wrote
+ * `ctx.request.subject.id`, typed `string | null`, into a NOT NULL column, so
+ * an anonymous caller reached the database and got a raw statement failure
+ * instead of a typed refusal), and a closed-set column receiving a value the
+ * descriptor had declared as `Schema.String`.
+ *
+ * The narrowest example is the most persuasive: a value spread from a plain
+ * object literal widens to `string`, and the column's `.oneOf()` union rejects
+ * it — even though the value IS one of the members. Neither a reviewer nor a
+ * test would plausibly find that. `as const` fixes it, and only the row type
+ * asks the question.
+ */
+export declare const updateManyRow: <T extends AnyTable>(store: TypedUpdateManyStore, table: T, patch: Readonly<Partial<InferRow<T>>>, options: {
+    readonly where: Predicate;
+}) => Promise<number>;
+
 /**
  * Upsert a row, typed the same way. `conflictColumns` is constrained to the
  * table's own column names, so a typo'd conflict key is a compile error too.

package/dist/index.js

@@ -1680,6 +1680,7 @@ var pt = (e) => e === "mysql" || e === "mariadb" || e === "mssql" || e === "sqli
 	revokedAt: w().nullable(),
 	createdBy: n().nullable(),
 	onBehalfOf: n().nullable(),
+	metadata: a().nullable(),
 	createdAt: w().default("now")
 }).index("byTenant", ["tenantId"]).reactive(), _a = [
 	da,
@@ -1713,40 +1714,40 @@ var pt = (e) => e === "mysql" || e === "mariadb" || e === "mssql" || e === "sqli
 }, Sa = (e, t, n) => e.insert(t.tableName, n), Ca = (e, t, n, r) => e.upsert(t.tableName, n, {
 	conflictColumns: r.conflictColumns,
 	...r.update === void 0 ? {} : { update: r.update }
-}), wa = 512, Ta = (e) => {
+}), wa = (e, t, n, r) => e.updateMany(t.tableName, n, { where: r.where }), Ta = 512, Ea = (e) => {
 	e.setMaxListeners(512);
-}, Ea = (e, t, n) => ({
+}, Da = (e, t, n) => ({
 	_tag: "PrimaryKeyConflictError",
 	table: e,
 	key: t,
 	cause: n
-}), Da = (e) => typeof e == "object" && !!e && e._tag === "PrimaryKeyConflictError", Oa = /* @__PURE__ */ new Map(), ka = (e) => {
+}), Oa = (e) => typeof e == "object" && !!e && e._tag === "PrimaryKeyConflictError", ka = /* @__PURE__ */ new Map(), Aa = (e) => {
 	if (!e.table || !e.timeColumn) throw Error("registerRetention: table + timeColumn are required");
 	if (!Number.isFinite(e.ttlMs) || e.ttlMs <= 0) throw Error(`registerRetention(${e.table}): ttlMs must be a positive number`);
-	Oa.set(e.table, e);
-}, Aa = () => [...Oa.values()], ja = () => Oa.clear(), Ma = async (e, t, n, r = 2e4) => {
+	ka.set(e.table, e);
+}, ja = () => [...ka.values()], Ma = () => ka.clear(), Na = async (e, t, n, r = 2e4) => {
 	let i = new Date(t - e.ttlMs), a = 0;
 	for (;;) {
 		let t = await n(e.table, e.timeColumn, i, r, e.where);
 		if (a += t, t < r) break;
 	}
 	return a;
-}, Na = (e, t) => {
+}, Pa = (e, t) => {
 	let n = Number(e ?? String(t));
 	return (Number.isFinite(n) && n > 0 ? n : t) * 36e5;
-}, Pa = "_voltro_cdc_offsets", Fa = f(Pa, {
+}, Fa = "_voltro_cdc_offsets", Ia = f(Fa, {
 	id: S({ prefix: "cdcoff" }),
 	replicaId: n(),
 	streamName: n(),
 	binlogFile: n(),
 	binlogPosition: n(),
 	updatedAt: w()
-}).index(["replicaId"]), Ia = f(Pa, {
+}).index(["replicaId"]), La = f(Fa, {
 	id: S({ prefix: "cdcoff" }),
 	replicaId: n(),
 	streamName: n(),
 	ctVersion: n(),
 	updatedAt: w()
-}).index(["replicaId"]), La = "postgres";
+}).index(["replicaId"]), Ra = "postgres";
 //#endregion
-export { r as AUTO_FILLED_COLUMNS, J as BranchNameInvalid, wi as BranchTransitionInvalid, Pa as CDC_OFFSETS_TABLE, wa as CHANGE_LISTENER_CEILING, Pe as ColumnBuilder, _t as ENCRYPTED_PREFIX, La as ENGINE, tn as EagerCardinalityError, Je as FILE_MIGRATION_PATTERN, vt as FieldDecryptionError, ne as MAX_IDENTIFIER_LENGTH, ft as SqlClient, fi as TableStreamError, hn as TenantNamespaceInvalid, mn as TenantNamespaceUnresolved, Bi as TenantRegionUnavailable, zi as TenantResidencyUnresolved, e as WARN_IDENTIFIER_LENGTH, ga as _voltroApiKeysTable, Fa as _voltroCdcOffsetsTable, ma as _voltroIdempotencyTable, ha as _voltroKvTable, pa as _voltroMigrationPlansTable, da as _voltroMigrationsTable, Ia as _voltroMssqlCdcOffsetsTable, fa as _voltroSeedsTable, Rr as actorsTable, Li as admitBranch, ge as allEnumRenames, Wt as allRegisteredRelations, ee as allRegisteredTables, ei as and, Ze as array, Jr as arrayContains, Xr as arrayHas, Yr as arrayOverlaps, rn as attachEagerLoads, $i as auditAllTableIndexes, Qi as auditTableIndexes, Ne as avg, Xe as avgOver, xe as bigint, Ji as bindResidentStore, we as boolean, xi as branchNamespaceName, He as bytes, Be as clearEnumRenames, Kt as clearRelationsRegistry, Wi as clearResidencyConfig, ja as clearRetentions, v as clearTableRegistry, Cn as coercePredicateValue, wn as coercePredicateValues, di as collectSubqueries, be as column, wt as columnSchema, Ln as compileEagerJson, P as compilePredicate, Tn as compileRawFragment, F as compileSelect, _i as computeEmbedding, qr as contains, Ce as count, Ve as countDistinct, Fe as databaseHandle, Ie as date, Oe as dbEnum, Ee as decimal, qe as declareEnumRename, Qt as decodeRowsFromSchema, Ct as decryptFieldsOnRead, la as defineMigration, le as defineMixin, oa as defineSeed, De as denseRank, Ue as deriveTypeIdPrefix, gt as deserializeArraysOnRead, Se as drainIdentifierWarnings, me as dropped, en as encodeRowForSchema, St as encryptFieldsForWrite, xt as encryptedColumnsOf, Pi as enforceBranchLimits, b as ensureTableRegistered, zr as eq, En as escapeLike, ui as evaluatePredicate, Te as except, si as exists, ia as formatIndexAuditIssue, _a as frameworkTables, m as generateId, ue as generateSnowflake, $e as geography, it as geometry, ye as getEnumRenames, Ut as getRelation, M as getRelations, Ui as getResidencyConfig, u as getTable, Vr as gt, Hr as gte, pn as hasEagerLoads, gi as hybridSearch, S as id, Gr as inSet, ai as inSubquery, k as inferForeignKey, Sa as insertRow, T as integer, pe as intersect, ie as interval, Si as isBranchNamespace, bt as isEncrypted, yt as isFieldDecryptionError, Le as isFileMigration, ua as isMigrationDefinition, Oi as isNeonConnection, Qr as isNotNull, Zr as isNull, Da as isPrimaryKeyConflictError, Ki as isRegionServable, Mt as isRelationsSpec, sa as isSeedDefinition, x as isSqliteFamily, he as isView, a as json, ri as jsonField, ce as jsonIndex, Qe as lag, rt as lead, Aa as listRetentions, Ur as lt, Wr as lte, Ri as makeNamespaceBranchExecutor, Pt as many, Ft as manyToMany, tt as materializeFields, _e as max, We as migration, nt as min, xa as missingConflictColumns, ba as missingRequiredColumns, d as mixin, Br as neq, Ti as nextBranchState, ni as not, ci as notExists, Kr as notInSet, oi as notInSubquery, oe as numeric, Nt as one, nn as oneCardinalityMessage, ti as or, re as paginateBy, i as paginateById, Mi as planBranch, Ei as planBranchProvision, Di as planBranchTeardown, Ni as planBranchTeardownFor, Ai as planNeonBranchProvision, ji as planNeonBranchTeardown, Ea as primaryKeyConflictError, Fi as provisionBranch, Yi as provisionResidentTenant, bn as qualifyTable, et as queryFor, ze as queryForView, at as quoteIdent, Ta as raiseChangeListenerCeiling, ae as rank, l as raw, s as real, y as reference, Pr as registerCoreTables, Ht as registerDiscoveredRelations, Vt as registerRelations, ka as registerRetention, p as registerTable, jt as relations, Ir as requireActors, g as requireTable, Lr as requireTenants, fe as resetSnowflake, qi as residentPlacement, ki as resolveBranchMechanism, c as resolveFullTextIndex, de as resolveIdScheme, h as resolveMixinGraph, Gi as resolveTenantHome, yn as resolveTenantNamespace, Na as retentionTtlMsFromEnv, o as rowNumber, Tt as rowSchema, vn as sanitizeIdentifierFragment, ht as serializeArraysForWrite, Me as serverOnlyColumns, Hi as setResidencyConfig, $r as spatialPredicate, va as stampGeneratedId, ya as stampGeneratedIds, hi as streamTable, te as sum, je as sumOver, Ma as sweepRetention, f as table, Ii as teardownBranch, n as text, w as timestamp, ot as timestampMs, st as timestampMsOrNull, t as union, Ae as unionAll, Ca as upsertRow, Ye as validateColumnName, Re as validateIndexName, Gt as validateRegisteredRelations, Rt as validateRelationConfig, Ge as validateTableName, ke as validateTypeIdPrefix, _ as vector, se as vectorDistanceToOpclass, vi as vectorEmbedding, Ke as view, ve as viewSql, q as walkLeaves };
+export { r as AUTO_FILLED_COLUMNS, J as BranchNameInvalid, wi as BranchTransitionInvalid, Fa as CDC_OFFSETS_TABLE, Ta as CHANGE_LISTENER_CEILING, Pe as ColumnBuilder, _t as ENCRYPTED_PREFIX, Ra as ENGINE, tn as EagerCardinalityError, Je as FILE_MIGRATION_PATTERN, vt as FieldDecryptionError, ne as MAX_IDENTIFIER_LENGTH, ft as SqlClient, fi as TableStreamError, hn as TenantNamespaceInvalid, mn as TenantNamespaceUnresolved, Bi as TenantRegionUnavailable, zi as TenantResidencyUnresolved, e as WARN_IDENTIFIER_LENGTH, ga as _voltroApiKeysTable, Ia as _voltroCdcOffsetsTable, ma as _voltroIdempotencyTable, ha as _voltroKvTable, pa as _voltroMigrationPlansTable, da as _voltroMigrationsTable, La as _voltroMssqlCdcOffsetsTable, fa as _voltroSeedsTable, Rr as actorsTable, Li as admitBranch, ge as allEnumRenames, Wt as allRegisteredRelations, ee as allRegisteredTables, ei as and, Ze as array, Jr as arrayContains, Xr as arrayHas, Yr as arrayOverlaps, rn as attachEagerLoads, $i as auditAllTableIndexes, Qi as auditTableIndexes, Ne as avg, Xe as avgOver, xe as bigint, Ji as bindResidentStore, we as boolean, xi as branchNamespaceName, He as bytes, Be as clearEnumRenames, Kt as clearRelationsRegistry, Wi as clearResidencyConfig, Ma as clearRetentions, v as clearTableRegistry, Cn as coercePredicateValue, wn as coercePredicateValues, di as collectSubqueries, be as column, wt as columnSchema, Ln as compileEagerJson, P as compilePredicate, Tn as compileRawFragment, F as compileSelect, _i as computeEmbedding, qr as contains, Ce as count, Ve as countDistinct, Fe as databaseHandle, Ie as date, Oe as dbEnum, Ee as decimal, qe as declareEnumRename, Qt as decodeRowsFromSchema, Ct as decryptFieldsOnRead, la as defineMigration, le as defineMixin, oa as defineSeed, De as denseRank, Ue as deriveTypeIdPrefix, gt as deserializeArraysOnRead, Se as drainIdentifierWarnings, me as dropped, en as encodeRowForSchema, St as encryptFieldsForWrite, xt as encryptedColumnsOf, Pi as enforceBranchLimits, b as ensureTableRegistered, zr as eq, En as escapeLike, ui as evaluatePredicate, Te as except, si as exists, ia as formatIndexAuditIssue, _a as frameworkTables, m as generateId, ue as generateSnowflake, $e as geography, it as geometry, ye as getEnumRenames, Ut as getRelation, M as getRelations, Ui as getResidencyConfig, u as getTable, Vr as gt, Hr as gte, pn as hasEagerLoads, gi as hybridSearch, S as id, Gr as inSet, ai as inSubquery, k as inferForeignKey, Sa as insertRow, T as integer, pe as intersect, ie as interval, Si as isBranchNamespace, bt as isEncrypted, yt as isFieldDecryptionError, Le as isFileMigration, ua as isMigrationDefinition, Oi as isNeonConnection, Qr as isNotNull, Zr as isNull, Oa as isPrimaryKeyConflictError, Ki as isRegionServable, Mt as isRelationsSpec, sa as isSeedDefinition, x as isSqliteFamily, he as isView, a as json, ri as jsonField, ce as jsonIndex, Qe as lag, rt as lead, ja as listRetentions, Ur as lt, Wr as lte, Ri as makeNamespaceBranchExecutor, Pt as many, Ft as manyToMany, tt as materializeFields, _e as max, We as migration, nt as min, xa as missingConflictColumns, ba as missingRequiredColumns, d as mixin, Br as neq, Ti as nextBranchState, ni as not, ci as notExists, Kr as notInSet, oi as notInSubquery, oe as numeric, Nt as one, nn as oneCardinalityMessage, ti as or, re as paginateBy, i as paginateById, Mi as planBranch, Ei as planBranchProvision, Di as planBranchTeardown, Ni as planBranchTeardownFor, Ai as planNeonBranchProvision, ji as planNeonBranchTeardown, Da as primaryKeyConflictError, Fi as provisionBranch, Yi as provisionResidentTenant, bn as qualifyTable, et as queryFor, ze as queryForView, at as quoteIdent, Ea as raiseChangeListenerCeiling, ae as rank, l as raw, s as real, y as reference, Pr as registerCoreTables, Ht as registerDiscoveredRelations, Vt as registerRelations, Aa as registerRetention, p as registerTable, jt as relations, Ir as requireActors, g as requireTable, Lr as requireTenants, fe as resetSnowflake, qi as residentPlacement, ki as resolveBranchMechanism, c as resolveFullTextIndex, de as resolveIdScheme, h as resolveMixinGraph, Gi as resolveTenantHome, yn as resolveTenantNamespace, Pa as retentionTtlMsFromEnv, o as rowNumber, Tt as rowSchema, vn as sanitizeIdentifierFragment, ht as serializeArraysForWrite, Me as serverOnlyColumns, Hi as setResidencyConfig, $r as spatialPredicate, va as stampGeneratedId, ya as stampGeneratedIds, hi as streamTable, te as sum, je as sumOver, Na as sweepRetention, f as table, Ii as teardownBranch, n as text, w as timestamp, ot as timestampMs, st as timestampMsOrNull, t as union, Ae as unionAll, wa as updateManyRow, Ca as upsertRow, Ye as validateColumnName, Re as validateIndexName, Gt as validateRegisteredRelations, Rt as validateRelationConfig, Ge as validateTableName, ke as validateTypeIdPrefix, _ as vector, se as vectorDistanceToOpclass, vi as vectorEmbedding, Ke as view, ve as viewSql, q as walkLeaves };

package/dist/sql.d.ts

@@ -29,6 +29,14 @@ export declare interface AppliedMigration {
     readonly environment: 'dev' | 'staging' | 'prod';
     readonly rollbackPlan?: ReadonlyArray<MigrationOperation>;
     readonly durationMs: number;
+    /**
+     * How many operations the applier actually EXECUTED, counted from the per-op
+     * results — not `operations.length`, which is what the plan asked for. The
+     * two can only differ if an op reports `skipped`, but the log lines quote
+     * this one on principle: "applied N op(s)" derived from the plan length is a
+     * claim about intent dressed up as a claim about the database.
+     */
+    readonly appliedOps: number;
     readonly onlineStrategy?: 'inline' | 'concurrent' | 'batched' | 'shadow-column';
     readonly source: 'auto-diff' | 'file';
     readonly notes?: string;
@@ -90,6 +98,31 @@ export declare interface ApplyPlanCtx {
     readonly source: 'auto-diff' | 'file';
     /** Optional human note via `voltro db apply --note "..."`. */
     readonly notes?: string;
+    /**
+     * Re-plan against the LIVE schema — the convergence proof.
+     *
+     * `applyPlan` calls this once, after the DDL and BEFORE it records the
+     * fingerprint. A plan that converged re-plans to zero operations; anything
+     * left is DDL that ran without error and did not take effect, and the apply
+     * fails rather than recording a fingerprint that describes a database state
+     * that does not exist.
+     *
+     * This exists because "reports success, applies nothing" is not hypothetical.
+     * A schema shipped 31 operations that logged `applied 31 op(s)` on every boot
+     * for two releases: the statements were real, postgres accepted all of them,
+     * and none of them changed anything (`ALTER COLUMN … TYPE text` on a text
+     * column; `SET DEFAULT NULL` for a default the renderer couldn't express).
+     * The recorded fingerprint then made the next boot short-circuit on
+     * "schema up to date". Both underlying defects are fixed — this is the guard
+     * that makes the NEXT one loud instead of permanent.
+     *
+     * It is REQUIRED, not optional, because the caller is the only place that
+     * knows the exact planner inputs (which tables were filtered, which were
+     * ignored); an applier-side re-plan would compare against a different set and
+     * report drift that isn't there. A caller that cannot re-plan cannot prove it
+     * applied anything.
+     */
+    readonly replan: (sql: SqlClient.SqlClient) => Effect.Effect<MigrationPlan, SqlError_2, SqlClient.SqlClient>;
 }
 
 /**
@@ -598,6 +631,43 @@ export declare interface ColumnSnapshot {
      * blocks a masking export until classified.
      */
     readonly safe?: boolean;
+    /**
+     * Type PARAMETERS for the three `ColumnType`s whose DDL is not determined by
+     * the type tag alone — `vector(n)`, `array(of)`, `enum(name, values)`.
+     * DECLARED-side only (introspection reports a concrete SQL type, not the
+     * declaration that produced it).
+     *
+     * These exist because the applier renders its DDL from a ColumnSnapshot, not
+     * from the `ColumnDefinition` that `migrate.ts`'s canonical `sqlType` reads.
+     * Without them the snapshot renderers had nothing to render and collapsed all
+     * three to `text` — which is not a smaller mistake than it looks. A declared
+     * `vector(1536)` against a live `text` column planned an `alter-column-type`
+     * that emitted `ALTER COLUMN … TYPE text`: valid SQL, applied successfully,
+     * changed nothing. The plan re-emitted it on every boot, the applier reported
+     * success every time, and the schema never converged. (Reported from a live
+     * pod: "applied 31 op(s)" with none of the 31 present in the database.)
+     *
+     * The rule for anything added later: if the applier has to RENDER it, the
+     * snapshot has to CARRY it — a snapshot renderer must never invent a type it
+     * wasn't given.
+     */
+    readonly vectorDim?: number;
+    readonly vectorPrecision?: 'float32' | 'half';
+    readonly arrayElement?: ColumnType;
+    readonly enumName?: string;
+    readonly enumValues?: ReadonlyArray<string>;
+    /**
+     * PostGIS `geography(kind, srid)` / `geometry(kind, srid)` parameters. Same
+     * reason as the three above: a spatial column declares `type: 'text'`, so
+     * WITHOUT this the applier's `add-column` created a plain `text` column and
+     * introspection (`USER-DEFINED` → `text`) agreed with it — no churn, no
+     * error, and no spatial column. DECLARED-side only.
+     */
+    readonly spatial?: {
+        readonly kind: 'geography' | 'geometry';
+        readonly geomKind: string;
+        readonly srid: number;
+    };
 }
 
 declare type ColumnType = 'id' | 'text' | 'integer' | 'real' | 'decimal' | 'bigint' | 'boolean' | 'timestamp' | 'date' | 'json' | 'bytes' | 'reference' | 'vector' | 'enum' | 'array' | 'interval' | 'raw';
@@ -610,6 +680,16 @@ declare type ColumnType = 'id' | 'text' | 'integer' | 'real' | 'decimal' | 'bigi
  */
 export declare const declaredSnapshot: (tables: ReadonlyArray<TableLike>, dialect?: DialectId) => SchemaSnapshot;
 
+/**
+ * `DEFAULT <expr>` for an array-valued default.
+ *
+ * Postgres is the only dialect with native arrays, so a `array()` column there
+ * takes an array literal (`'{a,b}'::text[]`); every other dialect stores the
+ * value as JSON/TEXT and takes the json form. A default on a `json()` column
+ * always takes the json form — the array is the VALUE, not the storage.
+ */
+export declare const defaultArrayClause: (value: ReadonlyArray<unknown>, column: ColumnDefinition<unknown>, dialect: DialectId) => string;
+
 export declare const defaultClause: (column: ColumnDefinition<unknown>, dialect: DialectId) => string | null;
 
 /**
@@ -1498,6 +1578,14 @@ export declare interface SchemaSnapshot {
  */
 export declare const shortFingerprint: (fp: string) => string;
 
+/**
+ * Snapshot a single `TableLike` declaration. Drops the runtime-only
+ * fields (`computed`, `defaultFactory`, `__tsType`) that don't round-
+ * trip to/from `information_schema`. `idScheme.kind` IS carried — the
+ * applier needs it to emit auto-increment DDL for numeric ids.
+ */
+export declare const snapshotColumn: (name: string, def: ColumnDefinition<unknown>) => ColumnSnapshot;
+
 /**
  * The `sql` template tag — captures a tagged-template literal into a
  * {@link RawSqlFragment} descriptor without binding it to any client.