@sixb/ducklake 0.1.4 → 0.1.6

package/dist/index.js

@@ -1,52 +1,145 @@
 // @bun
-// src/internal/ducklake-connection-manager.ts
-import { LakeStorageError as LakeStorageError4 } from "@sixb/core/lake-storage";
+// src/internal/ducklake-change-reader.ts
+import { randomUUID } from "crypto";
+import {
+  LakeStorageError as LakeStorageError7,
+  resolveDatasetChangeColumns
+} from "@sixb/core/lake-storage";
 
-// src/internal/catalog-key.ts
-import { resolve } from "path";
-function localCatalogCoordinationKey(options) {
-  switch (options.catalog.type) {
-    case "duckdb":
-    case "sqlite":
-      if (options.catalog.path === ":memory:") {
-        return;
-      }
-      return `${options.catalog.type}:${resolve(options.catalog.path)}`;
-    case "custom":
-      return `custom:${options.catalog.uri}`;
-    case "postgres":
-      return;
+// src/internal/duckdb-row.ts
+import { LakeStorageError } from "@sixb/core/lake-storage";
+function getString(row, key) {
+  const value = row[key];
+  if (typeof value !== "string") {
+    throw new LakeStorageError(`[SixbDuckLake] Expected DuckDB column '${key}' to be a string, got ${typeof value}.`);
   }
+  return value;
+}
+function getOptionalString(row, key) {
+  const value = row[key];
+  if (value === null || value === undefined) {
+    return;
+  }
+  if (typeof value !== "string") {
+    throw new LakeStorageError(`[SixbDuckLake] Expected DuckDB column '${key}' to be a string, got ${typeof value}.`);
+  }
+  return value;
+}
+function getBoolean(row, key) {
+  const value = row[key];
+  if (typeof value !== "boolean") {
+    throw new LakeStorageError(`[SixbDuckLake] Expected DuckDB column '${key}' to be a boolean, got ${typeof value}.`);
+  }
+  return value;
+}
+function getBigIntLike(row, key) {
+  const value = row[key];
+  if (typeof value === "bigint") {
+    return value;
+  }
+  if (typeof value === "number" && Number.isInteger(value)) {
+    return BigInt(value);
+  }
+  if (typeof value === "string" && /^-?\d+$/.test(value)) {
+    return BigInt(value);
+  }
+  throw new LakeStorageError(`[SixbDuckLake] Expected DuckDB column '${key}' to be an integer, got ${typeof value}.`);
+}
+function getOptionalBigIntLike(row, key) {
+  const value = row[key];
+  if (value === null || value === undefined) {
+    return;
+  }
+  return getBigIntLike(row, key);
+}
+function getDate(row, key) {
+  const value = row[key];
+  if (value instanceof Date) {
+    return value;
+  }
+  if (typeof value === "string") {
+    return new Date(value);
+  }
+  throw new LakeStorageError(`[SixbDuckLake] Expected DuckDB column '${key}' to be a date, got ${typeof value}.`);
 }
 
-// src/internal/duckdb-runtime.ts
-import {
-  DuckDBInstance
-} from "@duckdb/node-api";
-import { LakeStorageError as LakeStorageError3 } from "@sixb/core/lake-storage";
-
-// src/internal/duckdb-value-converter.ts
-import {
-  DuckDBDecimalValue,
-  DuckDBTypeId,
-  JSDuckDBValueConverter
-} from "@duckdb/node-api";
-import { LakeStorageError } from "@sixb/core/lake-storage";
-var sixbDuckDbValueConverter = (value, type, converter) => {
-  if (value === null) {
+// src/internal/names.ts
+import { LakeStorageError as LakeStorageError2 } from "@sixb/core/lake-storage";
+var DATASET_TABLE_PREFIX = "sixb__ds__";
+var textEncoder = new TextEncoder;
+var textDecoder = new TextDecoder("utf-8", { fatal: true });
+function isInlineByte(byte) {
+  return byte >= 97 && byte <= 122 || byte >= 48 && byte <= 57;
+}
+function isHexPair(value) {
+  return /^[0-9a-f]{2}$/.test(value);
+}
+function encodeDatasetId(datasetId) {
+  if (datasetId.trim().length === 0) {
+    throw new LakeStorageError2("[SixbDuckLake] Dataset id must not be empty.");
+  }
+  let encoded = "";
+  for (const byte of textEncoder.encode(datasetId)) {
+    if (isInlineByte(byte)) {
+      encoded += String.fromCharCode(byte);
+    } else if (byte === 46) {
+      encoded += "__";
+    } else {
+      encoded += `_${byte.toString(16).padStart(2, "0")}`;
+    }
+  }
+  return encoded;
+}
+function decodeDatasetId(encoded) {
+  if (encoded.length === 0) {
     return null;
   }
-  if (type.typeId === DuckDBTypeId.DECIMAL) {
-    if (!(value instanceof DuckDBDecimalValue)) {
-      throw new LakeStorageError("[SixbDuckLake] DuckDB returned an invalid DECIMAL value.");
+  const bytes = [];
+  let index = 0;
+  while (index < encoded.length) {
+    const char = encoded[index];
+    const byte = char.charCodeAt(0);
+    if (isInlineByte(byte)) {
+      bytes.push(byte);
+      index += 1;
+      continue;
     }
-    return value.toString();
+    if (char !== "_") {
+      return null;
+    }
+    if (encoded[index + 1] === "_") {
+      bytes.push(46);
+      index += 2;
+      continue;
+    }
+    const hex = encoded.slice(index + 1, index + 3);
+    if (!isHexPair(hex)) {
+      return null;
+    }
+    bytes.push(Number.parseInt(hex, 16));
+    index += 3;
   }
-  return JSDuckDBValueConverter(value, type, converter);
-};
+  try {
+    return textDecoder.decode(new Uint8Array(bytes));
+  } catch {
+    return null;
+  }
+}
+function encodeDatasetTableName(datasetId) {
+  return `${DATASET_TABLE_PREFIX}${encodeDatasetId(datasetId)}`;
+}
+function encodeDatasetSequenceTableName(datasetId) {
+  return `sixb__seq__${encodeDatasetTableName(datasetId)}`;
+}
+function decodeDatasetTableName(tableName) {
+  if (!tableName.startsWith(DATASET_TABLE_PREFIX)) {
+    return null;
+  }
+  return decodeDatasetId(tableName.slice(DATASET_TABLE_PREFIX.length));
+}
 
 // src/internal/sql.ts
-import { LakeStorageError as LakeStorageError2 } from "@sixb/core/lake-storage";
+import { LakeStorageError as LakeStorageError3 } from "@sixb/core/lake-storage";
 var DEFAULT_ALIAS = "sixb_lake";
 function duckLakeAlias(options) {
   return options.alias ?? DEFAULT_ALIAS;
@@ -70,7 +163,7 @@ function duckLakeMetadataTableName(options, tableName) {
 }
 function quoteIdentifier(identifier) {
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier)) {
-    throw new LakeStorageError2(`[SixbDuckLake] Invalid SQL identifier '${identifier}'.`);
+    throw new LakeStorageError3(`[SixbDuckLake] Invalid SQL identifier '${identifier}'.`);
   }
   return `"${identifier}"`;
 }
@@ -279,7 +372,7 @@ function optionalIdentifierParameter(name, value) {
     return [];
   }
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
-    throw new LakeStorageError2(`[SixbDuckLake] Invalid SQL identifier '${value}'.`);
+    throw new LakeStorageError3(`[SixbDuckLake] Invalid SQL identifier '${value}'.`);
   }
   return [`${name} ${value}`];
 }
@@ -288,23 +381,441 @@ function appendPostgresConnectionParameter(parameters, names, name, value) {
     return;
   }
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
-    throw new LakeStorageError2(`[SixbDuckLake] Invalid PostgreSQL catalog parameter '${name}'.`);
+    throw new LakeStorageError3(`[SixbDuckLake] Invalid PostgreSQL catalog parameter '${name}'.`);
   }
   const normalizedName = name.toLowerCase();
   if (names.has(normalizedName)) {
-    throw new LakeStorageError2(`[SixbDuckLake] Duplicate PostgreSQL catalog parameter '${name}'.`);
+    throw new LakeStorageError3(`[SixbDuckLake] Duplicate PostgreSQL catalog parameter '${name}'.`);
+  }
+  names.add(normalizedName);
+  parameters.push(`${name}=${quotePostgresConnectionValue(String(value))}`);
+}
+function quotePostgresConnectionValue(value) {
+  return `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
+}
+function pathScheme(path) {
+  const match = /^([a-z][a-z0-9+.-]*):\/\//i.exec(path);
+  return match ? match[1].toLowerCase() : null;
+}
+
+// src/internal/ducklake-dataset-table-ref.ts
+async function resolveDatasetTableRef(options, runtime, datasetId) {
+  const tableName = encodeDatasetTableName(datasetId);
+  const ducklakeTable = duckLakeMetadataTableName(options, "ducklake_table");
+  const [row] = await runtime.query(`
+    SELECT table_id
+    FROM ${ducklakeTable}
+    WHERE table_name = ${quoteSqlString(tableName)}
+      AND end_snapshot IS NULL
+    LIMIT 1
+  `);
+  return row === undefined ? null : {
+    datasetId,
+    tableName,
+    tableId: getBigIntLike(row, "table_id")
+  };
+}
+
+// src/internal/schema.ts
+import { LakeStorageError as LakeStorageError5 } from "@sixb/core/lake-storage";
+
+// src/internal/duckdb-column-types.ts
+function normalizeDuckDbTypeSql(typeSql) {
+  return typeSql.trim().toUpperCase().replace(/\s+/g, " ").replace(/\s*([(),])\s*/g, "$1");
+}
+function defineDuckDbColumnType(sql, aliases = []) {
+  const acceptedTypes = new Set([sql, ...aliases].map(normalizeDuckDbTypeSql));
+  return {
+    sql,
+    matches: (typeSql) => acceptedTypes.has(normalizeDuckDbTypeSql(typeSql))
+  };
+}
+function defineDuckDbDecimalType(precision, scale) {
+  return {
+    ...defineDuckDbColumnType(`DECIMAL(${precision}, ${scale})`),
+    precision,
+    scale
+  };
+}
+var DUCKDB_COLUMN_TYPES = {
+  string: defineDuckDbColumnType("VARCHAR"),
+  boolean: defineDuckDbColumnType("BOOLEAN"),
+  int64: defineDuckDbColumnType("BIGINT", ["INT64"]),
+  float64: defineDuckDbColumnType("DOUBLE", ["FLOAT64"]),
+  decimal: defineDuckDbDecimalType(38, 9),
+  date: defineDuckDbColumnType("DATE"),
+  timestamp: defineDuckDbColumnType("TIMESTAMPTZ", ["TIMESTAMP WITH TIME ZONE"]),
+  json: defineDuckDbColumnType("JSON"),
+  fileRef: defineDuckDbColumnType("STRUCT(blobId VARCHAR, digest VARCHAR, sizeBytes BIGINT, fileName VARCHAR, mediaType VARCHAR, logicalPath VARCHAR)")
+};
+function findDatasetColumnTypeForDuckDbSql(typeSql) {
+  for (const type of Object.keys(DUCKDB_COLUMN_TYPES)) {
+    if (DUCKDB_COLUMN_TYPES[type].matches(typeSql)) {
+      return type;
+    }
+  }
+  return;
+}
+
+// src/internal/duckdb-decimal.ts
+import { normalizeDecimalValue } from "@sixb/core";
+import { LakeStorageError as LakeStorageError4 } from "@sixb/core/lake-storage";
+var decimalType = DUCKDB_COLUMN_TYPES.decimal;
+var maxIntegerDigits = decimalType.precision - decimalType.scale;
+function normalizeDuckDbDecimalValue(value, columnName) {
+  if (typeof value !== "string") {
+    throw new LakeStorageError4(`[SixbDuckLake] Decimal column '${columnName}' must be an exact decimal string.`);
+  }
+  let normalized;
+  try {
+    normalized = normalizeDecimalValue(value);
+  } catch {
+    throw new LakeStorageError4(`[SixbDuckLake] Decimal column '${columnName}' must be an exact decimal string.`);
+  }
+  const unsigned = normalized.startsWith("-") ? normalized.slice(1) : normalized;
+  const [integer, fraction = ""] = unsigned.split(".");
+  if (integer.length > maxIntegerDigits || fraction.length > decimalType.scale) {
+    throw new LakeStorageError4(`[SixbDuckLake] Decimal column '${columnName}' cannot be represented exactly as ${decimalType.sql}; expected at most ${maxIntegerDigits} integer digits and ${decimalType.scale} fractional digits.`);
+  }
+  return normalized;
+}
+
+// src/internal/schema.ts
+function datasetColumnTypeToDuckDbSql(type) {
+  return DUCKDB_COLUMN_TYPES[type].sql;
+}
+function duckDbTypeToDatasetColumnType(typeSql) {
+  const type = findDatasetColumnTypeForDuckDbSql(typeSql);
+  if (type) {
+    return type;
+  }
+  throw new LakeStorageError5(`[SixbDuckLake] DuckDB column type '${typeSql}' cannot be mapped to a Sixb dataset column type.`);
+}
+function datasetColumnToDuckDbSql(column) {
+  const nullableSql = column.nullable ? "" : " NOT NULL";
+  return `${quoteIdentifier(column.name)} ${datasetColumnTypeToDuckDbSql(column.type)}${nullableSql}`;
+}
+function datasetSchemaToDuckDbColumnsSql(schema) {
+  return schema.columns.map((column) => datasetColumnToDuckDbSql(column)).join(", ");
+}
+function datasetSchemaToDuckDbNullableColumnsSql(schema) {
+  return schema.columns.map((column) => `${quoteIdentifier(column.name)} ${datasetColumnTypeToDuckDbSql(column.type)}`).join(", ");
+}
+function datasetSchemaColumnNamesSql(schema) {
+  return schema.columns.map((column) => quoteIdentifier(column.name)).join(", ");
+}
+function normalizeReadValue(value, column) {
+  if (value === null || value === undefined) {
+    return null;
+  }
+  switch (column.type) {
+    case "int64":
+      return typeof value === "bigint" ? value.toString() : value;
+    case "decimal":
+      return normalizeDuckDbDecimalValue(value, column.name);
+    case "date":
+      return value instanceof Date ? value.toISOString().slice(0, 10) : String(value);
+    case "timestamp":
+      return value instanceof Date ? value.toISOString() : String(value);
+    case "json":
+      return typeof value === "string" ? JSON.parse(value) : value;
+    case "fileRef":
+      return normalizeFileRef(value);
+    default:
+      return value;
+  }
+}
+function normalizeFileRef(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new LakeStorageError5("[SixbDuckLake] DuckDB fileRef value must be a struct.");
+  }
+  const record = value;
+  return {
+    blobId: getStringField(record, "blobId"),
+    digest: getStringField(record, "digest"),
+    sizeBytes: getIntegerField(record, "sizeBytes"),
+    fileName: getOptionalStringField(record, "fileName"),
+    mediaType: getOptionalStringField(record, "mediaType"),
+    logicalPath: getOptionalStringField(record, "logicalPath")
+  };
+}
+function getStringField(record, key) {
+  const value = record[key];
+  if (typeof value !== "string") {
+    throw new LakeStorageError5(`[SixbDuckLake] DuckDB fileRef field '${key}' must be a string.`);
+  }
+  return value;
+}
+function getOptionalStringField(record, key) {
+  const value = record[key];
+  if (value === null || value === undefined) {
+    return;
+  }
+  if (typeof value !== "string") {
+    throw new LakeStorageError5(`[SixbDuckLake] DuckDB fileRef field '${key}' must be a string.`);
+  }
+  return value;
+}
+function getIntegerField(record, key) {
+  const value = record[key];
+  if (typeof value === "number" && Number.isInteger(value)) {
+    return value;
+  }
+  if (typeof value === "bigint") {
+    return Number(value);
+  }
+  throw new LakeStorageError5(`[SixbDuckLake] DuckDB fileRef field '${key}' must be an integer.`);
+}
+
+// src/internal/versions.ts
+import { LakeStorageError as LakeStorageError6 } from "@sixb/core/lake-storage";
+function parseVersionId(versionId) {
+  if (!versionId.startsWith("ducklake:")) {
+    throw new LakeStorageError6(`[SixbDuckLake] Invalid DuckLake version id '${versionId}'.`);
+  }
+  const snapshotId = versionId.slice("ducklake:".length);
+  if (!/^\d+$/.test(snapshotId)) {
+    throw new LakeStorageError6(`[SixbDuckLake] Invalid DuckLake version id '${versionId}'.`);
+  }
+  return snapshotId;
+}
+function toVersionId(snapshotId) {
+  return `ducklake:${snapshotId}`;
+}
+function parseCommitMetadata(value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    return;
+  }
+  if (!isRecord(parsed) || !isRecord(parsed.sixb) || parsed.sixb.kind !== "datasetVersion" || typeof parsed.sixb.datasetId !== "string") {
+    return;
+  }
+  const mode = parsed.sixb.mode;
+  const commitId = parsed.sixb.commitId;
+  const rowCount = parsed.sixb.rowCount;
+  const validatedPrimaryKeyColumns = parsed.sixb.validatedPrimaryKeyColumns;
+  return {
+    kind: "datasetVersion",
+    datasetId: parsed.sixb.datasetId,
+    ...typeof commitId === "string" ? { commitId } : {},
+    ...mode === "snapshot" || mode === "append" || mode === "merge" || mode === "schema" ? { mode } : {},
+    ...isDatasetProducer(parsed.sixb.producer) ? { producer: parsed.sixb.producer } : {},
+    ...isDatasetVersionRefs(parsed.sixb.inputs) ? { inputs: parsed.sixb.inputs } : {},
+    ...typeof commitId === "string" && isRowCount(rowCount) ? { rowCount } : {},
+    ...typeof commitId === "string" && isValidatedPrimaryKeyColumns(validatedPrimaryKeyColumns) ? { validatedPrimaryKeyColumns } : {},
+    ...isSchemaChangeMetadata(parsed.sixb.schemaChange) ? { schemaChange: parsed.sixb.schemaChange } : {}
+  };
+}
+function parseInlineDataChange(changesMade, tableId) {
+  const tableIdText = tableId.toString();
+  let hasDataChange = false;
+  let hasDeleteChange = false;
+  for (const change of changesMade.split(",")) {
+    const [kind, changedTableId] = change.split(":");
+    if (changedTableId !== tableIdText) {
+      continue;
+    }
+    const normalizedKind = kind.toLowerCase();
+    if (normalizedKind.includes("insert") || normalizedKind.includes("delete")) {
+      hasDataChange = true;
+    }
+    if (normalizedKind.includes("delete")) {
+      hasDeleteChange = true;
+    }
+  }
+  return { hasDataChange, hasDeleteChange };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isDatasetProducer(value) {
+  return isRecord(value) && (value.kind === "sync" || value.kind === "pipeline" || value.kind === "ingest") && optionalString(value.id) && optionalString(value.runId);
+}
+function isDatasetVersionRefs(value) {
+  return Array.isArray(value) && value.every((item) => isRecord(item) && typeof item.datasetId === "string" && typeof item.versionId === "string");
+}
+function isSchemaChangeMetadata(value) {
+  return isRecord(value) && (value.addColumns === undefined || Array.isArray(value.addColumns) && value.addColumns.every((columnName) => typeof columnName === "string"));
+}
+function optionalString(value) {
+  return value === undefined || typeof value === "string";
+}
+function isRowCount(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isValidatedPrimaryKeyColumns(value) {
+  return Array.isArray(value) && value.length > 0 && value.every((column) => typeof column === "string" && column.trim().length > 0) && new Set(value).size === value.length;
+}
+
+// src/internal/ducklake-change-reader.ts
+var PAGE_ROWS = 5000;
+
+class DuckLakeChangeReader {
+  options;
+  connections;
+  snapshots;
+  constructor(options, connections, snapshots) {
+    this.options = options;
+    this.connections = connections;
+    this.snapshots = snapshots;
+  }
+  async readChanges(input) {
+    input.signal?.throwIfAborted();
+    const before = await this.snapshots.getVersion(input.datasetId, input.fromVersionId);
+    const after = await this.snapshots.getVersion(input.datasetId, input.toVersionId);
+    const columns = resolveDatasetChangeColumns(input, before, after);
+    if (!columns)
+      return null;
+    const lease = await this.connections.acquireAttachedRuntime();
+    const runtime = lease.runtime;
+    const temporary = quoteIdentifier(`sixb_delta_${randomUUID().replaceAll("-", "")}`);
+    let retained = false;
+    let created = false;
+    try {
+      const ref = await resolveDatasetTableRef(this.options, runtime, input.datasetId);
+      if (!ref)
+        return null;
+      const table = qualifiedTableName(this.options, ref.tableName);
+      const oldRelation = `${table} AT (VERSION => ${parseVersionId(input.fromVersionId)})`;
+      const newRelation = `${table} AT (VERSION => ${parseVersionId(input.toVersionId)})`;
+      const previousCount = await uniqueRowCount(runtime, oldRelation, input.keyColumns);
+      const nextCount = await uniqueRowCount(runtime, newRelation, input.keyColumns);
+      if (previousCount === null || nextCount === null)
+        return null;
+      input.signal?.throwIfAborted();
+      const key = quoteIdentifier(input.keyColumns[0]);
+      const values = columns.flatMap((column, index) => [
+        `b.${quoteIdentifier(column.name)} AS b${index}`,
+        `a.${quoteIdentifier(column.name)} AS a${index}`
+      ]);
+      const join = input.keyColumns.map((name) => `b.${quoteIdentifier(name)} = a.${quoteIdentifier(name)}`).join(" AND ");
+      const changed = columns.map((column) => `b.${quoteIdentifier(column.name)} IS DISTINCT FROM a.${quoteIdentifier(column.name)}`).join(" OR ");
+      await runtime.run(`CREATE TEMP TABLE ${temporary} AS
+        SELECT b.${key} IS NOT NULL AS before_present, a.${key} IS NOT NULL AS after_present,
+          ${values.join(", ")}
+        FROM (SELECT * FROM ${oldRelation}) b
+        FULL OUTER JOIN (SELECT * FROM ${newRelation}) a ON ${join}
+        WHERE b.${key} IS NULL OR a.${key} IS NULL OR ${changed}`);
+      created = true;
+      const [count] = await runtime.query(`SELECT count(*) AS count FROM ${temporary}`);
+      const changeCount = safeCount(count, "count");
+      input.signal?.throwIfAborted();
+      let closePromise;
+      const close = () => {
+        closePromise ??= runtime.run(`DROP TABLE IF EXISTS ${temporary}`);
+        return closePromise;
+      };
+      const changes = async function* () {
+        try {
+          let cursor = -1n;
+          let delivered = 0;
+          while (delivered < changeCount) {
+            input.signal?.throwIfAborted();
+            if (closePromise)
+              throw new LakeStorageError7("[SixbDuckLake] Change reader is closed.");
+            const page = await runtime.query(`SELECT rowid AS position, * FROM ${temporary}
+              WHERE rowid > ${cursor} ORDER BY rowid LIMIT ${PAGE_ROWS}`);
+            if (page.length === 0)
+              throw new LakeStorageError7("[SixbDuckLake] Change read ended before its declared count.");
+            for (const row of page) {
+              input.signal?.throwIfAborted();
+              delivered++;
+              yield {
+                before: row.before_present === true ? rowImage(row, "b", columns) : null,
+                after: row.after_present === true ? rowImage(row, "a", columns) : null
+              };
+            }
+            cursor = getBigIntLike(page[page.length - 1], "position");
+          }
+        } finally {
+          await close();
+        }
+      }();
+      retained = true;
+      return { fromRowCount: previousCount, toRowCount: nextCount, changeCount, changes, close };
+    } finally {
+      try {
+        if (!retained && created)
+          await runtime.run(`DROP TABLE IF EXISTS ${temporary}`);
+      } finally {
+        await lease.release();
+      }
+    }
+  }
+}
+async function uniqueRowCount(runtime, relation, keys) {
+  const names = keys.map(quoteIdentifier);
+  const invalid = names.map((name) => `${name} IS NULL OR trim(${name}) = ''`).join(" OR ");
+  const [row] = await runtime.query(`SELECT count(*) AS total,
+    count(DISTINCT (${names.join(", ")})) AS unique_keys,
+    count(*) FILTER (WHERE ${invalid}) AS invalid_keys FROM ${relation}`);
+  const count = safeCount(row, "total");
+  return safeCount(row, "unique_keys") === count && safeCount(row, "invalid_keys") === 0 ? count : null;
+}
+function safeCount(row, name) {
+  const count = Number(getBigIntLike(row, name));
+  if (!Number.isSafeInteger(count) || count < 0)
+    throw new LakeStorageError7("[SixbDuckLake] Change count exceeds the supported integer range.");
+  return count;
+}
+function rowImage(row, prefix, columns) {
+  return Object.fromEntries(columns.map((column, index) => [
+    column.name,
+    normalizeReadValue(row[`${prefix}${index}`], column)
+  ]));
+}
+
+// src/internal/ducklake-connection-manager.ts
+import { LakeStorageError as LakeStorageError10 } from "@sixb/core/lake-storage";
+
+// src/internal/catalog-key.ts
+import { resolve } from "path";
+function localCatalogCoordinationKey(options) {
+  switch (options.catalog.type) {
+    case "duckdb":
+    case "sqlite":
+      if (options.catalog.path === ":memory:") {
+        return;
+      }
+      return `${options.catalog.type}:${resolve(options.catalog.path)}`;
+    case "custom":
+      return `custom:${options.catalog.uri}`;
+    case "postgres":
+      return;
   }
-  names.add(normalizedName);
-  parameters.push(`${name}=${quotePostgresConnectionValue(String(value))}`);
-}
-function quotePostgresConnectionValue(value) {
-  return `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
-}
-function pathScheme(path) {
-  const match = /^([a-z][a-z0-9+.-]*):\/\//i.exec(path);
-  return match ? match[1].toLowerCase() : null;
 }
 
+// src/internal/duckdb-runtime.ts
+import {
+  DuckDBInstance
+} from "@duckdb/node-api";
+import { LakeStorageError as LakeStorageError9 } from "@sixb/core/lake-storage";
+
+// src/internal/duckdb-value-converter.ts
+import {
+  DuckDBDecimalValue,
+  DuckDBTypeId,
+  JSDuckDBValueConverter
+} from "@duckdb/node-api";
+import { LakeStorageError as LakeStorageError8 } from "@sixb/core/lake-storage";
+var sixbDuckDbValueConverter = (value, type, converter) => {
+  if (value === null) {
+    return null;
+  }
+  if (type.typeId === DuckDBTypeId.DECIMAL) {
+    if (!(value instanceof DuckDBDecimalValue)) {
+      throw new LakeStorageError8("[SixbDuckLake] DuckDB returned an invalid DECIMAL value.");
+    }
+    return value.toString();
+  }
+  return JSDuckDBValueConverter(value, type, converter);
+};
+
 // src/internal/duckdb-runtime.ts
 class NodeDuckDbRuntime {
   instance;
@@ -337,8 +848,8 @@ class NodeDuckDbRuntime {
   async* streamRows(sql, values) {
     this.assertAcceptingOperations();
     let releaseOperation;
-    const operationFinished = new Promise((resolve2) => {
-      releaseOperation = resolve2;
+    const operationFinished = new Promise((resolve) => {
+      releaseOperation = resolve;
     });
     const waitForTurn = this.operations.then(() => {
       this.assertNotClosed();
@@ -392,12 +903,12 @@ class NodeDuckDbRuntime {
   }
   assertAcceptingOperations() {
     if (this.closing || this.closed) {
-      throw new LakeStorageError3("[SixbDuckLake] DuckDB runtime is closed.");
+      throw new LakeStorageError9("[SixbDuckLake] DuckDB runtime is closed.");
     }
   }
   assertNotClosed() {
     if (this.closed) {
-      throw new LakeStorageError3("[SixbDuckLake] DuckDB runtime is closed.");
+      throw new LakeStorageError9("[SixbDuckLake] DuckDB runtime is closed.");
     }
   }
 }
@@ -509,7 +1020,7 @@ class DuckLakeConnectionManager {
   }
   assertOpen() {
     if (this.closed) {
-      throw new LakeStorageError4("[SixbDuckLake] DuckLakeStorage is closed.");
+      throw new LakeStorageError10("[SixbDuckLake] DuckLakeStorage is closed.");
     }
   }
   async runtime() {
@@ -793,8 +1304,8 @@ class DuckLakeConnectionManager {
     }
     const previous = this.localAttachmentLock.catch(() => {});
     let release;
-    const current = new Promise((resolve2) => {
-      release = resolve2;
+    const current = new Promise((resolve) => {
+      release = resolve;
     });
     this.localAttachmentLock = previous.then(() => current);
     await previous;
@@ -805,264 +1316,54 @@ class DuckLakeConnectionManager {
       }
       released = true;
       release();
-    };
-  }
-  async closeRuntimePromise(runtimePromise, options) {
-    if (runtimePromise === undefined) {
-      return;
-    }
-    let runtime;
-    try {
-      runtime = await runtimePromise;
-    } catch {
-      return;
-    }
-    await this.closeRuntime(runtime, options);
-  }
-  async closeRuntime(runtime, options) {
-    if (options.detach) {
-      try {
-        await runtime.run(`DETACH ${quoteIdentifier(duckLakeAlias(this.options))}`);
-      } catch {}
-    }
-    await runtime.close();
-  }
-}
-var localCatalogGenerations = new Map;
-function currentLocalCatalogGeneration(options) {
-  const key = localCatalogCoordinationKey(options);
-  return key === undefined ? 0 : localCatalogGenerations.get(key) ?? 0;
-}
-function incrementLocalCatalogGeneration(options) {
-  const key = localCatalogCoordinationKey(options);
-  if (key === undefined) {
-    return 0;
-  }
-  const nextGeneration = (localCatalogGenerations.get(key) ?? 0) + 1;
-  localCatalogGenerations.set(key, nextGeneration);
-  return nextGeneration;
-}
-
-// src/internal/ducklake-dataset-catalog.ts
-import { randomUUID } from "crypto";
-import {
-  assertDatasetDefinition,
-  LakeStorageError as LakeStorageError11,
-  planDatasetDefinitionUpdate
-} from "@sixb/core/lake-storage";
-
-// src/internal/duckdb-row.ts
-import { LakeStorageError as LakeStorageError5 } from "@sixb/core/lake-storage";
-function getString(row, key) {
-  const value = row[key];
-  if (typeof value !== "string") {
-    throw new LakeStorageError5(`[SixbDuckLake] Expected DuckDB column '${key}' to be a string, got ${typeof value}.`);
-  }
-  return value;
-}
-function getOptionalString(row, key) {
-  const value = row[key];
-  if (value === null || value === undefined) {
-    return;
-  }
-  if (typeof value !== "string") {
-    throw new LakeStorageError5(`[SixbDuckLake] Expected DuckDB column '${key}' to be a string, got ${typeof value}.`);
-  }
-  return value;
-}
-function getBoolean(row, key) {
-  const value = row[key];
-  if (typeof value !== "boolean") {
-    throw new LakeStorageError5(`[SixbDuckLake] Expected DuckDB column '${key}' to be a boolean, got ${typeof value}.`);
-  }
-  return value;
-}
-function getBigIntLike(row, key) {
-  const value = row[key];
-  if (typeof value === "bigint") {
-    return value;
-  }
-  if (typeof value === "number" && Number.isInteger(value)) {
-    return BigInt(value);
-  }
-  if (typeof value === "string" && /^-?\d+$/.test(value)) {
-    return BigInt(value);
-  }
-  throw new LakeStorageError5(`[SixbDuckLake] Expected DuckDB column '${key}' to be an integer, got ${typeof value}.`);
-}
-function getOptionalBigIntLike(row, key) {
-  const value = row[key];
-  if (value === null || value === undefined) {
-    return;
-  }
-  return getBigIntLike(row, key);
-}
-function getDate(row, key) {
-  const value = row[key];
-  if (value instanceof Date) {
-    return value;
-  }
-  if (typeof value === "string") {
-    return new Date(value);
-  }
-  throw new LakeStorageError5(`[SixbDuckLake] Expected DuckDB column '${key}' to be a date, got ${typeof value}.`);
-}
-
-// src/internal/ducklake-catalog-schema.ts
-import { LakeStorageError as LakeStorageError8 } from "@sixb/core/lake-storage";
-
-// src/internal/schema.ts
-import { LakeStorageError as LakeStorageError7 } from "@sixb/core/lake-storage";
-
-// src/internal/duckdb-column-types.ts
-function normalizeDuckDbTypeSql(typeSql) {
-  return typeSql.trim().toUpperCase().replace(/\s+/g, " ").replace(/\s*([(),])\s*/g, "$1");
-}
-function defineDuckDbColumnType(sql, aliases = []) {
-  const acceptedTypes = new Set([sql, ...aliases].map(normalizeDuckDbTypeSql));
-  return {
-    sql,
-    matches: (typeSql) => acceptedTypes.has(normalizeDuckDbTypeSql(typeSql))
-  };
-}
-function defineDuckDbDecimalType(precision, scale) {
-  return {
-    ...defineDuckDbColumnType(`DECIMAL(${precision}, ${scale})`),
-    precision,
-    scale
-  };
-}
-var DUCKDB_COLUMN_TYPES = {
-  string: defineDuckDbColumnType("VARCHAR"),
-  boolean: defineDuckDbColumnType("BOOLEAN"),
-  int64: defineDuckDbColumnType("BIGINT", ["INT64"]),
-  float64: defineDuckDbColumnType("DOUBLE", ["FLOAT64"]),
-  decimal: defineDuckDbDecimalType(38, 9),
-  date: defineDuckDbColumnType("DATE"),
-  timestamp: defineDuckDbColumnType("TIMESTAMPTZ", ["TIMESTAMP WITH TIME ZONE"]),
-  json: defineDuckDbColumnType("JSON"),
-  fileRef: defineDuckDbColumnType("STRUCT(blobId VARCHAR, digest VARCHAR, sizeBytes BIGINT, fileName VARCHAR, mediaType VARCHAR, logicalPath VARCHAR)")
-};
-function findDatasetColumnTypeForDuckDbSql(typeSql) {
-  for (const type of Object.keys(DUCKDB_COLUMN_TYPES)) {
-    if (DUCKDB_COLUMN_TYPES[type].matches(typeSql)) {
-      return type;
-    }
-  }
-  return;
-}
-
-// src/internal/duckdb-decimal.ts
-import { normalizeDecimalValue } from "@sixb/core";
-import { LakeStorageError as LakeStorageError6 } from "@sixb/core/lake-storage";
-var decimalType = DUCKDB_COLUMN_TYPES.decimal;
-var maxIntegerDigits = decimalType.precision - decimalType.scale;
-function normalizeDuckDbDecimalValue(value, columnName) {
-  if (typeof value !== "string") {
-    throw new LakeStorageError6(`[SixbDuckLake] Decimal column '${columnName}' must be an exact decimal string.`);
-  }
-  let normalized;
-  try {
-    normalized = normalizeDecimalValue(value);
-  } catch {
-    throw new LakeStorageError6(`[SixbDuckLake] Decimal column '${columnName}' must be an exact decimal string.`);
-  }
-  const unsigned = normalized.startsWith("-") ? normalized.slice(1) : normalized;
-  const [integer, fraction = ""] = unsigned.split(".");
-  if (integer.length > maxIntegerDigits || fraction.length > decimalType.scale) {
-    throw new LakeStorageError6(`[SixbDuckLake] Decimal column '${columnName}' cannot be represented exactly as ${decimalType.sql}; expected at most ${maxIntegerDigits} integer digits and ${decimalType.scale} fractional digits.`);
-  }
-  return normalized;
-}
-
-// src/internal/schema.ts
-function datasetColumnTypeToDuckDbSql(type) {
-  return DUCKDB_COLUMN_TYPES[type].sql;
-}
-function duckDbTypeToDatasetColumnType(typeSql) {
-  const type = findDatasetColumnTypeForDuckDbSql(typeSql);
-  if (type) {
-    return type;
-  }
-  throw new LakeStorageError7(`[SixbDuckLake] DuckDB column type '${typeSql}' cannot be mapped to a Sixb dataset column type.`);
-}
-function datasetColumnToDuckDbSql(column) {
-  const nullableSql = column.nullable ? "" : " NOT NULL";
-  return `${quoteIdentifier(column.name)} ${datasetColumnTypeToDuckDbSql(column.type)}${nullableSql}`;
-}
-function datasetSchemaToDuckDbColumnsSql(schema) {
-  return schema.columns.map((column) => datasetColumnToDuckDbSql(column)).join(", ");
-}
-function datasetSchemaToDuckDbNullableColumnsSql(schema) {
-  return schema.columns.map((column) => `${quoteIdentifier(column.name)} ${datasetColumnTypeToDuckDbSql(column.type)}`).join(", ");
-}
-function datasetSchemaColumnNamesSql(schema) {
-  return schema.columns.map((column) => quoteIdentifier(column.name)).join(", ");
-}
-function normalizeReadValue(value, column) {
-  if (value === null || value === undefined) {
-    return null;
-  }
-  switch (column.type) {
-    case "int64":
-      return typeof value === "bigint" ? value.toString() : value;
-    case "decimal":
-      return normalizeDuckDbDecimalValue(value, column.name);
-    case "date":
-      return value instanceof Date ? value.toISOString().slice(0, 10) : String(value);
-    case "timestamp":
-      return value instanceof Date ? value.toISOString() : String(value);
-    case "json":
-      return typeof value === "string" ? JSON.parse(value) : value;
-    case "fileRef":
-      return normalizeFileRef(value);
-    default:
-      return value;
-  }
-}
-function normalizeFileRef(value) {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new LakeStorageError7("[SixbDuckLake] DuckDB fileRef value must be a struct.");
-  }
-  const record = value;
-  return {
-    blobId: getStringField(record, "blobId"),
-    digest: getStringField(record, "digest"),
-    sizeBytes: getIntegerField(record, "sizeBytes"),
-    fileName: getOptionalStringField(record, "fileName"),
-    mediaType: getOptionalStringField(record, "mediaType"),
-    logicalPath: getOptionalStringField(record, "logicalPath")
-  };
-}
-function getStringField(record, key) {
-  const value = record[key];
-  if (typeof value !== "string") {
-    throw new LakeStorageError7(`[SixbDuckLake] DuckDB fileRef field '${key}' must be a string.`);
+    };
   }
-  return value;
-}
-function getOptionalStringField(record, key) {
-  const value = record[key];
-  if (value === null || value === undefined) {
-    return;
+  async closeRuntimePromise(runtimePromise, options) {
+    if (runtimePromise === undefined) {
+      return;
+    }
+    let runtime;
+    try {
+      runtime = await runtimePromise;
+    } catch {
+      return;
+    }
+    await this.closeRuntime(runtime, options);
   }
-  if (typeof value !== "string") {
-    throw new LakeStorageError7(`[SixbDuckLake] DuckDB fileRef field '${key}' must be a string.`);
+  async closeRuntime(runtime, options) {
+    if (options.detach) {
+      try {
+        await runtime.run(`DETACH ${quoteIdentifier(duckLakeAlias(this.options))}`);
+      } catch {}
+    }
+    await runtime.close();
   }
-  return value;
 }
-function getIntegerField(record, key) {
-  const value = record[key];
-  if (typeof value === "number" && Number.isInteger(value)) {
-    return value;
-  }
-  if (typeof value === "bigint") {
-    return Number(value);
+var localCatalogGenerations = new Map;
+function currentLocalCatalogGeneration(options) {
+  const key = localCatalogCoordinationKey(options);
+  return key === undefined ? 0 : localCatalogGenerations.get(key) ?? 0;
+}
+function incrementLocalCatalogGeneration(options) {
+  const key = localCatalogCoordinationKey(options);
+  if (key === undefined) {
+    return 0;
   }
-  throw new LakeStorageError7(`[SixbDuckLake] DuckDB fileRef field '${key}' must be an integer.`);
+  const nextGeneration = (localCatalogGenerations.get(key) ?? 0) + 1;
+  localCatalogGenerations.set(key, nextGeneration);
+  return nextGeneration;
 }
 
+// src/internal/ducklake-dataset-catalog.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import {
+  assertDatasetDefinition,
+  LakeStorageError as LakeStorageError13,
+  planDatasetDefinitionUpdate
+} from "@sixb/core/lake-storage";
+
 // src/internal/ducklake-catalog-schema.ts
+import { LakeStorageError as LakeStorageError11 } from "@sixb/core/lake-storage";
 var SIXB_PRIMARY_KEY_COMMENT_NAMESPACE = "sixb:primary-key:";
 var DATASET_SEQUENCE_COLUMN_COMMENT = "sixb.sequenceBy.v1";
 var SIXB_PRIMARY_KEY_COMMENT_PREFIX = `${SIXB_PRIMARY_KEY_COMMENT_NAMESPACE}v1:`;
@@ -1113,14 +1414,14 @@ function duckLakeCatalogColumnsToDatasetPrimaryKey(tableName, rows) {
       throwInvalidPrimaryKeyMetadata(tableName, column, comment);
     }
     if (seenOrdinals.has(ordinal)) {
-      throw new LakeStorageError8(`[SixbDuckLake] Dataset table '${tableName}' has duplicate primary-key ordinal '${ordinal}'.`);
+      throw new LakeStorageError11(`[SixbDuckLake] Dataset table '${tableName}' has duplicate primary-key ordinal '${ordinal}'.`);
     }
     seenOrdinals.add(ordinal);
     if (duckDbTypeToDatasetColumnType(column.columnType) !== "string") {
-      throw new LakeStorageError8(`[SixbDuckLake] Dataset table '${tableName}' primary-key column '${column.columnName}' must map to type 'string'.`);
+      throw new LakeStorageError11(`[SixbDuckLake] Dataset table '${tableName}' primary-key column '${column.columnName}' must map to type 'string'.`);
     }
     if (column.nullsAllowed) {
-      throw new LakeStorageError8(`[SixbDuckLake] Dataset table '${tableName}' primary-key column '${column.columnName}' must not be nullable.`);
+      throw new LakeStorageError11(`[SixbDuckLake] Dataset table '${tableName}' primary-key column '${column.columnName}' must not be nullable.`);
     }
     keyedColumns.push({ column, ordinal });
   }
@@ -1130,7 +1431,7 @@ function duckLakeCatalogColumnsToDatasetPrimaryKey(tableName, rows) {
   keyedColumns.sort((left, right) => left.ordinal - right.ordinal);
   for (const [expectedOrdinal, keyedColumn] of keyedColumns.entries()) {
     if (keyedColumn.ordinal !== expectedOrdinal) {
-      throw new LakeStorageError8(`[SixbDuckLake] Dataset table '${tableName}' primary-key ordinals must be contiguous from 0.`);
+      throw new LakeStorageError11(`[SixbDuckLake] Dataset table '${tableName}' primary-key ordinals must be contiguous from 0.`);
     }
   }
   const columnNames = keyedColumns.map(({ column }) => column.columnName);
@@ -1140,7 +1441,7 @@ function duckLakeCatalogColumnsToDatasetPrimaryKey(tableName, rows) {
   return columnNames;
 }
 function throwInvalidPrimaryKeyMetadata(tableName, column, comment) {
-  throw new LakeStorageError8(`[SixbDuckLake] Dataset table '${tableName}' has malformed primary-key metadata '${comment}' on column '${column.columnName}'.`);
+  throw new LakeStorageError11(`[SixbDuckLake] Dataset table '${tableName}' has malformed primary-key metadata '${comment}' on column '${column.columnName}'.`);
 }
 function duckLakeCatalogColumnToDefinition(tableName, column, childrenByParentId) {
   const children = [...childrenByParentId.get(column.columnId) ?? []].sort(compareDuckLakeCatalogColumnOrder);
@@ -1157,7 +1458,7 @@ function duckLakeCatalogColumnTypeToDatasetType(tableName, column, children) {
   if (isFileRefStruct(children)) {
     return "fileRef";
   }
-  throw new LakeStorageError8(`[SixbDuckLake] DuckDB column type '${formatDuckLakeCatalogColumnType(column, children)}' in dataset table '${tableName}' cannot be mapped to a Sixb dataset column type.`);
+  throw new LakeStorageError11(`[SixbDuckLake] DuckDB column type '${formatDuckLakeCatalogColumnType(column, children)}' in dataset table '${tableName}' cannot be mapped to a Sixb dataset column type.`);
 }
 function compareDuckLakeCatalogColumnOrder(left, right) {
   return Number(left.columnOrder - right.columnOrder);
@@ -1179,84 +1480,7 @@ function formatDuckLakeCatalogColumnType(column, children) {
 }
 
 // src/internal/ducklake-current-dataset-definitions.ts
-import { LakeStorageError as LakeStorageError10 } from "@sixb/core/lake-storage";
-
-// src/internal/names.ts
-import { LakeStorageError as LakeStorageError9 } from "@sixb/core/lake-storage";
-var DATASET_TABLE_PREFIX = "sixb__ds__";
-var textEncoder = new TextEncoder;
-var textDecoder = new TextDecoder("utf-8", { fatal: true });
-function isInlineByte(byte) {
-  return byte >= 97 && byte <= 122 || byte >= 48 && byte <= 57;
-}
-function isHexPair(value) {
-  return /^[0-9a-f]{2}$/.test(value);
-}
-function encodeDatasetId(datasetId) {
-  if (datasetId.trim().length === 0) {
-    throw new LakeStorageError9("[SixbDuckLake] Dataset id must not be empty.");
-  }
-  let encoded = "";
-  for (const byte of textEncoder.encode(datasetId)) {
-    if (isInlineByte(byte)) {
-      encoded += String.fromCharCode(byte);
-    } else if (byte === 46) {
-      encoded += "__";
-    } else {
-      encoded += `_${byte.toString(16).padStart(2, "0")}`;
-    }
-  }
-  return encoded;
-}
-function decodeDatasetId(encoded) {
-  if (encoded.length === 0) {
-    return null;
-  }
-  const bytes = [];
-  let index = 0;
-  while (index < encoded.length) {
-    const char = encoded[index];
-    const byte = char.charCodeAt(0);
-    if (isInlineByte(byte)) {
-      bytes.push(byte);
-      index += 1;
-      continue;
-    }
-    if (char !== "_") {
-      return null;
-    }
-    if (encoded[index + 1] === "_") {
-      bytes.push(46);
-      index += 2;
-      continue;
-    }
-    const hex = encoded.slice(index + 1, index + 3);
-    if (!isHexPair(hex)) {
-      return null;
-    }
-    bytes.push(Number.parseInt(hex, 16));
-    index += 3;
-  }
-  try {
-    return textDecoder.decode(new Uint8Array(bytes));
-  } catch {
-    return null;
-  }
-}
-function encodeDatasetTableName(datasetId) {
-  return `${DATASET_TABLE_PREFIX}${encodeDatasetId(datasetId)}`;
-}
-function encodeDatasetSequenceTableName(datasetId) {
-  return `sixb__seq__${encodeDatasetTableName(datasetId)}`;
-}
-function decodeDatasetTableName(tableName) {
-  if (!tableName.startsWith(DATASET_TABLE_PREFIX)) {
-    return null;
-  }
-  return decodeDatasetId(tableName.slice(DATASET_TABLE_PREFIX.length));
-}
-
-// src/internal/ducklake-current-dataset-definitions.ts
+import { LakeStorageError as LakeStorageError12 } from "@sixb/core/lake-storage";
 async function readCurrentDatasetDefinitions(input) {
   if (input.datasetIds?.length === 0) {
     return new Map;
@@ -1383,7 +1607,7 @@ async function readCurrentDatasetPartitions(input, tableNames) {
       transform: getString(row, "transform")
     };
     if (partition.transform !== "identity") {
-      throw new LakeStorageError10(`[SixbDuckLake] Dataset table '${partition.tableName}' uses unsupported DuckLake partition transform '${partition.transform}'.`);
+      throw new LakeStorageError12(`[SixbDuckLake] Dataset table '${partition.tableName}' uses unsupported DuckLake partition transform '${partition.transform}'.`);
     }
     return partition;
   });
@@ -1485,7 +1709,7 @@ class DuckLakeDatasetCatalog {
     if (failures.length > 0) {
       const details = failures.join(`
 `);
-      throw new LakeStorageError11(`[SixbLake] Lake dataset definition check failed for ${failures.length} dataset(s).
+      throw new LakeStorageError13(`[SixbLake] Lake dataset definition check failed for ${failures.length} dataset(s).
 ${details}`);
     }
   }
@@ -1521,12 +1745,12 @@ ${details}`);
     assertDuckLakeSnapshotId(snapshotId);
     const columns = await this.readDatasetColumnsAtSnapshot(runtime, tableName, tableId, snapshotId);
     if (columns.length === 0) {
-      throw new LakeStorageError11(`[SixbDuckLake] Could not reconstruct schema for dataset '${datasetId}' at DuckLake snapshot '${snapshotId}'.`);
+      throw new LakeStorageError13(`[SixbDuckLake] Could not reconstruct schema for dataset '${datasetId}' at DuckLake snapshot '${snapshotId}'.`);
     }
     return duckLakeCatalogColumnsToDatasetSchema(tableName, columns);
   }
   assertSchema(definition) {
-    assertDatasetDefinition(definition, (message) => new LakeStorageError11(`[SixbDuckLake] ${message}`));
+    assertDatasetDefinition(definition, (message) => new LakeStorageError13(`[SixbDuckLake] ${message}`));
   }
   async applyExistingDatasetUpdate(plan) {
     const tableName = encodeDatasetTableName(plan.definition.id);
@@ -1573,7 +1797,7 @@ ${details}`);
       await runtime.run(`ALTER TABLE ${qualifiedName} SET PARTITIONED BY (${definition.partitionBy.map((columnName) => quoteIdentifier(columnName)).join(", ")})`);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new LakeStorageError11(`[SixbDuckLake] Dataset '${definition.id}' cannot apply partitionBy because DuckLake rejected ALTER TABLE SET PARTITIONED BY: ${message}`);
+      throw new LakeStorageError13(`[SixbDuckLake] Dataset '${definition.id}' cannot apply partitionBy because DuckLake rejected ALTER TABLE SET PARTITIONED BY: ${message}`);
     }
   }
   async applyPrimaryKey(runtime, qualifiedName, definition) {
@@ -1590,7 +1814,7 @@ ${details}`);
       sixb: {
         kind: "datasetVersion",
         datasetId,
-        commitId: randomUUID(),
+        commitId: randomUUID2(),
         mode: "schema",
         schemaChange: {
           addColumns: plan.columns.map((column) => column.name)
@@ -1632,12 +1856,12 @@ ${details}`);
 }
 function assertDuckLakeSnapshotId(snapshotId) {
   if (!/^\d+$/.test(snapshotId)) {
-    throw new LakeStorageError11(`[SixbDuckLake] Invalid DuckLake snapshot id '${snapshotId}'.`);
+    throw new LakeStorageError13(`[SixbDuckLake] Invalid DuckLake snapshot id '${snapshotId}'.`);
   }
 }
 
 // src/internal/ducklake-maintenance.ts
-import { LakeStorageError as LakeStorageError12 } from "@sixb/core/lake-storage";
+import { LakeStorageError as LakeStorageError14 } from "@sixb/core/lake-storage";
 var DEFAULT_RETENTION = "7 days";
 
 class DuckLakeMaintenance {
@@ -1653,7 +1877,7 @@ class DuckLakeMaintenance {
     const deleteOlderThan = options.deleteOlderThan ?? expireOlderThan;
     const dryRun = options.dryRun ?? false;
     if (this.options.readOnly && !dryRun) {
-      throw new LakeStorageError12("[SixbDuckLake] DuckLake maintenance cannot run in read-only mode.");
+      throw new LakeStorageError14("[SixbDuckLake] DuckLake maintenance cannot run in read-only mode.");
     }
     return this.connections.withExclusiveAttached(async (runtime) => {
       const counts = await runMaintenanceProcedures(runtime, this.options, {
@@ -1690,112 +1914,7 @@ function maintenanceProcedureSql(procedure, aliasSql, olderThan, dryRun) {
 }
 
 // src/internal/ducklake-row-reader.ts
-import { LakeStorageError as LakeStorageError14 } from "@sixb/core/lake-storage";
-
-// src/internal/ducklake-dataset-table-ref.ts
-async function resolveDatasetTableRef(options, runtime, datasetId) {
-  const tableName = encodeDatasetTableName(datasetId);
-  const ducklakeTable = duckLakeMetadataTableName(options, "ducklake_table");
-  const [row] = await runtime.query(`
-    SELECT table_id
-    FROM ${ducklakeTable}
-    WHERE table_name = ${quoteSqlString(tableName)}
-      AND end_snapshot IS NULL
-    LIMIT 1
-  `);
-  return row === undefined ? null : {
-    datasetId,
-    tableName,
-    tableId: getBigIntLike(row, "table_id")
-  };
-}
-
-// src/internal/versions.ts
-import { LakeStorageError as LakeStorageError13 } from "@sixb/core/lake-storage";
-function parseVersionId(versionId) {
-  if (!versionId.startsWith("ducklake:")) {
-    throw new LakeStorageError13(`[SixbDuckLake] Invalid DuckLake version id '${versionId}'.`);
-  }
-  const snapshotId = versionId.slice("ducklake:".length);
-  if (!/^\d+$/.test(snapshotId)) {
-    throw new LakeStorageError13(`[SixbDuckLake] Invalid DuckLake version id '${versionId}'.`);
-  }
-  return snapshotId;
-}
-function toVersionId(snapshotId) {
-  return `ducklake:${snapshotId}`;
-}
-function parseCommitMetadata(value) {
-  if (typeof value !== "string") {
-    return;
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(value);
-  } catch {
-    return;
-  }
-  if (!isRecord(parsed) || !isRecord(parsed.sixb) || parsed.sixb.kind !== "datasetVersion" || typeof parsed.sixb.datasetId !== "string") {
-    return;
-  }
-  const mode = parsed.sixb.mode;
-  const commitId = parsed.sixb.commitId;
-  const rowCount = parsed.sixb.rowCount;
-  const validatedPrimaryKeyColumns = parsed.sixb.validatedPrimaryKeyColumns;
-  return {
-    kind: "datasetVersion",
-    datasetId: parsed.sixb.datasetId,
-    ...typeof commitId === "string" ? { commitId } : {},
-    ...mode === "snapshot" || mode === "append" || mode === "merge" || mode === "schema" ? { mode } : {},
-    ...isDatasetProducer(parsed.sixb.producer) ? { producer: parsed.sixb.producer } : {},
-    ...isDatasetVersionRefs(parsed.sixb.inputs) ? { inputs: parsed.sixb.inputs } : {},
-    ...typeof commitId === "string" && isRowCount(rowCount) ? { rowCount } : {},
-    ...typeof commitId === "string" && isValidatedPrimaryKeyColumns(validatedPrimaryKeyColumns) ? { validatedPrimaryKeyColumns } : {},
-    ...isSchemaChangeMetadata(parsed.sixb.schemaChange) ? { schemaChange: parsed.sixb.schemaChange } : {}
-  };
-}
-function parseInlineDataChange(changesMade, tableId) {
-  const tableIdText = tableId.toString();
-  let hasDataChange = false;
-  let hasDeleteChange = false;
-  for (const change of changesMade.split(",")) {
-    const [kind, changedTableId] = change.split(":");
-    if (changedTableId !== tableIdText) {
-      continue;
-    }
-    const normalizedKind = kind.toLowerCase();
-    if (normalizedKind.includes("insert") || normalizedKind.includes("delete")) {
-      hasDataChange = true;
-    }
-    if (normalizedKind.includes("delete")) {
-      hasDeleteChange = true;
-    }
-  }
-  return { hasDataChange, hasDeleteChange };
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isDatasetProducer(value) {
-  return isRecord(value) && (value.kind === "sync" || value.kind === "pipeline" || value.kind === "ingest") && optionalString(value.id) && optionalString(value.runId);
-}
-function isDatasetVersionRefs(value) {
-  return Array.isArray(value) && value.every((item) => isRecord(item) && typeof item.datasetId === "string" && typeof item.versionId === "string");
-}
-function isSchemaChangeMetadata(value) {
-  return isRecord(value) && (value.addColumns === undefined || Array.isArray(value.addColumns) && value.addColumns.every((columnName) => typeof columnName === "string"));
-}
-function optionalString(value) {
-  return value === undefined || typeof value === "string";
-}
-function isRowCount(value) {
-  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
-}
-function isValidatedPrimaryKeyColumns(value) {
-  return Array.isArray(value) && value.length > 0 && value.every((column) => typeof column === "string" && column.trim().length > 0) && new Set(value).size === value.length;
-}
-
-// src/internal/ducklake-row-reader.ts
+import { LakeStorageError as LakeStorageError15 } from "@sixb/core/lake-storage";
 var READ_PAGE_ROWS = 5000;
 var PHYSICAL_ROW_ID_ALIAS = "__sixb_physical_row_id";
 
@@ -1815,7 +1934,7 @@ class DuckLakeRowReader {
       const runtime = lease.runtime;
       const tableRef = await resolveDatasetTableRef(this.options, runtime, input.datasetId);
       if (!tableRef) {
-        throw new LakeStorageError14(`[SixbDuckLake] Unknown dataset '${input.datasetId}'.`);
+        throw new LakeStorageError15(`[SixbDuckLake] Unknown dataset '${input.datasetId}'.`);
       }
       const version = await this.resolveVersion(runtime, tableRef, input.versionId);
       const selectedColumns = this.resolveReadColumns(tableRef.datasetId, version.schema, input.columns);
@@ -1891,18 +2010,18 @@ class DuckLakeRowReader {
     return columns.map((columnName) => {
       const column = columnsByName.get(columnName);
       if (!column) {
-        throw new LakeStorageError14(`[SixbDuckLake] Dataset '${datasetId}' does not have column '${columnName}' at the requested version.`);
+        throw new LakeStorageError15(`[SixbDuckLake] Dataset '${datasetId}' does not have column '${columnName}' at the requested version.`);
       }
       return column;
     });
   }
   throwNoCommittedVersion(datasetId) {
-    throw new LakeStorageError14(`[SixbDuckLake] No committed version found for dataset '${datasetId}'.`);
+    throw new LakeStorageError15(`[SixbDuckLake] No committed version found for dataset '${datasetId}'.`);
   }
 }
 
 // src/internal/ducklake-snapshot-reader.ts
-import { LakeStorageError as LakeStorageError15 } from "@sixb/core/lake-storage";
+import { LakeStorageError as LakeStorageError16 } from "@sixb/core/lake-storage";
 var SNAPSHOT_ROW_BATCH_SIZE = 128;
 var CATALOG_SNAPSHOT_SCAN_LIMIT = 512;
 
@@ -2115,7 +2234,7 @@ class DuckLakeSnapshotReader {
   }
   assertNoMetadataConflict(snapshotId, datasetId, metadata) {
     if (metadata !== undefined && metadata.datasetId !== datasetId) {
-      throw new LakeStorageError15(`[SixbDuckLake] DuckLake snapshot '${snapshotId}' changed dataset '${datasetId}' but Sixb commit metadata references dataset '${metadata.datasetId}'.`);
+      throw new LakeStorageError16(`[SixbDuckLake] DuckLake snapshot '${snapshotId}' changed dataset '${datasetId}' but Sixb commit metadata references dataset '${metadata.datasetId}'.`);
     }
   }
   async getLatestVersionForDefinition(runtime, dataset) {
@@ -2395,7 +2514,7 @@ class DuckLakeSnapshotReader {
 }
 function assertDuckLakeSnapshotId2(snapshotId) {
   if (!/^\d+$/.test(snapshotId)) {
-    throw new LakeStorageError15(`[SixbDuckLake] Invalid DuckLake snapshot id '${snapshotId}'.`);
+    throw new LakeStorageError16(`[SixbDuckLake] Invalid DuckLake snapshot id '${snapshotId}'.`);
   }
 }
 function fileChangeKey(snapshotId, tableId) {
@@ -2403,19 +2522,19 @@ function fileChangeKey(snapshotId, tableId) {
 }
 
 // src/internal/ducklake-sql-executor.ts
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID as randomUUID4 } from "crypto";
 import {
-  LakeStorageError as LakeStorageError18
+  LakeStorageError as LakeStorageError19
 } from "@sixb/core/lake-storage";
 
 // src/internal/dataset-row-commit.ts
 import {
   getDatasetPrimaryKeyColumns,
-  LakeStorageError as LakeStorageError16
+  LakeStorageError as LakeStorageError17
 } from "@sixb/core/lake-storage";
 function assertDatasetWriteMode(mode, operation) {
   if (mode !== "snapshot" && mode !== "append") {
-    throw new LakeStorageError16(`[SixbDuckLake] Invalid ${operation} mode '${String(mode)}'. Expected 'snapshot' or 'append'.`);
+    throw new LakeStorageError17(`[SixbDuckLake] Invalid ${operation} mode '${String(mode)}'. Expected 'snapshot' or 'append'.`);
   }
 }
 async function applyDatasetRowsFromRelation(input) {
@@ -2475,7 +2594,7 @@ async function applyDatasetRowsFromRelation(input) {
 async function inspectUniqueKeyedRelation(input) {
   const primaryKeyColumns = getDatasetPrimaryKeyColumns(input.dataset);
   if (primaryKeyColumns === null) {
-    throw new LakeStorageError16(`[SixbDuckLake] Dataset '${input.dataset.id}' must define a primaryKey before rows can be keyed.`);
+    throw new LakeStorageError17(`[SixbDuckLake] Dataset '${input.dataset.id}' must define a primaryKey before rows can be keyed.`);
   }
   const keysSql = primaryKeyColumns.map((column) => quoteIdentifier(column)).join(", ");
   const [row] = await input.runtime.query(`
@@ -2490,7 +2609,7 @@ async function inspectUniqueKeyedRelation(input) {
   const rowCount = row === undefined ? 0 : Number(getBigIntLike(row, "row_count"));
   const maxKeyCount = row === undefined ? 0 : Number(getBigIntLike(row, "max_key_count"));
   if (maxKeyCount > 1) {
-    throw new LakeStorageError16(`[SixbDuckLake] Dataset '${input.dataset.id}' ${input.context} contains duplicate primary key.`);
+    throw new LakeStorageError17(`[SixbDuckLake] Dataset '${input.dataset.id}' ${input.context} contains duplicate primary key.`);
   }
   return rowCount;
 }
@@ -2507,7 +2626,7 @@ async function assertNoPrimaryKeyOverlap(input) {
     LIMIT 1
   `);
   if (collision !== undefined) {
-    throw new LakeStorageError16(`[SixbDuckLake] Dataset '${input.dataset.id}' ${input.context} contains duplicate primary key.`);
+    throw new LakeStorageError17(`[SixbDuckLake] Dataset '${input.dataset.id}' ${input.context} contains duplicate primary key.`);
   }
 }
 async function fingerprintRelation(runtime, relationSql, columnsSql) {
@@ -2539,9 +2658,9 @@ async function countRows(runtime, relationSql) {
 }
 
 // src/internal/sql-transform-relations.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 import {
-  LakeStorageError as LakeStorageError17
+  LakeStorageError as LakeStorageError18
 } from "@sixb/core/lake-storage";
 var RELATION_PLACEHOLDER_PREFIX = "__sixb_sql_transform_relation_";
 var RELATION_PLACEHOLDER_PATTERN = /__sixb_sql_transform_relation_[0-9a-f]{32}_[0-9]+__/g;
@@ -2559,12 +2678,12 @@ function renderDuckLakeSqlTransformSql(input) {
   const context = createDuckLakeSqlTransformRelationContext(input);
   const sql = input.sql(context.relations);
   if (typeof sql !== "string") {
-    throw new LakeStorageError17("[SixbDuckLake] SQL transform body must return a SQL string.");
+    throw new LakeStorageError18("[SixbDuckLake] SQL transform body must return a SQL string.");
   }
   return context.render(sql);
 }
 function createDuckLakeSqlTransformRelationContext(input) {
-  const token = randomUUID2().replaceAll("-", "");
+  const token = randomUUID3().replaceAll("-", "");
   const relations = Object.create(null);
   const replacements = new Map;
   let index = 0;
@@ -2597,7 +2716,7 @@ function renderDuckLakeSourceRelation(options, source) {
   return `(SELECT * FROM ${qualifiedTableName(options, tableName)} AT (VERSION => ${snapshotId}))`;
 }
 function throwUnresolvedPlaceholder() {
-  throw new LakeStorageError17("[SixbDuckLake] SQL transform contains an unresolved relation placeholder.");
+  throw new LakeStorageError18("[SixbDuckLake] SQL transform contains an unresolved relation placeholder.");
 }
 
 // src/internal/ducklake-sql-executor.ts
@@ -2657,8 +2776,8 @@ class DuckLakeSqlExecutor {
         commitMessage: input.commitMessage ?? `execute SQL transform for dataset ${target.id}`,
         producer: input.producer,
         inputs: sources.inputs,
-        applyChanges: (runtime2, context) => this.applySqlTransform({
-          runtime: runtime2,
+        applyChanges: (runtime, context) => this.applySqlTransform({
+          runtime,
           target,
           mode: input.mode,
           sql,
@@ -2691,14 +2810,14 @@ class DuckLakeSqlExecutor {
   async resolveSourceDataset(runtime, dataset) {
     const definition = await this.datasets.getDatasetOnRuntime(runtime, dataset.id);
     if (!definition) {
-      throw new LakeStorageError18(`[SixbDuckLake] Unknown SQL transform source dataset '${dataset.id}'.`);
+      throw new LakeStorageError19(`[SixbDuckLake] Unknown SQL transform source dataset '${dataset.id}'.`);
     }
     return definition;
   }
   async resolveTargetDataset(runtime, dataset) {
     const definition = await this.datasets.getDatasetOnRuntime(runtime, dataset.id);
     if (!definition) {
-      throw new LakeStorageError18(`[SixbDuckLake] Unknown SQL transform target dataset '${dataset.id}'.`);
+      throw new LakeStorageError19(`[SixbDuckLake] Unknown SQL transform target dataset '${dataset.id}'.`);
     }
     this.datasets.assertSchema(definition);
     return definition;
@@ -2748,7 +2867,7 @@ class DuckLakeSqlExecutor {
     return checkedCasts;
   }
   async applySqlTransform(input) {
-    const tempTableName = `sixb_sql_transform_${randomUUID3().replaceAll("-", "")}`;
+    const tempTableName = `sixb_sql_transform_${randomUUID4().replaceAll("-", "")}`;
     const tempTable = quoteIdentifier(tempTableName);
     await input.runtime.run(`CREATE TEMP TABLE ${tempTable} AS SELECT * FROM (${input.sql}) AS sixb_sql_transform_result`);
     let result;
@@ -2819,33 +2938,33 @@ function normalizePreviewValue(value) {
   return value;
 }
 function throwNoCommittedSourceVersion(datasetId) {
-  throw new LakeStorageError18(`[SixbDuckLake] No committed version found for SQL transform source dataset '${datasetId}'.`);
+  throw new LakeStorageError19(`[SixbDuckLake] No committed version found for SQL transform source dataset '${datasetId}'.`);
 }
 function throwResultSchemaMismatch(datasetId, detail) {
-  throw new LakeStorageError18(`[SixbDuckLake] SQL transform result schema does not match target dataset '${datasetId}': ${detail}.`);
+  throw new LakeStorageError19(`[SixbDuckLake] SQL transform result schema does not match target dataset '${datasetId}': ${detail}.`);
 }
 
 // src/internal/ducklake-write-coordinator.ts
-import { randomUUID as randomUUID6 } from "crypto";
+import { randomUUID as randomUUID7 } from "crypto";
 import {
   assertUnsequencedDatasetWrite,
   getDatasetPrimaryKeyColumns as getDatasetPrimaryKeyColumns4,
   hasDatasetInputChanges,
   LakeConcurrencyError,
-  LakeStorageError as LakeStorageError22,
+  LakeStorageError as LakeStorageError23,
   retryDatasetMergeCommit
 } from "@sixb/core/lake-storage";
 
 // src/internal/dataset-row-merge.ts
 import {
   getDatasetPrimaryKeyColumns as getDatasetPrimaryKeyColumns2,
-  LakeStorageError as LakeStorageError19,
+  LakeStorageError as LakeStorageError20,
   reconcileDatasetSequences
 } from "@sixb/core/lake-storage";
 async function applyDatasetMergeFromRelation(input) {
   const primaryKeyColumns = getDatasetPrimaryKeyColumns2(input.dataset);
   if (primaryKeyColumns === null) {
-    throw new LakeStorageError19(`[SixbDuckLake] Dataset '${input.dataset.id}' must define a primaryKey before it can be merged.`);
+    throw new LakeStorageError20(`[SixbDuckLake] Dataset '${input.dataset.id}' must define a primaryKey before it can be merged.`);
   }
   const stagingTable = quoteIdentifier(input.stagingTableName);
   const targetTable = qualifiedTableName(input.options, encodeDatasetTableName(input.dataset.id));
@@ -3006,7 +3125,7 @@ function finalChangesSelectSql(input, primaryKeyColumns) {
 async function countMergeEffects(input, targetTable, finalChanges, primaryKeyColumns) {
   const matchColumn = primaryKeyColumns[0];
   if (matchColumn === undefined) {
-    throw new LakeStorageError19(`[SixbDuckLake] Dataset '${input.dataset.id}' primaryKey must contain at least one column.`);
+    throw new LakeStorageError20(`[SixbDuckLake] Dataset '${input.dataset.id}' primaryKey must contain at least one column.`);
   }
   const keyMatchSql = primaryKeyMatchSql(primaryKeyColumns, "target", "source");
   const targetMatch = `target.${quoteIdentifier(matchColumn)} IS NOT NULL`;
@@ -3055,12 +3174,12 @@ function sameColumns(left, right) {
 }
 
 // src/internal/ducklake-merge-session.ts
-import { randomUUID as randomUUID4 } from "crypto";
+import { randomUUID as randomUUID5 } from "crypto";
 import {
   cloneDatasetMergeChange,
   datasetSequenceChange,
   getDatasetMergeChangeValidationError,
-  LakeStorageError as LakeStorageError20
+  LakeStorageError as LakeStorageError21
 } from "@sixb/core/lake-storage";
 
 // src/internal/row-appender.ts
@@ -3119,7 +3238,7 @@ function fileRefToDuckDbStruct(fileRef) {
 // src/internal/ducklake-merge-session.ts
 var MERGE_CHANGE_BATCH_SIZE = 1000;
 async function createDuckLakeMergeSession(input) {
-  const suffix = randomUUID4().replaceAll("-", "");
+  const suffix = randomUUID5().replaceAll("-", "");
   const stagingTableName = `sixb_merge_${suffix}`;
   const sequenceColumnName = `sixb_merge_sequence_${suffix}`;
   const kindColumnName = `sixb_merge_kind_${suffix}`;
@@ -3161,7 +3280,7 @@ class DuckLakeMergeSession {
     for await (const change of changes) {
       const validationError = getDatasetMergeChangeValidationError(change, this.input.dataset);
       if (validationError) {
-        throw new LakeStorageError20(`[SixbDuckLake] ${validationError}`);
+        throw new LakeStorageError21(`[SixbDuckLake] ${validationError}`);
       }
       batch.push({
         sequence: this.nextSequence,
@@ -3224,7 +3343,7 @@ class DuckLakeMergeSession {
   }
   assertOpen() {
     if (this.closed) {
-      throw new LakeStorageError20("[SixbDuckLake] Merge session is already closed.");
+      throw new LakeStorageError21("[SixbDuckLake] Merge session is already closed.");
     }
   }
   async cleanup() {
@@ -3239,16 +3358,16 @@ class DuckLakeMergeSession {
 }
 
 // src/internal/ducklake-write-session.ts
-import { randomUUID as randomUUID5 } from "crypto";
+import { randomUUID as randomUUID6 } from "crypto";
 import { getDatasetRowValidationError } from "@sixb/core";
 import {
   encodeDatasetPrimaryKey,
   getDatasetPrimaryKeyColumns as getDatasetPrimaryKeyColumns3,
-  LakeStorageError as LakeStorageError21
+  LakeStorageError as LakeStorageError22
 } from "@sixb/core/lake-storage";
 var WRITE_ROW_BATCH_SIZE = 1000;
 async function createDuckLakeWriteSession(input) {
-  const stagingTableName = `sixb_write_${randomUUID5().replaceAll("-", "")}`;
+  const stagingTableName = `sixb_write_${randomUUID6().replaceAll("-", "")}`;
   await input.runtime.run(`CREATE TEMP TABLE ${quoteIdentifier(stagingTableName)} (${datasetSchemaToDuckDbColumnsSql(input.write.dataset.schema)})`);
   return new DuckLakeWriteSession(input.commitWrite, input.runtime, input.write, stagingTableName);
 }
@@ -3275,13 +3394,13 @@ class DuckLakeWriteSession {
     for await (const row of rows) {
       const validationError = getDatasetRowValidationError(row, this.input.dataset);
       if (validationError) {
-        throw new LakeStorageError21(`[SixbDuckLake] ${validationError}`);
+        throw new LakeStorageError22(`[SixbDuckLake] ${validationError}`);
       }
       const clonedRow = structuredClone(row);
       if (getDatasetPrimaryKeyColumns3(this.input.dataset) !== null) {
         const primaryKey = encodeDatasetPrimaryKey(this.input.dataset, clonedRow);
         if (this.stagedPrimaryKeys.has(primaryKey) || batchPrimaryKeys.has(primaryKey)) {
-          throw new LakeStorageError21(`[SixbDuckLake] Dataset '${this.input.dataset.id}' ${this.input.mode ?? "snapshot"} source contains duplicate primary key.`);
+          throw new LakeStorageError22(`[SixbDuckLake] Dataset '${this.input.dataset.id}' ${this.input.mode ?? "snapshot"} source contains duplicate primary key.`);
         }
         batchPrimaryKeys.add(primaryKey);
       }
@@ -3338,7 +3457,7 @@ class DuckLakeWriteSession {
   }
   assertOpen() {
     if (this.closed) {
-      throw new LakeStorageError21("[SixbDuckLake] Write session is already closed.");
+      throw new LakeStorageError22("[SixbDuckLake] Write session is already closed.");
     }
   }
   async cleanup() {
@@ -3371,7 +3490,7 @@ class DuckLakeWriteCoordinator {
     this.connections.assertOpen();
     const definition = await this.datasets.getDataset(input.dataset.id);
     if (!definition) {
-      throw new LakeStorageError22(`[SixbDuckLake] Unknown dataset '${input.dataset.id}'.`);
+      throw new LakeStorageError23(`[SixbDuckLake] Unknown dataset '${input.dataset.id}'.`);
     }
     this.datasets.assertSchema(definition);
     assertUnsequencedDatasetWrite(definition);
@@ -3392,13 +3511,13 @@ class DuckLakeWriteCoordinator {
     this.connections.assertOpen();
     const definition = await this.datasets.getDataset(input.dataset.id);
     if (!definition) {
-      throw new LakeStorageError22(`[SixbDuckLake] Unknown dataset '${input.dataset.id}'.`);
+      throw new LakeStorageError23(`[SixbDuckLake] Unknown dataset '${input.dataset.id}'.`);
     }
     if (getDatasetPrimaryKeyColumns4(definition) === null) {
-      throw new LakeStorageError22(`[SixbDuckLake] Dataset '${definition.id}' must define a primaryKey before it can be merged.`);
+      throw new LakeStorageError23(`[SixbDuckLake] Dataset '${definition.id}' must define a primaryKey before it can be merged.`);
     }
     this.datasets.assertSchema(definition);
-    const latestVersion = await this.connections.withAttachedRuntime((runtime2) => this.snapshots.getLatestVersionForDefinition(runtime2, definition));
+    const latestVersion = await this.connections.withAttachedRuntime((runtime) => this.snapshots.getLatestVersionForDefinition(runtime, definition));
     if (input.expectedLatestVersionId !== undefined && latestVersion?.versionId !== input.expectedLatestVersionId) {
       throw new LakeConcurrencyError(`[SixbDuckLake] Optimistic merge start failed for dataset '${definition.id}': expected latest version '${input.expectedLatestVersionId}', found '${latestVersion?.versionId ?? "none"}'.`);
     }
@@ -3413,7 +3532,7 @@ class DuckLakeWriteCoordinator {
   async commitWrite(input) {
     const definition = await this.datasets.getDataset(input.write.dataset.id);
     if (!definition) {
-      throw new LakeStorageError22(`[SixbDuckLake] Unknown dataset '${input.write.dataset.id}'.`);
+      throw new LakeStorageError23(`[SixbDuckLake] Unknown dataset '${input.write.dataset.id}'.`);
     }
     const mode = input.write.mode ?? "snapshot";
     assertDatasetWriteMode(mode, "write");
@@ -3434,10 +3553,10 @@ class DuckLakeWriteCoordinator {
   async commitMerge(input) {
     const definition = await this.datasets.getDataset(input.merge.dataset.id);
     if (!definition) {
-      throw new LakeStorageError22(`[SixbDuckLake] Unknown dataset '${input.merge.dataset.id}'.`);
+      throw new LakeStorageError23(`[SixbDuckLake] Unknown dataset '${input.merge.dataset.id}'.`);
     }
     if (getDatasetPrimaryKeyColumns4(definition) === null) {
-      throw new LakeStorageError22(`[SixbDuckLake] Dataset '${definition.id}' must define a primaryKey before it can be merged.`);
+      throw new LakeStorageError23(`[SixbDuckLake] Dataset '${definition.id}' must define a primaryKey before it can be merged.`);
     }
     return retryDatasetMergeCommit(input.merge, input.commit, (rebase) => this.withCommitRuntime(async (runtime) => {
       input.commit?.signal?.throwIfAborted();
@@ -3465,7 +3584,7 @@ class DuckLakeWriteCoordinator {
             validatedPrimaryKeyColumns: context.validatedPrimaryKeyColumns
           });
           if (result.sourceRowCount !== input.changesWritten) {
-            throw new LakeStorageError22(`[SixbDuckLake] Staged merge for dataset '${definition.id}' accepted ${input.changesWritten} change(s), but DuckLake saw ${result.sourceRowCount} source change(s) at commit time.`);
+            throw new LakeStorageError23(`[SixbDuckLake] Staged merge for dataset '${definition.id}' accepted ${input.changesWritten} change(s), but DuckLake saw ${result.sourceRowCount} source change(s) at commit time.`);
           }
           return result;
         }
@@ -3487,7 +3606,7 @@ class DuckLakeWriteCoordinator {
       disableRetries: input.mode === "append" && getDatasetPrimaryKeyColumns4(input.dataset) !== null
     });
     if (result.version === null) {
-      throw new LakeStorageError22(`[SixbDuckLake] No DuckLake changes were committed for dataset '${input.dataset.id}', and no previous version exists.`);
+      throw new LakeStorageError23(`[SixbDuckLake] No DuckLake changes were committed for dataset '${input.dataset.id}', and no previous version exists.`);
     }
     return { ...result.version, outcome: result.outcome };
   }
@@ -3536,7 +3655,7 @@ class DuckLakeWriteCoordinator {
       });
       input.signal?.throwIfAborted();
       await this.ensureNoOpHasSnapshot(input, changeResult, latestVersion);
-      const commitId = randomUUID6();
+      const commitId = randomUUID7();
       await this.setCommitMetadata(input, commitId, commitRowCount(input, changeResult, latestVersion));
       await input.runtime.run("COMMIT");
       committed = true;
@@ -3569,7 +3688,7 @@ class DuckLakeWriteCoordinator {
       if (version) {
         return { outcome: "created", version };
       }
-      throw new LakeStorageError22(`[SixbDuckLake] DuckLake committed snapshot '${ownSnapshotId}' for dataset '${input.dataset.id}', but Sixb could not hydrate it as a dataset version.`);
+      throw new LakeStorageError23(`[SixbDuckLake] DuckLake committed snapshot '${ownSnapshotId}' for dataset '${input.dataset.id}', but Sixb could not hydrate it as a dataset version.`);
     }
     if (!input.changeResult.dataChangeExpected) {
       const version = await this.versionForNoOpCommit(input.runtime, input.dataset, input.allowInitialNoOp ?? false);
@@ -3587,9 +3706,9 @@ class DuckLakeWriteCoordinator {
       };
     }
     if (input.committedWriteSnapshotId === input.previousWriteSnapshotId) {
-      throw new LakeStorageError22(`[SixbDuckLake] DuckLake commit for dataset '${input.dataset.id}' completed without producing a snapshot for this non-empty write.`);
+      throw new LakeStorageError23(`[SixbDuckLake] DuckLake commit for dataset '${input.dataset.id}' completed without producing a snapshot for this non-empty write.`);
     }
-    throw new LakeStorageError22(`[SixbDuckLake] DuckLake commit for dataset '${input.dataset.id}' completed, but Sixb could not find a matching snapshot for this write.`);
+    throw new LakeStorageError23(`[SixbDuckLake] DuckLake commit for dataset '${input.dataset.id}' completed, but Sixb could not find a matching snapshot for this write.`);
   }
   async applyStagedRows(input) {
     const mode = input.write.mode ?? "snapshot";
@@ -3602,7 +3721,7 @@ class DuckLakeWriteCoordinator {
       previousRowCount: input.previousRowCount
     });
     if (result.sourceRowCount !== input.rowsWritten) {
-      throw new LakeStorageError22(`[SixbDuckLake] Staged write for dataset '${input.write.dataset.id}' accepted ${input.rowsWritten} row(s), but DuckLake saw ${result.sourceRowCount} source row(s) at commit time.`);
+      throw new LakeStorageError23(`[SixbDuckLake] Staged write for dataset '${input.write.dataset.id}' accepted ${input.rowsWritten} row(s), but DuckLake saw ${result.sourceRowCount} source row(s) at commit time.`);
     }
     return result;
   }
@@ -3640,7 +3759,7 @@ class DuckLakeWriteCoordinator {
     if (allowInitialNoOp) {
       return null;
     }
-    throw new LakeStorageError22(`[SixbDuckLake] No DuckLake changes were committed for dataset '${definition.id}', and no previous version exists.`);
+    throw new LakeStorageError23(`[SixbDuckLake] No DuckLake changes were committed for dataset '${definition.id}', and no previous version exists.`);
   }
   async rollbackTransaction(runtime) {
     try {
@@ -3714,7 +3833,7 @@ function commitRowCount(input, changeResult, latestVersion) {
 }
 function assertDuckLakeSnapshotId3(snapshotId) {
   if (!/^\d+$/.test(snapshotId)) {
-    throw new LakeStorageError22(`[SixbDuckLake] Invalid DuckLake snapshot id '${snapshotId}'.`);
+    throw new LakeStorageError23(`[SixbDuckLake] Invalid DuckLake snapshot id '${snapshotId}'.`);
   }
 }
 var localCatalogCommitLocks = new Map;
@@ -3726,8 +3845,8 @@ async function withCatalogCommitLock(options, run) {
   const previous = localCatalogCommitLocks.get(key) ?? Promise.resolve();
   const ready = previous.catch(() => {});
   let release;
-  const next = new Promise((resolve2) => {
-    release = resolve2;
+  const next = new Promise((resolve) => {
+    release = resolve;
   });
   const current = ready.then(() => next);
   localCatalogCommitLocks.set(key, current);
@@ -3750,6 +3869,7 @@ class DuckLakeStorage {
   datasets;
   maintenance;
   rows;
+  changes;
   snapshotReader;
   writes;
   constructor(options) {
@@ -3768,6 +3888,7 @@ class DuckLakeStorage {
     this.maintenance = new DuckLakeMaintenance(normalizedOptions, this.connections);
     this.snapshotReader = new DuckLakeSnapshotReader(normalizedOptions, this.connections, this.datasets);
     this.rows = new DuckLakeRowReader(normalizedOptions, this.connections, this.snapshotReader);
+    this.changes = new DuckLakeChangeReader(normalizedOptions, this.connections, this.snapshotReader);
     this.writes = new DuckLakeWriteCoordinator(normalizedOptions, this.connections, this.datasets, this.snapshotReader);
     this.sql = new DuckLakeSqlExecutor(normalizedOptions, this.connections, this.datasets, this.snapshotReader, this.writes);
   }
@@ -3804,6 +3925,9 @@ class DuckLakeStorage {
   readRows(input) {
     return this.rows.readRows(input);
   }
+  readChanges(input) {
+    return this.changes.readChanges(input);
+  }
   async runMaintenance(options) {
     return this.maintenance.runMaintenance(options);
   }
@@ -3815,4 +3939,4 @@ export {
   DuckLakeStorage
 };
 
-//# debugId=2A2E6355256FAE5864756E2164756E21
+//# debugId=555594FFA13F16F264756E2164756E21