@sixb/ducklake 0.1.8 → 0.2.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"plan-relation.d.ts","sourceRoot":"","sources":["../../../src/internal/sql-lineage/plan-relation.ts"],"names":[],"mappings":"AAEA,0FAA0F;AAC1F,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,CAAC,CAAA;AAE9C;;;GAGG;AACH,eAAO,MAAM,cAAc,KAAK,CAAA;AAEhC,+CAA+C;AAC/C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;IACnC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,qGAAqG;AACrG,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAA;IACvC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAC5B;AAED,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED,mEAAmE;AACnE,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAO7E;AAED,wBAAgB,OAAO,CAAC,GAAG,IAAI,EAAE,SAAS,YAAY,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAOrE;AAED,wBAAgB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,CAI1E;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAEjF"}

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

@@ -0,0 +1,18 @@
+/** The tables a plan may scan: physical table name, then column name, to a source column id. */
+export type PlanSourceTables = ReadonlyMap<string, ReadonlyMap<string, number>>;
+/** Source column ids, sorted, for the whole result and for each output column by position. */
+export interface PlanLineage {
+    readonly rows: readonly number[];
+    readonly columns: readonly (readonly number[])[];
+}
+/**
+ * Column lineage of one bound, unoptimized logical plan (`json_serialize_plan(sql, optimize :=
+ * false)`), walked bottom-up. Each operator yields its output columns with the source columns their
+ * values come from, plus the source columns that decide which rows exist or their order. Those row
+ * dependencies accumulate upwards and apply to every output column.
+ *
+ * Expressions mostly reference their operator's input by position, so each operator below states
+ * the order of its output columns.
+ */
+export declare function planLineage(plan: unknown, tables: PlanSourceTables): PlanLineage;
+//# sourceMappingURL=plan-walker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plan-walker.d.ts","sourceRoot":"","sources":["../../../src/internal/sql-lineage/plan-walker.ts"],"names":[],"mappings":"AA8BA,gGAAgG;AAChG,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AAE/E,8FAA8F;AAC9F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAA;CACjD;AAaD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,GAAG,WAAW,CAUhF"}

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

@@ -0,0 +1,11 @@
+/**
+ * A transform whose lineage cannot be derived exactly. The message names the construct and becomes
+ * the `reason` of an unsupported analysis; it never escapes the analysis as an error.
+ */
+export declare class SqlLineageRejected extends Error {
+    readonly name = "SqlLineageRejected";
+}
+export declare function reject(reason: string): never;
+/** DuckDB serialized something the analysis does not recognize, most likely after an upgrade. */
+export declare function rejectPlanFormat(detail: string): never;
+//# sourceMappingURL=rejection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rejection.d.ts","sourceRoot":"","sources":["../../../src/internal/sql-lineage/rejection.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAkB,IAAI,wBAAuB;CAC9C;AAED,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAE5C;AAED,iGAAiG;AACjG,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAEtD"}

package/dist/internal/sql-lineage/statement-gate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Checks the parse tree (`json_serialize_sql`) before DuckDB binds the query. Binding already runs
+ * table functions' bind code, and table macros such as `query()` only expand during binding, so
+ * they must be refused from the parse tree. PIVOT is refused here because its output columns depend
+ * on data the empty analysis tables do not have.
+ */
+export declare function assertSingleSelect(statements: readonly unknown[]): void;
+/**
+ * Whether the statement reads nothing but its sources, for a transform the analysis rejected: then
+ * every column it outputs depends on at most every column of its sources. PIVOT reads only its
+ * input.
+ *
+ * Data reaches a query through its table references. Each must be one of `sourceTables`, or a
+ * common table expression an enclosing query defines; a table function must compute from its
+ * arguments alone. A name a query does not define resolves to a table of the lake.
+ *
+ * A function must carry a name DuckDB itself defines, one of `builtinFunctions`: a macro the
+ * lake's setup defines can read any table, and its call shows none.
+ */
+export declare function readsOnlySources(statements: readonly unknown[], sourceTables: ReadonlySet<string>, builtinFunctions: ReadonlySet<string>): boolean;
+//# sourceMappingURL=statement-gate.d.ts.map

package/dist/internal/sql-lineage/statement-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statement-gate.d.ts","sourceRoot":"","sources":["../../../src/internal/sql-lineage/statement-gate.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAevE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,SAAS,OAAO,EAAE,EAC9B,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,EACjC,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,GACpC,OAAO,CAYT"}

package/dist/internal/sql-lineage/table-functions.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Table functions that compute only from their arguments. Every other table function reads outside
+ * the transform's sources (files, catalogs, settings) or runs SQL of its own, like `query()`.
+ */
+export declare const PURE_TABLE_FUNCTIONS: ReadonlySet<string>;
+//# sourceMappingURL=table-functions.d.ts.map

package/dist/internal/sql-lineage/table-functions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-functions.d.ts","sourceRoot":"","sources":["../../../src/internal/sql-lineage/table-functions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAMnD,CAAA"}

package/dist/internal/sql-transform-relations.d.ts

@@ -1,13 +1,28 @@
+import type { DatasetColumnDefinition, DatasetDefinition } from "@sixb/core";
 import { type SqlTransformBody } from "@sixb/core/lake-storage";
 import type { DuckLakeStorageOptions } from "../types";
 export interface DuckLakeSqlTransformSourceRelation {
     readonly datasetId: string;
     readonly versionId: string;
+    /** The only columns the transform may read, in order. Every column when omitted. */
+    readonly columns?: readonly string[];
 }
-export interface RenderDuckLakeSqlTransformSqlInput {
-    readonly options: Pick<DuckLakeStorageOptions, "alias">;
-    readonly sources: Readonly<Record<string, DuckLakeSqlTransformSourceRelation>>;
-    readonly sql: SqlTransformBody<"duckdb">;
+/**
+ * The SQL a transform body returned, with a placeholder where each source relation belongs. The
+ * body runs once; the same SQL then renders against the lake and against the lineage analysis.
+ */
+export interface DuckLakeSqlTransformTemplate {
+    /** Replaces each placeholder with its source's relation SQL, keyed by source name. */
+    render(relations: ReadonlyMap<string, string>): string;
 }
-export declare function renderDuckLakeSqlTransformSql(input: RenderDuckLakeSqlTransformSqlInput): string;
+export declare function createDuckLakeSqlTransformTemplate(sourceNames: readonly string[], body: SqlTransformBody<"duckdb">): DuckLakeSqlTransformTemplate;
+/** Each source as DuckLake time travel to its resolved version. */
+export declare function renderDuckLakeSourceRelations(options: Pick<DuckLakeStorageOptions, "alias">, sources: Readonly<Record<string, DuckLakeSqlTransformSourceRelation>>): ReadonlyMap<string, string>;
+/**
+ * The shape of every source relation. A pick lists its columns, so the transform cannot read any
+ * other column of the source.
+ */
+export declare function renderSourceRelation(tableSql: string, columns?: readonly string[]): string;
+/** The columns a source exposes to a transform: its pick, in order, or every column. */
+export declare function pickSourceColumns(sourceName: string, dataset: DatasetDefinition, columns?: readonly string[]): readonly DatasetColumnDefinition[];
 //# sourceMappingURL=sql-transform-relations.d.ts.map

package/dist/internal/sql-transform-relations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sql-transform-relations.d.ts","sourceRoot":"","sources":["../../src/internal/sql-transform-relations.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,gBAAgB,EAEtB,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AAQtD,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,sBAAsB,EAAE,OAAO,CAAC,CAAA;IACvD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kCAAkC,CAAC,CAAC,CAAA;IAC9E,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAA;CACzC;AAeD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,kCAAkC,GAAG,MAAM,CAS/F"}
+{"version":3,"file":"sql-transform-relations.d.ts","sourceRoot":"","sources":["../../src/internal/sql-transform-relations.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC5E,OAAO,EAEL,KAAK,gBAAgB,EAEtB,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AAQtD,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,4BAA4B;IAC3C,sFAAsF;IACtF,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAA;CACvD;AAUD,wBAAgB,kCAAkC,CAChD,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,IAAI,EAAE,gBAAgB,CAAC,QAAQ,CAAC,GAC/B,4BAA4B,CAmC9B;AAED,mEAAmE;AACnE,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,IAAI,CAAC,sBAAsB,EAAE,OAAO,CAAC,EAC9C,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kCAAkC,CAAC,CAAC,GACpE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAW7B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAI1F;AAED,wFAAwF;AACxF,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAC1B,SAAS,uBAAuB,EAAE,CA+BpC"}

package/dist/internal/versions.d.ts

@@ -12,11 +12,20 @@ export interface SixbCommitMetadata {
     readonly rowCount?: number;
     readonly validatedPrimaryKeyColumns?: readonly string[];
     readonly schemaChange?: SixbSchemaChangeMetadata;
+    /** As `encodeLineage` stored it: decoded only for the versions a read returns. */
+    readonly lineage?: unknown;
 }
 export declare function parseVersionId(versionId: string): string;
 export declare function toVersionId(snapshotId: string): string;
 export declare function parseCommitMetadata(value: unknown): SixbCommitMetadata | undefined;
-export declare function parseInlineDataChange(changesMade: string, tableId: bigint): {
+/** Whether a DuckLake snapshot's `changes_made` names one of the tables, for any change. */
+export declare function changesTouchTables(changesMade: string, tableIds: readonly bigint[]): boolean;
+/**
+ * Whether a DuckLake snapshot changed a table's rows, and whether it removed any. DuckLake records
+ * every row change in `changes_made`, for inlined rows (`inlined_insert:<id>`) as for files
+ * (`inserted_into_table:<id>`, `deleted_from_table:<id>`); altering a table changes none.
+ */
+export declare function parseTableDataChange(changesMade: string, tableId: bigint): {
     readonly hasDataChange: boolean;
     readonly hasDeleteChange: boolean;
 };

package/dist/internal/versions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../../src/internal/versions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAG7D,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACxC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAA;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAA;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAA;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,0BAA0B,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACvD,QAAQ,CAAC,YAAY,CAAC,EAAE,wBAAwB,CAAA;CACjD;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAWxD;AAED,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,GAAG,SAAS,CA2ClF;AAED,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd;IAAE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;CAAE,CAsBxE"}
+{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../../src/internal/versions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAG9E,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACxC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAA;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAA;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAA;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,0BAA0B,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACvD,QAAQ,CAAC,YAAY,CAAC,EAAE,wBAAwB,CAAA;IAChD,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAWxD;AAED,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,GAAG,SAAS,CA6ClF;AAED,4FAA4F;AAC5F,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAG5F;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd;IAAE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;CAAE,CAsBxE"}

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { DatasetVersionRef } from "@sixb/core/lake-storage";
 /**
  * DuckLake catalog connection settings.
  *
@@ -107,18 +108,26 @@ export interface AzureSecretOptions extends BaseSecretOptions {
 }
 export type DuckDbSecretOptions = S3SecretOptions | R2SecretOptions | GcsSecretOptions | AzureSecretOptions;
 export interface DuckLakeMaintenanceOptions {
-    /** How long to keep snapshots before they can expire. Default: "7 days". */
+    /**
+     * How long to keep snapshots before they can expire. Default: "7 days". Each dataset's latest
+     * version and the `protect` versions are kept whatever their age.
+     */
     readonly expireOlderThan?: string;
     /** How long to keep deleted/orphaned files before reclaim. Default: expireOlderThan. */
     readonly deleteOlderThan?: string;
     /** Report what would be expired/deleted without changing the lake. Default: false. */
     readonly dryRun?: boolean;
+    /** Versions to keep whatever their age, such as those projections applied. */
+    readonly protect?: readonly DatasetVersionRef[];
 }
 export interface DuckLakeMaintenanceReport {
     readonly dryRun: boolean;
     readonly expireOlderThan: string;
     readonly deleteOlderThan: string;
+    /** Snapshots expired, or that would expire on a dry run. */
     readonly snapshots: number;
+    /** Snapshots older than `expireOlderThan` kept because a version they hold is still needed. */
+    readonly keptSnapshots: number;
     readonly oldFiles: number;
     readonly orphanedFiles: number;
 }

package/dist/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sixb/ducklake",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "DuckDB/DuckLake lake storage provider for Sixb",
   "keywords": [
     "sixb",
@@ -36,18 +36,18 @@
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "test:e2e": "bun run test:e2e:local && bun run test:e2e:remote",
-    "test:e2e:local": "bun test ./tests/ducklake-reader.e2e.ts ./tests/ducklake-changes.e2e.ts ./tests/ducklake-contract.e2e.ts ./tests/ducklake-file-refs.e2e.ts ./tests/ducklake-catalog-state.e2e.ts ./tests/ducklake-catalogs.e2e.ts ./tests/ducklake-concurrency.e2e.ts ./tests/ducklake-datasets.e2e.ts ./tests/ducklake-driver.e2e.ts ./tests/ducklake-maintenance.e2e.ts ./tests/ducklake-merges.e2e.ts ./tests/ducklake-sql-transforms.e2e.ts ./tests/ducklake-versions.e2e.ts ./tests/ducklake-long-history.e2e.ts ./tests/ducklake-writes.e2e.ts ./tests/ducklake-sqlite-writes.e2e.ts",
-    "test:e2e:remote": "bun test --preload ./tests/setup.ts ./tests/ducklake-remote.e2e.ts",
+    "test:e2e:local": "bun test --preload ./tests/extensions.ts ./tests/ducklake-reader.e2e.ts ./tests/ducklake-changes.e2e.ts ./tests/ducklake-contract.e2e.ts ./tests/ducklake-catalog-state.e2e.ts ./tests/ducklake-catalogs.e2e.ts ./tests/ducklake-concurrency.e2e.ts ./tests/ducklake-datasets.e2e.ts ./tests/ducklake-driver.e2e.ts ./tests/ducklake-maintenance.e2e.ts ./tests/ducklake-merges.e2e.ts ./tests/ducklake-sql-transforms.e2e.ts ./tests/ducklake-versions.e2e.ts ./tests/ducklake-long-history.e2e.ts ./tests/ducklake-writes.e2e.ts ./tests/ducklake-sqlite-writes.e2e.ts",
+    "test:e2e:remote": "bun test --preload ./tests/extensions.ts --preload ./tests/setup.ts ./tests/ducklake-remote.e2e.ts",
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@duckdb/node-api": "^1.5.2-r.1"
+    "@duckdb/node-api": "1.5.2-r.2"
   },
   "peerDependencies": {
-    "@sixb/core": "^0.1.17"
+    "@sixb/core": "^0.2.0"
   },
   "devDependencies": {
-    "@sixb/core": "0.1.17",
+    "@sixb/core": "0.2.0",
     "@types/bun": "latest",
     "typescript": "^5.7.0"
   },

package/src/ducklake-storage.ts

@@ -35,6 +35,7 @@ import type {
  */
 export class DuckLakeStorage implements LakeStorageWithSql<"duckdb"> {
   readonly standard = { id: "ducklake", version: "1.0" } as const
+  readonly recordsLineage = true
   readonly sql: DuckLakeSqlExecutor
 
   private readonly connections: DuckLakeConnectionManager
@@ -58,12 +59,16 @@ export class DuckLakeStorage implements LakeStorageWithSql<"duckdb"> {
     }
     this.connections = new DuckLakeConnectionManager(normalizedOptions)
     this.datasets = new DuckLakeDatasetCatalog(normalizedOptions, this.connections)
-    this.maintenance = new DuckLakeMaintenance(normalizedOptions, this.connections)
     this.snapshotReader = new DuckLakeSnapshotReader(
       normalizedOptions,
       this.connections,
       this.datasets
     )
+    this.maintenance = new DuckLakeMaintenance(
+      normalizedOptions,
+      this.connections,
+      this.snapshotReader
+    )
     this.rows = new DuckLakeRowReader(normalizedOptions, this.connections, this.snapshotReader)
     this.changes = new DuckLakeChangeReader(
       normalizedOptions,
@@ -86,7 +91,9 @@ export class DuckLakeStorage implements LakeStorageWithSql<"duckdb"> {
   }
 
   async createDataset(definition: DatasetDefinition): Promise<DatasetDefinition> {
-    return this.datasets.createDataset(definition)
+    return this.datasets.createDataset(definition, (runtime, dataset) =>
+      this.snapshotReader.getLatestVersionSummaryAtCurrentSnapshot(runtime, dataset)
+    )
   }
 
   async assertDatasetDefinitionsCompatible(

package/src/internal/dataset-row-commit.ts

@@ -19,6 +19,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 function assertDatasetWriteMode(
@@ -46,6 +56,7 @@ export async function applyDatasetRowsFromRelation(input: {
   const columnsSql = datasetSchemaColumnNamesSql(input.dataset.schema)
   const primaryKeyColumns = getDatasetPrimaryKeyColumns(input.dataset)
 
+  let baselineRowCount: number | undefined
   if (primaryKeyColumns !== null) {
     await inspectUniqueKeyedRelation({
       runtime: input.runtime,
@@ -55,7 +66,7 @@ export async function applyDatasetRowsFromRelation(input: {
     })
 
     if (input.mode === "append") {
-      await inspectUniqueKeyedRelation({
+      baselineRowCount = await inspectUniqueKeyedRelation({
         runtime: input.runtime,
         dataset: input.dataset,
         relationSql: table,
@@ -80,6 +91,8 @@ export async function applyDatasetRowsFromRelation(input: {
         dataChangeExpected: false,
         sourceRowCount: source.rowCount,
         resultingRowCount: { kind: "exact", value: target.rowCount },
+        targetWasEmpty: target.rowCount === 0,
+        changedTableRows: false,
       }
     }
 
@@ -88,20 +101,28 @@ export async function applyDatasetRowsFromRelation(input: {
       `INSERT INTO ${table} (${columnsSql}) SELECT ${columnsSql} FROM ${input.sourceRelationSql}`
     )
 
+    const changedTableRows = source.rowCount > 0 || target.rowCount > 0
     return {
-      dataChangeExpected: source.rowCount > 0 || target.rowCount > 0,
+      dataChangeExpected: changedTableRows,
       sourceRowCount: source.rowCount,
       resultingRowCount: { kind: "exact", value: source.rowCount },
+      targetWasEmpty: target.rowCount === 0,
+      changedTableRows,
     }
   }
 
   const sourceRowCount = await countRows(input.runtime, input.sourceRelationSql)
+  const knownRowCount = baselineRowCount ?? input.previousRowCount
+  const targetWasEmpty =
+    knownRowCount === undefined ? await isEmptyRelation(input.runtime, table) : knownRowCount === 0
   await input.runtime.run(
     `INSERT INTO ${table} (${columnsSql}) SELECT ${columnsSql} FROM ${input.sourceRelationSql}`
   )
 
   return {
     dataChangeExpected: sourceRowCount > 0,
+    targetWasEmpty,
+    changedTableRows: sourceRowCount > 0,
     sourceRowCount,
     resultingRowCount:
       input.previousRowCount === undefined
@@ -219,3 +240,8 @@ async function countRows(runtime: DuckDbQueryRuntime, relationSql: string): Prom
 
   return Number(getBigIntLike(row, "row_count"))
 }
+
+async function isEmptyRelation(runtime: DuckDbQueryRuntime, relationSql: string): Promise<boolean> {
+  const rows = await runtime.query(`SELECT 1 AS present FROM ${relationSql} LIMIT 1`)
+  return rows.length === 0
+}

package/src/internal/dataset-row-merge.ts

@@ -58,6 +58,8 @@ export async function applyDatasetMergeFromRelation(
           dataChangeExpected: orderingChanged,
           sourceRowCount,
           resultingRowCount: { kind: "exact", value: previousRowCount },
+          targetWasEmpty: previousRowCount === 0,
+          changedTableRows: false,
         }
       }
 
@@ -103,6 +105,8 @@ export async function applyDatasetMergeFromRelation(
           kind: "exact",
           value: previousRowCount + effects.inserts - effects.deletes,
         },
+        targetWasEmpty: previousRowCount === 0,
+        changedTableRows: true,
       }
     }
   )