feat(framework)!: immutable queries and automatic row schemas (v5)

[andrewzolotukhin]

Original request

Expand this PR into the approved breaking release: make Framework query builders immutable, infer projection-aware row schemas automatically, migrate in-repository consumers, and major-bump every published Framework package. Keep this PR against development. Framework is an independent, application-agnostic project. Current API documentation is separate from v4.x-to-v5 migration guidance.

What changed

• Canonical immutable table, aliased, polymorphic and ORM query APIs. Retaining a configured branch no longer changes its source or siblings. SQL stays lazy; metadata access does not execute queries.
• Automatic rowSchema/variantRowSchemas, replace-on-select projections, typed predicates and mapped/nested JSON references, aggregates, ordering and pagination.
• Synchronous, return-required Framework scopes/groups/relation customizers with ownership checks. Default scopes are captured once; caller OR predicates cannot bypass default visibility. Raw Knex callbacks remain an explicit mutable boundary.
• Explicit { output } object schemas for opaque raw SELECTs; captured SQL/bindings; one output parse per row.
• Consistent read/returning-write/reload representation: exact decimal/bigint strings, Date, SQL null. Projection/raw results stay detached; full ORM entities retain identity tracking and mutable save workflows. Added variant page tracking, CTI exact-key/update coverage, and rollback-safe generated IDs/versions.
• Updated demo consumers, README examples, JSDoc, documentation pages and the v5 migration guide. Repaired stale demo attachment test setup and malformed telemetry-test syntax; added an optional installed-browser path for local QA. Manual QA also found and fixed an admin-only directory lookup that signed regular users out of the todo detail page; the browser test now waits for that page to finish loading.
• A major changeset for all 19 published packages, retaining the existing fixed release group. Isolated release simulation produced 5.0.0 for all 19, with all 60 internal dependency/peer ranges or workspace links compatible. No versions were published.

Reasoning

Immutability prevents the query's runtime shape from drifting away from its inferred type or an already-registered mapper. Reusable base queries retain predictable types and runtime shapes. Full entity writes remain separate from projections; raw SQL must declare the contract the Framework cannot infer. This deliberately requires consumers to retain returned builders and migrate together.

Native Knex itself is not made immutable. The private SQL/write planner remains internal; the exported Framework query surface is immutable. PostgreSQL is the integration-tested dialect for graph/precision behavior.

Migrating from v4.x to v5

Remove .withRowSchema() calls and retain each configured query instead of relying on mutation. Use explicit output contracts instead of raw base-query overloads. The migration guides contain historical API comparisons; current READMEs, examples and website guides describe the supported API directly.

Documentation follow-up

Removed consumer-application references from package changelogs and PR text while preserving the external website showcase link. Added repository guidance for application-neutral examples and current-API documentation. Removed obsolete variant examples and updated the immutable relation-customizer example. API behavior and deprecation annotations are unchanged.

Blog post

Skipped per the approved scope: this is a breaking library API migration, documented in package READMEs, JSDoc, the docs site and a dedicated migration guide instead of a separate product blog post.

Screenshots / preview evidence

This repository does not provision a hosted PR preview. Browser QA used the local docs site (localhost:3201) and demo (127.0.0.1:5173) with an isolated QA database. Screenshots below are local QA evidence, not a hosted deployment.

Validation

• npm run lint — passed.
• npm run build — passed, all 21 workspace build tasks.
• npm run test — passed again for this documentation update: 206 files, 4,313 tests; no type errors.
• npm run test:queries:integration — passed: 53 PostgreSQL tests.
• npx tsc --noEmit -p libs/knex-schema/tsconfig.typecheck.json — passed.
• npm run typecheck:schema-site and npm run typecheck:docs-site — passed.
• npm run docs — passed, zero errors; cross-package TypeDoc warnings remain.
• Demo API/UI regression suite — 49 tests passed across 13 files on the implementation commit, using a temporary local config that bypasses Docker orchestration and excludes the two telemetry tests. Exercises auth, CRUD, attachments, activity, batching, live updates, error handling and browser flows. Not rerun for this documentation-only follow-up; no demo behavior changed. This is not a claim that the full Docker/SigNoz suite ran.
• Browser inspection of knex-schema/ORM documentation and manual registration, create/read/detail demo flow — passed after repairing the admin-only picker lookup; no browser errors recorded. Local backend log review found only the deliberately triggered errors from resilience/error-demo tests.
• Documentation follow-up browser QA — query, form, cache-key and schema-validation pages rendered successfully on the local documentation sites; current API wording and examples verified, with no browser JavaScript errors. Repository-wide reference audit found only the allowed website showcase link; PR text is application-neutral.
• Release simulation — all 19 packages major, all internal consumers compatible with the simulated release.
• GitHub required checks — both passed for documentation follow-up commit ff6a30ec: Lint, Build & Test (Node 24) and PostgreSQL Query Integration (run).
• SigNoz/ClickHouse verification — skipped for this documentation-only follow-up. The implementation's telemetry check was also unavailable because of occupied ports, uncached collector images and limited disk space. No unrelated services or volumes were stopped/reset. Telemetry is not verified by the local log review.

No merge, npm publication or production deployment has been performed.