semanticdb-v2 2.0.0-alpha.6 → 2.0.0-alpha.7

package/README.md

@@ -167,6 +167,114 @@ Providers execute only parameterized `sql + parameters`; SemanticDB never execut
 Because `displaySql` contains literal values and may expose sensitive data, use it only in trusted
 debugging and observability channels.
 
+### Native SQL and table discovery
+
+`DBConnector` provides trusted physical database operations independently of LogicForm execution:
+
+```ts
+import { DBConnector, Logicform } from 'semanticdb-v2';
+import type { DatabaseConnection } from 'semanticdb-v2';
+
+const connection = {
+  id: 'analytics',
+  kind: 'mysql',
+  host: 'localhost',
+  user: 'analytics',
+  password: process.env.MYSQL_PASSWORD ?? '',
+  database: 'analytics',
+} satisfies DatabaseConnection;
+
+const tables = await DBConnector.getTableList({ connection });
+// [{ name: 'orders', database: 'analytics', type: 'table' }, ...]
+
+const description = await DBConnector.describeTable({ connection, table: 'orders' });
+// {
+//   columns: [{ name: 'id', type: 'int', comment: 'Order ID', primaryKey: true, exampleValue: 42 }, ...],
+//   tableInfo: { name: 'orders', database: 'analytics', type: 'table', comment: 'Orders' },
+// }
+
+const { rows } = await DBConnector.runSQL({
+  connection,
+  sql: 'SELECT * FROM orders WHERE status = ?',
+  parameters: ['paid'],
+});
+
+const updated = await DBConnector.runSQL({
+  connection,
+  sql: 'UPDATE orders SET status = ? WHERE id = ?',
+  parameters: ['shipped', 42],
+});
+// { rows: [], affectedRows: 1 }
+
+// The exact same object belongs in Logicform.execute's connections array:
+// await Logicform.execute(logicform, { connections: [connection], schemas, schemaMappings });
+
+await Logicform.close(); // DBConnector.close() is the same shutdown operation.
+```
+
+Both APIs share providers and connection pools by connection ID and `providerRegistry`. An ID must
+retain the same configuration until shutdown. Providers and pools are initialized lazily. Either
+`close()` releases **all** SDK-managed connections, including those used by the other API; it does
+not close just the last connector connection.
+
+`runSQL` returns `{ rows: DataRow[], affectedRows?: number }`. Commands without a result set return
+an empty array; affected-row counts are included only when the driver reports them. SQL is passed
+through without automatic LIMIT, dialect translation, Schema mapping, hydration, generated `_id`,
+or query caching. It does **not** enforce `ExecuteOptions.permissions`: use trusted callers and
+appropriately restricted database accounts. Supply values through `parameters` using the native
+provider placeholders: `?` for MySQL-compatible databases, Databricks, Dameng, Snowflake and MaxCompute;
+`$1` for PostgreSQL; `@p0` for SQL Server; `:1` for Oracle; typed `{p0:String}`-style
+placeholders for ClickHouse. ClickHouse uses JSONEachRow output; do not override it with another
+FORMAT. Each call is independent, with Oracle/Dameng command execution automatically committed;
+cross-call transactions and multi-statement/multi-result execution are not supported.
+
+`getTableList` returns `{ name, database?, schema?, type: 'table' | 'view' }[]` for accessible tables
+and views, retaining namespaces to distinguish same-name tables. Optional `database` and `schema`
+override only this metadata lookup, never the cached connection configuration:
+
+- MySQL, Doris, StarRocks, GBase and ClickHouse: `database`; `schema` is rejected.
+- PostgreSQL, Oracle and Dameng: `schema`; cross-database overrides are rejected. Defaults to the
+  current schema (or the configured Dameng schema).
+- SQL Server and Snowflake: `database` and `schema`. SQL Server lists all accessible schemas in
+  the database by default; Snowflake defaults to the current schema.
+- Databricks: `database` means catalog, and `schema` means schema. Defaults come from the connection's
+  `catalog` and `schema` (`connection.database` remains the existing legacy alias for schema).
+- MaxCompute: the existing injected client handles `SHOW TABLES`, returning rows with `table_name`.
+  It may implement `getTableList(request)` for project/schema overrides and view metadata, and
+  `runSQL(request)` for affected-row counts. Otherwise commands must return `[]` through `execute`.
+
+`describeTable({ connection, table, database?, schema?, includeSample? })` inspects one physical
+table or view. `table` is a literal **unqualified** name; provide its namespace separately, using
+the same scope rules as `getTableList`. A dot inside `table` is part of the identifier, not a separator.
+Do not pass a SQL expression or the legacy semantic Schema/`from` object. SQL Server descriptions
+default to the connection's current default schema; pass `schema` explicitly when describing a
+table returned from another schema. Column order follows the database's definition.
+
+The result has `columns: { name, type, comment, primaryKey?, exampleValue? }[]` and
+`tableInfo: { name, database?, schema?, type, comment }`. These are physical names/native types,
+not semantic Properties; no `_id` is added. Comments default to an empty string. Primary-key
+membership includes every column of composite keys; unique-only indexes are not primary keys.
+ClickHouse reports its storage primary key, which does not imply relational uniqueness. If the
+adapter cannot determine primary-key membership (Databricks/Snowflake), `primaryKey` is omitted
+rather than guessed. Example values preserve driver types, including `null`.
+
+Like the legacy API, descriptions read one example row by default. Set `includeSample: false`
+for metadata-only inspection, avoiding a data read. Empty tables and failed sample queries still
+return metadata without example values; metadata failures, tables not found in the selected namespace, and
+cancellation reject. All SQL uses bound metadata values and quoted identifiers, bypassing
+LogicForm permissions and caching just like `runSQL`.
+
+MaxCompute clients may implement `describeTable(request)` to provide project/schema-aware
+metadata. Otherwise the fallback runs `DESC` and expects structured rows with `column_name`,
+`column_type`, optional `column_comment` and `is_primary_key`. Legacy UDBC ASCII `Info` reports
+must be normalized by the client; unparsed reports are rejected rather than producing empty columns.
+
+All operations accept `signal` and the same optional `providerRegistry` as `Logicform.execute`.
+Custom providers opt in through `runSQL(request)`, `getTableList(request)` and `describeTable(request)`; missing capabilities
+fail explicitly without changing the existing provider `execute` contract. Unsupported discovery
+scopes are rejected rather than silently ignored. Cancellation does not guarantee rollback of
+commands that have already reached the database.
+
 ### Permissions
 
 Pass table, row, and column permissions together through `ExecuteOptions.permissions`:

package/dist/executor/connection-registry.d.ts

@@ -1,12 +1 @@
-import type { CoreComputeProvider, DatabaseConnection, ProviderRegistry } from '../physical/index';
-type ProviderFactory = (connection: DatabaseConnection) => CoreComputeProvider;
-export declare class ConnectionRegistry {
-    #private;
-    private readonly create;
-    constructor(create?: ProviderFactory);
-    get(connection: DatabaseConnection): CoreComputeProvider;
-    close(): Promise<void>;
-}
-export declare const getConnectionProvider: (connection: DatabaseConnection, providers?: ProviderRegistry) => CoreComputeProvider;
-export declare const closeConnections: () => Promise<void>;
-export {};
+export { ConnectionRegistry, getConnectionProvider, closeConnections } from '../physical/index';

package/dist/index.d.ts

@@ -16,7 +16,8 @@ export type { CalendarAlignment, CalendarComparison, CalendarDateRow, CalendarRe
 export type { CalendarRelationStore } from './calendar/index';
 export type { PrimalType, PropertyHierarchyDefinition, PropertySqlDefinition, ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticTypeNormalizeContext, SemanticPropertyDraft, SemanticSchemaDraft, SemanticTypeDefinition, SemanticTypeResultContext, SemanticTypeResultProperty, TimeGranularity, TimeWatermarkPolicy, } from './semantic-types/index';
 export type { DataRow, SqlParameters, BuiltinDatabaseConnection, DatabaseConnection, DatabaseConnectionBase, DatabaseConnectionExtensions, ProviderDefinition, ProviderKind, ProviderKindExtensions, } from './physical/index';
-export { ProviderRegistry } from './physical/index';
+export { DBConnector, ProviderRegistry } from './physical/index';
+export type { DBConnectorOptions, RunSQLOptions, GetTableListOptions, DescribeTableOptions, DescribeTableRequest, DatabaseColumn, TableDescription, DatabaseTable, SQLResult, TableListRequest, } from './physical/index';
 export type { OperatorDefinition, OperatorDefaultNameContext, OperatorComponentContext, OperatorComponentCalculation, OperatorComponentQuery, OperatorExecutionComponent, OperatorPlanInputContext, OperatorPlannedInput, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorEvaluateContext, OperatorOutputPropertyContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, ResultPropertyTemporalMetadataExtensions, } from './operators/index';
 export type { SchemaMappingDefinition, SchemaMappingEnrichmentDefinition, SchemaMappingEnrichmentKey, SchemaMappingItem, SchemaMappingGranularity, SchemaMappingGranularityExtensions, SchemaMappingPointTemporalDefinition, SchemaMappingPredDefinition, SchemaMappingPredMatch, SchemaMappingSelection, RejectedSchemaMapping, SourceFreshnessPolicy, YiAskSchemaMappingItem, YiAskSchemaMappingRecord, } from './schema-mappings/index';
 export type { QueryCache, QueryCacheExecutionOptions, QueryCacheIdentity, QueryCacheWriteOptions, } from './cache/index';

package/dist/normalizer/core.d.ts

@@ -16,6 +16,15 @@ export interface NormalizeLogicformOptions {
     readonly now?: Date;
     readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
     readonly requestTimeWatermark?: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty, requestedUpperBound: Date) => Promise<Date | undefined>;
+    readonly requestAutoCaseBounds?: (schema: ResolvedSemanticSchema, reference: string, query: LogicformType['query']) => Promise<{
+        readonly min: number;
+        readonly max: number;
+        readonly count: number;
+    } | {
+        readonly empty: true;
+    }>;
+    /** Internal root query used to resolve automatic `$case` boundaries. */
+    readonly autoCaseQuery?: LogicformType['query'];
     readonly resolveFromSchema?: (normalizedFrom: LogicformType, outerSchema: ResolvedSemanticSchema) => ResolvedSemanticSchema;
     readonly canProjectProperty?: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty) => boolean;
     /** Internal recursion hook installed by normalizeLogicform. */

package/dist/physical/clickhouse-provider.d.ts

@@ -1,4 +1,4 @@
-import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest } from './provider';
+import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest, SQLResult, DatabaseTable, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
 interface ClickHouseResultLike {
     json<T>(): Promise<T>;
 }
@@ -9,6 +9,17 @@ export interface ClickHouseClientLike {
         query_params: Readonly<Record<string, unknown>>;
         abort_signal?: AbortSignal;
     }): Promise<ClickHouseResultLike>;
+    /** Native SDK exec does not append a FORMAT clause to commands. */
+    exec?(options: {
+        query: string;
+        query_params: Readonly<Record<string, unknown>>;
+        clickhouse_settings: {
+            readonly default_format: 'JSONEachRow';
+        };
+        abort_signal?: AbortSignal;
+    }): Promise<{
+        readonly stream: AsyncIterable<string | Buffer>;
+    }>;
     close(): Promise<void>;
 }
 export interface ClickHouseProviderOptions {
@@ -52,6 +63,9 @@ export declare class ClickHouseProvider implements CoreComputeProvider {
         valueExpression: string;
     };
     execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    getTableList(request: TableListRequest): Promise<DatabaseTable[]>;
+    describeTable(request: DescribeTableRequest): Promise<TableDescription>;
+    runSQL(request: ProviderExecutionRequest): Promise<SQLResult>;
     close(): Promise<void>;
 }
 export {};

package/dist/physical/connection-registry.d.ts

@@ -0,0 +1,13 @@
+import type { DatabaseConnection, ProviderRegistry } from './connection';
+import type { CoreComputeProvider } from './provider';
+type ProviderFactory = (connection: DatabaseConnection) => CoreComputeProvider;
+export declare class ConnectionRegistry {
+    #private;
+    private readonly create;
+    constructor(create?: ProviderFactory);
+    get(connection: DatabaseConnection): CoreComputeProvider;
+    close(): Promise<void>;
+}
+export declare const getConnectionProvider: (connection: DatabaseConnection, providers?: ProviderRegistry) => CoreComputeProvider;
+export declare const closeConnections: () => Promise<void>;
+export {};

package/dist/physical/dameng-provider.d.ts

@@ -1,4 +1,4 @@
-import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest } from './provider';
+import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest, SQLResult, DatabaseTable, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
 type DamengBind = string | number | Date | Buffer | null;
 export interface DamengConnectionOptions {
     readonly connectString?: string;
@@ -15,8 +15,10 @@ export interface DamengConnectionOptions {
 export interface DamengConnectionLike {
     execute(sql: string, binds: DamengBind[], options: {
         readonly outFormat: number;
+        readonly autoCommit?: boolean;
     }): Promise<{
         readonly rows?: unknown[];
+        readonly rowsAffected?: number;
     }>;
     close(): Promise<void>;
 }
@@ -56,6 +58,9 @@ export declare class DamengProvider implements CoreComputeProvider {
     stringLength(expression: string): string;
     regex(expression: string, pattern: string, options?: string): string;
     execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    runSQL(request: ProviderExecutionRequest): Promise<SQLResult>;
+    getTableList(request: TableListRequest): Promise<DatabaseTable[]>;
+    describeTable(request: DescribeTableRequest): Promise<TableDescription>;
     close(): Promise<void>;
 }
 export {};

package/dist/physical/databricks-provider.d.ts

@@ -1,4 +1,4 @@
-import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest } from './provider';
+import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest, SQLResult, DatabaseTable, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
 type DatabricksBind = string | number | boolean | bigint | Date | null;
 export interface DatabricksConnectionBase {
     readonly host: string;
@@ -29,6 +29,8 @@ export interface DatabricksOAuthAuth {
 export type DatabricksConnectionOptions = DatabricksConnectionBase & (DatabricksAccessTokenAuth | DatabricksOAuthAuth);
 export interface DatabricksOperationLike {
     fetchAll(): Promise<unknown>;
+    /** The native SDK can finish commands that have no result set to fetch. */
+    finished?(): Promise<void>;
     cancel(): Promise<unknown>;
     close(): Promise<unknown>;
 }
@@ -78,6 +80,9 @@ export declare class DatabricksProvider implements CoreComputeProvider {
         valueExpression: string;
     };
     execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    runSQL(request: ProviderExecutionRequest): Promise<SQLResult>;
+    describeTable(request: DescribeTableRequest): Promise<TableDescription>;
+    getTableList(request: TableListRequest): Promise<DatabaseTable[]>;
     close(): Promise<void>;
 }
 export {};

package/dist/physical/db-connector.d.ts

@@ -0,0 +1,23 @@
+import type { DatabaseConnection, ProviderRegistry } from './connection';
+import type { DatabaseTable, SQLResult, SqlParameters, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
+export interface DBConnectorOptions {
+    /** Exactly the same connection object accepted by Logicform.execute.connections. */
+    readonly connection: DatabaseConnection;
+    readonly providerRegistry?: ProviderRegistry;
+    readonly signal?: AbortSignal;
+}
+export interface RunSQLOptions extends DBConnectorOptions {
+    readonly sql: string;
+    readonly parameters?: SqlParameters;
+}
+export interface GetTableListOptions extends DBConnectorOptions, TableListRequest {
+}
+export interface DescribeTableOptions extends DBConnectorOptions, DescribeTableRequest {
+}
+/** Trusted physical operations; no LogicForm permissions, rewriting, or caching. */
+export declare const DBConnector: Readonly<{
+    runSQL: (options: RunSQLOptions) => Promise<SQLResult>;
+    getTableList: (options: GetTableListOptions) => Promise<DatabaseTable[]>;
+    describeTable: (options: DescribeTableOptions) => Promise<TableDescription>;
+    close: () => Promise<void>;
+}>;

package/dist/physical/index.d.ts

@@ -1,5 +1,8 @@
 /** Internal physical adapters selected from the public database connection configuration. */
-export type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest, ProviderKind, ProviderKindExtensions, SqlRenderCapabilities, SqlParameters, } from './provider';
+export type { CoreComputeProvider, DatePart, DataRow, DatabaseTable, SQLResult, TableListRequest, DescribeTableRequest, DatabaseColumn, TableDescription, ProviderExecutionRequest, ProviderKind, ProviderKindExtensions, SqlRenderCapabilities, SqlParameters, } from './provider';
+export { ConnectionRegistry, getConnectionProvider, closeConnections } from './connection-registry';
+export { DBConnector } from './db-connector';
+export type { DBConnectorOptions, RunSQLOptions, GetTableListOptions, DescribeTableOptions } from './db-connector';
 export { builtinProviderDefinitions, createProvider, defaultProviderRegistry, ProviderRegistry, } from './connection';
 export type { BuiltinDatabaseConnection, DatabaseConnection, DatabaseConnectionBase, DatabaseConnectionExtensions, ProviderDefinition, } from './connection';
 export { DuckDBCoordinatorProvider } from './duckdb-coordinator-provider';

package/dist/physical/maxcompute-provider.d.ts

@@ -1,10 +1,14 @@
-import type { CoreComputeProvider, DataRow, DatePart, ProviderExecutionRequest, SqlParameters } from './provider';
+import type { CoreComputeProvider, DataRow, DatePart, ProviderExecutionRequest, SqlParameters, SQLResult, DatabaseTable, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
 /**
  * Parameterized MaxCompute execution boundary supplied by the application.
  * Implementations must bind `parameters`; they must not interpolate them into `sql`.
  */
 export interface MaxComputeClientLike {
     execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    /** Optional command metadata and project/schema-aware discovery extensions. */
+    runSQL?(request: ProviderExecutionRequest): Promise<SQLResult>;
+    getTableList?(request: TableListRequest): Promise<DatabaseTable[]>;
+    describeTable?(request: DescribeTableRequest): Promise<TableDescription>;
     close(): Promise<void>;
 }
 export interface MaxComputeConnectionOptions {
@@ -33,5 +37,8 @@ export declare class MaxComputeProvider implements CoreComputeProvider {
     stringLength(expression: string): string;
     regex(expression: string, pattern: string, options?: string): string;
     execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    runSQL(request: ProviderExecutionRequest): Promise<SQLResult>;
+    getTableList(request: TableListRequest): Promise<DatabaseTable[]>;
     close(): Promise<void>;
+    describeTable(request: DescribeTableRequest): Promise<TableDescription>;
 }

package/dist/physical/mysql-protocol-provider.d.ts

@@ -1,4 +1,4 @@
-import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest, SqlParameters } from './provider';
+import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest, SqlParameters, SQLResult, DatabaseTable, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
 export interface MySQLProtocolPoolLike {
     execute(sql: string, values: readonly unknown[]): Promise<readonly [unknown, unknown]>;
     end(): Promise<void>;
@@ -47,5 +47,8 @@ export declare abstract class MySQLProtocolProvider implements CoreComputeProvid
         readonly valueExpression: string;
     };
     execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    runSQL(request: ProviderExecutionRequest): Promise<SQLResult>;
+    getTableList(request: TableListRequest): Promise<DatabaseTable[]>;
+    describeTable(request: DescribeTableRequest): Promise<TableDescription>;
     close(): Promise<void>;
 }

package/dist/physical/oracle-provider.d.ts

@@ -1,10 +1,12 @@
-import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest } from './provider';
+import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest, SQLResult, DatabaseTable, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
 type OracleBind = string | number | boolean | Date | Buffer | null;
 export interface OracleConnectionLike {
     execute(sql: string, binds: OracleBind[], options: {
         readonly outFormat: number;
+        readonly autoCommit?: boolean;
     }): Promise<{
         readonly rows?: unknown[] | undefined;
+        readonly rowsAffected?: number | undefined;
     }>;
     break(): Promise<void>;
     close(): Promise<void>;
@@ -60,6 +62,9 @@ export declare class OracleProvider implements CoreComputeProvider {
         valueExpression: string;
     };
     execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    runSQL(request: ProviderExecutionRequest): Promise<SQLResult>;
+    getTableList(request: TableListRequest): Promise<DatabaseTable[]>;
+    describeTable(request: DescribeTableRequest): Promise<TableDescription>;
     close(): Promise<void>;
 }
 export {};

package/dist/physical/postgresql-provider.d.ts

@@ -1,7 +1,9 @@
-import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest } from './provider';
+import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest, SQLResult, DatabaseTable, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
 export interface PostgreSQLPoolLike {
     query(sql: string, values: unknown[]): Promise<{
         readonly rows: unknown;
+        readonly rowCount?: number | null;
+        readonly command?: string;
     }>;
     end(): Promise<void>;
 }
@@ -48,5 +50,8 @@ export declare class PostgreSQLProvider implements CoreComputeProvider {
         valueExpression: string;
     };
     execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    getTableList(request: TableListRequest): Promise<DatabaseTable[]>;
+    describeTable(request: DescribeTableRequest): Promise<TableDescription>;
+    runSQL(request: ProviderExecutionRequest): Promise<SQLResult>;
     close(): Promise<void>;
 }

package/dist/physical/provider.d.ts

@@ -10,6 +10,46 @@ export interface ProviderExecutionRequest {
     readonly parameters: SqlParameters;
     readonly signal?: AbortSignal;
 }
+/** Native SQL results, without semantic hydration or generated row identities. */
+export interface SQLResult {
+    readonly rows: DataRow[];
+    /** Omitted when the driver does not report an affected-row count. */
+    readonly affectedRows?: number;
+}
+export interface DatabaseTable {
+    readonly name: string;
+    readonly database?: string;
+    readonly schema?: string;
+    readonly type: 'table' | 'view';
+}
+export interface TableListRequest {
+    /** Database/catalog override; unsupported scopes are rejected, not ignored. */
+    readonly database?: string;
+    readonly schema?: string;
+    readonly signal?: AbortSignal;
+}
+export interface DescribeTableRequest extends TableListRequest {
+    /** Literal, unqualified physical table name; use database/schema for its namespace. */
+    readonly table: string;
+    /** Read one example row by default. Disable to inspect metadata only. */
+    readonly includeSample?: boolean;
+}
+export interface DatabaseColumn {
+    readonly name: string;
+    /** Native database type, including size/precision where available. */
+    readonly type: string;
+    readonly comment: string;
+    /** Omitted if the database/adapter cannot report primary-key membership. */
+    readonly primaryKey?: boolean;
+    /** Omitted for empty tables, disabled sampling, or a failed sample query. */
+    readonly exampleValue?: unknown;
+}
+export interface TableDescription {
+    readonly columns: DatabaseColumn[];
+    readonly tableInfo: DatabaseTable & {
+        readonly comment: string;
+    };
+}
 export interface SqlRenderCapabilities {
     /** Whether HAVING may reference an alias declared in the same SELECT list. */
     readonly supportsHavingAlias?: boolean;
@@ -53,5 +93,10 @@ export interface CoreComputeProvider extends SqlRenderCapabilities {
     /** Render bound parameters for diagnostics only; this SQL is never executed by SemanticDB. */
     displayQuery(sql: string, parameters: SqlParameters): string;
     execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    /** Optional native-SQL capability; execute retains its row-query contract. */
+    runSQL?(request: ProviderExecutionRequest): Promise<SQLResult>;
+    /** Optional physical metadata capability, independent of semantic Schemas. */
+    getTableList?(request: TableListRequest): Promise<DatabaseTable[]>;
+    describeTable?(request: DescribeTableRequest): Promise<TableDescription>;
     close(): Promise<void>;
 }

package/dist/physical/snowflake-provider.d.ts

@@ -1,7 +1,8 @@
-import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest } from './provider';
+import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest, SQLResult, DatabaseTable, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
 type SnowflakeBind = string | number | boolean | null;
 export interface SnowflakeStatementLike {
     cancel(callback?: (error?: Error) => void): void;
+    getNumUpdatedRows?(): number | undefined;
 }
 export interface SnowflakeConnectionLike {
     connect(callback: (error?: Error) => void): unknown;
@@ -53,6 +54,9 @@ export declare class SnowflakeProvider implements CoreComputeProvider {
         valueExpression: string;
     };
     execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    runSQL(request: ProviderExecutionRequest): Promise<SQLResult>;
+    getTableList(request: TableListRequest): Promise<DatabaseTable[]>;
+    describeTable(request: DescribeTableRequest): Promise<TableDescription>;
     close(): Promise<void>;
 }
 export {};

package/dist/physical/sqlserver-provider.d.ts

@@ -1,9 +1,10 @@
-import type { CoreComputeProvider, DataRow, DatePart, ProviderExecutionRequest } from './provider';
+import type { CoreComputeProvider, DataRow, DatePart, ProviderExecutionRequest, SQLResult, DatabaseTable, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
 type SQLServerBind = string | number | boolean | Date | Buffer | null;
 export interface SQLServerRequestLike {
     input(name: string, value: SQLServerBind): this;
     query(sql: string): Promise<{
         readonly recordset?: unknown;
+        readonly rowsAffected?: readonly number[];
     }>;
     cancel(): void;
 }
@@ -60,6 +61,9 @@ export declare class SQLServerProvider implements CoreComputeProvider {
         readonly valueExpression: string;
     };
     execute(execution: ProviderExecutionRequest): Promise<DataRow[]>;
+    runSQL(execution: ProviderExecutionRequest): Promise<SQLResult>;
+    getTableList(request: TableListRequest): Promise<DatabaseTable[]>;
+    describeTable(request: DescribeTableRequest): Promise<TableDescription>;
     close(): Promise<void>;
 }
 export {};

package/dist/physical/table-description.d.ts

@@ -0,0 +1,5 @@
+import type { CoreComputeProvider, DataRow, DescribeTableRequest, TableDescription } from './provider';
+export declare const validateDescribeTable: (request: DescribeTableRequest) => void;
+/** INFORMATION_SCHEMA/Oracle expose size separately; PostgreSQL/MySQL already format native types. */
+export declare const columnType: (row: DataRow) => string;
+export declare const describePhysicalTable: (provider: CoreComputeProvider, request: DescribeTableRequest) => Promise<TableDescription>;

package/dist/physical/table-discovery.d.ts

@@ -0,0 +1,10 @@
+import type { CoreComputeProvider, DatabaseTable, DataRow, TableListRequest } from './provider';
+export declare const validateTableScope: (request: TableListRequest) => void;
+export declare const rejectTableScope: (provider: CoreComputeProvider, field: "database" | "schema") => never;
+/** Drivers differ in alias casing; never silently discard malformed metadata rows. */
+export declare const metadataValue: (row: DataRow, field: string) => unknown;
+export declare const metadataString: (row: DataRow, field: string) => string;
+export declare const normalizeTableRow: (row: DataRow) => DatabaseTable;
+export declare const normalizeTableMetadata: (rows: DataRow[]) => DatabaseTable[];
+/** Physical metadata SQL only; no semantic Schema resolution belongs here. */
+export declare const discoverTables: (provider: CoreComputeProvider, request: TableListRequest) => Promise<DatabaseTable[]>;