tina4ruby 3.13.38 → 3.13.39

data/lib/tina4/metrics.rb

@@ -649,7 +649,10 @@ module Tina4
 
     # Top-level class/module names defined in the file at rel_path (resolved
     # against the last scan root when present). Distinctive names only:
-    # leading-uppercase, longer than 3 chars.
+    # leading-uppercase, longer than 2 chars — so genuine 3-char constants like
+    # ORM (orm.rb) and API (api.rb), which specs reference as `Tina4::ORM` /
+    # `Tina4::API`, are detected as tested instead of being mislabelled
+    # untested. (Was > 3, which silently excluded every 3-char constant.)
     def self._defined_constants(rel_path)
       src_file = if @last_scan_root && !@last_scan_root.empty? && !File.exist?(rel_path)
                    File.join(@last_scan_root, rel_path)
@@ -667,7 +670,7 @@ module Tina4
         m = stripped.match(/\A(?:class|module)\s+([A-Z][A-Za-z0-9_]*)/)
         next unless m
         const = m[1]
-        symbols.add(const) if const.length > 3
+        symbols.add(const) if const.length > 2
       end
       symbols
     end
@@ -702,8 +705,61 @@ module Tina4
       imports
     end
 
-    def self._extract_functions(source, tokens, lines)
+    # Replace the CONTENT of Ruby string literals, regex literals, and comments
+    # with neutral spaces — keeping every line's length and the line count
+    # identical to the original — so decision-point keywords and method-shaped
+    # text that live INSIDE strings/comments are never miscounted. Returns an
+    # array of cleaned lines (chomped) aligned 1:1 with the original lines.
+    #
+    # Ruby's own lexer (Ripper) does the hard parsing: it tags string/heredoc/
+    # regex bodies as :on_tstring_content (and :on_comment, :on_embdoc — the
+    # =begin/=end block-comment body), which we blank out positionally. The
+    # surrounding code structure (def/if/end keywords, operators) is left intact.
+    NOISE_TOKEN_TYPES = %i[
+      on_tstring_content on_comment on_embdoc on_embdoc_beg on_embdoc_end
+    ].freeze
+
+    def self._clean_source(source)
+      lines = source.lines.map(&:chomp)
+      # Mutable per-line character buffers we can blank out by column range.
+      buffers = lines.map(&:dup)
+
+      tokens = begin
+        Ripper.lex(source)
+      rescue StandardError
+        return lines
+      end
+
+      tokens.each do |(pos, type, token)|
+        next unless NOISE_TOKEN_TYPES.include?(type)
+
+        row = pos[0] - 1
+        col = pos[1]
+        # A noise token may span multiple physical lines (heredocs, block
+        # comments, multi-line strings). Blank each covered line segment.
+        token.to_s.each_line.with_index do |seg, offset|
+          line_idx = row + offset
+          next if line_idx.negative? || line_idx >= buffers.length
+
+          buf = buffers[line_idx]
+          # On the token's first line the content starts at `col`; on
+          # continuation lines it starts at column 0.
+          start = offset.zero? ? col : 0
+          seg_len = seg.chomp.length
+          stop = [start + seg_len, buf.length].min
+          (start...stop).each { |c| buf[c] = ' ' } if stop > start
+        end
+      end
+
+      buffers
+    end
+
+    def self._extract_functions(source, _tokens, _lines)
       functions = []
+      # Operate on a neutralised copy: string/regex/comment CONTENT is blanked
+      # so keywords inside them are never read as real code (line numbers, line
+      # count and column widths are preserved).
+      lines = _clean_source(source)
       # Track class/module nesting for method names
       context_stack = []
       i = 0
@@ -718,7 +774,8 @@ module Tina4
           context_stack.push(class_name) unless class_name.empty?
         end
 
-        # Detect method definitions
+        # Detect method definitions — require a real `def ` declaration so a
+        # `def`-shaped substring inside a (now-blanked) string is never a method.
         if stripped.match?(/\Adef\s+/)
           method_match = stripped.match(/\Adef\s+(self\.)?(\S+?)(\(.*\))?\s*$/)
           if method_match
@@ -779,43 +836,73 @@ module Tina4
       functions
     end
 
+    # Keywords that ALWAYS open a block needing a matching `end`.
+    BLOCK_OPENERS = %w[def class module begin case].freeze
+    # Keywords that open a block ONLY in statement-leading position; in trailing
+    # position they are modifiers (`return x if y`) and need no `end`.
+    CONDITIONAL_OPENERS = %w[if unless while until for].freeze
+
+    # Find the line index where the method that starts at `start_index` ends.
+    #
+    # Token-driven (Ripper) so it is immune to the line-regex footguns that made
+    # this over-run to end-of-file (CC 496 on tiny methods):
+    #   * `self.class` — `class` after a `.` is an identifier, not a block opener
+    #     (Ripper tags it :on_ident), so it no longer bumps depth.
+    #   * modifier `if/unless/while/until/for` (`return x if y`) — only counted
+    #     as an opener in statement-LEADING position (first real token of a
+    #     statement), never trailing.
+    #   * `lines` are already string/comment-cleaned, so keywords inside string
+    #     bodies are gone too.
+    # Falls back to the last line only if no matching `end` is found.
     def self._find_method_end(lines, start_index)
-      depth = 0
-      i = start_index
-      base_indent = lines[i].length - lines[i].lstrip.length
+      source = lines[start_index..].join("\n")
+      tokens = begin
+        Ripper.lex(source)
+      rescue StandardError
+        return lines.length - 1
+      end
 
-      while i < lines.length
-        stripped = lines[i].strip
+      depth = 0
+      # A keyword is a block opener only when it leads a statement. Track that:
+      # we are at statement start initially and right after a newline / `;`.
+      at_statement_start = true
+      seen_opener = false
 
-        unless stripped.empty? || stripped.start_with?('#')
-          # Count block openers
-          if stripped.match?(/\b(def|class|module|if|unless|case|while|until|for|begin|do)\b/) &&
-             !stripped.match?(/\bend\b/) &&
-             !stripped.end_with?(' if ', ' unless ', ' while ', ' until ') &&
-             !(stripped.match?(/\bif\b|\bunless\b|\bwhile\b|\buntil\b/) && i != start_index && _is_modifier?(stripped))
+      tokens.each do |(pos, type, token)|
+        case type
+        when :on_kw
+          if BLOCK_OPENERS.include?(token)
             depth += 1
-          end
-
-          if stripped == 'end' || stripped.start_with?('end ') || stripped.start_with?('end;')
+            seen_opener = true
+          elsif token == 'do'
+            depth += 1
+            seen_opener = true
+          elsif CONDITIONAL_OPENERS.include?(token)
+            # Leading => real block opener; trailing => modifier (no end).
+            if at_statement_start
+              depth += 1
+              seen_opener = true
+            end
+          elsif token == 'end'
             depth -= 1
-            return i if depth <= 0
+            if seen_opener && depth <= 0
+              return start_index + (pos[0] - 1)
+            end
           end
+          at_statement_start = false
+        when :on_nl, :on_ignored_nl, :on_semicolon
+          at_statement_start = true
+        when :on_sp, :on_comment, :on_embdoc, :on_embdoc_beg, :on_embdoc_end
+          # whitespace/comments don't change statement-start state
+        else
+          at_statement_start = false
         end
-
-        i += 1
       end
 
       # If we never found the end, return last line
       lines.length - 1
     end
 
-    def self._is_modifier?(line)
-      # A rough check: if the keyword is not at the start of the meaningful content,
-      # it's likely a modifier (e.g., "return x if condition")
-      stripped = line.strip
-      !stripped.match?(/\A(if|unless|while|until)\b/)
-    end
-
     def self._cyclomatic_complexity_from_source(source)
       cc = 1
 

data/lib/tina4/migration.rb

@@ -179,10 +179,12 @@ module Tina4
           rescue
             # Generator may already exist
           end
+          # migration_name is UNIQUE: a migration is "applied" iff a success row
+          # exists, so a re-applied name must never duplicate a tracking row.
           @db.execute(<<~SQL)
             CREATE TABLE #{TRACKING_TABLE} (
               id INTEGER NOT NULL PRIMARY KEY,
-              migration_name VARCHAR(500) NOT NULL,
+              migration_name VARCHAR(500) NOT NULL UNIQUE,
               description VARCHAR(500) DEFAULT '',
               batch INTEGER NOT NULL DEFAULT 1,
               executed_at VARCHAR(50) DEFAULT CURRENT_TIMESTAMP,
@@ -190,10 +192,12 @@ module Tina4
             )
           SQL
         else
+          # migration_name is UNIQUE: a migration is "applied" iff a success row
+          # exists, so a re-applied name must never duplicate a tracking row.
           @db.execute(<<~SQL)
             CREATE TABLE #{TRACKING_TABLE} (
               id INTEGER PRIMARY KEY,
-              migration_name VARCHAR(255) NOT NULL,
+              migration_name VARCHAR(255) NOT NULL UNIQUE,
               description VARCHAR(255) DEFAULT '',
               batch INTEGER NOT NULL DEFAULT 1,
               executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
@@ -224,22 +228,37 @@ module Tina4
       return [] unless Dir.exist?(@migrations_dir)
 
       completed = completed_migrations
-      # Support both .rb and .sql migration files
-      # Accept both 000001_name.sql (sequential) and YYYYMMDDHHMMSS_name.sql (timestamp) patterns
-      Dir.glob(File.join(@migrations_dir, "*.{rb,sql}"))
-         .reject { |f| f.end_with?(".down.sql") }
-         .sort_by { |f| migration_sort_key(File.basename(f)) }
-         .reject { |f| completed.include?(File.basename(f)) }
+      # Support both .rb and .sql migration files. Accept both 000001_name.sql
+      # (sequential) and YYYYMMDDHHMMSS_name.sql (timestamp) patterns. Sort by a
+      # leading numeric/timestamp prefix (numeric-aware) so `9_*` applies before
+      # `10_*` — a plain lexical sort misorders unpadded prefixes ("10" < "9").
+      # Files with no numeric prefix sort after the numbered ones, lexically.
+      files = Dir.glob(File.join(@migrations_dir, "*.{rb,sql}"))
+                 .reject { |f| f.end_with?(".down.sql") }
+                 .sort_by { |f| migration_sort_key(File.basename(f)) }
+
+      # Warn about filenames without a recognized NNNNNN_/timestamp prefix —
+      # their ordering relative to numbered migrations is undefined, a silent
+      # out-of-order-apply footgun.
+      unprefixed = files.map { |f| File.basename(f) }.reject { |n| n =~ /\A\d+[_-]/ }
+      unless unprefixed.empty?
+        Tina4::Log.warning(
+          "Migration file(s) without a numeric/timestamp prefix may apply out of order: " +
+          unprefixed.join(", ")
+        )
+      end
+
+      files.reject { |f| completed.include?(File.basename(f)) }
     end
 
-    # Sort key that handles both 000001_name.sql and 20240315120000_name.sql patterns.
-    # Both are zero-padded numeric prefixes so alphabetical sorting works, but we
-    # extract the prefix explicitly to guarantee correct ordering when mixed.
+    # Numeric-aware sort key so `9_name.sql` sorts before `10_name.sql` (plain
+    # lexical sort puts "10" before "9"). Files with a leading numeric/timestamp
+    # prefix sort first by that number; the rest sort after, lexically.
     def migration_sort_key(filename)
       if filename =~ /\A(\d+)/
-        [$1.to_i, filename]
+        [0, $1.to_i, filename]
       else
-        [0, filename]
+        [1, 0, filename]
       end
     end
 
@@ -247,16 +266,27 @@ module Tina4
       name = File.basename(file)
       Tina4::Log.info("Running migration: #{name}")
       begin
+        # Wrap each migration FILE in its own transaction so a multi-statement
+        # file that fails midway rolls back as a unit. Truly atomic only on
+        # engines with transactional DDL (PostgreSQL); MySQL/Firebird/SQLite
+        # auto-commit DDL, so earlier statements may persist there — keep one
+        # logical change per file.
+        @db.start_transaction
         if file.end_with?(".rb")
           execute_ruby_migration(file, :up)
         else
           execute_sql_file(file)
         end
+        # ROW-EXISTENCE tracking: only a SUCCESS row is ever written. A
+        # migration is "applied" iff a success row exists — failures are never
+        # recorded, nothing is deleted, the file rolls back and we surface the
+        # error. Fix the bad file and re-run.
         _record_migration(name, batch, passed: 1)
+        @db.commit
         { name: name, status: "success" }
       rescue => e
+        @db.rollback rescue nil
         Tina4::Log.error("Migration failed: #{name} - #{e.message}")
-        _record_migration(name, batch, passed: 0)
         { name: name, status: "failed", error: e.message }
       end
     end
@@ -296,6 +326,26 @@ module Tina4
       migration.__send__(direction, @db)
     end
 
+    # Smart/curly quotes — editors, word processors, docs and chat apps silently
+    # convert a straight " to “ ” and a straight ' to ‘ ’ (plus primes ′ ″). Those
+    # characters are NOT valid SQL string/identifier delimiters, so a pasted-in
+    # migration fails to run ("syntax error near …"). Map them back to straight
+    # ASCII quotes. (Real string CONTENTS are unaffected by intent — we only swap
+    # the lookalike code points for their ASCII equivalents.)
+    SMART_QUOTES = {
+      "“" => '"', "”" => '"', "„" => '"', "‟" => '"', "″" => '"', # “ ” „ ‟ ″
+      "‘" => "'", "’" => "'", "‚" => "'", "‛" => "'", "′" => "'"  # ‘ ’ ‚ ‛ ′
+    }.freeze
+    SMART_QUOTE_RE = Regexp.union(SMART_QUOTES.keys)
+
+    # Replace smart/curly quotes with straight ASCII quotes so migration SQL
+    # authored or pasted from an editor/doc actually runs (those code points are
+    # not valid SQL delimiters). Already-straight quotes and ordinary content are
+    # returned byte-for-byte unchanged.
+    def normalize_quotes(sql)
+      sql.gsub(SMART_QUOTE_RE, SMART_QUOTES)
+    end
+
     # Split SQL into individual statements, handling:
     # - $$ delimited stored procedure blocks
     # - // delimited blocks
@@ -303,6 +353,10 @@ module Tina4
     # - Line comments -- ...
     # Matches the Python/Node.js approach: extract blocks first, split on ;, restore blocks.
     def split_sql_statements(sql, delimiter = ";")
+      # Normalize smart/curly quotes to straight ASCII first, so SQL pasted from
+      # an editor/doc (which converts " → “ ” and ' → ‘ ’) actually runs.
+      sql = normalize_quotes(sql)
+
       blocks = []
 
       # Extract $$ ... $$ blocks (stored procedures, triggers, etc.)
@@ -311,8 +365,12 @@ module Tina4
         "__BLOCK_#{blocks.length - 1}__"
       end
 
-      # Extract // ... // blocks
-      processed = processed.gsub(/\/\/(.*?)\/\//m) do
+      # Extract // ... // blocks (stored procedures, triggers, etc.). The `//`
+      # delimiters must NOT be preceded by a colon, so a URL scheme
+      # (`https://…`) or other `://` literal inside a migration is never
+      # captured as an opaque stored-proc block (it would otherwise swallow
+      # everything between two `//` occurrences and skip statement splitting).
+      processed = processed.gsub(/(?<!:)\/\/(.*?)(?<!:)\/\//m) do
         blocks << $~.to_s
         "__BLOCK_#{blocks.length - 1}__"
       end
@@ -348,10 +406,11 @@ module Tina4
       sql = File.read(file)
       statements = split_sql_statements(sql)
       statements.each do |stmt|
-        # Firebird lacks IF NOT EXISTS for ALTER TABLE ADD.
-        # Pre-check the system catalogue so duplicate columns are
-        # silently skipped instead of raising an error.
-        skip_reason = should_skip_for_firebird(stmt)
+        # Idempotency on engines lacking IF NOT EXISTS: Firebird ALTER-TABLE-ADD
+        # (pre-check the system catalogue for a duplicate column), and CREATE
+        # TABLE on Firebird/MSSQL (pre-check the table exists). Only a genuine
+        # already-exists is skipped — every other error still raises.
+        skip_reason = should_skip_for_firebird(stmt) || should_skip_create_table(stmt)
         if skip_reason
           Tina4::Log.info("Migration #{File.basename(file)}: #{skip_reason}")
           next
@@ -398,6 +457,34 @@ module Tina4
       end
     end
 
+    # CREATE TABLE <name> — name may be quoted ("x"), bracketed ([x] MSSQL), or bare.
+    CREATE_TABLE_RE = /\A\s*CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(?:"([^"]+)"|\[([^\]]+)\]|(\w+))/i
+
+    # Make CREATE TABLE idempotent on engines lacking IF NOT EXISTS.
+    #
+    # Firebird and MSSQL do not support `CREATE TABLE IF NOT EXISTS`, so a raw
+    # CREATE in a re-run migration raises "object already exists". When the
+    # target table already exists on those engines, returns a skip reason so the
+    # statement is skipped (mirrors the Firebird ALTER-TABLE-ADD idempotency
+    # guard). SQLite/MySQL/PostgreSQL support IF NOT EXISTS and are left to the
+    # engine. Only a genuine already-exists is skipped — every other error still
+    # raises. Returns nil if the statement should execute normally.
+    def should_skip_create_table(stmt)
+      engine = @db.get_database_type rescue nil
+      return nil unless %w[firebird mssql].include?(engine)
+
+      m = stmt.match(CREATE_TABLE_RE)
+      return nil unless m
+
+      table = m[1] || m[2] || m[3]
+      begin
+        return "Table #{table} already exists, skipping CREATE TABLE" if @db.table_exists?(table)
+      rescue
+        return nil
+      end
+      nil
+    end
+
     def _record_migration(name, batch, passed: 1)
       # Extract description from filename (strip numeric prefix and extension)
       stem = File.basename(name, File.extname(name))

data/lib/tina4/orm.rb

@@ -13,6 +13,26 @@ module Tina4
     name.to_s.gsub(/([A-Z])/) { "_#{$1.downcase}" }.sub(/^_/, "")
   end
 
+  # Singularize a plural relationship name to derive a class name.
+  #
+  # has_many :posts → "Post", has_many :categories → "Category". The old
+  # derivation was a naive sub(/s$/) that turned "categories" into
+  # "Categorie" — a NameError waiting to happen. This handles the common
+  # English plural endings before falling back to stripping a trailing "s".
+  # (When class_name: is passed explicitly, this is never consulted.)
+  def self.singularize(word)
+    s = word.to_s
+    if s =~ /ies\z/i
+      s.sub(/ies\z/i, "y")
+    elsif s =~ /(ss|sh|ch|x|z)es\z/i
+      s.sub(/es\z/i, "")
+    elsif s =~ /s\z/i && s !~ /ss\z/i
+      s.sub(/s\z/i, "")
+    else
+      s
+    end
+  end
+
   class ORM
     include Tina4::FieldTypes
 
@@ -144,7 +164,12 @@ module Tina4
       def has_many(name, class_name: nil, foreign_key: nil)
         relationship_definitions[name] = {
           type: :has_many,
-          class_name: class_name || name.to_s.sub(/s$/, "").split("_").map(&:capitalize).join,
+          # Derive the target class from the (plural) relationship name via a
+          # proper singularizer — "posts" → "Post", "categories" → "Category"
+          # — instead of the naive sub(/s$/) that produced "Categorie". The FK
+          # auto-wire path (foreign_key_field) always passes class_name:
+          # explicitly, so this default only applies to a hand-written has_many.
+          class_name: class_name || Tina4.singularize(name).split("_").map(&:capitalize).join,
           foreign_key: foreign_key
         }
 
@@ -326,9 +351,17 @@ module Tina4
         result[:cnt].to_i
       end
 
+      # Create a new instance, save it, and return it.
+      #
+      # Returns the saved instance on success. v3.13.39: if the underlying #save
+      # fails (validation errors or a driver error), create returns false — it
+      # does NOT hand back a possibly-unsaved instance, so a failed insert can
+      # never masquerade as a success. The failure cause is logged and available
+      # on the (discarded) instance's #get_error via the same path save uses.
+      # Parity with the Python master.
       def create(attributes = {})
         instance = new(attributes)
-        instance.save
+        return false if instance.save == false
         instance
       end
 
@@ -473,6 +506,17 @@ module Tina4
         select_one(sql, [id])
       end
 
+      # Return true if a record with the given primary key exists.
+      #
+      # Cross-framework parity with Python's MyModel.exists(pk_value),
+      # PHP's Model::exists($id), and Node's Model.exists(pk). Honours the
+      # soft-delete filter the same way find_by_id does (it routes through it).
+      # Used by #save to decide INSERT vs UPDATE for natural (non-auto-increment)
+      # primary keys — see the note on #save.
+      def exists(id)
+        !find_by_id(id).nil?
+      end
+
       # Clear the relationship cache on all loaded instances (class-level helper).
       # Useful after bulk operations when you want to force relationship re-loads.
       def clear_rel_cache # -> nil
@@ -536,6 +580,11 @@ module Tina4
     def initialize(attributes = {})
       @persisted = false
       @errors = []
+      # Cause of the most recent failed #save (validation message or DB error).
+      # nil when the most recent save succeeded. Mirrors db.get_error so a caller
+      # that checks `return false unless model.save` can still recover the real
+      # cause via #get_error / #last_error — the failure never vanishes silently.
+      @last_error = nil
       @relationship_cache = {}
       # Accept a JSON object string (parity with Python/PHP/Node):
       #   Widget.new('{"id":1,"name":"alpha"}')
@@ -566,42 +615,137 @@ module Tina4
       end
     end
 
+    # Insert or update. Returns self on success (fluent), false on failure.
+    #
+    # Fails loud, never silent (the same principle db.execute already follows
+    # by raising). On *any* failure path save returns false — keeping the
+    # contract callers rely on (`return false unless model.save`) — but it also
+    # (a) logs the real cause via Tina4::Log.error with model/table context and
+    # (b) records the cause on a retrievable per-model error (#last_error /
+    # #get_error, mirroring db.get_error) plus #errors, so a caller can recover
+    # it after the fact. It never raises and never changes the self/false
+    # return shape. On success it returns self (was `true` pre-v3.13.39 — Ruby
+    # was the sole framework returning a bare boolean here) and clears the
+    # error.
+    #
+    # Two distinct failure paths, both loud:
+    #
+    #   * Validation (v3.13.39): #validate runs FIRST. If it returns errors,
+    #     save records them on @errors + @last_error, logs them, and returns
+    #     false WITHOUT touching the database — an invalid model never reaches
+    #     the driver. (Ruby already enforced validate-on-save; this adds the
+    #     loud log + recoverable last_error to the failure path.)
+    #   * Database (v3.13.39): a driver error (NOT NULL, duplicate PK, missing
+    #     table, …) is rolled back by db.transaction, then captured (db.get_error
+    #     falling back to the exception text) onto @last_error, logged with
+    #     model/table context, and returns false — the cause is no longer
+    #     swallowed silently.
+    #
+    # INSERT vs UPDATE (bug B, parity with the Python master): for a NATURAL
+    # (non-auto-increment) primary key that is set, the decision is made on
+    # whether the ROW EXISTS (via self.class.exists), not on @persisted alone.
+    # Pre-v3.13.39 a re-save of a manually-PK'd record that had @persisted set
+    # would UPDATE — but a freshly built (not-yet-persisted) natural-key record
+    # whose row already existed could double-INSERT, or a `new`-then-`save` of a
+    # natural key would INSERT then a second save UPDATE a phantom. Probing
+    # existence makes the choice correct regardless of @persisted. Auto-increment
+    # PKs keep the legacy @persisted-based decision (a nil PK means "new row,
+    # let the engine assign an id").
     def save
       @errors = []
       @relationship_cache = {} # Clear relationship cache on save
-      validate_fields
-      return false unless @errors.empty?
+
+      # ── validate() is ENFORCED. An invalid model never reaches the driver —
+      # fail loud (record + log), return false. ──
+      validation_errors = validate
+      unless validation_errors.empty?
+        @errors = validation_errors
+        @last_error = validation_errors.join("; ")
+        Tina4::Log.error(
+          "#{self.class.name}.save refused: validation failed — #{@last_error}"
+        )
+        return false
+      end
 
       data = to_db_hash(exclude_nil: true)
       pk = self.class.primary_key_field || :id
       pk_value = __send__(pk)
+      pk_opts = self.class.field_definitions[pk] || {}
+      auto_increment = pk_opts[:auto_increment]
 
-      self.class.db.transaction do |db|
-        if @persisted && pk_value
-          filter = { pk => pk_value }
-          data.delete(pk)
-          # Remove mapped primary key too
-          mapped_pk = self.class.field_mapping[pk.to_s]
-          data.delete(mapped_pk.to_sym) if mapped_pk
-          db.update(self.class.table_name, data, filter)
+      # Decide INSERT vs UPDATE.
+      is_update =
+        if pk_value.nil?
+          false
+        elsif auto_increment
+          # Auto-increment: legacy behaviour — a set PK on a persisted instance
+          # means UPDATE.
+          @persisted ? true : false
         else
-          result = db.insert(self.class.table_name, data)
-          if result[:last_id] && respond_to?("#{pk}=")
-            __send__("#{pk}=", result[:last_id])
+          # Natural key: probe row existence so a re-save never double-inserts
+          # and a first save of a never-seen key still inserts. If the probe
+          # itself fails (e.g. table missing), fall back to INSERT so the caller
+          # sees the real driver error rather than a silent no-op UPDATE.
+          begin
+            self.class.exists(pk_value)
+          rescue StandardError
+            false
           end
-          @persisted = true
         end
+
+      begin
+        self.class.db.transaction do |db|
+          if is_update
+            filter = { pk => pk_value }
+            data.delete(pk)
+            # Remove mapped primary key too
+            mapped_pk = self.class.field_mapping[pk.to_s]
+            data.delete(mapped_pk.to_sym) if mapped_pk
+            db.update(self.class.table_name, data, filter)
+          else
+            result = db.insert(self.class.table_name, data)
+            # Only adopt the engine-assigned id for an auto-increment PK. A
+            # natural-key PK was set by the caller; don't overwrite it with the
+            # driver's last_insert_id (which may be a sequence value that
+            # doesn't apply here).
+            if auto_increment && result[:last_id] && respond_to?("#{pk}=")
+              __send__("#{pk}=", result[:last_id])
+            end
+          end
+        end
+      rescue => e
+        # ── Fail loud, never silent. db.transaction already rolled back and
+        # re-raised. Keep the false return contract, but capture the REAL cause
+        # (prefer db.get_error, which insert/update/execute populate, falling
+        # back to the exception text) on @last_error + @errors so it survives,
+        # and log it with model/table context. ──
+        cause = (self.class.db.get_error rescue nil) || e.message
+        @last_error = cause
+        @errors = [cause]
+        Tina4::Log.error(
+          "#{self.class.name}.save failed for table " \
+          "'#{self.class.table_name}': #{cause}"
+        )
+        return false
       end
-      true
-    rescue => e
-      @errors << e.message
-      false
+
+      @persisted = true
+      @last_error = nil
+      self
     end
 
+    # Delete this record (soft or hard).
+    #
+    # v3.13.39 (bug D): RAISES on a missing primary key, matching #force_delete
+    # (which already raised). Previously delete returned false on a nil PK while
+    # force_delete raised — an inconsistent contract where "couldn't delete" and
+    # "deleted nothing" were indistinguishable on one path but loud on the other.
+    # Both now fail loud: deleting a record with no PK is a programmer error, not
+    # a quiet no-op. Returns true on a successful delete.
     def delete
       pk = self.class.primary_key_field || :id
       pk_value = __send__(pk)
-      return false unless pk_value
+      raise "Cannot delete: no primary key value" unless pk_value
 
       self.class.db.transaction do |db|
         if self.class.soft_delete
@@ -703,6 +847,23 @@ module Tina4
       @errors
     end
 
+    # Cause of the most recent failed #save (validation message or DB error),
+    # or nil when the last save succeeded.
+    def last_error
+      @last_error
+    end
+
+    # Return the cause of the most recent failed #save, or nil.
+    #
+    # Mirrors db.get_error. After save returns false — whether from validation
+    # or a driver error — the real cause is retrievable here (and on
+    # #last_error) so a caller using the `return false unless model.save`
+    # contract can still surface it. Cleared to nil on a successful save.
+    # Cross-framework parity with Python/PHP/Node get_error().
+    def get_error
+      @last_error
+    end
+
     # Convert to hash using Ruby attribute names.
     # Optionally include relationships via the include keyword.
     # case: "camel" converts snake_case keys to camelCase (parity with