@sun-asterisk/sungen 3.2.8 → 3.2.10-beta.1

package/dist/orchestrator/templates/specs-db.js

@@ -33,7 +33,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.db = void 0;
+exports.db = exports.DynamoEngine = exports.MongoEngine = exports.CosmosEngine = void 0;
+exports.rewritePlaceholders = rewritePlaceholders;
+exports.cosmosBindParams = cosmosBindParams;
 /* eslint-disable */
 /**
  * Sungen Data Driver — runtime DB-verification helper (auto-generated into specs/db.ts).
@@ -42,7 +44,7 @@ exports.db = void 0;
  * table/column identifiers are validated against a strict allowlist pattern (identifiers
  * can't be bound as parameters). Secrets come from .env.qa / process.env, never inline.
  *
- * Engines: PostgreSQL (`pg`) and SQLite (`better-sqlite3`), lazy-loaded on first use.
+ * Engines: PostgreSQL (`pg`), MySQL (`mysql2`), and SQLite (`better-sqlite3`), lazy-loaded on first use.
  * Config: a `datasources.yaml` at the project root (or qa/), with ${VAR} resolved from env.
  *
  * DO NOT EDIT — regenerated by `sungen generate`.
@@ -56,6 +58,13 @@ const ident = (s) => {
         throw new Error(`Unsafe identifier: ${JSON.stringify(s)} (allowed: [A-Za-z_][A-Za-z0-9_]*)`);
     return s;
 };
+// SQL engines: verified via the direct guarded-SELECT path and needing the `$n`→`?` placeholder
+// rewrite. This literal is the single source of truth for that rewrite condition and is quoted, by
+// name, in the sungen-gherkin-syntax skill's "direct SQL verification" note — keep them in sync.
+const SUPPORTED_ENGINES = ['postgres', 'sqlite', 'mysql'];
+// NoSQL engines: implement the Engine contract natively (no SQL rewrite). Tracked separately so the
+// SQL-rewrite guard and its skill-parity test stay pinned to the three SQL engines above.
+const NOSQL_ENGINES = ['cosmos', 'mongodb', 'dynamodb'];
 /**
  * Open a local TCP forward (127.0.0.1:<ephemeral> → ssh bastion → dstHost:dstPort) for a DB socket.
  * Sockets are unref()'d so a dangling tunnel never keeps the test process alive after the run.
@@ -144,11 +153,336 @@ function loadConfig() {
     }
     return doc.datasources;
 }
+/**
+ * `build()` always emits PG-style `$1..$n` placeholders; mysql2/better-sqlite3 both bind with
+ * positional `?` (left-to-right). Rewriting `$n`→`?` must therefore ALSO reorder the params to the
+ * textual placeholder order: an author-written catalog query `WHERE a = $2 AND b = $1` becomes
+ * `a = ? AND b = ?`, so the params must be bound `[params[1], params[0]]` — otherwise the values
+ * silently swap and the query returns wrong rows. A repeated `$k` duplicates its value at each `?`.
+ * Postgres binds `$n` natively, so it is returned untouched.
+ *
+ * Only real placeholders are rewritten — a `$1` inside a single-quoted string literal (e.g.
+ * `WHERE label = '$1 off'`) is left untouched. SQL escapes an inner quote by doubling it (`''`),
+ * which the simple in-string toggle handles (an even number of quotes returns to the same state).
+ *
+ * DynamoDB PartiQL binds the same positional `?` as mysql2/sqlite, so it shares this path — the
+ * reorder is essential there too (an author-written PartiQL `WHERE sk = $2 AND pk = $1`).
+ */
+function rewritePlaceholders(engine, sql, params) {
+    if (engine !== 'sqlite' && engine !== 'mysql' && engine !== 'dynamodb')
+        return { sql, params };
+    let out = '';
+    let inStr = false;
+    const newParams = [];
+    for (let i = 0; i < sql.length; i++) {
+        const c = sql[i];
+        if (c === "'") {
+            inStr = !inStr;
+            out += c;
+            continue;
+        }
+        if (!inStr && c === '$' && sql[i + 1] >= '0' && sql[i + 1] <= '9') {
+            let j = i + 1;
+            while (j < sql.length && sql[j] >= '0' && sql[j] <= '9')
+                j++;
+            const k = Number(sql.slice(i + 1, j)); // 1-based placeholder index
+            out += '?';
+            newParams.push(params[k - 1]);
+            i = j - 1;
+            continue;
+        }
+        out += c;
+    }
+    return { sql: out, params: newParams };
+}
+/** Read-only guard (second layer): a named SQL query must be a single SELECT/WITH statement. */
+function assertSelectOnly(label, sql) {
+    const s = sql.trim().replace(/;\s*$/, '');
+    if (!/^(SELECT|WITH)\b/i.test(s))
+        throw new Error(`Data Driver: ${label} is not a read-only SELECT — refused.`);
+    if (s.includes(';'))
+        throw new Error(`Data Driver: ${label} contains multiple statements — refused.`);
+    if (/\b(INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|TRUNCATE|GRANT|REVOKE|MERGE|REPLACE|CALL|EXEC|EXECUTE|ATTACH|PRAGMA|VACUUM)\b/i.test(s)) {
+        throw new Error(`Data Driver: ${label} contains a write/DDL keyword — refused.`);
+    }
+}
+/**
+ * SQL engine (postgres / mysql / sqlite). Builds the exact guarded, parameterized SELECTs the Data
+ * Driver has always emitted — `SELECT * … WHERE col = $n LIMIT`, `SELECT count(*)`, the `$n`→`?`
+ * reorder, and the read-only catalog guard — so the query strings are byte-identical to the
+ * pre-refactor path. `exec` is the lazy-loaded driver call (pg/mysql2/better-sqlite3).
+ */
+class SqlEngine {
+    constructor(engineName, exec) {
+        this.engineName = engineName;
+        this.exec = exec;
+    }
+    rewrite(sql, params) {
+        return rewritePlaceholders(this.engineName, sql, params);
+    }
+    async findRows(table, filter, limit) {
+        const cols = Object.keys(filter);
+        const where = cols.map((c, i) => `${ident(c)} = $${i + 1}`).join(' AND ');
+        const sql = `SELECT * FROM ${ident(table)}${where ? ' WHERE ' + where : ''} LIMIT ${limit}`;
+        const q = this.rewrite(sql, cols.map((c) => filter[c]));
+        return this.exec(q.sql, q.params);
+    }
+    async countRows(table, filter) {
+        const cols = Object.keys(filter);
+        const where = cols.map((c, i) => `${ident(c)} = $${i + 1}`).join(' AND ');
+        const sql = `SELECT count(*) AS n FROM ${ident(table)}${where ? ' WHERE ' + where : ''}`;
+        const q = this.rewrite(sql, cols.map((c) => filter[c]));
+        const rows = await this.exec(q.sql, q.params);
+        return Number(rows[0]?.n ?? rows[0]?.['count(*)'] ?? 0);
+    }
+    async runQuery(label, sql, params) {
+        assertSelectOnly(label, sql);
+        const q = this.rewrite(sql, params);
+        return this.exec(q.sql, q.params);
+    }
+}
+/**
+ * Azure Cosmos DB (NoSQL API) engine. The Cosmos query API is read-only by construction — `.query()`
+ * only ever reads; mutations require item-level APIs this engine never calls — so the SELECT guard is
+ * defense-in-depth. Cosmos binds NAMED params (`@p`), so it is immune to the positional-`?` reorder
+ * hazard. A step/catalog `[table]` selects the container; `SELECT * FROM c` uses the mandatory `c` alias.
+ */
+class CosmosEngine {
+    constructor(getContainer, opts) {
+        this.getContainer = getContainer;
+        this.opts = opts;
+    }
+    async query(container, spec) {
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), this.opts.timeoutMs);
+        try {
+            const res = await container.items.query(spec, { maxItemCount: this.opts.maxRows, abortSignal: ac.signal }).fetchAll();
+            return res.resources.slice(0, this.opts.maxRows);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Build `c.<col> = @p<i>` equality predicates over the mandatory `c` alias. Columns are identifier-checked. */
+    whereFor(filter) {
+        const cols = Object.keys(filter);
+        const where = cols.map((c, i) => `c.${ident(c)} = @p${i}`).join(' AND ');
+        const parameters = cols.map((c, i) => ({ name: `@p${i}`, value: filter[c] }));
+        return { where: where ? ` WHERE ${where}` : '', parameters };
+    }
+    async findRows(table, filter, limit) {
+        const { where, parameters } = this.whereFor(filter);
+        // TOP bounds the fetch server-side (like the SQL engine's LIMIT) — without it, fetchAll() would
+        // drain every matching row into memory before the client-side slice, wasting RUs + latency.
+        const cap = Math.min(limit, this.opts.maxRows);
+        const rows = await this.query(this.getContainer(table), { query: `SELECT TOP ${cap} * FROM c${where}`, parameters });
+        return rows.slice(0, limit);
+    }
+    async countRows(table, filter) {
+        const { where, parameters } = this.whereFor(filter);
+        // SELECT VALUE COUNT(1) returns the scalar count as the single resource.
+        const rows = await this.query(this.getContainer(table), { query: `SELECT VALUE COUNT(1) FROM c${where}`, parameters });
+        return Number(rows[0] ?? 0);
+    }
+    async runQuery(label, sql, params) {
+        assertSelectOnly(label, sql); // defense-in-depth; the query API is read-only anyway
+        const { query, parameters } = cosmosBindParams(sql, params);
+        return this.query(this.getContainer(), { query, parameters });
+    }
+}
+exports.CosmosEngine = CosmosEngine;
+/**
+ * Rewrite compiled positional `$n` placeholders to Cosmos NAMED params (`@pN`) and collect the
+ * matching parameter list. A `$n` inside a single-quoted string literal is left untouched (same
+ * in-string toggle as the SQL rewrite); a repeated `$n` reuses its one `@pN` entry.
+ */
+function cosmosBindParams(sql, params) {
+    const parameters = [];
+    const seen = new Set();
+    let out = '';
+    let inStr = false;
+    for (let i = 0; i < sql.length; i++) {
+        const c = sql[i];
+        if (c === "'") {
+            inStr = !inStr;
+            out += c;
+            continue;
+        }
+        if (!inStr && c === '$' && sql[i + 1] >= '0' && sql[i + 1] <= '9') {
+            let j = i + 1;
+            while (j < sql.length && sql[j] >= '0' && sql[j] <= '9')
+                j++;
+            const k = Number(sql.slice(i + 1, j));
+            out += `@p${k}`;
+            if (!seen.has(k)) {
+                seen.add(k);
+                parameters.push({ name: `@p${k}`, value: params[k - 1] });
+            }
+            i = j - 1;
+            continue;
+        }
+        out += c;
+    }
+    return { query: out, parameters };
+}
+/** Forbidden MongoDB operators (write-out / server-side JS) — refused at runtime as defense-in-depth. */
+const MONGO_FORBIDDEN = /\$out|\$merge|\$where|\$function|\$accumulator|mapReduce/i;
+/** Replace every whole-string `:param` in a find/pipeline shape with its bound native value (type-preserving). */
+function substituteShapeParams(obj, params) {
+    if (typeof obj === 'string') {
+        const m = obj.match(/^:([A-Za-z_][A-Za-z0-9_]*)$/);
+        return m ? params[m[1]] : obj;
+    }
+    if (Array.isArray(obj))
+        return obj.map((v) => substituteShapeParams(v, params));
+    if (obj && typeof obj === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(obj))
+            out[k] = substituteShapeParams(v, params);
+        return out;
+    }
+    return obj;
+}
+/** Refuse a shape whose serialized form contains a write/JS-exec operator (nested or aliased). */
+function assertMongoReadOnly(label, shape) {
+    const m = JSON.stringify(shape ?? {}).match(MONGO_FORBIDDEN);
+    if (m)
+        throw new Error(`Data Driver: ${label} uses forbidden MongoDB operator "${m[0]}" — refused (read-only find/aggregate only).`);
+}
+/**
+ * MongoDB engine. There is no SQL — declarative steps map to native find()/countDocuments(), and the
+ * raw `@query` path takes a find/pipeline shape (via fetchQueryShape → runShape) rather than a SQL
+ * string. Type-strict matching (`{age:30}` ≠ `{age:"30"}`) is why DB params bind via raw() (native
+ * type), not the stringifying get(). Read-only is enforced first by the server-side read role, with
+ * the operator blocklist as in-driver defense-in-depth. Per-query `maxTimeMS` + row cap bound cost.
+ */
+class MongoEngine {
+    constructor(getCollection, opts) {
+        this.getCollection = getCollection;
+        this.opts = opts;
+    }
+    async findRows(table, filter, limit) {
+        return this.getCollection(table).find(filter).limit(limit).maxTimeMS(this.opts.timeoutMs).toArray();
+    }
+    async countRows(table, filter) {
+        return this.getCollection(table).countDocuments(filter, { maxTimeMS: this.opts.timeoutMs });
+    }
+    async runQuery(label) {
+        throw new Error(`Data Driver: ${label} — MongoDB has no SQL; author a find:/pipeline: catalog entry instead of sql:.`);
+    }
+    async runShape(label, shape, params) {
+        if (shape.find) {
+            const f = substituteShapeParams(shape.find, params);
+            assertMongoReadOnly(label, f);
+            let cursor = this.getCollection(f.collection).find(f.filter ?? {});
+            if (f.projection)
+                cursor = cursor.project(f.projection);
+            if (f.sort)
+                cursor = cursor.sort(f.sort);
+            cursor = cursor.limit(f.limit ?? this.opts.maxRows).maxTimeMS(this.opts.timeoutMs);
+            return cursor.toArray();
+        }
+        if (shape.pipeline) {
+            const p = substituteShapeParams(shape.pipeline, params);
+            assertMongoReadOnly(label, p);
+            const rows = await this.getCollection(p.collection).aggregate(p.stages, { maxTimeMS: this.opts.timeoutMs }).toArray();
+            return rows.slice(0, this.opts.maxRows);
+        }
+        throw new Error(`Data Driver: ${label} — catalog shape has neither find: nor pipeline:.`);
+    }
+}
+exports.MongoEngine = MongoEngine;
+/**
+ * DynamoDB engine. The clean primary path is raw `@query` PartiQL SELECT (positional `?`, reordered
+ * via the shared placeholder rewrite). Declarative assertRow/count is structurally constrained by
+ * DynamoDB's key model: it routes GetItem/Query only for pk / pk+sk filters (via the `keySchema`
+ * registry) and REFUSES a non-key filter rather than falling back to an unaffordable full-table Scan.
+ * Read-only is primarily IAM (`dynamodb:PartiQLSelect` only); the SELECT guard is defense-in-depth.
+ */
+class DynamoEngine {
+    constructor(ops, keySchema, opts) {
+        this.ops = ops;
+        this.keySchema = keySchema;
+        this.opts = opts;
+    }
+    async withTimeout(fn) {
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), this.opts.timeoutMs);
+        try {
+            return await fn(ac.signal);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Decide how a flat equality filter maps to a key-based access pattern, or refuse it. */
+    route(table, filter) {
+        const ks = this.keySchema[table];
+        if (!ks)
+            throw new Error(`Data Driver: DynamoDB table "${table}" has no keySchema entry — add it under the datasource's keySchema:, or use a raw @query PartiQL SELECT.`);
+        const pk = ks.partitionKey;
+        const sk = ks.sortKey || undefined;
+        const keyAttrs = sk ? [pk, sk] : [pk];
+        const keys = Object.keys(filter);
+        const nonKey = keys.filter((k) => !keyAttrs.includes(k));
+        if (nonKey.length)
+            throw new Error(`Data Driver: DynamoDB "${table}" filter has non-key attribute(s) [${nonKey.join(', ')}] — routing would require a full-table Scan (refused). Use a raw @query PartiQL SELECT instead.`);
+        if (!keys.includes(pk))
+            throw new Error(`Data Driver: DynamoDB "${table}" filter must include the partition key "${pk}".`);
+        if (sk && keys.includes(sk))
+            return { kind: 'get', key: { [pk]: filter[pk], [sk]: filter[sk] } };
+        if (!sk)
+            return { kind: 'get', key: { [pk]: filter[pk] } };
+        return { kind: 'query', pk, value: filter[pk] }; // pk only on a table that has a sort key → Query
+    }
+    async findRows(table, filter, limit) {
+        const route = this.route(table, filter);
+        const cap = Math.min(limit, this.opts.maxRows);
+        if (route.kind === 'get') {
+            const res = await this.withTimeout((s) => this.ops.getItem({ TableName: table, Key: route.key }, s));
+            return res.Item ? [res.Item] : [];
+        }
+        const res = await this.withTimeout((s) => this.ops.query({ TableName: table, KeyConditionExpression: '#pk = :pk', ExpressionAttributeNames: { '#pk': route.pk }, ExpressionAttributeValues: { ':pk': route.value }, Limit: cap }, s));
+        return (res.Items ?? []).slice(0, cap);
+    }
+    async countRows(table, filter) {
+        const route = this.route(table, filter);
+        if (route.kind === 'get') {
+            const res = await this.withTimeout((s) => this.ops.getItem({ TableName: table, Key: route.key }, s));
+            return res.Item ? 1 : 0;
+        }
+        // A Query with Select:COUNT evaluates at most ~1MB per request and returns a PARTIAL Count with a
+        // LastEvaluatedKey for the rest — accumulate across pages so the exact-equality assert is correct.
+        let count = 0;
+        let startKey;
+        do {
+            const res = await this.withTimeout((s) => this.ops.query({ TableName: table, KeyConditionExpression: '#pk = :pk', ExpressionAttributeNames: { '#pk': route.pk }, ExpressionAttributeValues: { ':pk': route.value }, Select: 'COUNT', ExclusiveStartKey: startKey }, s));
+            count += Number(res.Count ?? 0);
+            startKey = res.LastEvaluatedKey;
+        } while (startKey);
+        return count;
+    }
+    async runQuery(label, sql, params) {
+        assertSelectOnly(label, sql); // defense-in-depth; primary read-only guarantee is IAM PartiQLSelect-only
+        const bound = rewritePlaceholders('dynamodb', sql, params); // $n → ? positional, reordered to textual order
+        const items = [];
+        let nextToken;
+        do {
+            const page = await this.withTimeout((s) => this.ops.executeStatement({ Statement: bound.sql, Parameters: bound.params.length ? bound.params : undefined, Limit: this.opts.maxRows, NextToken: nextToken }, s));
+            items.push(...(page.Items ?? []));
+            nextToken = page.NextToken;
+        } while (nextToken && items.length < this.opts.maxRows); // manual pagination, bounded by the row cap
+        return items.slice(0, this.opts.maxRows);
+    }
+}
+exports.DynamoEngine = DynamoEngine;
 class DataSource {
     constructor() {
         this.configs = null;
         this.engines = new Map();
         this.tunnels = [];
+        this.mysqlPools = [];
+        this.mongoClients = [];
     }
     cfg(name) {
         if (!this.configs)
@@ -163,12 +497,34 @@ class DataSource {
         const { key, conf } = this.cfg(name);
         if (this.engines.has(key))
             return { engine: this.engines.get(key), conf };
-        if (!conf.url)
-            throw new Error(`Data Driver: datasource "${key}" has no url (set it in .env.qa).`);
         let engine;
+        if (conf.engine === 'postgres' || conf.engine === 'mysql' || conf.engine === 'sqlite') {
+            // url is required for the SQL engines (host-based, or a sqlite file path). NoSQL engines that
+            // have no connection URL (e.g. DynamoDB region+creds) supply their own config and skip this.
+            if (!conf.url)
+                throw new Error(`Data Driver: datasource "${key}" has no url (set it in .env.qa).`);
+            engine = new SqlEngine(conf.engine, await this.sqlExec(key, conf));
+        }
+        else if (conf.engine === 'cosmos') {
+            engine = this.cosmosEngine(key, conf);
+        }
+        else if (conf.engine === 'mongodb') {
+            engine = this.mongoEngine(key, conf);
+        }
+        else if (conf.engine === 'dynamodb') {
+            engine = this.dynamoEngine(key, conf);
+        }
+        else {
+            throw new Error(`Data Driver: engine "${conf.engine}" not supported (supported: ${[...SUPPORTED_ENGINES, ...NOSQL_ENGINES].join(' | ')}). For an unlisted store, verify via @api or @manual.`);
+        }
+        this.engines.set(key, engine);
+        return { engine, conf };
+    }
+    /** Build the lazy driver-call closure for a SQL engine (pg/mysql/sqlite), incl. the optional SSH-tunnel fallback. */
+    async sqlExec(key, conf) {
         if (conf.engine === 'postgres') {
             let connectionString = conf.url;
-            if (conf.ssh) { // Cách B: tunnel the DB socket through a bastion
+            if (conf.ssh) { // Fallback path: tunnel the DB socket through a bastion
                 const u = new URL(conf.url);
                 const t = await openSshTunnel(conf.ssh, u.hostname, Number(u.port || 5432));
                 this.tunnels.push(t);
@@ -178,38 +534,133 @@ class DataSource {
             }
             const { Pool } = require('pg');
             const pool = new Pool({ connectionString, max: 2, statement_timeout: conf.statement_timeout_ms ?? 4000 });
-            engine = { query: async (sql, params) => (await pool.query(sql, params)).rows };
+            return async (sql, params) => (await pool.query(sql, params)).rows;
         }
-        else if (conf.engine === 'sqlite') {
-            if (conf.ssh)
-                console.warn(`Data Driver: datasource "${key}" sets ssh: but engine is sqlite (file-based) — ssh ignored.`);
-            const Database = require('better-sqlite3');
-            const db = new Database(conf.url.replace(/^sqlite:/, ''), { readonly: conf.readonly !== false });
-            engine = { query: async (sql, params) => db.prepare(sql).all(...params) };
-        }
-        else {
-            throw new Error(`Data Driver: engine "${conf.engine}" not supported yet (postgres | sqlite).`);
+        if (conf.engine === 'mysql') {
+            let connectionString = conf.url;
+            if (conf.ssh) { // Fallback path: tunnel the DB socket through a bastion
+                const u = new URL(conf.url);
+                const t = await openSshTunnel(conf.ssh, u.hostname, Number(u.port || 3306));
+                this.tunnels.push(t);
+                u.hostname = t.host;
+                u.port = String(t.port); // rewrite host:port → 127.0.0.1:<tunnel> (keep user/pass/db/query)
+                connectionString = u.toString();
+            }
+            const mysql = require('mysql2/promise');
+            const pool = mysql.createPool({ uri: connectionString, connectionLimit: 2 });
+            this.mysqlPools.push(pool);
+            // mysql2 ignores the mysqljs per-query `timeout` field, and destroying the connection does
+            // not interrupt an in-flight query — so bound the wait client-side by racing the query
+            // against a timer. On overrun we reject and destroy the connection (removes it from the pool
+            // rather than releasing a still-busy socket); on success we release it back.
+            const timeoutMs = conf.statement_timeout_ms ?? 4000;
+            return async (sql, params) => {
+                const conn = await pool.getConnection();
+                const qp = conn.query(sql, params);
+                qp.catch(() => { });
+                let timer;
+                let timedOut = false;
+                const guard = new Promise((_, reject) => {
+                    timer = setTimeout(() => { timedOut = true; reject(new Error(`Data Driver: mysql query exceeded ${timeoutMs}ms — aborted.`)); }, timeoutMs);
+                });
+                try {
+                    const [rows] = await Promise.race([qp, guard]);
+                    return rows;
+                }
+                finally {
+                    clearTimeout(timer);
+                    if (timedOut) {
+                        try {
+                            conn.destroy();
+                        }
+                        catch { /* best-effort */ }
+                    }
+                    else {
+                        try {
+                            conn.release();
+                        }
+                        catch { /* already gone */ }
+                    }
+                }
+            };
         }
-        this.engines.set(key, engine);
-        return { engine, conf };
+        // sqlite
+        if (conf.ssh)
+            console.warn(`Data Driver: datasource "${key}" sets ssh: but engine is sqlite (file-based) — ssh ignored.`);
+        const Database = require('better-sqlite3');
+        const db = new Database(conf.url.replace(/^sqlite:/, ''), { readonly: conf.readonly !== false });
+        return async (sql, params) => db.prepare(sql).all(...params);
+    }
+    /** Build the Cosmos engine — connect via endpoint+key or a connection-string url; resolve containers by name. */
+    cosmosEngine(key, conf) {
+        const { CosmosClient } = require('@azure/cosmos');
+        let client;
+        if (conf.endpoint && conf.key)
+            client = new CosmosClient({ endpoint: conf.endpoint, key: conf.key });
+        else if (conf.url)
+            client = new CosmosClient(conf.url); // AccountEndpoint=…;AccountKey=…; connection string
+        else
+            throw new Error(`Data Driver: cosmos datasource "${key}" needs endpoint+key (or a connection-string url).`);
+        if (!conf.database)
+            throw new Error(`Data Driver: cosmos datasource "${key}" needs a database name.`);
+        const getContainer = (name) => {
+            const cn = name || conf.container;
+            if (!cn)
+                throw new Error(`Data Driver: cosmos datasource "${key}" — no container (set container: in config, or name a [table]).`);
+            return client.database(conf.database).container(cn);
+        };
+        return new CosmosEngine(getContainer, { timeoutMs: conf.statement_timeout_ms ?? 4000, maxRows: conf.max_rows ?? 100 });
+    }
+    /** Build the MongoDB engine — one reused client per datasource; the db comes from `database` or the URI default. */
+    mongoEngine(key, conf) {
+        if (!conf.url)
+            throw new Error(`Data Driver: mongodb datasource "${key}" needs a url (mongodb:// URI).`);
+        const { MongoClient } = require('mongodb');
+        const client = new MongoClient(conf.url); // operations auto-connect; one client is reused
+        this.mongoClients.push(client);
+        const dbHandle = client.db(conf.database); // undefined → the URI's default database
+        return new MongoEngine((name) => dbHandle.collection(name), { timeoutMs: conf.statement_timeout_ms ?? 5000, maxRows: conf.max_rows ?? 50 });
+    }
+    /** Build the DynamoDB engine — region + credentials from the AWS env chain; wraps the Document client's three read ops. */
+    dynamoEngine(key, conf) {
+        if (!conf.region)
+            throw new Error(`Data Driver: dynamodb datasource "${key}" needs a region (DynamoDB has no url).`);
+        const { DynamoDBClient } = require('@aws-sdk/client-dynamodb');
+        const { DynamoDBDocumentClient, ExecuteStatementCommand, GetCommand, QueryCommand } = require('@aws-sdk/lib-dynamodb');
+        const base = new DynamoDBClient({ region: conf.region }); // creds resolved from env / IAM role
+        const doc = DynamoDBDocumentClient.from(base, { marshallOptions: { removeUndefinedValues: true } });
+        const ops = {
+            executeStatement: (input, signal) => doc.send(new ExecuteStatementCommand(input), { abortSignal: signal }),
+            getItem: (input, signal) => doc.send(new GetCommand(input), { abortSignal: signal }),
+            query: (input, signal) => doc.send(new QueryCommand(input), { abortSignal: signal }),
+        };
+        return new DynamoEngine(ops, conf.keySchema ?? {}, { timeoutMs: conf.statement_timeout_ms ?? 4000, maxRows: conf.max_rows ?? 1000 });
     }
-    /** Close any open SSH tunnels (optional explicit teardown; tunnels are unref'd so the process exits regardless). */
+    /** Close open MySQL pools + Mongo clients + SSH tunnels (optional explicit teardown; tunnels are unref'd so the process exits regardless). */
     close() {
+        for (const p of this.mysqlPools) {
+            try {
+                void p.end();
+            }
+            catch { /* best-effort */ }
+        }
+        this.mysqlPools = [];
+        for (const c of this.mongoClients) {
+            try {
+                void c.close();
+            }
+            catch { /* best-effort */ }
+        }
+        this.mongoClients = [];
         for (const t of this.tunnels)
             t.close();
         this.tunnels = [];
     }
-    build(table, filter) {
-        const cols = Object.keys(filter);
-        const where = cols.map((c, i) => `${ident(c)} = $${i + 1}`).join(' AND ');
-        const sql = `SELECT * FROM ${ident(table)}${where ? ' WHERE ' + where : ''} LIMIT 50`;
-        return { sql, params: cols.map((c) => filter[c]) };
-    }
+    // --- Engine-agnostic assertions: build nothing, just delegate to the engine + compare here ----
     /** A row matching `filter` must exist; if `expected` given, assert those columns on the first match. */
     async assertRow(table, filter, expected, datasource) {
-        const { engine, conf } = await this.engine(datasource);
-        const { sql, params } = this.build(table, filter);
-        const rows = await engine.query(this.sqlFor(conf, sql), params);
+        const { engine } = await this.engine(datasource);
+        const rows = await engine.findRows(table, filter, 50);
         (0, test_1.expect)(rows.length, `Expected a row in "${table}" where ${desc(filter)} — found ${rows.length}`).toBeGreaterThanOrEqual(1);
         if (expected) {
             const row = rows[0];
@@ -221,46 +672,36 @@ class DataSource {
     }
     /** No row matching `filter` may exist. */
     async assertNoRow(table, filter, datasource) {
-        const { engine, conf } = await this.engine(datasource);
-        const { sql, params } = this.build(table, filter);
-        const rows = await engine.query(this.sqlFor(conf, sql), params);
+        const { engine } = await this.engine(datasource);
+        const rows = await engine.findRows(table, filter, 50);
         (0, test_1.expect)(rows.length, `Expected NO row in "${table}" where ${desc(filter)} — found ${rows.length}`).toBe(0);
     }
     /** Exactly `count` rows must match `filter`. */
     async assertCount(table, filter, count, datasource) {
-        const { engine, conf } = await this.engine(datasource);
+        const { engine } = await this.engine(datasource);
+        const n = await engine.countRows(table, filter);
         const cols = Object.keys(filter);
-        const where = cols.map((c, i) => `${ident(c)} = $${i + 1}`).join(' AND ');
-        const sql = `SELECT count(*) AS n FROM ${ident(table)}${where ? ' WHERE ' + where : ''}`;
-        const rows = await engine.query(this.sqlFor(conf, sql), cols.map((c) => filter[c]));
-        const n = Number(rows[0]?.n ?? rows[0]?.['count(*)'] ?? 0);
         (0, test_1.expect)(n, `Expected ${count} row(s) in "${table}"${cols.length ? ' where ' + desc(filter) : ''} — found ${n}`).toBe(Number(count));
     }
-    /** Rewrites $1/$2 placeholders to `?` for SQLite. */
-    sqlFor(conf, sql) {
-        return conf.engine === 'sqlite' ? sql.replace(/\$\d+/g, '?') : sql;
-    }
-    // --- Named queries (catalog-backed; SQL is resolved + embedded at compile time) -----------
-    /** Read-only guard (second layer): a named query must be a single SELECT/WITH statement. */
-    assertSelectOnly(label, sql) {
-        const s = sql.trim().replace(/;\s*$/, '');
-        if (!/^(SELECT|WITH)\b/i.test(s))
-            throw new Error(`Data Driver: ${label} is not a read-only SELECT — refused.`);
-        if (s.includes(';'))
-            throw new Error(`Data Driver: ${label} contains multiple statements — refused.`);
-        if (/\b(INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|TRUNCATE|GRANT|REVOKE|MERGE|REPLACE|CALL|EXEC|EXECUTE|ATTACH|PRAGMA|VACUUM)\b/i.test(s)) {
-            throw new Error(`Data Driver: ${label} contains a write/DDL keyword — refused.`);
-        }
-    }
     /**
      * Run a catalog query (read-only) and return its rows. The result is bound to a `{{name}}`
      * variable via `testData.bind(...)`, so the scenario asserts on it with `expect …` steps and
      * path access (`{{name.count}}`, `{{name.first.col}}`, `{{name[2].col}}`).
      */
     async fetchQuery(label, sql, params, datasource) {
-        this.assertSelectOnly(label, sql);
-        const { engine, conf } = await this.engine(datasource);
-        return engine.query(this.sqlFor(conf, sql), params);
+        const { engine } = await this.engine(datasource);
+        return engine.runQuery(label, sql, params);
+    }
+    /**
+     * Run a MongoDB find/pipeline catalog query (read-only) and return its documents. Same binding
+     * contract as fetchQuery, but the query is a structured shape (not SQL) with `:param` placeholders
+     * bound from `params` at runtime. Refused on an engine that has no non-SQL shape support.
+     */
+    async fetchQueryShape(label, shape, params, datasource) {
+        const { engine } = await this.engine(datasource);
+        if (!engine.runShape)
+            throw new Error(`Data Driver: ${label} is a find/pipeline query, but this datasource's engine has no such support (find:/pipeline: is MongoDB-only).`);
+        return engine.runShape(label, shape, params);
     }
 }
 function desc(filter) {