@quereus/quereus 2.9.0 → 3.0.0

package/README.md

@@ -1,222 +1,224 @@
-# Quereus - A TypeScript SQL Query Processor
-
-<img src="../../docs/images/Quereus_colored_wide.svg" alt="Quereus Logo" height="150">
-
-Quereus is a feature-complete SQL query processor specifically designed for efficient in-memory data processing with a strong emphasis on the **virtual table** interface. It provides rich SQL query and constraint capabilities (joins, aggregates, subqueries, CTEs, window functions, constraints) over data sources exposed via the virtual table mechanism. Quereus features a modern type system with temporal types, JSON support, and plugin-extensible custom types. It has no persistent file storage, though one could be built as a virtual table module.
-
-## Project Goals
-
-*   **Virtual Table Centric** — provide a robust and flexible virtual table API as the primary means of interacting with data sources. All tables are virtual tables.
-*   **In-Memory Default** — includes a comprehensive in-memory virtual table implementation (`MemoryTable`) with support for transactions and savepoints.
-*   **Modern Type System** — extensible logical/physical type separation with built-in temporal types (DATE, TIME, DATETIME), native JSON type with deep equality comparison, and plugin support for custom types. See [Type System Documentation](../../docs/types.md).
-*   **TypeScript & Modern JS** — leverage TypeScript's type system and modern JavaScript features and idioms.
-*   **Async VTab Operations** — virtual table data operations (reads/writes) are asynchronous. Cursors are implemented as async iterables.
-*   **Cross-Platform** — target diverse Javascript runtime environments, including Node.js, browser, and React Native. Plugin loading (via `@quereus/plugin-loader`) uses dynamic `import()` and is not compatible with React Native; use static imports for RN.
-*   **Minimal Dependencies** — avoid heavy external dependencies where possible.
-*   **SQL Compatibility** — comprehensive support for modern SQL features including joins, window functions, subqueries, CTEs, constraints, views, and advanced DML/DDL operations.
-*   **Key-Based Addressing** — all tables are addressed by their defined Primary Key. The concept of a separate, implicit `rowid` for addressing rows is not used.
-*   **Third Manifesto Friendly** — embraces some of the principles of the [Third Manifesto](https://www.dcs.warwick.ac.uk/~hugh/TTM/DTATRM.pdf), such as allowing for empty keys. Utilizes algebraic planning.
-
-## Quick Start
-
-```typescript
-import { Database } from '@quereus/quereus';
-
-const db = new Database();
-
-// Create a table and insert data
-await db.exec("create table users (id integer primary key, name text, email text)");
-await db.exec("insert into users values (1, 'Alice', 'alice@example.com')");
-
-// Query returns objects: { id: 1, name: 'Alice', email: 'alice@example.com' }
-const user = await db.get("select * from users where id = ?", [1]);
-console.log(user.name); // "Alice"
-
-// Iterate over multiple rows
-for await (const row of db.eval("select * from users")) {
-  console.log(row.name);
-}
-```
-
-### Reactive Patterns with Event Hooks
-
-```typescript
-import { Database } from '@quereus/quereus';
-
-const db = new Database();
-
-// Subscribe to data changes at the database level
-db.onDataChange((event) => {
-  console.log(`${event.type} on ${event.tableName} (module: ${event.moduleName})`);
-  if (event.remote) {
-    console.log('Change came from remote sync');
-  }
-  if (event.type === 'update') {
-    console.log('Changed columns:', event.changedColumns);
-  }
-});
-
-// Subscribe to schema changes
-db.onSchemaChange((event) => {
-  console.log(`${event.type} ${event.objectType}: ${event.objectName}`);
-});
-
-// Events fire after commit
-await db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)");
-// Output: create table: users
-
-await db.exec("INSERT INTO users VALUES (1, 'Alice')");
-// Output: insert on users (module: memory)
-```
-
-The database-level event system aggregates events from all modules automatically. Events are batched within transactions and delivered only after successful commit.
-
-SQL values use native JavaScript types (`string`, `number`, `bigint`, `Uint8Array`, `null`). Temporal types are ISO 8601 strings. Results stream as async iterators.
-
-See the [Usage Guide](../../docs/usage.md) for complete API reference and [Module Authoring Guide](../../docs/module-authoring.md) for event system details.
-
-## Platform Support & Storage
-
-Quereus runs on any JavaScript runtime. For persistent storage, platform-specific plugins provide the `store` virtual table module:
-
-### Node.js
-
-Use [`@quereus/plugin-leveldb`](../quereus-plugin-leveldb/) for LevelDB-based persistent storage with full transaction isolation. Each table becomes a subdirectory under `basePath`:
-
-```typescript
-import { Database, registerPlugin } from '@quereus/quereus';
-import leveldbPlugin from '@quereus/plugin-leveldb/plugin';
-
-const db = new Database();
-await registerPlugin(db, leveldbPlugin, { basePath: './data' }); // ./data/users/, ./data/orders/, etc.
-
-await db.exec(`create table users (id integer primary key, name text) using store`);
-
-// Full transaction isolation enabled by default
-await db.exec('BEGIN');
-await db.exec(`INSERT INTO users VALUES (1, 'Alice')`);
-const user = await db.get('SELECT * FROM users WHERE id = 1'); // Sees uncommitted insert
-await db.exec('COMMIT');
-```
-
-### Browser
-
-Use [`@quereus/plugin-indexeddb`](../quereus-plugin-indexeddb/) for IndexedDB-based persistent storage with cross-tab sync and full transaction isolation. All tables share one IndexedDB database:
-
-```typescript
-import { Database, registerPlugin } from '@quereus/quereus';
-import indexeddbPlugin from '@quereus/plugin-indexeddb/plugin';
-
-const db = new Database();
-await registerPlugin(db, indexeddbPlugin, { databaseName: 'myapp' }); // IndexedDB database name
-
-await db.exec(`create table users (id integer primary key, name text) using store`);
-```
-
-### React Native
-
-Use [`@quereus/plugin-react-native-leveldb`](../quereus-plugin-react-native-leveldb/) for fast LevelDB storage with full transaction isolation. Each table becomes a separate LevelDB database with a name prefix:
-
-```typescript
-import { LevelDB, LevelDBWriteBatch } from 'react-native-leveldb';
-import { Database, registerPlugin } from '@quereus/quereus';
-import leveldbPlugin from '@quereus/plugin-react-native-leveldb/plugin';
-
-const db = new Database();
-await registerPlugin(db, leveldbPlugin, {
-  openFn: LevelDB.open,
-  WriteBatch: LevelDBWriteBatch,
-  databaseName: 'myapp'  // creates myapp_users, myapp_orders, etc.
-});
-
-await db.exec(`create table users (id integer primary key, name text) using store`);
-```
-
-**Note:** React Native requires runtime polyfills and static plugin loading. See the [plugin README](../quereus-plugin-react-native-leveldb/) for setup details.
-
-**Required polyfills:**
-- `structuredClone` (Quereus uses it internally)
-- `TextEncoder` / `TextDecoder` (used by store plugins)
-- `Symbol.asyncIterator` (required for async-iterable support; Quereus has a Hermes workaround for AsyncGenerator iterables, but the symbol must exist)
-
-### NativeScript
-
-Use [`@quereus/plugin-nativescript-sqlite`](../quereus-plugin-nativescript-sqlite/) for SQLite-based storage with full transaction isolation. All tables share one SQLite database file:
-
-```typescript
-import { openOrCreate } from '@nativescript-community/sqlite';
-import { Database, registerPlugin } from '@quereus/quereus';
-import sqlitePlugin from '@quereus/plugin-nativescript-sqlite/plugin';
-
-const sqliteDb = openOrCreate('myapp.db');  // SQLite database file
-const db = new Database();
-await registerPlugin(db, sqlitePlugin, { db: sqliteDb });
-
-await db.exec(`create table users (id integer primary key, name text) using store`);
-```
-
-See [Store Documentation](../../docs/store.md) for the storage architecture and custom backend implementation.
-
-## Documentation
-
-**Architecture deep dive:** [Architecture](../../docs/architecture.md) — the pipeline (parser → planner → runtime), source layout, extension patterns, design decisions, constraints model, and testing strategy. Start here if you're working on the engine itself.
-
-**User & operator docs:**
-* [Usage Guide](../../docs/usage.md) — complete API reference (type mappings, parameter binding, logging, tracing, transactions)
-* [SQL Reference Guide](../../docs/sql.md) — SQL syntax (includes Declarative Schema)
-* [Schema Management](../../docs/schema.md) — SchemaManager API, change events, key types, DDL generation
-* [Type System](../../docs/types.md) — logical/physical types, temporal types, JSON, custom types
-* [Functions](../../docs/functions.md) — built-in scalar, aggregate, window, and JSON functions
-* [Memory Tables](../../docs/memory-table.md) — built-in MemoryTable module
-* [Module Authoring](../../docs/module-authoring.md) — virtual table module development and event system
-* [Date/Time Handling](../../docs/datetime.md) — temporal parsing, functions, and ISO 8601 formats
-* [Runtime](../../docs/runtime.md) — instruction-based execution and opcodes
-* [Error Handling](../../docs/errors.md) — error types and status codes
-* [Plugin System](../../docs/plugins.md) — virtual tables, functions, and collations
-* [Optimizer](../../docs/optimizer.md) / [Optimizer Conventions](../../docs/optimizer-conventions.md)
-* [TODO List](../../docs/todo.md) — planned features
-
-### Plugin Development
-
-Quereus exports all critical utilities needed for plugin and module development:
-
-* **Comparison Functions** — `compareSqlValues`, `compareRows`, `compareTypedValues`, `createTypedComparator` — match Quereus SQL semantics in custom implementations
-* **Coercion Utilities** — `tryCoerceToNumber`, `coerceForAggregate` — handle type coercion for aggregates and arithmetic
-* **Collation Support** — `registerCollation`, `getCollation`, built-in collations (`BINARY_COLLATION`, `NOCASE_COLLATION`, `RTRIM_COLLATION`)
-* **Type System** — full access to logical types, validation, and parsing utilities
-* **Event Hooks** — `VTableEventEmitter` interface for mutation and schema change events; enable reactive patterns, caching, and replication
-* **DDL Generation** — `generateTableDDL(tableSchema, db?)`, `generateIndexDDL(indexSchema, tableSchema, db?)` — canonical `CREATE TABLE` / `CREATE INDEX` output from runtime schema objects. With a `Database`, matches session defaults (schema qualification, `default_column_nullability`, `default_vtab_module`/`default_vtab_args`) for readable output; without one, emits fully-qualified, explicitly-annotated DDL safe for cross-session persistence. See [Schema Management — DDL Generation](../../docs/schema.md#ddl-generation).
-
-See the [Plugin System documentation](../../docs/plugins.md#comparison-and-coercion-utilities) for complete API reference and examples.
-
-## Current Status
-
-Quereus is a feature-complete SQL query processor with a modern planner and instruction-based runtime architecture. The engine successfully handles complex SQL workloads including joins, window functions, subqueries, CTEs, constraints, and comprehensive DML/DDL operations.
-
-**Current capabilities include:**
-*   **Modern Type System** — temporal types (DATE, TIME, DATETIME), JSON with deep equality, plugin-extensible custom types
-*   **Complete JOIN support** — INNER, LEFT, RIGHT, CROSS, SEMI, and ANTI joins with proper NULL padding
-*   **Advanced window functions** — ranking, aggregates, and frame specifications
-*   **Full constraint system** — NOT NULL, CHECK, FOREIGN KEY, and CREATE ASSERTION. Row-level constraints that reference other tables are automatically deferred to COMMIT. The `committed.tablename` pseudo-schema provides read-only access to pre-transaction state for transition constraints (e.g., "balance may not decrease"). See [Architecture — Constraints](../../docs/architecture.md#constraints).
-*   **Comprehensive subqueries** — scalar, correlated, EXISTS, and IN subqueries
-*   **Relational orthogonality** — INSERT/UPDATE/DELETE with RETURNING can be used as table sources
-*   **Complete set operations** — UNION, INTERSECT, EXCEPT with proper deduplication
-*   **DIFF (symmetric difference)** — `A diff B` equals `(A except B) union (B except A)`, handy for table equality checks via `not exists(A diff B)`
-*   **Robust transaction support** — multi-level savepoints and rollback. See [Usage Guide](../../docs/usage.md#transactions) for details
-*   **Rich built-in function library** — scalar, aggregate, window, JSON, and date/time functions
-*   **Rule-based optimizer** — constant folding, caching, streaming aggregation, bloom-join selection, and correlated subquery decorrelation. See [Architecture — Optimizer](../../docs/architecture.md#optimizer).
-
-[TODO List](../../docs/todo.md) has remaining priorities.
-
-## Supported Built-in Functions
-
-*   **Scalar** — `lower`, `upper`, `length`, `substr`/`substring`, `abs`, `round`, `coalesce`, `nullif`, `like`, `glob`, `typeof`
-*   **Aggregate** — `count`, `sum`, `avg`, `min`, `max`, `group_concat`, `json_group_array`, `json_group_object`
-*   **Window Functions** — complete implementation with `row_number`, `rank`, `dense_rank`, `ntile` (ranking); `count`, `sum`, `avg`, `min`, `max` with OVER clause (aggregates); full frame specification support (`ROWS BETWEEN`, `UNBOUNDED PRECEDING/FOLLOWING`); `NULLS FIRST/LAST` ordering
-*   **Date/Time** — `date`, `time`, `datetime`, `julianday`, `strftime` (supports common formats and modifiers), `epoch_s`, `epoch_ms`, `epoch_s_frac` (Unix epoch conversions with strict parsing)
-*   **JSON** — `json_valid`, `json_schema`, `json_type`, `json_extract`, `json_quote`, `json_array`, `json_object`, `json_insert`, `json_replace`, `json_set`, `json_remove`, `json_array_length`, `json_patch`
-*   **Query Analysis** — `query_plan`, `scheduler_program`, `execution_trace` (debugging and performance analysis)
-
-## Testing
-
-Tests live in `test/*.spec.ts`, driven by Mocha with ts-node/esm. Run with `yarn test`. Quereus uses SQL logic tests (primary), property-based tests, performance sentinels, unit tests, and a benchmark suite — see [Architecture — Testing Strategy](../../docs/architecture.md#testing-strategy) for details.
+# Quereus - A TypeScript SQL Query Processor
+
+<img src="../../docs/images/Quereus_colored_wide.svg" alt="Quereus Logo" height="150">
+
+Quereus is a feature-complete SQL query processor specifically designed for efficient in-memory data processing with a strong emphasis on the **virtual table** interface. It provides rich SQL query and constraint capabilities (joins, aggregates, subqueries, CTEs, window functions, constraints) over data sources exposed via the virtual table mechanism. Quereus features a modern type system with temporal types, JSON support, and plugin-extensible custom types. It has no persistent file storage, though one could be built as a virtual table module.
+
+## Project Goals
+
+*   **Virtual Table Centric** — provide a robust and flexible virtual table API as the primary means of interacting with data sources. All tables are virtual tables.
+*   **In-Memory Default** — includes a comprehensive in-memory virtual table implementation (`MemoryTable`) with support for transactions and savepoints.
+*   **Modern Type System** — extensible logical/physical type separation with built-in temporal types (DATE, TIME, DATETIME), native JSON type with deep equality comparison, and plugin support for custom types. See [Type System Documentation](../../docs/types.md).
+*   **TypeScript & Modern JS** — leverage TypeScript's type system and modern JavaScript features and idioms.
+*   **Async VTab Operations** — virtual table data operations (reads/writes) are asynchronous. Cursors are implemented as async iterables.
+*   **Cross-Platform** — target diverse Javascript runtime environments, including Node.js, browser, and React Native. Plugin loading (via `@quereus/plugin-loader`) uses dynamic `import()` and is not compatible with React Native; use static imports for RN.
+*   **Minimal Dependencies** — avoid heavy external dependencies where possible.
+*   **SQL Compatibility** — comprehensive support for modern SQL features including joins, window functions, subqueries, CTEs, constraints, views, and advanced DML/DDL operations.
+*   **Key-Based Addressing** — all tables are addressed by their defined Primary Key. The concept of a separate, implicit `rowid` for addressing rows is not used.
+*   **Third Manifesto Friendly** — embraces some of the principles of the [Third Manifesto](https://www.dcs.warwick.ac.uk/~hugh/TTM/DTATRM.pdf), such as allowing for empty keys. Utilizes algebraic planning.
+
+## Quick Start
+
+```typescript
+import { Database } from '@quereus/quereus';
+
+const db = new Database();
+
+// Create a table and insert data
+await db.exec("create table users (id integer primary key, name text, email text)");
+await db.exec("insert into users values (1, 'Alice', 'alice@example.com')");
+
+// Query returns objects: { id: 1, name: 'Alice', email: 'alice@example.com' }
+const user = await db.get("select * from users where id = ?", [1]);
+console.log(user.name); // "Alice"
+
+// Iterate over multiple rows
+for await (const row of db.eval("select * from users")) {
+  console.log(row.name);
+}
+```
+
+### Reactive Patterns with Event Hooks
+
+```typescript
+import { Database } from '@quereus/quereus';
+
+const db = new Database();
+
+// Subscribe to data changes at the database level
+db.onDataChange((event) => {
+  console.log(`${event.type} on ${event.tableName} (module: ${event.moduleName})`);
+  if (event.remote) {
+    console.log('Change came from remote sync');
+  }
+  if (event.type === 'update') {
+    console.log('Changed columns:', event.changedColumns);
+  }
+});
+
+// Subscribe to schema changes
+db.onSchemaChange((event) => {
+  console.log(`${event.type} ${event.objectType}: ${event.objectName}`);
+});
+
+// Events fire after commit
+await db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)");
+// Output: create table: users
+
+await db.exec("INSERT INTO users VALUES (1, 'Alice')");
+// Output: insert on users (module: memory)
+```
+
+The database-level event system aggregates events from all modules automatically. Events are batched within transactions and delivered only after successful commit.
+
+SQL values use native JavaScript types (`string`, `number`, `bigint`, `Uint8Array`, `null`). Temporal types are ISO 8601 strings. Results stream as async iterators.
+
+See the [Usage Guide](../../docs/usage.md) for complete API reference and [Module Authoring Guide](../../docs/module-authoring.md) for event system details.
+
+## Platform Support & Storage
+
+Quereus runs on any JavaScript runtime. For persistent storage, platform-specific plugins provide the `store` virtual table module:
+
+### Node.js
+
+Use [`@quereus/plugin-leveldb`](../quereus-plugin-leveldb/) for LevelDB-based persistent storage with full transaction isolation. Each table becomes a subdirectory under `basePath`:
+
+```typescript
+import { Database, registerPlugin } from '@quereus/quereus';
+import leveldbPlugin from '@quereus/plugin-leveldb/plugin';
+
+const db = new Database();
+await registerPlugin(db, leveldbPlugin, { basePath: './data' }); // ./data/users/, ./data/orders/, etc.
+
+await db.exec(`create table users (id integer primary key, name text) using store`);
+
+// Full transaction isolation enabled by default
+await db.exec('BEGIN');
+await db.exec(`INSERT INTO users VALUES (1, 'Alice')`);
+const user = await db.get('SELECT * FROM users WHERE id = 1'); // Sees uncommitted insert
+await db.exec('COMMIT');
+```
+
+### Browser
+
+Use [`@quereus/plugin-indexeddb`](../quereus-plugin-indexeddb/) for IndexedDB-based persistent storage with cross-tab sync and full transaction isolation. All tables share one IndexedDB database:
+
+```typescript
+import { Database, registerPlugin } from '@quereus/quereus';
+import indexeddbPlugin from '@quereus/plugin-indexeddb/plugin';
+
+const db = new Database();
+await registerPlugin(db, indexeddbPlugin, { databaseName: 'myapp' }); // IndexedDB database name
+
+await db.exec(`create table users (id integer primary key, name text) using store`);
+```
+
+### React Native
+
+Use [`@quereus/plugin-react-native-leveldb`](../quereus-plugin-react-native-leveldb/) for fast LevelDB storage with full transaction isolation. Each table becomes a separate LevelDB database with a name prefix:
+
+```typescript
+import { LevelDB, LevelDBWriteBatch } from 'react-native-leveldb';
+import { Database, registerPlugin } from '@quereus/quereus';
+import leveldbPlugin from '@quereus/plugin-react-native-leveldb/plugin';
+
+const db = new Database();
+await registerPlugin(db, leveldbPlugin, {
+  openFn: LevelDB.open,
+  WriteBatch: LevelDBWriteBatch,
+  databaseName: 'myapp'  // creates myapp_users, myapp_orders, etc.
+});
+
+await db.exec(`create table users (id integer primary key, name text) using store`);
+```
+
+**Note:** React Native requires runtime polyfills and static plugin loading. See the [plugin README](../quereus-plugin-react-native-leveldb/) for setup details.
+
+**Required polyfills:**
+- `structuredClone` (Quereus uses it internally)
+- `TextEncoder` / `TextDecoder` (used by store plugins)
+- `Symbol.asyncIterator` (required for async-iterable support; Quereus has a Hermes workaround for AsyncGenerator iterables, but the symbol must exist)
+
+### NativeScript
+
+Use [`@quereus/plugin-nativescript-sqlite`](../quereus-plugin-nativescript-sqlite/) for SQLite-based storage with full transaction isolation. All tables share one SQLite database file:
+
+```typescript
+import { openOrCreate } from '@nativescript-community/sqlite';
+import { Database, registerPlugin } from '@quereus/quereus';
+import sqlitePlugin from '@quereus/plugin-nativescript-sqlite/plugin';
+
+const sqliteDb = openOrCreate('myapp.db');  // SQLite database file
+const db = new Database();
+await registerPlugin(db, sqlitePlugin, { db: sqliteDb });
+
+await db.exec(`create table users (id integer primary key, name text) using store`);
+```
+
+See [Store Documentation](../../docs/store.md) for the storage architecture and custom backend implementation.
+
+## Documentation
+
+**Architecture deep dive:** [Architecture](../../docs/architecture.md) — the pipeline (parser → planner → runtime), source layout, extension patterns, design decisions, constraints model, and testing strategy. Start here if you're working on the engine itself.
+
+**User & operator docs:**
+* [Usage Guide](../../docs/usage.md) — complete API reference (type mappings, parameter binding, logging, tracing, transactions)
+* [SQL Reference Guide](../../docs/sql.md) — SQL syntax (includes Declarative Schema)
+* [Schema Management](../../docs/schema.md) — SchemaManager API, change events, key types, DDL generation
+* [Type System](../../docs/types.md) — logical/physical types, temporal types, JSON, custom types
+* [Functions](../../docs/functions.md) — built-in scalar, aggregate, window, and JSON functions
+* [Memory Tables](../../docs/memory-table.md) — built-in MemoryTable module
+* [Module Authoring](../../docs/module-authoring.md) — virtual table module development and event system
+* [Date/Time Handling](../../docs/datetime.md) — temporal parsing, functions, and ISO 8601 formats
+* [Runtime](../../docs/runtime.md) — instruction-based execution and opcodes
+* [Error Handling](../../docs/errors.md) — error types and status codes
+* [Plugin System](../../docs/plugins.md) — virtual tables, functions, and collations
+* [Optimizer](../../docs/optimizer.md) / [Optimizer Conventions](../../docs/optimizer-conventions.md)
+* [Change-scope Introspection](../../docs/change-scope.md) — what a prepared statement reads from
+* [TODO List](../../docs/todo.md) — planned features
+
+### Plugin Development
+
+Quereus exports all critical utilities needed for plugin and module development:
+
+* **Comparison Functions** — `compareSqlValues`, `compareRows`, `compareTypedValues`, `createTypedComparator` — match Quereus SQL semantics in custom implementations
+* **Coercion Utilities** — `tryCoerceToNumber`, `coerceForAggregate` — handle type coercion for aggregates and arithmetic
+* **Collation Support** — `registerCollation`, `getCollation`, built-in collations (`BINARY_COLLATION`, `NOCASE_COLLATION`, `RTRIM_COLLATION`)
+* **Type System** — full access to logical types, validation, and parsing utilities
+* **Event Hooks** — `VTableEventEmitter` interface for mutation and schema change events; enable reactive patterns, caching, and replication
+* **DDL Generation** — `generateTableDDL(tableSchema, db?)`, `generateIndexDDL(indexSchema, tableSchema, db?)` — canonical `CREATE TABLE` / `CREATE INDEX` output from runtime schema objects. With a `Database`, matches session defaults (schema qualification, `default_column_nullability`, `default_vtab_module`/`default_vtab_args`) for readable output; without one, emits fully-qualified, explicitly-annotated DDL safe for cross-session persistence. See [Schema Management — DDL Generation](../../docs/schema.md#ddl-generation).
+
+See the [Plugin System documentation](../../docs/plugins.md#comparison-and-coercion-utilities) for complete API reference and examples.
+
+## Current Status
+
+Quereus is a feature-complete SQL query processor with a modern planner and instruction-based runtime architecture. The engine successfully handles complex SQL workloads including joins, window functions, subqueries, CTEs, constraints, and comprehensive DML/DDL operations.
+
+**Current capabilities include:**
+*   **Modern Type System** — temporal types (DATE, TIME, DATETIME), JSON with deep equality, plugin-extensible custom types
+*   **Complete JOIN support** — INNER, LEFT, RIGHT, CROSS, SEMI, and ANTI joins with proper NULL padding
+*   **Advanced window functions** — ranking, aggregates, and frame specifications
+*   **Full constraint system** — NOT NULL, CHECK, FOREIGN KEY, and CREATE ASSERTION. Row-level constraints that reference other tables are automatically deferred to COMMIT. The `committed.tablename` pseudo-schema provides read-only access to pre-transaction state for transition constraints (e.g., "balance may not decrease"). See [Architecture — Constraints](../../docs/architecture.md#constraints).
+*   **Comprehensive subqueries** — scalar, correlated, EXISTS, and IN subqueries
+*   **Relational orthogonality** — INSERT/UPDATE/DELETE with RETURNING can be used as table sources
+*   **Complete set operations** — UNION, INTERSECT, EXCEPT with proper deduplication
+*   **DIFF (symmetric difference)** — `A diff B` equals `(A except B) union (B except A)`, handy for table equality checks via `not exists(A diff B)`
+*   **Robust transaction support** — multi-level savepoints and rollback. See [Usage Guide](../../docs/usage.md#transactions) for details
+*   **Rich built-in function library** — scalar, aggregate, window, JSON, and date/time functions
+*   **Rule-based optimizer** — constant folding, caching, streaming aggregation, bloom-join selection, and correlated subquery decorrelation. See [Architecture — Optimizer](../../docs/architecture.md#optimizer).
+*   **Change-scope introspection and reactive subscriptions** — `Statement.getChangeScope()` returns a JSON-serializable description of what base-table state and external inputs a prepared statement reads from. The companion `Database.watch(scope, handler)` consumes any `ChangeScope` value (analyzed, deserialized, or hand-built) and fires a post-commit callback whenever matching rows, groups, or tables change. See [Change-scope Documentation](../../docs/change-scope.md).
+
+[TODO List](../../docs/todo.md) has remaining priorities.
+
+## Supported Built-in Functions
+
+*   **Scalar** — `lower`, `upper`, `length`, `substr`/`substring`, `abs`, `round`, `coalesce`, `nullif`, `like`, `glob`, `typeof`
+*   **Aggregate** — `count`, `sum`, `avg`, `min`, `max`, `group_concat`, `json_group_array`, `json_group_object`
+*   **Window Functions** — complete implementation with `row_number`, `rank`, `dense_rank`, `ntile` (ranking); `count`, `sum`, `avg`, `min`, `max` with OVER clause (aggregates); full frame specification support (`ROWS BETWEEN`, `UNBOUNDED PRECEDING/FOLLOWING`); `NULLS FIRST/LAST` ordering
+*   **Date/Time** — `date`, `time`, `datetime`, `julianday`, `strftime` (supports common formats and modifiers), `epoch_s`, `epoch_ms`, `epoch_s_frac` (Unix epoch conversions with strict parsing)
+*   **JSON** — `json_valid`, `json_schema`, `json_type`, `json_extract`, `json_quote`, `json_array`, `json_object`, `json_insert`, `json_replace`, `json_set`, `json_remove`, `json_array_length`, `json_patch`
+*   **Query Analysis** — `query_plan`, `scheduler_program`, `execution_trace` (debugging and performance analysis)
+
+## Testing
+
+Tests live in `test/*.spec.ts`, driven by Mocha with ts-node/esm. Run with `yarn test`. Quereus uses SQL logic tests (primary), property-based tests, performance sentinels, unit tests, and a benchmark suite — see [Architecture — Testing Strategy](../../docs/architecture.md#testing-strategy) for details.

package/dist/src/core/database-assertions.d.ts

@@ -1,13 +1,16 @@
 /**
  * Global assertion evaluation for deferred constraint checking.
  *
- * This module handles the evaluation of CREATE ASSERTION constraints at transaction
- * commit time. It optimizes assertion checking by:
+ * This module handles the evaluation of CREATE ASSERTION constraints at
+ * transaction commit time. It optimizes assertion checking by:
  * - Only evaluating assertions impacted by changed tables
- * - Caching compiled plans and classifications across commits
+ * - Caching compiled plans, classifications, and residual variants across commits
  * - Invalidating cached plans on schema changes
- * - Using row-specific filtering when possible to avoid full table scans
- * - Injecting PK filters for parameterized per-row evaluation
+ * - Driving per-binding execution through the reusable `DeltaExecutor` kernel
+ *
+ * Assertions are the first consumer of `DeltaExecutor`. Materialized views,
+ * reactive signals, and triggers will plug in by registering their own
+ * `DeltaSubscription`s.
  */
 import { type SqlValue } from '../common/types.js';
 import * as AST from '../parser/ast.js';
@@ -28,16 +31,22 @@ export interface AssertionEvaluatorContext {
     getChangedBaseTables(): Set<string>;
     /** Get changed PK tuples for a specific base table */
     getChangedKeyTuples(base: string): SqlValue[][];
+    /** Get changed projected tuples for a specific base table */
+    getChangedTuples(base: string, columnIndices: readonly number[], pkIndices: readonly number[]): SqlValue[][];
+    /** Register a column-projection capture spec for a base table */
+    registerCaptureSpec(baseTable: string, spec: {
+        extraColumns: ReadonlySet<number>;
+    }): () => void;
 }
 /**
  * Evaluates global assertions (CREATE ASSERTION) at transaction commit time.
  *
  * Assertions are evaluated only when the tables they reference have been modified.
- * The evaluator uses constraint analysis to determine whether assertions can be
- * checked per-row (more efficient) or require a full violation query.
+ * The evaluator uses binding analysis to determine whether assertions can be
+ * checked per-row, per-group, or require a full violation query.
  *
- * Compiled plans are cached and invalidated on schema changes to avoid
- * re-parsing/re-planning on every commit.
+ * Compiled plans and residual variants are cached and invalidated on schema
+ * changes to avoid re-parsing/re-planning on every commit.
  */
 export declare class AssertionEvaluator {
     private readonly ctx;
@@ -47,25 +56,36 @@ export declare class AssertionEvaluator {
     private schemaGeneration;
     /** Unsubscribe function for schema change listener */
     private unsubscribeSchemaChanges;
+    /** The shared delta dispatcher */
+    private readonly executor;
     constructor(ctx: AssertionEvaluatorContext);
     private subscribeToSchemaChanges;
     /** Remove an assertion from the plan cache (called on DROP ASSERTION) */
     invalidateAssertion(name: string): void;
     /** Unsubscribe from schema changes and clear cached plans */
     dispose(): void;
+    private releaseCached;
     /**
-     * Run all global assertions that are impacted by changes in the current transaction.
-     * @throws QuereusError with CONSTRAINT status if any assertion is violated
+     * Run all global assertions impacted by changes in the current transaction.
+     * The DeltaExecutor walks all live subscriptions; assertion subscriptions
+     * dispatch their own residual scheduler per binding tuple.
+     *
+     * @throws QuereusError with CONSTRAINT status if any assertion is violated.
      */
     runGlobalAssertions(): Promise<void>;
     private getOrCompilePlan;
-    private evaluateAssertion;
+    private compileUnderSuppression;
+    private buildSubscription;
     private executeViolationOnce;
-    private executeViolationPerChangedKeys;
+    private executeResidualPerTuple;
     private buildViolationError;
-    private injectPkFilter;
-    private rewriteForPkFilter;
+    /**
+     * Inject a key-equality filter onto the `TableReferenceNode` matching
+     * `targetRelationKey`. Used for both `'row'` (with PK columns + 'pk' prefix)
+     * and `'group'` (with group-key columns + 'gk' prefix).
+     */
+    private injectKeyFilter;
+    private rewriteForKeyFilter;
     private tryWrapTableReference;
-    private collectTables;
 }
 //# sourceMappingURL=database-assertions.d.ts.map

package/dist/src/core/database-assertions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database-assertions.d.ts","sourceRoot":"","sources":["../../../src/core/database-assertions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAI/D,OAAO,KAAK,GAAG,MAAM,kBAAkB,CAAC;AAaxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAQ9C;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAEtC,UAAU,CAAC,UAAU,EAAE,GAAG,CAAC,SAAS,EAAE,GAAG,OAAO,eAAe,EAAE,eAAe,CAAC;IACjF,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC;IACvF,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;IACtD,oBAAoB,IAAI,UAAU,CAAC,QAAQ,CAAC,sBAAsB,CAAC,CAAC,CAAC;IAErE,qEAAqE;IACrE,oBAAoB,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IACpC,sDAAsD;IACtD,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE,EAAE,CAAC;CAChD;AAwBD;;;;;;;;;GASG;AACH,qBAAa,kBAAkB;IAQlB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPhC,gEAAgE;IAChE,OAAO,CAAC,KAAK,CAA0C;IACvD,6FAA6F;IAC7F,OAAO,CAAC,gBAAgB,CAAK;IAC7B,sDAAsD;IACtD,OAAO,CAAC,wBAAwB,CAA6B;gBAEhC,GAAG,EAAE,yBAAyB;IAI3D,OAAO,CAAC,wBAAwB;IAUhC,yEAAyE;IACzE,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIvC,6DAA6D;IAC7D,OAAO,IAAI,IAAI;IAQf;;;OAGG;IACG,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAY1C,OAAO,CAAC,gBAAgB;YA+DV,iBAAiB;YA+DjB,oBAAoB;YAkBpB,8BAA8B;IAmC5C,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,kBAAkB;IAe1B,OAAO,CAAC,qBAAqB;IAiD7B,OAAO,CAAC,aAAa;CAYrB"}
+{"version":3,"file":"database-assertions.d.ts","sourceRoot":"","sources":["../../../src/core/database-assertions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAI/D,OAAO,KAAK,GAAG,MAAM,kBAAkB,CAAC;AAcxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAQ9C;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAEtC,UAAU,CAAC,UAAU,EAAE,GAAG,CAAC,SAAS,EAAE,GAAG,OAAO,eAAe,EAAE,eAAe,CAAC;IACjF,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC;IACvF,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;IACtD,oBAAoB,IAAI,UAAU,CAAC,QAAQ,CAAC,sBAAsB,CAAC,CAAC,CAAC;IAErE,qEAAqE;IACrE,oBAAoB,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IACpC,sDAAsD;IACtD,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE,EAAE,CAAC;IAChD,6DAA6D;IAC7D,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,QAAQ,EAAE,EAAE,CAAC;IAC7G,iEAAiE;IACjE,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;KAAE,GAAG,MAAM,IAAI,CAAC;CAChG;AAwCD;;;;;;;;;GASG;AACH,qBAAa,kBAAkB;IAUlB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAThC,gEAAgE;IAChE,OAAO,CAAC,KAAK,CAA0C;IACvD,6FAA6F;IAC7F,OAAO,CAAC,gBAAgB,CAAK;IAC7B,sDAAsD;IACtD,OAAO,CAAC,wBAAwB,CAA6B;IAC7D,kCAAkC;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;gBAEZ,GAAG,EAAE,yBAAyB;IAe3D,OAAO,CAAC,wBAAwB;IAUhC,yEAAyE;IACzE,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IASvC,6DAA6D;IAC7D,OAAO,IAAI,IAAI;IAYf,OAAO,CAAC,aAAa;IAMrB;;;;;;OAMG;IACG,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IA4B1C,OAAO,CAAC,gBAAgB;IAiCxB,OAAO,CAAC,uBAAuB;IA+F/B,OAAO,CAAC,iBAAiB;YAwCX,oBAAoB;YAsBpB,uBAAuB;IAkCrC,OAAO,CAAC,mBAAmB;IAS3B;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,mBAAmB;IAmB3B,OAAO,CAAC,qBAAqB;CA2E7B"}