@lakeql/datasource 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1.  Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2.  Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3.  Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4.  Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5.  Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6.  Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7.  Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8.  Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9.  Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/dist/adapter-factory-BzuS1VyB.d.mts

@@ -0,0 +1,375 @@
+import { a as AdapterName, o as SourceConfig, r as DataSourceWriteStrategy } from "./write-a_2WwSyG.mjs";
+import { n as TypeMapper } from "./type-mapper-B7AlDDrp.mjs";
+/**
+ * Neutral authentication types for data source access.
+ *
+ * These types live in `@lakeql/datasource` (design decision 4) because
+ * they are required by the adapter factory and read strategy contracts.
+ */
+/**
+ * Discriminated union of authentication credentials that can be
+ * transported through the core without adapter-specific knowledge.
+ *
+ * The set of variants may be extended by a future auth design, but
+ * the core must carry request auth without interpreting adapter-level
+ * credential details.
+ */
+type DataSourceAuth = {
+  /** Username and password credentials. */
+  type: "basic";
+  /** Username sent to the data source. */
+  username: string;
+  /** Password sent to the data source. */
+  password: string;
+} | {
+  /** Static bearer token credentials. */
+  type: "bearer";
+  /** Token sent in the authorization header. */
+  token: string;
+} | {
+  /** OAuth 2.0 access-token credentials. */
+  type: "oauth2";
+  /** Current OAuth 2.0 access token. */
+  accessToken: string;
+};
+/**
+ * Auth resolution function injected into read strategies and adapter
+ * factories. Given a data source name and an opaque request context,
+ * it returns optional credentials and adapter-level options.
+ *
+ * @param dataSourceName - Configured runtime name of the data source.
+ * @param context - Opaque request context from which credentials can be resolved.
+ * @returns Credentials and adapter-owned options for the request, when available.
+ */
+type ResolveAuth = (dataSourceName: string, context: unknown) => Promise<{
+  /** Credentials to attach to the data-source request. */
+  requestAuth?: DataSourceAuth;
+  /** Adapter-owned request options. */
+  options?: Record<string, unknown>;
+}>;
+/**
+ * Describes actual support for operations, metadata discovery, write
+ * modes, and DDL provided by a data source.
+ *
+ * Adapters populate this at construction time so that the runtime can
+ * avoid selecting unsupported operations.
+ */
+interface DataSourceCapabilities {
+  /** Whether the data source supports query execution. */
+  query: boolean;
+  /** Whether the data source supports streaming results. */
+  stream: boolean;
+  /** Metadata discovery support per catalog object type. */
+  metadata: {
+    /** Whether catalog discovery is supported. */
+    catalogs: boolean;
+    /** Whether schema discovery is supported. */
+    schemas: boolean;
+    /** Whether table discovery is supported. */
+    tables: boolean;
+    /** Whether view discovery is supported. */
+    views: boolean;
+    /** Whether column discovery is supported. */
+    columns: boolean;
+  };
+  /** Write support and available write modes. */
+  write: {
+    supported: boolean;
+    /**
+     * Available write modes — an open string array so that future
+     * adapters can provide modes not known to the core.
+     */
+    modes: string[];
+  };
+  /** DDL support. */
+  ddl: {
+    /** Whether creating tables is supported. */
+    createTable: boolean;
+    /** Whether dropping tables is supported. */
+    dropTable: boolean;
+  };
+}
+/**
+ * Parameters for executing a SQL query against a data source.
+ */
+interface QueryProps {
+  /** SQL statement to execute. */
+  sql: string;
+  /** Optional cancellation signal for the query. */
+  signal?: AbortSignal;
+  /** Credentials resolved for this request. */
+  requestAuth?: DataSourceAuth;
+  /** Adapter-specific query options. */
+  options?: Record<string, unknown>;
+}
+/**
+ * Metadata describing a single column in a table.
+ */
+interface ColumnInfo {
+  /** Column name as exposed by the data source. */
+  name: string;
+  /** Native or normalized data type name. */
+  type: string;
+  /** Additional adapter-provided metadata, such as precision or nullability. */
+  extra?: string;
+  /** Optional human-readable column description. */
+  description?: string;
+}
+/**
+ * Definition for creating a new table.
+ */
+interface TableDefinition {
+  /** Catalog in which to create the table. */
+  catalog: string;
+  /** Schema in which to create the table. */
+  schema: string;
+  /** Name of the table to create. */
+  table: string;
+  /** Ordered column definitions for the new table. */
+  columns: {
+    name: string;
+    type: string;
+  }[];
+}
+/**
+ * Adapter-neutral data source contract.
+ *
+ * Every adapter package implements this interface to provide query
+ * execution, streaming, metadata discovery, DDL, and lifecycle
+ * management without coupling the core to adapter-specific details.
+ */
+interface DataSource {
+  /** Open adapter identifier for this data source instance. */
+  readonly adapter: AdapterName;
+  /** Capabilities supported by this data source. */
+  readonly capabilities: DataSourceCapabilities;
+  /** Maps between this adapter's engine types and LakeQL primitive types. */
+  readonly typeMapper: TypeMapper;
+  /**
+   * Executes a SQL query and returns all matching rows.
+   *
+   * @template TRow - Shape of each row returned by the data source.
+   * @param props - SQL text, optional cancellation signal, request auth, and adapter options.
+   * @returns All rows produced by the query.
+   */
+  query: <TRow>(props: QueryProps) => Promise<TRow[]>;
+  /**
+   * Executes a SQL query and returns its rows as an asynchronous generator.
+   *
+   * @template TRow - Shape of each row yielded by the data source.
+   * @param props - SQL text, optional cancellation signal, request auth, and adapter options.
+   * @returns A generator that yields rows in source order.
+   */
+  stream: <TRow>(props: QueryProps) => Promise<AsyncGenerator<TRow>>;
+  /**
+   * Lists catalogs available to the current data source.
+   *
+   * @returns Catalog names visible to the configured connection.
+   */
+  catalogs: () => Promise<string[]>;
+  /**
+   * Lists schemas within a catalog.
+   *
+   * @param catalog - Catalog whose schemas should be listed.
+   * @returns Schema names in the catalog.
+   */
+  schemas: (catalog: string) => Promise<string[]>;
+  /**
+   * Lists tables within a catalog and schema.
+   *
+   * @param catalog - Catalog containing the schema.
+   * @param schema - Schema whose tables should be listed.
+   * @returns Table names in the schema.
+   */
+  tables: (catalog: string, schema: string) => Promise<string[]>;
+  /**
+   * Lists views within a catalog and schema.
+   *
+   * @param catalog - Catalog containing the schema.
+   * @param schema - Schema whose views should be listed.
+   * @returns View names in the schema.
+   */
+  views: (catalog: string, schema: string) => Promise<string[]>;
+  /**
+   * Lists column metadata for a table.
+   *
+   * @param catalog - Catalog containing the table.
+   * @param schema - Schema containing the table.
+   * @param table - Table whose columns should be listed.
+   * @returns Metadata for the table's columns.
+   */
+  columns: (catalog: string, schema: string, table: string) => Promise<ColumnInfo[]>;
+  /**
+   * Creates a table from a neutral definition.
+   *
+   * @param definition - Target coordinates and ordered column definitions.
+   */
+  createTable: (definition: TableDefinition) => Promise<void>;
+  /**
+   * Drops a table.
+   *
+   * @param catalog - Catalog containing the table.
+   * @param schema - Schema containing the table.
+   * @param table - Table to drop.
+   */
+  dropTable: (catalog: string, schema: string, table: string) => Promise<void>;
+  /**
+   * Builds an adapter-specific fully qualified table name.
+   *
+   * @param config - Source coordinates to qualify.
+   * @returns The data-source-specific qualified table name.
+   */
+  qualifiedTableName: (config: SourceConfig) => string;
+  /** Releases all resources held by this data source. */
+  close: () => Promise<void>;
+}
+/**
+ * Resolved per-data-source paging limits.
+ *
+ * Owned by `@lakeql/datasource` so resolved config values flow to the
+ * adapter factory and read strategies with compile-time assignability.
+ */
+interface ReadStrategyPaging {
+  /** Page size used when a request omits `perPage`. */
+  defaultPerPage: number;
+  /** Upper bound a request's `perPage` may not exceed. */
+  maxRecordsPerPage: number;
+}
+/**
+ * Shared read input that types common values while leaving
+ * filter, schema, and context generic for adapter- or API-specific
+ * extensibility.
+ *
+ * @template TFilter - Filter expression understood by the read implementation.
+ * @template TSchema - Schema or selection metadata understood by the read implementation.
+ * @template TContext - Request-scoped context passed through to the read implementation.
+ */
+interface DataSourceReadInput<TFilter = unknown, TSchema = unknown, TContext = unknown> {
+  /** Table and adapter coordinates for the requested source. */
+  sourceConfig: SourceConfig;
+  /** Source fields to include in the result. */
+  selectFields: readonly string[];
+  /** Adapter- or API-specific filter expression. */
+  filter: TFilter;
+  /**
+   * One-based page number and the requested page size. `perPage` is
+   * optional; the strategy substitutes the resolved default when omitted.
+   */
+  paging: {
+    page: number;
+    perPage?: number | null;
+  };
+  /** Adapter- or API-specific sort definitions. */
+  sorting: readonly unknown[];
+  /** Mapping from source field names to their result aliases. */
+  transformFields: Readonly<Record<string, string>>;
+  /** Fields that require date-specific handling by the adapter. */
+  dateFields: readonly string[];
+  /** Schema or selection metadata required by the read implementation. */
+  schema: TSchema;
+  /** Request-scoped context passed through without core interpretation. */
+  context: TContext;
+}
+/**
+ * Neutral read result exposing total count, page information,
+ * and typed result nodes.
+ *
+ * @template T - Shape of each record in the result page.
+ */
+interface DataSourceReadResult<T> {
+  /** Total number of matching records across all pages. */
+  totalCount: number;
+  /** Paging metadata for the returned result page. */
+  pageInfo: {
+    /** Total number of available pages, or zero when no records match. */
+    maxPages: number;
+    /** Whether another page is available after this one. */
+    hasNext: boolean;
+    /** Whether a page is available before this one. */
+    hasPrevious: boolean;
+    /** One-based number of the returned page. */
+    currentPage: number;
+    /** One-based number of the next page, or `null` when on the last page. */
+    nextPage: number | null;
+    /** One-based number of the previous page, or `null` when on the first page. */
+    previousPage: number | null;
+  };
+  /** Typed records returned for the requested page. */
+  nodes: T[];
+}
+/**
+ * Strategy contract for reading data from a data source.
+ * Adapter-specific read implementations conform to this interface.
+ */
+interface DataSourceReadStrategy {
+  /**
+   * Reads a page of records. Implementations must validate paging before
+   * building or executing their query.
+   *
+   * @template T - Shape of each record returned by the read strategy.
+   * @param input - Source coordinates, selection, filtering, paging, and request context.
+   * @returns A typed page of matching records and its paging metadata.
+   */
+  read: <T>(input: DataSourceReadInput) => Promise<DataSourceReadResult<T>>;
+}
+/**
+ * Adapter factory contract.
+ *
+ * Every adapter package exposes a single factory that the runtime
+ * uses to construct a data source, read strategy, and write strategy
+ * without adapter-specific switch statements.
+ *
+ * Config parameters use `unknown` to keep the core free of
+ * adapter-specific type imports. Adapter factories own validation
+ * and narrowing of their configuration objects.
+ *
+ * Environment-based connection configuration is NOT part of this
+ * contract. If an adapter needs environment parsing, it provides
+ * a separate config-layer provider that feeds the central config
+ * loader.
+ */
+interface AdapterFactory {
+  /** Unique adapter identifier (e.g. `"trino"`, `"fabric"`). */
+  readonly adapterName: AdapterName;
+  /**
+   * Constructs an adapter-owned data source from validated adapter-specific
+   * configuration and its configured runtime name.
+   *
+   * @param config - Adapter-specific configuration to validate and consume.
+   * @param name - Configured runtime name for the new data source.
+   * @returns A data source owned by this adapter.
+   */
+  createDataSource: (config: unknown, name: string) => DataSource;
+  /**
+   * Constructs a read strategy with its data source and auth resolver.
+   *
+   * @param args - The data source and request-auth resolver required by the strategy.
+   * @returns A read strategy owned by this adapter.
+   */
+  createReadStrategy: (args: {
+    /** Data source used to execute reads. */
+    dataSource: DataSource;
+    /** Resolves credentials from the request context. */
+    resolveAuth: ResolveAuth;
+    /**
+     * Resolved per-data-source paging limits from config. Optional so
+     * existing/third-party implementers and test stubs stay valid.
+     */
+    paging?: ReadStrategyPaging;
+  }) => DataSourceReadStrategy;
+  /**
+   * Constructs a write strategy from adapter-owned configuration.
+   *
+   * @param args - The data source, its configured name, and write configuration.
+   * @returns A write strategy owned by this adapter.
+   */
+  createWriteStrategy: (args: {
+    /** Data source used to execute writes. */
+    dataSource: DataSource;
+    /** Configured runtime name of the data source. */
+    dataSourceName: string;
+    /** Validated adapter-specific write configuration. */
+    writeConfig: unknown;
+  }) => DataSourceWriteStrategy;
+}
+export { ReadStrategyPaging as a, QueryProps as c, DataSourceAuth as d, ResolveAuth as f, DataSourceReadStrategy as i, TableDefinition as l, DataSourceReadInput as n, DataSource as o, DataSourceReadResult as r, ColumnInfo as s, AdapterFactory as t, DataSourceCapabilities as u };

package/dist/index.d.mts

@@ -0,0 +1,282 @@
+/**
+ * Adapter-neutral contracts for LakeQL data sources, read strategies,
+ * write strategies, and adapter factories.
+ *
+ * Package: lakeql/datasource
+ */
+import { a as AdapterName, i as LoadStrategy, n as DataSourceWriteInput, o as SourceConfig, r as DataSourceWriteStrategy, t as DataSourceWriteConfig } from "./write-a_2WwSyG.mjs";
+import { a as ReadStrategyPaging, c as QueryProps, d as DataSourceAuth, f as ResolveAuth, i as DataSourceReadStrategy, l as TableDefinition, n as DataSourceReadInput, o as DataSource, r as DataSourceReadResult, s as ColumnInfo, t as AdapterFactory, u as DataSourceCapabilities } from "./adapter-factory-BzuS1VyB.mjs";
+import { n as TypeMapper, t as PrimitiveType } from "./type-mapper-B7AlDDrp.mjs";
+import { UnsupportedWriteStrategy } from "./unsupported-write-strategy.mjs";
+import { TypeMapperTables, createTypeMapper } from "./type-mapper-factory.mjs";
+/**
+ * Category strings that classify operational datasource errors.
+ *
+ * Each category maps to a specific {@link DataSourceError} subclass,
+ * allowing consumers to branch on the category without `instanceof`
+ * checks or message parsing.
+ */
+type DataSourceErrorCategory = "auth" | "query" | "network" | "timeout" | "cancelled" | "unsupported";
+/**
+ * Base operational error for datasource failures.
+ *
+ * Every instance carries a fixed {@link category}, the
+ * {@link adapter} name and {@link dataSource} identifier that
+ * produced the failure, and optionally the lower-level
+ * {@link Error.cause | cause}.
+ *
+ * Adapter-owned configuration and connection errors remain the
+ * adapter's responsibility — they should extend their own error
+ * types, not this one.
+ */
+export declare class DataSourceError extends Error {
+  /** Open identifier of the adapter that produced this error. */
+  readonly adapter: AdapterName;
+  /** Runtime name of the data source that produced this error. */
+  readonly dataSource: string;
+  /** Fixed category classifying this operational error. */
+  readonly category: DataSourceErrorCategory;
+  /**
+   * @param message - Human-readable explanation of the failure. Must not contain credentials.
+   * @param adapter - Open identifier of the adapter that produced this error.
+   * @param dataSource - Runtime name of the data source that produced this error.
+   * @param category - Fixed category for this error class.
+   * @param options - Optional lower-level cause to preserve.
+   */
+  constructor(message: string, adapter: AdapterName, dataSource: string, category: DataSourceErrorCategory, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * Operational error for authentication or authorization failures.
+ *
+ * Fixes {@link DataSourceError.category | category} to `"auth"`.
+ */
+export declare class AuthenticationError extends DataSourceError {
+  /**
+   * @param message - Human-readable explanation of the auth failure. Must not contain credentials.
+   * @param adapter - Open identifier of the adapter that produced this error.
+   * @param dataSource - Runtime name of the data source that produced this error.
+   * @param options - Optional lower-level cause to preserve.
+   */
+  constructor(message: string, adapter: AdapterName, dataSource: string, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * Operational error for explicitly cancelled operations.
+ *
+ * Fixes {@link DataSourceError.category | category} to `"cancelled"`.
+ */
+export declare class CancellationError extends DataSourceError {
+  /**
+   * @param message - Human-readable explanation of the cancellation. Must not contain credentials.
+   * @param adapter - Open identifier of the adapter that produced this error.
+   * @param dataSource - Runtime name of the data source that produced this error.
+   * @param options - Optional lower-level cause to preserve.
+   */
+  constructor(message: string, adapter: AdapterName, dataSource: string, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * Validation error for core contract values.
+ *
+ * Identifies the invalid field and value when the validation logic can
+ * reasonably determine them. Field identification is optional.
+ */
+export declare class DataSourceValidationError extends Error {
+  /** Name of the invalid field, when validation can identify one. */
+  readonly field?: string;
+  /** Invalid value, when validation can safely expose it. */
+  readonly value?: unknown;
+  /**
+   * @param message - Human-readable explanation of the invalid value.
+   * @param options - Optional field, value, and lower-level cause metadata.
+   */
+  constructor(message: string, options?: {
+    field?: string;
+    value?: unknown;
+    cause?: unknown;
+  });
+}
+/**
+ * Operational error for network-level failures (connection refused,
+ * DNS resolution, TLS handshake, etc.).
+ *
+ * Fixes {@link DataSourceError.category | category} to `"network"`.
+ */
+export declare class NetworkError extends DataSourceError {
+  /**
+   * @param message - Human-readable explanation of the network failure. Must not contain credentials.
+   * @param adapter - Open identifier of the adapter that produced this error.
+   * @param dataSource - Runtime name of the data source that produced this error.
+   * @param options - Optional lower-level cause to preserve.
+   */
+  constructor(message: string, adapter: AdapterName, dataSource: string, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * Operational error for query execution failures.
+ *
+ * Fixes {@link DataSourceError.category | category} to `"query"`.
+ */
+export declare class QueryExecutionError extends DataSourceError {
+  /**
+   * @param message - Human-readable explanation of the query failure. Must not contain credentials.
+   * @param adapter - Open identifier of the adapter that produced this error.
+   * @param dataSource - Runtime name of the data source that produced this error.
+   * @param options - Optional lower-level cause to preserve.
+   */
+  constructor(message: string, adapter: AdapterName, dataSource: string, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * Operational error for operations that exceeded a time limit.
+ *
+ * Fixes {@link DataSourceError.category | category} to `"timeout"`.
+ */
+export declare class TimeoutError extends DataSourceError {
+  /**
+   * @param message - Human-readable explanation of the timeout. Must not contain credentials.
+   * @param adapter - Open identifier of the adapter that produced this error.
+   * @param dataSource - Runtime name of the data source that produced this error.
+   * @param options - Optional lower-level cause to preserve.
+   */
+  constructor(message: string, adapter: AdapterName, dataSource: string, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * Operational error for operations that an adapter does not support.
+ *
+ * Fixes {@link DataSourceError.category | category} to `"unsupported"`
+ * and exposes the rejected {@link operation} name.
+ */
+export declare class UnsupportedOperationError extends DataSourceError {
+  /** Name of the unsupported operation (e.g. `"write"`). */
+  readonly operation: string;
+  /**
+   * @param message - Human-readable explanation. Must not contain credentials.
+   * @param adapter - Open identifier of the adapter that produced this error.
+   * @param dataSource - Runtime name of the data source that produced this error.
+   * @param operation - Name of the unsupported operation.
+   * @param options - Optional lower-level cause to preserve.
+   */
+  constructor(message: string, adapter: AdapterName, dataSource: string, operation: string, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * Default upper bound for `perPage` when no {@link ReadValidationConfig}
+ * override is supplied.
+ */
+export declare const DEFAULT_MAX_PER_PAGE = 10000;
+/**
+ * Configuration for read-input validation.
+ */
+interface ReadValidationConfig {
+  /**
+   * Maximum allowed `perPage` value.
+   *
+   * @default 10000
+   */
+  maxPerPage?: number;
+}
+/**
+ * Validates paging (and optional sorting) parameters before query building.
+ *
+ * Read-strategy implementations MUST call this before building or executing
+ * any query. Invalid input throws a {@link DataSourceValidationError} to block
+ * query construction.
+ *
+ * Rules:
+ * - `page`: finite integer ≥ 1.
+ * - `perPage`: finite integer between 1 and `config.maxPerPage`
+ *   (default {@link DEFAULT_MAX_PER_PAGE}).
+ * - `sorting` (when present): must be an array.
+ *
+ * @param paging - One-based page number, page size, and optional sorting.
+ * @param config - Optional validation limits (e.g. `maxPerPage`).
+ * @throws {DataSourceValidationError} When any value is out of range or of the
+ *   wrong shape.
+ */
+export declare function validatePaging(paging: {
+  page: number;
+  perPage: number;
+  sorting?: readonly unknown[];
+}, config?: ReadValidationConfig): void;
+/**
+ * Adapter-neutral SQL rendering primitives shared across LakeQL adapters.
+ *
+ * These helpers own the escaping and validation semantics that every adapter
+ * must apply identically: control-character rejection, single-quote literal
+ * escaping, qualified-identifier joining, and strict plain-object detection.
+ * Dialect-specific identifier quoting (double-quote vs bracket doubling) stays
+ * per-adapter and is injected into {@link quoteQualified}.
+ *
+ * @module
+ */
+/**
+ * Throws if `value` contains any C0 (U+0000–U+001F) or C1 (U+007F–U+009F)
+ * control character.
+ *
+ * @param value - The raw string to validate.
+ * @param context - Human-readable label used in the thrown error message.
+ * @throws {Error} If `value` contains a C0 or C1 control character.
+ */
+export declare function rejectControlChars(value: string, context: string): void;
+/**
+ * Escape a value as a SQL string literal.
+ *
+ * The input is treated as a string literal value. Embedded single-quote
+ * characters are escaped by doubling them (`'` → `''`), and the result is
+ * wrapped in single quotes. The escaping is identical across the Trino and
+ * Fabric dialects.
+ *
+ * @param value - The raw string value to escape.
+ * @returns The safely single-quoted literal string.
+ * @throws {Error} If `value` contains C0/C1 control characters.
+ *
+ * @example
+ * ```ts
+ * escapeLiteral("hello")           // => "'hello'"
+ * escapeLiteral("it's")            // => "'it''s'"
+ * escapeLiteral("schema'name")     // => "'schema''name'"
+ * ```
+ */
+export declare function escapeLiteral(value: string): string;
+/**
+ * Quote a fully-qualified identifier composed of one or more segments.
+ *
+ * Applies the dialect-specific `quoteFn` independently to each segment and
+ * joins them with literal dots. Requires at least one segment. The per-segment
+ * quoting semantics are owned by the caller's `quoteFn`.
+ *
+ * @param quoteFn - Dialect-specific single-segment quoter (e.g. double-quote or bracket).
+ * @param segments - One or more raw identifier segments (e.g. catalog, schema, table).
+ * @returns The safely quoted qualified identifier string.
+ * @throws {Error} If no segments are provided, or if any segment is invalid per `quoteFn`.
+ *
+ * @example
+ * ```ts
+ * quoteQualified(quoteIdentifier, "iceberg", "public", "orders")
+ * // => '"iceberg"."public"."orders"'  (with a double-quote quoteFn)
+ * ```
+ */
+export declare function quoteQualified(quoteFn: (segment: string) => string, ...segments: string[]): string;
+/**
+ * Returns `true` if `value` is a non-null plain object: its prototype is
+ * `Object.prototype` or `null`, and it is not an array.
+ *
+ * This is the strict variant shared across all adapter modules. It rejects
+ * class instances, Date, RegExp, and other exotic objects, and it is safe for
+ * prototype-less objects created via `Object.create(null)`.
+ *
+ * @param value - The value to test.
+ * @returns `true` if `value` is a plain object, otherwise `false`.
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+export { type AdapterFactory, type AdapterName, type ColumnInfo, type DataSource, type DataSourceAuth, type DataSourceCapabilities, type DataSourceErrorCategory, type DataSourceReadInput, type DataSourceReadResult, type DataSourceReadStrategy, type DataSourceWriteConfig, type DataSourceWriteInput, type DataSourceWriteStrategy, type LoadStrategy, type PrimitiveType, type QueryProps, type ReadStrategyPaging, type ReadValidationConfig, type ResolveAuth, type SourceConfig, type TableDefinition, type TypeMapper, type TypeMapperTables, UnsupportedWriteStrategy, createTypeMapper };

package/dist/index.mjs

@@ -0,0 +1 @@
+import{n as e,r as t,t as n}from"./unsupported-write-strategy-MBzQRkBF.mjs";import{createTypeMapper as r}from"./type-mapper-factory.mjs";var i=class extends t{constructor(e,t,n,r){super(e,t,n,`auth`,r),this.name=`AuthenticationError`}},a=class extends t{constructor(e,t,n,r){super(e,t,n,`cancelled`,r),this.name=`CancellationError`}},o=class extends Error{field;value;constructor(e,t){super(e,{cause:t?.cause}),this.name=`DataSourceValidationError`,this.field=t?.field,this.value=t?.value}},s=class extends t{constructor(e,t,n,r){super(e,t,n,`network`,r),this.name=`NetworkError`}},c=class extends t{constructor(e,t,n,r){super(e,t,n,`query`,r),this.name=`QueryExecutionError`}},l=class extends t{constructor(e,t,n,r){super(e,t,n,`timeout`,r),this.name=`TimeoutError`}};const u=1e4;function d(e,t){let n=t?.maxPerPage??1e4;if(!Number.isInteger(e.page)||e.page<1)throw new o(`Invalid page value: ${e.page}. Must be a positive integer.`,{field:`page`,value:e.page});if(!Number.isInteger(e.perPage)||e.perPage<1)throw new o(`Invalid perPage value: ${e.perPage}. Must be a positive integer.`,{field:`perPage`,value:e.perPage});if(e.perPage>n)throw new o(`Invalid perPage value: ${e.perPage}. Must not exceed ${n}.`,{field:`perPage`,value:e.perPage});if(e.sorting!==void 0&&!Array.isArray(e.sorting))throw new o(`Invalid sorting value: expected an array.`,{field:`sorting`,value:e.sorting})}const f=/[\u0000-\u001F\u007F-\u009F]/u;function p(e,t){if(f.test(e))throw Error(`${t} must not contain control characters (C0 U+0000–U+001F or C1 U+007F–U+009F)`)}function m(e){return p(e,`String literal`),`'${e.replaceAll(`'`,`''`)}'`}function h(e,...t){if(t.length===0)throw Error(`quoteQualified requires at least one segment`);return t.map(e).join(`.`)}function g(e){if(typeof e!=`object`||!e||Array.isArray(e))return!1;let t=Object.getPrototypeOf(e);return t===Object.prototype||t===null}export{i as AuthenticationError,a as CancellationError,u as DEFAULT_MAX_PER_PAGE,t as DataSourceError,o as DataSourceValidationError,s as NetworkError,c as QueryExecutionError,l as TimeoutError,e as UnsupportedOperationError,n as UnsupportedWriteStrategy,r as createTypeMapper,m as escapeLiteral,g as isPlainObject,h as quoteQualified,p as rejectControlChars,d as validatePaging};

package/dist/testing/index.d.mts

@@ -0,0 +1,65 @@
+import { a as AdapterName, n as DataSourceWriteInput, o as SourceConfig, r as DataSourceWriteStrategy } from "../write-a_2WwSyG.mjs";
+import { a as ReadStrategyPaging, c as QueryProps, f as ResolveAuth, i as DataSourceReadStrategy, l as TableDefinition, n as DataSourceReadInput, o as DataSource, r as DataSourceReadResult, s as ColumnInfo, t as AdapterFactory, u as DataSourceCapabilities } from "../adapter-factory-BzuS1VyB.mjs";
+import { n as TypeMapper } from "../type-mapper-B7AlDDrp.mjs";
+/**
+ * Minimal fake `DataSource` implementation for testing.
+ *
+ * All methods return no-op stubs. Does not import `@lakeql/config`
+ * or any concrete adapter package.
+ */
+export declare class FakeDataSource implements DataSource {
+  readonly adapter: AdapterName;
+  readonly capabilities: DataSourceCapabilities;
+  readonly typeMapper: TypeMapper;
+  query<TRow>(_props: QueryProps): Promise<TRow[]>;
+  _streamGenerator<TRow>(): AsyncGenerator<TRow>;
+  stream<TRow>(_props: QueryProps): Promise<AsyncGenerator<TRow>>;
+  catalogs(): Promise<string[]>;
+  schemas(_catalog: string): Promise<string[]>;
+  tables(_catalog: string, _schema: string): Promise<string[]>;
+  views(_catalog: string, _schema: string): Promise<string[]>;
+  columns(_catalog: string, _schema: string, _table: string): Promise<ColumnInfo[]>;
+  createTable(_definition: TableDefinition): Promise<void>;
+  dropTable(_catalog: string, _schema: string, _table: string): Promise<void>;
+  qualifiedTableName(config: SourceConfig): string;
+  close(): Promise<void>;
+}
+/**
+ * Minimal fake `AdapterFactory` for testing.
+ *
+ * Proves that a third-party adapter can implement the factory contract
+ * without importing `@lakeql/config` or any concrete adapter package.
+ */
+export declare class FakeAdapterFactory implements AdapterFactory {
+  readonly adapterName = "fake";
+  createDataSource(_config: unknown, _name: string): DataSource;
+  createReadStrategy(_args: {
+    dataSource: DataSource;
+    resolveAuth: ResolveAuth;
+    paging?: ReadStrategyPaging;
+  }): DataSourceReadStrategy;
+  createWriteStrategy(_args: {
+    dataSource: DataSource;
+    dataSourceName: string;
+    writeConfig: unknown;
+  }): DataSourceWriteStrategy;
+}
+/**
+ * Minimal fake `DataSourceReadStrategy` for testing.
+ *
+ * Returns empty results with valid page info. Does not import
+ * `@lakeql/config` or any concrete adapter package.
+ */
+export declare class FakeReadStrategy implements DataSourceReadStrategy {
+  read: <T>(_input: DataSourceReadInput) => Promise<DataSourceReadResult<T>>;
+}
+/**
+ * Minimal fake write strategy for testing.
+ * Simulates a direct-insert write without importing `@lakeql/storage`.
+ */
+export declare class FakeWriteStrategy implements DataSourceWriteStrategy {
+  /** Record batches received through {@link write}, in call order. */
+  readonly writtenRecords: Record<string, unknown>[][];
+  /** Records the input batch without writing it to an external system. */
+  write: (input: DataSourceWriteInput) => Promise<void>;
+}

package/dist/testing/index.mjs

@@ -0,0 +1 @@
+var e=class{adapter=`fake`;capabilities={query:!0,stream:!0,metadata:{catalogs:!0,schemas:!0,tables:!0,views:!0,columns:!0},write:{supported:!0,modes:[`full_load`,`append`]},ddl:{createTable:!0,dropTable:!0}};typeMapper={toPrimitiveType:e=>`String`,toEngineType:e=>e};query(e){return Promise.resolve([])}async*_streamGenerator(){}stream(e){return Promise.resolve(this._streamGenerator())}catalogs(){return Promise.resolve([])}schemas(e){return Promise.resolve([])}tables(e,t){return Promise.resolve([])}views(e,t){return Promise.resolve([])}columns(e,t,n){return Promise.resolve([])}createTable(e){return Promise.resolve()}dropTable(e,t,n){return Promise.resolve()}qualifiedTableName(e){return`${e.catalog}.${e.schema}.${e.tableName}`}close(){return Promise.resolve()}},t=class{adapterName=`fake`;createDataSource(t,n){return new e}createReadStrategy(e){return{read:async e=>({totalCount:0,pageInfo:{maxPages:0,hasNext:!1,hasPrevious:!1,currentPage:1,nextPage:null,previousPage:null},nodes:[]})}}createWriteStrategy(e){return{write:async e=>{}}}},n=class{read=async e=>({totalCount:0,pageInfo:{maxPages:0,hasNext:!1,hasPrevious:!1,currentPage:1,nextPage:null,previousPage:null},nodes:[]})},r=class{writtenRecords=[];write=async e=>{this.writtenRecords.push(e.records)}};export{t as FakeAdapterFactory,e as FakeDataSource,n as FakeReadStrategy,r as FakeWriteStrategy};

package/dist/type-mapper-B7AlDDrp.d.mts

@@ -0,0 +1,43 @@
+/**
+ * Adapter-neutral type mapping between engine-specific data types and the
+ * canonical LakeQL primitive type system.
+ *
+ * @module
+ */
+/**
+ * The canonical LakeQL primitive types used across codegen and metadata.
+ *
+ * This union mirrors `PrimitiveType` in `@lakeql/schema-generator`
+ * (the source of truth). It is duplicated here on purpose: this contract
+ * package must not depend on an implementation package. Keep the two in sync.
+ */
+type PrimitiveType = "String" | "Integer" | "Float" | "Boolean" | "Date" | "DateTime";
+/**
+ * Maps between an adapter's engine-specific data types and LakeQL
+ * {@link PrimitiveType}s.
+ *
+ * Each adapter provides its own implementation that understands its engine's
+ * native type system (Trino, T-SQL, etc.).
+ */
+interface TypeMapper {
+  /**
+   * Converts an engine-specific type string to a LakeQL {@link PrimitiveType}.
+   *
+   * Implementations SHALL normalize the input (case, type parameters) and
+   * fall back to `"String"` when the engine type has no known mapping.
+   *
+   * @param engineType - The engine-specific type string (e.g. `"varchar(255)"`,
+   *   `"nvarchar"`, `"bigint"`).
+   * @returns The corresponding LakeQL primitive type.
+   */
+  toPrimitiveType: (engineType: string) => PrimitiveType;
+  /**
+   * Converts a LakeQL {@link PrimitiveType} to the engine's native type string.
+   *
+   * @param primitiveType - The LakeQL primitive type to convert.
+   * @returns The corresponding engine-specific type string (e.g. `"VARCHAR"`,
+   *   `"BIGINT"`).
+   */
+  toEngineType: (primitiveType: PrimitiveType) => string;
+}
+export { TypeMapper as n, PrimitiveType as t };

package/dist/type-mapper-factory.d.mts

@@ -0,0 +1,29 @@
+/**
+ * Shared factory for building a {@link TypeMapper} from two lookup records.
+ *
+ * @module
+ */
+import { n as TypeMapper, t as PrimitiveType } from "./type-mapper-B7AlDDrp.mjs";
+/**
+ * Lookup tables that define an adapter's type mapping in both directions.
+ */
+export interface TypeMapperTables {
+  /**
+   * Maps a normalized engine type (lowercased, without parameters) to a LakeQL
+   * {@link PrimitiveType}. Unknown engine types fall back to `"String"`.
+   */
+  toPrimitive: Record<string, PrimitiveType>;
+  /** Maps each LakeQL {@link PrimitiveType} to the engine's native type string. */
+  toEngine: Record<PrimitiveType, string>;
+}
+/**
+ * Builds a {@link TypeMapper} from an adapter's engine↔primitive lookup tables.
+ *
+ * The returned `toPrimitiveType` normalizes its input before the lookup and
+ * falls back to `"String"` for unknown engine types. `toEngineType` reads the
+ * mapping for the closed {@link PrimitiveType} union.
+ *
+ * @param tables - The adapter's bidirectional type-mapping tables.
+ * @returns A {@link TypeMapper} backed by the supplied tables.
+ */
+export declare function createTypeMapper(tables: TypeMapperTables): TypeMapper;

package/dist/type-mapper-factory.mjs

@@ -0,0 +1 @@
+function e(e){return e.toLowerCase().replaceAll(/\(.*\)/gu,``).trim()}function t(t){let{toPrimitive:n,toEngine:r}=t;return{toPrimitiveType(t){return n[e(t)]??`String`},toEngineType(e){return r[e]}}}export{t as createTypeMapper};

package/dist/unsupported-write-strategy-MBzQRkBF.mjs

@@ -0,0 +1 @@
+var e=class extends Error{adapter;dataSource;category;constructor(e,t,n,r,i){super(e,{cause:i?.cause}),this.name=`DataSourceError`,this.adapter=t,this.dataSource=n,this.category=r}},t=class extends e{operation;constructor(e,t,n,r,i){super(e,t,n,`unsupported`,i),this.name=`UnsupportedOperationError`,this.operation=r}},n=class{#e;#t;constructor(e){this.#e=e.adapter,this.#t=e.dataSource}write(e){return Promise.reject(new t(`Adapter "${this.#e}" does not support write operations`,this.#e,this.#t,`write`))}};export{t as n,e as r,n as t};

package/dist/unsupported-write-strategy.d.mts

@@ -0,0 +1,31 @@
+import { a as AdapterName, n as DataSourceWriteInput, r as DataSourceWriteStrategy } from "./write-a_2WwSyG.mjs";
+/**
+ * A write strategy that rejects every write with an
+ * {@link UnsupportedOperationError}.
+ *
+ * Adapter factories use this to satisfy the {@link DataSourceWriteStrategy}
+ * contract when the adapter does not yet provide a real write path.
+ */
+export declare class UnsupportedWriteStrategy implements DataSourceWriteStrategy {
+  #private;
+  /**
+   * @param options - Adapter and data-source identifiers attached to the
+   *   rejection error.
+   * @param options.adapter - Open identifier of the adapter.
+   * @param options.dataSource - Runtime name of the data source.
+   */
+  constructor(options: {
+    adapter: AdapterName;
+    dataSource: string;
+  });
+  /**
+   * Always rejects with an {@link UnsupportedOperationError}.
+   *
+   * The input is intentionally ignored — the strategy does not inspect,
+   * destructure, validate, log, mutate, forward, or otherwise access it.
+   *
+   * @param _input - Write input (unused).
+   * @returns A promise that rejects with an `UnsupportedOperationError`.
+   */
+  write(_input: DataSourceWriteInput): Promise<void>;
+}

package/dist/unsupported-write-strategy.mjs

@@ -0,0 +1 @@
+export{t as UnsupportedWriteStrategy}from"./unsupported-write-strategy-MBzQRkBF.mjs";

package/dist/write-a_2WwSyG.d.mts

@@ -0,0 +1,89 @@
+/**
+ * Open adapter name type.
+ *
+ * Adapter identifiers are plain strings so that third-party adapters
+ * do not require changes to a central union type.
+ */
+type AdapterName = string;
+/**
+ * Shared source configuration that identifies a table within a
+ * data source without coupling to adapter-specific connection details.
+ */
+interface SourceConfig {
+  /** Runtime name of the configured data source. */
+  dataSource: string;
+  /** Open identifier of the adapter that owns this source. */
+  adapter: AdapterName;
+  /** Source catalog containing the target table. */
+  catalog: string;
+  /** Source schema containing the target table. */
+  schema: string;
+  /** Name of the target table. */
+  tableName: string;
+}
+/**
+ * Supported load strategies for write operations.
+ *
+ * - `full_load` — replace the target table completely
+ * - `full_load_append` — replace existing partitions; append new ones
+ * - `append` — add records without removing existing data
+ */
+type LoadStrategy = "full_load" | "full_load_append" | "append";
+/**
+ * Shared write configuration containing table coordinates and
+ * optional common write settings. Storage-backed strategies may
+ * require `basePath`; direct-insert strategies omit it.
+ */
+interface DataSourceWriteConfig {
+  /** Catalog, schema, and table name of the write target. */
+  table: {
+    catalog: string;
+    schema: string;
+    tableName: string;
+  };
+  /** Behavior to apply when records reach an existing target. */
+  loadStrategy?: LoadStrategy;
+  /** Storage base path required by storage-backed write strategies. */
+  basePath?: string;
+  /**
+   * When `true`, instructs strategies that manage shadow tables
+   * to retain them after the write completes. Useful for debugging
+   * or auditing intermediate state.
+   */
+  keepShadowTables?: boolean;
+  /**
+   * Reserved for future idempotency support. Accepting this value
+   * now ensures forward-compatible configuration, but it has no
+   * current behavioral effect.
+   */
+  writeId?: string;
+  /** Adapter-owned partitioning configuration. */
+  partitioning?: unknown;
+  /** Adapter-owned format for partition values. */
+  partitioningFormat?: string;
+}
+/**
+ * Schema-library-agnostic write input containing records, a generic
+ * schema value, and write configuration.
+ */
+interface DataSourceWriteInput {
+  /** Records to write to the configured target. */
+  records: Record<string, unknown>[];
+  /** Schema understood by the adapter-owned write implementation. */
+  schema: unknown;
+  /** Common and adapter-owned settings for this write. */
+  config: DataSourceWriteConfig;
+}
+/**
+ * Strategy contract for writing data to a data source.
+ * Adapter-specific write implementations conform to this interface.
+ */
+interface DataSourceWriteStrategy {
+  /**
+   * Writes the supplied records and completes when the write has finished.
+   *
+   * @param input - Records, schema, and configuration for the write operation.
+   */
+  write: (input: DataSourceWriteInput) => Promise<void>;
+}
+export { AdapterName as a, LoadStrategy as i, DataSourceWriteInput as n, SourceConfig as o, DataSourceWriteStrategy as r, DataSourceWriteConfig as t };

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@lakeql/datasource",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Adapter-neutral contracts for LakeQL data sources, read strategies, write strategies, and adapter factories",
+  "keywords": [
+    "contracts",
+    "datasource",
+    "lakeql",
+    "types"
+  ],
+  "homepage": "https://lakeql.dev",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Marcus Reinhardt",
+    "url": "https://github.com/noxify"
+  },
+  "contributors": [
+    {
+      "name": "Marcus Reinhardt",
+      "url": "https://github.com/noxify"
+    }
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/noxify/lakeql",
+    "directory": "packages/datasource"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.mts",
+      "import": "./dist/testing/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@lakeql/tsconfig": "0.1.0",
+    "@lakeql/vitest-config": "0.1.0",
+    "@types/node": "24.19.2",
+    "fast-check": "4.10.2",
+    "tsdown": "0.23.7",
+    "typescript": "6.0.3",
+    "vitest": "5.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "git clean -xdf .cache .turbo dist node_modules dist",
+    "clean:cache": "git clean -xdf .cache .turbo",
+    "clean:dist": "git clean -xdf dist",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.