@this-npm-test-org/sql-driver-sdk 0.1.0

package/dist/src/driver-registry.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { DriverDescriptor as TypesDriverDescriptor, DriverRegistry as DriverRegistryShape, RuntimeLogger as Logger, SqlDriver } from '@amodalai/types';
+/**
+ * `amodalDriver` block as it appears in a package's `package.json`.
+ * The discovery scanner validates that all required fields are
+ * present and well-typed before producing a descriptor.
+ */
+export interface DriverDescriptor {
+    /** npm package name (`@amodalai/postgres-driver`). */
+    packageName: string;
+    /** Dialect names this driver claims to handle. The runtime checks
+        `connection.dialect` against this list at load. */
+    dialects: string[];
+    /** Connection protocol — always `'sql'` for now, but reserved so
+        future protocols can reuse this discovery surface. */
+    protocol: 'sql';
+    /** Absolute path to the package directory inside node_modules. */
+    packageDir: string;
+    /** Absolute path to the JS entry the runtime dynamic-imports. */
+    moduleEntry: string;
+    /** Named export inside `moduleEntry` that returns a `SqlDriver`. */
+    exportName: string;
+    /** Range of `@amodalai/sql-driver-sdk` versions the driver was
+        built against. The runtime checks compatibility before invoking
+        the factory. */
+    sdkVersion: string;
+}
+export interface DiscoverDriversOptions {
+    /** Absolute path to the agent repo root (the directory containing
+        `node_modules`). */
+    repoPath: string;
+    /** Candidate package names to inspect. Sourced from the agent's
+        `packages` array in `amodal.json`. Packages without an
+        `amodalDriver` block are silently skipped. */
+    candidatePackages: string[];
+    logger: Logger;
+}
+/**
+ * Scan candidate packages for `amodalDriver` blocks and return
+ * descriptors. Packages missing the block are skipped silently;
+ * packages whose block is malformed throw `SqlRegistryError`.
+ */
+export declare function discoverDrivers(opts: DiscoverDriversOptions): DriverDescriptor[];
+/**
+ * Registry of discovered SQL drivers. Built once per agent-bundle load
+ * and queried per connection at runtime. Implements the
+ * `DriverRegistry` shape from `@amodalai/types` so it can be attached
+ * to `AgentBundle.sqlDrivers` and consumed across packages without
+ * importing concrete classes.
+ */
+export declare class DriverRegistry implements DriverRegistryShape {
+    private readonly byName;
+    private readonly logger;
+    constructor(descriptors: DriverDescriptor[], logger: Logger);
+    list(): TypesDriverDescriptor[];
+    has(packageName: string): boolean;
+    get(packageName: string): DriverDescriptor | undefined;
+    /**
+     * Dynamic-import the descriptor's module, call the named factory,
+     * and return the resulting `SqlDriver`. Each call produces a fresh
+     * instance — drivers are not cached at the registry layer; the
+     * caller (typically the repo loader) owns lifecycle.
+     */
+    loadDriver(packageName: string): Promise<SqlDriver>;
+}

package/dist/src/driver-registry.js

@@ -0,0 +1,192 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Discovery and loading of SQL drivers published as npm packages.
+ *
+ * A driver opts in by declaring an `amodalDriver` block in its
+ * `package.json`. The runtime scans installed packages for these
+ * blocks at agent-bundle load and builds a `DriverRegistry`. At
+ * connection load, the registry dynamic-imports the named module and
+ * calls the declared zero-arg factory export, which returns a fresh
+ * `SqlDriver` instance. The runtime then calls `driver.init(config,
+ * parsers)` to wire it up — capabilities come back from the handshake,
+ * not from the descriptor.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { SqlRegistryError } from './errors.js';
+/**
+ * Scan candidate packages for `amodalDriver` blocks and return
+ * descriptors. Packages missing the block are skipped silently;
+ * packages whose block is malformed throw `SqlRegistryError`.
+ */
+export function discoverDrivers(opts) {
+    const descriptors = [];
+    for (const packageName of opts.candidatePackages) {
+        const descriptor = readDriverDescriptor(packageName, opts.repoPath);
+        if (descriptor) {
+            descriptors.push(descriptor);
+            opts.logger.info('sql_driver_discovered', {
+                package: descriptor.packageName,
+                dialects: descriptor.dialects,
+                sdk_version: descriptor.sdkVersion,
+            });
+        }
+    }
+    return descriptors;
+}
+function readDriverDescriptor(packageName, repoPath) {
+    const packageDir = path.join(repoPath, 'node_modules', ...packageName.split('/'));
+    const pkgJsonPath = path.join(packageDir, 'package.json');
+    if (!existsSync(pkgJsonPath)) {
+        return undefined;
+    }
+    const pkgJson = parsePackageJson(pkgJsonPath, packageName);
+    const block = pkgJson['amodalDriver'];
+    if (block === undefined) {
+        return undefined;
+    }
+    return validateDriverDescriptor(block, packageName, packageDir);
+}
+function validateDriverDescriptor(block, packageName, packageDir) {
+    if (typeof block !== 'object' || block === null || Array.isArray(block)) {
+        throw new SqlRegistryError('INVALID_DESCRIPTOR', `Package "${packageName}" has an amodalDriver field that is not an object`, { kind: 'driver', packageName });
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- narrowed by the typeof/null/array guards above.
+    const raw = block;
+    const protocol = raw['protocol'];
+    if (protocol !== 'sql') {
+        throw new SqlRegistryError('INVALID_DESCRIPTOR', `Package "${packageName}" amodalDriver.protocol must be "sql"`, { kind: 'driver', packageName, context: { protocol } });
+    }
+    const dialects = raw['dialects'];
+    if (!Array.isArray(dialects) ||
+        dialects.length === 0 ||
+        !dialects.every((d) => typeof d === 'string')) {
+        throw new SqlRegistryError('INVALID_DESCRIPTOR', `Package "${packageName}" amodalDriver.dialects must be a non-empty string array`, { kind: 'driver', packageName });
+    }
+    const moduleRel = raw['module'];
+    if (typeof moduleRel !== 'string' || moduleRel.length === 0) {
+        throw new SqlRegistryError('INVALID_DESCRIPTOR', `Package "${packageName}" amodalDriver.module must be a relative path string`, { kind: 'driver', packageName });
+    }
+    const moduleEntry = path.resolve(packageDir, moduleRel);
+    if (!moduleEntry.startsWith(path.resolve(packageDir))) {
+        throw new SqlRegistryError('INVALID_DESCRIPTOR', `Package "${packageName}" amodalDriver.module escapes the package directory`, { kind: 'driver', packageName, context: { moduleRel } });
+    }
+    const exportName = raw['exportName'];
+    if (typeof exportName !== 'string' || exportName.length === 0) {
+        throw new SqlRegistryError('INVALID_DESCRIPTOR', `Package "${packageName}" amodalDriver.exportName must be a non-empty string`, { kind: 'driver', packageName });
+    }
+    const sdkVersion = raw['sdkVersion'];
+    if (typeof sdkVersion !== 'string' || sdkVersion.length === 0) {
+        throw new SqlRegistryError('INVALID_DESCRIPTOR', `Package "${packageName}" amodalDriver.sdkVersion must be a semver range string`, { kind: 'driver', packageName });
+    }
+    return {
+        packageName,
+        dialects,
+        protocol,
+        packageDir,
+        moduleEntry,
+        exportName,
+        sdkVersion,
+    };
+}
+function parsePackageJson(pkgJsonPath, packageName) {
+    const raw = readFileSync(pkgJsonPath, 'utf-8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (cause) {
+        throw new SqlRegistryError('INVALID_DESCRIPTOR', `Package "${packageName}" has unparseable package.json`, { kind: 'driver', packageName, cause });
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new SqlRegistryError('INVALID_DESCRIPTOR', `Package "${packageName}" package.json is not an object`, { kind: 'driver', packageName });
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- narrowed by the typeof/null/array guards above.
+    return parsed;
+}
+/**
+ * Registry of discovered SQL drivers. Built once per agent-bundle load
+ * and queried per connection at runtime. Implements the
+ * `DriverRegistry` shape from `@amodalai/types` so it can be attached
+ * to `AgentBundle.sqlDrivers` and consumed across packages without
+ * importing concrete classes.
+ */
+export class DriverRegistry {
+    byName;
+    logger;
+    constructor(descriptors, logger) {
+        this.byName = new Map(descriptors.map((d) => [d.packageName, d]));
+        this.logger = logger;
+    }
+    list() {
+        return Array.from(this.byName.values()).map((d) => ({
+            name: d.packageName,
+            dialects: d.dialects,
+            sdkVersion: d.sdkVersion,
+        }));
+    }
+    has(packageName) {
+        return this.byName.has(packageName);
+    }
+    get(packageName) {
+        return this.byName.get(packageName);
+    }
+    /**
+     * Dynamic-import the descriptor's module, call the named factory,
+     * and return the resulting `SqlDriver`. Each call produces a fresh
+     * instance — drivers are not cached at the registry layer; the
+     * caller (typically the repo loader) owns lifecycle.
+     */
+    async loadDriver(packageName) {
+        const descriptor = this.byName.get(packageName);
+        if (!descriptor) {
+            throw new SqlRegistryError('PACKAGE_NOT_FOUND', `Driver "${packageName}" was referenced but not discovered. Add it to the agent's packages list and run npm install.`, { kind: 'driver', packageName });
+        }
+        const moduleUrl = pathToFileURL(descriptor.moduleEntry).href;
+        let mod;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- dynamic import yields unknown module shape; narrowed below.
+            mod = (await import(moduleUrl));
+        }
+        catch (cause) {
+            throw new SqlRegistryError('FACTORY_FAILED', `Failed to import driver "${packageName}" from ${descriptor.moduleEntry}`, { kind: 'driver', packageName, cause });
+        }
+        const factory = mod[descriptor.exportName];
+        if (typeof factory !== 'function') {
+            throw new SqlRegistryError('FACTORY_MISSING', `Driver "${packageName}" does not export "${descriptor.exportName}" as a function`, { kind: 'driver', packageName, context: { exportName: descriptor.exportName } });
+        }
+        let instance;
+        try {
+            instance = factory();
+        }
+        catch (cause) {
+            throw new SqlRegistryError('FACTORY_FAILED', `Driver "${packageName}" factory "${descriptor.exportName}" threw`, { kind: 'driver', packageName, cause });
+        }
+        if (!isSqlDriver(instance)) {
+            throw new SqlRegistryError('INVALID_INSTANCE', `Driver "${packageName}" factory returned a value that is not a SqlDriver`, { kind: 'driver', packageName });
+        }
+        this.logger.info('sql_driver_loaded', {
+            package: packageName,
+            dialects: descriptor.dialects,
+        });
+        return instance;
+    }
+}
+function isSqlDriver(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- narrowed by the typeof/null guards above.
+    const obj = value;
+    return (typeof obj['init'] === 'function' &&
+        typeof obj['introspectSchema'] === 'function' &&
+        typeof obj['parse'] === 'function' &&
+        typeof obj['execute'] === 'function' &&
+        typeof obj['beginTransaction'] === 'function' &&
+        typeof obj['shutdown'] === 'function');
+}
+//# sourceMappingURL=driver-registry.js.map

package/dist/src/driver-registry.js.map

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

package/dist/src/errors.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Failures during SQL driver / parser discovery and loading.
+ *
+ * Discovery scans `node_modules` for `amodalDriver` / `amodalParser`
+ * blocks. Loading dynamic-imports the named module, calls the factory,
+ * and validates the returned instance against the SqlDriver / Parser
+ * shape.
+ */
+export type SqlRegistryErrorCode = 
+/** Package referenced in connection config wasn't found in node_modules. */
+'PACKAGE_NOT_FOUND'
+/** package.json has an `amodalDriver` / `amodalParser` block, but it's
+    missing required fields or has invalid values. */
+ | 'INVALID_DESCRIPTOR'
+/** Dynamic import succeeded but the named factory export isn't a function. */
+ | 'FACTORY_MISSING'
+/** Calling the factory threw. */
+ | 'FACTORY_FAILED'
+/** Factory returned a value that doesn't satisfy the SqlDriver / Parser shape. */
+ | 'INVALID_INSTANCE'
+/** Driver's SDK version doesn't satisfy the runtime's compatibility range. */
+ | 'SDK_VERSION_MISMATCH';
+/**
+ * Errors thrown by `DriverRegistry` and `ParserRegistry` operations.
+ * The `kind` field discriminates which registry surfaced the failure
+ * for log/SIEM filtering — both use the same code set.
+ */
+export declare class SqlRegistryError extends Error {
+    readonly code: SqlRegistryErrorCode;
+    readonly kind: 'driver' | 'parser';
+    readonly packageName: string;
+    readonly context: Record<string, unknown>;
+    constructor(code: SqlRegistryErrorCode, message: string, options: {
+        kind: 'driver' | 'parser';
+        packageName: string;
+        context?: Record<string, unknown>;
+        cause?: unknown;
+    });
+}

package/dist/src/errors.js

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Errors thrown by `DriverRegistry` and `ParserRegistry` operations.
+ * The `kind` field discriminates which registry surfaced the failure
+ * for log/SIEM filtering — both use the same code set.
+ */
+export class SqlRegistryError extends Error {
+    code;
+    kind;
+    packageName;
+    context;
+    constructor(code, message, options) {
+        super(message, { cause: options.cause });
+        this.name = 'SqlRegistryError';
+        this.code = code;
+        this.kind = options.kind;
+        this.packageName = options.packageName;
+        this.context = options.context ?? {};
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAyBH;;;;GAIG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,IAAI,CAAuB;IAC3B,IAAI,CAAsB;IAC1B,WAAW,CAAS;IACpB,OAAO,CAA0B;IAE1C,YACE,IAA0B,EAC1B,OAAe,EACf,OAKC;QAED,KAAK,CAAC,OAAO,EAAE,EAAC,KAAK,EAAE,OAAO,CAAC,KAAK,EAAC,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACvC,CAAC;CACF"}

package/dist/src/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Authoring surface for SQL drivers and parsers. Driver / parser
+ * packages depend on this SDK rather than directly on `@amodalai/types`
+ * so the runtime can evolve the type-level contracts on a slower
+ * cadence than the runtime internals. Conformance + version-
+ * compatibility checks live here too.
+ *
+ * The runtime cares about three things from a driver / parser package:
+ *
+ *   1. The `amodalDriver` / `amodalParser` block in `package.json`,
+ *      pointing at this SDK's `sdkVersion` so the runtime can refuse
+ *      to load packages built against an incompatible major.
+ *   2. The named factory export — a zero-arg function returning a
+ *      `SqlDriver` or `Parser`. `defineDriver` / `defineParser` here
+ *      are identity wrappers; their job is purely compile-time type
+ *      inference today, but they're the natural hook for SDK-version
+ *      checks or telemetry tomorrow.
+ *   3. The shape of the returned object. The runtime validates with
+ *      structural type guards (see `core/sql/driver-registry.ts`); the
+ *      types here are the compile-time contract.
+ */
+export type { SqlDriver, DriverCapabilities, TransactionHandle, TransactionOptions, Parser, SessionContext, ParamValue, ResultSet, ResultField, SchemaInfo, SchemaInfoTable, SchemaInfoColumn, SqlConnectionConfig, DbConnectionSettings, McpDriverSettings, PoolSettings, ScopingPolicy, QueryConstraints, AuditPolicy, SchemaDriftPolicy, DriftAction, SchemaJson, TableSchema, TableScoping, ColumnPolicy, WriteThresholdRule, LoadedSqlConnection, ParsedStatement, StatementKind, StatementIntent, SelectStatement, InsertStatement, InsertValues, UpdateStatement, DeleteStatement, MergeStatement, MergeAction, SelectItem, TableRef, Assignment, OrderItem, LimitClause, CommonTableExpr, SetOperation, Expression, ColumnRef, ResolvedColumnRef, ParameterRef, LiteralExpr, FunctionCall, BinaryExpr, UnaryExpr, CaseExpr, CastExpr, SubqueryExpr, StarExpr, Predicate, ComparisonPredicate, InPredicate, BetweenPredicate, IsNullPredicate, AndPredicate, OrPredicate, NotPredicate, ExistsPredicate, FunctionPredicate, } from '@amodalai/types';
+import type { Parser, SqlDriver } from '@amodalai/types';
+/**
+ * The SDK version this package was built against. Drivers should
+ * reference this when declaring `amodalDriver.sdkVersion` in their
+ * `package.json` so the runtime's compatibility check is anchored to
+ * the actual published contract, not a hand-typed string.
+ *
+ * Bumped on every major SDK contract change.
+ */
+export declare const SDK_VERSION: "1";
+/**
+ * Identity helper. Wraps a `SqlDriver` so authors get full inference
+ * without explicit type annotations, and so future SDK versions can
+ * add behavior (capability claim validation, telemetry hooks) without
+ * a breaking signature change.
+ *
+ * ```ts
+ * import {defineDriver} from '@amodalai/sql-driver-sdk';
+ *
+ * export const createDriver = () => defineDriver({
+ *   init: async (config, parsers) => { ... },
+ *   parse: (sql) => { ... },
+ *   // ...
+ * });
+ * ```
+ */
+export declare function defineDriver<T extends SqlDriver>(driver: T): T;
+/**
+ * Identity helper for parsers. Same intent as `defineDriver`.
+ *
+ * ```ts
+ * import {defineParser} from '@amodalai/sql-driver-sdk';
+ *
+ * export const createParser = () => defineParser({
+ *   parse: (sql) => { ... },
+ *   dialects: ['postgres'],
+ * });
+ * ```
+ */
+export declare function defineParser<T extends Parser>(parser: T): T;
+export { SqlRegistryError } from './errors.js';
+export type { SqlRegistryErrorCode } from './errors.js';
+export { DriverRegistry, discoverDrivers, } from './driver-registry.js';
+export type { DriverDescriptor, DiscoverDriversOptions, } from './driver-registry.js';
+export { ParserRegistry, discoverParsers, } from './parser-registry.js';
+export type { ParserDescriptor, DiscoverParsersOptions, } from './parser-registry.js';
+export { SqlConnectionConfigSchema, SchemaJsonSchema, } from './sql-connection-schemas.js';
+export { parseSqlConnectionConfig, parseSchemaJson, } from './sql-connection-parsers.js';

package/dist/src/index.js

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+// ---------------------------------------------------------------------------
+// Authoring helpers
+// ---------------------------------------------------------------------------
+/**
+ * The SDK version this package was built against. Drivers should
+ * reference this when declaring `amodalDriver.sdkVersion` in their
+ * `package.json` so the runtime's compatibility check is anchored to
+ * the actual published contract, not a hand-typed string.
+ *
+ * Bumped on every major SDK contract change.
+ */
+export const SDK_VERSION = '1';
+/**
+ * Identity helper. Wraps a `SqlDriver` so authors get full inference
+ * without explicit type annotations, and so future SDK versions can
+ * add behavior (capability claim validation, telemetry hooks) without
+ * a breaking signature change.
+ *
+ * ```ts
+ * import {defineDriver} from '@amodalai/sql-driver-sdk';
+ *
+ * export const createDriver = () => defineDriver({
+ *   init: async (config, parsers) => { ... },
+ *   parse: (sql) => { ... },
+ *   // ...
+ * });
+ * ```
+ */
+export function defineDriver(driver) {
+    return driver;
+}
+/**
+ * Identity helper for parsers. Same intent as `defineDriver`.
+ *
+ * ```ts
+ * import {defineParser} from '@amodalai/sql-driver-sdk';
+ *
+ * export const createParser = () => defineParser({
+ *   parse: (sql) => { ... },
+ *   dialects: ['postgres'],
+ * });
+ * ```
+ */
+export function defineParser(parser) {
+    return parser;
+}
+// ---------------------------------------------------------------------------
+// Discovery + validation — host helpers used by the agent-bundle loader.
+//
+// These live in the SDK rather than `@amodalai/core` so that core never has
+// to know SQL exists: the bundle loader imports `discoverDrivers` /
+// `discoverParsers` / `parseSqlConnectionConfig` / `parseSchemaJson` from
+// here and stays protocol-agnostic.
+// ---------------------------------------------------------------------------
+export { SqlRegistryError } from './errors.js';
+// Concrete classes exposed as `DriverRegistry` / `ParserRegistry`. They
+// implement the interfaces of the same name in `@amodalai/types`, so
+// consumers can use the class type as the interface type wherever the
+// interface was previously imported.
+export { DriverRegistry, discoverDrivers, } from './driver-registry.js';
+export { ParserRegistry, discoverParsers, } from './parser-registry.js';
+export { SqlConnectionConfigSchema, SchemaJsonSchema, } from './sql-connection-schemas.js';
+export { parseSqlConnectionConfig, parseSchemaJson, } from './sql-connection-parsers.js';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA+GH,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAY,CAAC;AAExC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAAsB,MAAS;IACzD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAmB,MAAS;IACtD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,8EAA8E;AAC9E,yEAAyE;AACzE,EAAE;AACF,4EAA4E;AAC5E,oEAAoE;AACpE,0EAA0E;AAC1E,oCAAoC;AACpC,8EAA8E;AAE9E,OAAO,EAAC,gBAAgB,EAAC,MAAM,aAAa,CAAC;AAG7C,wEAAwE;AACxE,qEAAqE;AACrE,sEAAsE;AACtE,qCAAqC;AACrC,OAAO,EACL,cAAc,EACd,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EACL,cAAc,EACd,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EACL,yBAAyB,EACzB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,wBAAwB,EACxB,eAAe,GAChB,MAAM,6BAA6B,CAAC"}

package/dist/src/parser-registry.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { Parser, ParserDescriptor as TypesParserDescriptor, ParserRegistry as ParserRegistryShape, RuntimeLogger as Logger } from '@amodalai/types';
+/**
+ * `amodalParser` block as it appears in a package's `package.json`,
+ * normalized into a descriptor by discovery.
+ */
+export interface ParserDescriptor {
+    /** npm package name (`@amodalai/postgres-parser`). */
+    packageName: string;
+    /** Dialects this parser claims to accept. */
+    dialects: string[];
+    /** Absolute path to the package directory. */
+    packageDir: string;
+    /** Absolute path to the JS entry the runtime dynamic-imports. */
+    moduleEntry: string;
+    /** Named export inside `moduleEntry` that returns a `Parser`. */
+    exportName: string;
+    /** Range of `@amodalai/sql-driver-sdk` versions the parser was
+        built against (parsers ship from the same SDK as drivers). */
+    sdkVersion: string;
+}
+export interface DiscoverParsersOptions {
+    repoPath: string;
+    candidatePackages: string[];
+    logger: Logger;
+}
+/**
+ * Scan candidate packages for `amodalParser` blocks. Packages missing
+ * the block are skipped silently; malformed blocks throw
+ * `SqlRegistryError`.
+ */
+export declare function discoverParsers(opts: DiscoverParsersOptions): ParserDescriptor[];
+/**
+ * Implementation of the `ParserRegistry` shape from `@amodalai/types`,
+ * which is what `SqlDriver.init(config, parsers)` receives. Parsers
+ * are cached after first load — they're stateless and safely shared
+ * across drivers.
+ */
+export declare class ParserRegistry implements ParserRegistryShape {
+    private readonly byName;
+    private readonly cache;
+    private readonly logger;
+    constructor(descriptors: ParserDescriptor[], logger: Logger);
+    list(): TypesParserDescriptor[];
+    has(packageName: string): boolean;
+    /**
+     * Synchronous interface required by `SqlDriver.init()` — drivers
+     * resolve parsers during the load handshake and shouldn't have to
+     * await. Parser instances must be preloaded via `prepare()` first.
+     */
+    getParser(packageName: string): Parser;
+    /**
+     * Preload a parser. Called by the repo loader for each parser name
+     * referenced by an SQL connection, before any `driver.init()` runs.
+     * Idempotent — calling twice returns the cached instance.
+     */
+    prepare(packageName: string): Promise<Parser>;
+}