tina4-nodejs 3.13.132 → 3.13.134

package/CLAUDE.md

@@ -13,13 +13,13 @@ Even if the skill text is not currently loaded, these are non-negotiable:
 
 The full discipline lives in `.claude/skills/tina4-maintainer/SKILL.md`; this block is the always-on floor.
 
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.132)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.134)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.13.132 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.134 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 
@@ -172,6 +172,7 @@ Database layer with auto-CRUD generation, seeding, fake data, and SQL translatio
 - `sqlTranslator.ts` — Cross-engine SQL translator (`SQLTranslator`) and TTL query cache (`QueryCache`)
 - **Instance methods:** `save(): this|false` (fluent, false on failure), `delete()`, `forceDelete()`, `restore()`, `load(sql, params?, include?): boolean`, `validate(): string[]`, `toDict(include?)`, `toAssoc(include?)`, `toObject()`, `toArray(): unknown[]`, `toList()`, `toJson(include?)`, `hasOne(class, fk)`, `hasMany(class, fk, limit?, offset?)`, `belongsTo(class, fk)`
 - **Static methods:** `find(id, include?)`, `findById(id, include?)`, `findOrFail(id)`, `create(data)`, `all(limit=100, offset=0, include?, orderBy?)`, `select(sql, params?, limit=100, offset=0)`, `selectOne(sql, params?, include?)`, `where(conditions, params?, limit=100, offset=0, include?, orderBy?)`, `count(conditions?, params?)`, `withTrashed(conditions?, params?, limit=100, offset=0)`, `scope(name, filterSql, params?)` (registers reusable method), `createTable()`, `query()`, `_processForeignKeys()`, `_applyFkRegistry()`
+- **ModelCollection (ADR-0064):** `where`, `select`, `find` (filter form), `all`, and `withTrashed` return a `ModelCollection<T>` (extends `Array<T>`, so `Array.isArray` stays true and iterate/index/`.length`/`JSON.stringify` are unchanged) that ALSO carries the filter total, independent of limit/offset: `rows.getTotalRecords()` (e.g. 250, reuses the query COUNT -- zero extra queries) and `rows.toPaginate()` (`{ records, total, page, per_page, total_pages, limit, offset }`). A method, not a `.count` property. Single-record finders (`findById`, `selectOne`) are unchanged.
 - **Foreign key auto-wire (declarative, read-side-only):** Declare a field with `type: "foreignKey"` and `references: "ModelName"` to auto-wire both `belongsTo` on the declaring model and `hasMany` on the referenced model. Optional `relatedName` overrides the has-many key. Models must be registered via `BaseModel.registerModel(name, class)` for name-based resolution. Example: `author_id: { type: "foreignKey", references: "Author", relatedName: "posts" }` attaches LAZY accessors on both sides — `await post.author` (belongsTo) and `await author.posts` (hasMany) resolve on attribute access (async, cached), and `include: ["posts"]` on `find`/`all`/`where` eager-loads them in ONE query per relation. A soft-deleted child is excluded from traversal, and the has-many read is uncapped. The auto-wire emits NO DB-level FK / ON DELETE clause (REL-DEC-01, read-side-only): referential integrity is the migration/DDL's job, so deleting a parent does not cascade to children at the engine level. (Before 3.13.99 the declarative accessors did not attach and lazy load did not exist — only the imperative `post.belongsTo(Author, "author_id")` / `author.hasMany(Post, "author_id")` worked.)
 - QueryBuilder supports `toMongo()` for generating MongoDB query documents from the same fluent API
 - `getNextId(table: string, pkColumn?: string, generatorName?: string): Promise<number>` — Race-safe ID generation using atomic sequence table (`tina4_sequences`). SQLite/MySQL/MSSQL use `tina4_sequences` with atomic UPDATE+SELECT. PostgreSQL auto-creates sequences if missing. Firebird uses existing generators (unchanged).
@@ -1412,7 +1413,7 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 
 ## v3 Features Summary
 
-- **98 built-in features**, zero third-party dependencies
+- **140 cataloged features**, zero third-party dependencies
 - **7,537 tests** passing, 0 failed, **0 skipped** across 262 files (typecheck exit 0) - measured 2026-08-06 on the lab host (Ubuntu 24.04.4 LTS x86_64, Node v24.18.0) against live services with TINA4_REQUIRE_SERVICES=1. **Firebird runs on the lab but IS excluded from the require-services gate** - `test/_serviceGate.ts` lists `firebird` in `EXCLUDED_KEYWORDS` because GitHub CI provisions no Firebird, so a Firebird skip has to stay green there; the lab provisions a live Firebird 5 (`TINA4_TEST_FIREBIRD_URL`) and `test/firebird*.test.ts` (plus the feature-12 `test/firebirdProviderContract.test.ts`) runs against it. Those are two different things: real-Firebird coverage is enforced on the LAB, not by CI (FB-GATE-EXCLUDED). `node-firebird` is an optionalDependency of `@tina4/orm`, not a devDependency. The last six skips are closed, each by giving it the environment its condition needs rather than by relaxing what it asserts: the four missing-driver cases run in a child process that genuinely cannot resolve the driver (the source is copied out of the repo to a tree with no `node_modules` above it and run with plain `node` - `test/_driverlessTree.ts`, no resolver shim); the strict-mode write failure drops the effective uid so a 0400 file really denies root; and the RabbitMQ default-config round-trip clears the per-framework isolation overrides for that one case so "default" means the default. Every one was proven able to FAIL by mutating the code it guards.
 - **Race-safe `getNextId()`** with atomic sequence table (`tina4_sequences`) for SQLite/MySQL/MSSQL; PostgreSQL auto-creates sequences
 - **Frond template engine optimizations**: pre-compiled regexes, lazy loop context (copy-on-write), filter chain caching, path split caching, inline common filters (11-15% speedup)

package/README.md

@@ -108,7 +108,7 @@ Benchmarked with `wrk`: 5,000 requests, 50 concurrent, median of 3 runs:
 | Raw `node:http` | 91,110 | 0 | 1 |
 | **Tina4 Node.js** | **84,771** | 0 | 55 |
 
-Tina4 Node.js runs at **93% of raw Node.js speed** while providing 98 built-in features, a zero-overhead architecture.
+Tina4 Node.js runs at **93% of raw Node.js speed** while providing 140 cataloged features, a zero-overhead architecture.
 
 **Across all 4 Tina4 implementations:**
 
@@ -122,7 +122,7 @@ Tina4 Node.js runs at **93% of raw Node.js speed** while providing 98 built-in f
 
 ## Cross-Framework Parity
 
-Tina4 ships identical features across four languages: same architecture, same conventions, same 98 features:
+Tina4 ships identical features across four languages: same architecture, same conventions, the same 140 cataloged features:
 
 | | Python | PHP | Ruby | Node.js |
 |---|--------|-----|------|---------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.132",
+  "version": "3.13.134",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - native TypeScript conventions and shared Tina4 contracts",
   "keywords": [