@sun-asterisk/sungen 3.2.10-beta.6 → 3.2.10

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

@@ -33,9 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.db = exports.DynamoEngine = exports.MongoEngine = exports.CosmosEngine = void 0;
+exports.db = void 0;
 exports.rewritePlaceholders = rewritePlaceholders;
-exports.cosmosBindParams = cosmosBindParams;
 /* eslint-disable */
 /**
  * Sungen Data Driver — runtime DB-verification helper (auto-generated into specs/db.ts).
@@ -58,13 +57,9 @@ 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.
+// Single source of truth for the "not supported" error message below and for the mysql/sqlite
+// placeholder rewrite condition (`rewritePlaceholders`) — keep engine names in sync with `DataSourceConfig.engine`.
 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.
@@ -154,26 +149,16 @@ 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`).
+ * `build()` always emits PG-style `$1..$n` placeholders; mysql2/better-sqlite3 both bind with `?`.
+ * Only real placeholders are rewritten — a `$1` sitting inside a single-quoted string literal (e.g.
+ * a catalog query `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).
  */
-function rewritePlaceholders(engine, sql, params) {
-    if (engine !== 'sqlite' && engine !== 'mysql' && engine !== 'dynamodb')
-        return { sql, params };
+function rewritePlaceholders(engine, sql) {
+    if (engine !== 'sqlite' && engine !== 'mysql')
+        return sql;
     let out = '';
     let inStr = false;
-    const newParams = [];
     for (let i = 0; i < sql.length; i++) {
         const c = sql[i];
         if (c === "'") {
@@ -185,304 +170,20 @@ function rewritePlaceholders(engine, sql, params) {
             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);
-    }
+    return out;
 }
-/**
- * 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)
@@ -497,31 +198,9 @@ 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) { // Fallback path: tunnel the DB socket through a bastion
@@ -534,9 +213,9 @@ class DataSource {
             }
             const { Pool } = require('pg');
             const pool = new Pool({ connectionString, max: 2, statement_timeout: conf.statement_timeout_ms ?? 4000 });
-            return async (sql, params) => (await pool.query(sql, params)).rows;
+            engine = { query: async (sql, params) => (await pool.query(sql, params)).rows };
         }
-        if (conf.engine === 'mysql') {
+        else 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);
@@ -554,89 +233,52 @@ class DataSource {
             // 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 */ }
+            engine = {
+                query: 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;
                     }
-                    else {
-                        try {
-                            conn.release();
+                    finally {
+                        clearTimeout(timer);
+                        if (timedOut) {
+                            try {
+                                conn.destroy();
+                            }
+                            catch { /* best-effort */ }
+                        }
+                        else {
+                            try {
+                                conn.release();
+                            }
+                            catch { /* already gone */ }
                         }
-                        catch { /* already gone */ }
                     }
-                }
+                },
             };
         }
-        // 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 });
+        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 (supported: ${SUPPORTED_ENGINES.join(' | ')}). For non-SQL stores (Cosmos NoSQL, Mongo…) verify via @api or @manual.`);
+        }
+        this.engines.set(key, engine);
+        return { engine, conf };
     }
-    /** Close open MySQL pools + Mongo clients + SSH tunnels (optional explicit teardown; tunnels are unref'd so the process exits regardless). */
+    /** Close open MySQL pools + SSH tunnels (optional explicit teardown; tunnels are unref'd so the process exits regardless). */
     close() {
         for (const p of this.mysqlPools) {
             try {
@@ -645,22 +287,21 @@ class DataSource {
             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 = [];
     }
-    // --- Engine-agnostic assertions: build nothing, just delegate to the engine + compare here ----
+    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]) };
+    }
     /** A row matching `filter` must exist; if `expected` given, assert those columns on the first match. */
     async assertRow(table, filter, expected, datasource) {
-        const { engine } = await this.engine(datasource);
-        const rows = await engine.findRows(table, filter, 50);
+        const { engine, conf } = await this.engine(datasource);
+        const { sql, params } = this.build(table, filter);
+        const rows = await engine.query(this.sqlFor(conf, sql), params);
         (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];
@@ -672,36 +313,46 @@ class DataSource {
     }
     /** No row matching `filter` may exist. */
     async assertNoRow(table, filter, datasource) {
-        const { engine } = await this.engine(datasource);
-        const rows = await engine.findRows(table, filter, 50);
+        const { engine, conf } = await this.engine(datasource);
+        const { sql, params } = this.build(table, filter);
+        const rows = await engine.query(this.sqlFor(conf, sql), params);
         (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 } = await this.engine(datasource);
-        const n = await engine.countRows(table, filter);
+        const { engine, conf } = await this.engine(datasource);
         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 engines that don't support PG-style positional params. */
+    sqlFor(conf, sql) {
+        return rewritePlaceholders(conf.engine, 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) {
-        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);
+        this.assertSelectOnly(label, sql);
+        const { engine, conf } = await this.engine(datasource);
+        return engine.query(this.sqlFor(conf, sql), params);
     }
 }
 function desc(filter) {