qubu 0.0.0 → 0.3.3

package/dist/types-BX0mckiU.d.mts

@@ -0,0 +1,644 @@
+import { n as SchemaSnapshot } from "./types-4Q076HKo.mjs";
+//#region src/introspection/connection.d.ts
+/** A parameterized statement owned by a catalog adapter. */
+interface CatalogQuery {
+  /** Fixed catalog SQL selected by Qubu's dialect adapter. */
+  readonly text: string;
+  /** Values bound by the user-owned connection or driver adapter. */
+  readonly parameters: readonly unknown[];
+}
+/** Optional execution controls passed through to a catalog connection. */
+interface CatalogQueryOptions {
+  /** Abort propagation is optional because drivers expose it inconsistently. */
+  readonly signal?: AbortSignal;
+}
+/**
+ * User-owned catalog query boundary.
+ *
+ * Qubu does not select a driver, open or close a connection, manage a pool,
+ * authenticate, retry, start a transaction, or impose a timeout. The
+ * connection only executes fixed, parameterized catalog statements and
+ * returns already-decoded row records.
+ */
+interface CatalogConnection {
+  readonly dialect: CatalogDialect;
+  query<TRow extends CatalogQueryRow = CatalogQueryRow>(statement: CatalogQuery, options?: CatalogQueryOptions): Promise<readonly TRow[]>;
+}
+//#endregion
+//#region src/introspection/diagnostics.d.ts
+/** Stable severity levels for discovery and normalization findings. */
+type IntrospectionDiagnosticSeverity = 'error' | 'warning' | 'info';
+/** Stable codes emitted by catalog discovery and normalization. */
+type IntrospectionDiagnosticCode = 'connection-failed' | 'query-failed' | 'permission-denied' | 'unsupported-product' | 'unsupported-server' | 'unsupported-feature' | 'invalid-catalog-row' | 'missing-catalog-row' | 'expression-parse-failed' | 'unresolved-reference' | 'ambiguous-identity' | 'unmodeled-object' | 'lossy-mapping' | 'dialect-mismatch' | 'partial-result';
+/** A path-addressed diagnostic from catalog discovery or normalization. */
+interface IntrospectionDiagnostic {
+  readonly severity: IntrospectionDiagnosticSeverity;
+  readonly code: IntrospectionDiagnosticCode;
+  readonly message: string;
+  /** Location in the normalized catalog or adapter input being described. */
+  readonly path: readonly (string | number)[];
+  /** Physical object and current-run catalog identity involved in the issue. */
+  readonly physicalReference?: CatalogReference;
+  /** Other physical objects or current-run references related to the issue. */
+  readonly relatedReferences?: readonly CatalogReference[];
+  /** Optional action that can resolve or explain the finding. */
+  readonly remediation?: string;
+}
+/** Input accepted by {@link createIntrospectionDiagnostic}. */
+type IntrospectionDiagnosticInput = IntrospectionDiagnostic;
+/**
+ * Create one immutable diagnostic without interpreting catalog text or
+ * copying driver error details into the structured fields.
+ */
+declare function createIntrospectionDiagnostic(diagnostic: IntrospectionDiagnosticInput): IntrospectionDiagnostic;
+/** Return whether a diagnostic list prevents strict introspection output. */
+declare function hasIntrospectionErrors(diagnostics: readonly IntrospectionDiagnostic[]): boolean;
+/** Error raised by a throwing introspection operation after collecting findings. */
+declare class IntrospectionError extends Error {
+  readonly name = "IntrospectionError";
+  readonly diagnostics: readonly IntrospectionDiagnostic[];
+  readonly issues: readonly IntrospectionDiagnostic[];
+  constructor(diagnostics: readonly IntrospectionDiagnostic[]);
+}
+//#endregion
+//#region src/introspection/identity.d.ts
+/** The source selected by the stable introspection identity precedence. */
+type CatalogIdentitySource = 'explicit-hint' | 'previous-snapshot' | 'physical-name' | 'deterministic-fallback';
+/** Entity kinds for which a caller may provide a logical identity hint. */
+type CatalogIdentityEntityKind = Exclude<CatalogEntityKind, 'namespace' | 'deferred-object'>;
+/** A physical selector for one table-scoped or namespace-scoped entity. */
+interface CatalogIdentityHint {
+  readonly kind: CatalogIdentityEntityKind;
+  /** Logical ID to retain in the normalized catalog and later snapshot. */
+  readonly logicalId: string;
+  /** Current physical name of the selected object. */
+  readonly physicalName: string;
+  /** Physical table name for columns, constraints, and indexes. */
+  readonly tablePhysicalName?: string;
+}
+/** The caller-provided identity hints accepted by an introspection run. */
+type CatalogIdentityHints = readonly CatalogIdentityHint[];
+/** How invalid physical names become deterministic logical IDs. */
+type CatalogIdentityFallback = 'escaped' | 'hashed';
+/** Versioned metadata for the identity policy used by one introspection run. */
+interface CatalogIdentityPolicy {
+  readonly name: string;
+  readonly version: number;
+  readonly fallback: CatalogIdentityFallback;
+  readonly precedence: readonly CatalogIdentitySource[];
+}
+/** The naming policy used by the first introspection snapshot mapper. */
+declare const introspectedPhysicalIdentityPolicy: CatalogIdentityPolicy;
+/** A resolved logical ID together with the rule that selected it. */
+interface CatalogResolvedIdentity {
+  readonly logicalId: string;
+  readonly source: CatalogIdentitySource;
+}
+/**
+ * Inputs used when carrying a prior snapshot's table and column IDs forward.
+ * The resolver must match physical names inside the selected namespace only.
+ */
+interface CatalogPreviousSnapshotIdentitySource {
+  readonly snapshot: SchemaSnapshot;
+}
+//#endregion
+//#region src/introspection/types.d.ts
+/** SQL engines supported by the common catalog contract. */
+type CatalogDialect = 'postgresql' | 'sqlite' | 'mysql';
+/** A decoded row returned by a user-owned catalog connection. */
+type CatalogQueryRow = Readonly<Record<string, unknown>>;
+/** Physical objects that can receive stable logical IDs. */
+type CatalogEntityKind = 'namespace' | 'table' | 'column' | 'constraint' | 'index' | 'view' | 'materialized-view' | 'sequence' | 'enum' | 'domain' | 'collation' | 'trigger' | 'routine' | 'partition' | 'policy' | 'extension' | 'comment' | 'ownership' | 'opaque-object' | 'deferred-object';
+/** A scalar value retained as catalog data rather than executable SQL. */
+type CatalogScalar = null | boolean | string | number | bigint;
+/** Plain catalog data used for dialect extensions and unknown fields. */
+type CatalogData = CatalogScalar | readonly CatalogData[] | {
+  readonly [key: string]: CatalogData;
+};
+/** A current-run catalog key. It is never a persisted logical identity. */
+interface CatalogCatalogReference {
+  readonly relation: string;
+  readonly key: string;
+  readonly value: string | number;
+}
+/**
+ * A physical object reference with an optional current-run catalog key.
+ * PostgreSQL OIDs and similar values belong in `catalog`, not in logical IDs.
+ */
+interface CatalogReference {
+  readonly kind: CatalogEntityKind;
+  readonly namespace?: string;
+  readonly table?: string;
+  readonly name: string;
+  readonly catalog?: CatalogCatalogReference;
+}
+/** Where an opaque catalog SQL expression came from. */
+type CatalogProvenanceKind = 'catalog' | 'decompiler' | 'create-sql';
+/** Source location retained with catalog-derived SQL text. */
+interface CatalogProvenance {
+  readonly kind: CatalogProvenanceKind;
+  readonly dialect: CatalogDialect;
+  readonly reference?: CatalogReference;
+  readonly path?: readonly (string | number)[];
+}
+/**
+ * Opaque SQL text recovered from catalog metadata. It has no evaluator or
+ * Qubu expression implementation and must not be executed by introspection.
+ */
+interface CatalogSqlExpression {
+  readonly kind: 'sql';
+  readonly dialect: CatalogDialect;
+  readonly text: string;
+  readonly provenance: CatalogProvenance;
+}
+/** A literal catalog fact with optional source provenance. */
+interface CatalogLiteralFact {
+  readonly kind: 'literal';
+  readonly value: CatalogScalar;
+  readonly provenance?: CatalogProvenance;
+}
+/** A catalog fact whose value remains opaque dialect SQL. */
+interface CatalogExpressionFact {
+  readonly kind: 'expression';
+  readonly expression: CatalogSqlExpression;
+}
+/** Tagged data used by defaults, identity options, and dialect metadata. */
+type CatalogValueFact = CatalogLiteralFact | CatalogExpressionFact;
+/** An unmodeled field retained for later adapter and mapper support. */
+interface CatalogUnknownField {
+  readonly name: string;
+  readonly value: CatalogData | CatalogSqlExpression;
+  readonly provenance?: CatalogProvenance;
+}
+/** A reference to an object in the normalized catalog. */
+interface CatalogObjectReference {
+  readonly kind: Exclude<CatalogEntityKind, 'namespace'>;
+  readonly id: string;
+}
+/** A comment observed for a physical catalog object. */
+interface CatalogComment {
+  readonly kind: 'comment';
+  readonly id: string;
+  readonly object: CatalogObjectReference;
+  readonly text: string;
+  readonly reference?: CatalogReference;
+  readonly provenance?: CatalogProvenance;
+  readonly dialect?: CatalogDialectExtension;
+  readonly unknownFields?: readonly CatalogUnknownField[];
+}
+/** Ownership metadata observed for a physical catalog object. */
+interface CatalogOwnership {
+  readonly kind: 'ownership';
+  readonly id: string;
+  readonly object: CatalogObjectReference;
+  readonly owner: string;
+  readonly reference?: CatalogReference;
+  readonly provenance?: CatalogProvenance;
+  readonly dialect?: CatalogDialectExtension;
+  readonly unknownFields?: readonly CatalogUnknownField[];
+}
+/** Optional metadata shared by complete normalized catalog objects. */
+interface CatalogObjectMetadata {
+  readonly provenance?: CatalogProvenance;
+  readonly comment?: CatalogComment;
+  readonly ownership?: CatalogOwnership;
+}
+/** Common identity and physical-name fields for complete catalog objects. */
+interface CatalogObjectBase extends CatalogObjectMetadata {
+  readonly kind: Exclude<CatalogEntityKind, 'namespace'>;
+  readonly id: string;
+  readonly identitySource: CatalogIdentitySource;
+  readonly physicalName: string;
+  readonly reference?: CatalogReference;
+  readonly dialect?: CatalogDialectExtension;
+  readonly unknownFields?: readonly CatalogUnknownField[];
+}
+/** Portable classification retained beside an exact native declaration. */
+type CatalogPortableStorageType = 'integer' | 'numeric' | 'text' | 'boolean' | 'date' | 'timestamp' | 'uuid' | 'json' | 'bigint' | 'binary';
+/** Confidence for a portable classification, never a replacement for native type text. */
+type CatalogClassificationConfidence = 'exact' | 'inferred' | 'unknown';
+/** Exact native storage plus an optional portable classification. */
+interface CatalogStorageType {
+  readonly nativeType: string;
+  readonly portable?: {
+    readonly type: CatalogPortableStorageType;
+    readonly confidence: CatalogClassificationConfidence;
+  };
+}
+/** A generated-column expression and its recovered storage mode. */
+interface CatalogGeneratedColumn {
+  readonly kind: 'generated';
+  readonly expression: CatalogSqlExpression;
+  readonly mode: 'stored' | 'virtual' | 'unknown';
+}
+/** Identity behavior kept separate from defaults and generated expressions. */
+interface CatalogIdentity {
+  readonly kind: 'identity';
+  readonly generation: 'always' | 'by-default';
+  readonly options: Readonly<Record<string, CatalogValueFact>>;
+  readonly dialect?: CatalogDialectExtension;
+}
+/** Version parts parsed from a server's raw version string. */
+interface CatalogVersion {
+  readonly major: number;
+  readonly minor?: number;
+  readonly patch?: number;
+  readonly suffix?: string;
+}
+/** Calculated feature and visibility facts reported by a catalog adapter. */
+interface CatalogCapabilities {
+  readonly generatedColumns: boolean;
+  readonly identityMetadata: boolean;
+  readonly checkConstraints: boolean;
+  readonly checkConstraintEnforcement: 'enforced' | 'metadata-only' | 'unknown';
+  readonly expressionDecompilation: boolean;
+  readonly indexExpressions: boolean;
+  readonly indexPredicates: boolean;
+  readonly indexIncludedColumns: boolean;
+  readonly namespaces: boolean;
+  readonly visibility: 'complete' | 'limited' | 'unknown';
+  readonly [capability: string]: boolean | string;
+}
+/** Server product, raw version text, parsed version, and adapter capabilities. */
+interface CatalogServerInfo {
+  readonly product: string;
+  readonly rawVersion: string;
+  readonly parsedVersion?: CatalogVersion;
+  readonly capabilities: CatalogCapabilities;
+}
+/** The one physical namespace selected for a catalog run. */
+interface CatalogNamespace {
+  readonly kind: 'postgres-schema' | 'sqlite-database' | 'mysql-database';
+  readonly name: string;
+  readonly reference?: CatalogReference;
+  readonly provenance?: CatalogProvenance;
+  readonly comment?: CatalogComment;
+  readonly ownership?: CatalogOwnership;
+  readonly dialect?: CatalogDialectExtension;
+  readonly unknownFields?: readonly CatalogUnknownField[];
+}
+/** A logical reference used for normalized cross-object relationships. */
+interface CatalogEntityReference {
+  readonly kind: Exclude<CatalogEntityKind, 'namespace' | 'deferred-object'>;
+  readonly id: string;
+  readonly tableId?: string;
+}
+/** A primary key constraint in the normalized catalog. */
+interface CatalogPrimaryKeyConstraint extends CatalogObjectMetadata {
+  readonly kind: 'primary-key';
+  readonly id: string;
+  readonly identitySource: CatalogIdentitySource;
+  readonly physicalName?: string;
+  readonly columns: readonly string[];
+  readonly backingIndex?: CatalogEntityReference;
+  readonly deferrable?: boolean;
+  readonly initially?: 'immediate' | 'deferred';
+  readonly validated?: boolean;
+  readonly reference?: CatalogReference;
+  readonly dialect?: CatalogDialectExtension;
+  readonly unknownFields?: readonly CatalogUnknownField[];
+}
+/** A unique constraint, including nullable uniqueness semantics. */
+interface CatalogUniqueConstraint extends CatalogObjectMetadata {
+  readonly kind: 'unique';
+  readonly id: string;
+  readonly identitySource: CatalogIdentitySource;
+  readonly physicalName?: string;
+  readonly columns: readonly string[];
+  readonly nulls: 'distinct' | 'not-distinct';
+  readonly backingIndex?: CatalogEntityReference;
+  readonly deferrable?: boolean;
+  readonly initially?: 'immediate' | 'deferred';
+  readonly validated?: boolean;
+  readonly reference?: CatalogReference;
+  readonly dialect?: CatalogDialectExtension;
+  readonly unknownFields?: readonly CatalogUnknownField[];
+}
+/** Ordered target columns and table IDs for a normalized foreign key. */
+interface CatalogForeignKeyTarget {
+  readonly table: string;
+  readonly columns: readonly string[];
+}
+/** A foreign key with ordered columns and referential actions. */
+interface CatalogForeignKeyConstraint extends CatalogObjectMetadata {
+  readonly kind: 'foreign-key';
+  readonly id: string;
+  readonly identitySource: CatalogIdentitySource;
+  readonly physicalName?: string;
+  readonly columns: readonly string[];
+  readonly target: CatalogForeignKeyTarget;
+  readonly onUpdate?: 'no-action' | 'restrict' | 'cascade' | 'set-null' | 'set-default';
+  readonly onDelete?: 'no-action' | 'restrict' | 'cascade' | 'set-null' | 'set-default';
+  readonly match?: 'simple' | 'full' | 'partial';
+  readonly deferrable?: boolean;
+  readonly initially?: 'immediate' | 'deferred';
+  readonly validated?: boolean;
+  readonly reference?: CatalogReference;
+  readonly dialect?: CatalogDialectExtension;
+  readonly unknownFields?: readonly CatalogUnknownField[];
+}
+/** A check constraint whose expression remains tagged catalog SQL. */
+interface CatalogCheckConstraint extends CatalogObjectMetadata {
+  readonly kind: 'check';
+  readonly id: string;
+  readonly identitySource: CatalogIdentitySource;
+  readonly physicalName?: string;
+  readonly expression: CatalogSqlExpression;
+  readonly deferrable?: boolean;
+  readonly initially?: 'immediate' | 'deferred';
+  readonly validated?: boolean;
+  readonly reference?: CatalogReference;
+  readonly dialect?: CatalogDialectExtension;
+  readonly unknownFields?: readonly CatalogUnknownField[];
+}
+/** Every constraint represented by the normalized catalog contract. */
+type CatalogConstraint = CatalogPrimaryKeyConstraint | CatalogUniqueConstraint | CatalogForeignKeyConstraint | CatalogCheckConstraint;
+/** One ordered column or expression term in a normalized index. */
+type CatalogIndexTerm = {
+  readonly kind: 'column';
+  readonly column: string;
+  readonly position: number;
+  readonly direction?: 'ASC' | 'DESC';
+  readonly nulls?: 'FIRST' | 'LAST';
+  readonly prefixLength?: CatalogValueFact;
+  readonly operatorClass?: string;
+} | {
+  readonly kind: 'expression';
+  readonly expression: CatalogSqlExpression;
+  readonly position: number;
+  readonly direction?: 'ASC' | 'DESC';
+  readonly nulls?: 'FIRST' | 'LAST';
+  readonly operatorClass?: string;
+};
+/** A normalized index with ordered terms and backing relationships. */
+interface CatalogIndex extends CatalogObjectMetadata {
+  readonly kind: 'index';
+  readonly id: string;
+  readonly identitySource: CatalogIdentitySource;
+  readonly physicalName?: string;
+  readonly unique: boolean;
+  readonly terms: readonly CatalogIndexTerm[];
+  readonly predicate?: CatalogSqlExpression;
+  readonly includedColumns?: readonly string[];
+  readonly backingConstraint?: CatalogEntityReference;
+  readonly method?: string;
+  readonly reference?: CatalogReference;
+  readonly dialect?: CatalogDialectExtension;
+  readonly unknownFields?: readonly CatalogUnknownField[];
+}
+/** A normalized table containing only ordinary included table metadata. */
+interface CatalogTable extends CatalogObjectMetadata {
+  readonly kind: 'table';
+  readonly id: string;
+  readonly identitySource: CatalogIdentitySource;
+  readonly physicalName: string;
+  readonly ordinalPosition?: number;
+  readonly reference?: CatalogReference;
+  readonly columns: readonly CatalogColumn[];
+  readonly constraints: readonly CatalogConstraint[];
+  readonly indexes: readonly CatalogIndex[];
+  readonly dialect?: CatalogDialectExtension;
+  readonly unknownFields?: readonly CatalogUnknownField[];
+}
+/** A normalized visible column within an ordinary table. */
+interface CatalogColumn extends CatalogObjectMetadata {
+  readonly kind: 'column';
+  readonly id: string;
+  readonly identitySource: CatalogIdentitySource;
+  readonly physicalName: string;
+  readonly ordinalPosition: number;
+  readonly nullable: boolean;
+  readonly storage: CatalogStorageType;
+  readonly default?: CatalogValueFact;
+  readonly generated?: CatalogGeneratedColumn;
+  readonly identity?: CatalogIdentity;
+  readonly onUpdate?: CatalogSqlExpression;
+  readonly reference?: CatalogReference;
+  readonly dialect?: CatalogDialectExtension;
+  readonly unknownFields?: readonly CatalogUnknownField[];
+}
+/** Object categories intentionally retained outside Snapshot v1 tables. */
+type CatalogDeferredObjectKind = 'view' | 'materialized-view' | 'sequence' | 'enum' | 'domain' | 'collation' | 'routine' | 'trigger' | 'policy' | 'extension' | 'partition' | 'virtual-table' | 'shadow-table' | 'temporary-object' | 'foreign-table' | 'other';
+/** A deferred or unmodeled object retained for diagnostics and future support. */
+interface CatalogDeferredObject extends CatalogObjectMetadata {
+  readonly kind: 'deferred-object';
+  readonly objectKind: CatalogDeferredObjectKind;
+  /** Optional in the legacy reader contract; complete readers should set it. */
+  readonly id?: string;
+  readonly identitySource?: CatalogIdentitySource;
+  readonly physicalName: string;
+  readonly reference?: CatalogReference;
+  readonly dialect?: CatalogDialectExtension;
+  readonly unknownFields?: readonly CatalogUnknownField[];
+}
+/** A versioned dialect-owned catalog payload. */
+interface CatalogDialectExtension {
+  readonly dialect: CatalogDialect;
+  readonly version: number;
+  readonly data: CatalogData;
+}
+/** A view or materialized view definition and its exposed columns. */
+interface CatalogView extends CatalogObjectBase {
+  readonly kind: 'view' | 'materialized-view';
+  readonly columns: readonly CatalogColumn[];
+  readonly definition: CatalogSqlExpression;
+  readonly dependencies?: readonly CatalogObjectReference[];
+  readonly checkOption?: 'none' | 'local' | 'cascaded';
+  readonly securityBarrier?: boolean;
+  readonly securityInvoker?: boolean;
+}
+/** Sequence metadata, including options needed to describe an identity. */
+interface CatalogSequence extends CatalogObjectBase {
+  readonly kind: 'sequence';
+  readonly storage?: CatalogStorageType;
+  readonly start?: CatalogValueFact;
+  readonly increment?: CatalogValueFact;
+  readonly minimum?: CatalogValueFact;
+  readonly maximum?: CatalogValueFact;
+  readonly cache?: CatalogValueFact;
+  readonly cycle?: boolean;
+  readonly ownedBy?: CatalogObjectReference;
+  readonly identity?: CatalogIdentity;
+}
+/** One ordered enum label retained exactly as returned by the database. */
+interface CatalogEnumValue {
+  readonly value: string;
+  readonly ordinalPosition: number;
+  readonly provenance?: CatalogProvenance;
+}
+/** A database enum type with stable label ordering. */
+interface CatalogEnum extends CatalogObjectBase {
+  readonly kind: 'enum';
+  readonly values: readonly CatalogEnumValue[];
+}
+/** A domain type layered over a native storage declaration. */
+interface CatalogDomain extends CatalogObjectBase {
+  readonly kind: 'domain';
+  readonly storage: CatalogStorageType;
+  readonly nullable?: boolean;
+  readonly default?: CatalogValueFact;
+  readonly constraints?: readonly CatalogCheckConstraint[];
+}
+/** Collation properties that affect comparison and ordering semantics. */
+interface CatalogCollation extends CatalogObjectBase {
+  readonly kind: 'collation';
+  readonly provider?: string;
+  readonly locale?: string;
+  readonly deterministic?: boolean;
+  readonly version?: string;
+}
+/** A trigger attached to a table or view, retaining its body as opaque SQL. */
+interface CatalogTrigger extends CatalogObjectBase {
+  readonly kind: 'trigger';
+  readonly table: CatalogObjectReference;
+  readonly timing: 'before' | 'after' | 'instead-of' | 'unknown';
+  readonly events: readonly ('insert' | 'update' | 'delete' | 'truncate')[];
+  readonly orientation?: 'row' | 'statement';
+  readonly condition?: CatalogSqlExpression;
+  readonly body: CatalogSqlExpression;
+  readonly enabled?: boolean;
+}
+/** A routine parameter as observed in a function or procedure signature. */
+interface CatalogRoutineParameter {
+  readonly name?: string;
+  readonly mode?: 'in' | 'out' | 'inout' | 'variadic' | 'table';
+  readonly storage: CatalogStorageType;
+  readonly default?: CatalogValueFact;
+  readonly ordinalPosition: number;
+  readonly provenance?: CatalogProvenance;
+}
+/** A function, procedure, aggregate, or other routine declaration. */
+interface CatalogRoutine extends CatalogObjectBase {
+  readonly kind: 'routine';
+  readonly routineKind: 'function' | 'procedure' | 'aggregate' | 'window' | 'unknown';
+  readonly parameters: readonly CatalogRoutineParameter[];
+  readonly returnType?: CatalogStorageType;
+  readonly language?: string;
+  readonly body?: CatalogSqlExpression;
+  readonly volatility?: 'immutable' | 'stable' | 'volatile' | 'unknown';
+  readonly parallel?: 'safe' | 'restricted' | 'unsafe' | 'unknown';
+  readonly security?: 'invoker' | 'definer' | 'unknown';
+  readonly dependencies?: readonly CatalogObjectReference[];
+}
+/** A partition child and its normalized bound expression. */
+interface CatalogPartition extends CatalogObjectBase {
+  readonly kind: 'partition';
+  readonly parent: CatalogObjectReference;
+  readonly strategy: 'range' | 'list' | 'hash' | 'reference' | 'unknown';
+  readonly keyColumns?: readonly string[];
+  readonly bound?: CatalogSqlExpression;
+  readonly default?: boolean;
+}
+/** A row-level security policy attached to a table. */
+interface CatalogPolicy extends CatalogObjectBase {
+  readonly kind: 'policy';
+  readonly table: CatalogObjectReference;
+  readonly command: 'all' | 'select' | 'insert' | 'update' | 'delete' | 'unknown';
+  readonly roles?: readonly string[];
+  readonly permissive?: boolean;
+  readonly using?: CatalogSqlExpression;
+  readonly check?: CatalogSqlExpression;
+}
+/** An engine extension object and its typed, versioned payload. */
+interface CatalogExtensionObject extends CatalogObjectBase {
+  readonly kind: 'extension';
+  readonly extensionName: string;
+  readonly extensionVersion?: string;
+  readonly schema?: string;
+  readonly data: CatalogData;
+  readonly configuration?: CatalogData;
+}
+/** An observed object whose family is not yet modeled by a first-party type. */
+interface CatalogOpaqueObject extends CatalogObjectBase {
+  readonly kind: 'opaque-object';
+  readonly objectKind: string;
+  readonly data: CatalogData;
+  readonly sql?: CatalogSqlExpression;
+}
+/** Naming alias for adapters that call retained objects "unknown" records. */
+type CatalogUnknownObject = CatalogOpaqueObject;
+/** Every complete object family retained by the normalized catalog. */
+type CatalogCompleteObject = CatalogTable | CatalogView | CatalogSequence | CatalogEnum | CatalogDomain | CatalogCollation | CatalogTrigger | CatalogRoutine | CatalogPartition | CatalogPolicy | CatalogExtensionObject | CatalogOpaqueObject | CatalogDeferredObject | CatalogComment | CatalogOwnership;
+/** Short alias for the complete normalized object union. */
+type CatalogObject = CatalogCompleteObject;
+/** The complete normalized catalog shape used by the v2 snapshot mapper. */
+interface CompleteIntrospectionCatalog {
+  readonly dialect: CatalogDialect;
+  readonly server: CatalogServerInfo;
+  readonly capabilities: CatalogCapabilities;
+  readonly namespace: CatalogNamespace;
+  readonly tables: readonly CatalogTable[];
+  readonly views: readonly CatalogView[];
+  readonly sequences: readonly CatalogSequence[];
+  readonly enums: readonly CatalogEnum[];
+  readonly domains: readonly CatalogDomain[];
+  readonly collations: readonly CatalogCollation[];
+  readonly triggers: readonly CatalogTrigger[];
+  readonly routines: readonly CatalogRoutine[];
+  readonly partitions: readonly CatalogPartition[];
+  readonly policies: readonly CatalogPolicy[];
+  readonly extensionObjects: readonly CatalogExtensionObject[];
+  readonly deferredObjects: readonly CatalogDeferredObject[];
+  readonly opaqueObjects: readonly CatalogOpaqueObject[];
+  readonly comments: readonly CatalogComment[];
+  readonly ownership: readonly CatalogOwnership[];
+  readonly diagnostics: readonly IntrospectionDiagnostic[];
+}
+/** The complete normalized catalog for one selected physical namespace. */
+interface IntrospectionCatalog {
+  readonly dialect: CatalogDialect;
+  readonly server: CatalogServerInfo;
+  readonly namespace: CatalogNamespace;
+  readonly tables: readonly CatalogTable[];
+  /** Complete object families are optional until a dialect reader populates them. */
+  readonly views?: readonly CatalogView[];
+  readonly sequences?: readonly CatalogSequence[];
+  readonly enums?: readonly CatalogEnum[];
+  readonly domains?: readonly CatalogDomain[];
+  readonly collations?: readonly CatalogCollation[];
+  readonly triggers?: readonly CatalogTrigger[];
+  readonly routines?: readonly CatalogRoutine[];
+  readonly partitions?: readonly CatalogPartition[];
+  readonly policies?: readonly CatalogPolicy[];
+  readonly extensionObjects?: readonly CatalogExtensionObject[];
+  readonly deferredObjects: readonly CatalogDeferredObject[];
+  readonly opaqueObjects?: readonly CatalogOpaqueObject[];
+  readonly comments?: readonly CatalogComment[];
+  readonly ownership?: readonly CatalogOwnership[];
+  readonly capabilities?: CatalogCapabilities;
+  readonly diagnostics: readonly IntrospectionDiagnostic[];
+}
+/** Strictness of the optional normalized-catalog-to-snapshot step. */
+type IntrospectionMode = 'strict' | 'lossy';
+/** Inputs shared by dialect adapters and the later snapshot mapper. */
+interface IntrospectionOptions {
+  /** PostgreSQL schema, MySQL database, or SQLite database name. */
+  readonly namespace: string;
+  readonly previousSnapshot?: SchemaSnapshot;
+  readonly identityHints?: CatalogIdentityHints;
+  readonly identityPolicy?: CatalogIdentityPolicy;
+  /** Strict is the default. Lossy output must be requested explicitly. */
+  readonly mode?: IntrospectionMode;
+  readonly signal?: AbortSignal;
+}
+/** A successful introspection result with a canonical snapshot. */
+interface IntrospectionSuccess {
+  readonly ok: true;
+  readonly catalog: IntrospectionCatalog;
+  readonly snapshot: SchemaSnapshot;
+  readonly diagnostics: readonly IntrospectionDiagnostic[];
+  readonly lossy: boolean;
+}
+/** A failed introspection result, optionally retaining a partial catalog. */
+interface IntrospectionFailure {
+  readonly ok: false;
+  readonly catalog?: IntrospectionCatalog;
+  readonly diagnostics: readonly IntrospectionDiagnostic[];
+  readonly lossy: false;
+}
+/** Result returned by a non-throwing introspection operation. */
+type IntrospectionResult = IntrospectionSuccess | IntrospectionFailure;
+/** Function shape for a later dialect-specific catalog reader. */
+type CatalogIntrospector = (connection: CatalogConnection, options: IntrospectionOptions) => Promise<IntrospectionResult>;
+//#endregion
+export { CatalogTrigger as $, CatalogNamespace as A, CatalogQuery as At, CatalogPrimaryKeyConstraint as B, CatalogForeignKeyTarget as C, IntrospectionDiagnosticCode as Ct, CatalogIndexTerm as D, createIntrospectionDiagnostic as Dt, CatalogIndex as E, IntrospectionError as Et, CatalogOpaqueObject as F, CatalogRoutine as G, CatalogProvenanceKind as H, CatalogOwnership as I, CatalogSequence as J, CatalogRoutineParameter as K, CatalogPartition as L, CatalogObjectBase as M, CatalogObjectMetadata as N, CatalogIntrospector as O, hasIntrospectionErrors as Ot, CatalogObjectReference as P, CatalogTable as Q, CatalogPolicy as R, CatalogForeignKeyConstraint as S, IntrospectionDiagnostic as St, CatalogIdentity as T, IntrospectionDiagnosticSeverity as Tt, CatalogQueryRow as U, CatalogProvenance as V, CatalogReference as W, CatalogSqlExpression as X, CatalogServerInfo as Y, CatalogStorageType as Z, CatalogEntityReference as _, CatalogIdentityPolicy as _t, CatalogCollation as a, CatalogView as at, CatalogExpressionFact as b, CatalogResolvedIdentity as bt, CatalogCompleteObject as c, IntrospectionFailure as ct, CatalogDeferredObject as d, IntrospectionResult as dt, CatalogUniqueConstraint as et, CatalogDeferredObjectKind as f, IntrospectionSuccess as ft, CatalogEntityKind as g, CatalogIdentityHints as gt, CatalogDomain as h, CatalogIdentityHint as ht, CatalogClassificationConfidence as i, CatalogVersion as it, CatalogObject as j, CatalogQueryOptions as jt, CatalogLiteralFact as k, CatalogConnection as kt, CatalogConstraint as l, IntrospectionMode as lt, CatalogDialectExtension as m, CatalogIdentityFallback as mt, CatalogCatalogReference as n, CatalogUnknownObject as nt, CatalogColumn as o, CompleteIntrospectionCatalog as ot, CatalogDialect as p, CatalogIdentityEntityKind as pt, CatalogScalar as q, CatalogCheckConstraint as r, CatalogValueFact as rt, CatalogComment as s, IntrospectionCatalog as st, CatalogCapabilities as t, CatalogUnknownField as tt, CatalogData as u, IntrospectionOptions as ut, CatalogEnum as v, CatalogIdentitySource as vt, CatalogGeneratedColumn as w, IntrospectionDiagnosticInput as wt, CatalogExtensionObject as x, introspectedPhysicalIdentityPolicy as xt, CatalogEnumValue as y, CatalogPreviousSnapshotIdentitySource as yt, CatalogPortableStorageType as z };