turbine-orm 0.67.0 → 0.70.0

package/dist/query/filters.js

@@ -67,23 +67,23 @@ export const COLUMN_REF_OPERATORS = new Set(['equals', 'not', 'gt', 'gte', 'lt',
  * dependency is fixed: `cli/` and the prisma-compat shim may import from the
  * query path, and the query path may never import from `cli/`
  * (`scripts/check-import-cycles.mjs`).
+ *
+ * ## STATUS: a landing spot, not yet a deduplication. Read this before trusting it.
+ *
+ * NOTHING IMPORTS THIS YET. The three copies listed above are all still in
+ * place and still hand-synced; declaring the canonical home did not by itself
+ * move any of them onto it. It is kept, rather than deleted as unused, because
+ * `cli/pii-predicate-guard.ts` names this module as where its own copy wants to
+ * go, and deleting the destination is the one change that makes converging
+ * harder. Wiring the copies up is a separate change: each one sits on a
+ * different walk, so each has to be re-tested on its own.
+ *
+ * So do not read this constant as evidence that the walkers agree. The comment
+ * on each copy is still the only thing holding them in step.
  */
 export const RELATION_FILTER_WRAPPERS = ['some', 'none', 'every', 'is', 'isNot'];
 /** {@link RELATION_FILTER_WRAPPERS} as a membership set, for the walkers. */
 export const RELATION_FILTER_WRAPPER_SET = new Set(RELATION_FILTER_WRAPPERS);
-/**
- * True when a normalized relation-filter body carries at least one cardinality
- * wrapper. THE predicate the SQL compiler branches on: a key that names a
- * relation but whose value is not one of these falls through to the scalar
- * path.
- */
-export function hasRelationFilterWrapper(filterObj) {
-    for (const wrapper of RELATION_FILTER_WRAPPERS) {
-        if (wrapper in filterObj)
-            return true;
-    }
-    return false;
-}
 /**
  * Check if an operator value is a column reference: a plain object whose ONLY
  * key is `col` with a string value. Anything else (extra keys, non-string

package/dist/query/where-compile.js

@@ -34,7 +34,7 @@
  * step.
  */
 import { ValidationError } from '../errors.js';
-import { findArrayUniqueKey, findJsonUniqueKey, fingerprintArrayFilterShape, fingerprintJsonFilterShape, fingerprintOperatorShape, hasRelationFilterWrapper, isArrayFilter, isJsonFilter, isTextSearchFilter, isUnmatchedPlainObject, isVectorFilter, isWhereOperator, sortedKeys, VECTOR_DISTANCE_COMPARATORS, } from './filters.js';
+import { findArrayUniqueKey, findJsonUniqueKey, fingerprintArrayFilterShape, fingerprintJsonFilterShape, fingerprintOperatorShape, isArrayFilter, isJsonFilter, isTextSearchFilter, isUnmatchedPlainObject, isVectorFilter, isWhereOperator, sortedKeys, VECTOR_DISTANCE_COMPARATORS, } from './filters.js';
 import { ownLookup } from './utils.js';
 /**
  * Maximum nesting of `OR` / `AND` / `NOT` combinators and relation-filter

package/dist/query/where.d.ts

@@ -10,9 +10,9 @@
  * instance (built once in its constructor) exposing exactly the class-resident
  * primitives this module needs. See builder.ts for the thin delegating methods.
  */
-import type pg from 'pg';
 import type { Dialect } from '../dialect.js';
 import { ValidationError } from '../errors.js';
+import type { PgCompatQueryResult } from '../pg-types.js';
 import type { RelationDef, SchemaMetadata, TableMetadata } from '../schema.js';
 import type { TemporalInfinityReading } from './deferred.js';
 import type { ArrayFilter, ColumnRef, GlobalFilters, JsonFilter, JsonPathOrderBy, ResolvedSkipGlobalFilters, TextSearchFilter, VectorFilter, WhereClause, WhereOperator } from './types.js';
@@ -127,7 +127,7 @@ export interface BuilderCtx {
     resolveOrderByColumn(table: string, meta: TableMetadata, key: string): string;
     buildJsonPathOrderEntry(table: string, meta: TableMetadata, field: string, spec: JsonPathOrderBy, prefix: string, params?: unknown[]): string;
     toSqlColumn(field: string): string;
-    mutationInsertId(result: pg.QueryResult): unknown;
+    mutationInsertId(result: PgCompatQueryResult): unknown;
     acquireSql(cacheKey: string, build: (params: unknown[]) => string): SqlCacheEntry;
     crossCheckCache(op: string, cacheKey: string, entry: SqlCacheEntry, build: (params: unknown[]) => string, collectedParams: unknown[]): void;
     readonly jsonEncoding: 'object' | 'positional';

package/dist/schema-sql.d.ts

@@ -35,6 +35,24 @@ export declare function schemaToSQL(schema: SchemaDef, options?: SchemaSqlOption
  * column list), or null when the definitions agree. Expression/partial indexes
  * in the DB never structurally match a plain column list, which is the
  * intended outcome: the operator gets a warning rather than a silent skip.
+ *
+ * ## Parser 3 of 3, and what it is safe for
+ *
+ * THREE indexdef parsers coexist in this repo, catalogued on
+ * `parseIndexKeyEntries` in introspect.ts: that character-by-character scanner
+ * (the one to prefer for new callers), `parsePlainUniqueIndexColumns` in the
+ * same file, and this one. The two in introspect.ts do NOT feed this function
+ * and a fix to either does not reach it.
+ *
+ * This still uses the `USING \w+ \(([^)]*)\)` regex the scanner was written to
+ * replace, so it inherits the same weaknesses: it stops at the FIRST `)`, and it
+ * splits on every comma, which misreads an expression key (`lower(email)`), a
+ * quoted identifier containing a comma or a paren, and an opclass'd key. Safe
+ * here because every outcome of a misread is the SAME outcome as a genuine
+ * mismatch: a string describing the difference, which the caller turns into a
+ * warning for a human to read. It never drops or alters an index, and it is
+ * never consulted about whether a column set is unique. Do not reuse it
+ * anywhere those two properties stop holding.
  */
 export declare function describeIndexDefMismatch(idx: ColumnIndexDef, indexdef: string): string | null;
 /**

package/dist/schema-sql.js

@@ -384,6 +384,24 @@ function declaredIndexName(tableName, idx) {
  * column list), or null when the definitions agree. Expression/partial indexes
  * in the DB never structurally match a plain column list, which is the
  * intended outcome: the operator gets a warning rather than a silent skip.
+ *
+ * ## Parser 3 of 3, and what it is safe for
+ *
+ * THREE indexdef parsers coexist in this repo, catalogued on
+ * `parseIndexKeyEntries` in introspect.ts: that character-by-character scanner
+ * (the one to prefer for new callers), `parsePlainUniqueIndexColumns` in the
+ * same file, and this one. The two in introspect.ts do NOT feed this function
+ * and a fix to either does not reach it.
+ *
+ * This still uses the `USING \w+ \(([^)]*)\)` regex the scanner was written to
+ * replace, so it inherits the same weaknesses: it stops at the FIRST `)`, and it
+ * splits on every comma, which misreads an expression key (`lower(email)`), a
+ * quoted identifier containing a comma or a paren, and an opclass'd key. Safe
+ * here because every outcome of a misread is the SAME outcome as a genuine
+ * mismatch: a string describing the difference, which the caller turns into a
+ * warning for a human to read. It never drops or alters an index, and it is
+ * never consulted about whether a column set is unique. Do not reuse it
+ * anywhere those two properties stop holding.
  */
 export function describeIndexDefMismatch(idx, indexdef) {
     const dbUnique = /^\s*CREATE\s+UNIQUE\s+INDEX\b/i.test(indexdef);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.67.0",
+  "version": "0.70.0",
   "description": "Postgres-native TypeScript ORM, runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "//exports": "Each subpath declares its types PER CONDITION. A single shared top-level \"types\" resolves to the ESM declarations for `require` too, which is TS1479 (\"is an ES module ... cannot be require()d\") for any CJS consumer on moduleResolution node16/nodenext. The require condition points at dist/cjs, which ships its own {\"type\":\"commonjs\"} package.json, so those declarations are CJS declarations. Gated in CI by publint + @arethetypeswrong/cli + a real .cts consumer typecheck (see the package-types job in ci.yml).",
@@ -124,24 +124,35 @@
     "test:unit": "DATABASE_URL= tsx --test src/test/*.test.ts",
     "test:coverage": "c8 tsx --test --test-concurrency=1 src/test/*.test.ts",
     "//coverage:cli": "The CLI coverage gate, split into ONE collection run plus FOUR threshold checks. c8 enforces a single threshold set per invocation and its --per-file applies the SAME numbers to every file, neither of which can express 'destructive.ts holds 100 while migrate.ts holds 70'. An aggregate-only floor lets the least-covered file spend the whole slack the best-covered file earned: at the measured 3623/2951 lines, migrate.ts could fall from 70.3% to 66.6% with the aggregate still green. So each file gets its OWN floor, checked by re-reporting the coverage already on disk (c8 report re-reads ./coverage/tmp, so this costs no extra test run). The aggregate check is kept as well: it catches all three sagging together inside their individual margins. Per-file gates run FIRST because their failure names the file. DATABASE_URL is neutralized on the collection run: these test files include live migration tests that create and drop tables, and this script runs from prepublishOnly.",
-    "test:coverage:cli": "npm run coverage:cli:collect && npm run coverage:cli:gate:destructive && npm run coverage:cli:gate:sql-statements && npm run coverage:cli:gate:pii-guard && npm run coverage:cli:gate:studio && npm run coverage:cli:gate:migrate && npm run coverage:cli:gate:aggregate",
-    "coverage:cli:collect": "DATABASE_URL= c8 --all --reporter text --exclude 'src/test/**' --include src/cli/studio.ts --include src/cli/migrate.ts --include src/cli/destructive.ts --include src/cli/sql-statements.ts --include src/cli/pii-predicate-guard.ts tsx --test src/test/studio-write.test.ts src/test/studio-demo.test.ts src/test/studio.test.ts src/test/studio-security.test.ts src/test/migrate.test.ts src/test/migrate-deploy.test.ts src/test/migrate-smoke-fixes.test.ts src/test/destructive-migrations.test.ts src/test/backfill-recipe.test.ts src/test/cli.test.ts src/test/cli-diff-migration.test.ts src/test/cli-flags.test.ts src/test/cli-first-run.test.ts",
+    "test:coverage:cli": "npm run coverage:cli:collect && npm run coverage:cli:gate:destructive && npm run coverage:cli:gate:sql-statements && npm run coverage:cli:gate:pii-guard && npm run coverage:cli:gate:error-catalog && npm run coverage:cli:gate:mcp && npm run coverage:cli:gate:studio && npm run coverage:cli:gate:migrate && npm run coverage:cli:gate:aggregate",
+    "coverage:cli:collect": "DATABASE_URL= c8 --all --reporter text --exclude 'src/test/**' --include src/cli/studio.ts --include src/cli/migrate.ts --include src/cli/destructive.ts --include src/cli/sql-statements.ts --include src/cli/pii-predicate-guard.ts --include src/cli/mcp.ts --include src/cli/error-catalog.ts tsx --test src/test/studio-write.test.ts src/test/studio-demo.test.ts src/test/studio.test.ts src/test/studio-security.test.ts src/test/migrate.test.ts src/test/migrate-deploy.test.ts src/test/migrate-smoke-fixes.test.ts src/test/destructive-migrations.test.ts src/test/backfill-recipe.test.ts src/test/cli.test.ts src/test/cli-diff-migration.test.ts src/test/cli-flags.test.ts src/test/cli-first-run.test.ts src/test/mcp.test.ts src/test/mcp-relations.test.ts src/test/mcp-pii.test.ts src/test/mcp-pii-round2.test.ts src/test/mcp-agent-tools.test.ts",
     "coverage:cli:gate": "c8 report --all --exclude 'src/test/**' --reporter text --check-coverage",
     "coverage:cli:gate:destructive": "npm run coverage:cli:gate -- --include src/cli/destructive.ts --lines 98 --statements 98 --branches 84 --functions 98",
     "coverage:cli:gate:sql-statements": "npm run coverage:cli:gate -- --include src/cli/sql-statements.ts --lines 100 --statements 100 --branches 98 --functions 100",
     "coverage:cli:gate:pii-guard": "npm run coverage:cli:gate -- --include src/cli/pii-predicate-guard.ts --lines 97 --statements 97 --branches 88 --functions 100",
+    "//coverage:cli:gate:mcp": "The MCP server is a network-facing read-only surface with its own PII perimeter (sample_rows never fetches a hidden column, explain_query refuses a predicate on one, sanitizeIndex strips literals out of an index definition), so it belongs in this gate for the same reason cli/studio.ts does. It was added to coverage:cli:collect with no gate of its own and was absent from the aggregate's --include list, which meant it was COLLECTED and enforced by nothing: a slower lane holding a floor of zero. Floors measured 2026-08-14 at 93.47 lines / 93.47 statements / 81.77 branches / 92.30 functions.",
+    "coverage:cli:gate:mcp": "npm run coverage:cli:gate -- --include src/cli/mcp.ts --lines 93 --statements 93 --branches 81 --functions 91",
+    "coverage:cli:gate:error-catalog": "npm run coverage:cli:gate -- --include src/cli/error-catalog.ts --lines 100 --statements 100 --branches 90 --functions 100",
     "coverage:cli:gate:studio": "npm run coverage:cli:gate -- --include src/cli/studio.ts --lines 82 --statements 82 --branches 81 --functions 86",
     "coverage:cli:gate:migrate": "npm run coverage:cli:gate -- --include src/cli/migrate.ts --lines 69 --statements 69 --branches 91 --functions 73",
-    "coverage:cli:gate:aggregate": "npm run coverage:cli:gate -- --include src/cli/studio.ts --include src/cli/migrate.ts --include src/cli/destructive.ts --include src/cli/sql-statements.ts --include src/cli/pii-predicate-guard.ts --lines 78 --statements 78 --branches 84 --functions 82",
-    "lint": "biome check src/",
+    "//coverage:cli:gate:aggregate": "Re-baselined 2026-08-14 when mcp.ts and error-catalog.ts joined the --include list: measured 88.15 lines / 88.15 statements / 85.82 branches / 87.57 functions, up from a 78/78/84/82 floor set over five files. Raise as coverage improves, never lower one without recording why.",
+    "coverage:cli:gate:aggregate": "npm run coverage:cli:gate -- --include src/cli/studio.ts --include src/cli/migrate.ts --include src/cli/destructive.ts --include src/cli/sql-statements.ts --include src/cli/pii-predicate-guard.ts --include src/cli/mcp.ts --include src/cli/error-catalog.ts --lines 87 --statements 87 --branches 85 --functions 86",
+    "//lint": "`--error-on-warnings` is load-bearing, not cosmetic. Biome exits 0 on a warning, so `npm run lint` passed while reporting an unused import, and both the lint CI job and prepublishOnly read only the exit code. Every rule this repo runs is one it means, so a warning nobody has to act on is a rule that should not be enabled.",
+    "lint": "biome check --error-on-warnings src/",
     "lint:fix": "biome check --write src/",
     "format": "biome format --write src/",
     "check:error-codes": "tsx scripts/check-error-codes.ts",
     "check:changelog": "node scripts/check-changelog-headings.mjs",
     "check:cycles": "node scripts/check-import-cycles.mjs",
+    "//check:skip-gates": "Guards the TURBINE_REQUIRE_ENGINE coupling, which is a regex against a human-readable skipGate reason string: rewording a reason silently disarms the guard and the engine job it protects goes green over a suite that never ran. Fails on a reason no engine pattern claims and no allowlist entry excuses, on a token no CI job sets, and on a workflow token that is not a known engine.",
+    "check:skip-gates": "tsx scripts/check-skip-gate-reasons.ts",
+    "//check:private-terms": "The `--all` mode of the pre-commit private-material guard, over every TRACKED file rather than the staged diff. The hook is advisory (`git commit --no-verify` skips it) and nothing downstream re-asked, so this runs in CI's lint job. `.private-terms` is gitignored, so CI enforces the builtin provenance patterns only.",
+    "check:private-terms": "node scripts/check-private-terms.mjs --all",
     "check:release-tests": "node scripts/check-release-tests.mjs",
     "check:package": "publint --strict && attw --pack . --profile node16",
-    "prepublishOnly": "npm run build && npm run typecheck && npm run lint && npm run test:unit && npm run test:coverage:cli && npm run check:error-codes && npm run check:changelog && npm run check:cycles && npm run check:package && npm run size && npm run check:release-tests",
+    "//check:package-types": "The @types/pg tripwire, and the permanent guard on the v0.28.1 regression: no reference to the pg module family may reach a published .d.ts, or a types-only package becomes a hard requirement for every consumer compiling under strict. It lived as an inline grep in ONE ci.yml job, which left the gate proving the change safe off the publish path entirely (a tag push and a local `npm publish` both reached npm without asking). The logic is scripts/check-no-pg-types.mjs now and this script is its single entry point, called by prepublishOnly and by the `consumer-types` job in BOTH ci.yml and release.yml. Reads dist/, so it must run after `npm run build`.",
+    "check:package-types": "node scripts/check-no-pg-types.mjs",
+    "prepublishOnly": "npm run build && npm run typecheck && npm run lint && npm run test:unit && npm run test:coverage:cli && npm run check:error-codes && npm run check:changelog && npm run check:cycles && npm run check:skip-gates && npm run check:package && npm run check:package-types && npm run size && npm run check:release-tests",
     "prepack": "node scripts/strip-prepare.mjs",
     "postpack": "node scripts/restore-prepare.mjs",
     "size": "size-limit",
@@ -162,8 +173,8 @@
   "engines": {
     "node": ">=20.0.0"
   },
+  "//dependencies": "EXACTLY ONE runtime dependency, `pg`. `@types/pg` sat here until 0.70.0 because the published declarations named `pg.Pool` / `pg.PoolClient` / `pg.QueryResult`, which makes a types-only package a hard requirement for every consumer compiling under strict (the v0.28.1 regression). The declaration surface is now pg-free (see src/pg-types.ts) and the `consumer-types` CI job proves it against the real tarball, so the types package is a devDependency. The order is one-way: clear the surface FIRST, then move the dependency.",
   "dependencies": {
-    "@types/pg": "^8.11.11",
     "pg": "^8.13.1"
   },
   "devDependencies": {
@@ -172,6 +183,7 @@
     "@size-limit/esbuild": "^12.1.0",
     "@size-limit/file": "^12.1.0",
     "@types/node": "^26.1.0",
+    "@types/pg": "^8.11.11",
     "@zvndev/powdb-client": "^0.20.0",
     "@zvndev/powdb-embedded": "^0.20.0",
     "c8": "^11.0.0",