rip-lang 3.15.4 → 3.16.1

package/src/repl.js

@@ -327,9 +327,23 @@ export class RipREPL {
       return varName;
     });
 
-    const staticImports = dynamicImports
-      .map(({ varName, specifier }) => `import * as ${varName} from '${specifier}';`)
-      .join('\n');
+    const staticImportLines = dynamicImports
+      .map(({ varName, specifier }) => `import * as ${varName} from '${specifier}';`);
+
+    // Extract user-written `import X from "…"` statements out of the body so they
+    // live in the SourceTextModule prelude instead of failing inside the async IIFE.
+    // Captures default, named, namespace, mixed, renamed, and side-effect imports.
+    const importedBindings = new Set();
+    js = js.replace(
+      /^import\s+(?:([^'"]+?)\s+from\s+)?(['"])([^'"]+)\2\s*;?\s*$/gm,
+      (match, spec) => {
+        staticImportLines.push(match);
+        for (const name of parseImportBindings(spec)) importedBindings.add(name);
+        return '';
+      }
+    );
+
+    const staticImports = staticImportLines.join('\n');
 
     // Restore existing variables and remove duplicate declarations
     const existingVars = Object.keys(this.vars);
@@ -351,13 +365,16 @@ export class RipREPL {
     // Build restore code
     // Non-reactive vars: let x = __vars['x'];
     // Reactive vars: const x = __vars['x']; (they're already stored)
+    // Skip names being declared by an `import` on this line — the import itself
+    // is the binding, and `let x = …` (or `const x = …`) on top would be a
+    // redeclaration. Apply the skip uniformly to both restore paths.
     const nonReactiveRestore = existingNonReactive
-      .filter(k => k !== '_')
+      .filter(k => k !== '_' && !importedBindings.has(k))
       .map(v => `let ${v} = __vars['${v}'];`)
       .join('\n');
 
     const reactiveRestore = [...this.reactiveVars]
-      .filter(v => existingVars.includes(v))
+      .filter(v => existingVars.includes(v) && !importedBindings.has(v))
       .map(v => `const ${v} = __vars['${v}'];`)
       .join('\n');
 
@@ -365,7 +382,7 @@ export class RipREPL {
 
     // Build save code (save non-reactive vars back to __vars)
     // Reactive vars are already saved via the const transformation
-    const nonReactiveVars = [...new Set([...existingNonReactive, ...declaredVars])]
+    const nonReactiveVars = [...new Set([...existingNonReactive, ...declaredVars, ...importedBindings])]
       .filter(k => k !== '_' && !this.reactiveVars.has(k));
     const saveCode = nonReactiveVars
       .map(v => `if (typeof ${v} !== 'undefined') __vars['${v}'] = ${v};`)
@@ -592,6 +609,57 @@ ${colors.cyan}Tips:${colors.reset}
   }
 }
 
+/**
+ * Extract local-binding names from the bindings clause of a static import.
+ *
+ * Handles:
+ *   default          → `Time`                     → ['Time']
+ *   namespace        → `* as time`                → ['time']
+ *   default + named  → `Time, { Duration }`       → ['Time', 'Duration']
+ *   default + ns     → `Time, * as ns`            → ['Time', 'ns']
+ *   named + rename   → `{ A, B as C }`            → ['A', 'C']
+ *   side-effect      → undefined / `{}`           → []
+ */
+function parseImportBindings(spec) {
+  if (!spec) return [];
+  const names = [];
+  let rest = spec.trim();
+
+  const ID = /^([A-Za-z_$][\w$]*)/;
+  const NS = /^\*\s+as\s+([A-Za-z_$][\w$]*)/;
+  const RENAME = /^([A-Za-z_$][\w$]*)\s+as\s+([A-Za-z_$][\w$]*)$/;
+
+  // Default import (must come first if present)
+  const def = rest.match(ID);
+  if (def && rest.slice(def[0].length).trimStart().match(/^[,{]|$/)) {
+    names.push(def[1]);
+    rest = rest.slice(def[0].length).trimStart();
+    if (rest.startsWith(',')) rest = rest.slice(1).trimStart();
+  }
+
+  // Namespace
+  const ns = rest.match(NS);
+  if (ns) {
+    names.push(ns[1]);
+    rest = rest.slice(ns[0].length).trimStart();
+  }
+
+  // Named bindings { A, B as C }
+  const named = rest.match(/^\{([^}]*)\}/);
+  if (named) {
+    for (const part of named[1].split(',')) {
+      const t = part.trim();
+      if (!t) continue;
+      const ren = t.match(RENAME);
+      if (ren) { names.push(ren[2]); continue; }
+      const id = t.match(/^([A-Za-z_$][\w$]*)$/);
+      if (id) names.push(id[1]);
+    }
+  }
+
+  return names;
+}
+
 /**
  * Start the REPL
  */

package/src/schema/runtime-orm.js

@@ -14,7 +14,7 @@
 
 /* eslint-disable no-undef, no-unused-vars */
 function __schemaDefaultAdapter() {
-  const url = (typeof process !== 'undefined' && process.env?.DB_URL) || 'http://localhost:4213';
+  const url = (typeof process !== 'undefined' && process.env?.DB_URL) || 'http://localhost:9494';
   return {
     async query(sql, params) {
       const body = params && params.length ? { sql, params } : { sql };
@@ -121,6 +121,21 @@ async function __schemaRunHook(def, inst, name) {
 }
 
 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
+  // the snapshot / savedChanges machinery and almost certainly loop
+  // forever. Throw a clear error instead. The flag is per-instance, so
+  // independent instances saving in parallel are unaffected; sequential
+  // saves on the same instance work fine because `finally` clears it.
+  if (inst._saving) {
+    throw new Error(
+      "schema: save() re-entered on the same " + (def.name || 'instance') +
+      "; a hook on this instance called save() while a save was already in flight."
+    );
+  }
+  inst._saving = true;
+  try {
+
   const norm = def._normalize();
   const isNew = !inst._persisted;
 
@@ -133,14 +148,25 @@ async function __schemaSave(def, inst) {
   if (isNew) await __schemaRunHook(def, inst, 'beforeCreate');
   else       await __schemaRunHook(def, inst, 'beforeUpdate');
 
+  // Reset `savedChanges` at the start of every save so it always
+  // reflects the most recent write, never accumulates. Hooks running
+  // from this point until end-of-save read this Map; afterCreate /
+  // afterUpdate / afterSave see the just-completed write's diff.
+  inst.savedChanges = new Map();
+
   if (isNew) {
     const cols = [], placeholders = [], values = [];
+    // Track which persisted columns actually got written so savedChanges
+    // can record [null, newValue] entries below. Both declared fields
+    // and belongsTo FK columns count.
+    const writtenColumns = [];
     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));
+      writtenColumns.push([n, v]);
     }
     // Include relation FKs. belongsTo FKs are camelCase properties on
     // the instance (e.g. organizationId for organization_id).
@@ -152,6 +178,7 @@ async function __schemaSave(def, inst) {
         cols.push('"' + rel.foreignKey + '"');
         placeholders.push('?');
         values.push(v);
+        writtenColumns.push([fkCamel, v]);
       }
     }
     const sql = 'INSERT INTO "' + norm.tableName + '" (' + cols.join(', ') + ') VALUES (' + placeholders.join(', ') + ') RETURNING *';
@@ -180,19 +207,148 @@ async function __schemaSave(def, inst) {
     // populated. Per-docs semantics ("materialize once, not reactive")
     // still hold — we're firing once, at end of construction, not on
     // subsequent mutations.
+    //
+    // Order matters here: snapshot the declared-field state BEFORE
+    // flipping `_persisted`, so a later save() can never see the
+    // combination "_persisted = true, _snapshot = null" (which would
+    // fall through to a full-row UPDATE and reintroduce the FK bug).
     def._applyEagerDerived(inst);
+    inst._snapshot = __schemaSnapshot(norm, inst);
     inst._persisted = true;
+    // Populate savedChanges with [null, newValue] per persisted column
+    // that was written (declared fields + belongsTo FKs). Mirrors
+    // Active Record: on a fresh INSERT every attribute "changed from
+    // nil to its new value". @timestamps columns get the same
+    // [null, newValue] treatment using the values RETURNING gave us
+    // — they were assigned on this INSERT, so they belong in the diff.
+    for (const [n, v] of writtenColumns) inst.savedChanges.set(n, [null, v]);
+    if (norm.timestamps) {
+      if (inst.createdAt != null) inst.savedChanges.set('createdAt', [null, inst.createdAt]);
+      if (inst.updatedAt != null) inst.savedChanges.set('updatedAt', [null, inst.updatedAt]);
+    }
   } else {
+    // Column-targeted UPDATE: only write fields that actually changed
+    // since hydrate / last save (snapshot comparison) or that the caller
+    // explicitly marked dirty via .markDirty(name) — escape hatch for
+    // in-place mutations of object-valued fields where === can't detect
+    // change. Two reasons this matters:
+    //   1. Skip a wasted DB round-trip when nothing changed.
+    //   2. DuckDB's foreign-key implementation rejects UPDATE statements
+    //      that touch indexed columns (PK / UNIQUE) on a row that is
+    //      referenced by another table's FK — even when the SET is a
+    //      no-op like "mrn = mrn". A full-row UPDATE on a parent table
+    //      with any child rows is therefore a hard error in DuckDB.
+    //      Writing only changed columns keeps no-op saves entirely off
+    //      the index path.
+    //
+    // We build `nextSnap` from the values we are about to write — BEFORE
+    // the await — and only install it on success. Doing this after the
+    // await would be unsafe under concurrent mutation: a write to the
+    // instance during the in-flight query would be captured into the
+    // post-await snapshot, mark itself "clean", and never be persisted.
+    //
+    // `nextSnap` is allocated lazily on the first changed field; the
+    // common no-op-save path keeps zero allocations.
     const sets = [], values = [];
+    const snap = inst._snapshot;
+    const dirty = inst._dirty;
+    const changes = inst.savedChanges;
+    let nextSnap = null;
+    // Declared fields.
     for (const [n, f] of norm.fields) {
+      const cur = inst[n];
+      const isDirty = dirty && dirty.has(n);
+      const changed = !snap || !Object.prototype.hasOwnProperty.call(snap, n) || !__schemaSameValue(snap[n], cur);
+      if (!isDirty && !changed) continue;
+      if (!nextSnap) nextSnap = Object.assign(Object.create(null), snap || {});
       sets.push('"' + __schemaSnake(n) + '" = ?');
-      values.push(__schemaSerialize(inst[n], f));
+      values.push(__schemaSerialize(cur, f));
+      nextSnap[n] = cur;
+      // Record [oldValue, newValue] for hook consumers / audit. Old
+      // value comes from the snapshot; if no snapshot existed (first
+      // save after a manually-constructed persisted instance) we
+      // record null as the old value, which is the best information
+      // we have.
+      const old = snap && Object.prototype.hasOwnProperty.call(snap, n) ? snap[n] : null;
+      changes.set(n, [old, cur]);
+    }
+    // belongsTo FK columns. Same dirty / snapshot / savedChanges
+    // machinery as declared fields, but the SQL column name is
+    // already snake_case (rel.foreignKey) and the value isn't passed
+    // through __schemaSerialize since FKs are scalar IDs.
+    for (const [, rel] of norm.relations) {
+      if (rel.kind !== 'belongsTo') continue;
+      const fkCamel = __schemaCamel(rel.foreignKey);
+      const cur = inst[fkCamel];
+      const isDirty = dirty && dirty.has(fkCamel);
+      const changed = !snap || !Object.prototype.hasOwnProperty.call(snap, fkCamel) || !__schemaSameValue(snap[fkCamel], cur);
+      if (!isDirty && !changed) continue;
+      if (!nextSnap) nextSnap = Object.assign(Object.create(null), snap || {});
+      sets.push('"' + rel.foreignKey + '" = ?');
+      values.push(cur);
+      nextSnap[fkCamel] = cur;
+      const old = snap && Object.prototype.hasOwnProperty.call(snap, fkCamel) ? snap[fkCamel] : null;
+      changes.set(fkCamel, [old, cur]);
+    }
+    // @timestamps: bump updated_at iff this UPDATE will actually emit
+    // SQL. The check sits between the diff loops and the write, so we
+    // only touch the column when sets has something else in it —
+    // never on a no-op save (which would defeat the column-targeted
+    // UPDATE optimization and reintroduce a wasted DB round-trip).
+    // The column itself isn't in `_snapshot` (we always overwrite it
+    // explicitly on every real write, never compare it for diffs),
+    // so we mirror the new value onto the instance and record it in
+    // savedChanges to mirror Active Record's saved_changes shape.
+    //
+    // `oldTs` is the in-memory value at this moment, which after
+    // hydrate is the DB-loaded timestamp and after a prior save in
+    // this session is the value we set then. If user code reassigns
+    // `inst.updatedAt` between saves, the recorded "old" reflects
+    // that reassignment, not what's actually in the DB. The implicit
+    // column isn't in the snapshot for the same reason it isn't in
+    // the diff loop: we always overwrite it on real writes.
+    //
+    // Declaring `updatedAt` as a regular field is rejected at schema
+    // definition (__SCHEMA_RESERVED_IMPLICIT) so we can't end up with
+    // duplicate "updated_at = ?" entries in `sets`.
+    if (norm.timestamps && sets.length > 0) {
+      const newTs = new Date().toISOString();
+      const oldTs = inst.updatedAt != null ? inst.updatedAt : null;
+      sets.push('"updated_at" = ?');
+      values.push(newTs);
+      inst.updatedAt = newTs;
+      changes.set('updatedAt', [oldTs, newTs]);
     }
     if (sets.length) {
+      // WHERE uses the *original* PK from the snapshot, not the live
+      // `inst[pk]` value. If user code reassigns the in-memory PK
+      // between hydrate and save, the UPDATE still targets the row
+      // that was actually loaded — mirrors Active Record, which
+      // ignores in-memory PK mutation when building the UPDATE.
+      // Falls back to `inst[pk]` only when no snapshot exists (e.g.
+      // a manually-constructed persisted instance), where there's
+      // no better information available. We log a warning in non-prod
+      // when the fallback fires, since "persisted instance with no
+      // snapshot" is almost always an accidental misuse pattern.
       const pk = norm.primaryKey;
-      values.push(inst[pk]);
+      let wherePk;
+      if (snap && snap[pk] != null) {
+        wherePk = snap[pk];
+      } else {
+        wherePk = inst[pk];
+        if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
+          console.warn(
+            "[schema] " + (def.name || 'save()') + ": no _snapshot, falling back to inst." + pk +
+            " for the UPDATE WHERE clause. This usually means the instance was constructed " +
+            "with _persisted = true without going through hydrate(); the WHERE will target " +
+            "whatever inst." + pk + " happens to be at save time."
+          );
+        }
+      }
+      values.push(wherePk);
       const sql = 'UPDATE "' + norm.tableName + '" SET ' + sets.join(', ') + ' WHERE "' + pk + '" = ?';
       await __schemaAdapter.query(sql, values);
+      inst._snapshot = nextSnap;
     }
   }
   inst._dirty.clear();
@@ -201,6 +357,10 @@ async function __schemaSave(def, inst) {
   else       await __schemaRunHook(def, inst, 'afterUpdate');
   await __schemaRunHook(def, inst, 'afterSave');
   return inst;
+
+  } finally {
+    inst._saving = false;
+  }
 }
 
 async function __schemaDestroy(def, inst) {
@@ -234,7 +394,11 @@ __SchemaDef.prototype.find = async function (id) {
   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]);
-  if (!res.rows) return null;
+  // 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]);
 };
 

package/src/schema/runtime-validate.js

@@ -33,9 +33,21 @@ const __SCHEMA_RESERVED_STATIC = new Set([
   'parse','safe','ok','find','findMany','where','all','first','count','create','toSQL',
 ]);
 const __SCHEMA_RESERVED_INSTANCE = new Set([
-  'save','destroy','reload','ok','errors','toJSON',
+  'save','destroy','reload','ok','errors','toJSON','savedChanges','markDirty',
+  '_saving',
+]);
+// Implicit columns owned by directive-driven runtime behavior. Declaring
+// them as user fields would either shadow the runtime API (savedChanges /
+// markDirty in INSTANCE) or produce duplicate SET writes in the same
+// UPDATE statement when @timestamps / @softDelete bump them.
+const __SCHEMA_RESERVED_IMPLICIT = new Set([
+  'createdAt','updatedAt','deletedAt',
+]);
+const __SCHEMA_RESERVED = new Set([
+  ...__SCHEMA_RESERVED_STATIC,
+  ...__SCHEMA_RESERVED_INSTANCE,
+  ...__SCHEMA_RESERVED_IMPLICIT,
 ]);
-const __SCHEMA_RESERVED = new Set([...__SCHEMA_RESERVED_STATIC, ...__SCHEMA_RESERVED_INSTANCE]);
 
 const __schemaTypes = {
   string:   v => typeof v === 'string',
@@ -97,6 +109,63 @@ function __schemaSnake(s) { return s.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLo
 
 function __schemaCamel(col) { return String(col).replace(/_([a-z])/g, (_, c) => c.toUpperCase()); }
 
+// Reject acronym-style camelCase like `mdmID`, `userOrgID`, or
+// `XMLHttpRequest`. Two consecutive uppercase letters break the
+// snake_case <-> camelCase bijection: `mdmID` would round-trip via
+// __schemaSnake to `mdm_i_d` and back via __schemaCamel to `mdmID`,
+// while a more natural snake_case spelling `mdm_id` round-trips to
+// `mdmId` (different identifier). Forcing canonical camelCase at
+// schema-definition time eliminates the entire class of edge case
+// in field-name resolution (markDirty, savedChanges keys, snake
+// aliases on hydrate). Same convention as Active Record / Java
+// Beans / Swift's "Acronyms in API names" guidance.
+//
+// Accepts: lowercase-first, alphanumeric body, no two consecutive
+// uppercase letters anywhere.
+//   ok:    name, mrn, firstName, mdmId, userOrgId, line2, a1b2
+//   bad:   ID, mdmID, userID, XMLHttpRequest, _foo, 1foo, foo_bar
+function __schemaValidateCanonicalName(name) {
+  if (typeof name !== 'string' || !/^[a-z][a-zA-Z0-9]*$/.test(name)) return false;
+  if (/[A-Z]{2,}/.test(name)) return false;
+  return true;
+}
+
+// Snapshot the current values of every persisted column on an instance:
+// the primary key, declared fields (from `norm.fields`), and `belongsTo`
+// FK columns (from `norm.relations`). Used by `_hydrate` and the INSERT
+// / UPDATE branches of `__schemaSave` (defined in the orm fragment,
+// which loads after this one) so that a later .save() can compare and
+// emit a SET only for columns the caller actually mutated. Lives in the
+// validate fragment because `_hydrate` owns it; the orm fragment is
+// the consumer.
+//
+// FK columns are keyed by their camelCase property name on the instance
+// (e.g. `userId`) — same convention the dirty Set, savedChanges Map,
+// and markDirty() resolver use.
+//
+// The primary key is captured so __schemaSave's UPDATE WHERE clause can
+// target the originally-loaded row even if `inst[pk]` is reassigned in
+// memory. PK never appears in the UPDATE SET; it's identity, not data.
+function __schemaSnapshot(norm, inst) {
+  const snap = Object.create(null);
+  snap[norm.primaryKey] = inst[norm.primaryKey];
+  for (const [n] of norm.fields) snap[n] = inst[n];
+  for (const [, rel] of norm.relations) {
+    if (rel.kind !== 'belongsTo') continue;
+    const fkCamel = __schemaCamel(rel.foreignKey);
+    snap[fkCamel] = inst[fkCamel];
+  }
+  return snap;
+}
+
+// SameValue-Zero: like ===, except NaN equals NaN. Used by the dirty
+// check so a persisted NaN doesn't trigger a wasted UPDATE on every
+// save. Distinguishes from Object.is by treating +0/-0 as equal, which
+// is the right semantics for SQL: the DB doesn't distinguish them.
+function __schemaSameValue(a, b) {
+  return a === b || (a !== a && b !== b);
+}
+
 const __SchemaRegistry = {
   _entries: new Map(),
   register(def) {
@@ -161,9 +230,24 @@ class __SchemaDef {
       if (this.kind === 'model' && __SCHEMA_RESERVED.has(n)) collision(n, 'reserved ORM name');
     };
 
+    const requireCanonicalName = (n, kindLabel) => {
+      if (!__schemaValidateCanonicalName(n)) {
+        throw new SchemaError(
+          [{
+            field: n,
+            error: 'invalid-name',
+            message: kindLabel + " name '" + n + "' is not canonical camelCase. " +
+              "Use a lowercase-first, alphanumeric identifier with no consecutive uppercase letters " +
+              "(e.g. 'mdmId' not 'mdmID'). This keeps snake_case <-> camelCase mapping unambiguous.",
+          }],
+          this.name, this.kind);
+      }
+    };
+
     for (const e of this._desc.entries) {
       switch (e.tag) {
         case 'field':
+          requireCanonicalName(e.name, 'field');
           noteCollision(e.name);
           fields.set(e.name, {
             name: e.name,
@@ -330,6 +414,20 @@ class __SchemaDef {
         Object.defineProperty(this, '_dirty', { value: new Set(), enumerable: false, writable: false, configurable: true });
         Object.defineProperty(this, '_persisted', { value: persisted === true, enumerable: false, writable: true, configurable: true });
         Object.defineProperty(this, '_snapshot', { value: null, enumerable: false, writable: true, configurable: true });
+        // Re-entry guard for save(): set true while a save is in flight,
+        // cleared in __schemaSave's finally. Throws on same-instance
+        // re-entry (typically from a hook accidentally calling save()
+        // on its own instance) instead of looping forever or racing the
+        // snapshot / savedChanges machinery.
+        Object.defineProperty(this, '_saving', { value: false, enumerable: false, writable: true, configurable: true });
+        // Mirrors Active Record's `saved_changes`: populated by save()
+        // with the field-level diff of the just-completed write. INSERT
+        // produces `[null, newValue]` per written field; UPDATE produces
+        // `[oldValue, newValue]` per changed field. An empty Map after a
+        // save() call means nothing was actually written. Reset to a
+        // fresh Map at the start of every save() so it always reflects
+        // the most recent save, never accumulates across calls.
+        Object.defineProperty(this, 'savedChanges', { value: new Map(), enumerable: false, writable: true, configurable: true });
         if (data && typeof data === 'object') {
           for (const k of fieldNames) {
             if (k in data && data[k] !== undefined) this[k] = data[k];
@@ -376,6 +474,43 @@ class __SchemaDef {
         enumerable: false, configurable: true, writable: true,
         value: function() { return def._validateFields(this, true); },
       });
+      // Public API for forcing a column into the next UPDATE when value
+      // identity can't detect the change — typically after an in-place
+      // mutation of an object-valued field (json, Date) where the JS
+      // reference is unchanged. Validates the field name against the
+      // schema so typos throw instead of silently no-op'ing, and is
+      // restricted to persisted instances since INSERT writes every
+      // non-null field anyway (silently doing nothing is a footgun).
+      Object.defineProperty(klass.prototype, 'markDirty', {
+        enumerable: false, configurable: true, writable: true,
+        value: function(name) {
+          if (!this._persisted) {
+            throw new Error(
+              "schema: markDirty('" + name + "') is only valid on persisted instances; INSERT writes every set field"
+            );
+          }
+          const n = __schemaCamel(name);
+          const norm = def._normalize();
+          // Accept declared fields and `belongsTo` FK column names
+          // (camelCase or snake_case input both resolve via __schemaCamel).
+          let valid = norm.fields.has(n);
+          if (!valid) {
+            for (const [, rel] of norm.relations) {
+              if (rel.kind === 'belongsTo' && __schemaCamel(rel.foreignKey) === n) {
+                valid = true;
+                break;
+              }
+            }
+          }
+          if (!valid) {
+            throw new Error(
+              "schema: markDirty('" + name + "') — '" + n + "' is not a declared field or belongs_to FK on " + (def.name || 'anon')
+            );
+          }
+          this._dirty.add(n);
+          return this;
+        },
+      });
       // toJSON mirrors the instance's own enumerable properties, which by
       // construction are: the primary key, declared fields, @timestamps
       // columns, @softDelete timestamp, @belongs_to FK columns, and any
@@ -435,6 +570,15 @@ class __SchemaDef {
     // Eager-derived fields re-run on hydrate — they're not persisted
     // and must be re-computed from the declared fields now present.
     this._applyEagerDerived(inst);
+    // Capture the as-loaded values so `save()` can emit a column-targeted
+    // UPDATE that only touches fields the caller actually mutated. Two
+    // reasons this matters: (a) avoids a pointless DB round-trip when the
+    // caller didn't change anything, and (b) sidesteps a hard DuckDB FK
+    // limitation — UPDATEs that touch indexed columns (PK / UNIQUE) on a
+    // row referenced by another table's FK are rejected even when the
+    // value isn't really changing. Writing only dirty columns keeps no-op
+    // saves out of the index path entirely.
+    inst._snapshot = __schemaSnapshot(this._normalize(), inst);
     return inst;
   }