@palbase/backend 25.1.0 → 27.0.0

package/dist/db/index.cjs

@@ -3,6 +3,7 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -55,18 +56,149 @@ module.exports = __toCommonJS(db_exports);
 function qualifiedTableKey(schemaName, tableName) {
   return schemaName === "" || schemaName === "public" ? tableName : `${schemaName}.${tableName}`;
 }
+__name(qualifiedTableKey, "qualifiedTableKey");
 
 // src/db/policy.ts
+var PolicyExprRef = class _PolicyExprRef {
+  static {
+    __name(this, "PolicyExprRef");
+  }
+  expr;
+  constructor(expr) {
+    this.expr = expr;
+  }
+  bin(op, other) {
+    return new _PolicyExprRef({
+      kind: "binop",
+      op,
+      left: this.expr,
+      right: toExpr(other)
+    });
+  }
+  eq(other) {
+    return this.bin("eq", other);
+  }
+  neq(other) {
+    return this.bin("neq", other);
+  }
+  gt(other) {
+    return this.bin("gt", other);
+  }
+  gte(other) {
+    return this.bin("gte", other);
+  }
+  lt(other) {
+    return this.bin("lt", other);
+  }
+  lte(other) {
+    return this.bin("lte", other);
+  }
+  /**
+  * `IS NULL` / `IS NOT NULL` — `= NULL` SQL'de her zaman UNKNOWN'dır, o yüzden
+  * niyet ayrı bir düğümle yazılır. Partial index'in en sık koşulu
+  * (`WHERE deleted_at IS NULL`) tam olarak bu.
+  */
+  isNull(negated = false) {
+    return new _PolicyExprRef({
+      kind: "isNull",
+      expr: this.expr,
+      negated
+    });
+  }
+  and(...others) {
+    return new _PolicyExprRef({
+      kind: "and",
+      parts: [
+        this.expr,
+        ...others.map((o) => o.expr)
+      ]
+    });
+  }
+  or(...others) {
+    return new _PolicyExprRef({
+      kind: "or",
+      parts: [
+        this.expr,
+        ...others.map((o) => o.expr)
+      ]
+    });
+  }
+  not() {
+    return new _PolicyExprRef({
+      kind: "not",
+      expr: this.expr
+    });
+  }
+};
+function toExpr(v) {
+  return v instanceof PolicyExprRef ? v.expr : {
+    kind: "lit",
+    value: v
+  };
+}
+__name(toExpr, "toExpr");
+function exprCtx(_columns, depth = 0, ownTable = "") {
+  const alias = `pb_e${depth}`;
+  return {
+    col: /* @__PURE__ */ __name((name) => new PolicyExprRef(depth === 0 ? {
+      kind: "col",
+      name
+    } : {
+      kind: "col",
+      name,
+      alias
+    }), "col"),
+    auth: {
+      uid: /* @__PURE__ */ __name(() => new PolicyExprRef({
+        kind: "authUid"
+      }), "uid")
+    },
+    lit: /* @__PURE__ */ __name((v) => new PolicyExprRef({
+      kind: "lit",
+      value: v
+    }), "lit"),
+    and: /* @__PURE__ */ __name((...parts) => new PolicyExprRef({
+      kind: "and",
+      parts: parts.map((p) => p.expr)
+    }), "and"),
+    or: /* @__PURE__ */ __name((...parts) => new PolicyExprRef({
+      kind: "or",
+      parts: parts.map((p) => p.expr)
+    }), "or"),
+    not: /* @__PURE__ */ __name((part) => new PolicyExprRef({
+      kind: "not",
+      expr: part.expr
+    }), "not"),
+    existsIn: /* @__PURE__ */ __name((table, predicate) => {
+      const meta = table[TABLE_META];
+      const inner = exprCtx(Object.keys(meta.columns), depth + 1, ownTable);
+      return new PolicyExprRef({
+        kind: "exists",
+        table: meta.name,
+        alias: `pb_e${depth + 1}`,
+        outer: ownTable,
+        predicate: predicate(inner).expr
+      });
+    }, "existsIn")
+  };
+}
+__name(exprCtx, "exprCtx");
 function quote(name) {
   return `"${name.replace(/"/g, '""')}"`;
 }
+__name(quote, "quote");
 var PolicyBuilder = class {
+  static {
+    __name(this, "PolicyBuilder");
+  }
   _def;
   constructor(name) {
     this._def = {
       name,
       command: "all",
-      roles: ["authenticated"],
+      roles: [
+        "authenticated"
+      ],
       using: null,
       withCheck: null,
       permissive: true
@@ -78,65 +210,78 @@ var PolicyBuilder = class {
     return this;
   }
   /**
-   * Set the DB roles the policy applies to (the `TO` clause), replacing any
-   * previously-set roles. Call with no arguments to target PUBLIC (all roles).
-   *
-   * @example
-   * policy("p").to("authenticated")
-   * policy("p").to("authenticated", "service_role")
-   * policy("p").to() // PUBLIC
-   */
+  * Set the DB roles the policy applies to (the `TO` clause), replacing any
+  * previously-set roles. Call with no arguments to target PUBLIC (all roles).
+  *
+  * @example
+  * policy("p").to("authenticated")
+  * policy("p").to("authenticated", "service_role")
+  * policy("p").to() // PUBLIC
+  */
   to(...roles) {
     this._def.roles = roles;
     return this;
   }
-  /** Set the `USING (...)` row-visibility expression (raw SQL). */
-  using(sqlExpr) {
-    this._def.using = sqlExpr;
+  /**
+  * `USING (...)` satır görünürlüğü ifadesi.
+  *
+  * Tercih edilen biçim YAPI'dır (FR-022) — `policies` callback'inin verdiği
+  * bağlamla kurulur ve kolon adları derlemede doğrulanır:
+  *
+  * ```ts
+  * policies: (p) => [
+  *   policy("owner_read").for("select").using(p.col("owner").eq(p.auth.uid())),
+  * ]
+  * ```
+  *
+  * Ham string KAÇIŞ KAPAĞI olarak kalır (FR-028): yapının ifade edemediği bir
+  * şey gerektiğinde yol kapanmaz. Ama o yolda kolon adı doğrulaması yoktur ve
+  * hata deploy anında Postgres'ten gelir.
+  */
+  using(expr) {
+    this._def.using = expr instanceof PolicyExprRef ? expr.expr : expr;
     return this;
   }
   /**
-   * "Rows of THIS table whose owner the caller is a member of" — the membership
-   * pattern, written so it cannot recurse.
-   *
-   * THE TRAP IT EXISTS FOR. Written by hand, membership policies point at each
-   * other: `channels` is visible to members, so its policy reads
-   * `channel_members`; `channel_members` is visible to members, so its policy
-   * reads `channels`. Postgres refuses the pair at query time with `infinite
-   * recursion detected in policy for relation ...`, and the error names the
-   * relation but not the cycle. The way out is asymmetry — the MEMBERSHIP table
-   * is protected by `user_id = auth.uid()` and nothing else, and every other
-   * table subqueries INTO it. That shape was in the platform's own schema and
-   * written down nowhere; a customer recovered it by reading that schema.
-   *
-   * `(select auth.uid())` rather than a bare call: the scalar subquery is
-   * evaluated ONCE per statement instead of per row.
-   *
-   * @example
-   * // channels: visible to members. The membership table gets the simple one.
-   * policy("member_read").for("select").to("authenticated")
-   *   .memberOf("channel_members", "channel_id")
-   * // → id IN (SELECT "channel_id" FROM "channel_members"
-   * //          WHERE "user_id" = (select auth.uid()))
-   */
+  * "Rows of THIS table whose owner the caller is a member of" — the membership
+  * pattern, written so it cannot recurse.
+  *
+  * THE TRAP IT EXISTS FOR. Written by hand, membership policies point at each
+  * other: `channels` is visible to members, so its policy reads
+  * `channel_members`; `channel_members` is visible to members, so its policy
+  * reads `channels`. Postgres refuses the pair at query time with `infinite
+  * recursion detected in policy for relation ...`, and the error names the
+  * relation but not the cycle. The way out is asymmetry — the MEMBERSHIP table
+  * is protected by `user_id = auth.uid()` and nothing else, and every other
+  * table subqueries INTO it. That shape was in the platform's own schema and
+  * written down nowhere; a customer recovered it by reading that schema.
+  *
+  * `(select auth.uid())` rather than a bare call: the scalar subquery is
+  * evaluated ONCE per statement instead of per row.
+  *
+  * @example
+  * // channels: visible to members. The membership table gets the simple one.
+  * policy("member_read").for("select").to("authenticated")
+  *   .memberOf("channel_members", "channel_id")
+  * // → id IN (SELECT "channel_id" FROM "channel_members"
+  * //          WHERE "user_id" = (select auth.uid()))
+  */
   memberOf(membershipTable, foreignKey, options = {}) {
     if (this._def.using !== null) {
-      throw new Error(
-        `policy(${this._def.name}).memberOf(): this policy already has a using() expression. Write one or the other \u2014 memberOf IS the using expression.`
-      );
+      throw new Error(`policy(${this._def.name}).memberOf(): this policy already has a using() expression. Write one or the other \u2014 memberOf IS the using expression.`);
     }
     const column = options.column ?? "id";
     const userColumn = options.userColumn ?? "user_id";
     this._def.using = `${quote(column)} IN (SELECT ${quote(foreignKey)} FROM ${quote(membershipTable)} WHERE ${quote(userColumn)} = (select auth.uid()))`;
     return this;
   }
-  /** Set the `WITH CHECK (...)` write-validation expression (raw SQL). */
-  withCheck(sqlExpr) {
-    this._def.withCheck = sqlExpr;
+  /** `WITH CHECK (...)` yazma doğrulaması — `using` ile aynı iki biçim. */
+  withCheck(expr) {
+    this._def.withCheck = expr instanceof PolicyExprRef ? expr.expr : expr;
     return this;
   }
   /** Set the policy mode: `"permissive"` (default, OR-combined) or
-   * `"restrictive"` (AND-combined). */
+  * `"restrictive"` (AND-combined). */
   as(mode) {
     this._def.permissive = mode === "permissive";
     return this;
@@ -145,23 +290,93 @@ var PolicyBuilder = class {
 function policy(name) {
   return new PolicyBuilder(name);
 }
+__name(policy, "policy");
 
 // src/db/schema.ts
+var IndexBuilder = class {
+  static {
+    __name(this, "IndexBuilder");
+  }
+  _def;
+  constructor(name) {
+    if (name.trim() === "") {
+      throw new Error("index(ad): index'in ad\u0131 bo\u015F olamaz \u2014 Palbase index'leri ADA g\xF6re uzla\u015Ft\u0131r\u0131r.");
+    }
+    this._def = {
+      name
+    };
+  }
+  /** Index'in kolonları. SIRA KORUNUR — çok kolonlu bir index'in anlamı sırasıdır. */
+  on(...cols) {
+    this._def.columns = cols.map((c) => {
+      const e = c.expr;
+      if (e.kind !== "col") {
+        throw new Error(`index(${this._def.name}).on(): yaln\u0131z kolon referans\u0131 al\u0131r \u2014 ifade i\xE7in onExpression("\u2026") kullan\u0131n.`);
+      }
+      return e.name;
+    });
+    return this;
+  }
+  /**
+  * İfade index'i (`lower(email)`), kolon yerine.
+  *
+  * Metin VERBATIM emit ediliyor — `policy().using("…")` ile aynı güven duruşu.
+  * Tipli yapı bunu ifade edemiyor ve kaçış kapağını kapatmak, yazarı elle
+  * migration yazmaya iterdi.
+  */
+  onExpression(expr) {
+    this._def.expression = expr;
+    return this;
+  }
+  /** Partial index koşulu — politika ifade dilinin ta kendisi. */
+  where(expr) {
+    this._def.where = expr.expr;
+    return this;
+  }
+  /** Sıra. Tek yönlü index'te sıra genelde önemsizdir; ORDER BY ile eşleşen
+  * bir index arandığında değildir. */
+  desc() {
+    this._def.sort = "desc";
+    return this;
+  }
+  asc() {
+    this._def.sort = "asc";
+    return this;
+  }
+  /** NULL'ların yeri — `ORDER BY … NULLS LAST` ile eşleşmesi için. */
+  nulls(where) {
+    this._def.nulls = where;
+    return this;
+  }
+  /** Covering index (`INCLUDE`): index-only scan için taşınan ama
+  * ARANMAYAN kolonlar. */
+  include(cols) {
+    this._def.include = cols;
+    return this;
+  }
+};
 function toPolicyDef(p) {
   return p instanceof PolicyBuilder ? p._def : p;
 }
+__name(toPolicyDef, "toPolicyDef");
 var TABLE_META = /* @__PURE__ */ Symbol.for("palbase.table.meta");
 function defineTable(name, input) {
   if (name.trim() === "") {
     throw new Error("defineTable(name, \u2026): name must not be empty");
   }
-  const policies = (input.policies ?? []).map(toPolicyDef);
+  const policies = (input.policies?.(exprCtx(Object.keys(input.columns), 0, name)) ?? []).map(toPolicyDef);
   const rls = policies.length > 0 || input.rls !== false;
   const owned = {};
   for (const [colName, b] of Object.entries(input.columns)) {
     const builder = b;
     const clone = Object.create(Object.getPrototypeOf(builder));
-    Object.defineProperty(clone, "_def", { value: { ...builder._def }, enumerable: true, writable: true });
+    Object.defineProperty(clone, "_def", {
+      value: {
+        ...builder._def
+      },
+      enumerable: true,
+      writable: true
+    });
     owned[colName] = clone;
   }
   const def = {
@@ -174,22 +389,20 @@ function defineTable(name, input) {
   if (input.unique !== void 0) def.unique = input.unique;
   if (input.raw !== void 0 && input.raw.length > 0) def.raw = input.raw.slice();
   if (input.checks !== void 0 && input.checks.length > 0) def.checks = input.checks.slice();
-  if (input.indexes !== void 0 && input.indexes.length > 0) def.indexes = input.indexes.slice();
+  const declaredIndexes = (input.indexes?.(exprCtx(Object.keys(input.columns), 0, name)) ?? []).map((i) => i instanceof IndexBuilder ? i._def : i);
+  if (declaredIndexes.length > 0) def.indexes = declaredIndexes;
+  if (input.appendOnly === true) def.appendOnly = true;
   if (input.search !== void 0) {
     const s = input.search;
     if (s.from !== void 0) {
       if (s.vector !== void 0) {
-        throw new Error(
-          `table ${name}: search beyan\u0131nda tek bi\xE7im kullan\u0131n \u2014 'from' (yeni) ile 'vector' (eski) birlikte olamaz`
-        );
+        throw new Error(`table ${name}: search beyan\u0131nda tek bi\xE7im kullan\u0131n \u2014 'from' (yeni) ile 'vector' (eski) birlikte olamaz`);
       }
       if (s.from.length === 0) {
         throw new Error(`table ${name}: search.from bo\u015F olamaz`);
       }
       if (s.model === void 0) {
-        throw new Error(
-          `table ${name}: search.from model'siz anlams\u0131z \u2014 auto-embed i\xE7in model verin (BYO i\xE7in eski 'vector' bi\xE7imini kullan\u0131n)`
-        );
+        throw new Error(`table ${name}: search.from model'siz anlams\u0131z \u2014 auto-embed i\xE7in model verin (BYO i\xE7in eski 'vector' bi\xE7imini kullan\u0131n)`);
       }
       if (Array.isArray(s.text) && s.text.length === 0) {
         throw new Error(`table ${name}: search.text bo\u015F dizi olamaz \u2014 FTS istemiyorsan text: false yaz\u0131n`);
@@ -199,14 +412,14 @@ function defineTable(name, input) {
         throw new Error(`table ${name}: text:${String(s.text)} yaln\u0131z yeni bi\xE7imde ('from' ile) ge\xE7erli`);
       }
       if (s.text === void 0 && s.vector === void 0) {
-        throw new Error(
-          `table ${name}: search beyan\u0131 bo\u015F \u2014 en az bir kol (text ya da vector) verin, yoksa alan\u0131 hi\xE7 yazmay\u0131n`
-        );
+        throw new Error(`table ${name}: search beyan\u0131 bo\u015F \u2014 en az bir kol (text ya da vector) verin, yoksa alan\u0131 hi\xE7 yazmay\u0131n`);
       }
       if (s.text !== void 0 && s.text.length === 0) {
         throw new Error(`table ${name}: search.text bo\u015F olamaz \u2014 FTS kolu istemiyorsan alan\u0131 hi\xE7 yazma`);
       }
-      const legs = s.vector === void 0 ? [] : Array.isArray(s.vector) ? s.vector : [s.vector];
+      const legs = s.vector === void 0 ? [] : Array.isArray(s.vector) ? s.vector : [
+        s.vector
+      ];
       for (const leg of legs) {
         if (leg.model !== void 0 && (leg.from === void 0 || leg.from.length === 0)) {
           throw new Error(`table ${name}: search.vector.model beyan edildi ama 'from' yok \u2014 embed kayna\u011F\u0131 kolonlar zorunlu (C-2)`);
@@ -227,10 +440,16 @@ function defineTable(name, input) {
   for (const b of Object.values(owned)) {
     b._def.ownerTable = def;
   }
-  const handle = { ...owned };
-  Object.defineProperty(handle, TABLE_META, { value: def, enumerable: false });
+  const handle = {
+    ...owned
+  };
+  Object.defineProperty(handle, TABLE_META, {
+    value: def,
+    enumerable: false
+  });
   return handle;
 }
+__name(defineTable, "defineTable");
 var declaringSchemaOf = /* @__PURE__ */ new WeakMap();
 function resolveReferences(tables, schemaName) {
   for (const table of Object.values(tables)) {
@@ -238,9 +457,7 @@ function resolveReferences(tables, schemaName) {
       const def = builder._def;
       if (def.selfRefColumn !== void 0) {
         if (!(def.selfRefColumn in table.columns)) {
-          throw new Error(
-            `table "${table.name}" column "${colName}": selfReferences("${def.selfRefColumn}") \u2014 no such column on this table`
-          );
+          throw new Error(`table "${table.name}" column "${colName}": selfReferences("${def.selfRefColumn}") \u2014 no such column on this table`);
         }
         def.references = {
           table: qualifiedTableKey(schemaName, table.name),
@@ -252,23 +469,15 @@ function resolveReferences(tables, schemaName) {
       const target = def.referencesThunk();
       const owner = target?._def?.ownerTable;
       if (owner === void 0) {
-        throw new Error(
-          `table "${table.name}" column "${colName}": references(() => \u2026) must point at a column of a table declared with defineTable(...)`
-        );
+        throw new Error(`table "${table.name}" column "${colName}": references(() => \u2026) must point at a column of a table declared with defineTable(...)`);
       }
-      const targetColumn = Object.entries(owner.columns).find(
-        ([, b]) => b._def === target._def
-      )?.[0];
+      const targetColumn = Object.entries(owner.columns).find(([, b]) => b._def === target._def)?.[0];
       if (targetColumn === void 0) {
-        throw new Error(
-          `table "${table.name}" column "${colName}": the referenced column was not found on table "${owner.name}"`
-        );
+        throw new Error(`table "${table.name}" column "${colName}": the referenced column was not found on table "${owner.name}"`);
       }
       const targetSchema = declaringSchemaOf.get(owner);
       if (targetSchema === void 0) {
-        throw new Error(
-          `table "${table.name}" column "${colName}": references(() => \u2026) points at table "${owner.name}", which no defineSchema(...) has claimed yet \u2014 a foreign key cannot be written without its target's schema. Declare that table's schema first (one file per schema: db/public.ts, db/billing.ts \u2026, imported by this one).`
-        );
+        throw new Error(`table "${table.name}" column "${colName}": references(() => \u2026) points at table "${owner.name}", which no defineSchema(...) has claimed yet \u2014 a foreign key cannot be written without its target's schema. Declare that table's schema first (one file per schema: db/public.ts, db/billing.ts \u2026, imported by this one).`);
       }
       def.references = {
         table: qualifiedTableKey(targetSchema, owner.name),
@@ -277,11 +486,10 @@ function resolveReferences(tables, schemaName) {
     }
   }
 }
+__name(resolveReferences, "resolveReferences");
 function defineSchema(name, input) {
   if (typeof name !== "string") {
-    throw new Error(
-      `defineSchema(...) takes the schema NAME first: defineSchema("public", { tables: [todos, lists] }). The one-argument form defineSchema({ tables: { \u2026 } }) is gone \u2014 a schema that does not say its own name cannot be told apart from another schema's table of the same name, which is what a cross-schema foreign key has to do. Migrate db/public.ts (one file per schema: db/public.ts, db/billing.ts \u2026): name the schema, and lift each table key onto the table itself with defineTable("todos", { columns: { \u2026 } }), then list the tables in the array.`
-    );
+    throw new Error(`defineSchema(...) takes the schema NAME first: defineSchema("public", { tables: [todos, lists] }). The one-argument form defineSchema({ tables: { \u2026 } }) is gone \u2014 a schema that does not say its own name cannot be told apart from another schema's table of the same name, which is what a cross-schema foreign key has to do. Migrate db/public.ts (one file per schema: db/public.ts, db/billing.ts \u2026): name the schema, and lift each table key onto the table itself with defineTable("todos", { columns: { \u2026 } }), then list the tables in the array.`);
   }
   if (name.trim() === "") {
     throw new Error("defineSchema(name, \u2026): name must not be empty");
@@ -290,9 +498,7 @@ function defineSchema(name, input) {
   for (const handle of input.tables) {
     const table = handle[TABLE_META];
     if (tables[table.name] !== void 0) {
-      throw new Error(
-        `defineSchema("${name}"): two tables declare the name "${table.name}" \u2014 table names must be unique within a schema`
-      );
+      throw new Error(`defineSchema("${name}"): two tables declare the name "${table.name}" \u2014 table names must be unique within a schema`);
     }
     tables[table.name] = table;
     declaringSchemaOf.set(table, name);
@@ -323,7 +529,9 @@ function defineSchema(name, input) {
       }
     }
   }
-  const extensions = [...new Set(input.extensions ?? [])];
+  const extensions = [
+    ...new Set(input.extensions ?? [])
+  ];
   return {
     name,
     tables,
@@ -331,46 +539,39 @@ function defineSchema(name, input) {
     exposed: input.exposed ?? name === "public"
   };
 }
+__name(defineSchema, "defineSchema");
 
 // src/db/extensions.ts
 var PALBASE_EXTENSIONS = [
   // Search & text
   "vector",
-  // pgvector: AI embeddings + vector similarity search (semantic search / RAG).
   // NB: the Postgres extension is named "vector", not "pgvector" — declare "vector".
   "pg_trgm",
-  // trigram fuzzy / typo-tolerant text search
   "unaccent",
-  // accent-insensitive text search
   "citext",
-  // case-insensitive text type
   // Geospatial / location
   "cube",
-  // multi-dimensional cubes (dependency of earthdistance)
   "earthdistance",
-  // great-circle distance (needs cube)
   // Data types & structures
   "hstore",
-  // key/value pairs in a single column
   "ltree",
-  // hierarchical tree-structured labels
   // Indexing & constraints
   "btree_gist",
-  // GiST operator classes for scalar types — needed for EXCLUDE
   // constraints that mix "=" with a range/&& overlap (e.g. no-double-booking).
   // Scheduling
   // Crypto / ids (also installed by default; listable for explicitness)
   "pgcrypto",
-  // cryptographic functions (hashing, encryption)
   "uuid-ossp"
-  // UUID generation functions
 ];
 var EXTENSION_DEPENDENCIES = {
-  earthdistance: ["cube"]
+  earthdistance: [
+    "cube"
+  ]
 };
 function isPalbaseExtension(name) {
   return PALBASE_EXTENSIONS.includes(name);
 }
+__name(isPalbaseExtension, "isPalbaseExtension");
 
 // src/db/columns.ts
 function refuseOnVector(def, modifier) {
@@ -378,7 +579,11 @@ function refuseOnVector(def, modifier) {
     throw new Error(`vector column: .${modifier}() is not supported (FR-002 \u2014 allowed: nullable()/notNull())`);
   }
 }
+__name(refuseOnVector, "refuseOnVector");
 var ColumnBuilder = class _ColumnBuilder {
+  static {
+    __name(this, "ColumnBuilder");
+  }
   _def;
   constructor(type, existingDef) {
     this._def = existingDef ?? {
@@ -422,52 +627,52 @@ var ColumnBuilder = class _ColumnBuilder {
     return new _ColumnBuilder(this._def.type, this._def);
   }
   /**
-   * The DATABASE assigns this column's value — a trigger, a rule, an identity.
-   *
-   * The column becomes optional on INSERT (the author has nothing to send) while
-   * the DDL stays free of a DEFAULT this schema would not honour. It is NOT
-   * `default()`: that declares a value the schema promises to write.
-   *
-   * Naming: deliberately not `generated()`. Postgres has GENERATED columns and
-   * they are a different thing; borrowing the word would send a reader — or a
-   * model writing a schema — to the wrong feature.
-   */
+  * The DATABASE assigns this column's value — a trigger, a rule, an identity.
+  *
+  * The column becomes optional on INSERT (the author has nothing to send) while
+  * the DDL stays free of a DEFAULT this schema would not honour. It is NOT
+  * `default()`: that declares a value the schema promises to write.
+  *
+  * Naming: deliberately not `generated()`. Postgres has GENERATED columns and
+  * they are a different thing; borrowing the word would send a reader — or a
+  * model writing a schema — to the wrong feature.
+  */
   dbAssigned() {
     this._def.dbAssigned = true;
     return new _ColumnBuilder(this._def.type, this._def);
   }
   /** Add a foreign key reference. */
   /**
-   * Declares that this column used to be called `previous`.
-   *
-   * A schema diff sees one name gone and another present; it cannot know whether
-   * you renamed a column or dropped one and added another, and the two are very
-   * different — the second loses every value. Saying so here turns the plan into
-   * `ALTER TABLE … RENAME COLUMN` instead.
-   *
-   * Once the rename has been applied the annotation is inert (the old name is no
-   * longer there to rename), so it can be deleted at your leisure.
-   */
+  * Declares that this column used to be called `previous`.
+  *
+  * A schema diff sees one name gone and another present; it cannot know whether
+  * you renamed a column or dropped one and added another, and the two are very
+  * different — the second loses every value. Saying so here turns the plan into
+  * `ALTER TABLE … RENAME COLUMN` instead.
+  *
+  * Once the rename has been applied the annotation is inert (the old name is no
+  * longer there to rename), so it can be deleted at your leisure.
+  */
   renamedFrom(previous) {
     this._def.renamedFrom = previous;
     return this;
   }
   /**
-   * See {@link ColumnDef.ignored}.
-   *
-   * COPIES the def rather than mutating it. The constructor takes an existing
-   * def BY REFERENCE, so every builder derived from another shares one object —
-   * `const a = slug.unique()` leaves `a._def === slug._def`. An in-place
-   * `ignored = true` therefore marks every column sharing that def, including
-   * one another table actively reads, and the gate would let THAT column be
-   * dropped. Measured before this copy existed.
-   *
-   * The aliasing is older than this method and other fields leak through it too.
-   * The reason this one cannot wait: every other leak produces a VISIBLE schema
-   * difference — the plan shows it, the DDL shows it. This one is invisible by
-   * design (no DDL, no diff, no plan line), so its only effect is to disarm a
-   * safety gate in silence.
-   */
+  * See {@link ColumnDef.ignored}.
+  *
+  * COPIES the def rather than mutating it. The constructor takes an existing
+  * def BY REFERENCE, so every builder derived from another shares one object —
+  * `const a = slug.unique()` leaves `a._def === slug._def`. An in-place
+  * `ignored = true` therefore marks every column sharing that def, including
+  * one another table actively reads, and the gate would let THAT column be
+  * dropped. Measured before this copy existed.
+  *
+  * The aliasing is older than this method and other fields leak through it too.
+  * The reason this one cannot wait: every other leak produces a VISIBLE schema
+  * difference — the plan shows it, the DDL shows it. This one is invisible by
+  * design (no DDL, no diff, no plan line), so its only effect is to disarm a
+  * safety gate in silence.
+  */
   ignored() {
     return new _ColumnBuilder(this._def.type, {
       ...this._def,
@@ -475,47 +680,67 @@ var ColumnBuilder = class _ColumnBuilder {
     });
   }
   /**
-   * Foreign key onto another table's column.
-   *
-   * The target is a THUNK, not a direct reference. In a cycle (`x → y`, `y → x`)
-   * the second table does not exist yet when the first is built; a direct
-   * reference makes TypeScript chase its own tail (TS7022 — measured, and making
-   * the return type independent of the target does NOT help). The thunk is
-   * invoked in `defineSchema`, where every binding exists and every table
-   * already knows its name.
-   *
-   * In a cycle, ONE side needs an explicit return type:
-   * `references((): AnyColumn => y.id)`. One side is enough — measured.
-   * For a self-reference use `selfReferences(column)`: no thunk, no annotation.
-   *
-   * `as` names the FORWARD relation (`author_id` → `author` by default);
-   * `reverseAs` names the REVERSE one on the parent, whose default is this
-   * table's own name (`users.posts`). Two foreign keys from one table onto one
-   * parent therefore need a `reverseAs` on at least one of them — the reverse
-   * names would otherwise both be this table's name.
-   */
+  * Foreign key onto another table's column.
+  *
+  * The target is a THUNK, not a direct reference. In a cycle (`x → y`, `y → x`)
+  * the second table does not exist yet when the first is built; a direct
+  * reference makes TypeScript chase its own tail (TS7022 — measured, and making
+  * the return type independent of the target does NOT help). The thunk is
+  * invoked in `defineSchema`, where every binding exists and every table
+  * already knows its name.
+  *
+  * In a cycle, ONE side needs an explicit return type:
+  * `references((): AnyColumn => y.id)`. One side is enough — measured.
+  * For a self-reference use `selfReferences(column)`: no thunk, no annotation.
+  *
+  * `as` names the FORWARD relation (`author_id` → `author` by default);
+  * `reverseAs` names the REVERSE one on the parent, whose default is this
+  * table's own name (`users.posts`). Two foreign keys from one table onto one
+  * parent therefore need a `reverseAs` on at least one of them — the reverse
+  * names would otherwise both be this table's name.
+  */
   references(target, opts) {
     refuseOnVector(this._def, "references");
     if (typeof target !== "function") {
-      throw new Error(
-        `references(...) takes a callback: write references(() => otherTable.column). The two-string form references("table", "column") is gone \u2014 a string cannot be type-checked and cannot point at a table that does not exist yet.`
-      );
+      throw new Error(`references(...) takes a callback: write references(() => otherTable.column). The two-string form references("table", "column") is gone \u2014 a string cannot be type-checked and cannot point at a table that does not exist yet.`);
     }
     this._def.referencesThunk = target;
     if (opts?.as !== void 0) this._def.refAs = opts.as;
     if (opts?.reverseAs !== void 0) this._def.reverseAs = opts.reverseAs;
     if (opts?.onDelete !== void 0) this._def.onDeleteAction = opts.onDelete;
+    if (opts?.index === false) this._def.index = false;
+    return new _ColumnBuilder(this._def.type, this._def);
+  }
+  /**
+  * Bu kolon `increment()` / `decrement()` ile güncelleniyor (FR-049).
+  *
+  * Deploy kontrolcü kodunu OKUMAZ, o yüzden bildirimin söylemesi gerekiyor —
+  * ve söylediği anda plan bir şeyi görebiliyor: aynı kolon hem sayaç hem
+  * indeksliyse her güncelleme HOT'u kaybeder.
+  *
+  * ZİNCİR (D-028+D-030): HOT kaybı → ölü tuple → autovacuum yükü → ve
+  * autovacuum worker'ları KÜME GENELİNDE bir kaynak, yani bedeli başka
+  * kiracıların tabloları da öder.
+  *
+  * Sektörde çare "dokümana uyarı yaz"dır, çünkü index'i ekleyen kişi
+  * `increment()`'i yazan kişi değildir. Bu bildirimde ikisi de YAN YANA
+  * duruyor.
+  *
+  * Uyarı, HATA DEĞİL: sayaç kolonunu indekslemek bazen doğru karardır.
+  */
+  counter() {
+    this._def.counter = true;
     return new _ColumnBuilder(this._def.type, this._def);
   }
   /**
-   * Foreign key onto THIS table (`parent_id → id`) — category trees, comment
-   * replies, org charts.
-   *
-   * No thunk and no type annotation: the target table is the one being declared,
-   * so there is nothing to defer and nothing for TypeScript to chase in a circle.
-   * Drizzle forces an explicit `(): AnyPgColumn =>` here because its reference
-   * always goes through a callback; measured, we do not need one.
-   */
+  * Foreign key onto THIS table (`parent_id → id`) — category trees, comment
+  * replies, org charts.
+  *
+  * No thunk and no type annotation: the target table is the one being declared,
+  * so there is nothing to defer and nothing for TypeScript to chase in a circle.
+  * Drizzle forces an explicit `(): AnyPgColumn =>` here because its reference
+  * always goes through a callback; measured, we do not need one.
+  */
   selfReferences(column, opts) {
     refuseOnVector(this._def, "selfReferences");
     this._def.selfRefColumn = column;
@@ -535,23 +760,23 @@ var ColumnBuilder = class _ColumnBuilder {
     return new _ColumnBuilder(this._def.type, this._def);
   }
   /**
-   * Declare how this column's value is projected in and out of the process.
-   *
-   * The DDL does not move: `numeric` stays `numeric`, and the driver still hands
-   * back what Postgres sent. What changes is the type the row surface exposes —
-   * it becomes `Target`:
-   *
-   *   amount: numeric().transform<number>({ fromDb: Number, toDb: String })
-   *
-   * `numeric` surfacing as `string` is CORRECT (a JS number cannot hold
-   * arbitrary precision), and that is exactly why this exists: application code
-   * that does arithmetic on the column otherwise rewrites the same
-   * `Number(row.amount)` / `String(x)` pair in every controller that touches it,
-   * and each rewrite is a place the two directions can drift apart.
-   *
-   * A transform is a PROJECTION, never a constraint: it lives only in this
-   * process, so it can neither validate nor migrate what is stored.
-   */
+  * Declare how this column's value is projected in and out of the process.
+  *
+  * The DDL does not move: `numeric` stays `numeric`, and the driver still hands
+  * back what Postgres sent. What changes is the type the row surface exposes —
+  * it becomes `Target`:
+  *
+  *   amount: numeric().transform<number>({ fromDb: Number, toDb: String })
+  *
+  * `numeric` surfacing as `string` is CORRECT (a JS number cannot hold
+  * arbitrary precision), and that is exactly why this exists: application code
+  * that does arithmetic on the column otherwise rewrites the same
+  * `Number(row.amount)` / `String(x)` pair in every controller that touches it,
+  * and each rewrite is a place the two directions can drift apart.
+  *
+  * A transform is a PROJECTION, never a constraint: it lives only in this
+  * process, so it can neither validate nor migrate what is stored.
+  */
   transform(fns) {
     this._def.transform = fns;
     return new _ColumnBuilder(this._def.type, this._def);
@@ -560,30 +785,40 @@ var ColumnBuilder = class _ColumnBuilder {
 function uuid() {
   return new ColumnBuilder("uuid");
 }
+__name(uuid, "uuid");
 function text() {
   return new ColumnBuilder("text");
 }
+__name(text, "text");
 function integer() {
   return new ColumnBuilder("integer");
 }
+__name(integer, "integer");
 function bigint() {
   return new ColumnBuilder("bigint");
 }
+__name(bigint, "bigint");
 function boolean() {
   return new ColumnBuilder("boolean");
 }
+__name(boolean, "boolean");
 function timestamp() {
   return new ColumnBuilder("timestamp");
 }
+__name(timestamp, "timestamp");
 function jsonb() {
   return new ColumnBuilder("jsonb");
 }
+__name(jsonb, "jsonb");
 function enumType(name, values) {
   const builder = new ColumnBuilder("enum");
   builder._def.enumName = name;
-  builder._def.enumValues = [...values];
+  builder._def.enumValues = [
+    ...values
+  ];
   return builder;
 }
+__name(enumType, "enumType");
 function vector(dimensions) {
   if (!Number.isInteger(dimensions) || dimensions < 1 || dimensions > 2e3) {
     throw new Error(`vector(): dimensions must be an integer in [1, 2000], got ${String(dimensions)}`);
@@ -592,33 +827,53 @@ function vector(dimensions) {
   b._def.dimensions = dimensions;
   return b;
 }
+__name(vector, "vector");
 function ownedByUser() {
   const b = new ColumnBuilder("text");
   b._def.nullable = false;
-  b._def.references = { table: "auth.users", column: "id" };
+  b._def.references = {
+    table: "auth.users",
+    column: "id"
+  };
   b._def.onDeleteAction = "cascade";
   b._def.owns = true;
   return b;
 }
+__name(ownedByUser, "ownedByUser");
 function userRef(opts) {
   const b = new ColumnBuilder("text");
-  b._def.references = { table: "auth.users", column: "id" };
+  b._def.references = {
+    table: "auth.users",
+    column: "id"
+  };
   b._def.onDeleteAction = opts.onDelete;
   if (opts.as !== void 0) b._def.refAs = opts.as;
   return b;
 }
+__name(userRef, "userRef");
 function installationRef(opts) {
   const b = new ColumnBuilder("text");
-  b._def.references = { table: "auth.installations", column: "id" };
+  b._def.references = {
+    table: "auth.installations",
+    column: "id"
+  };
   b._def.onDeleteAction = opts.onDelete;
   if (opts.as !== void 0) b._def.refAs = opts.as;
   return b;
 }
+__name(installationRef, "installationRef");
 
 // src/db/raw.ts
 function raw(name, up, opts) {
-  return { name, up, ...opts?.down != null ? { down: opts.down } : {} };
+  return {
+    name,
+    up,
+    ...opts?.down != null ? {
+      down: opts.down
+    } : {}
+  };
 }
+__name(raw, "raw");
 
 // src/db/embedding.ts
 var openai = {
@@ -627,23 +882,62 @@ var openai = {
       provider: "openai",
       model,
       apiKeyName: opts?.apiKeyName ?? "OPENAI_API_KEY",
-      ...opts?.dimensions !== void 0 ? { dimensions: opts.dimensions } : {},
-      ...opts?.baseURL !== void 0 ? { baseURL: opts.baseURL } : {}
+      ...opts?.dimensions !== void 0 ? {
+        dimensions: opts.dimensions
+      } : {},
+      ...opts?.baseURL !== void 0 ? {
+        baseURL: opts.baseURL
+      } : {}
     };
   },
   chat(model) {
-    return { provider: "openai", model };
+    return {
+      provider: "openai",
+      model
+    };
   }
 };
 
+// src/db/input-guards.ts
+var REF_BRAND = /* @__PURE__ */ Symbol.for("palbase.db.ref");
+function brandRef(v, kind) {
+  Object.defineProperty(v, REF_BRAND, {
+    value: kind,
+    enumerable: false
+  });
+  return v;
+}
+__name(brandRef, "brandRef");
+function brandOf(v) {
+  if (typeof v !== "object" || v === null) return void 0;
+  return Object.hasOwn(v, REF_BRAND) ? v[REF_BRAND] : void 0;
+}
+__name(brandOf, "brandOf");
+function isColRef(v) {
+  return brandOf(v) === "col" && typeof v.$col === "string";
+}
+__name(isColRef, "isColRef");
+function isSqlFragment(v) {
+  if (brandOf(v) !== "sql") return false;
+  const f = v.$sql;
+  return f !== void 0 && Array.isArray(f.text) && Array.isArray(f.values);
+}
+__name(isSqlFragment, "isSqlFragment");
+
 // src/db/tx-plan.ts
 var TxRefError = class extends Error {
+  static {
+    __name(this, "TxRefError");
+  }
   constructor(message) {
     super(message);
     this.name = "TxRefError";
   }
 };
 var TxPlanError = class extends Error {
+  static {
+    __name(this, "TxPlanError");
+  }
   constructor(message) {
     super(message);
     this.name = "TxPlanError";
@@ -662,126 +956,193 @@ var TRAPPED_PROPS = [
 ];
 function trap(prop, what, hint) {
   const name = typeof prop === "symbol" ? prop.description ?? String(prop) : prop;
-  throw new TxRefError(
-    `${what} was used as a value (via \`${name}\`). Nothing in a transaction callback has run yet, so there is no value to read. ${hint}`
-  );
+  throw new TxRefError(`${what} was used as a value (via \`${name}\`). Nothing in a transaction callback has run yet, so there is no value to read. ${hint}`);
 }
+__name(trap, "trap");
 function now() {
-  return makeExpr({ fn: "now" });
+  return makeExpr({
+    fn: "now"
+  });
 }
-function inc(by) {
-  assertFiniteNumber(by, "inc");
-  return makeExpr({ fn: "inc", by });
+__name(now, "now");
+function increment(by) {
+  assertAmount(by, "increment");
+  return makeExpr({
+    fn: "inc",
+    by
+  });
 }
-function dec(by) {
-  assertFiniteNumber(by, "dec");
-  return makeExpr({ fn: "dec", by });
+__name(increment, "increment");
+var inc = increment;
+function decrement(by) {
+  assertAmount(by, "decrement");
+  return makeExpr({
+    fn: "dec",
+    by
+  });
 }
-function assertFiniteNumber(by, fn) {
-  if (typeof by !== "number" || !Number.isFinite(by)) {
+__name(decrement, "decrement");
+var dec = decrement;
+function assertAmount(by, fn) {
+  if (typeof by === "string") {
+    if (!/^-?\d+(\.\d+)?$/.test(by)) {
+      throw new TxPlanError(`${fn}() ondal\u0131k bir say\u0131 metni bekliyor, "${by}" ald\u0131 \u2014 kabul edilen bi\xE7im: "12", "-12", "12.50"`);
+    }
+  } else if (typeof by !== "number" || !Number.isFinite(by)) {
     throw new TxPlanError(`${fn}() needs a finite number, got ${String(by)}`);
   }
+  const negative = typeof by === "string" ? by.trimStart().startsWith("-") : by < 0;
+  if (negative) {
+    const other = fn === "increment" ? "decrement" : "increment";
+    throw new TxPlanError(`${fn}() negatif miktar almaz ("${String(by)}"). Ters y\xF6n i\xE7in ${other}() kullan\u0131n \u2014 i\u015Faretin miktarda saklanmas\u0131, y\xF6n\xFC okuyan hi\xE7bir kod taraf\u0131ndan g\xF6r\xFClmezdi.`);
+  }
 }
+__name(assertAmount, "assertAmount");
 function makeExpr(expr) {
-  return new Proxy(
-    { [EXPR]: expr },
-    {
-      get(target, prop) {
-        if (prop === EXPR) return target[EXPR];
-        if (TRAPPED_PROPS.includes(prop)) {
-          trap(prop, "A plan expression", "Write it into an operation instead.");
-        }
-        return void 0;
+  return new Proxy({
+    [EXPR]: expr
+  }, {
+    get(target, prop) {
+      if (prop === EXPR) return target[EXPR];
+      if (TRAPPED_PROPS.includes(prop)) {
+        trap(prop, "A plan expression", "Write it into an operation instead.");
       }
+      return void 0;
     }
-  );
+  });
 }
+__name(makeExpr, "makeExpr");
 function makeRef(op, field) {
-  const target = { [REF]: { op, field } };
+  const target = {
+    [REF]: {
+      op,
+      field
+    }
+  };
   return new Proxy(target, {
     get(t, prop) {
       if (prop === REF) return t[REF];
       if (TRAPPED_PROPS.includes(prop)) {
-        trap(
-          prop,
-          `\`${field}\` of a row this transaction has not written yet`,
-          "Pass it to another operation in the same plan, or return it from the callback and read it after `transaction()` resolves."
-        );
+        trap(prop, `\`${field}\` of a row this transaction has not written yet`, "Pass it to another operation in the same plan, or return it from the callback and read it after `transaction()` resolves.");
       }
       return void 0;
     }
   });
 }
+__name(makeRef, "makeRef");
 function makeRowHandle(op) {
-  const target = { [ROW]: op };
+  const target = {
+    [ROW]: op
+  };
   return new Proxy(target, {
     get(t, prop) {
       if (prop === ROW) return t[ROW];
       if (TRAPPED_PROPS.includes(prop)) {
-        trap(
-          prop,
-          "A row this transaction has not written yet",
-          "Read one of its columns to reference it, or return the row from the callback and read it after `transaction()` resolves."
-        );
+        trap(prop, "A row this transaction has not written yet", "Read one of its columns to reference it, or return the row from the callback and read it after `transaction()` resolves.");
       }
       if (typeof prop === "symbol") return void 0;
       return makeRef(op, prop);
     }
   });
 }
+__name(makeRowHandle, "makeRowHandle");
 function refDescriptor(v) {
   if (typeof v !== "object" || v === null) return null;
   const d = v[REF];
   return isRefDescriptor(d) ? d : null;
 }
+__name(refDescriptor, "refDescriptor");
 function isRefDescriptor(d) {
   return typeof d === "object" && d !== null && typeof d.op === "number" && typeof d.field === "string";
 }
+__name(isRefDescriptor, "isRefDescriptor");
 function rowOpIndex(v) {
   if (typeof v !== "object" || v === null) return null;
   const op = v[ROW];
   return typeof op === "number" ? op : null;
 }
+__name(rowOpIndex, "rowOpIndex");
 function exprOf(v) {
   if (typeof v !== "object" || v === null) return null;
   const e = v[EXPR];
   return typeof e === "object" && e !== null ? e : null;
 }
+__name(exprOf, "exprOf");
 function isRowsHandle(v) {
   return typeof v === "object" && v !== null && v[ROWS] !== void 0;
 }
+__name(isRowsHandle, "isRowsHandle");
 function encodeValue(value, column, allowColumnExpr) {
   const ref = refDescriptor(value);
-  if (ref) return { $ref: { op: ref.op, field: ref.field } };
+  if (ref) return brandRef({
+    $ref: {
+      op: ref.op,
+      field: ref.field
+    }
+  }, "ref");
   const expr = exprOf(value);
   if (expr) {
     if (expr.fn !== "now" && !allowColumnExpr) {
-      throw new TxPlanError(
-        `\`${column}\`: ${expr.fn}() reads the column's current value, so it is only valid in updateWhere(where, set).`
-      );
+      throw new TxPlanError(`\`${column}\`: ${expr.fn}() reads the column's current value, so it is only valid in updateWhere(where, set).`);
     }
-    return { $expr: expr };
+    return {
+      $expr: expr
+    };
   }
   if (rowOpIndex(value) !== null) {
-    throw new TxPlanError(
-      `\`${column}\`: a row handle is not a value. Read the column you meant (e.g. \`row.id\`).`
-    );
+    throw new TxPlanError(`\`${column}\`: a row handle is not a value. Read the column you meant (e.g. \`row.id\`).`);
   }
   if (isRowsHandle(value)) {
-    throw new TxPlanError(
-      `\`${column}\`: an operation result is not a value. Declare an expectation first (\`.expectOne(err)\`) and read a column from the row.`
-    );
+    throw new TxPlanError(`\`${column}\`: an operation result is not a value. Declare an expectation first (\`.expectOne(err)\`) and read a column from the row.`);
   }
   assertNoNestedHandles(value, column);
   return value;
 }
+__name(encodeValue, "encodeValue");
+function encodeFilterValue(value, column) {
+  const ref = refDescriptor(value);
+  if (ref) return brandRef({
+    $ref: {
+      op: ref.op,
+      field: ref.field
+    }
+  }, "ref");
+  const expr = exprOf(value);
+  if (expr) {
+    throw new TxPlanError(`\`${column}\`: ${expr.fn}() bir YAZMA ifadesi, kar\u015F\u0131la\u015Ft\u0131rma de\u011Fil \u2014 filtrede kullan\u0131lamaz. Kolonu bir de\u011Ferle ya da col() ile kar\u015F\u0131la\u015Ft\u0131r\u0131n.`);
+  }
+  if (rowOpIndex(value) !== null) {
+    throw new TxPlanError(`\`${column}\`: a row handle is not a value. Read the column you meant (e.g. \`row.id\`).`);
+  }
+  if (isRowsHandle(value)) {
+    throw new TxPlanError(`\`${column}\`: an operation result is not a value. Declare an expectation first (\`.expectOne(err)\`) and read a column from the row.`);
+  }
+  if (Array.isArray(value)) return value.map((v) => encodeFilterValue(v, column));
+  if (value !== null && typeof value === "object" && !(value instanceof Date) && !isColRef(value) && !isSqlFragment(value)) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = encodeFilterValue(v, column);
+    }
+    return out;
+  }
+  return value;
+}
+__name(encodeFilterValue, "encodeFilterValue");
+function encodeFilterMap(map) {
+  const out = {};
+  for (const key of Object.keys(map).sort()) {
+    const value = map[key];
+    if (value === void 0) continue;
+    out[key] = encodeFilterValue(value, key);
+  }
+  return out;
+}
+__name(encodeFilterMap, "encodeFilterMap");
 function assertNoNestedHandles(value, column) {
   if (typeof value !== "object" || value === null) return;
   if (value instanceof Date) return;
   if (refDescriptor(value) || exprOf(value) || rowOpIndex(value) !== null || isRowsHandle(value)) {
-    throw new TxPlanError(
-      `\`${column}\`: a plan handle is nested inside a value. The server would store it as literal JSON, not resolve it. Put the reference directly in the column.`
-    );
+    throw new TxPlanError(`\`${column}\`: a plan handle is nested inside a value. The server would store it as literal JSON, not resolve it. Put the reference directly in the column.`);
   }
   if (Array.isArray(value)) {
     for (const item of value) assertNoNestedHandles(item, column);
@@ -791,6 +1152,7 @@ function assertNoNestedHandles(value, column) {
     assertNoNestedHandles(item, column);
   }
 }
+__name(assertNoNestedHandles, "assertNoNestedHandles");
 function encodeMap(map, allowColumnExpr) {
   const out = {};
   for (const key of Object.keys(map).sort()) {
@@ -800,12 +1162,11 @@ function encodeMap(map, allowColumnExpr) {
   }
   return out;
 }
+__name(encodeMap, "encodeMap");
 var SKIPPED_OP = -1;
-var TxRowsImpl = class {
-  constructor(builder, opIndex, what) {
-    this.builder = builder;
-    this.opIndex = opIndex;
-    this.what = what;
+var TxRowsImpl = class TxRowsImpl2 {
+  static {
+    __name(this, "TxRowsImpl");
   }
   builder;
   opIndex;
@@ -813,12 +1174,15 @@ var TxRowsImpl = class {
   // Present so `isRowsHandle` recognises the object; never read for its value.
   [ROWS] = true;
   guarded = false;
+  constructor(builder, opIndex, what) {
+    this.builder = builder;
+    this.opIndex = opIndex;
+    this.what = what;
+  }
   // The type-level `await` guard made real: TS rejects `await rows` at compile
   // time, and reaching this means someone called `.then(...)` by hand.
   then() {
-    throw new TxRefError(
-      `${this.what} cannot be awaited: a transaction callback builds a plan, it does not run statements. Remove the \`await\`.`
-    );
+    throw new TxRefError(`${this.what} cannot be awaited: a transaction callback builds a plan, it does not run statements. Remove the \`await\`.`);
   }
   expectOne(error) {
     this.declareGuard("one", 1, error);
@@ -839,14 +1203,10 @@ var TxRowsImpl = class {
   }
   declareGuard(kind, n, error) {
     if (!(error instanceof Error)) {
-      throw new TxPlanError(
-        `${this.what}: an expectation needs the Error to throw when it does not hold (e.g. \`.expect\u2026(new Conflict("already accepted"))\`).`
-      );
+      throw new TxPlanError(`${this.what}: an expectation needs the Error to throw when it does not hold (e.g. \`.expect\u2026(new Conflict("already accepted"))\`).`);
     }
     if (this.guarded) {
-      throw new TxPlanError(
-        `${this.what} already has an expectation. One operation carries one expectation; declare the second one on its own operation.`
-      );
+      throw new TxPlanError(`${this.what} already has an expectation. One operation carries one expectation; declare the second one on its own operation.`);
     }
     this.guarded = true;
     if (this.opIndex === SKIPPED_OP) return;
@@ -858,115 +1218,119 @@ function assertGuardCount(n, fn) {
     throw new TxPlanError(`${fn}(n) needs a non-negative integer, got ${String(n)}`);
   }
 }
+__name(assertGuardCount, "assertGuardCount");
 var MAX_OPS = 1e3;
 var MAX_ROWS = 5e3;
 var TxPlanBuilder = class {
+  static {
+    __name(this, "TxPlanBuilder");
+  }
   ops = [];
   /** Errors handed to expectations, indexed by the `slot` the server echoes. */
   slots = [];
   /** The table surface handed to the callback. Untyped here; the public
-   * `transaction()` signatures put the schema types on top. */
+  * `transaction()` signatures put the schema types on top. */
   table(name) {
     return {
-      insert: (values) => {
+      insert: /* @__PURE__ */ __name((values) => {
         const encoded = encodeMap(values, false);
         if (Object.keys(encoded).length === 0) {
           throw new TxPlanError(`${name}.insert() needs at least one column`);
         }
-        return this.push({ op: "insert", table: name, values: encoded }, `${name}.insert()`);
-      },
-      upsert: (values, options) => {
+        return this.push({
+          op: "insert",
+          table: name,
+          values: encoded
+        }, `${name}.insert()`);
+      }, "insert"),
+      put: /* @__PURE__ */ __name((values, options) => {
         const encoded = encodeMap(values, false);
         if (Object.keys(encoded).length === 0) {
-          throw new TxPlanError(`${name}.upsert() needs at least one column`);
+          throw new TxPlanError(`${name}.put() needs at least one column`);
         }
         if (options.onConflict.length === 0) {
-          throw new TxPlanError(`${name}.upsert() needs at least one onConflict column`);
+          throw new TxPlanError(`${name}.put() needs at least one onConflict column`);
         }
-        return this.push(
-          { op: "upsert", table: name, values: encoded, onConflict: options.onConflict },
-          `${name}.upsert()`
-        );
-      },
-      insertMany: (rows, opts) => {
+        return this.push({
+          op: "upsert",
+          table: name,
+          values: encoded,
+          onConflict: options.onConflict
+        }, `${name}.upsert()`);
+      }, "put"),
+      insertMany: /* @__PURE__ */ __name((rows, opts) => {
         if (rows.length === 0) {
           return new TxRowsImpl(this, SKIPPED_OP, `${name}.insertMany()`);
         }
         if (rows.length > MAX_ROWS) {
-          throw new TxPlanError(
-            `${name}.insertMany() has ${rows.length} rows; the limit is ${MAX_ROWS}. Split the write across requests.`
-          );
+          throw new TxPlanError(`${name}.insertMany() has ${rows.length} rows; the limit is ${MAX_ROWS}. Split the write across requests.`);
         }
         const encoded = rows.map((row) => encodeMap(row, false));
         assertUniformRows(encoded, name);
         if (opts !== void 0 && opts.onConflict.length === 0) {
-          throw new TxPlanError(
-            `${name}.insertMany() was given a conflict action with no onConflict columns. Postgres matches a collision on columns, so name them.`
-          );
+          throw new TxPlanError(`${name}.insertMany() was given a conflict action with no onConflict columns. Postgres matches a collision on columns, so name them.`);
         }
-        return this.push(
-          {
-            op: "insertMany",
-            table: name,
-            rows: encoded,
-            // Omitted entirely when no options were given, so the op a plain
-            // insertMany produces is byte-identical to the one it produced
-            // before this option existed.
-            ...opts !== void 0 ? { onConflict: opts.onConflict, action: opts.action ?? "ignore" } : {}
-          },
-          `${name}.insertMany()`
-        );
-      },
-      updateWhere: (where, set) => {
-        const encodedWhere = encodeMap(where, false);
+        return this.push({
+          op: "insertMany",
+          table: name,
+          rows: encoded,
+          // Omitted entirely when no options were given, so the op a plain
+          // insertMany produces is byte-identical to the one it produced
+          // before this option existed.
+          ...opts !== void 0 ? {
+            onConflict: opts.onConflict,
+            action: opts.action ?? "ignore"
+          } : {}
+        }, `${name}.insertMany()`);
+      }, "insertMany"),
+      updateWhere: /* @__PURE__ */ __name((where, set) => {
+        const encodedWhere = encodeFilterMap(where);
         const encodedSet = encodeMap(set, true);
         if (Object.keys(encodedWhere).length === 0) {
-          throw new TxPlanError(
-            `${name}.updateWhere() needs a filter. An update with no filter rewrites the whole table.`
-          );
+          throw new TxPlanError(`${name}.updateWhere() needs a filter. An update with no filter rewrites the whole table.`);
         }
         if (Object.keys(encodedSet).length === 0) {
           throw new TxPlanError(`${name}.updateWhere() needs at least one column to set`);
         }
-        return this.push(
-          { op: "update", table: name, set: encodedSet, where: encodedWhere },
-          `${name}.updateWhere()`
-        );
-      },
-      deleteWhere: (where) => {
-        const encodedWhere = encodeMap(where, false);
+        return this.push({
+          op: "update",
+          table: name,
+          set: encodedSet,
+          where: encodedWhere
+        }, `${name}.updateWhere()`);
+      }, "updateWhere"),
+      deleteWhere: /* @__PURE__ */ __name((where) => {
+        const encodedWhere = encodeFilterMap(where);
         if (Object.keys(encodedWhere).length === 0) {
-          throw new TxPlanError(
-            `${name}.deleteWhere() needs a filter. A delete with no filter empties the table.`
-          );
+          throw new TxPlanError(`${name}.deleteWhere() needs a filter. A delete with no filter empties the table.`);
         }
-        return this.push(
-          { op: "delete", table: name, where: encodedWhere },
-          `${name}.deleteWhere()`
-        );
-      },
-      select: (where, options) => {
-        const op = { op: "select", table: name };
-        const encodedWhere = encodeMap(where ?? {}, false);
+        return this.push({
+          op: "delete",
+          table: name,
+          where: encodedWhere
+        }, `${name}.deleteWhere()`);
+      }, "deleteWhere"),
+      select: /* @__PURE__ */ __name((where, options) => {
+        const op = {
+          op: "select",
+          table: name
+        };
+        const encodedWhere = encodeFilterMap(where ?? {});
         if (Object.keys(encodedWhere).length > 0) op.where = encodedWhere;
         if (options?.limit !== void 0) {
           if (!Number.isInteger(options.limit) || options.limit < 0) {
-            throw new TxPlanError(
-              `${name}.select(): limit needs a non-negative integer, got ${String(options.limit)}`
-            );
+            throw new TxPlanError(`${name}.select(): limit needs a non-negative integer, got ${String(options.limit)}`);
           }
           op.limit = options.limit;
         }
         if (options?.lock !== void 0) op.lock = options.lock;
         return this.push(op, `${name}.select()`);
-      }
+      }, "select")
     };
   }
   push(op, what) {
     if (this.ops.length >= MAX_OPS) {
-      throw new TxPlanError(
-        `this transaction has ${MAX_OPS} operations, which is the limit. Use insertMany() for bulk writes, or split the work across requests.`
-      );
+      throw new TxPlanError(`this transaction has ${MAX_OPS} operations, which is the limit. Use insertMany() for bulk writes, or split the work across requests.`);
     }
     const index = this.ops.length;
     this.ops.push(op);
@@ -978,14 +1342,20 @@ var TxPlanBuilder = class {
     if (!op) throw new TxPlanError(`internal: expectation on unknown operation ${opIndex}`);
     const slot = this.slots.length;
     this.slots.push(error);
-    op.guard = { kind, n, slot };
+    op.guard = {
+      kind,
+      n,
+      slot
+    };
   }
   /** The serialisable plan. Empty when the callback described no writes. */
   body() {
-    return { ops: this.ops };
+    return {
+      ops: this.ops
+    };
   }
   /** The error the server's `slot` selects, or `null` when it names one this
-   * plan never declared (a server/client disagreement, not a tenant error). */
+  * plan never declared (a server/client disagreement, not a tenant error). */
   errorForSlot(slot) {
     return this.slots[slot] ?? null;
   }
@@ -998,29 +1368,24 @@ function assertUniformRows(rows, table) {
   for (let i = 1; i < rows.length; i++) {
     const got = Object.keys(rows[i]);
     if (got.join(",") !== wantKey) {
-      throw new TxPlanError(
-        `${table}.insertMany(): every row must set the same columns. Row 0 sets [${want.join(", ")}] but row ${i} sets [${got.join(", ")}]. (A property set to \`undefined\` counts as absent \u2014 use \`null\`.)`
-      );
+      throw new TxPlanError(`${table}.insertMany(): every row must set the same columns. Row 0 sets [${want.join(", ")}] but row ${i} sets [${got.join(", ")}]. (A property set to \`undefined\` counts as absent \u2014 use \`null\`.)`);
     }
   }
 }
+__name(assertUniformRows, "assertUniformRows");
 function materializeResult(value, results) {
   const ref = refDescriptor(value);
   if (ref) {
     const row = rowOf(results, ref.op, `\`${ref.field}\``);
     if (!(ref.field in row)) {
-      throw new TxPlanError(
-        `the transaction's operation ${ref.op} returned no column \`${ref.field}\`.`
-      );
+      throw new TxPlanError(`the transaction's operation ${ref.op} returned no column \`${ref.field}\`.`);
     }
     return row[ref.field];
   }
   const rowOp = rowOpIndex(value);
   if (rowOp !== null) return rowOf(results, rowOp, "a row");
   if (isRowsHandle(value)) {
-    throw new TxPlanError(
-      "an operation result cannot be returned from a transaction callback: its row count is not known until the plan runs. Declare an expectation (`.expectOne(err)`) and return the row, or a column of it."
-    );
+    throw new TxPlanError("an operation result cannot be returned from a transaction callback: its row count is not known until the plan runs. Declare an expectation (`.expectOne(err)`) and return the row, or a column of it.");
   }
   if (Array.isArray(value)) return value.map((item) => materializeResult(item, results));
   if (isPlainObject(value)) {
@@ -1030,28 +1395,27 @@ function materializeResult(value, results) {
   }
   return value;
 }
+__name(materializeResult, "materializeResult");
 function rowOf(results, opIndex, what) {
   const result = results[opIndex];
   if (!result) {
-    throw new TxPlanError(
-      `the transaction returned no result for operation ${opIndex}, so ${what} cannot be read.`
-    );
+    throw new TxPlanError(`the transaction returned no result for operation ${opIndex}, so ${what} cannot be read.`);
   }
   const row = result.rows[0];
   if (!row) {
-    throw new TxPlanError(
-      `the transaction's operation ${opIndex} returned no row, so ${what} cannot be read.`
-    );
+    throw new TxPlanError(`the transaction's operation ${opIndex} returned no row, so ${what} cannot be read.`);
   }
   return row;
 }
+__name(rowOf, "rowOf");
 function isPlainObject(value) {
   if (typeof value !== "object" || value === null) return false;
   const proto = Object.getPrototypeOf(value);
   return proto === Object.prototype || proto === null;
 }
-async function runTxPlan(transport, tables, builder, fn) {
-  const returned = fn({ tables });
+__name(isPlainObject, "isPlainObject");
+async function runTxPlan(transport, handle, builder, fn) {
+  const returned = fn(handle);
   const body = builder.body();
   if (body.ops.length === 0) {
     return materializeResult(returned, []);
@@ -1064,6 +1428,7 @@ async function runTxPlan(transport, tables, builder, fn) {
   }
   return materializeResult(returned, response.results);
 }
+__name(runTxPlan, "runTxPlan");
 function translateRejection(err, builder) {
   if (typeof err !== "object" || err === null) return err;
   const rejection = err;
@@ -1072,25 +1437,72 @@ function translateRejection(err, builder) {
   }
   return builder.errorForSlot(rejection.slot) ?? err;
 }
+__name(translateRejection, "translateRejection");
+
+// src/errors.ts
+var HTTP_ERROR_BRAND = /* @__PURE__ */ Symbol.for("palbase.backend.httpError");
+var HttpError = class extends Error {
+  static {
+    __name(this, "HttpError");
+  }
+  status;
+  error;
+  errorDescription;
+  data;
+  /** See {@link HTTP_ERROR_BRAND} — how the engine recognises this across SDK copies. */
+  [HTTP_ERROR_BRAND] = true;
+  constructor(status, error, errorDescription, data) {
+    super(errorDescription);
+    this.name = "HttpError";
+    this.status = status;
+    this.error = error;
+    this.errorDescription = errorDescription;
+    if (data !== void 0) {
+      this.data = data;
+    }
+  }
+  /**
+  * Serialize to the standard Palbase error response format.
+  * The `requestId` is injected by the runtime layer from the request context.
+  * When called without arguments (e.g. JSON.stringify), request_id is omitted.
+  * When `data` is set, it is appended as a strict-superset field.
+  */
+  toJSON(requestId) {
+    const result = {
+      error: this.error,
+      error_description: this.errorDescription,
+      status: this.status
+    };
+    if (requestId) {
+      result.request_id = requestId;
+    }
+    if (this.data !== void 0) {
+      result.data = this.data;
+    }
+    return result;
+  }
+};
 
 // src/db/typed-db.ts
 function makeTypedTable(name, raw2) {
   return {
-    insert: (data) => raw2.insert(name, data),
-    upsert: (data, opts) => raw2.upsert(name, data, opts),
-    update: (id, data) => raw2.update(name, id, data),
-    delete: (id) => raw2.delete(name, id),
-    findById: (id) => raw2.findById(name, id),
-    findMany: (query, opts) => raw2.findMany(name, query, opts),
-    updateMany: (where, set) => raw2.updateMany(
-      name,
-      where,
-      set
-    ),
-    deleteMany: (where) => raw2.deleteMany(name, where),
-    count: (where) => raw2.count(name, where)
+    insert: /* @__PURE__ */ __name((data) => raw2.insert(name, data), "insert"),
+    put: /* @__PURE__ */ __name((q) => raw2.put(name, q.data, {
+      onConflict: q.onConflict
+    }), "put"),
+    update: /* @__PURE__ */ __name((q) => raw2.update(name, q.where.id, q.set), "update"),
+    delete: /* @__PURE__ */ __name((id) => raw2.delete(name, id), "delete"),
+    findById: /* @__PURE__ */ __name((id) => raw2.findById(name, id), "findById"),
+    findMany: /* @__PURE__ */ __name((q) => {
+      const { where, ...opts } = q ?? {};
+      return raw2.findMany(name, where, opts);
+    }, "findMany"),
+    updateMany: /* @__PURE__ */ __name((q) => raw2.updateMany(name, q.where, q.set), "updateMany"),
+    deleteMany: /* @__PURE__ */ __name((q) => raw2.deleteMany(name, q.where), "deleteMany"),
+    count: /* @__PURE__ */ __name((q) => raw2.count(name, q?.where), "count")
   };
 }
+__name(makeTypedTable, "makeTypedTable");
 function makeTypedDB(schema, raw2) {
   const tables = {};
   for (const key of Object.keys(schema.tables)) {
@@ -1108,16 +1520,14 @@ function makeTypedDB(schema, raw2) {
         const tableDef = schema.tables[key];
         if (tableDef !== void 0) planTables[key] = builder.table(tableDef.name);
       }
-      return runTxPlan(
-        raw2,
-        planTables,
-        builder,
-        fn
-      );
+      return runTxPlan(raw2, {
+        tables: planTables
+      }, builder, fn);
     }
   };
   return result;
 }
+__name(makeTypedDB, "makeTypedDB");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   EXTENSION_DEPENDENCIES,