@venizia/ignis-connectors 0.2.0-0

package/dist/cjs/index.d.ts

@@ -0,0 +1,3 @@
+export * from './relational/core';
+export * from './search/core';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC"}

package/dist/cjs/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./relational/core"), exports);
+__exportStar(require("./search/core"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oDAAkC;AAClC,gDAA8B"}

package/dist/cjs/relational/core/datasources/abstract.d.ts

@@ -0,0 +1,71 @@
+import type { TAnyDataSourceSchema } from '@venizia/ignis-kernel';
+import { AbstractDataSource } from '@venizia/ignis-kernel';
+import type { IRelationalDriver } from '../../../relational/core/drivers';
+import type { IRelationalDataSource, IRelationalTransaction, TRelationalTransactionOptions } from '../../../relational/core/datasources/common';
+import type { IRelationalQueryDialect, IRelationalQueryExecutor } from '../../../relational/core/repositories/common';
+import type { AnyObject, TClass, ValueOrPromise } from '@venizia/ignis-helpers/common';
+/**
+ * SQL branch root: connector, pool, transactions. Engine-neutral - dialect and executor are
+ * declared abstract here and supplied by each engine branch.
+ *
+ * `mapSecretToSettings` is a driver-config convention, not Postgres SQL, so it belongs on this
+ * neutral base - do not move it down into `connectors/postgres`.
+ */
+export declare abstract class AbstractRelationalDataSource<Settings extends object = {}, Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema, ConfigurableOptions extends object = {}, Client = unknown, TConnector = unknown> extends AbstractDataSource<Settings, Schema, ConfigurableOptions> implements IRelationalDataSource<Settings, Schema, ConfigurableOptions, Client, TConnector> {
+    connector: TConnector;
+    protected client?: Client;
+    protected driver?: IRelationalDriver<TConnector>;
+    /**
+     * Lazy and idempotent: builds the driver named by `@datasource({ driver })` over the client
+     * `configure()` assigned, then the connector from it.
+     */
+    protected wireDriverFromMetadata(): void;
+    /**
+     * Rejects a driver-name string from untyped JS
+     * callers: a string carries no module into the bundle.
+     */
+    protected resolveDriverClass(): TClass<IRelationalDriver<TConnector>>;
+    protected resolveDriver(): IRelationalDriver<TConnector>;
+    /**
+     * Assigns `this.driver` AND builds `this.connector` in one step - a
+     * driver without its connector is silently bypassed on pooled queries.
+     */
+    protected useDriver(opts: {
+        driver: IRelationalDriver<TConnector>;
+        schema?: Schema;
+    }): void;
+    abstract getConnectionString(): ValueOrPromise<string>;
+    abstract beginTransaction(opts?: TRelationalTransactionOptions): Promise<IRelationalTransaction<TConnector>>;
+    /** Wires the driver on first use, so a `configure()` that only builds `this.client` is enough. */
+    getConnector(): TConnector;
+    /**
+     * Raw driver client (`pg.Pool` / `Sql`). Throws rather
+     * than handing back an `undefined` typed as `Client`.
+     */
+    getClient(): Client;
+    abstract getQueryDialect(): IRelationalQueryDialect;
+    abstract getQueryExecutor(): IRelationalQueryExecutor<TConnector>;
+    /**
+     * Soft-evicts the pool after a secret rotation: rebuilds against the rotated credentials without
+     * touching live fields, swaps atomically, then drains the old pool. On failure live state is
+     * restored, any half-built pool drained, and the error rethrown.
+     */
+    onSecretRotated(opts: {
+        key: string;
+        secret: Record<string, string>;
+    }): Promise<void>;
+    /**
+     * Shuts a client down by whichever verb its engine spells it with -
+     * `pg.Pool` and postgres.js have `end()`, PGlite and libsql only `close()`.
+     * Probed rather than type-tested: this tier must not name an engine, and a
+     * client left undrained keeps a WASM instance or file handle alive forever.
+     */
+    protected drainClient(opts: {
+        client: unknown;
+    }): Promise<boolean>;
+    /** Vault's database engine returns `{ username, password }`; pg expects `{ user, password }`. */
+    protected mapSecretToSettings(opts: {
+        secret: Record<string, string>;
+    }): AnyObject;
+}
+//# sourceMappingURL=abstract.d.ts.map

package/dist/cjs/relational/core/datasources/abstract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract.d.ts","sourceRoot":"","sources":["../../../../../src/relational/core/datasources/abstract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EACtB,6BAA6B,EAC9B,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EACV,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,uCAAuC,CAAC;AAE/C,OAAO,KAAK,EAAE,SAAS,EAAW,MAAM,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAGhG;;;;;;GAMG;AACH,8BAAsB,4BAA4B,CAChD,QAAQ,SAAS,MAAM,GAAG,EAAE,EAC5B,MAAM,SAAS,oBAAoB,GAAG,oBAAoB,EAC1D,mBAAmB,SAAS,MAAM,GAAG,EAAE,EACvC,MAAM,GAAG,OAAO,EAChB,UAAU,GAAG,OAAO,CAEpB,SAAQ,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,mBAAmB,CAChE,YAAW,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,UAAU,CAAC;IAE3F,SAAS,EAAE,UAAU,CAAC;IAEtB,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;IAEjD;;;OAGG;IACH,SAAS,CAAC,sBAAsB,IAAI,IAAI;IAoBxC;;;OAGG;IACH,SAAS,CAAC,kBAAkB,IAAI,MAAM,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC;IAerE,SAAS,CAAC,aAAa,IAAI,iBAAiB,CAAC,UAAU,CAAC;IAKxD;;;OAGG;IACH,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAK3F,QAAQ,CAAC,mBAAmB,IAAI,cAAc,CAAC,MAAM,CAAC;aACpC,gBAAgB,CAChC,IAAI,CAAC,EAAE,6BAA6B,GACnC,OAAO,CAAC,sBAAsB,CAAC,UAAU,CAAC,CAAC;IAE9C,kGAAkG;IAClG,YAAY,IAAI,UAAU;IAK1B;;;OAGG;IACH,SAAS,IAAI,MAAM;IAcnB,QAAQ,CAAC,eAAe,IAAI,uBAAuB;IACnD,QAAQ,CAAC,gBAAgB,IAAI,wBAAwB,CAAC,UAAU,CAAC;IAEjE;;;;OAIG;IACG,eAAe,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA8D3F;;;;;OAKG;cACa,WAAW,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBxE,iGAAiG;IACjG,SAAS,CAAC,mBAAmB,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG,SAAS;CAanF"}

package/dist/cjs/relational/core/datasources/abstract.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractRelationalDataSource = void 0;
+const ignis_kernel_1 = require("@venizia/ignis-kernel");
+const ignis_kernel_2 = require("@venizia/ignis-kernel");
+const core_1 = require("@venizia/ignis-helpers/core");
+/**
+ * SQL branch root: connector, pool, transactions. Engine-neutral - dialect and executor are
+ * declared abstract here and supplied by each engine branch.
+ *
+ * `mapSecretToSettings` is a driver-config convention, not Postgres SQL, so it belongs on this
+ * neutral base - do not move it down into `connectors/postgres`.
+ */
+class AbstractRelationalDataSource extends ignis_kernel_1.AbstractDataSource {
+    /**
+     * Lazy and idempotent: builds the driver named by `@datasource({ driver })` over the client
+     * `configure()` assigned, then the connector from it.
+     */
+    wireDriverFromMetadata() {
+        if (this.connector) {
+            return;
+        }
+        if (this.driver) {
+            this.connector = this.driver.createConnector({ schema: this.getSchema() });
+            return;
+        }
+        if (!this.client) {
+            throw (0, core_1.getError)({
+                message: `[${this.constructor.name}][wireDriverFromMetadata] No driver and no client | Assign this.client in configure(), or wire a custom driver with useDriver()`,
+            });
+        }
+        const DriverClass = this.resolveDriverClass();
+        this.useDriver({ driver: new DriverClass({ client: this.client }) });
+    }
+    /**
+     * Rejects a driver-name string from untyped JS
+     * callers: a string carries no module into the bundle.
+     */
+    resolveDriverClass() {
+        const metadata = ignis_kernel_2.MetadataRegistry.getInstance().getDataSourceMetadata({
+            target: this.constructor,
+        });
+        const driver = metadata?.driver;
+        if (typeof driver !== 'function') {
+            throw (0, core_1.getError)({
+                message: `[${this.constructor.name}][resolveDriverClass] @datasource({ driver }) must name a driver CLASS | Got: ${String(driver)} | Use \`@datasource({ driver: NodePostgresDriver })\` with \`import { NodePostgresDriver } from '@venizia/ignis-connectors/postgres/node-postgres'\`, or wire a custom driver with useDriver()`,
+            });
+        }
+        return driver;
+    }
+    resolveDriver() {
+        this.wireDriverFromMetadata();
+        return this.driver;
+    }
+    /**
+     * Assigns `this.driver` AND builds `this.connector` in one step - a
+     * driver without its connector is silently bypassed on pooled queries.
+     */
+    useDriver(opts) {
+        this.driver = opts.driver;
+        this.connector = opts.driver.createConnector({ schema: opts.schema ?? this.getSchema() });
+    }
+    /** Wires the driver on first use, so a `configure()` that only builds `this.client` is enough. */
+    getConnector() {
+        this.wireDriverFromMetadata();
+        return this.connector;
+    }
+    /**
+     * Raw driver client (`pg.Pool` / `Sql`). Throws rather
+     * than handing back an `undefined` typed as `Client`.
+     */
+    getClient() {
+        if (this.driver) {
+            return this.driver.getClient();
+        }
+        if (!this.client) {
+            throw (0, core_1.getError)({
+                message: `[${this.constructor.name}][getClient] No driver and no client | Assign this.driver in configure()`,
+            });
+        }
+        return this.client;
+    }
+    /**
+     * Soft-evicts the pool after a secret rotation: rebuilds against the rotated credentials without
+     * touching live fields, swaps atomically, then drains the old pool. On failure live state is
+     * restored, any half-built pool drained, and the error rethrown.
+     */
+    async onSecretRotated(opts) {
+        const logger = this.logger.for(this.onSecretRotated.name);
+        const oldClient = this.getClient();
+        // Snapshot so a failed rebuild restores the datasource verbatim;
+        // `settings` is copied because rotation mutates it in place.
+        const savedClient = this.client;
+        const savedSettings = { ...this.settings };
+        // Rotation only takes effect through this.settings + configure(); a configure() that
+        // hard-codes its connection string or reads Envs directly rebuilds with stale credentials.
+        Object.assign(this.settings, this.mapSecretToSettings({ secret: opts.secret }));
+        // configure() overwrites this.client, so the new pool is captured
+        // into a local and the old client restored at once - live fields
+        // are never nulled and the old pool keeps serving until the swap.
+        let newClient;
+        try {
+            await this.configure();
+            newClient = this.client;
+        }
+        catch (error) {
+            const halfBuilt = this.client;
+            this.client = savedClient;
+            Object.assign(this.settings, savedSettings);
+            if (halfBuilt && halfBuilt !== savedClient) {
+                await this.drainClient({ client: halfBuilt });
+            }
+            logger.error('Secret rotation failed in configure(); kept old pool | key: %s', opts.key);
+            throw error;
+        }
+        this.client = savedClient;
+        // Wired into locals: live state must stay on the old pool until the swap below.
+        let newDriver;
+        let newConnector;
+        try {
+            const DriverClass = this.resolveDriverClass();
+            newDriver = new DriverClass({ client: newClient });
+            newConnector = newDriver.createConnector({ schema: this.getSchema() });
+        }
+        catch (error) {
+            Object.assign(this.settings, savedSettings);
+            await this.drainClient({ client: newClient });
+            logger.error('Secret rotation failed while wiring driver; kept old pool | key: %s', opts.key);
+            throw error;
+        }
+        // Commit the live fields in one synchronous step so there is no null window,
+        // then soft-evict the old pool so its in-flight transactions can finish.
+        this.client = newClient;
+        this.driver = newDriver;
+        this.connector = newConnector;
+        const isDrained = await this.drainClient({ client: oldClient });
+        if (isDrained) {
+            logger.info('Old pool drained after secret rotation | key: %s', opts.key);
+        }
+    }
+    /**
+     * Shuts a client down by whichever verb its engine spells it with -
+     * `pg.Pool` and postgres.js have `end()`, PGlite and libsql only `close()`.
+     * Probed rather than type-tested: this tier must not name an engine, and a
+     * client left undrained keeps a WASM instance or file handle alive forever.
+     */
+    async drainClient(opts) {
+        const client = opts.client;
+        const drain = typeof client?.end === 'function' ? client.end : client?.close;
+        if (typeof drain !== 'function') {
+            this.logger
+                .for(this.drainClient.name)
+                .warn('Client exposes neither end() nor close(); nothing to drain');
+            return false;
+        }
+        await drain.call(client);
+        return true;
+    }
+    /** Vault's database engine returns `{ username, password }`; pg expects `{ user, password }`. */
+    mapSecretToSettings(opts) {
+        const { username, password } = opts.secret;
+        const mapped = {};
+        if (username !== undefined) {
+            mapped.user = username;
+        }
+        if (password !== undefined) {
+            mapped.password = password;
+        }
+        return mapped;
+    }
+}
+exports.AbstractRelationalDataSource = AbstractRelationalDataSource;
+//# sourceMappingURL=abstract.js.map

package/dist/cjs/relational/core/datasources/abstract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract.js","sourceRoot":"","sources":["../../../../../src/relational/core/datasources/abstract.ts"],"names":[],"mappings":"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"}

package/dist/cjs/relational/core/datasources/base.d.ts

@@ -0,0 +1,22 @@
+import type { TAnyDataSourceSchema } from '@venizia/ignis-kernel';
+import { AbstractRelationalDataSource } from './abstract';
+import type { IRelationalTransaction, TRelationalTransactionOptions } from './common';
+/** Base DataSource with schema auto-discovery from registered repositories. */
+export declare abstract class BaseRelationalDataSource<Settings extends object = {}, Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema, ConfigurableOptions extends object = {}, Client = unknown, TConnector = unknown> extends AbstractRelationalDataSource<Settings, Schema, ConfigurableOptions, Client, TConnector> {
+    constructor(opts: {
+        name: string;
+        config: Settings;
+        schema?: Schema;
+    });
+    /** Auto-discovers schema from repositories if not manually provided. */
+    getSchema(): Schema;
+    protected discoverSchema(): Schema;
+    hasDiscoverableModels(): boolean;
+    getCapabilities(): {
+        transactions: boolean;
+    };
+    beginTransaction(opts?: TRelationalTransactionOptions): Promise<IRelationalTransaction<TConnector>>;
+    /** The engine's own BEGIN. Postgres interpolates an isolation level; SQLite has none and uses `BEGIN IMMEDIATE`. Never parameterized - `BEGIN ... ISOLATION LEVEL $1` is not valid SQL. */
+    protected abstract buildBeginStatement(opts?: TRelationalTransactionOptions): string;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/cjs/relational/core/datasources/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../../../src/relational/core/datasources/base.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAe,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAO/E,OAAO,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,6BAA6B,EAAE,MAAM,UAAU,CAAC;AAEtF,+EAA+E;AAC/E,8BAAsB,wBAAwB,CAC5C,QAAQ,SAAS,MAAM,GAAG,EAAE,EAC5B,MAAM,SAAS,oBAAoB,GAAG,oBAAoB,EAC1D,mBAAmB,SAAS,MAAM,GAAG,EAAE,EACvC,MAAM,GAAG,OAAO,EAChB,UAAU,GAAG,OAAO,CACpB,SAAQ,4BAA4B,CAAC,QAAQ,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,UAAU,CAAC;gBACnF,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,QAAQ,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAWrE,wEAAwE;IAC/D,SAAS,IAAI,MAAM;IAK5B,SAAS,CAAC,cAAc,IAAI,MAAM;IA2BlC,qBAAqB,IAAI,OAAO;IAKvB,eAAe;;;IAIT,gBAAgB,CAC7B,IAAI,CAAC,EAAE,6BAA6B,GACnC,OAAO,CAAC,sBAAsB,CAAC,UAAU,CAAC,CAAC;IA4D9C,2LAA2L;IAC3L,SAAS,CAAC,QAAQ,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE,6BAA6B,GAAG,MAAM;CACrF"}

package/dist/cjs/relational/core/datasources/base.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseRelationalDataSource = void 0;
+const ignis_kernel_1 = require("@venizia/ignis-kernel");
+const ignis_kernel_2 = require("@venizia/ignis-kernel");
+const core_1 = require("@venizia/ignis-helpers/core");
+// Deep import, not a barrel: `discoverSchema()` below is the only production call site that needs
+// `createRelations`, so the install runs from here rather than `dialect/relation.ts` - nothing else
+// value-imports that file's `createRelations` export, and a `sideEffects: false` bundler drops an
+// unused export's module body even when it is reachable through a barrel `export *` chain (verified
+// with `bun build --target=browser`, the tool `make purity` uses).
+const relation_1 = require("../../../relational/core/repositories/dialect/relation");
+const abstract_1 = require("./abstract");
+/** Base DataSource with schema auto-discovery from registered repositories. */
+class BaseRelationalDataSource extends abstract_1.AbstractRelationalDataSource {
+    constructor(opts) {
+        super({ scope: opts.name });
+        this.name = opts.name;
+        this.settings = opts.config;
+        if (opts.schema) {
+            this.schema = opts.schema;
+        }
+    }
+    /** Auto-discovers schema from repositories if not manually provided. */
+    getSchema() {
+        this.schema ??= this.discoverSchema();
+        return this.schema;
+    }
+    discoverSchema() {
+        const registry = ignis_kernel_1.MetadataRegistry.getInstance();
+        const metadata = registry.getDataSourceMetadata({ target: this.constructor });
+        if (metadata?.autoDiscovery === false) {
+            this.logger.for(this.discoverSchema.name).debug('Auto-discovery disabled for %s', this.name);
+            return {};
+        }
+        const { schema, relations } = registry.buildSchema({
+            dataSource: this.constructor,
+        });
+        const models = Object.keys(schema);
+        this.logger
+            .for(this.discoverSchema.name)
+            .debug('Detected model(s) | Name: %s | Count: %s | Models: %j', this.name, models.length, models);
+        // buildSchema() is shared by every connector so it returns Record<string, unknown>; the cast narrows back to the Drizzle schema shape.
+        return { ...schema, ...relations };
+    }
+    hasDiscoverableModels() {
+        const registry = ignis_kernel_1.MetadataRegistry.getInstance();
+        return registry.hasModels({ dataSource: this.constructor });
+    }
+    getCapabilities() {
+        return { transactions: true };
+    }
+    async beginTransaction(opts) {
+        const driver = this.resolveDriver();
+        const connection = await driver.acquire({ schema: this.getSchema() });
+        try {
+            await connection.execute({ statement: this.buildBeginStatement(opts) });
+        }
+        catch (error) {
+            this.logger.for('beginTransaction').error('Failed to BEGIN transaction | Error: %s', error);
+            // No caller ever receives a handle to release this connection, so leaking it exhausts the pool; destroyed rather than pooled because session state after a failed BEGIN is unknown.
+            connection.release({ destroy: true });
+            throw error;
+        }
+        let isActive = true;
+        let isEndedByFailure = false;
+        /** On failure the connection is discarded rather than pooled - the next borrower would inherit an open transaction - and the error rethrown: a caller must never believe a failed COMMIT succeeded. */
+        const finish = async (finishOpts) => {
+            const { statement, verb } = finishOpts;
+            if (!isActive) {
+                // After a FAILED commit/rollback the transaction is already torn down, so rollback is satisfied by construction - throwing here would replace the caller's original error in `catch { await tx.rollback(); throw error; }`.
+                if (isEndedByFailure && verb === 'rollback') {
+                    this.logger
+                        .for(verb)
+                        .debug('Rollback after a failure-ended transaction - no-op, already torn down');
+                    return;
+                }
+                throw (0, core_1.getError)({ message: `[Transaction][${verb}] Transaction already ended` });
+            }
+            // Flipped BEFORE the await: commit racing rollback would otherwise both pass the guard, issue two control statements, and double-release the same physical connection.
+            isActive = false;
+            try {
+                await connection.execute({ statement });
+            }
+            catch (error) {
+                this.logger.for(verb).error('Failed to %s transaction | Error: %s', statement, error);
+                isEndedByFailure = true;
+                connection.release({ destroy: true });
+                throw error;
+            }
+            connection.release();
+        };
+        return {
+            connector: connection.connector,
+            get isActive() {
+                return isActive;
+            },
+            commit: () => finish({ statement: 'COMMIT', verb: 'commit' }),
+            rollback: () => finish({ statement: 'ROLLBACK', verb: 'rollback' }),
+        };
+    }
+}
+exports.BaseRelationalDataSource = BaseRelationalDataSource;
+// Runs once this module loads. Every engine (postgres, sqlite) extends `BaseRelationalDataSource`,
+// and `discoverSchema()` above is the sole caller of `resolveModelRelations()`, so this is the one
+// place guaranteed to load whenever relation building is actually needed.
+ignis_kernel_2.RelationBuilderRegistry.set({ builder: relation_1.createRelations });
+//# sourceMappingURL=base.js.map

package/dist/cjs/relational/core/datasources/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../../../src/relational/core/datasources/base.ts"],"names":[],"mappings":"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"}

package/dist/cjs/relational/core/datasources/common/guards.d.ts

@@ -0,0 +1,5 @@
+import type { ITransaction } from '@venizia/ignis-kernel';
+import type { IRelationalTransaction } from './types';
+/** Narrows the neutral `ITransaction` to a SQL transaction handle before accessing `.connector`. */
+export declare const isRelationalTransaction: (transaction: ITransaction | undefined) => transaction is IRelationalTransaction<unknown>;
+//# sourceMappingURL=guards.d.ts.map

package/dist/cjs/relational/core/datasources/common/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../../../../../src/relational/core/datasources/common/guards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAEtD,oGAAoG;AACpG,eAAO,MAAM,uBAAuB,GAClC,aAAa,YAAY,GAAG,SAAS,KACpC,WAAW,IAAI,sBAAsB,CAAC,OAAO,CAE/C,CAAC"}

package/dist/cjs/relational/core/datasources/common/guards.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRelationalTransaction = void 0;
+/** Narrows the neutral `ITransaction` to a SQL transaction handle before accessing `.connector`. */
+const isRelationalTransaction = (transaction) => {
+    return transaction !== undefined && 'connector' in transaction;
+};
+exports.isRelationalTransaction = isRelationalTransaction;
+//# sourceMappingURL=guards.js.map

package/dist/cjs/relational/core/datasources/common/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../../../../../src/relational/core/datasources/common/guards.ts"],"names":[],"mappings":";;;AAGA,oGAAoG;AAC7F,MAAM,uBAAuB,GAAG,CACrC,WAAqC,EACW,EAAE;IAClD,OAAO,WAAW,KAAK,SAAS,IAAI,WAAW,IAAI,WAAW,CAAC;AACjE,CAAC,CAAC;AAJW,QAAA,uBAAuB,2BAIlC"}

package/dist/cjs/relational/core/datasources/common/index.d.ts

@@ -0,0 +1,3 @@
+export * from './guards';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/relational/core/datasources/common/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/relational/core/datasources/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC"}

package/dist/cjs/relational/core/datasources/common/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./guards"), exports);
+__exportStar(require("./types"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/relational/core/datasources/common/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../src/relational/core/datasources/common/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,0CAAwB"}

package/dist/cjs/relational/core/datasources/common/types.d.ts

@@ -0,0 +1,24 @@
+import type { AbstractDataSource, ITransaction, ITransactionOptions, TAnyDataSourceSchema } from '@venizia/ignis-kernel';
+import type { IRelationalQueryDialect, IRelationalQueryExecutor } from '../../../../relational/core/repositories/common';
+import type { ValueOrPromise } from '@venizia/ignis-helpers/common';
+/** Neutral SQL transaction options; each engine adds its own knobs. An alias, not an empty `interface ... extends`, which `@typescript-eslint/no-empty-object-type` rejects. */
+export type TRelationalTransactionOptions = ITransactionOptions;
+export interface IRelationalTransaction<TConnector> extends ITransaction {
+    /** Bound to the transaction's own connection, whichever driver acquired it. */
+    connector: TConnector;
+    /** Throws if COMMIT fails, per {@link ITransaction.commit}. The connection is discarded where the driver supports it (node-postgres `release(error)`); postgres-js has no destroy semantics, so a poisoned connection returns to its pool. */
+    commit(): Promise<void>;
+    /** Throws if ROLLBACK fails (same connection-discard caveat as {@link commit}) - but is a silent no-op after the transaction already ended BY FAILURE, keeping `catch (error) { await transaction.rollback(); throw error; }` safe. */
+    rollback(): Promise<void>;
+}
+/** SQL-branch contract, engine-free. Extends `AbstractDataSource` itself, not just `IDataSource`, so repositories can narrow safely. `getConnectionString()` is app-implemented and never called by the framework - an embedded engine with no URL returns its data directory. */
+export interface IRelationalDataSource<Settings extends object = {}, Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema, ConfigurableOptions extends object = {}, Client = unknown, TConnector = unknown> extends AbstractDataSource<Settings, Schema, ConfigurableOptions> {
+    connector: TConnector;
+    getConnectionString(): ValueOrPromise<string>;
+    getConnector(): TConnector;
+    getClient(): Client;
+    getQueryDialect(): IRelationalQueryDialect;
+    getQueryExecutor(): IRelationalQueryExecutor<TConnector>;
+    beginTransaction(opts?: TRelationalTransactionOptions): Promise<IRelationalTransaction<TConnector>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cjs/relational/core/datasources/common/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../src/relational/core/datasources/common/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACV,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpE,gLAAgL;AAChL,MAAM,MAAM,6BAA6B,GAAG,mBAAmB,CAAC;AAEhE,MAAM,WAAW,sBAAsB,CAAC,UAAU,CAAE,SAAQ,YAAY;IACtE,+EAA+E;IAC/E,SAAS,EAAE,UAAU,CAAC;IAEtB,8OAA8O;IAC9O,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB,uOAAuO;IACvO,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,kRAAkR;AAClR,MAAM,WAAW,qBAAqB,CACpC,QAAQ,SAAS,MAAM,GAAG,EAAE,EAC5B,MAAM,SAAS,oBAAoB,GAAG,oBAAoB,EAC1D,mBAAmB,SAAS,MAAM,GAAG,EAAE,EACvC,MAAM,GAAG,OAAO,EAChB,UAAU,GAAG,OAAO,CACpB,SAAQ,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,mBAAmB,CAAC;IACjE,SAAS,EAAE,UAAU,CAAC;IAEtB,mBAAmB,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;IAC9C,YAAY,IAAI,UAAU,CAAC;IAC3B,SAAS,IAAI,MAAM,CAAC;IACpB,eAAe,IAAI,uBAAuB,CAAC;IAC3C,gBAAgB,IAAI,wBAAwB,CAAC,UAAU,CAAC,CAAC;IACzD,gBAAgB,CACd,IAAI,CAAC,EAAE,6BAA6B,GACnC,OAAO,CAAC,sBAAsB,CAAC,UAAU,CAAC,CAAC,CAAC;CAChD"}

package/dist/cjs/relational/core/datasources/common/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/relational/core/datasources/common/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../src/relational/core/datasources/common/types.ts"],"names":[],"mappings":""}

package/dist/cjs/relational/core/datasources/index.d.ts

@@ -0,0 +1,4 @@
+export * from './abstract';
+export * from './base';
+export * from './common';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/relational/core/datasources/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/relational/core/datasources/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC"}

package/dist/cjs/relational/core/datasources/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./abstract"), exports);
+__exportStar(require("./base"), exports);
+__exportStar(require("./common"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/relational/core/datasources/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/relational/core/datasources/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,yCAAuB;AACvB,2CAAyB"}

package/dist/cjs/relational/core/drivers/driver.d.ts

@@ -0,0 +1,35 @@
+import type { TAnyDataSourceSchema } from '@venizia/ignis-kernel';
+/** Neutral result of a raw statement. Each driver maps its native shape (pg `rowCount`, postgres-js `count`) at its own boundary - callers never sniff shapes at runtime. */
+export interface IStatementResult {
+    /** Rows affected - the same `count` the repository verbs return; `0` for control statements (BEGIN / COMMIT / SET LOCAL). */
+    count: number;
+}
+/** One dedicated physical connection, held for the lifetime of a single explicit transaction. */
+export interface IRelationalConnection<TConnector> {
+    /** Drizzle bound to THIS connection, not to the pool. */
+    connector: TConnector;
+    /** Runs a control statement verbatim (BEGIN / COMMIT / ROLLBACK / SET LOCAL) - never parameterized, `BEGIN ... ISOLATION LEVEL $1` is not valid SQL. Use `connector` for rows. */
+    execute(opts: {
+        statement: string;
+    }): Promise<IStatementResult>;
+    /** Rows from a verbatim statement, for the few callers that have no Drizzle schema to query through - the migration ledger is the one in-tree case. Also unparameterized: placeholder syntax is not portable (`$1` on Postgres, `?` on SQLite), so a caller needing a value must prove it is a literal. */
+    query<R>(opts: {
+        statement: string;
+    }): Promise<Array<R>>;
+    /** Returns the connection; `destroy` discards instead of pooling - required after a failed COMMIT/ROLLBACK, where the next borrower would inherit an open transaction. A driver that cannot destroy must say so in its own docs. */
+    release(opts?: {
+        destroy?: boolean;
+    }): void;
+}
+/** Owns connection acquisition and raw control statements - the only two places hard-wired to a client library. `configure()` stays app-written: the framework never builds the driver for you. */
+export interface IRelationalDriver<TConnector, Client = unknown> {
+    createConnector(opts: {
+        schema: TAnyDataSourceSchema;
+    }): TConnector;
+    acquire(opts: {
+        schema: TAnyDataSourceSchema;
+    }): Promise<IRelationalConnection<TConnector>>;
+    getClient(): Client;
+    end(): Promise<void>;
+}
+//# sourceMappingURL=driver.d.ts.map

package/dist/cjs/relational/core/drivers/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../../../../src/relational/core/drivers/driver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAElE,6KAA6K;AAC7K,MAAM,WAAW,gBAAgB;IAC/B,6HAA6H;IAC7H,KAAK,EAAE,MAAM,CAAC;CACf;AAED,iGAAiG;AACjG,MAAM,WAAW,qBAAqB,CAAC,UAAU;IAC/C,yDAAyD;IACzD,SAAS,EAAE,UAAU,CAAC;IAEtB,kLAAkL;IAClL,OAAO,CAAC,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEhE,2SAA2S;IAC3S,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAEzD,oOAAoO;IACpO,OAAO,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CAC7C;AAED,mMAAmM;AACnM,MAAM,WAAW,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAC7D,eAAe,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,oBAAoB,CAAA;KAAE,GAAG,UAAU,CAAC;IACpE,OAAO,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,oBAAoB,CAAA;KAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC,UAAU,CAAC,CAAC,CAAC;IAC5F,SAAS,IAAI,MAAM,CAAC;IACpB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB"}

package/dist/cjs/relational/core/drivers/driver.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=driver.js.map

package/dist/cjs/relational/core/drivers/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../../../../../src/relational/core/drivers/driver.ts"],"names":[],"mappings":""}

package/dist/cjs/relational/core/drivers/index.d.ts

@@ -0,0 +1,2 @@
+export * from './driver';
+//# sourceMappingURL=index.d.ts.map