@sixb/core 0.1.9 → 0.1.11

package/src/connectors/connections/runs.ts

@@ -16,6 +16,7 @@ import {
 } from "./authorizations"
 import {
   assertConnectorConnectionRunInitiator,
+  isConnectorConnectionRunInitiator,
   requireConnectorConnectionCommandActor,
 } from "./command-context"
 import type {
@@ -207,6 +208,7 @@ export class ConnectorConnectionRunService {
         attempt,
         principal,
         code: nonblank(input.code, "OAuth authorization code", "connector.authorization_invalid"),
+        callbackParameters: input.callbackParameters,
         redirectUri,
         onAuthorizationPersisted: async (persisted) => {
           authorizationId = persisted.id
@@ -237,6 +239,42 @@ export class ConnectorConnectionRunService {
     }
   }
 
+  async listPending(
+    command: ConnectorConnectionCommandContext,
+    connectorId: string
+  ): Promise<readonly ConnectorConnectionRunView[]> {
+    const actor = requireConnectorConnectionCommandActor(command.execution, this.projectId)
+    const candidates = await withConnectorStorageBoundary(
+      "Pending connector connection runs could not be read.",
+      () =>
+        this.connectionStorage.listPendingConnectionRuns({ projectId: this.projectId, connectorId })
+    )
+    const runs: ConnectorConnectionRunView[] = []
+    for (const candidate of candidates) {
+      const initiating = await withConnectorStorageBoundary(
+        "Connector connection run initiating execution could not be read.",
+        () =>
+          this.storage.executions.getById({
+            projectId: this.projectId,
+            id: candidate.initiatedByExecutionId,
+          })
+      )
+      if (!isConnectorConnectionRunInitiator(initiating, actor)) continue
+      // Re-read through the normal expiry/cleanup path before exposing accounts.
+      const run = await this.get(command, connectorId, candidate.id)
+      if (
+        run &&
+        (run.status === "running" ||
+          (run.status === "waiting" && run.waitingFor === "account_selection"))
+      )
+        runs.push(run)
+    }
+    return runs.sort(
+      (left, right) =>
+        right.createdAt.getTime() - left.createdAt.getTime() || left.id.localeCompare(right.id)
+    )
+  }
+
   async get(
     command: ConnectorConnectionCommandContext,
     connectorId: string,
@@ -580,7 +618,6 @@ export class ConnectorConnectionRunService {
         status: "waiting",
         waitingFor: "account_selection",
         accounts: authorization.accounts,
-        expiresAt: run.expiresAt,
       }
     }
     if (run.status === "succeeded") {
@@ -644,6 +681,7 @@ export class ConnectorConnectionRunService {
       : CLEANUP_RETRY_DELAY_MS
   ): void {
     this.cancelRunMaintenance(run.id)
+    if (run.status === "waiting" && run.waitingFor === "account_selection") return
     const timer = setTimeout(
       () => void this.maintainRun(run.connectorId, run.id),
       Math.min(delayMs, MAX_TIMER_DELAY_MS)

package/src/connectors/connections/service.ts

@@ -66,6 +66,7 @@ export interface ConnectorConnectionServiceOptions {
   readonly storage?: Storage
   readonly credentialProtector?: ConnectorCredentialProtector
   readonly authorizationAttemptTtlMs?: number
+  /** @deprecated Selection no longer expires; retained for legacy storage metadata only. */
   readonly accountSelectionTtlMs?: number
   readonly credentialMutationLeaseMs?: number
   readonly providerOperationTimeoutMs?: number
@@ -322,6 +323,11 @@ export class ConnectorConnectionService implements ConnectorConnectionProcess {
     })
   }
 
+  listPendingConnectionRuns(command: ConnectorConnectionCommandContext, connectorId: string) {
+    this.requireOAuthDefinition(connectorId)
+    return this.runs.listPending(command, connectorId)
+  }
+
   getConnectionRun(
     command: ConnectorConnectionCommandContext,
     connectorId: string,

package/src/connectors/connections/tokens.ts

@@ -169,6 +169,10 @@ export class ConnectorTokenAccess {
                 ? { tokenType: current.tokenType }
                 : {}),
               scopes: refreshed.scopes ?? current.scopes ?? authorization.scopes,
+              ...(refreshed.authorizationContext === undefined &&
+              current.authorizationContext !== undefined
+                ? { authorizationContext: current.authorizationContext }
+                : {}),
             } satisfies ConnectorOAuthCredentials
             const envelope = await this.credentials.seal(
               definition.id,

package/src/connectors/connections/validation.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto"
+import { isJsonObject } from "../../json"
 import type { ConnectorAuthorizationRecord } from "../../storage"
 import { createConnectorCodedError } from "../errors"
 import type { ConnectorAccountCandidate, ConnectorOAuthCredentials } from "../types"
@@ -26,6 +27,7 @@ export function validateCredentials(
     tokenType?: string
     scopes?: string[]
     expiresAt?: Date
+    authorizationContext?: ConnectorOAuthCredentials["authorizationContext"]
   } = {
     accessToken: nonblank(
       credentials.accessToken,
@@ -76,6 +78,16 @@ export function validateCredentials(
     normalized.expiresAt = new Date(credentials.expiresAt)
   }
 
+  if (credentials.authorizationContext !== undefined) {
+    if (!isJsonObject(credentials.authorizationContext)) {
+      throw createConnectorCodedError(
+        "connector.adapter_invalid",
+        "OAuth connector adapter returned invalid authorization context; expected a JSON object."
+      )
+    }
+    normalized.authorizationContext = structuredClone(credentials.authorizationContext)
+  }
+
   return normalized
 }
 
@@ -135,6 +147,9 @@ export function serializeCredentials(credentials: ConnectorOAuthCredentials): st
     ...(credentials.expiresAt === undefined
       ? {}
       : { expiresAt: credentials.expiresAt.toISOString() }),
+    ...(credentials.authorizationContext === undefined
+      ? {}
+      : { authorizationContext: credentials.authorizationContext }),
   })
 }
 
@@ -160,7 +175,8 @@ export function parseCredentials(serialized: string): ConnectorOAuthCredentials
     (value.tokenType !== undefined && typeof value.tokenType !== "string") ||
     (value.scopes !== undefined &&
       (!Array.isArray(value.scopes) || value.scopes.some((scope) => typeof scope !== "string"))) ||
-    (value.expiresAt !== undefined && typeof value.expiresAt !== "string")
+    (value.expiresAt !== undefined && typeof value.expiresAt !== "string") ||
+    (value.authorizationContext !== undefined && !isJsonObject(value.authorizationContext))
   ) {
     throw createConnectorCodedError(
       "connector.credentials_unavailable",
@@ -175,6 +191,9 @@ export function parseCredentials(serialized: string): ConnectorOAuthCredentials
       ...(value.tokenType === undefined ? {} : { tokenType: value.tokenType }),
       ...(value.scopes === undefined ? {} : { scopes: value.scopes as string[] }),
       ...(expiresAt === undefined ? {} : { expiresAt }),
+      ...(value.authorizationContext === undefined
+        ? {}
+        : { authorizationContext: value.authorizationContext }),
     })
   } catch (error) {
     throw createConnectorCodedError(
@@ -238,21 +257,88 @@ export function normalizedHttpUrl(
 
 export function assertAuthorizationUrlParameters(
   authorizationUrl: string,
-  expected: { readonly state: string; readonly codeChallenge: string }
+  expected: { readonly state: string; readonly codeChallenge?: string }
 ): void {
   const parameters = new URL(authorizationUrl).searchParams
   if (
     !sameSingleParameter(parameters, "state", expected.state) ||
-    !sameSingleParameter(parameters, "code_challenge", expected.codeChallenge) ||
-    !sameSingleParameter(parameters, "code_challenge_method", "S256")
+    (expected.codeChallenge === undefined
+      ? parameters.has("code_challenge") || parameters.has("code_challenge_method")
+      : !sameSingleParameter(parameters, "code_challenge", expected.codeChallenge) ||
+        !sameSingleParameter(parameters, "code_challenge_method", "S256"))
   ) {
     throw createConnectorCodedError(
       "connector.adapter_invalid",
-      "OAuth connector authorization URL must preserve the framework-provided state and PKCE S256 parameters."
+      expected.codeChallenge === undefined
+        ? "OAuth connector authorization URL must preserve the framework-provided state and omit disabled PKCE parameters."
+        : "OAuth connector authorization URL must preserve the framework-provided state and PKCE S256 parameters."
     )
   }
 }
 
+export function connectorPkceEnabled(pkce: "S256" | "disabled" | undefined): boolean {
+  if (pkce === undefined || pkce === "S256") return true
+  if (pkce === "disabled") return false
+  throw createConnectorCodedError(
+    "connector.adapter_invalid",
+    "OAuth connector PKCE must be S256 or disabled."
+  )
+}
+
+const reservedCallbackParameters = new Set([
+  "state",
+  "code",
+  "auth_code",
+  "error",
+  "error_description",
+  "error_uri",
+])
+
+export function validateCallbackParameterNames(names: readonly string[] = []): void {
+  if (
+    !Array.isArray(names) ||
+    names.some(
+      (name) =>
+        typeof name !== "string" ||
+        !/^[A-Za-z_][A-Za-z0-9_.-]*$/.test(name) ||
+        reservedCallbackParameters.has(name)
+    ) ||
+    new Set(names).size !== names.length
+  ) {
+    throw createConnectorCodedError(
+      "connector.adapter_invalid",
+      "OAuth callback parameter names must be unique, non-reserved parameter names."
+    )
+  }
+}
+
+/** Select only declared provider values after the callback's state and browser binding are proved. */
+export function selectCallbackParameters(
+  names: readonly string[] = [],
+  parameters: Readonly<Record<string, string | readonly string[]>> = {}
+): Readonly<Record<string, string>> {
+  validateCallbackParameterNames(names)
+  if (!isRecord(parameters)) {
+    throw createConnectorCodedError(
+      "connector.authorization_invalid",
+      "OAuth provider callback parameters must be an object."
+    )
+  }
+  return Object.fromEntries(
+    names.flatMap((name) => {
+      if (!Object.hasOwn(parameters, name)) return []
+      const value = parameters[name]
+      if (typeof value !== "string") {
+        throw createConnectorCodedError(
+          "connector.authorization_invalid",
+          "OAuth provider callback parameters must have a single string value."
+        )
+      }
+      return [[name, value]]
+    })
+  )
+}
+
 export function nonblank(
   value: unknown,
   field: string,

package/src/connectors/types.ts

@@ -1,3 +1,4 @@
+import type { ReadonlyJsonObject } from "../json"
 import type { WebhookDefinition } from "../webhooks/types"
 
 /**
@@ -33,6 +34,12 @@ export interface ConnectorOAuthCredentials {
   readonly tokenType?: string
   readonly scopes?: readonly string[]
   readonly expiresAt?: Date
+  /**
+   * Provider-owned grant context, encrypted with the tokens and never exposed in connection views.
+   * Available to account discovery, refresh, and revoke. Refresh preserves it when omitted;
+   * returning an object replaces it (use {} to clear it). Code exchange starts fresh on reauthorization.
+   */
+  readonly authorizationContext?: ReadonlyJsonObject
 }
 
 /** Public, non-secret account information returned for framework-owned selection UI. */
@@ -75,13 +82,17 @@ export interface OAuthConnectorAuthorizationContext extends ConnectorContext {
 
 export interface OAuthConnectorAuthorizationUrlInput {
   readonly state: string
-  readonly codeChallenge: string
-  readonly codeChallengeMethod: "S256"
+  /** Present only when the adapter enables PKCE (S256 by default). */
+  readonly codeChallenge?: string
+  readonly codeChallengeMethod?: "S256"
 }
 
 export interface OAuthConnectorCodeExchangeInput {
   readonly code: string
-  readonly codeVerifier: string
+  /** Present only when this authorization attempt used PKCE. */
+  readonly codeVerifier?: string
+  /** Allowlisted callback values. Untrusted until the adapter validates them with the provider. */
+  readonly callbackParameters?: Readonly<Record<string, string>>
 }
 
 export interface ConnectorConnectionClientContext extends ConnectorContext {
@@ -109,6 +120,10 @@ export interface ConnectorTokenSource {
  */
 export interface ConnectorOAuth2Authentication {
   readonly type: "oauth2"
+  /** Defaults to S256. Disable only for providers whose flow does not support PKCE. */
+  readonly pkce?: "S256" | "disabled"
+  /** Additional callback parameter names accepted by exchangeCode; framework OAuth fields are reserved. */
+  readonly callbackParameters?: readonly string[]
   authorizationUrl(
     context: OAuthConnectorAuthorizationContext,
     input: OAuthConnectorAuthorizationUrlInput
@@ -131,7 +146,7 @@ export interface ConnectorOAuth2Authentication {
 export interface OAuthConnectorAdapter<TType extends string = string, TClient = unknown> {
   readonly type: TType
   readonly authentication: ConnectorOAuth2Authentication
-  readonly webhooks?: undefined
+  readonly webhooks?: readonly WebhookDefinition<unknown, TClient>[]
   discoverAccounts(
     context: ConnectorContext,
     credentials: ConnectorOAuthCredentials

package/src/events/execution.ts

@@ -17,7 +17,7 @@ export interface EventsRuntime {
   latestCursor(): Promise<string | undefined>
   subscribe(
     input: EventsSubscribeInput,
-    handler: (events: readonly StoredDomainEvent[]) => void
+    handler: (events: readonly StoredDomainEvent[]) => unknown
   ): Promise<() => void>
 }
 
@@ -88,7 +88,7 @@ export function createEventsRuntime(runtime: SixbRuntimeContext): EventsRuntime
       }
       return runtime.events.subscribe(input, (events) => {
         const visible = visibleEvents(events)
-        if (visible.length > 0) handler(visible)
+        if (visible.length > 0) return handler(visible)
       })
     },
   }

package/src/events/outbox-dispatcher.ts

@@ -46,6 +46,7 @@ export interface OntologyOutboxDispatcherOptions {
   readonly maxIsolationAttempts?: number
   /** Maximum claimed batches handled by one drain pass. */
   readonly maxClaimsPerDrain?: number
+  /** Broker grace period. Shutdown still waits for outstanding storage operations afterward. */
   readonly shutdownTimeoutMs?: number
   readonly now?: () => Date
   readonly random?: () => number
@@ -100,10 +101,10 @@ export class OntologyOutboxDispatcher {
   private readonly createLeaseId: () => string
   private readonly onDeliveryFailure?: OntologyOutboxDispatcherOptions["onDeliveryFailure"]
   private readonly onError: (error: unknown) => void
-  private readonly inFlight = new Set<ClaimedBatch>()
   private draining: Promise<void> | null = null
   private pendingDrain: Promise<void> | null = null
   private stopping: Promise<void> | null = null
+  private closing = false
   private stopRequested = false
   private readonly forcedStop = new AbortController()
 
@@ -166,7 +167,7 @@ export class OntologyOutboxDispatcher {
    * mutation.
    */
   drain(): Promise<void> {
-    if (this.stopRequested) return Promise.resolve()
+    if (this.closing || this.stopRequested) return Promise.resolve()
     if (!this.draining) return this.startDrainPass()
 
     this.pendingDrain ??= settled(this.draining).then(() => {
@@ -178,7 +179,7 @@ export class OntologyOutboxDispatcher {
 
   /** Starts a tracked, best-effort drain without extending mutation latency. */
   notify(): void {
-    if (this.stopRequested) return
+    if (this.closing || this.stopRequested) return
     void this.drain().catch((error) => this.reportError(error))
   }
 
@@ -193,19 +194,16 @@ export class OntologyOutboxDispatcher {
     // Include one final bounded pass so commits whose notifications were coalesced immediately
     // before shutdown are not left pending merely because the process is stopping.
     const gracefulDrain = this.drain().catch((error) => this.reportError(error))
-    if (await settlesWithin(gracefulDrain, this.shutdownTimeoutMs)) {
-      this.stopRequested = true
-      return
-    }
-
+    this.closing = true
+    const finished = await settlesWithin(gracefulDrain, this.shutdownTimeoutMs)
     this.stopRequested = true
-    this.forcedStop.abort()
-    await settlesWithin(
-      this.rescheduleUnsettledForShutdown(),
-      Math.min(this.shutdownTimeoutMs, 1_000)
-    )
-    this.draining = null
-    this.pendingDrain = null
+    if (!finished) this.forcedStop.abort()
+    // Storage operations cannot be cancelled by this contract. A late claim must release its
+    // lease, and an acknowledgement already started must finish before callers close storage.
+    // publishClaim owns settlement, including forced stop; never race a second cleanup against it.
+    await gracefulDrain
+    if (this.draining) await settled(this.draining)
+    if (this.pendingDrain) await settled(this.pendingDrain)
   }
 
   private startDrainPass(): Promise<void> {
@@ -224,11 +222,14 @@ export class OntologyOutboxDispatcher {
       if (rows.length === 0) return
       const publishedCount = await this.publishClaim(rows)
       if (this.stopRequested || publishedCount === 0 || rows.length < this.batchSize) return
+      // In-memory/SQLite can resolve without I/O. Yield between full batches so catch-up cannot
+      // monopolize the event loop, while keeping small post-commit deliveries immediate.
+      await new Promise<void>((resolve) => setImmediate(resolve))
     }
 
     // A healthy full slice means more due rows may remain. Reuse the existing coalescing path so
     // catch-up continues without recursion, an idle polling loop, or an unbounded individual pass.
-    if (!this.stopRequested) this.notify()
+    if (!this.closing && !this.stopRequested) this.notify()
   }
 
   private claimBatch(): Promise<readonly ClaimedOntologyOutboxRow[]> {
@@ -247,7 +248,6 @@ export class OntologyOutboxDispatcher {
   private async publishClaim(rows: readonly ClaimedOntologyOutboxRow[]): Promise<number> {
     const claim = new ClaimedBatch(rows)
     const failures = new DeliveryFailureAccumulator()
-    this.inFlight.add(claim)
     const pending: PublicationGroup[] = [{ rows }]
     let publishAttempts = 0
     let publishedCount = 0
@@ -288,7 +288,6 @@ export class OntologyOutboxDispatcher {
       if (this.stopRequested) {
         await this.rescheduleClaimedForShutdown(claim.close())
       }
-      this.inFlight.delete(claim)
       for (const failure of failures.list()) {
         this.reportDeliveryFailure(failure.error, failure.context)
       }
@@ -378,15 +377,10 @@ export class OntologyOutboxDispatcher {
     }
   }
 
-  private async rescheduleUnsettledForShutdown(): Promise<void> {
-    for (const claim of [...this.inFlight]) {
-      await this.rescheduleClaimedForShutdown(claim.close())
-      this.inFlight.delete(claim)
-    }
-  }
-
   private withOutbox<T>(run: (outbox: OntologyOutboxStorage) => Promise<T> | T): Promise<T> {
-    return this.storage.transaction((tx) => run(tx.ontology.outbox))
+    // Every outbox method owns its atomic provider operation. A framework-wide transaction
+    // adds no guarantee here and copies the entire InMemoryStorage state for every batch.
+    return Promise.resolve(run(this.storage.ontology.outbox))
   }
 
   private reportDeliveryFailure(error: unknown, failure: OntologyOutboxDeliveryFailure): void {

package/src/events/service.ts

@@ -79,7 +79,7 @@ export interface DomainEventLog {
   latestCursor(): Promise<string | undefined>
   subscribe(
     input: EventsSubscribeInput,
-    handler: (events: readonly StoredDomainEvent[]) => void
+    handler: (events: readonly StoredDomainEvent[]) => unknown
   ): Promise<() => void>
 }
 
@@ -251,7 +251,7 @@ export class DomainEventService implements DomainEventLog, StableEventPublisher
 
   async subscribe(
     input: EventsSubscribeInput,
-    handler: (events: readonly StoredDomainEvent[]) => void
+    handler: (events: readonly StoredDomainEvent[]) => unknown
   ): Promise<() => void> {
     await this.ensureStream()
     return this.broker.subscribe(
@@ -269,7 +269,7 @@ export class DomainEventService implements DomainEventLog, StableEventPublisher
         }
 
         try {
-          handler(events)
+          return handler(events)
         } catch {
           // Preserve fire-and-forget subscriber semantics.
         }

package/src/index.ts

@@ -163,9 +163,15 @@ export {
 
 // ── Broker ─────────────────────────────────────────────────
 
-export type { Broker, BrokerCursor } from "./broker"
+export type {
+  Broker,
+  BrokerCursor,
+  BrokerRetention,
+  BrokerStreamRetention,
+  InMemoryBrokerOptions,
+} from "./broker"
 export { InMemoryBroker } from "./broker"
-export type { JsonValue, ReadonlyJsonValue } from "./json"
+export type { JsonValue, ReadonlyJsonObject, ReadonlyJsonValue } from "./json"
 export {
   assertJsonValue,
   cloneJsonValue,
@@ -681,6 +687,8 @@ export type {
   WebhookBodyFormat,
   WebhookBodyParser,
   WebhookBodySchema,
+  WebhookConnection,
+  WebhookConnections,
   WebhookConnectorClient,
   WebhookDefinition,
   WebhookHandlerContext,

package/src/lake-storage/changes.ts

@@ -0,0 +1,43 @@
+import type { DatasetColumnDefinition } from "../datasets"
+import { LakeStorageError } from "./errors"
+import type { DatasetVersion, ReadDatasetChangesInput } from "./types"
+
+/** Shared eligibility checks for providers comparing pinned row images. */
+export function resolveDatasetChangeColumns(
+  input: ReadDatasetChangesInput,
+  before: DatasetVersion | null,
+  after: DatasetVersion | null
+): readonly DatasetColumnDefinition[] | null {
+  for (const value of [input.datasetId, input.fromVersionId, input.toVersionId]) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+      throw new LakeStorageError(
+        "[LakeStorage] Change reads require explicit dataset and version ids."
+      )
+    }
+  }
+  if (
+    input.keyColumns.length === 0 ||
+    new Set(input.keyColumns).size !== input.keyColumns.length ||
+    input.columns.length === 0 ||
+    new Set(input.columns).size !== input.columns.length ||
+    input.columns.some((column) => typeof column !== "string" || column.length === 0) ||
+    input.keyColumns.some((column) => !input.columns.includes(column))
+  ) {
+    throw new LakeStorageError(
+      "[LakeStorage] Change reads require distinct columns including every key column."
+    )
+  }
+  if (!before || !after) return null
+  const oldColumns = new Map(before.schema.columns.map((column) => [column.name, column]))
+  const newColumns = new Map(after.schema.columns.map((column) => [column.name, column]))
+  const columns: DatasetColumnDefinition[] = []
+  for (const name of input.columns) {
+    const previous = oldColumns.get(name)
+    const next = newColumns.get(name)
+    if (!previous || !next || previous.type !== next.type) return null
+    // Projection identities are nonblank strings. Other key types keep the full-read path.
+    if (input.keyColumns.includes(name) && next.type !== "string") return null
+    columns.push(next)
+  }
+  return columns
+}

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

@@ -1,6 +1,8 @@
 import { randomUUID } from "node:crypto"
+import { isDeepStrictEqual } from "node:util"
 import type { DatasetDefinition, DatasetSchema, MergeChange } from "../datasets"
 import { getDatasetRowValidationError } from "../datasets/validation"
+import { resolveDatasetChangeColumns } from "./changes"
 import { mergeStrictDatasetDefinition } from "./definition-updates"
 import { LakeConcurrencyError, LakeStorageError } from "./errors"
 import type {
@@ -26,12 +28,15 @@ import type {
   BeginDatasetWriteInput,
   CommitDatasetWriteInput,
   DatasetCatalogState,
+  DatasetChanges,
   DatasetRow,
+  DatasetRowChange,
   DatasetVersion,
   DatasetWriteCommitResult,
   DatasetWriteMode,
   LakeStorage,
   LakeWriteSession,
+  ReadDatasetChangesInput,
   ReadDatasetRowsInput,
 } from "./types"
 import { hasDatasetInputChanges } from "./version-inputs"
@@ -362,6 +367,7 @@ export class InMemoryLakeStorage implements LakeStorage {
   }
 
   async *readRows(input: ReadDatasetRowsInput): AsyncIterable<DatasetRow> {
+    input.signal?.throwIfAborted()
     const definition = this.datasets.get(input.datasetId)
     if (!definition) {
       throw new LakeStorageError(`[LakeStorage] Unknown dataset '${input.datasetId}'`)
@@ -385,10 +391,79 @@ export class InMemoryLakeStorage implements LakeStorage {
       ?.slice(offset, limit === undefined ? undefined : offset + limit)
 
     for (const row of rows ?? []) {
+      input.signal?.throwIfAborted()
       yield selectColumns(row, input.columns)
     }
   }
 
+  async readChanges(input: ReadDatasetChangesInput): Promise<DatasetChanges | null> {
+    input.signal?.throwIfAborted()
+    const before = await this.getVersion(input.datasetId, input.fromVersionId)
+    const after = await this.getVersion(input.datasetId, input.toVersionId)
+    if (!resolveDatasetChangeColumns(input, before, after)) return null
+    const previous = this.rowsByVersionId.get(input.fromVersionId)!
+    const next = this.rowsByVersionId.get(input.toVersionId)!
+    const index = (rows: readonly DatasetRow[]) => {
+      const result = new Map<string, DatasetRow>()
+      for (const row of rows) {
+        input.signal?.throwIfAborted()
+        const values = input.keyColumns.map((column) => row[column])
+        if (values.some((value) => typeof value !== "string" || value.trim().length === 0))
+          return null
+        const key = JSON.stringify(values)
+        if (result.has(key)) return null
+        result.set(key, row)
+      }
+      return result
+    }
+    const oldRows = index(previous)
+    const newRows = index(next)
+    if (!oldRows || !newRows) return null
+    let pending: DatasetRowChange[] = []
+    for (const [key, row] of oldRows) {
+      const newRow = newRows.get(key)
+      if (
+        !newRow ||
+        input.columns.some(
+          (column) => !isDeepStrictEqual(row[column] ?? null, newRow[column] ?? null)
+        )
+      ) {
+        pending.push({
+          before: selectColumns(row, input.columns),
+          after: newRow ? selectColumns(newRow, input.columns) : null,
+        })
+      }
+    }
+    for (const [key, row] of newRows) {
+      if (!oldRows.has(key))
+        pending.push({ before: null, after: selectColumns(row, input.columns) })
+    }
+    let closed = false
+    const changeCount = pending.length
+    return {
+      fromRowCount: previous.length,
+      toRowCount: next.length,
+      changeCount,
+      changes: (async function* () {
+        if (closed) throw new LakeStorageError("[LakeStorage] Change reader is closed.")
+        try {
+          for (let i = 0; i < changeCount; i++) {
+            input.signal?.throwIfAborted()
+            if (closed) throw new LakeStorageError("[LakeStorage] Change reader is closed.")
+            yield structuredClone(pending[i]!)
+          }
+        } finally {
+          closed = true
+          pending = []
+        }
+      })(),
+      async close() {
+        closed = true
+        pending = []
+      },
+    }
+  }
+
   async commitWrite(options: {
     write: BeginDatasetWriteInput
     rows: readonly DatasetRow[]