@sixb/ducklake 0.1.7 → 0.1.9

package/dist/internal/dataset-row-commit.d.ts

@@ -12,6 +12,16 @@ export interface ApplyDatasetRowsResult {
     readonly dataChangeExpected: boolean;
     readonly sourceRowCount: number;
     readonly resultingRowCount: CommitRowCount;
+    /**
+     * The table held no rows when this transaction read it. A write into an empty table deletes
+     * nothing, so DuckLake lets it commit alongside a concurrent one that also read the table empty.
+     */
+    readonly targetWasEmpty: boolean;
+    /**
+     * The write inserted or deleted rows of the dataset table, which DuckLake checks against
+     * concurrent changes to the table. A merge that only advances source ordering changes none.
+     */
+    readonly changedTableRows: boolean;
 }
 export declare function assertDatasetWriteMode(mode: unknown, operation: string): asserts mode is DatasetWriteMode;
 export declare function applyDatasetRowsFromRelation(input: {

package/dist/internal/dataset-row-commit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset-row-commit.d.ts","sourceRoot":"","sources":["../../src/internal/dataset-row-commit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,EACL,KAAK,gBAAgB,EAGtB,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AAEtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAK1D,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAA;AAEhC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAA;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,cAAc,CAAA;CAC3C;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,IAAI,gBAAgB,CAMlC;AAED,wBAAsB,4BAA4B,CAAC,KAAK,EAAE;IACxD,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAA;IACxC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;IACnC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CACnC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAoElC;AAED,wBAAsB,0BAA0B,CAAC,KAAK,EAAE;IACtD,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BlB"}
+{"version":3,"file":"dataset-row-commit.d.ts","sourceRoot":"","sources":["../../src/internal/dataset-row-commit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,EACL,KAAK,gBAAgB,EAGtB,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AAEtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAK1D,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAA;AAEhC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAA;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,cAAc,CAAA;IAC1C;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;CACnC;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,IAAI,gBAAgB,CAMlC;AAED,wBAAsB,4BAA4B,CAAC,KAAK,EAAE;IACxD,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAA;IACxC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;IACnC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CACnC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA+ElC;AAED,wBAAsB,0BAA0B,CAAC,KAAK,EAAE;IACtD,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BlB"}

package/dist/internal/dataset-row-merge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset-row-merge.d.ts","sourceRoot":"","sources":["../../src/internal/dataset-row-merge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAQnD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAAE,KAAK,sBAAsB,EAA8B,MAAM,sBAAsB,CAAA;AAE9F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAK1D,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAA;IACxC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;IACnC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,0BAA0B,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACxD;AAQD,wBAAsB,6BAA6B,CACjD,KAAK,EAAE,kCAAkC,GACxC,OAAO,CAAC,sBAAsB,CAAC,CAyEjC"}
+{"version":3,"file":"dataset-row-merge.d.ts","sourceRoot":"","sources":["../../src/internal/dataset-row-merge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAQnD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAAE,KAAK,sBAAsB,EAA8B,MAAM,sBAAsB,CAAA;AAE9F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAK1D,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAA;IACxC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;IACnC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,0BAA0B,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACxD;AAQD,wBAAsB,6BAA6B,CACjD,KAAK,EAAE,kCAAkC,GACxC,OAAO,CAAC,sBAAsB,CAAC,CA6EjC"}

package/dist/internal/ducklake-dataset-catalog.d.ts

@@ -2,6 +2,18 @@ import type { DatasetDefinition, DatasetSchema } from "@sixb/core";
 import type { DuckLakeStorageOptions } from "../types";
 import type { DuckDbQueryRuntime } from "./duckdb-runtime";
 import type { DuckLakeConnectionManager } from "./ducklake-connection-manager";
+import type { DatasetTableRef } from "./ducklake-dataset-table-ref";
+import type { DuckLakeVersionSummary } from "./ducklake-snapshot-reader";
+import { type LatestVersionAtSnapshot } from "./ducklake-version-transaction";
+/**
+ * Reads the latest version of a dataset, which a schema change keeps the rows of, as
+ * `BeginVersionTransactionInput.readLatestVersion`.
+ */
+export type LatestDatasetVersionReader = (runtime: DuckDbQueryRuntime, definition: DatasetDefinition) => Promise<LatestVersionAtSnapshot<DuckLakeVersionSummary>>;
+export interface DatasetSchemaAtSnapshotRequest {
+    readonly table: DatasetTableRef;
+    readonly snapshotId: string;
+}
 /**
  * Translates between Sixb dataset definitions and DuckLake table metadata.
  *
@@ -13,14 +25,19 @@ export declare class DuckLakeDatasetCatalog {
     private readonly options;
     private readonly connections;
     constructor(options: DuckLakeStorageOptions, connections: DuckLakeConnectionManager);
-    createDataset(definition: DatasetDefinition): Promise<DatasetDefinition>;
+    createDataset(definition: DatasetDefinition, readLatestVersion: LatestDatasetVersionReader): Promise<DatasetDefinition>;
     assertDatasetDefinitionsCompatible(definitions: readonly DatasetDefinition[]): Promise<void>;
     getDataset(datasetId: string): Promise<DatasetDefinition | null>;
     getDatasetOnRuntime(runtime: DuckDbQueryRuntime, datasetId: string): Promise<DatasetDefinition | null>;
     listDatasets(): Promise<readonly DatasetDefinition[]>;
     private readCurrentDatasetDefinitions;
     private readCurrentDatasetDefinitionsOnRuntime;
-    getDatasetSchemaAtSnapshot(runtime: DuckDbQueryRuntime, datasetId: string, tableName: string, tableId: bigint, snapshotId: string): Promise<DatasetSchema>;
+    /**
+     * Dataset schemas at DuckLake snapshots, in request order, from one catalog read: a column row
+     * is visible from its begin_snapshot until its end_snapshot, so the rows alive anywhere between
+     * the oldest and the newest requested snapshot answer every request.
+     */
+    getDatasetSchemasAtSnapshots(runtime: DuckDbQueryRuntime, requests: readonly DatasetSchemaAtSnapshotRequest[]): Promise<readonly DatasetSchema[]>;
     assertSchema(definition: DatasetDefinition): void;
     private applyExistingDatasetUpdate;
     private applySchemaEvolutionDdl;
@@ -29,6 +46,6 @@ export declare class DuckLakeDatasetCatalog {
     private applyPrimaryKey;
     private setSchemaEvolutionCommitMetadata;
     private rollbackTransaction;
-    private readDatasetColumnsAtSnapshot;
+    private readDatasetColumnsBetweenSnapshots;
 }
 //# sourceMappingURL=ducklake-dataset-catalog.d.ts.map

package/dist/internal/ducklake-dataset-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ducklake-dataset-catalog.d.ts","sourceRoot":"","sources":["../../src/internal/ducklake-dataset-catalog.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAOlE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AAEtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAO1D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAA;AAY9E;;;;;;GAMG;AACH,qBAAa,sBAAsB;IAE/B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW;gBADX,OAAO,EAAE,sBAAsB,EAC/B,WAAW,EAAE,yBAAyB;IAGnD,aAAa,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAiExE,kCAAkC,CACtC,WAAW,EAAE,SAAS,iBAAiB,EAAE,GACxC,OAAO,CAAC,IAAI,CAAC;IAwCV,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAQhE,mBAAmB,CACvB,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAU9B,YAAY,IAAI,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC;YAU7C,6BAA6B;YAY7B,sCAAsC;IAW9C,0BAA0B,CAC9B,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC;IAazB,YAAY,CAAC,UAAU,EAAE,iBAAiB,GAAG,IAAI;YAOnC,0BAA0B;YA+B1B,uBAAuB;YAYvB,kBAAkB;YAmBlB,gBAAgB;YA0BhB,eAAe;YAoBf,gCAAgC;YAwBhC,mBAAmB;YASnB,4BAA4B;CAgC3C"}
+{"version":3,"file":"ducklake-dataset-catalog.d.ts","sourceRoot":"","sources":["../../src/internal/ducklake-dataset-catalog.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAYlE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AAEtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAO1D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAA;AAE9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAA;AACnE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAA;AACxE,OAAO,EAGL,KAAK,uBAAuB,EAE7B,MAAM,gCAAgC,CAAA;AAYvC;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAAG,CACvC,OAAO,EAAE,kBAAkB,EAC3B,UAAU,EAAE,iBAAiB,KAC1B,OAAO,CAAC,uBAAuB,CAAC,sBAAsB,CAAC,CAAC,CAAA;AAE7D,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAUD;;;;;;GAMG;AACH,qBAAa,sBAAsB;IAE/B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW;gBADX,OAAO,EAAE,sBAAsB,EAC/B,WAAW,EAAE,yBAAyB;IAGnD,aAAa,CACjB,UAAU,EAAE,iBAAiB,EAC7B,iBAAiB,EAAE,0BAA0B,GAC5C,OAAO,CAAC,iBAAiB,CAAC;IAiFvB,kCAAkC,CACtC,WAAW,EAAE,SAAS,iBAAiB,EAAE,GACxC,OAAO,CAAC,IAAI,CAAC;IAwCV,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAQhE,mBAAmB,CACvB,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAU9B,YAAY,IAAI,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC;YAU7C,6BAA6B;YAY7B,sCAAsC;IAWpD;;;;OAIG;IACG,4BAA4B,CAChC,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,EAAE,SAAS,8BAA8B,EAAE,GAClD,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC;IAsCpC,YAAY,CAAC,UAAU,EAAE,iBAAiB,GAAG,IAAI;YAOnC,0BAA0B;YAoD1B,uBAAuB;YAYvB,kBAAkB;YAmBlB,gBAAgB;YA0BhB,eAAe;YAoBf,gCAAgC;YA0BhC,mBAAmB;YASnB,kCAAkC;CAwCjD"}

package/dist/internal/ducklake-dataset-table-ref.d.ts

@@ -4,6 +4,19 @@ export interface DatasetTableRef {
     readonly datasetId: string;
     readonly tableName: string;
     readonly tableId: bigint;
+    /** The table a sequenced dataset keeps its source ordering in, which merges also change. */
+    readonly sequenceTableId?: bigint;
 }
 export declare function resolveDatasetTableRef(options: DuckLakeStorageOptions, runtime: DuckDbQueryRuntime, datasetId: string): Promise<DatasetTableRef | null>;
+/**
+ * The dataset's tables and the lake's current snapshot, in one catalog read. Inside a
+ * transaction, reading the current snapshot also fixes the transaction's DuckLake snapshot, which
+ * DuckLake otherwise fixes on its first read of the lake.
+ */
+export declare function resolveDatasetTableRefAtCurrentSnapshot(options: DuckLakeStorageOptions, runtime: DuckDbQueryRuntime, datasetId: string): Promise<{
+    readonly snapshotId: string;
+    readonly table: DatasetTableRef | null;
+}>;
+/** Every table a dataset's versions change. */
+export declare function datasetTableIds(table: Omit<DatasetTableRef, "tableName">): readonly bigint[];
 //# sourceMappingURL=ducklake-dataset-table-ref.d.ts.map

package/dist/internal/ducklake-dataset-table-ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ducklake-dataset-table-ref.d.ts","sourceRoot":"","sources":["../../src/internal/ducklake-dataset-table-ref.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AAEtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAI1D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,sBAAsB,EAC/B,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAkBjC"}
+{"version":3,"file":"ducklake-dataset-table-ref.d.ts","sourceRoot":"","sources":["../../src/internal/ducklake-dataset-table-ref.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AAEtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAI1D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAClC;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,sBAAsB,EAC/B,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAEjC;AAED;;;;GAIG;AACH,wBAAsB,uCAAuC,CAC3D,OAAO,EAAE,sBAAsB,EAC/B,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAA;CAAE,CAAC,CAmBlF;AAED,+CAA+C;AAC/C,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,GAAG,SAAS,MAAM,EAAE,CAI5F"}

package/dist/internal/ducklake-maintenance.d.ts

@@ -1,9 +1,29 @@
 import type { DuckLakeMaintenanceOptions, DuckLakeMaintenanceReport, DuckLakeStorageOptions } from "../types";
 import type { DuckLakeConnectionManager } from "./ducklake-connection-manager";
+import type { DuckLakeSnapshotReader } from "./ducklake-snapshot-reader";
+/**
+ * Expires old snapshots, except those holding a version that is still needed, then reclaims files.
+ *
+ * DuckLake's own `older_than` would expire the latest version of a dataset idle longer than the
+ * retention, leaving its rows without a version to read them through. Maintenance lists the
+ * snapshots older than the retention, keeps those holding each dataset's latest version or a
+ * protected version, and expires the rest by id. DuckLake then schedules the files only the
+ * expired snapshots referenced, as it does with `older_than`.
+ */
 export declare class DuckLakeMaintenance {
     private readonly options;
     private readonly connections;
-    constructor(options: DuckLakeStorageOptions, connections: DuckLakeConnectionManager);
+    private readonly snapshots;
+    constructor(options: DuckLakeStorageOptions, connections: DuckLakeConnectionManager, snapshots: DuckLakeSnapshotReader);
     runMaintenance(options?: DuckLakeMaintenanceOptions): Promise<DuckLakeMaintenanceReport>;
+    private runMaintenanceProcedures;
+    /**
+     * Snapshots older than the retention, except the current one, which DuckLake never expires.
+     *
+     * Not DuckLake's own `older_than` selection: a SQLite catalog stores snapshot times as text with
+     * their UTC offset, and with DuckLake 415a9ebd that selection then also returned snapshots
+     * written a moment ago outside UTC. Casting the stored text compares instants on every catalog.
+     */
+    private snapshotsOlderThan;
 }
 //# sourceMappingURL=ducklake-maintenance.d.ts.map

package/dist/internal/ducklake-maintenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ducklake-maintenance.d.ts","sourceRoot":"","sources":["../../src/internal/ducklake-maintenance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACvB,MAAM,UAAU,CAAA;AAEjB,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAA;AAW9E,qBAAa,mBAAmB;IAE5B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW;gBADX,OAAO,EAAE,sBAAsB,EAC/B,WAAW,EAAE,yBAAyB;IAGnD,cAAc,CAClB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,yBAAyB,CAAC;CAoCtC"}
+{"version":3,"file":"ducklake-maintenance.d.ts","sourceRoot":"","sources":["../../src/internal/ducklake-maintenance.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACvB,MAAM,UAAU,CAAA;AAGjB,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAA;AAC9E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAA;AAaxE;;;;;;;;GAQG;AACH,qBAAa,mBAAmB;IAE5B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAFT,OAAO,EAAE,sBAAsB,EAC/B,WAAW,EAAE,yBAAyB,EACtC,SAAS,EAAE,sBAAsB;IAG9C,cAAc,CAClB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,yBAAyB,CAAC;YAmCvB,wBAAwB;IAoDtC;;;;;;OAMG;YACW,kBAAkB;CAiBjC"}

package/dist/internal/ducklake-snapshot-reader.d.ts

@@ -1,14 +1,33 @@
-import type { DatasetDefinition } from "@sixb/core";
-import type { DatasetCatalogState, DatasetVersion, DatasetVersionRef } from "@sixb/core/lake-storage";
+import type { DatasetDefinition, DatasetSchema } from "@sixb/core";
+import type { DatasetCatalogState, DatasetProducer, DatasetVersion, DatasetVersionLineage, DatasetVersionMode, DatasetVersionRef, LatestVersionsSince, ListLatestVersionsSinceInput } from "@sixb/core/lake-storage";
 import type { DuckLakeStorageOptions } from "../types";
 import type { DuckDbQueryRuntime } from "./duckdb-runtime";
 import type { DuckLakeConnectionManager } from "./ducklake-connection-manager";
 import type { DuckLakeDatasetCatalog } from "./ducklake-dataset-catalog";
 import { type DatasetTableRef } from "./ducklake-dataset-table-ref";
+import type { LatestVersionAtSnapshot } from "./ducklake-version-transaction";
+import { type SixbCommitMetadata } from "./versions";
+export interface DatasetSnapshotRow {
+    readonly snapshotId: string;
+    readonly tableId: bigint;
+    readonly createdAt: Date;
+    readonly mode: DatasetVersionMode;
+    readonly parentSnapshotId?: string;
+    readonly metadata?: SixbCommitMetadata;
+}
+/** A version reference, with the DuckLake table and snapshot it was resolved through. */
+export interface DuckLakeTableVersionRef extends DatasetVersionRef {
+    readonly table: DatasetTableRef;
+    readonly snapshot: DatasetSnapshotRow;
+}
+/** What a commit needs of the version it builds on. */
 export interface DuckLakeVersionSummary {
     readonly datasetId: string;
     readonly versionId: string;
+    readonly schema: DatasetSchema;
+    readonly producer?: DatasetProducer;
     readonly inputs?: readonly DatasetVersionRef[];
+    readonly lineage?: DatasetVersionLineage;
     readonly rowCount?: number;
     readonly validatedPrimaryKeyColumns?: readonly string[];
 }
@@ -21,8 +40,13 @@ export interface DuckLakeVersionSummary {
  *
  * This class intentionally reads DuckLake metadata directly. The provider does
  * not keep a Sixb side table for versions; a Sixb version is a DuckLake
- * snapshot that either changed the dataset table or was explicitly tagged with
- * Sixb dataset metadata.
+ * snapshot whose `changes_made` names the dataset table: one that changed its
+ * rows, or that altered the table with Sixb commit metadata naming the dataset,
+ * as a version that changes no rows does (see the write coordinator's
+ * `claimTable`).
+ *
+ * DuckLake names a table in `changes_made` for every change to its rows, inlined
+ * or written to files, so version reads never scan the catalog's file tables.
  */
 export declare class DuckLakeSnapshotReader {
     private readonly options;
@@ -41,8 +65,28 @@ export declare class DuckLakeSnapshotReader {
      */
     listDatasetCatalogState(datasetIds: readonly string[]): Promise<readonly DatasetCatalogState[]>;
     private collectDatasetCatalogState;
+    /**
+     * Change feed over DuckLake's snapshot table, which is an append-only commit log: snapshot ids
+     * only increase, and a commit becomes visible only after every lower id has (concurrent commits
+     * that pick the same id conflict, and the loser retries with the next one). The cursor is the
+     * last snapshot id read. Every query is bounded by a snapshot-id range, so an idle read is one
+     * indexed query that returns the cursor's own snapshot, whatever the history length.
+     */
+    listLatestVersionsSince(input: ListLatestVersionsSinceInput): Promise<LatestVersionsSince | null>;
+    private queryHeadSnapshotId;
+    /** The cursor's snapshot and up to one feed page of snapshots after it, oldest first. */
+    private querySnapshotsFrom;
+    /** Current dataset tables, with the first snapshot each table id existed in. */
+    private resolveFeedTables;
+    /** Folds a page of snapshots, oldest first, into each dataset's newest data version. */
+    private collectFeedPage;
+    /**
+     * The snapshot of every dataset's latest version, however old, from one shared walk down the
+     * whole history: maintenance must never expire one.
+     */
+    latestVersionSnapshotIds(runtime: DuckDbQueryRuntime): Promise<readonly string[]>;
     private snapshotRowToSummary;
-    private resolveDatasetTableIds;
+    private resolveDatasetTables;
     /**
      * Resolve each dataset's latest snapshot row with one shared descending walk.
      *
@@ -52,14 +96,24 @@ export declare class DuckLakeSnapshotReader {
      */
     private resolveLatestSnapshotRows;
     private queryCatalogSnapshotBatch;
-    private queryFileChangeFlags;
     private assertNoMetadataConflict;
     getLatestVersionForDefinition(runtime: DuckDbQueryRuntime, dataset: DatasetDefinition): Promise<DatasetVersion | null>;
-    getLatestVersionRefForDefinition(runtime: DuckDbQueryRuntime, dataset: DatasetDefinition): Promise<DatasetVersionRef | null>;
+    getLatestVersionRefForDefinition(runtime: DuckDbQueryRuntime, dataset: DatasetDefinition): Promise<DuckLakeTableVersionRef | null>;
     getLatestVersionSummaryForDefinition(runtime: DuckDbQueryRuntime, dataset: DatasetDefinition): Promise<DuckLakeVersionSummary | null>;
+    /**
+     * The latest version a commit builds on, with the lake's snapshot it was read at. Its first
+     * read fixes the snapshot of a transaction it runs in (see `beginTransactionOnLatestVersion`).
+     */
+    getLatestVersionSummaryAtCurrentSnapshot(runtime: DuckDbQueryRuntime, dataset: DatasetDefinition): Promise<LatestVersionAtSnapshot<DuckLakeVersionSummary>>;
+    private getLatestVersionSummaryForTableRef;
     getVersionForSnapshot(runtime: DuckDbQueryRuntime, dataset: DatasetDefinition, snapshotId: string): Promise<DatasetVersion | null>;
     getVersionForTableRef(runtime: DuckDbQueryRuntime, tableRef: DatasetTableRef, snapshotId: string): Promise<DatasetVersion | null>;
-    getVersionRefForSnapshot(runtime: DuckDbQueryRuntime, dataset: DatasetDefinition, snapshotId: string): Promise<DatasetVersionRef | null>;
+    getVersionRefForSnapshot(runtime: DuckDbQueryRuntime, dataset: DatasetDefinition, snapshotId: string): Promise<DuckLakeTableVersionRef | null>;
+    /**
+     * The versions resolved refs point to, with their schemas from one catalog read. Refs resolve
+     * without their parent, so these versions carry no `parentVersionId`.
+     */
+    getVersionsForRefs(runtime: DuckDbQueryRuntime, refs: readonly DuckLakeTableVersionRef[]): Promise<DatasetVersion[]>;
     listVersionsForDefinition(runtime: DuckDbQueryRuntime, dataset: DatasetDefinition, limit?: number): Promise<readonly DatasetVersion[]>;
     private listVersionsForTableRef;
     getLatestVersionForTableRef(runtime: DuckDbQueryRuntime, tableRef: DatasetTableRef): Promise<DatasetVersion | null>;
@@ -67,9 +121,27 @@ export declare class DuckLakeSnapshotReader {
     private getSnapshotRowForTableRef;
     private getSnapshotRowsForTableRef;
     private collectVisibleSnapshotRows;
+    /**
+     * Hydrates, newest first, the snapshots whose changes name one of the dataset's tables: every
+     * snapshot that may hold one of its versions. The text match is a superset;
+     * candidateToSnapshotRow decides visibility.
+     *
+     * The query walks the catalog's snapshot ids downwards, from `beforeSnapshotId` or the head,
+     * and stops at the limit or at the table's creation. A lookup therefore reads the snapshots
+     * between where it starts and the versions it returns: a few for an active dataset, at most the
+     * table's lifetime for one written long ago. It never reads the file tables, whose replaced
+     * files stay until cleanup.
+     */
     private querySnapshotCandidates;
+    /**
+     * Sixb commit metadata of the snapshots that changed a scanned dataset. Each one carries the
+     * lineage of its version, which can be large: scans read it only for the snapshots they keep,
+     * never for the other datasets' snapshots they page past.
+     */
+    private readCommitMetadata;
     private candidateToSnapshotRow;
-    private snapshotToVersion;
+    /** One catalog read for the schemas of every listed version, not one per version. */
+    private snapshotsToVersions;
     private withParentSnapshotIds;
 }
 //# sourceMappingURL=ducklake-snapshot-reader.d.ts.map

package/dist/internal/ducklake-snapshot-reader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ducklake-snapshot-reader.d.ts","sourceRoot":"","sources":["../../src/internal/ducklake-snapshot-reader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ducklake-snapshot-reader.d.ts","sourceRoot":"","sources":["../../src/internal/ducklake-snapshot-reader.ts"],"names":[],"mappings":"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"}

package/dist/internal/ducklake-sql-executor.d.ts

@@ -1,5 +1,5 @@
 import type { DatasetRow } from "@sixb/core";
-import { type DatasetWriteCommitResult, type ExecuteSqlTransformInput, type LakeSqlExecutor, type PreviewSqlTransformInput } from "@sixb/core/lake-storage";
+import { type AnalyzeSqlTransformInput, type DatasetWriteCommitResult, type ExecuteSqlTransformInput, type LakeSqlExecutor, type PreviewSqlTransformInput, type SqlTransformAnalysis } from "@sixb/core/lake-storage";
 import type { DuckLakeStorageOptions } from "../types";
 import type { DuckLakeConnectionManager } from "./ducklake-connection-manager";
 import type { DuckLakeDatasetCatalog } from "./ducklake-dataset-catalog";
@@ -23,9 +23,17 @@ export declare class DuckLakeSqlExecutor implements LakeSqlExecutor<"duckdb"> {
     constructor(options: DuckLakeStorageOptions, connections: DuckLakeConnectionManager, datasets: DuckLakeDatasetCatalog, snapshots: DuckLakeSnapshotReader, writes: DuckLakeWriteCoordinator);
     preview(input: PreviewSqlTransformInput<"duckdb">): AsyncIterable<DatasetRow>;
     execute(input: ExecuteSqlTransformInput<"duckdb">): Promise<DatasetWriteCommitResult>;
+    /**
+     * Column lineage bound against the definitions passed in, without reading the lake: it works
+     * before any source version exists. Their columns are bound in the order given, which can differ
+     * from the lake's stored order; `execute` binds each source's stored version schema instead.
+     */
+    analyze(input: AnalyzeSqlTransformInput<"duckdb">): Promise<SqlTransformAnalysis>;
     private resolveSources;
     private resolveSourceDataset;
     private resolveTargetDataset;
+    /** The source versions read, by source name, with their schemas from one catalog read. */
+    private readSourceVersions;
     private resolveSourceVersion;
     private assertResultSchemaMatchesTarget;
     private applySqlTransform;

package/dist/internal/ducklake-sql-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ducklake-sql-executor.d.ts","sourceRoot":"","sources":["../../src/internal/ducklake-sql-executor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA8C,UAAU,EAAE,MAAM,YAAY,CAAA;AACxF,OAAO,EAEL,KAAK,wBAAwB,EAE7B,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EAEpB,KAAK,wBAAwB,EAC9B,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AAStD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAA;AAC9E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAA;AACxE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAA;AACxE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAA;AAoC5E;;GAEG;AACH,qBAAa,mBAAoB,YAAW,eAAe,CAAC,QAAQ,CAAC;IASjE,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAZzB,QAAQ,CAAC,OAAO,EAAG,QAAQ,CAAS;IACpC,QAAQ,CAAC,YAAY;;;;MAIpB;gBAGkB,OAAO,EAAE,sBAAsB,EAC/B,WAAW,EAAE,yBAAyB,EACtC,QAAQ,EAAE,sBAAsB,EAChC,SAAS,EAAE,sBAAsB,EACjC,MAAM,EAAE,wBAAwB;IAG5C,OAAO,CAAC,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC;IAkB9E,OAAO,CAAC,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,wBAAwB,CAAC;YAmC7E,cAAc;YA2Bd,oBAAoB;YAcpB,oBAAoB;YAepB,oBAAoB;YAuBpB,+BAA+B;YAoD/B,iBAAiB;CAuChC"}
+{"version":3,"file":"ducklake-sql-executor.d.ts","sourceRoot":"","sources":["../../src/internal/ducklake-sql-executor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA8C,UAAU,EAAE,MAAM,YAAY,CAAA;AACxF,OAAO,EACL,KAAK,wBAAwB,EAQ7B,KAAK,wBAAwB,EAE7B,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EAEpB,KAAK,wBAAwB,EAE7B,KAAK,oBAAoB,EAG1B,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AAStD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAA;AAC9E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAA;AACxE,OAAO,KAAK,EAAE,sBAAsB,EAA2B,MAAM,4BAA4B,CAAA;AACjG,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAA;AA+C5E;;GAEG;AACH,qBAAa,mBAAoB,YAAW,eAAe,CAAC,QAAQ,CAAC;IASjE,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAZzB,QAAQ,CAAC,OAAO,EAAG,QAAQ,CAAS;IACpC,QAAQ,CAAC,YAAY;;;;MAIpB;gBAGkB,OAAO,EAAE,sBAAsB,EAC/B,WAAW,EAAE,yBAAyB,EACtC,QAAQ,EAAE,sBAAsB,EAChC,SAAS,EAAE,sBAAsB,EACjC,MAAM,EAAE,wBAAwB;IAG5C,OAAO,CAAC,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC;IAgB9E,OAAO,CAAC,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAoD3F;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,oBAAoB,CAAC;YAczE,cAAc;YAmCd,oBAAoB;YAcpB,oBAAoB;IAelC,0FAA0F;YAC5E,kBAAkB;YAalB,oBAAoB;YAuBpB,+BAA+B;YAoD/B,iBAAiB;CAuChC"}

package/dist/internal/ducklake-version-transaction.d.ts

@@ -0,0 +1,54 @@
+import { LakeConcurrencyError } from "@sixb/core/lake-storage";
+import type { DuckLakeCatalogOptions, DuckLakeStorageOptions } from "../types";
+import type { DuckDbQueryRuntime } from "./duckdb-runtime";
+/**
+ * The catalog moved while a version transaction was being prepared or committed, before anything
+ * was stored. Rerunning the whole transaction from a fresh read of the latest version is safe.
+ */
+export declare class CatalogMovedError extends LakeConcurrencyError {
+}
+/** The latest version of a dataset, and the lake's snapshot it was read at. */
+export interface LatestVersionAtSnapshot<T> {
+    readonly snapshotId: string;
+    readonly latestVersion: T | null;
+}
+export interface BeginVersionTransactionInput<T> {
+    readonly options: DuckLakeStorageOptions;
+    readonly runtime: DuckDbQueryRuntime;
+    readonly datasetId: string;
+    readonly signal?: AbortSignal;
+    /**
+     * Reads the latest version of the dataset, which the transaction then builds on. Its first
+     * statement reads the lake's current snapshot, which fixes the transaction's snapshot.
+     */
+    readonly readLatestVersion: () => Promise<LatestVersionAtSnapshot<T>>;
+}
+/**
+ * Begins the transaction of a new dataset version together with a read of the latest version, so
+ * what the new version derives from its parent, such as its row count or its lineage, describes
+ * the parent it commits on top of, provided every version it must not build on unseen claims its
+ * table (see the write coordinator).
+ */
+export declare function beginTransactionOnLatestVersion<T>(input: BeginVersionTransactionInput<T>): Promise<T | null>;
+export interface CommitOnReadSnapshot {
+    /** Recycles the connection when its DuckLake retry setting cannot be restored. */
+    readonly poisonRuntime: () => void;
+}
+/**
+ * Commits a version transaction. A conflict with a concurrent commit fails before DuckLake stores
+ * anything, and is raised as a `CatalogMovedError` for the transaction to rerun.
+ *
+ * DuckLake commits on top of any snapshot committed since the transaction began that does not
+ * conflict with it. With `onReadSnapshot`, the commit fails on any such snapshot instead, of this
+ * dataset or not: a version that must sit on the version it read, but that inserts and deletes no
+ * rows DuckLake could check, needs it.
+ */
+export declare function commitVersionTransaction(runtime: DuckDbQueryRuntime, datasetId: string, onReadSnapshot?: CommitOnReadSnapshot): Promise<void>;
+/**
+ * Reruns a version transaction that the catalog moved under, before anything was stored. The
+ * rerun reads the latest version again: one guarded on an expected latest version checks its guard
+ * against what moved, and fails as an optimistic commit if this dataset is what moved.
+ */
+export declare function rerunWhenCatalogMoves<T>(datasetId: string, transaction: (attempt: number) => Promise<T>, signal?: AbortSignal): Promise<T>;
+export declare function isSqliteCatalog(catalog: DuckLakeCatalogOptions): boolean;
+//# sourceMappingURL=ducklake-version-transaction.d.ts.map

package/dist/internal/ducklake-version-transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ducklake-version-transaction.d.ts","sourceRoot":"","sources":["../../src/internal/ducklake-version-transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAoB,MAAM,yBAAyB,CAAA;AAChF,OAAO,KAAK,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AAE9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAgB1D;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,oBAAoB;CAAG;AAE9D,+EAA+E;AAC/E,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,aAAa,EAAE,CAAC,GAAG,IAAI,CAAA;CACjC;AAED,MAAM,WAAW,4BAA4B,CAAC,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAA;IACxC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAA;CACtE;AAED;;;;;GAKG;AACH,wBAAsB,+BAA+B,CAAC,CAAC,EACrD,KAAK,EAAE,4BAA4B,CAAC,CAAC,CAAC,GACrC,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CA0BnB;AAED,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,QAAQ,CAAC,aAAa,EAAE,MAAM,IAAI,CAAA;CACnC;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,oBAAoB,GACpC,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC5C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,CAAC,CAAC,CAmBZ;AAoCD,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAKxE"}

package/dist/internal/ducklake-write-coordinator.d.ts

@@ -13,6 +13,8 @@ export interface DuckLakeCommitDatasetVersionInput {
     readonly commitMessage: string;
     readonly producer?: BeginDatasetWriteInput["producer"];
     readonly inputs?: BeginDatasetWriteInput["inputs"];
+    /** The lineage of the rows written, as `BeginDatasetWriteInput.lineage`. */
+    readonly lineage?: BeginDatasetWriteInput["lineage"];
     applyChanges(runtime: DuckDbQueryRuntime, context: DuckLakeApplyChangesContext): Promise<ApplyDatasetRowsResult>;
 }
 export interface DuckLakeApplyChangesContext {
@@ -41,16 +43,41 @@ export declare class DuckLakeWriteCoordinator {
     withCommitRuntime<T>(run: (runtime: DuckDbQueryRuntime) => Promise<T>): Promise<T>;
     commitDatasetVersionOnExclusiveRuntime(runtime: DuckDbQueryRuntime, input: DuckLakeCommitDatasetVersionInput): Promise<DatasetWriteCommitResult>;
     private commitVersionOutcomeOnExclusiveRuntime;
-    private withGuardedRetrySetting;
     private commitDatasetVersionUnlocked;
     private versionForCommittedWrite;
     private applyStagedRows;
     private setCommitMetadata;
-    private ensureNoOpHasSnapshot;
+    /**
+     * Claims the table for the version this transaction commits by reapplying its current comment:
+     * an idempotent metadata write, which DuckLake records as altering the table. A transaction
+     * that changes a table another one altered since it began then fails to commit, before storing
+     * anything, and reruns on the new latest version (see `mustClaimTable`).
+     *
+     * It also gives a version that changes no rows, an initial empty write or a change of
+     * provenance, a DuckLake snapshot: DuckLake 1.5.2 creates none for a transaction whose data and
+     * metadata are unchanged, and set_commit_message alone cannot force one.
+     *
+     * Altering a table bumps DuckLake's catalog-wide schema version: every connection reloads its
+     * catalog, and concurrent writers to other tables slow down. Versions claim only when needed.
+     */
+    private claimTable;
+    /** A commit that changes no rows still creates a version for a first version or new provenance. */
+    private noOpCreatesVersion;
+    /**
+     * The latest version a write that began without reading it compared its rows with: the one at
+     * the lake snapshot its first read fixed. The version metadata also shows versions committed
+     * since. One of this dataset means the rows were compared with an older version, so the write
+     * reruns.
+     */
+    private latestVersionAtReadSnapshot;
     private versionForNoOpCommit;
     private rollbackTransaction;
+    /**
+     * Every version but a snapshot keeps its parent's rows, and the lineage it records merges the
+     * parent's. A snapshot replaces its parent: it reads it only to guard on it, or on SQLite, whose
+     * later reads inside the transaction would block its commit.
+     */
     private beginVersionTransaction;
-    private currentSnapshotId;
     private lastCommittedSnapshotId;
     private findSnapshotIdByCommitId;
     private findOwnSnapshotId;

package/dist/internal/ducklake-write-coordinator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ducklake-write-coordinator.d.ts","sourceRoot":"","sources":["../../src/internal/ducklake-write-coordinator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EAGtB,wBAAwB,EACxB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,yBAAyB,CAAA;AAShC,OAAO,KAAK,EAA0B,sBAAsB,EAAE,MAAM,UAAU,CAAA;AAE9E,OAAO,EACL,KAAK,sBAAsB,EAI5B,MAAM,sBAAsB,CAAA;AAG7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAA;AAC9E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAA;AAExE,OAAO,KAAK,EAAE,sBAAsB,EAA0B,MAAM,4BAA4B,CAAA;AAYhG,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;IACnC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;IAC/B,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAChD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,CAAC,UAAU,CAAC,CAAA;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC,QAAQ,CAAC,CAAA;IAClD,YAAY,CACV,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,sBAAsB,CAAC,CAAA;CACnC;AAgBD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,0BAA0B,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACxD;AAED;;;;;;;GAOG;AACH,qBAAa,wBAAwB;IAEjC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAHT,OAAO,EAAE,sBAAsB,EAC/B,WAAW,EAAE,yBAAyB,EACtC,QAAQ,EAAE,sBAAsB,EAChC,SAAS,EAAE,sBAAsB;IAG9C,UAAU,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA6BpE,UAAU,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAkC5D,WAAW;YAyBX,WAAW;IAoDnB,oBAAoB,CACxB,KAAK,EAAE,iCAAiC,GACvC,OAAO,CAAC,wBAAwB,CAAC;IAM9B,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAQlF,sCAAsC,CAC1C,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,iCAAiC,GACvC,OAAO,CAAC,wBAAwB,CAAC;YAkBtB,sCAAsC;YAUtC,uBAAuB;YA2CvB,4BAA4B;YA6E5B,wBAAwB;YAiExB,eAAe;YAyBf,iBAAiB;YAkCjB,qBAAqB;YA+BrB,oBAAoB;YAmBpB,mBAAmB;YASnB,uBAAuB;YAmCvB,iBAAiB;YAUjB,uBAAuB;YAYvB,wBAAwB;YAiCxB,iBAAiB;IA0B/B,OAAO,CAAC,2BAA2B;CAgBpC"}
+{"version":3,"file":"ducklake-write-coordinator.d.ts","sourceRoot":"","sources":["../../src/internal/ducklake-write-coordinator.ts"],"names":[],"mappings":"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"}

package/dist/internal/lineage-encoding.d.ts

@@ -0,0 +1,8 @@
+import type { DatasetVersionLineage } from "@sixb/core/lake-storage";
+export declare function encodeLineage(lineage: DatasetVersionLineage): string;
+/**
+ * The stored lineage, as stored. One Sixb cannot read is unknown, as Sixb reads a malformed
+ * lineage: dropping it instead would classify a version outside pipelines by its own columns only.
+ */
+export declare function decodeLineage(datasetId: string, stored: unknown): DatasetVersionLineage;
+//# sourceMappingURL=lineage-encoding.d.ts.map

package/dist/internal/lineage-encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineage-encoding.d.ts","sourceRoot":"","sources":["../../src/internal/lineage-encoding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,qBAAqB,EACtB,MAAM,yBAAyB,CAAA;AAqBhC,wBAAgB,aAAa,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,CA8BpE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,qBAAqB,CAOvF"}

package/dist/internal/sql-lineage/analysis.d.ts

@@ -0,0 +1,32 @@
+import type { AnalyzeSqlTransformSource, SqlTransformLineage } from "@sixb/core/lake-storage";
+import { type DuckLakeSqlTransformTemplate } from "../sql-transform-relations";
+interface AnalyzeSqlTransformLineageInput {
+    readonly sources: Readonly<Record<string, AnalyzeSqlTransformSource>>;
+    readonly template: DuckLakeSqlTransformTemplate;
+}
+/**
+ * `SqlTransformAnalysis` with the result's column names in order, which the lineage record cannot
+ * carry: object keys that look like integers enumerate first.
+ */
+export type SqlLineageAnalysis = {
+    readonly supported: true;
+    readonly lineage: SqlTransformLineage;
+    readonly outputColumns: readonly string[];
+} | {
+    readonly supported: false;
+    readonly reason: string;
+    readonly readsOnlySources: boolean;
+};
+/**
+ * Column lineage of a SQL transform, derived without reading any data.
+ *
+ * A fresh in-memory DuckDB instance creates one empty table per source from its column schema,
+ * the transform renders against those tables in the same relation shape it runs with on the lake,
+ * and DuckDB binds it. The bound, unoptimized plan is then walked operator by operator. Whatever
+ * the walker does not understand exactly is rejected rather than guessed; a rejection or a bind
+ * error is an unsupported analysis, while an invalid source pick throws. An unsupported analysis
+ * of SQL that parsed still says whether its parse tree reads anything but the sources.
+ */
+export declare function analyzeSqlTransformLineage(input: AnalyzeSqlTransformLineageInput): Promise<SqlLineageAnalysis>;
+export {};
+//# sourceMappingURL=analysis.d.ts.map

package/dist/internal/sql-lineage/analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis.d.ts","sourceRoot":"","sources":["../../../src/internal/sql-lineage/analysis.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,yBAAyB,EAEzB,mBAAmB,EACpB,MAAM,yBAAyB,CAAA;AAGhC,OAAO,EACL,KAAK,4BAA4B,EAGlC,MAAM,4BAA4B,CAAA;AAMnC,UAAU,+BAA+B;IACvC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC,CAAA;IACrE,QAAQ,CAAC,QAAQ,EAAE,4BAA4B,CAAA;CAChD;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IACE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAA;IACrC,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1C,GACD;IAAE,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;CAAE,CAAA;AAyB9F;;;;;;;;;GASG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,+BAA+B,GACrC,OAAO,CAAC,kBAAkB,CAAC,CA6B7B"}

package/dist/internal/sql-lineage/expressions.d.ts

@@ -0,0 +1,9 @@
+import { type JsonObject } from "./plan-json";
+import { type PlanColumn } from "./plan-relation";
+/** Source columns whose values flow into an expression evaluated over an operator's `input`. */
+export declare function expressionDependencies(expression: unknown, input: readonly PlanColumn[]): Set<number>;
+/** The sort expressions of an ORDER BY list (`{ type, null_order, expression }` entries). */
+export declare function orderExpressions(orders: readonly unknown[]): readonly unknown[];
+/** `{ orders: [...] }` or null, as aggregates and DISTINCT ON write their ORDER BY. */
+export declare function nestedOrderExpressions(object: JsonObject, key: string): readonly unknown[];
+//# sourceMappingURL=expressions.d.ts.map

package/dist/internal/sql-lineage/expressions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expressions.d.ts","sourceRoot":"","sources":["../../../src/internal/sql-lineage/expressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,UAAU,EAMhB,MAAM,aAAa,CAAA;AACpB,OAAO,EAA8B,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAG7E,gGAAgG;AAChG,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,OAAO,EACnB,KAAK,EAAE,SAAS,UAAU,EAAE,GAC3B,GAAG,CAAC,MAAM,CAAC,CAIb;AAED,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,OAAO,EAAE,CAE/E;AAED,uFAAuF;AACvF,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE,CAG1F"}

package/dist/internal/sql-lineage/plan-json.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Strict readers for DuckDB's JSON serializers (`json_serialize_sql`, `json_serialize_plan`).
+ *
+ * The format is not a stable DuckDB API. Every field the analysis reads must be present with the
+ * expected shape, so a renamed or retyped field in a future release rejects the transform instead
+ * of silently dropping a dependency.
+ */
+export type JsonObject = Readonly<Record<string, unknown>>;
+export declare function isJsonObject(value: unknown): value is JsonObject;
+export declare function asObject(value: unknown, what: string): JsonObject;
+/** A field the serializer always writes. It may be null. */
+export declare function field(object: JsonObject, key: string): unknown;
+export declare function objectField(object: JsonObject, key: string): JsonObject;
+export declare function nullableObjectField(object: JsonObject, key: string): JsonObject | null;
+export declare function stringField(object: JsonObject, key: string): string;
+export declare function booleanField(object: JsonObject, key: string): boolean;
+/**
+ * Indexes and table indexes. DuckDB writes 2^64-1 as an "unset" sentinel, which `JSON.parse`
+ * rounds; it stays an integer far past any column count, which is all the analysis compares.
+ */
+export declare function indexField(object: JsonObject, key: string): number;
+/** A list field. The serializer writes an absent list as null or as an empty array. */
+export declare function listField(object: JsonObject, key: string): readonly unknown[];
+export declare function asList(value: unknown, what: string): readonly unknown[];
+export declare function objectListField(object: JsonObject, key: string): readonly JsonObject[];
+export declare function indexListField(object: JsonObject, key: string): readonly number[];
+export declare function asIndexList(value: unknown, what: string): readonly number[];
+export declare function stringListField(object: JsonObject, key: string): readonly string[];
+/**
+ * Both serializers answer `{ "error": false, <listKey>: [...] }`, or `{ "error": true,
+ * "error_message": ... }` when DuckDB could not parse or bind the query.
+ */
+export declare function parseSerializerOutput(text: string, listKey: string, failure: string): readonly unknown[];
+//# sourceMappingURL=plan-json.d.ts.map

package/dist/internal/sql-lineage/plan-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-json.d.ts","sourceRoot":"","sources":["../../../src/internal/sql-lineage/plan-json.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAE1D,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CAMjE;AAED,4DAA4D;AAC5D,wBAAgB,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAM9D;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAEvE;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAGtF;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAOnE;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAOrE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAElE;AAUD,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE,CAE7E;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE,CAUvE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,UAAU,EAAE,CAEtF;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAEjF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAE3E;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAQlF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,SAAS,OAAO,EAAE,CAOpB"}

package/dist/internal/sql-lineage/plan-relation.d.ts

@@ -0,0 +1,28 @@
+/** Source columns, as ids assigned by the analysis session, that something depends on. */
+export type Dependencies = ReadonlySet<number>;
+/**
+ * A planner-internal column past the end of a table's columns: `rowid`, or the placeholder a
+ * `count(*)` scan reads. Scanning one is allowed; depending on one rejects the transform.
+ */
+export declare const VIRTUAL_COLUMN = -1;
+/** A column flowing out of a plan operator. */
+export interface PlanColumn {
+    readonly dependencies: Dependencies;
+    /**
+     * `table_index.column_index` in the plan. Most expressions reference their input by position
+     * (BOUND_REF); the subtree under a table function's input keeps binding references instead.
+     */
+    readonly binding?: string;
+}
+/** The output of a plan operator: its columns, and what decides which rows exist and their order. */
+export interface PlanRelation {
+    readonly columns: readonly PlanColumn[];
+    readonly rows: Dependencies;
+}
+export declare function bindingKey(tableIndex: number, columnIndex: number): string;
+/** Positional access into an operator's columns or index lists. */
+export declare function itemAt<T>(items: readonly T[], index: number, what: string): T;
+export declare function unionOf(...sets: readonly Dependencies[]): Set<number>;
+export declare function addAll(target: Set<number>, source: Iterable<number>): void;
+export declare function sameDependencies(left: Dependencies, right: Dependencies): boolean;
+//# sourceMappingURL=plan-relation.d.ts.map