sqlstack 1.0.25 → 3.0.0

package/dist/cjs/index.js

@@ -14,7 +14,7 @@ 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 });
-exports.SqlStackDB = exports.SqlFragment = exports.sql = void 0;
+exports.SourceScanResolver = exports.MANIFEST_DIALECT_EXT = exports.ManifestResolver = exports.FsResolver = exports.sqliteFamily = exports.FamilyRuntime = exports.resolveExecution = exports.activeSqlStack = exports.SqlStack = exports.SqlStackDB = exports.SqlFragment = exports.sql = void 0;
 // SQL Template Strings
 var sql_1 = require("./sql");
 Object.defineProperty(exports, "sql", { enumerable: true, get: function () { return sql_1.sql; } });
@@ -38,6 +38,23 @@ __exportStar(require("./core/validator"), exports);
 __exportStar(require("./utils/dto"), exports);
 var registry_1 = require("./registry");
 Object.defineProperty(exports, "SqlStackDB", { enumerable: true, get: function () { return registry_1.SqlStackDB; } });
+// Environment-owned runtime (v3): per-root SqlStack + active-context resolution
+var stack_1 = require("./stack");
+Object.defineProperty(exports, "SqlStack", { enumerable: true, get: function () { return stack_1.SqlStack; } });
+var runtime_1 = require("./runtime");
+Object.defineProperty(exports, "activeSqlStack", { enumerable: true, get: function () { return runtime_1.activeSqlStack; } });
+Object.defineProperty(exports, "resolveExecution", { enumerable: true, get: function () { return runtime_1.resolveExecution; } });
+// Dynamic database families (spec 17)
+var family_1 = require("./family");
+Object.defineProperty(exports, "FamilyRuntime", { enumerable: true, get: function () { return family_1.FamilyRuntime; } });
+var sqliteFamily_1 = require("./families/sqliteFamily");
+Object.defineProperty(exports, "sqliteFamily", { enumerable: true, get: function () { return sqliteFamily_1.sqliteFamily; } });
+var resolver_1 = require("./core/resolver");
+Object.defineProperty(exports, "FsResolver", { enumerable: true, get: function () { return resolver_1.FsResolver; } });
+Object.defineProperty(exports, "ManifestResolver", { enumerable: true, get: function () { return resolver_1.ManifestResolver; } });
+Object.defineProperty(exports, "MANIFEST_DIALECT_EXT", { enumerable: true, get: function () { return resolver_1.MANIFEST_DIALECT_EXT; } });
+var sourceScanResolver_1 = require("./core/sourceScanResolver");
+Object.defineProperty(exports, "SourceScanResolver", { enumerable: true, get: function () { return sourceScanResolver_1.SourceScanResolver; } });
 // Legacy exports (kept for backward compatibility)
 __exportStar(require("./binders/sqlBinder"), exports);
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,uBAAuB;AACvB,6BAAyC;AAAhC,0FAAA,GAAG,OAAA;AAAE,kGAAA,WAAW,OAAA;AAEzB,aAAa;AACb,2DAAyC;AACzC,qDAAmC;AACnC,wDAAsC;AACtC,2DAAyC;AACzC,8DAA4C;AAC5C,yDAAuC;AACvC,oDAAkC;AAElC,eAAe;AACf,iDAA+B;AAE/B,WAAW;AACX,6CAA2B;AAE3B,wBAAwB;AACxB,gDAA8B;AAC9B,mDAAiC;AAEjC,aAAa;AACb,8CAA4B;AAI5B,uCAAkD;AAAzC,sGAAA,UAAU,OAAA;AAEnB,mDAAmD;AACnD,sDAAoC","sourcesContent":["// SQL Template Strings\nexport { sql, SqlFragment } from './sql';\n\n// Decorators\nexport * from './decorators/queryBinder';\nexport * from './decorators/query';\nexport * from './decorators/defaults';\nexport * from './decorators/resultShape';\nexport * from './decorators/validateResult';\nexport * from './decorators/transform';\nexport * from './decorators/page';\n\n// Transactions\nexport * from './transactions';\n\n// Adapters\nexport * from './adapters';\n\n// Errors and Validation\nexport * from './core/errors';\nexport * from './core/validator';\n\n// DTO Helper\nexport * from './utils/dto';\n\n// Database Registry and Types\nexport type { Dialect, WriteResult, PostgresWriteResult, QueryResult, Database } from './registry';\nexport { SqlStackDB, IStackDB } from './registry';\n\n// Legacy exports (kept for backward compatibility)\nexport * from './binders/sqlBinder';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,uBAAuB;AACvB,6BAAyC;AAAhC,0FAAA,GAAG,OAAA;AAAE,kGAAA,WAAW,OAAA;AAEzB,aAAa;AACb,2DAAyC;AACzC,qDAAmC;AACnC,wDAAsC;AACtC,2DAAyC;AACzC,8DAA4C;AAC5C,yDAAuC;AACvC,oDAAkC;AAElC,eAAe;AACf,iDAA+B;AAE/B,WAAW;AACX,6CAA2B;AAE3B,wBAAwB;AACxB,gDAA8B;AAC9B,mDAAiC;AAEjC,aAAa;AACb,8CAA4B;AAI5B,uCAAkD;AAAzC,sGAAA,UAAU,OAAA;AAEnB,gFAAgF;AAChF,iCAAmC;AAA1B,iGAAA,QAAQ,OAAA;AAEjB,qCAA6D;AAApD,yGAAA,cAAc,OAAA;AAAE,2GAAA,gBAAgB,OAAA;AAEzC,sCAAsC;AACtC,mCAAyC;AAAhC,uGAAA,aAAa,OAAA;AAQtB,wDAAuD;AAA9C,4GAAA,YAAY,OAAA;AAKrB,4CAAqF;AAA5E,sGAAA,UAAU,OAAA;AAAE,4GAAA,gBAAgB,OAAA;AAAE,gHAAA,oBAAoB,OAAA;AAC3D,gEAA+D;AAAtD,wHAAA,kBAAkB,OAAA;AAE3B,mDAAmD;AACnD,sDAAoC","sourcesContent":["// SQL Template Strings\nexport { sql, SqlFragment } from './sql';\n\n// Decorators\nexport * from './decorators/queryBinder';\nexport * from './decorators/query';\nexport * from './decorators/defaults';\nexport * from './decorators/resultShape';\nexport * from './decorators/validateResult';\nexport * from './decorators/transform';\nexport * from './decorators/page';\n\n// Transactions\nexport * from './transactions';\n\n// Adapters\nexport * from './adapters';\n\n// Errors and Validation\nexport * from './core/errors';\nexport * from './core/validator';\n\n// DTO Helper\nexport * from './utils/dto';\n\n// Database Registry and Types\nexport type { Dialect, WriteResult, PostgresWriteResult, QueryResult, Database } from './registry';\nexport { SqlStackDB, IStackDB } from './registry';\n\n// Environment-owned runtime (v3): per-root SqlStack + active-context resolution\nexport { SqlStack } from './stack';\nexport type { DatabaseEntry, DatabaseRegistration, SqlStackConfig } from './stack';\nexport { activeSqlStack, resolveExecution } from './runtime';\n\n// Dynamic database families (spec 17)\nexport { FamilyRuntime } from './family';\nexport type {\n  DatabaseFamilyProvider,\n  FamilyConfig,\n  FamilyMemberEntry,\n  DatabaseLease,\n  DatabaseInspection,\n} from './family';\nexport { sqliteFamily } from './families/sqliteFamily';\nexport type { SqliteFamilyOptions } from './families/sqliteFamily';\n\n// SQL Resolvers (v2): pluggable SQL source resolution\nexport type { SqlResolver, SqlManifest, SqlResolutionRequest, ManifestResolverOptions } from './core/resolver';\nexport { FsResolver, ManifestResolver, MANIFEST_DIALECT_EXT } from './core/resolver';\nexport { SourceScanResolver } from './core/sourceScanResolver';\n\n// Legacy exports (kept for backward compatibility)\nexport * from './binders/sqlBinder';\n"]}

package/dist/cjs/ioc.d.ts

@@ -0,0 +1,22 @@
+import type { IContainerSetup } from '@noego/ioc';
+import { SqlStackConfig } from './stack';
+/**
+ * Root composition for SQLStack (repo spec 19 §6).
+ *
+ * Registers a per-root SqlStack Singleton built from normalized application
+ * configuration. Different roots in one process may register different
+ * database URLs/resolvers concurrently; child scopes resolve the owning
+ * root's instance under normal IoC semantics.
+ *
+ * This module is the only sqlstack module that imports @noego/ioc statically;
+ * core query execution reaches the active root through the IoC execution
+ * context without a hard dependency.
+ *
+ * Lifecycle: the returned dispose function closes SqlStack-owned database
+ * adapters. Call it when disposing the root (or wire it into the root's
+ * disposal hook where the container version supports one).
+ */
+export declare function registerSqlStack(container: IContainerSetup, config: SqlStackConfig | (() => SqlStackConfig)): {
+    dispose: () => Promise<void>;
+};
+//# sourceMappingURL=ioc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ioc.d.ts","sourceRoot":"","sources":["../../src/ioc.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAY,cAAc,EAAE,MAAM,SAAS,CAAC;AAEnD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,eAAe,EAC1B,MAAM,EAAE,cAAc,GAAG,CAAC,MAAM,cAAc,CAAC,GAC9C;IAAE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAelC"}

package/dist/cjs/ioc.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSqlStack = registerSqlStack;
+const ioc_1 = require("@noego/ioc");
+const stack_1 = require("./stack");
+/**
+ * Root composition for SQLStack (repo spec 19 §6).
+ *
+ * Registers a per-root SqlStack Singleton built from normalized application
+ * configuration. Different roots in one process may register different
+ * database URLs/resolvers concurrently; child scopes resolve the owning
+ * root's instance under normal IoC semantics.
+ *
+ * This module is the only sqlstack module that imports @noego/ioc statically;
+ * core query execution reaches the active root through the IoC execution
+ * context without a hard dependency.
+ *
+ * Lifecycle: the returned dispose function closes SqlStack-owned database
+ * adapters. Call it when disposing the root (or wire it into the root's
+ * disposal hook where the container version supports one).
+ */
+function registerSqlStack(container, config) {
+    let instance;
+    container.registerFunction(stack_1.SqlStack, () => {
+        instance = new stack_1.SqlStack(typeof config === 'function' ? config() : config);
+        return instance;
+    }, { loadAs: ioc_1.LoadAs.Singleton });
+    return {
+        dispose: async () => {
+            if (instance)
+                await instance.close();
+        },
+    };
+}
+//# sourceMappingURL=ioc.js.map

package/dist/cjs/ioc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ioc.js","sourceRoot":"","sources":["../../src/ioc.ts"],"names":[],"mappings":";;AAoBA,4CAkBC;AAtCD,oCAAoC;AAEpC,mCAAmD;AAEnD;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,gBAAgB,CAC9B,SAA0B,EAC1B,MAA+C;IAE/C,IAAI,QAA8B,CAAC;IAClC,SAAiB,CAAC,gBAAgB,CACjC,gBAAQ,EACR,GAAG,EAAE;QACH,QAAQ,GAAG,IAAI,gBAAQ,CAAC,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAC1E,OAAO,QAAQ,CAAC;IAClB,CAAC,EACD,EAAE,MAAM,EAAE,YAAM,CAAC,SAAS,EAAE,CAC7B,CAAC;IACF,OAAO;QACL,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,IAAI,QAAQ;gBAAE,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAC;QACvC,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import { LoadAs } from '@noego/ioc';\nimport type { IContainerSetup } from '@noego/ioc';\nimport { SqlStack, SqlStackConfig } from './stack';\n\n/**\n * Root composition for SQLStack (repo spec 19 §6).\n *\n * Registers a per-root SqlStack Singleton built from normalized application\n * configuration. Different roots in one process may register different\n * database URLs/resolvers concurrently; child scopes resolve the owning\n * root's instance under normal IoC semantics.\n *\n * This module is the only sqlstack module that imports @noego/ioc statically;\n * core query execution reaches the active root through the IoC execution\n * context without a hard dependency.\n *\n * Lifecycle: the returned dispose function closes SqlStack-owned database\n * adapters. Call it when disposing the root (or wire it into the root's\n * disposal hook where the container version supports one).\n */\nexport function registerSqlStack(\n  container: IContainerSetup,\n  config: SqlStackConfig | (() => SqlStackConfig)\n): { dispose: () => Promise<void> } {\n  let instance: SqlStack | undefined;\n  (container as any).registerFunction(\n    SqlStack,\n    () => {\n      instance = new SqlStack(typeof config === 'function' ? config() : config);\n      return instance;\n    },\n    { loadAs: LoadAs.Singleton }\n  );\n  return {\n    dispose: async () => {\n      if (instance) await instance.close();\n    },\n  };\n}\n"]}

package/dist/cjs/runtime.d.ts

@@ -0,0 +1,25 @@
+import { SqlStack, DatabaseEntry } from './stack';
+import type { SqlResolver } from './core/resolver';
+/** @internal Test-only: force re-detection of @noego/ioc. */
+export declare function __resetIocDetection(): void;
+/**
+ * The SqlStack for the active IoC execution context, or undefined when no
+ * IoC environment is active (or @noego/ioc is not installed).
+ *
+ * Throws when an environment IS active but has no SqlStack registered —
+ * silently falling back to global state under an active root is forbidden.
+ */
+export declare function activeSqlStack(): Promise<SqlStack | undefined>;
+export type ResolvedExecution = {
+    entry: DatabaseEntry;
+    resolver: SqlResolver | undefined;
+    /** True when resolved through an active IoC root's SqlStack. */
+    viaStack: boolean;
+};
+/**
+ * Resolve the concrete database entry (and SQL resolver) for one execution.
+ */
+export declare function resolveExecution(dbName?: string): Promise<ResolvedExecution>;
+/** @internal Resolve a legacy global-registry database as a DatabaseEntry. */
+export declare function legacyEntry(dbName?: string): DatabaseEntry;
+//# sourceMappingURL=runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGlD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAmCnD,6DAA6D;AAC7D,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAsBpE;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,WAAW,GAAG,SAAS,CAAC;IAClC,gEAAgE;IAChE,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAUlF;AAyBD,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAQ1D"}

package/dist/cjs/runtime.js

@@ -0,0 +1,133 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__resetIocDetection = __resetIocDetection;
+exports.activeSqlStack = activeSqlStack;
+exports.resolveExecution = resolveExecution;
+exports.legacyEntry = legacyEntry;
+const stack_1 = require("./stack");
+const registry_1 = require("./registry");
+const resolver_1 = require("./core/resolver");
+const errors_1 = require("./core/errors");
+// @noego/ioc is an optional peer: sqlstack remains usable standalone. The
+// import is dynamic so the CJS and ESM builds both work and so a missing
+// peer only disables the IoC path instead of breaking module load.
+let iocModulePromise;
+function loadIoc() {
+    iocModulePromise ?? (iocModulePromise = Promise.resolve().then(() => __importStar(require('@noego/ioc'))).then((m) => (m?.ExecutionContext ? m : undefined), () => undefined));
+    return iocModulePromise;
+}
+/** @internal Test-only: force re-detection of @noego/ioc. */
+function __resetIocDetection() {
+    iocModulePromise = undefined;
+}
+/**
+ * The SqlStack for the active IoC execution context, or undefined when no
+ * IoC environment is active (or @noego/ioc is not installed).
+ *
+ * Throws when an environment IS active but has no SqlStack registered —
+ * silently falling back to global state under an active root is forbidden.
+ */
+async function activeSqlStack() {
+    const ioc = await loadIoc();
+    if (!ioc)
+        return undefined;
+    const scope = ioc.ExecutionContext.current();
+    if (!scope)
+        return undefined;
+    try {
+        return (await scope.get(stack_1.SqlStack));
+    }
+    catch (err) {
+        if (err?.constructor?.name === 'DependencyNotFoundError') {
+            // Migration compatibility: a root with NO SqlStack registered may fall
+            // back to the deprecated global registry — that is not legacy state
+            // overriding a configured root, because the root configured nothing.
+            // A root that HAS a SqlStack is always authoritative.
+            if (hasLegacyDefault())
+                return undefined;
+            throw new errors_1.SqlStackError('An IoC execution environment is active, but no SqlStack is registered in it ' +
+                'and no legacy SqlStackDB default exists. Register a SqlStack at root ' +
+                'composition (see registerSqlStack in "sqlstack/ioc").');
+        }
+        throw err;
+    }
+}
+/**
+ * Resolve the concrete database entry (and SQL resolver) for one execution.
+ */
+async function resolveExecution(dbName) {
+    const stack = await activeSqlStack();
+    if (stack) {
+        return { entry: await stack.resolveEntry(dbName), resolver: stack.resolver(), viaStack: true };
+    }
+    return {
+        entry: legacyEntry(dbName),
+        resolver: (0, resolver_1.getActiveResolver)(),
+        viaStack: false,
+    };
+}
+// ---------------------------------------------------------------------------
+// Legacy (deprecated) global-registry support
+// ---------------------------------------------------------------------------
+// Stable DatabaseEntry identities for the legacy global registry, so the
+// entry-keyed transaction store works identically on both paths. Keyed by
+// name AND database object so re-registration under a name yields a fresh
+// identity (matching the fresh underlying connection).
+const legacyEntries = new Map();
+// One shared legacy pseudo-stack so legacy entries carry a stack identity for
+// diagnostics. It is intentionally NOT usable as a real stack.
+let legacyStack;
+function hasLegacyDefault() {
+    try {
+        registry_1.SqlStackDB.getEntry();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** @internal Resolve a legacy global-registry database as a DatabaseEntry. */
+function legacyEntry(dbName) {
+    const { name, db } = registry_1.SqlStackDB.getEntry(dbName);
+    const cached = legacyEntries.get(name);
+    if (cached && cached.db === db)
+        return cached.entry;
+    legacyStack ?? (legacyStack = new stack_1.SqlStack());
+    const entry = { name, db, owned: false, stack: legacyStack };
+    legacyEntries.set(name, { db, entry });
+    return entry;
+}
+//# sourceMappingURL=runtime.js.map

package/dist/cjs/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"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","sourcesContent":["import { SqlStack, DatabaseEntry } from './stack';\nimport { SqlStackDB } from './registry';\nimport type { Database } from './registry';\nimport type { SqlResolver } from './core/resolver';\nimport { getActiveResolver } from './core/resolver';\nimport { SqlStackError } from './core/errors';\n\n/**\n * Active-environment resolution for @Query and transactions (spec 16 §17,\n * repo spec 19 §7/§9).\n *\n * Canonical path: the active IoC execution context (owned by @noego/ioc)\n * supplies the current scope; the scope resolves its root's SqlStack\n * Singleton. When an IoC environment is active, the process-global legacy\n * registry is NEVER consulted — legacy state cannot override an active root.\n *\n * Legacy path: with no active IoC environment, execution falls back to the\n * deprecated process-global SqlStackDB registry so existing consumers keep\n * working during migration.\n */\n\ntype IocModule = {\n  ExecutionContext: { current(): any };\n};\n\n// @noego/ioc is an optional peer: sqlstack remains usable standalone. The\n// import is dynamic so the CJS and ESM builds both work and so a missing\n// peer only disables the IoC path instead of breaking module load.\nlet iocModulePromise: Promise<IocModule | undefined> | undefined;\n\nfunction loadIoc(): Promise<IocModule | undefined> {\n  iocModulePromise ??= import('@noego/ioc').then(\n    (m: any) => (m?.ExecutionContext ? (m as IocModule) : undefined),\n    () => undefined\n  );\n  return iocModulePromise;\n}\n\n/** @internal Test-only: force re-detection of @noego/ioc. */\nexport function __resetIocDetection(): void {\n  iocModulePromise = undefined;\n}\n\n/**\n * The SqlStack for the active IoC execution context, or undefined when no\n * IoC environment is active (or @noego/ioc is not installed).\n *\n * Throws when an environment IS active but has no SqlStack registered —\n * silently falling back to global state under an active root is forbidden.\n */\nexport async function activeSqlStack(): Promise<SqlStack | undefined> {\n  const ioc = await loadIoc();\n  if (!ioc) return undefined;\n  const scope = ioc.ExecutionContext.current();\n  if (!scope) return undefined;\n  try {\n    return (await scope.get(SqlStack)) as SqlStack;\n  } catch (err: any) {\n    if (err?.constructor?.name === 'DependencyNotFoundError') {\n      // Migration compatibility: a root with NO SqlStack registered may fall\n      // back to the deprecated global registry — that is not legacy state\n      // overriding a configured root, because the root configured nothing.\n      // A root that HAS a SqlStack is always authoritative.\n      if (hasLegacyDefault()) return undefined;\n      throw new SqlStackError(\n        'An IoC execution environment is active, but no SqlStack is registered in it ' +\n          'and no legacy SqlStackDB default exists. Register a SqlStack at root ' +\n          'composition (see registerSqlStack in \"sqlstack/ioc\").'\n      );\n    }\n    throw err;\n  }\n}\n\nexport type ResolvedExecution = {\n  entry: DatabaseEntry;\n  resolver: SqlResolver | undefined;\n  /** True when resolved through an active IoC root's SqlStack. */\n  viaStack: boolean;\n};\n\n/**\n * Resolve the concrete database entry (and SQL resolver) for one execution.\n */\nexport async function resolveExecution(dbName?: string): Promise<ResolvedExecution> {\n  const stack = await activeSqlStack();\n  if (stack) {\n    return { entry: await stack.resolveEntry(dbName), resolver: stack.resolver(), viaStack: true };\n  }\n  return {\n    entry: legacyEntry(dbName),\n    resolver: getActiveResolver(),\n    viaStack: false,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Legacy (deprecated) global-registry support\n// ---------------------------------------------------------------------------\n\n// Stable DatabaseEntry identities for the legacy global registry, so the\n// entry-keyed transaction store works identically on both paths. Keyed by\n// name AND database object so re-registration under a name yields a fresh\n// identity (matching the fresh underlying connection).\nconst legacyEntries = new Map<string, { db: Database; entry: DatabaseEntry }>();\n\n// One shared legacy pseudo-stack so legacy entries carry a stack identity for\n// diagnostics. It is intentionally NOT usable as a real stack.\nlet legacyStack: SqlStack | undefined;\n\nfunction hasLegacyDefault(): boolean {\n  try {\n    SqlStackDB.getEntry();\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/** @internal Resolve a legacy global-registry database as a DatabaseEntry. */\nexport function legacyEntry(dbName?: string): DatabaseEntry {\n  const { name, db } = SqlStackDB.getEntry(dbName);\n  const cached = legacyEntries.get(name);\n  if (cached && cached.db === db) return cached.entry;\n  legacyStack ??= new SqlStack();\n  const entry: DatabaseEntry = { name, db, owned: false, stack: legacyStack };\n  legacyEntries.set(name, { db, entry });\n  return entry;\n}\n"]}

package/dist/cjs/stack.d.ts

@@ -0,0 +1,101 @@
+import type { Database } from './registry';
+import type { SqlResolver } from './core/resolver';
+import { FamilyRuntime } from './family';
+import type { FamilyConfig } from './family';
+/**
+ * Concrete database identity inside one SqlStack instance.
+ *
+ * The entry OBJECT is the identity: two roots that both register a database
+ * under the name "primary" produce two distinct DatabaseEntry instances, so
+ * transaction lookup, caches, and diagnostics keyed by entry can never collide
+ * across roots merely because the registration text matches.
+ *
+ * Dynamic database families (spec 17) extend this identity with a normalized
+ * key; a static database is the no-key case.
+ */
+export interface DatabaseEntry {
+    readonly name: string;
+    readonly db: Database;
+    /** Close() closes owned databases; externally supplied ones are left open. */
+    readonly owned: boolean;
+    /** The stack this entry belongs to, for diagnostics and mismatch checks. */
+    readonly stack: SqlStack;
+}
+export type DatabaseRegistration = Database | {
+    db: Database | (() => Database);
+    /** Default false for direct Database values, true for factories. */
+    owned?: boolean;
+};
+export interface SqlStackConfig {
+    databases?: Record<string, DatabaseRegistration>;
+    /** Name of the default database. Required when more than one is registered. */
+    default?: string;
+    resolver?: SqlResolver;
+}
+/**
+ * Environment-owned SQLStack runtime (spec 16 §12-13, repo spec 19 §3-5).
+ *
+ * One instance per owning IoC root; child scopes resolve the root's Singleton.
+ * Native @Query/transaction/resolver execution goes through an instance —
+ * never through the process-global SqlStackDB registry.
+ */
+export declare class SqlStack {
+    #private;
+    /**
+     * @deprecated Legacy v2 process-global resolver registration
+     * (`SqlStack.useResolver(...)`). Forwards to the deprecated global state,
+     * which is only consulted when no IoC environment is active. Use the
+     * per-instance `useResolver` / SqlStackConfig.resolver instead.
+     */
+    static useResolver(resolver: SqlResolver): void;
+    /** @deprecated See static useResolver. */
+    static clearResolver(): void;
+    constructor(config?: SqlStackConfig);
+    register(name: string, db: Database, options?: {
+        owned?: boolean;
+        default?: boolean;
+    }): this;
+    setDefault(name: string): this;
+    getEntry(name?: string): DatabaseEntry;
+    database(name?: string): Database;
+    has(name: string): boolean;
+    /**
+     * Register a dynamic database family (spec 17): one registration whose
+     * concrete member is selected per execution flow via withDatabase(...).
+     */
+    registerFamily<K = string>(name: string, config: FamilyConfig<K>): this;
+    family<K = string>(name: string): FamilyRuntime<K>;
+    /**
+     * Bind a family registration to a concrete member for the duration of fn
+     * (spec 17 §10). The binding is flow-local to this SqlStack; the member's
+     * connection is leased lazily on first database resolution and released
+     * when fn settles. Rebinding a family to a different key while it has an
+     * active transaction fails deterministically (spec 17 §29).
+     */
+    withDatabase<T>(family: string, key: unknown, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Async database resolution for query/transaction execution. Static
+     * registrations resolve directly; family registrations resolve through the
+     * active flow-local binding, opening/leasing the member on first use.
+     */
+    resolveEntry(name?: string): Promise<DatabaseEntry>;
+    /**
+     * Set this stack's SQL resolver. When `options.classes` supplies the
+     * repository catalog, manifest coverage is validated from those classes'
+     * immutable metadata (environment-local, unpollutable by unrelated
+     * imports). Without a catalog, coverage falls back to the deprecated
+     * process-global decorated list.
+     */
+    useResolver(resolver: SqlResolver, options?: {
+        classes?: ReadonlyArray<abstract new (...args: any[]) => any>;
+    }): this;
+    resolver(): SqlResolver | undefined;
+    get closed(): boolean;
+    /**
+     * Close owned database adapters exactly once and release runtime resources.
+     * Externally supplied databases (owned: false) are not touched. Failures are
+     * collected and reported with database identity rather than swallowed.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=stack.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stack.d.ts","sourceRoot":"","sources":["../../src/stack.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AASnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAoC,MAAM,UAAU,CAAC;AAG/E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;CAC1B;AAED,MAAM,MAAM,oBAAoB,GAC5B,QAAQ,GACR;IACE,EAAE,EAAE,QAAQ,GAAG,CAAC,MAAM,QAAQ,CAAC,CAAC;IAChC,oEAAoE;IACpE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEN,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IACjD,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED;;;;;;GAMG;AACH,qBAAa,QAAQ;;IACnB;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI;IAI/C,0CAA0C;IAC1C,MAAM,CAAC,aAAa,IAAI,IAAI;gBAUhB,MAAM,CAAC,EAAE,cAAc;IAenC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAW5F,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAW9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,aAAa;IAiBtC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ;IAIjC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;;OAGG;IACH,cAAc,CAAC,CAAC,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IASvE,MAAM,CAAC,CAAC,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC;IAYlD;;;;;;OAMG;IACG,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAwBrF;;;;OAIG;IACG,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAgCzD;;;;;;OAMG;IACH,WAAW,CACT,QAAQ,EAAE,WAAW,EACrB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,CAAA;KAAE,GAC1E,IAAI;IAaP,QAAQ,IAAI,WAAW,GAAG,SAAS;IAInC,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAwC7B"}