@sixb/core 0.1.6 → 0.1.8

package/src/index.ts

@@ -9,6 +9,10 @@ export type {
   InferSchemaOrRef,
   Interface,
   LinkCardinality,
+  LinkPathSelection,
+  LinkPathSelectionBuilder,
+  LinkPathSelectionInput,
+  LinkPathSelectionMode,
   LinkToken,
   LinkTokenMap,
   MapSchema,
@@ -47,6 +51,7 @@ export {
   isObjectRefSchema,
   link,
   OntologyRegistry,
+  objectRef,
   prop,
   ref,
   stringEnum,
@@ -427,10 +432,28 @@ export {
   resolveAuthorizationContext,
 } from "./authorization"
 
+// ── AI usage ───────────────────────────────────────────────
+
+export type {
+  AiUsageLimitGroupOption,
+  AiUsageLimitServiceAccountOption,
+  AiUsageLimitSubjectOptions,
+  AiUsageLimitUserOption,
+  AiUsageRuntime,
+  CreateAiUsageLimitPolicyInput,
+  ListAiUsageLimitPoliciesInput,
+  ListAiUsageLimitStatusesInput,
+  ListAiUsageModelCallGroupsInput,
+  ListAiUsageModelCallsInput,
+  QueryAiUsageOverviewInput,
+  UpdateAiUsageLimitPolicyInput,
+} from "./ai-usage"
+
 // ── Security Definitions ───────────────────────────────────
 
 export type {
   AccessGrant,
+  AgentRunGrant,
   AppendGrant,
   ApplicationDefinition,
   ApplyGrant,
@@ -445,6 +468,7 @@ export type {
   GroupDefinition,
   GroupReference,
   ManageGrant,
+  ManageGrantTarget,
   MembershipOperation,
   MembershipPolicyDefinition,
   ObserveGrant,
@@ -455,6 +479,7 @@ export type {
   RunGrantTarget,
   SecurityDefinitionCatalog,
   Selection,
+  ShareGrant,
   ViewGrant,
   ViewGrantTarget,
 } from "./security"
@@ -468,6 +493,29 @@ export {
   SecurityValidationError,
 } from "./security"
 
+// ── Shares ────────────────────────────────────────────────
+
+export type {
+  DefineShareOptions,
+  IssueSharedAccessByIdInput,
+  IssueSharedAccessInput,
+  ListSharedAccessByIdInput,
+  ListSharedAccessInput,
+  ShareActionGrant,
+  ShareActionGrantBuilder,
+  ShareDefinition,
+  SharedAccessGrant,
+  SharedAccessGrantListResult,
+  SharedAccessInvitation,
+  ShareErrorReason,
+  ShareScopeGrant,
+  SharesRuntime,
+  ShareTarget,
+  ShareViewGrant,
+  ShareViewGrantBuilder,
+} from "./shares"
+export { defineShare, ShareDefinitionError, ShareError } from "./shares"
+
 // ── Storage ────────────────────────────────────────────────
 // Config contract + operator migration API + in-memory dev providers.
 // The full storage-provider contract lives at `@sixb/core/storage`.
@@ -748,6 +796,7 @@ export type {
   AgentStepPrompt,
   AgentStepPromptBuilder,
   AgentStepPromptContext,
+  DefineAgentStepConfig,
   InferAgentStepInput,
   InferAgentStepOutput,
   InferInterventionInput,
@@ -827,14 +876,14 @@ export type { ActionRunsRuntime, ActionsRuntime } from "./actions/execution"
 export type {
   AgentRunListResult,
   AgentRunsRuntime,
+  AgentRuntime,
   AgentRunView,
-  AgentsRuntime,
   AgentThreadsRuntime,
   ExecutionAgentRunResult,
 } from "./agents/execution"
 export type { BlobsRuntime } from "./blob-storage/execution"
 export type { ConnectorRuntime } from "./connectors/execution"
-export type { DatasetsRuntime } from "./datasets/execution"
+export type { DatasetIngestInput, DatasetIngestResult, DatasetsRuntime } from "./datasets/execution"
 export type {
   SixbActionPhaseFailedContext,
   SixbErrorContext,
@@ -857,6 +906,12 @@ export type {
   OntologyOperationalStatus,
   SixbReadiness,
 } from "./maintenance"
+export type {
+  LanguageModel,
+  LanguageModelDefinition,
+  LanguageModelRateCard,
+  ProviderData,
+} from "./models"
 export type {
   ExecutionObjectByIdHandle,
   ExecutionObjectSet,
@@ -949,32 +1004,23 @@ export type {
 // ── Agents ──────────────────────────────────────────────────
 
 export type {
-  AgentContextConfig,
   AgentContextEntryInput,
   AgentContextInput,
   AgentContextOrigin,
   AgentContextPart,
-  AgentDefinition,
+  AgentDescriptor,
   AgentFileDataProjection,
   AgentFileDataResolverInput,
   AgentFilePart,
-  AgentInboundUiMessage,
-  AgentInboundUiMessagePart,
-  AgentLoopConfig,
   AgentMessage,
   AgentMessagePart,
   AgentMessagePartType,
   AgentMessageRole,
-  AgentModelAssistantPart,
-  AgentModelFilePart,
-  AgentModelMessage,
-  AgentModelReasoningPart,
-  AgentModelTextPart,
-  AgentModelToolCallPart,
-  AgentModelToolOutput,
-  AgentModelToolResultPart,
+  AgentProviderStatePart,
+  AgentReasoning,
   AgentReasoningLevel,
   AgentReasoningPart,
+  AgentReference,
   AgentRequestErrorCode,
   AgentStepStartPart,
   AgentTextPart,
@@ -983,6 +1029,7 @@ export type {
   AgentToolArtifacts,
   AgentToolCallPart,
   AgentToolCallState,
+  AgentToolCatalog,
   AgentToolContent,
   AgentToolDefinition,
   AgentToolDescriptionBuilder,
@@ -997,10 +1044,7 @@ export type {
   AgentToolRunContext,
   AgentToolRunInfo,
   AgentToolTextContent,
-  AgentUiMessage,
-  AgentUiMessagePart,
-  AgentUiToolPart,
-  DefineAgentConfig,
+  AgentUsageReference,
   InferAgentToolInput,
   InferAgentToolInputSchema,
   RequestAgentRunInput,
@@ -1011,22 +1055,23 @@ export {
   AgentDefinitionError,
   AgentRequestError,
   AgentToolPublicError,
+  agent,
   agentContext,
   agentContextIdentity,
-  defineAgent,
   defineAgentTool,
-  isAgentDefinition,
   MAX_AGENT_APP_STATE_ENTRY_BYTES,
   MAX_AGENT_APP_STATE_TOTAL_BYTES,
   MAX_AGENT_CONTEXT_ENTRIES,
   requestAgentRun,
 } from "./agents"
+export type { AgentThreadRecord, ListAgentThreadsResult } from "./storage/agents"
 
 // ── Models ──────────────────────────────────────────────────
 
 export type {
   LanguageModelCatalog,
   LanguageModelEntry,
+  LanguageModelRef,
   ModelCatalog,
   ModelCatalogInput,
 } from "./models"
@@ -1037,6 +1082,12 @@ export { CronValidationError } from "./schedules"
 
 // ── Projections ─────────────────────────────────────────────
 
+export type {
+  ActionDescriptor,
+  ActionDescriptorBinding,
+  ActionParamDescriptor,
+  ActionPhaseDescriptor,
+} from "./actions/descriptor"
 export type {
   ForeignKeyDescriptor,
   LinkProjectionDefinition,
@@ -1054,7 +1105,6 @@ export type {
   TelemetryProjectionDefinition,
   TelemetryProjectionPropertyMapping,
 } from "./projections"
-
 export {
   defineProjection,
   fromForeignKey,

package/src/json.ts

@@ -21,6 +21,15 @@ export function assertJsonValue(value: unknown, label = "value"): asserts value
   }
 }
 
+export function isJsonObject(value: unknown): value is JsonObject {
+  return isPlainRecord(value) && isJsonValue(value)
+}
+
+export function assertJsonObject(value: unknown, label = "value"): asserts value is JsonObject {
+  assertJsonValue(value, label)
+  if (!isPlainRecord(value)) throw new Error(`[Sixb] ${label} must be a JSON object.`)
+}
+
 export function cloneJsonValue(value: ReadonlyJsonValue, label = "value"): JsonValue {
   assertJsonValue(value, label)
   return JSON.parse(JSON.stringify(value)) as JsonValue

package/src/lake-storage/definition-updates.ts

@@ -1,4 +1,5 @@
 import type { DatasetColumnDefinition, DatasetDefinition } from "../datasets"
+import { assertDatasetDefinition } from "../datasets/validation"
 import { LakeStorageError } from "./errors"
 import type { LakeStorage } from "./types"
 
@@ -36,6 +37,12 @@ export function planDatasetDefinitionUpdate(
   requested: DatasetDefinition
 ): DatasetDefinitionUpdatePlan {
   assertSameDataset(existing, requested)
+  assertDatasetDefinition(requested, (message) => new LakeStorageError(`[SixbLake] ${message}`))
+  if (existing.sequenceBy !== requested.sequenceBy) {
+    throw new LakeStorageError(
+      `[SixbLake] Dataset '${requested.id}' sequenceBy is immutable. Create a new dataset and backfill to adopt or change source ordering.`
+    )
+  }
   assertPrimaryKeyUnchanged(existing, requested)
 
   const addedColumns = getAddedColumnsAfterValidatingExistingColumns(existing, requested)
@@ -66,6 +73,7 @@ export function mergeStrictDatasetDefinition(options: {
   readonly existing?: DatasetDefinition | null
   readonly next: DatasetDefinition
 }): DatasetDefinition {
+  assertDatasetDefinition(options.next, (message) => new LakeStorageError(`[SixbLake] ${message}`))
   if (!options.existing) {
     return structuredClone(options.next)
   }
@@ -221,6 +229,7 @@ function mergeDatasetDefinition(
     id: requested.id,
     schema: { columns },
     ...(primaryKey !== undefined ? { primaryKey: structuredClone(primaryKey) } : {}),
+    ...(existing.sequenceBy !== undefined ? { sequenceBy: existing.sequenceBy } : {}),
     ...(partitionBy !== undefined ? { partitionBy: [...partitionBy] } : {}),
     ...(description !== undefined ? { description } : {}),
   }

package/src/lake-storage/errors.ts

@@ -2,5 +2,10 @@
  * Error for lake-storage invariants and invalid lake operations.
  */
 export class LakeStorageError extends Error {
-  readonly name = "LakeStorageError"
+  readonly name: string = "LakeStorageError"
+}
+
+/** A known, uncommitted version/transaction conflict; safe to retry staged changes. */
+export class LakeConcurrencyError extends LakeStorageError {
+  override readonly name = "LakeConcurrencyError"
 }

package/src/lake-storage/in-memory.ts

@@ -2,19 +2,26 @@ import { randomUUID } from "node:crypto"
 import type { DatasetDefinition, DatasetSchema, MergeChange } from "../datasets"
 import { getDatasetRowValidationError } from "../datasets/validation"
 import { mergeStrictDatasetDefinition } from "./definition-updates"
-import { LakeStorageError } from "./errors"
+import { LakeConcurrencyError, LakeStorageError } from "./errors"
 import type {
   BeginDatasetMergeInput,
   CommitDatasetMergeInput,
   DatasetMergeCommitResult,
   LakeMergeSession,
 } from "./merge"
+import { retryDatasetMergeCommit } from "./merge"
 import {
   cloneDatasetMergeChange,
   encodeDatasetPrimaryKey,
   getDatasetMergeChangeValidationError,
   getDatasetPrimaryKeyColumns,
 } from "./merge-validation"
+import {
+  assertUnsequencedDatasetWrite,
+  type DatasetSequenceState,
+  datasetSequenceChange,
+  reconcileDatasetSequences,
+} from "./source-ordering"
 import type {
   BeginDatasetWriteInput,
   CommitDatasetWriteInput,
@@ -27,6 +34,7 @@ import type {
   LakeWriteSession,
   ReadDatasetRowsInput,
 } from "./types"
+import { hasDatasetInputChanges } from "./version-inputs"
 
 function cloneDatasetDefinition(definition: DatasetDefinition): DatasetDefinition {
   return structuredClone(definition)
@@ -177,12 +185,16 @@ class InMemoryLakeMergeSession implements LakeMergeSession {
   async commit(input?: CommitDatasetMergeInput): Promise<DatasetMergeCommitResult> {
     this.assertOpen()
     this.closed = true
-    return this.storage.commitMerge({
-      merge: this.input,
-      baseVersionId: this.baseVersionId,
-      changes: this.changes,
-      commit: input,
-    })
+    return retryDatasetMergeCommit(this.input, input, async (rebase) =>
+      this.storage.commitMerge({
+        merge: this.input,
+        baseVersionId: rebase
+          ? ((await this.storage.getLatestVersion(this.input.dataset.id))?.versionId ?? null)
+          : this.baseVersionId,
+        changes: this.changes,
+        commit: input,
+      })
+    )
   }
 
   async abort(): Promise<void> {
@@ -201,6 +213,7 @@ export class InMemoryLakeStorage implements LakeStorage {
   private readonly datasets = new Map<string, DatasetDefinition>()
   private readonly versionsByDataset = new Map<string, DatasetVersion[]>()
   private readonly rowsByVersionId = new Map<string, readonly DatasetRow[]>()
+  private readonly sequencesByVersionId = new Map<string, Map<string, DatasetSequenceState>>()
   private readonly latestVersionIdByDataset = new Map<string, string>()
   private readonly commitLocks = new Map<string, Promise<void>>()
 
@@ -295,6 +308,7 @@ export class InMemoryLakeStorage implements LakeStorage {
       throw new LakeStorageError(`[LakeStorage] Unknown dataset '${input.dataset.id}'`)
     }
 
+    assertUnsequencedDatasetWrite(definition)
     return new InMemoryLakeWriteSession(this, {
       ...input,
       dataset: definition,
@@ -318,7 +332,7 @@ export class InMemoryLakeStorage implements LakeStorage {
       input.expectedLatestVersionId !== undefined &&
       latestVersion?.versionId !== input.expectedLatestVersionId
     ) {
-      throw new LakeStorageError(
+      throw new LakeConcurrencyError(
         `[LakeStorage] Optimistic merge start failed for dataset '${definition.id}': expected latest version '${input.expectedLatestVersionId}', found '${latestVersion?.versionId ?? "none"}'`
       )
     }
@@ -398,9 +412,10 @@ export class InMemoryLakeStorage implements LakeStorage {
       }
 
       const latestVersion = await this.getLatestVersion(options.merge.dataset.id)
+      options.commit?.signal?.throwIfAborted()
       const actualVersionId = latestVersion?.versionId ?? null
       if (actualVersionId !== options.baseVersionId) {
-        throw new LakeStorageError(
+        throw new LakeConcurrencyError(
           `[LakeStorage] Optimistic merge commit failed for dataset '${options.merge.dataset.id}': expected latest version '${options.baseVersionId ?? "none"}', found '${actualVersionId ?? "none"}'`
         )
       }
@@ -408,9 +423,21 @@ export class InMemoryLakeStorage implements LakeStorage {
       const previousRows = this.rowsByVersionId.get(latestVersion?.versionId ?? "") ?? []
       const previousByKey = this.rowsByPrimaryKey(previousRows, definition)
       const finalChanges = new Map<string, MergeChange<DatasetRow, DatasetRow>>()
-      for (const change of options.changes) {
-        const value = change.kind === "upsert" ? change.row : change.key
-        finalChanges.set(encodeDatasetPrimaryKey(definition, value), change)
+      const ordered =
+        definition.sequenceBy === undefined
+          ? undefined
+          : reconcileDatasetSequences(
+              definition,
+              this.sequencesByVersionId.get(actualVersionId ?? "") ?? new Map(),
+              options.changes.map((change) => datasetSequenceChange(definition, change))
+            )
+      if (ordered) {
+        for (const [key, index] of ordered.accepted) finalChanges.set(key, options.changes[index]!)
+      } else {
+        for (const change of options.changes) {
+          const value = change.kind === "upsert" ? change.row : change.key
+          finalChanges.set(encodeDatasetPrimaryKey(definition, value), change)
+        }
       }
 
       const nextByKey = new Map(previousByKey)
@@ -422,7 +449,13 @@ export class InMemoryLakeStorage implements LakeStorage {
         }
       }
 
-      if (this.sameKeyedRowContent(previousByKey, nextByKey, definition.schema)) {
+      const createInitialVersion = options.commit?.createInitialVersion && latestVersion === null
+      if (
+        !createInitialVersion &&
+        (ordered
+          ? ordered.accepted.size === 0
+          : this.sameKeyedRowContent(previousByKey, nextByKey, definition.schema))
+      ) {
         return {
           outcome: "unchanged",
           version: latestVersion ? cloneDatasetVersion(latestVersion) : null,
@@ -454,6 +487,7 @@ export class InMemoryLakeStorage implements LakeStorage {
         visibleRows.map((row) => cloneRow(row))
       )
       this.latestVersionIdByDataset.set(options.merge.dataset.id, versionId)
+      if (ordered) this.sequencesByVersionId.set(versionId, ordered.states)
 
       return { outcome: "created", version: cloneDatasetVersion(version) }
     })
@@ -470,13 +504,14 @@ export class InMemoryLakeStorage implements LakeStorage {
     }
 
     const mode = options.write.mode ?? "snapshot"
+    assertUnsequencedDatasetWrite(definition)
     const latestVersion = await this.getLatestVersion(options.write.dataset.id)
 
     if (options.commit?.expectedLatestVersionId !== undefined) {
-      const actual = latestVersion?.versionId
+      const actual = latestVersion?.versionId ?? null
       if (actual !== options.commit.expectedLatestVersionId) {
-        throw new LakeStorageError(
-          `[LakeStorage] Optimistic commit failed for dataset '${options.write.dataset.id}': expected latest version '${options.commit.expectedLatestVersionId}', found '${actual ?? "none"}'`
+        throw new LakeConcurrencyError(
+          `[LakeStorage] Optimistic commit failed for dataset '${options.write.dataset.id}': expected latest version '${options.commit.expectedLatestVersionId ?? "none"}', found '${actual ?? "none"}'`
         )
       }
     }
@@ -484,9 +519,10 @@ export class InMemoryLakeStorage implements LakeStorage {
     this.assertKeyedWriteIsUnique(mode, options.rows, latestVersion, definition)
 
     // Content-identical snapshots and empty appends reuse the latest version
-    // instead of creating a new one.
+    // unless explicitly supplied input lineage has changed.
     if (
       latestVersion &&
+      !hasDatasetInputChanges(latestVersion.inputs, options.write.inputs) &&
       this.isUnchangedWrite(mode, latestVersion, options.rows, definition.schema)
     ) {
       return { ...latestVersion, outcome: "unchanged" }

package/src/lake-storage/index.ts

@@ -6,6 +6,7 @@ export type {
   DatasetSchema,
   MergeChange,
 } from "../datasets"
+export { assertDatasetDefinition } from "../datasets/validation"
 export type { JsonValue } from "../json"
 export type {
   DatasetDefinitionUpdatePlan,
@@ -17,7 +18,7 @@ export {
   mergeStrictDatasetDefinition,
   planDatasetDefinitionUpdate,
 } from "./definition-updates"
-export { LakeStorageError } from "./errors"
+export { LakeConcurrencyError, LakeStorageError } from "./errors"
 export { InMemoryLakeStorage } from "./in-memory"
 export type {
   BeginDatasetMergeInput,
@@ -25,12 +26,19 @@ export type {
   DatasetMergeCommitResult,
   LakeMergeSession,
 } from "./merge"
+export { retryDatasetMergeCommit } from "./merge"
 export {
   cloneDatasetMergeChange,
   encodeDatasetPrimaryKey,
   getDatasetMergeChangeValidationError,
   getDatasetPrimaryKeyColumns,
 } from "./merge-validation"
+export type { DatasetSequenceChange, DatasetSequenceState } from "./source-ordering"
+export {
+  assertUnsequencedDatasetWrite,
+  datasetSequenceChange,
+  reconcileDatasetSequences,
+} from "./source-ordering"
 export type {
   ExecuteSqlTransformInput,
   LakeSqlExecutor,
@@ -60,3 +68,4 @@ export type {
   LakeWriteSession,
   ReadDatasetRowsInput,
 } from "./types"
+export { hasDatasetInputChanges } from "./version-inputs"

package/src/lake-storage/merge-validation.ts

@@ -1,5 +1,6 @@
 import type { DatasetDefinition, MergeChange } from "../datasets"
 import { getDatasetRowValidationError } from "../datasets"
+import { getDatasetSequenceValidationError } from "../datasets/sequence"
 import { isPlainRecord } from "../json"
 import { LakeStorageError } from "./errors"
 import type { DatasetRow } from "./types"
@@ -58,7 +59,11 @@ export function getDatasetMergeChangeValidationError(
     if (shapeError) {
       return shapeError
     }
-    return getDeleteKeyValidationError(change.key, dataset, primaryKeyColumns)
+    const keyError = getDeleteKeyValidationError(change.key, dataset, primaryKeyColumns)
+    if (keyError) return keyError
+    return dataset.sequenceBy === undefined
+      ? null
+      : getDatasetSequenceValidationError(dataset, change.sequence)
   }
 
   return `Dataset '${dataset.id}' merge change kind must be 'upsert' or 'delete'.`
@@ -70,7 +75,11 @@ export function cloneDatasetMergeChange(
 ): MergeChange<DatasetRow, DatasetRow> {
   return change.kind === "upsert"
     ? { kind: "upsert", row: structuredClone(change.row) }
-    : { kind: "delete", key: structuredClone(change.key) }
+    : {
+        kind: "delete",
+        key: structuredClone(change.key),
+        ...(change.sequence !== undefined ? { sequence: structuredClone(change.sequence) } : {}),
+      }
 }
 
 function getChangeShapeError(
@@ -79,6 +88,7 @@ function getChangeShapeError(
   payloadField: "row" | "key"
 ): string | null {
   const allowedFields = new Set(["kind", payloadField])
+  if (payloadField === "key" && dataset.sequenceBy !== undefined) allowedFields.add("sequence")
   for (const field of Object.keys(change)) {
     if (!allowedFields.has(field)) {
       return `Dataset '${dataset.id}' ${change.kind as string} change contains unknown field '${field}'.`

package/src/lake-storage/merge.ts

@@ -1,4 +1,5 @@
 import type { DatasetDefinition, MergeChange } from "../datasets"
+import { LakeConcurrencyError } from "./errors"
 import type { DatasetProducer, DatasetRow, DatasetVersion, DatasetVersionRef } from "./types"
 
 export interface BeginDatasetMergeInput {
@@ -12,6 +13,40 @@ export interface BeginDatasetMergeInput {
 
 export interface CommitDatasetMergeInput {
   readonly commitMessage?: string
+  /** Create an addressable first version even without changes; reuse an existing version on no-op. */
+  readonly createInitialVersion?: boolean
+  /** Retry sequenced merges up to three times total; ignored when an explicit version guard is set. */
+  readonly retryOnConflict?: boolean
+  /** Checked before each attempt; a durable commit is never cancelled retroactively. */
+  readonly signal?: AbortSignal
+}
+
+/** Providers retain their staging session throughout this bounded commit loop. */
+export async function retryDatasetMergeCommit(
+  merge: BeginDatasetMergeInput,
+  commit: CommitDatasetMergeInput | undefined,
+  run: (rebase: boolean) => Promise<DatasetMergeCommitResult>
+): Promise<DatasetMergeCommitResult> {
+  const attempts =
+    commit?.retryOnConflict &&
+    merge.dataset.sequenceBy !== undefined &&
+    merge.expectedLatestVersionId === undefined
+      ? 3
+      : 1
+  for (let attempt = 0; ; attempt += 1) {
+    commit?.signal?.throwIfAborted()
+    try {
+      return await run(attempt > 0)
+    } catch (error) {
+      if (!(error instanceof LakeConcurrencyError) || attempts === 1) throw error
+      if (attempt + 1 === attempts) {
+        throw new LakeConcurrencyError(
+          `[SixbLake] Dataset '${merge.dataset.id}' merge exhausted ${attempts} concurrency attempts. No changes from this operation were committed.`,
+          { cause: error }
+        )
+      }
+    }
+  }
 }
 
 /**
@@ -23,13 +58,16 @@ export type DatasetMergeCommitResult =
   | { readonly outcome: "unchanged"; readonly version: DatasetVersion | null }
 
 export interface LakeMergeSession {
-  /** Stage ordered complete-row upserts and exact primary-key deletes. */
+  /**
+   * Stage ordered complete-row upserts and exact primary-key deletes. With sequenceBy, deletes
+   * require a sequence, stale changes are ignored, and conflicting ties abort the whole merge.
+   */
   writeChanges(
     changes:
       | Iterable<MergeChange<DatasetRow, DatasetRow>>
       | AsyncIterable<MergeChange<DatasetRow, DatasetRow>>
   ): Promise<void>
-  /** Commit only if the latest version still matches the version captured when the session began. */
+  /** Commit against the captured version; opt-in retries rebase sequenced changes on a fresh head. */
   commit(input?: CommitDatasetMergeInput): Promise<DatasetMergeCommitResult>
   abort(): Promise<void>
 }