@sixb/core 0.1.0 → 0.1.1

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

@@ -0,0 +1,117 @@
+import type { DatasetDefinition, MergeChange } from "../datasets"
+import { getDatasetRowValidationError } from "../datasets"
+import { isPlainRecord } from "../json"
+import { LakeStorageError } from "./errors"
+import type { DatasetRow } from "./types"
+
+/** Return a new ordered primary-key column list, or `null` for an unkeyed dataset. */
+export function getDatasetPrimaryKeyColumns(dataset: DatasetDefinition): readonly string[] | null {
+  if (dataset.primaryKey === undefined) {
+    return null
+  }
+  return typeof dataset.primaryKey === "string" ? [dataset.primaryKey] : [...dataset.primaryKey]
+}
+
+/** Collision-safe internal identity for a validated row or delete-key object. */
+export function encodeDatasetPrimaryKey(dataset: DatasetDefinition, value: DatasetRow): string {
+  const columns = getDatasetPrimaryKeyColumns(dataset)
+  if (columns === null) {
+    throw new LakeStorageError(
+      `[SixbLake] Dataset '${dataset.id}' must define a primaryKey before rows can be keyed.`
+    )
+  }
+
+  const values = columns.map((columnName) => {
+    const columnValue = value[columnName]
+    if (typeof columnValue !== "string") {
+      throw new LakeStorageError(
+        `[SixbLake] Dataset '${dataset.id}' primary-key column '${columnName}' must be a string.`
+      )
+    }
+    return columnValue
+  })
+  return JSON.stringify(values)
+}
+
+export function getDatasetMergeChangeValidationError(
+  change: unknown,
+  dataset: DatasetDefinition
+): string | null {
+  const primaryKeyColumns = getDatasetPrimaryKeyColumns(dataset)
+  if (primaryKeyColumns === null) {
+    return `Dataset '${dataset.id}' must define a primaryKey before it can be merged.`
+  }
+  if (!isPlainRecord(change)) {
+    return `Dataset '${dataset.id}' merge changes must be plain objects.`
+  }
+
+  if (change.kind === "upsert") {
+    const shapeError = getChangeShapeError(change, dataset, "row")
+    if (shapeError) {
+      return shapeError
+    }
+    return getDatasetRowValidationError(change.row, dataset)
+  }
+
+  if (change.kind === "delete") {
+    const shapeError = getChangeShapeError(change, dataset, "key")
+    if (shapeError) {
+      return shapeError
+    }
+    return getDeleteKeyValidationError(change.key, dataset, primaryKeyColumns)
+  }
+
+  return `Dataset '${dataset.id}' merge change kind must be 'upsert' or 'delete'.`
+}
+
+/** Clone a validated change before a provider stages it beyond the caller's ownership. */
+export function cloneDatasetMergeChange(
+  change: MergeChange<DatasetRow, DatasetRow>
+): MergeChange<DatasetRow, DatasetRow> {
+  return change.kind === "upsert"
+    ? { kind: "upsert", row: structuredClone(change.row) }
+    : { kind: "delete", key: structuredClone(change.key) }
+}
+
+function getChangeShapeError(
+  change: Record<string, unknown>,
+  dataset: DatasetDefinition,
+  payloadField: "row" | "key"
+): string | null {
+  const allowedFields = new Set(["kind", payloadField])
+  for (const field of Object.keys(change)) {
+    if (!allowedFields.has(field)) {
+      return `Dataset '${dataset.id}' ${change.kind as string} change contains unknown field '${field}'.`
+    }
+  }
+  if (!Object.hasOwn(change, payloadField)) {
+    return `Dataset '${dataset.id}' ${change.kind as string} change is missing '${payloadField}'.`
+  }
+  return null
+}
+
+function getDeleteKeyValidationError(
+  key: unknown,
+  dataset: DatasetDefinition,
+  primaryKeyColumns: readonly string[]
+): string | null {
+  if (!isPlainRecord(key)) {
+    return `Dataset '${dataset.id}' delete keys must be plain objects.`
+  }
+
+  const expectedColumns = new Set(primaryKeyColumns)
+  for (const columnName of Object.keys(key)) {
+    if (!expectedColumns.has(columnName)) {
+      return `Dataset '${dataset.id}' delete key contains unknown column '${columnName}'.`
+    }
+  }
+  for (const columnName of primaryKeyColumns) {
+    if (!Object.hasOwn(key, columnName)) {
+      return `Dataset '${dataset.id}' delete key is missing primary-key column '${columnName}'.`
+    }
+    if (typeof key[columnName] !== "string") {
+      return `Dataset '${dataset.id}' delete key column '${columnName}' must be a string.`
+    }
+  }
+  return null
+}

package/src/lake-storage/merge.ts

@@ -0,0 +1,35 @@
+import type { DatasetDefinition, MergeChange } from "../datasets"
+import type { DatasetProducer, DatasetRow, DatasetVersion, DatasetVersionRef } from "./types"
+
+export interface BeginDatasetMergeInput {
+  /** Stored definition for the keyed dataset whose latest version is captured by `beginMerge`. */
+  readonly dataset: DatasetDefinition
+  /** Optional caller guard checked against the same latest version captured by the session. */
+  readonly expectedLatestVersionId?: string
+  readonly producer?: DatasetProducer
+  readonly inputs?: readonly DatasetVersionRef[]
+}
+
+export interface CommitDatasetMergeInput {
+  readonly commitMessage?: string
+}
+
+/**
+ * A merge can be unchanged before the dataset has a first version, so its result carries the
+ * version separately instead of extending `DatasetVersion` like ordinary write commits do.
+ */
+export type DatasetMergeCommitResult =
+  | { readonly outcome: "created"; readonly version: DatasetVersion }
+  | { readonly outcome: "unchanged"; readonly version: DatasetVersion | null }
+
+export interface LakeMergeSession {
+  /** Stage ordered complete-row upserts and exact primary-key deletes. */
+  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(input?: CommitDatasetMergeInput): Promise<DatasetMergeCommitResult>
+  abort(): Promise<void>
+}

package/src/lake-storage/types.ts

@@ -1,7 +1,8 @@
 import type { DatasetDefinition, DatasetSchema } from "../datasets"
+import type { BeginDatasetMergeInput, LakeMergeSession } from "./merge"
 
 export type DatasetWriteMode = "snapshot" | "append"
-export type DatasetVersionMode = DatasetWriteMode | "schema"
+export type DatasetVersionMode = DatasetWriteMode | "merge" | "schema"
 
 export type DatasetRow = Readonly<Record<string, unknown>>
 
@@ -124,6 +125,7 @@ export interface LakeStorage {
   listVersions(datasetId: string, limit?: number): Promise<readonly DatasetVersion[]>
 
   beginWrite(input: BeginDatasetWriteInput): Promise<LakeWriteSession>
+  beginMerge(input: BeginDatasetMergeInput): Promise<LakeMergeSession>
 
   getLatestVersion(datasetId: string): Promise<DatasetVersion | null>
   getVersion(datasetId: string, versionId: string): Promise<DatasetVersion | null>

package/src/ontology/json-schema.ts

@@ -53,8 +53,9 @@ function schemaJsonSchema(
       case "integer":
         return { type: "integer" }
       case "double":
-      case "decimal":
         return { type: "number" }
+      case "decimal":
+        return { type: "string", pattern: "^[+-]?\\d+(?:\\.\\d+)?$" }
       case "boolean":
         return { type: "boolean" }
       case "date":

package/src/ontology/validation/normalize.ts

@@ -2,7 +2,7 @@ import { assertJsonValue, cloneJsonValue, type JsonValue } from "../../json"
 import type { ObjectFieldSchema, Property, Schema, ValueType } from ".."
 import { normalizeDecimalValue } from "../decimal"
 import { OntologyValidationError } from "../errors"
-import { resolveValueTypeSchema } from "./schema"
+import { isRecord, resolveValueTypeSchema } from "./schema"
 
 /**
  * Normalize a property bag to JSON-safe values using each property's schema —
@@ -84,20 +84,18 @@ export function normalizeSchemaValue(
 
   const fields = schema.properties
   const record = assertPlainRecord(value, path)
-  const output: Record<string, JsonValue> = {}
+  const entries: Array<[string, JsonValue]> = []
   for (const [fieldId, field] of Object.entries(fields)) {
     const fieldValue = record[fieldId]
     if (fieldValue === undefined) {
       continue
     }
-    output[fieldId] = normalizeObjectFieldValue(
-      field,
-      fieldValue,
-      `${path}.${fieldId}`,
-      valueTypesById
-    )
+    entries.push([
+      fieldId,
+      normalizeObjectFieldValue(field, fieldValue, `${path}.${fieldId}`, valueTypesById),
+    ])
   }
-  return output
+  return Object.fromEntries(entries)
 }
 
 function normalizeObjectFieldValue(
@@ -149,10 +147,6 @@ function normalizeDateLike(value: unknown, path: string): Date {
   return date
 }
 
-function isPlainRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-}
-
 /**
  * Inverse of `normalizeSchemaValue` for the handler-facing surface: re-hydrate
  * `date`/`timestamp` values from their stored ISO string back into a `Date`, so
@@ -196,7 +190,7 @@ export function coerceSchemaValueToTyped(
   }
 
   if (schema.type === "map") {
-    if (!isPlainRecord(value)) return value
+    if (!isRecord(value)) return value
     return Object.fromEntries(
       Object.entries(value).map(([key, entry]) => [
         key,
@@ -205,7 +199,7 @@ export function coerceSchemaValueToTyped(
     )
   }
 
-  if (!isPlainRecord(value)) return value
+  if (!isRecord(value)) return value
   const output: Record<string, unknown> = { ...value }
   for (const [fieldId, field] of Object.entries(schema.properties)) {
     if (value[fieldId] === undefined) continue

package/src/runtime/sixb.ts

@@ -19,7 +19,7 @@ import {
 } from "../actions/request"
 import type { ActionDefinition } from "../actions/types"
 import type { AgentDefinition, RequestAgentRunInput, RequestAgentRunResult } from "../agents"
-import { AgentsRuntime, validateAgentGroupReferences } from "../agents"
+import { AgentsRuntime, validateAgentGroupReferences, validateAgentToolsAtStartup } from "../agents"
 import {
   AuthRuntime,
   AuthRuntimeError,
@@ -96,6 +96,10 @@ import {
   requestSyncRun,
   type SyncRunRequestResult,
 } from "../syncs/request"
+import {
+  validateKeyedDatasetWriterTopology,
+  validateMergeSyncProjectionSafety,
+} from "../syncs/validation"
 import type { RegisteredWebhook } from "../webhooks"
 import { registerWebhooks, WebhookValidationError, webhookRoute } from "../webhooks"
 import type {
@@ -227,6 +231,7 @@ export class Sixb<TOntologySources extends readonly OntologySource[]>
     this.actionRegistry = new ActionRegistry(options.actions ?? [], this.ontology)
     const registeredActionIds = new Set(this.actionRegistry.list().map((action) => action.id))
     const agents = options.agents ?? []
+    validateAgentToolsAtStartup(agents)
     this.security = createRuntimeSecurityRegistry({
       groups: options.groups ?? [],
       roles: options.roles ?? [],
@@ -327,6 +332,12 @@ export class Sixb<TOntologySources extends readonly OntologySource[]>
       this.pipelinesById.set(pipeline.id, pipeline)
     }
 
+    validateKeyedDatasetWriterTopology({
+      datasetsById: this.datasetsById,
+      syncs: [...this.syncsById.values()],
+      pipelines: [...this.pipelinesById.values()],
+    })
+
     // Rules validate against the resolved ontology so inherited properties and
     // links are available before checking predicate references.
     validateRulesAtStartup(this.rules, this.ontology)
@@ -368,6 +379,10 @@ export class Sixb<TOntologySources extends readonly OntologySource[]>
       ontology: this.ontology,
       datasetsById: this.datasetsById,
     })
+    validateMergeSyncProjectionSafety({
+      syncs: [...this.syncsById.values()],
+      telemetryProjections: this.projectionRegistry.listTelemetryProjections(),
+    })
     registerProjectionRegistry(this, this.projectionRegistry)
 
     const materializer = createOntologyMaterializer({

package/src/storage/index.ts

@@ -388,6 +388,7 @@ export type {
   ListSyncRunsResult,
   StartSyncRunInput,
   SyncRunFailure,
+  SyncRunMode,
   SyncRunRecord,
   SyncRunStatus,
   SyncRunStorage,

package/src/storage/sync-runs/in-memory.ts

@@ -90,9 +90,9 @@ export class InMemorySyncRunStorage implements SyncRunStorage {
           `[Sixb] Sync run '${input.id}' output dataset '${input.output.datasetId}' does not match '${existing.datasetId}'.`
         )
       }
-      if (!input.output && (existing.mode !== "append" || input.rowsRead !== 0)) {
+      if (!input.output && input.rowsRead !== 0 && existing.mode !== "merge") {
         throw new SyncRunError(
-          `[Sixb] Sync run '${input.id}' may omit its output only for an empty append.`
+          `[Sixb] Sync run '${input.id}' may omit its output with rows read only for an initial merge no-op.`
         )
       }
     }

package/src/storage/sync-runs/index.ts

@@ -8,6 +8,7 @@ export type {
   ListSyncRunsResult,
   StartSyncRunInput,
   SyncRunFailure,
+  SyncRunMode,
   SyncRunRecord,
   SyncRunStatus,
   SyncRunStorage,

package/src/storage/sync-runs/types.ts

@@ -1,6 +1,8 @@
 import type { JsonValue } from "../../json"
 import type { DatasetVersionRef, DatasetWriteMode } from "../../lake-storage"
 
+export type SyncRunMode = DatasetWriteMode | "merge"
+
 export type SyncRunStatus = "running" | "succeeded" | "failed" | "cancelled"
 
 export interface SyncRunFailure {
@@ -13,11 +15,12 @@ export interface SyncRunRecord {
   readonly projectId: string
   readonly syncId: string
   readonly datasetId: string
-  readonly mode: DatasetWriteMode
+  readonly mode: SyncRunMode
   readonly status: SyncRunStatus
   readonly startedAt: Date
   readonly finishedAt?: Date
-  readonly rowsRead?: number // Rows produced by this run, not the dataset's full visible row count.
+  /** Source items successfully consumed. Merge runs count both upserts and deletes. */
+  readonly rowsRead?: number
   readonly output?: DatasetVersionRef
   readonly expectedLatestVersionId?: string
   readonly commitMessage?: string
@@ -30,7 +33,7 @@ export interface StartSyncRunInput {
   readonly projectId: string
   readonly syncId: string
   readonly datasetId: string
-  readonly mode: DatasetWriteMode
+  readonly mode: SyncRunMode
   readonly startedAt?: Date
   readonly expectedLatestVersionId?: string
   readonly commitMessage?: string
@@ -42,8 +45,9 @@ export type FinishSyncRunInput =
       readonly projectId: string
       readonly status: "succeeded"
       readonly finishedAt?: Date
+      /** Source items successfully consumed. Merge runs count both upserts and deletes. */
       readonly rowsRead: number
-      /** Absent only when the first append run succeeds without producing any rows. */
+      /** Absent when a successful run has no dataset version to reference. */
       readonly output?: DatasetVersionRef
       readonly checkpoint?: JsonValue
     }
@@ -52,6 +56,7 @@ export type FinishSyncRunInput =
       readonly projectId: string
       readonly status: "failed" | "cancelled"
       readonly finishedAt?: Date
+      /** Source items successfully consumed before the failure or cancellation. */
       readonly rowsRead?: number
       readonly error?: SyncRunFailure
     }

package/src/storage/types.ts

@@ -172,6 +172,7 @@ export type {
   ListSyncRunsResult,
   StartSyncRunInput,
   SyncRunFailure,
+  SyncRunMode,
   SyncRunRecord,
   SyncRunStatus,
   SyncRunStorage,

package/src/storage/workflow-runs/in-memory.ts

@@ -174,10 +174,12 @@ export class InMemoryWorkflowRunStorage implements WorkflowRunStorage {
       input.status === "succeeded"
         ? {
             ...base,
+            output: cloneRecord(input.output),
             error: undefined,
           }
         : {
             ...base,
+            output: undefined,
             error: input.error,
           }
 

package/src/storage/workflow-runs/types.ts

@@ -121,6 +121,7 @@ export interface WorkflowRunRecord {
   readonly workflowId: string
   readonly status: WorkflowRunStatus
   readonly input: WorkflowIOSnapshot
+  readonly output?: WorkflowIOSnapshot
   readonly queuedAt?: Date
   readonly startedAt: Date
   readonly finishedAt?: Date
@@ -201,6 +202,7 @@ export type FinishWorkflowRunInput =
       readonly id: string
       readonly projectId: string
       readonly status: "succeeded"
+      readonly output: WorkflowIOSnapshot
       readonly finishedAt?: Date
       readonly executionToken?: string
     }

package/src/syncs/builders.ts

@@ -8,6 +8,7 @@ import type {
   BatchSyncDefinitionConfig,
   SyncBuilder,
   SyncDefinition,
+  SyncMode,
   SyncReadBuilder,
   SyncTargetBuilder,
 } from "./types"
@@ -18,16 +19,19 @@ function assertNonEmpty(value: string, field: string): void {
   }
 }
 
-function assertDataset(dataset: DatasetDefinition): void {
+function assertDataset(dataset: DatasetDefinition, mode: SyncMode): void {
   assertNonEmpty(dataset.id, "dataset id")
+  if (mode === "merge" && dataset.primaryKey === undefined) {
+    throw new SyncValidationError(`Merge sync dataset '${dataset.id}' must define a primaryKey.`)
+  }
 }
 
 function normalizeBatchSyncConfig(options: BatchSyncConfig | undefined): BatchSyncDefinitionConfig {
   const mode = options?.mode ?? "snapshot"
 
-  if (mode !== "snapshot" && mode !== "append") {
+  if (mode !== "snapshot" && mode !== "append" && mode !== "merge") {
     throw new SyncValidationError(
-      `Invalid sync mode '${String(mode)}'. Expected 'snapshot' or 'append'.`
+      `Invalid sync mode '${String(mode)}'. Expected 'snapshot', 'append', or 'merge'.`
     )
   }
 
@@ -37,43 +41,57 @@ function normalizeBatchSyncConfig(options: BatchSyncConfig | undefined): BatchSy
   }
 }
 
+type DefaultBatchSyncConfig = Omit<BatchSyncConfig, "mode"> & { readonly mode?: undefined }
+
 /**
  * Define a batch sync that reads from one connector and writes into one dataset.
  *
  * The returned definition is inert and safe to export from `syncs/` modules.
- * V1 supports `snapshot` and `append` modes with optional triggers and checkpoints.
+ * Supports `snapshot`, `append`, and keyed `merge` modes with optional triggers and checkpoints.
  */
+export function defineSync<TId extends string>(
+  id: TId,
+  options?: DefaultBatchSyncConfig
+): SyncBuilder<TId, never, "snapshot">
+export function defineSync<TId extends string, const TMode extends SyncMode>(
+  id: TId,
+  options: BatchSyncConfig<TMode> & { readonly mode: TMode }
+): SyncBuilder<TId, never, TMode>
+export function defineSync<TId extends string>(
+  id: TId,
+  options: BatchSyncConfig
+): SyncBuilder<TId, never, SyncMode>
 export function defineSync<TId extends string>(
   id: TId,
   options?: BatchSyncConfig
-): SyncBuilder<TId> {
+): SyncBuilder<TId, never, SyncMode> {
   assertNonEmpty(id, "id")
 
   const config = normalizeBatchSyncConfig(options)
   const triggers: ScheduleReference[] = []
 
-  function createBuilder<TCheckpoint>(): SyncBuilder<TId, TCheckpoint> {
-    const builder: SyncBuilder<TId, TCheckpoint> = {
-      when(schedule: ScheduleDefinition): SyncBuilder<TId, TCheckpoint> {
+  function createBuilder<TCheckpoint>(): SyncBuilder<TId, TCheckpoint, SyncMode> {
+    const builder: SyncBuilder<TId, TCheckpoint, SyncMode> = {
+      when(schedule: ScheduleDefinition): SyncBuilder<TId, TCheckpoint, SyncMode> {
         if (!isScheduleDefinition(schedule)) {
           throw new SyncValidationError("Sync .when(...) only accepts schedules.")
         }
         triggers.push({ type: "schedule", scheduleId: schedule.id })
         return builder
       },
-      checkpoint<TNextCheckpoint>(): SyncBuilder<TId, TNextCheckpoint> {
+      checkpoint<TNextCheckpoint>(): SyncBuilder<TId, TNextCheckpoint, SyncMode> {
         return createBuilder<TNextCheckpoint>()
       },
       from<TConnector extends ConnectorDefinition>(
         connector: TConnector
-      ): SyncReadBuilder<TId, TConnector, TCheckpoint> {
+      ): SyncReadBuilder<TId, TConnector, TCheckpoint, SyncMode> {
         return {
-          read(handler): SyncTargetBuilder<TId, TConnector, TCheckpoint> {
+          read(handler): SyncTargetBuilder<TId, TConnector, TCheckpoint, SyncMode> {
             return {
               intoDataset(
                 dataset: DatasetDefinition
-              ): SyncDefinition<TId, TConnector, TCheckpoint> {
-                assertDataset(dataset)
+              ): SyncDefinition<TId, TConnector, TCheckpoint, SyncMode> {
+                assertDataset(dataset, config.mode)
 
                 return {
                   kind: "sync",

package/src/syncs/index.ts

@@ -13,6 +13,7 @@ export type {
   SyncBlobContext,
   SyncBuilder,
   SyncDefinition,
+  SyncMode,
   SyncReadBuilder,
   SyncReadContext,
   SyncReadHandler,

package/src/syncs/types.ts

@@ -5,7 +5,7 @@ import {
   type ConnectorDefinition,
   isConnectorDefinition,
 } from "../connectors"
-import type { DatasetDefinition } from "../datasets"
+import type { DatasetDefinition, DatasetPrimaryKey, MergeChange } from "../datasets"
 import { isDatasetDefinition } from "../datasets"
 import type { Logger } from "../logging"
 import type { ScheduleDefinition, ScheduleReference } from "../schedules"
@@ -28,18 +28,27 @@ export type SyncReadContext<TCheckpoint = never> = {
       setCheckpoint(next: TCheckpoint): void
     })
 
+export type SyncMode = "snapshot" | "append" | "merge"
+
+type MergeSyncChange = MergeChange<
+  Readonly<Record<string, unknown>>,
+  Readonly<Record<string, unknown>>
+>
+
 /** A sync read handler may return one item, a sync iterable, or an async iterable. */
-export type SyncReadResult = unknown | Iterable<unknown> | AsyncIterable<unknown>
+export type SyncReadResult<TMode extends SyncMode = SyncMode> = TMode extends "merge"
+  ? MergeSyncChange | Iterable<MergeSyncChange> | AsyncIterable<MergeSyncChange>
+  : unknown | Iterable<unknown> | AsyncIterable<unknown>
 
 /** User-facing batch sync options accepted by `defineSync(...)`. */
-export interface BatchSyncConfig {
-  readonly mode?: "snapshot" | "append"
+export interface BatchSyncConfig<TMode extends SyncMode = SyncMode> {
+  readonly mode?: TMode
 }
 
 /** Normalized batch sync config stored on the final sync definition. */
-export interface BatchSyncDefinitionConfig {
+export interface BatchSyncDefinitionConfig<TMode extends SyncMode = SyncMode> {
   readonly kind: "batch"
-  readonly mode: "snapshot" | "append"
+  readonly mode: TMode
 }
 
 /** V1 syncs always target a named raw dataset. */
@@ -56,11 +65,15 @@ export interface DatasetSyncTarget {
  * builder still gives users precise `context.checkpoint` and `setCheckpoint(...)` types when
  * they author a sync.
  */
-export type SyncReadHandler<TAdapter extends ConnectorAdapter, TCheckpoint = never> = {
+export type SyncReadHandler<
+  TAdapter extends ConnectorAdapter,
+  TCheckpoint = never,
+  TMode extends SyncMode = SyncMode,
+> = {
   bivarianceHack(
     client: ConnectorClient<TAdapter>,
     context: SyncReadContext<TCheckpoint>
-  ): SyncReadResult | Promise<SyncReadResult>
+  ): SyncReadResult<TMode> | Promise<SyncReadResult<TMode>>
 }["bivarianceHack"]
 
 /**
@@ -73,13 +86,14 @@ export interface SyncDefinition<
   TId extends string = string,
   TConnector extends ConnectorDefinition = ConnectorDefinition,
   TCheckpoint = unknown,
+  TMode extends SyncMode = SyncMode,
 > {
   readonly kind: "sync"
   readonly id: TId
-  readonly config: BatchSyncDefinitionConfig
+  readonly config: BatchSyncDefinitionConfig<TMode>
   readonly triggers: readonly ScheduleReference[]
   readonly connector: TConnector
-  readonly read: SyncReadHandler<TConnector["adapter"], TCheckpoint>
+  readonly read: SyncReadHandler<TConnector["adapter"], TCheckpoint, TMode>
   readonly target: DatasetSyncTarget
 }
 
@@ -87,26 +101,36 @@ export interface SyncTargetBuilder<
   TId extends string = string,
   TConnector extends ConnectorDefinition = ConnectorDefinition,
   TCheckpoint = never,
+  TMode extends SyncMode = SyncMode,
 > {
-  intoDataset(dataset: DatasetDefinition): SyncDefinition<TId, TConnector, TCheckpoint>
+  intoDataset<TDataset extends DatasetDefinition>(
+    dataset: TMode extends "merge"
+      ? TDataset & { readonly primaryKey: DatasetPrimaryKey }
+      : TDataset
+  ): SyncDefinition<TId, TConnector, TCheckpoint, TMode>
 }
 
 export interface SyncReadBuilder<
   TId extends string = string,
   TConnector extends ConnectorDefinition = ConnectorDefinition,
   TCheckpoint = never,
+  TMode extends SyncMode = SyncMode,
 > {
   read(
-    handler: SyncReadHandler<TConnector["adapter"], TCheckpoint>
-  ): SyncTargetBuilder<TId, TConnector, TCheckpoint>
+    handler: SyncReadHandler<TConnector["adapter"], TCheckpoint, TMode>
+  ): SyncTargetBuilder<TId, TConnector, TCheckpoint, TMode>
 }
 
-export interface SyncBuilder<TId extends string = string, TCheckpoint = never> {
-  when(schedule: ScheduleDefinition): SyncBuilder<TId, TCheckpoint>
-  checkpoint<TNextCheckpoint>(): SyncBuilder<TId, TNextCheckpoint>
+export interface SyncBuilder<
+  TId extends string = string,
+  TCheckpoint = never,
+  TMode extends SyncMode = SyncMode,
+> {
+  when(schedule: ScheduleDefinition): SyncBuilder<TId, TCheckpoint, TMode>
+  checkpoint<TNextCheckpoint>(): SyncBuilder<TId, TNextCheckpoint, TMode>
   from<TConnector extends ConnectorDefinition>(
     connector: TConnector
-  ): SyncReadBuilder<TId, TConnector, TCheckpoint>
+  ): SyncReadBuilder<TId, TConnector, TCheckpoint, TMode>
 }
 
 /** Runtime type guard for values discovered from `syncs/` modules. */
@@ -120,7 +144,9 @@ export function isSyncDefinition(value: unknown): value is SyncDefinition {
     typeof value.id === "string" &&
     isRecord(value.config) &&
     value.config.kind === "batch" &&
-    (value.config.mode === "snapshot" || value.config.mode === "append") &&
+    (value.config.mode === "snapshot" ||
+      value.config.mode === "append" ||
+      value.config.mode === "merge") &&
     Array.isArray(value.triggers) &&
     (value.triggers as unknown[]).every((reference) => isScheduleReference(reference)) &&
     isConnectorDefinition(value.connector) &&