rip-lang 3.16.0 → 3.16.2

package/src/schema/runtime-orm.js

@@ -13,20 +13,91 @@
 // pinned by the test suite.
 
 /* eslint-disable no-undef, no-unused-vars */
-function __schemaDefaultAdapter() {
-  const url = (typeof process !== 'undefined' && process.env?.DB_URL) || 'http://localhost:9494';
+// ---- Adapter (Contract v2) -------------------------------------------------
+//
+// `query(sql, params) → {columns, data, rowCount}` is the only REQUIRED
+// method. v2 adds optional capabilities that the runtime feature-detects:
+//
+//   begin(options?) → TxHandle        transactions (schema.transaction!)
+//     TxHandle: { query(sql, params), commit(), rollback() }
+//   capabilities: { tx: true, ... }   truthful self-report (informational)
+//
+// Calling a feature whose method is absent throws a clear error — never
+// a silent fallback.
+//
+// The default adapter talks to a duckdb-harbor server (or any
+// /sql-compatible server). Configuration via env:
+//
+//   RIP_DB_URL    base URL (default http://127.0.0.1:9494; legacy DB_URL
+//                 honored as a fallback)
+//   RIP_DB_TOKEN  bearer token, required when harbor runs authenticated
+//
+// Transactions use harbor's session protocol: POST /sql/sessions/new
+// pins a DB session (connection) so BEGIN/COMMIT survive across
+// requests; statements carry the sessionId; the session is destroyed
+// after COMMIT/ROLLBACK. Harbor enforces an idle TTL, so an abandoned
+// transaction auto-rolls-back server-side.
+function __schemaDefaultAdapter(overrides) {
+  const env = (typeof process !== 'undefined' && process.env) || {};
+  const base = () => String(
+    overrides?.url || env.RIP_DB_URL || env.DB_URL || 'http://127.0.0.1:9494').replace(/\/+$/, '');
+  const headers = () => {
+    const h = { 'Content-Type': 'application/json', 'Accept': 'application/json' };
+    const token = overrides?.token || env.RIP_DB_TOKEN;
+    if (token) h['Authorization'] = 'Bearer ' + token;
+    return h;
+  };
+  async function post(path, body) {
+    const res = await fetch(base() + path, {
+      method: 'POST', headers: headers(), body: JSON.stringify(body),
+    });
+    let data;
+    try { data = await res.json(); } catch { data = {}; }
+    if (!res.ok || data.ok === false || data.error) {
+      const err = new Error(data.error || ('db request failed: ' + res.status + ' ' + (res.statusText || '')));
+      if (data.errorCode) err.code = data.errorCode;
+      if (data.errorDetails) err.details = data.errorDetails;
+      err.httpStatus = res.status;
+      throw err;
+    }
+    return data;
+  }
   return {
     async query(sql, params) {
-      const body = params && params.length ? { sql, params } : { sql };
-      const res = await fetch(url + '/sql', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(body),
-      });
-      const data = await res.json();
-      if (data.error) throw new Error(data.error);
-      return data;
-    }
+      return post('/sql', params && params.length ? { sql, params } : { sql });
+    },
+    async begin(options) {
+      let session;
+      try {
+        session = await post('/sql/sessions/new', {});
+      } catch (e) {
+        if (e && e.httpStatus === 403) {
+          e.message = 'transactions need a harbor DB session, and harbor denied session creation ' +
+            '(authz policy __HARBOR_ADMIN__:sessions:create). Allow it in your harbor_authorization_function ' +
+            'or set harbor_allow_admin_without_authz = true on a trusted deployment. Original error: ' + e.message;
+        }
+        throw e;
+      }
+      const sessionId = session.sessionId;
+      const run = (sql, params) =>
+        post('/sql', params && params.length ? { sql, params, sessionId } : { sql, sessionId });
+      const drop = async () => {
+        // Best-effort: harbor's idle TTL reaps abandoned sessions, so a
+        // failed DELETE only delays cleanup, never leaks a transaction.
+        try {
+          await fetch(base() + '/sql/sessions/' + sessionId, { method: 'DELETE', headers: headers() });
+        } catch {}
+      };
+      await run('BEGIN');
+      return {
+        query: run,
+        async commit() { await run('COMMIT'); await drop(); },
+        async rollback() {
+          try { await run('ROLLBACK'); } finally { await drop(); }
+        },
+      };
+    },
+    capabilities: { tx: true },
   };
 }
 
@@ -34,6 +105,205 @@ let __schemaAdapter = __schemaDefaultAdapter();
 
 function __schemaSetAdapter(a) { __schemaAdapter = a; }
 
+// Resolve the adapter for a def: its own `on:` adapter, else the
+// process-global one. Migration internals pass def = null → global.
+function __schemaAdapterFor(def) {
+  return (def && def._adapter) || __schemaAdapter;
+}
+
+// Build a NEW adapter value (without installing it globally) — the
+// counterpart of `schema :model, on: analytics`:
+//
+//   analytics = schema.connect url: env.ANALYTICS_URL, token: env.ANALYTICS_TOKEN
+//   Event = schema :model, on: analytics
+//
+// Same duckdb-harbor contract as the default adapter (query + begin +
+// capabilities), pinned to an explicit URL/token instead of env vars.
+function __schemaConnect(opts) {
+  const o = typeof opts === 'string' ? { url: opts } : (opts || {});
+  if (!o.url) throw new Error("schema.connect({url, token?}): a url is required");
+  return __schemaDefaultAdapter({ url: o.url, token: o.token });
+}
+
+// ---- Transactions ----------------------------------------------------------
+//
+// schema.transaction! ->                  propagates ambiently: every ORM
+//   user = User.create! ...               call inside the block routes
+//   Order.create! userId: user.id, ...    through the transaction's handle
+//   user                                  via AsyncLocalStorage. Model code
+//                                         is unchanged inside the block.
+//
+// Block throws   → ROLLBACK, exception propagates, afterRollback hooks fire.
+// Block returns  → COMMIT, value returned, afterCommit hooks fire.
+// Nested call    → joins the ambient transaction (Active Record's default;
+//                  DuckDB has no SAVEPOINT, so nested-as-independent-unit
+//                  cannot be honored on the primary backend).
+//
+// The ALS instance is created lazily on first use — `node:async_hooks`
+// exists in Bun and Node, and the import never runs in browser bundles
+// (this fragment is server/migration-only).
+let __schemaTxALS = null;
+
+// The ALS store is a Map<adapter, txContext> — each adapter gets its
+// own slot, so a transaction pinned to one adapter never captures ORM
+// calls bound to another (cross-adapter atomicity is impossible and
+// the runtime never pretends otherwise), and an inner transaction on a
+// second adapter doesn't shadow the outer one.
+function __schemaTxStore(adapter) {
+  if (!__schemaTxALS) return null;
+  const map = __schemaTxALS.getStore();
+  return (map && map.get(adapter)) || null;
+}
+
+// The single SQL funnel. Every ORM-issued statement flows through here:
+// it resolves the def's adapter, routes to that adapter's ambient
+// transaction handle when one exists, and translates DB constraint
+// violations into structured SchemaErrors.
+async function __schemaRunSQL(def, sql, params) {
+  const adapter = __schemaAdapterFor(def);
+  const tx = __schemaTxStore(adapter);
+  try {
+    return await (tx ? tx.handle.query(sql, params) : adapter.query(sql, params));
+  } catch (e) {
+    throw __schemaTranslateDBError(e, def);
+  }
+}
+
+async function __schemaTransaction(optsOrFn, maybeFn) {
+  const fn = typeof optsOrFn === 'function' ? optsOrFn : maybeFn;
+  const opts = typeof optsOrFn === 'function' ? {} : (optsOrFn || {});
+  if (typeof fn !== 'function') {
+    throw new Error('schema.transaction(fn): expected a function (got ' + typeof fn + ')');
+  }
+  // `on:` pins the transaction to a specific adapter (per-schema
+  // adapters); default is the process-global one.
+  const adapter = opts.on || __schemaAdapter;
+
+  // Nested transaction on the SAME adapter joins the ambient one — the
+  // inner block's writes commit or roll back with the outer transaction.
+  // A nested transaction on a DIFFERENT adapter is independent.
+  if (__schemaTxStore(adapter)) return fn();
+
+  if (typeof adapter.begin !== 'function') {
+    throw new Error(
+      'schema.transaction(): the configured adapter does not support transactions ' +
+      '(no begin() method; see Adapter Contract v2). Install an adapter with begin() ' +
+      'or use the default @rip-lang/db adapter against duckdb-harbor.');
+  }
+  if (!__schemaTxALS) {
+    const { AsyncLocalStorage } = await import('node:async_hooks');
+    __schemaTxALS = new AsyncLocalStorage();
+  }
+
+  const handle = await adapter.begin(opts);
+  // `after` collects {def, inst} for every save/destroy that completed
+  // inside the transaction on a model declaring afterCommit/afterRollback.
+  const store = { adapter, handle, after: [] };
+  // Copy-on-run: other adapters' ambient contexts stay visible inside
+  // the block; only this adapter's slot is (re)bound.
+  const nextMap = new Map(__schemaTxALS.getStore() || []);
+  nextMap.set(adapter, store);
+  let result;
+  try {
+    result = await __schemaTxALS.run(nextMap, fn);
+  } catch (err) {
+    try { await handle.rollback(); } catch {}
+    await __schemaFlushTxHooks(store, 'afterRollback');
+    throw err;
+  }
+  await handle.commit();
+  // afterCommit runs OUTSIDE the transaction — this is where emails,
+  // webhooks, and cache invalidation belong (they must never observe
+  // uncommitted state). Exceptions here propagate to the caller but
+  // cannot roll anything back: the COMMIT already happened.
+  await __schemaFlushTxHooks(store, 'afterCommit');
+  return result;
+}
+
+async function __schemaFlushTxHooks(store, hookName) {
+  // Dedupe by instance: a row saved twice in one transaction gets one
+  // callback, matching Active Record's after_commit semantics.
+  const seen = new Set();
+  for (const entry of store.after) {
+    if (seen.has(entry.inst)) continue;
+    seen.add(entry.inst);
+    await __schemaRunHook(entry.def, entry.inst, hookName);
+  }
+}
+
+// Queue an instance's commit-time hooks on the ambient transaction for
+// ITS adapter. Returns true when queued; false means "no ambient tx —
+// fire now".
+function __schemaEnqueueTxHook(def, inst) {
+  const tx = __schemaTxStore(__schemaAdapterFor(def));
+  if (!tx) return false;
+  tx.after.push({ def, inst });
+  return true;
+}
+
+// ---- Constraint-violation translation --------------------------------------
+//
+// The ORM wraps every adapter call (via __schemaRunSQL). Errors that are
+// recognizably DB constraint violations are translated into SchemaError
+// so a `save!` that trips a UNIQUE index fails the same way a `save!`
+// that trips a validator does: structured {field, error, message} issues.
+// Unrecognized errors propagate untouched. The original error is kept
+// as `.cause` for debugging.
+//
+// Recognition is message-pattern based (DuckDB first). Deliberately NOT
+// added: `validates_uniqueness_of`-style pre-checks — they race. The DB
+// constraint is the check; translation makes it ergonomic.
+function __schemaTranslateDBError(e, def) {
+  const msg = (e && e.message) || '';
+  const issue = __schemaConstraintIssue(msg);
+  if (!issue) return e;
+  const err = new SchemaError([issue], def ? def.name : null, def ? def.kind : null);
+  err.cause = e;
+  return err;
+}
+
+function __schemaConstraintIssue(msg) {
+  let m;
+  // DuckDB: Constraint Error: Duplicate key "email: a@b.c" violates unique constraint ...
+  //         (also "violates primary key constraint")
+  m = msg.match(/[Dd]uplicate key "([A-Za-z0-9_]+):[^"]*" violates (?:unique|primary key) constraint/);
+  if (m || /violates unique constraint/i.test(msg)) {
+    const field = m ? __schemaCamel(m[1]) : '';
+    return { field, error: 'unique', message: (field || 'value') + ' already taken' };
+  }
+  // DuckDB: Constraint Error: NOT NULL constraint failed: users.name
+  m = msg.match(/NOT NULL constraint failed:\s*(?:[A-Za-z0-9_]+\.)?([A-Za-z0-9_]+)/i);
+  if (m) {
+    const field = __schemaCamel(m[1]);
+    return { field, error: 'required', message: field + ' is required' };
+  }
+  // DuckDB: Constraint Error: Violates foreign key constraint because ... "user_id: 99" ...
+  if (/[Vv]iolates foreign key constraint/.test(msg)) {
+    m = msg.match(/"([A-Za-z0-9_]+):[^"]*"/);
+    const field = m ? __schemaCamel(m[1]) : '';
+    return { field, error: 'reference', message: (field || 'reference') + ' refers to a missing or still-referenced record' };
+  }
+  // DuckDB: Constraint Error: CHECK constraint failed: <table>
+  if (/CHECK constraint failed/i.test(msg)) {
+    return { field: '', error: 'check', message: msg };
+  }
+  return null;
+}
+
+// ---- Query builder ----------------------------------------------------------
+
+// Run a scope body with `this` bound to a query builder. `builder` is
+// null when invoked from a model static (User.active()) — a fresh
+// builder is created; chained scope calls pass the existing builder.
+// Scopes conventionally return the builder (`@where` does), but a body
+// that returns something else falls back to the builder so chains never
+// break on a stray trailing expression.
+function __schemaInvokeScope(def, builder, fn, args) {
+  const q = builder || new __SchemaQuery(def);
+  const out = fn.apply(q, args);
+  return out instanceof __SchemaQuery ? out : q;
+}
+
 class __SchemaQuery {
   constructor(def, opts = {}) {
     this._def = def;
@@ -42,7 +312,26 @@ class __SchemaQuery {
     this._limit = null;
     this._offset = null;
     this._order = null;
-    this._includeDeleted = opts.includeDeleted === true;
+    this._includes = [];
+    this._unscoped = false;
+    this._defaultScopeApplied = false;
+    // Soft-delete filter mode: 'live' (default), 'all' (.withDeleted),
+    // 'deleted' (.onlyDeleted). Pre-v2 `includeDeleted` option maps to 'all'.
+    this._deleted = opts.includeDeleted === true ? 'all' : 'live';
+    // Per-model scopes install as own methods so chains compose in any
+    // order: User.where(role: 'admin').active().since(d). Builder
+    // method names win on collision (normalize rejects those anyway).
+    const scopes = def._normalize().scopes;
+    if (scopes && scopes.size) {
+      for (const [sname, sfn] of scopes) {
+        if (!(sname in this)) {
+          Object.defineProperty(this, sname, {
+            enumerable: false, configurable: true,
+            value: (...args) => __schemaInvokeScope(def, this, sfn, args),
+          });
+        }
+      }
+    }
   }
   where(cond, ...params) {
     if (typeof cond === 'string') {
@@ -53,6 +342,9 @@ class __SchemaQuery {
         const col = __schemaSnake(k);
         if (v === null || v === undefined) {
           this._clauses.push('"' + col + '" IS NULL');
+        } else if (Array.isArray(v)) {
+          this._clauses.push('"' + col + '" IN (' + v.map(() => '?').join(', ') + ')');
+          this._params.push(...v);
         } else {
           this._clauses.push('"' + col + '" = ?');
           this._params.push(v);
@@ -65,12 +357,34 @@ class __SchemaQuery {
   offset(n) { this._offset = n; return this; }
   order(spec) { this._order = spec; return this; }
   orderBy(spec) { return this.order(spec); }
+  includes(...specs) {
+    this._includes.push(...__schemaNormalizeIncludes(specs));
+    return this;
+  }
+  withDeleted() { this._deleted = 'all'; return this; }
+  onlyDeleted() { this._deleted = 'deleted'; return this; }
+  unscoped() { this._unscoped = true; return this; }
+  // @defaultScope applies lazily at terminal time (all/count/updateAll/
+  // deleteAll) so .unscoped() works no matter where it appears in the
+  // chain, and so the default's clauses never double-apply.
+  _applyDefaultScope() {
+    if (this._unscoped || this._defaultScopeApplied) return;
+    this._defaultScopeApplied = true;
+    const fn = this._def._normalize().defaultScope;
+    if (fn) fn.call(this);
+  }
+  _whereParts(norm) {
+    const where = [...this._clauses];
+    if (norm.softDelete) {
+      if (this._deleted === 'live') where.push('"deleted_at" IS NULL');
+      else if (this._deleted === 'deleted') where.push('"deleted_at" IS NOT NULL');
+    }
+    return where;
+  }
   _buildSQL() {
     const n = this._def._normalize();
-    const table = n.tableName;
-    const parts = ['SELECT * FROM "' + table + '"'];
-    const where = [...this._clauses];
-    if (!this._includeDeleted && n.softDelete) where.push('"deleted_at" IS NULL');
+    const parts = ['SELECT * FROM "' + n.tableName + '"'];
+    const where = this._whereParts(n);
     if (where.length) parts.push('WHERE ' + where.join(' AND '));
     if (this._order) parts.push('ORDER BY ' + this._order);
     if (this._limit != null) parts.push('LIMIT ' + this._limit);
@@ -78,9 +392,16 @@ class __SchemaQuery {
     return parts.join(' ');
   }
   async all() {
+    this._applyDefaultScope();
     const sql = this._buildSQL();
-    const res = await __schemaAdapter.query(sql, this._params);
-    return (res.data || []).map(row => this._def._hydrate(res.columns, row));
+    const res = await __schemaRunSQL(this._def, sql, this._params);
+    const instances = (res.data || []).map(row => this._def._hydrate(res.columns, row));
+    // Eager loading: batched second queries (WHERE fk IN (...)) that
+    // fill the relation memos. Never changes the root result set.
+    if (this._includes.length && instances.length) {
+      await __schemaPreload(this._def, instances, this._includes);
+    }
+    return instances;
   }
   async first() {
     this._limit = 1;
@@ -88,14 +409,136 @@ class __SchemaQuery {
     return arr[0] || null;
   }
   async count() {
+    this._applyDefaultScope();
     const n = this._def._normalize();
     const parts = ['SELECT COUNT(*) FROM "' + n.tableName + '"'];
-    const where = [...this._clauses];
-    if (!this._includeDeleted && n.softDelete) where.push('"deleted_at" IS NULL');
+    const where = this._whereParts(n);
     if (where.length) parts.push('WHERE ' + where.join(' AND '));
-    const res = await __schemaAdapter.query(parts.join(' '), this._params);
+    const res = await __schemaRunSQL(this._def, parts.join(' '), this._params);
     return res.data?.[0]?.[0] || 0;
   }
+  // One UPDATE statement for every matching row. Bypasses validation
+  // and per-instance hooks — the name says "all", the docs say "raw".
+  // Returns the adapter's reported row count when available.
+  async updateAll(values) {
+    this._applyDefaultScope();
+    const n = this._def._normalize();
+    const keys = values && typeof values === 'object' ? Object.keys(values) : [];
+    if (!keys.length) throw new Error('updateAll: requires at least one column to set');
+    const sets = [];
+    const params = [];
+    for (const k of keys) {
+      const name = __schemaCamel(k);
+      const field = n.fields.get(name);
+      sets.push('"' + __schemaSnake(k) + '" = ?');
+      params.push(__schemaSerialize(values[k], field));
+    }
+    if (n.timestamps) {
+      sets.push('"updated_at" = ?');
+      params.push(new Date().toISOString());
+    }
+    const where = this._whereParts(n);
+    let sql = 'UPDATE "' + n.tableName + '" SET ' + sets.join(', ');
+    if (where.length) sql += ' WHERE ' + where.join(' AND ');
+    const res = await __schemaRunSQL(this._def, sql, [...params, ...this._params]);
+    return res.rowCount ?? res.rows ?? null;
+  }
+  // One statement for every matching row. Soft-delete aware: on a
+  // @softDelete model this is an UPDATE setting deleted_at; on a hard
+  // model it's a real DELETE. Bypasses per-instance hooks (bulk path).
+  async deleteAll() {
+    this._applyDefaultScope();
+    const n = this._def._normalize();
+    const where = this._whereParts(n);
+    let sql, params;
+    if (n.softDelete && this._deleted === 'live') {
+      sql = 'UPDATE "' + n.tableName + '" SET "deleted_at" = ?';
+      params = [new Date().toISOString(), ...this._params];
+    } else {
+      sql = 'DELETE FROM "' + n.tableName + '"';
+      params = this._params;
+    }
+    if (where.length) sql += ' WHERE ' + where.join(' AND ');
+    const res = await __schemaRunSQL(this._def, sql, params);
+    return res.rowCount ?? res.rows ?? null;
+  }
+}
+
+// ---- Eager loading ----------------------------------------------------------
+
+// Normalize .includes arguments into [{name, children}] trees. Accepts
+// :symbols, strings, arrays, and nested maps to any depth:
+//   .includes(:orders)
+//   .includes(:author, comments: :author)
+function __schemaNormalizeIncludes(specs) {
+  const out = [];
+  for (const s of specs) {
+    if (s == null) continue;
+    if (typeof s === 'symbol') out.push({ name: Symbol.keyFor(s) || s.description, children: [] });
+    else if (typeof s === 'string') out.push({ name: s, children: [] });
+    else if (Array.isArray(s)) out.push(...__schemaNormalizeIncludes(s));
+    else if (typeof s === 'object') {
+      for (const [k, v] of Object.entries(s)) {
+        out.push({ name: k, children: __schemaNormalizeIncludes([v]) });
+      }
+    }
+  }
+  return out;
+}
+
+// Batched preload: one query per relation per nesting level
+// (`WHERE fk IN (?, …)`), never JOINs — no row duplication, uniform
+// across belongs_to / has_one / has_many. Results land in the relation
+// memo, so `user.orders!` resolves from cache with no query. Invisible
+// to call sites: preloading is purely a performance fact.
+async function __schemaPreload(def, instances, specs) {
+  if (!instances.length || !specs.length) return;
+  const norm = def._normalize();
+  for (const spec of specs) {
+    const rel = norm.relations.get(spec.name);
+    if (!rel) {
+      throw new Error(
+        "schema: includes('" + spec.name + "') — no such relation on " + (def.name || 'model') +
+        '. Declared relations: ' + ([...norm.relations.keys()].join(', ') || '(none)'));
+    }
+    const target = __SchemaRegistry.get(rel.target);
+    if (!target) throw new Error('schema: unknown relation target "' + rel.target + '" from ' + (def.name || 'anon'));
+    const children = [];
+    if (rel.kind === 'belongsTo') {
+      const fkCamel = __schemaCamel(rel.foreignKey);
+      const ids = [...new Set(instances.map(i => i[fkCamel]).filter(v => v != null))];
+      const rows = ids.length ? await target.findMany(ids) : [];
+      const pk = target._normalize().primaryKey;
+      const byId = new Map(rows.map(r => [r[pk], r]));
+      for (const inst of instances) {
+        const v = inst[fkCamel] != null ? (byId.get(inst[fkCamel]) ?? null) : null;
+        __schemaRelMemoSet(inst, spec.name, v);
+        if (v && !children.includes(v)) children.push(v);
+      }
+    } else {
+      const pk = norm.primaryKey;
+      const fkCamel = __schemaCamel(rel.foreignKey);
+      const ids = [...new Set(instances.map(i => i[pk]).filter(v => v != null))];
+      let rows = [];
+      if (ids.length) {
+        rows = await new __SchemaQuery(target)
+          .where('"' + rel.foreignKey + '" IN (' + ids.map(() => '?').join(', ') + ')', ...ids)
+          .all();
+      }
+      const groups = new Map();
+      for (const r of rows) {
+        const k = r[fkCamel];
+        if (!groups.has(k)) groups.set(k, []);
+        groups.get(k).push(r);
+        children.push(r);
+      }
+      for (const inst of instances) {
+        const g = groups.get(inst[pk]) || [];
+        __schemaRelMemoSet(inst, spec.name, rel.kind === 'hasOne' ? (g[0] ?? null) : g);
+      }
+    }
+    if (spec.children.length) await __schemaPreload(target, children, spec.children);
+  }
 }
 
 async function __schemaResolveRelation(def, inst, rel) {
@@ -115,11 +558,26 @@ async function __schemaResolveRelation(def, inst, rel) {
   return null;
 }
 
+// ---- Save / destroy ----------------------------------------------------------
+
 async function __schemaRunHook(def, inst, name) {
   const fn = def._normalize().hooks.get(name);
   if (fn) await fn.call(inst);
 }
 
+// After a successful save/destroy: queue afterCommit/afterRollback on
+// the ambient transaction, or fire afterCommit immediately when no
+// transaction is open (AR semantics: outside a tx, "commit" is the
+// statement itself). Only models that declare one of the two hooks pay
+// any cost here.
+async function __schemaSettleTxHooks(def, inst) {
+  const hooks = def._normalize().hooks;
+  if (!hooks.has('afterCommit') && !hooks.has('afterRollback')) return;
+  if (!__schemaEnqueueTxHook(def, inst)) {
+    await __schemaRunHook(def, inst, 'afterCommit');
+  }
+}
+
 async function __schemaSave(def, inst) {
   // Re-entry guard. Same-instance re-entry into save() — typically a
   // hook on this very instance calling .save() on `this` — would race
@@ -182,24 +640,9 @@ async function __schemaSave(def, inst) {
       }
     }
     const sql = 'INSERT INTO "' + norm.tableName + '" (' + cols.join(', ') + ') VALUES (' + placeholders.join(', ') + ') RETURNING *';
-    const res = await __schemaAdapter.query(sql, values);
+    const res = await __schemaRunSQL(def, sql, values);
     if (res.data?.[0] && res.columns) {
-      for (let i = 0; i < res.columns.length; i++) {
-        const snake = res.columns[i].name;
-        const key = __schemaCamel(snake);
-        if (!(key in inst)) {
-          Object.defineProperty(inst, key, { value: res.data[0][i], enumerable: true, writable: true, configurable: true });
-        } else {
-          inst[key] = res.data[0][i];
-        }
-        if (snake !== key && !(snake in inst)) {
-          Object.defineProperty(inst, snake, {
-            enumerable: false, configurable: true,
-            get() { return this[key]; },
-            set(v) { this[key] = v; },
-          });
-        }
-      }
+      __schemaAbsorbRow(inst, res.columns, res.data[0]);
     }
     // Now that the RETURNING columns (id, @timestamps, FKs) are on the
     // instance, !> eager-derived fields can see them. Mirrors the hydrate
@@ -347,7 +790,7 @@ async function __schemaSave(def, inst) {
       }
       values.push(wherePk);
       const sql = 'UPDATE "' + norm.tableName + '" SET ' + sets.join(', ') + ' WHERE "' + pk + '" = ?';
-      await __schemaAdapter.query(sql, values);
+      await __schemaRunSQL(def, sql, values);
       inst._snapshot = nextSnap;
     }
   }
@@ -356,6 +799,7 @@ async function __schemaSave(def, inst) {
   if (isNew) await __schemaRunHook(def, inst, 'afterCreate');
   else       await __schemaRunHook(def, inst, 'afterUpdate');
   await __schemaRunHook(def, inst, 'afterSave');
+  await __schemaSettleTxHooks(def, inst);
   return inst;
 
   } finally {
@@ -363,19 +807,59 @@ async function __schemaSave(def, inst) {
   }
 }
 
-async function __schemaDestroy(def, inst) {
+// Absorb a RETURNING row onto an instance: camelCase canonical own
+// properties plus non-enumerable snake_case aliases. Shared by the
+// INSERT path, upsert, and restore.
+function __schemaAbsorbRow(inst, columns, row) {
+  for (let i = 0; i < columns.length; i++) {
+    const snake = columns[i].name;
+    const key = __schemaCamel(snake);
+    if (!(key in inst)) {
+      Object.defineProperty(inst, key, { value: row[i], enumerable: true, writable: true, configurable: true });
+    } else {
+      inst[key] = row[i];
+    }
+    if (snake !== key && !(snake in inst)) {
+      Object.defineProperty(inst, snake, {
+        enumerable: false, configurable: true,
+        get() { return this[key]; },
+        set(v) { this[key] = v; },
+      });
+    }
+  }
+}
+
+async function __schemaDestroy(def, inst, opts) {
   if (!inst._persisted) return inst;
   const norm = def._normalize();
+  const hard = opts && opts.hard === true;
   await __schemaRunHook(def, inst, 'beforeDestroy');
-  if (norm.softDelete) {
+  if (norm.softDelete && !hard) {
     const now = new Date().toISOString();
-    await __schemaAdapter.query('UPDATE "' + norm.tableName + '" SET "deleted_at" = ? WHERE "' + norm.primaryKey + '" = ?', [now, inst[norm.primaryKey]]);
+    await __schemaRunSQL(def, 'UPDATE "' + norm.tableName + '" SET "deleted_at" = ? WHERE "' + norm.primaryKey + '" = ?', [now, inst[norm.primaryKey]]);
     inst.deletedAt = now;
   } else {
-    await __schemaAdapter.query('DELETE FROM "' + norm.tableName + '" WHERE "' + norm.primaryKey + '" = ?', [inst[norm.primaryKey]]);
+    await __schemaRunSQL(def, 'DELETE FROM "' + norm.tableName + '" WHERE "' + norm.primaryKey + '" = ?', [inst[norm.primaryKey]]);
     inst._persisted = false;
   }
   await __schemaRunHook(def, inst, 'afterDestroy');
+  await __schemaSettleTxHooks(def, inst);
+  return inst;
+}
+
+// Soft-delete recovery: UPDATE ... SET deleted_at = NULL. Fires the
+// update lifecycle (beforeUpdate/afterUpdate) like Active Record's
+// touch-style writes. Only meaningful on @softDelete models.
+async function __schemaRestore(def, inst) {
+  const norm = def._normalize();
+  if (!norm.softDelete) {
+    throw new Error('schema: restore() requires @softDelete on ' + (def.name || 'model'));
+  }
+  if (!inst._persisted) return inst;
+  await __schemaRunHook(def, inst, 'beforeUpdate');
+  await __schemaRunSQL(def, 'UPDATE "' + norm.tableName + '" SET "deleted_at" = NULL WHERE "' + norm.primaryKey + '" = ?', [inst[norm.primaryKey]]);
+  inst.deletedAt = null;
+  await __schemaRunHook(def, inst, 'afterUpdate');
   return inst;
 }
 
@@ -386,20 +870,27 @@ function __schemaSerialize(v, field) {
   return v;
 }
 
-// ORM prototype augmentations — added to __SchemaDef
+// ---- ORM prototype augmentations — added to __SchemaDef ----------------------
 
 __SchemaDef.prototype.find = async function (id) {
   this._assertModel('find');
+  // Routed through the builder so find honors the same filters as every
+  // other read: the @softDelete `deleted_at IS NULL` filter and the
+  // model's @defaultScope (Active Record semantics — default_scope
+  // applies to find). `User.unscoped().where(id: …).first!` is the
+  // escape hatch.
+  const norm = this._normalize();
+  return new __SchemaQuery(this).where({ [norm.primaryKey]: id }).first();
+};
+
+__SchemaDef.prototype.findMany = async function (ids) {
+  this._assertModel('findMany');
+  if (!Array.isArray(ids)) throw new Error('schema: findMany(ids) expects an array');
+  if (!ids.length) return [];
   const norm = this._normalize();
-  const soft = norm.softDelete ? ' AND "deleted_at" IS NULL' : '';
-  const sql = 'SELECT * FROM "' + norm.tableName + '" WHERE "' + norm.primaryKey + '" = ?' + soft + ' LIMIT 1';
-  const res = await __schemaAdapter.query(sql, [id]);
-  // Harbor returns rowCount (not the legacy `rows` alias). Treat both
-  // as authoritative so the runtime works against any /sql adapter
-  // that has a row-count field, regardless of which name it uses.
-  const n = res.rowCount ?? res.rows;
-  if (!n || !res.data?.[0]) return null;
-  return this._hydrate(res.columns, res.data[0]);
+  return new __SchemaQuery(this)
+    .where('"' + norm.primaryKey + '" IN (' + ids.map(() => '?').join(', ') + ')', ...ids)
+    .all();
 };
 
 __SchemaDef.prototype.where = function (cond, ...params) {
@@ -407,6 +898,26 @@ __SchemaDef.prototype.where = function (cond, ...params) {
   return new __SchemaQuery(this).where(cond, ...params);
 };
 
+__SchemaDef.prototype.includes = function (...specs) {
+  this._assertModel('includes');
+  return new __SchemaQuery(this).includes(...specs);
+};
+
+__SchemaDef.prototype.withDeleted = function () {
+  this._assertModel('withDeleted');
+  return new __SchemaQuery(this).withDeleted();
+};
+
+__SchemaDef.prototype.onlyDeleted = function () {
+  this._assertModel('onlyDeleted');
+  return new __SchemaQuery(this).onlyDeleted();
+};
+
+__SchemaDef.prototype.unscoped = function () {
+  this._assertModel('unscoped');
+  return new __SchemaQuery(this).unscoped();
+};
+
 __SchemaDef.prototype.all = function () {
   this._assertModel('all');
   return new __SchemaQuery(this).all();
@@ -445,6 +956,139 @@ __SchemaDef.prototype.create = async function (data) {
   return inst;
 };
 
+// INSERT ... ON CONFLICT (target) DO UPDATE SET ... RETURNING *.
+//
+//   User.upsert! {email: "a@b.c", name: "Alice"}, on: :email
+//
+// Validates the row and fires beforeValidation / beforeSave / afterSave.
+// beforeCreate/beforeUpdate do NOT fire — the runtime cannot know which
+// branch the database took. The conflict target accepts a :symbol,
+// string, or array of either (composite targets).
+__SchemaDef.prototype.upsert = async function (data, opts) {
+  this._assertModel('upsert');
+  const norm = this._normalize();
+  const on = opts && (opts.on ?? opts.conflict);
+  if (on == null) throw new Error("schema: upsert(data, on: :column) requires a conflict target");
+  const targets = (Array.isArray(on) ? on : [on]).map(t =>
+    __schemaSnake(typeof t === 'symbol' ? (Symbol.keyFor(t) || t.description) : String(t)));
+
+  const klass = this._getClass();
+  const canonical = {};
+  if (data && typeof data === 'object') {
+    for (const k of Object.keys(data)) canonical[__schemaCamel(k)] = data[k];
+  }
+  const inst = new klass(this._applyDefaults(canonical), false);
+  for (const [k, v] of Object.entries(canonical)) {
+    if (!(k in inst)) {
+      Object.defineProperty(inst, k, { value: v, enumerable: true, writable: true, configurable: true });
+    }
+  }
+
+  await __schemaRunHook(this, inst, 'beforeValidation');
+  const errs = this._validateFields(inst, true);
+  if (errs.length) throw new SchemaError(errs, this.name, this.kind);
+  await __schemaRunHook(this, inst, 'afterValidation');
+  await __schemaRunHook(this, inst, 'beforeSave');
+
+  const cols = [], placeholders = [], values = [];
+  for (const [n, f] of norm.fields) {
+    const v = inst[n];
+    if (v == null) continue;
+    cols.push(__schemaSnake(n));
+    placeholders.push('?');
+    values.push(__schemaSerialize(v, f));
+  }
+  for (const [, rel] of norm.relations) {
+    if (rel.kind !== 'belongsTo') continue;
+    const v = inst[__schemaCamel(rel.foreignKey)];
+    if (v != null) {
+      cols.push(rel.foreignKey);
+      placeholders.push('?');
+      values.push(v);
+    }
+  }
+  if (!cols.length) throw new Error('schema: upsert() requires at least one column');
+  const updateCols = cols.filter(c => !targets.includes(c));
+  let conflict = ' ON CONFLICT (' + targets.map(t => '"' + t + '"').join(', ') + ')';
+  if (updateCols.length) {
+    const sets = updateCols.map(c => '"' + c + '" = EXCLUDED."' + c + '"');
+    if (norm.timestamps) sets.push('"updated_at" = CURRENT_TIMESTAMP');
+    conflict += ' DO UPDATE SET ' + sets.join(', ');
+  } else {
+    conflict += ' DO NOTHING';
+  }
+  const sql = 'INSERT INTO "' + norm.tableName + '" (' + cols.map(c => '"' + c + '"').join(', ') + ')' +
+    ' VALUES (' + placeholders.join(', ') + ')' + conflict + ' RETURNING *';
+  const res = await __schemaRunSQL(this, sql, values);
+  if (res.data?.[0] && res.columns) __schemaAbsorbRow(inst, res.columns, res.data[0]);
+  this._applyEagerDerived(inst);
+  inst._snapshot = __schemaSnapshot(norm, inst);
+  inst._persisted = true;
+  await __schemaRunHook(this, inst, 'afterSave');
+  await __schemaSettleTxHooks(this, inst);
+  return inst;
+};
+
+// Bulk insert: validates EVERY row first (collecting all failures into
+// one SchemaError, issues prefixed `[i].field`, before any SQL), then
+// issues one multi-VALUES INSERT ... RETURNING *. Per-instance hooks
+// are deliberately skipped — this is the bulk path; use create! in a
+// loop when hooks matter. Returns hydrated instances.
+__SchemaDef.prototype.insertMany = async function (rows) {
+  this._assertModel('insertMany');
+  if (!Array.isArray(rows)) throw new Error('schema: insertMany(rows) expects an array');
+  if (!rows.length) return [];
+  const norm = this._normalize();
+
+  const canonicalRows = [];
+  const allErrs = [];
+  for (let i = 0; i < rows.length; i++) {
+    const canonical = {};
+    const data = rows[i];
+    if (data && typeof data === 'object') {
+      for (const k of Object.keys(data)) canonical[__schemaCamel(k)] = data[k];
+    }
+    this._applyDefaults(canonical);
+    for (const e of this._validateFields(canonical, true)) {
+      allErrs.push({
+        field: '[' + i + ']' + (e.field ? '.' + e.field : ''),
+        error: e.error,
+        message: '[' + i + '] ' + e.message,
+      });
+    }
+    canonicalRows.push(canonical);
+  }
+  if (allErrs.length) throw new SchemaError(allErrs, this.name, this.kind);
+
+  // Column set = union of written columns across rows (missing values
+  // insert as NULL / column default).
+  const colSet = new Set();
+  for (const row of canonicalRows) {
+    for (const [n] of norm.fields) if (row[n] != null) colSet.add(n);
+    for (const [, rel] of norm.relations) {
+      if (rel.kind !== 'belongsTo') continue;
+      if (row[__schemaCamel(rel.foreignKey)] != null) colSet.add(__schemaCamel(rel.foreignKey));
+    }
+  }
+  const colNames = [...colSet];
+  if (!colNames.length) throw new Error('schema: insertMany() requires at least one column');
+  const values = [];
+  const tuples = [];
+  for (const row of canonicalRows) {
+    const slots = [];
+    for (const n of colNames) {
+      slots.push('?');
+      values.push(__schemaSerialize(row[n] ?? null, norm.fields.get(n)));
+    }
+    tuples.push('(' + slots.join(', ') + ')');
+  }
+  const sql = 'INSERT INTO "' + norm.tableName + '" (' +
+    colNames.map(n => '"' + __schemaSnake(n) + '"').join(', ') + ') VALUES ' +
+    tuples.join(', ') + ' RETURNING *';
+  const res = await __schemaRunSQL(this, sql, values);
+  return (res.data || []).map(row => this._hydrate(res.columns, row));
+};
+
 __SchemaDef.prototype._assertModel = function (api) {
   if (this.kind !== 'model') {
     throw new Error('schema: .' + api + '() is :model-only (got :' + this.kind + ')');