@sixb/core 0.1.6 → 0.1.8

package/src/authorization/decision.ts

@@ -13,7 +13,8 @@
 import type { AuthSessionAudience } from "../auth/audience"
 import {
   type ResolvedRuntimeAuthorization,
-  resolveRuntimeAuthorization,
+  resolveExecutionScopeAuthorization,
+  resolveRuntimeAuthorizationForProject,
 } from "../execution/authorization"
 import type { ExecutionContext, RuntimeAuthorization } from "../execution/types"
 import { AuthorizationError } from "./errors"
@@ -28,11 +29,14 @@ export type AuthzRequest =
   | { readonly kind: "object.edit"; readonly objectTypeId: string }
   | { readonly kind: "telemetry.append"; readonly objectTypeId: string }
   | { readonly kind: "action.apply"; readonly actionId: string }
+  | { readonly kind: "share.manage"; readonly shareId: string }
   | { readonly kind: "workflow.run"; readonly workflowId: string }
   | { readonly kind: "sync.run"; readonly syncId: string }
   | { readonly kind: "pipeline.run"; readonly pipelineId: string }
-  | { readonly kind: "agent.run"; readonly agentId: string }
+  | { readonly kind: "agent.run" }
   | { readonly kind: "logs.observe" }
+  | { readonly kind: "aiUsage.observe" }
+  | { readonly kind: "aiUsage.manage" }
   | { readonly kind: "connector.manage"; readonly connectorId: string }
   | { readonly kind: "object.query"; readonly touchedObjectTypeIds: readonly string[] }
 
@@ -45,6 +49,7 @@ export interface AuthzDecision {
 }
 
 interface AuthorizedRuntime {
+  readonly projectId: string
   readonly runtimeAuthorization?: RuntimeAuthorization
   readonly authorization?: AuthorizationContext
 }
@@ -53,10 +58,9 @@ interface AuthorizedRuntime {
 // the single unit that both names a requirement and tests the grant index, so
 // the two can never drift. `kind` is the resolved-index key, so enforcement is
 // a direct lookup with no per-target dispatch.
-interface Atom {
-  readonly kind: GrantKind
-  readonly id: string
-}
+type Atom =
+  | { readonly kind: "run:agent" }
+  | { readonly kind: Exclude<GrantKind, "run:agent">; readonly id: string }
 
 function atomsFor(request: AuthzRequest): readonly Atom[] {
   switch (request.kind) {
@@ -72,6 +76,8 @@ function atomsFor(request: AuthzRequest): readonly Atom[] {
       return [{ kind: "append:telemetry", id: request.objectTypeId }]
     case "action.apply":
       return [{ kind: "apply:action", id: request.actionId }]
+    case "share.manage":
+      return [{ kind: "share:share", id: request.shareId }]
     case "workflow.run":
       return [{ kind: "run:workflow", id: request.workflowId }]
     case "sync.run":
@@ -79,9 +85,13 @@ function atomsFor(request: AuthzRequest): readonly Atom[] {
     case "pipeline.run":
       return [{ kind: "run:pipeline", id: request.pipelineId }]
     case "agent.run":
-      return [{ kind: "run:agent", id: request.agentId }]
+      return [{ kind: "run:agent" }]
     case "logs.observe":
       return [{ kind: "observe:logs", id: "logs" }]
+    case "aiUsage.observe":
+      return [{ kind: "observe:aiUsage", id: "aiUsage" }]
+    case "aiUsage.manage":
+      return [{ kind: "manage:aiUsage", id: "aiUsage" }]
     case "connector.manage":
       return [{ kind: "manage:connector", id: request.connectorId }]
     case "object.query":
@@ -90,11 +100,19 @@ function atomsFor(request: AuthzRequest): readonly Atom[] {
 }
 
 function atomKey(atom: Atom): string {
-  if (atom.kind === "observe:logs") return atom.kind
+  if (atom.kind === "run:agent") return atom.kind
+  if (
+    atom.kind === "observe:logs" ||
+    atom.kind === "observe:aiUsage" ||
+    atom.kind === "manage:aiUsage"
+  ) {
+    return atom.kind
+  }
   return `${atom.kind}:${atom.id}`
 }
 
 function holds(grants: GrantIndex, atom: Atom): boolean {
+  if (atom.kind === "run:agent") return grants[atom.kind]
   return grants[atom.kind].has(atom.id)
 }
 
@@ -120,6 +138,12 @@ export function isAllowed(
 
 export function assertAuthorized(runtime: AuthorizedRuntime, request: AuthzRequest): void {
   const resolved = assertRuntimeAuthorizationBound(runtime)
+  if (resolved.type === "delegated") {
+    throw new AuthorizationError(
+      `delegated:${request.kind}`,
+      `[Sixb] Operation '${request.kind}' is not covered by delegated authorization.`
+    )
+  }
   const authorization = resolved.type === "principal" ? resolved.context : undefined
   const decision = evaluate(authorization, request)
   if (decision.allowed) {
@@ -132,11 +156,18 @@ export function assertAuthorized(runtime: AuthorizedRuntime, request: AuthzReque
   )
 }
 
+/** Runtime catalogs never infer unrestricted access from an absent principal context. */
+export function isRuntimeAllowed(runtime: AuthorizedRuntime, request: AuthzRequest): boolean {
+  const authority = resolveRuntimeAuthorizationForProject(runtime)
+  if (authority.type === "denied" || authority.type === "delegated") return false
+  return authority.type === "unrestricted" || isAllowed(authority.context, request)
+}
+
 /** Resolve registered process-local authority before a protected leaf makes a decision. */
 export function assertRuntimeAuthorizationBound(
   runtime: AuthorizedRuntime
 ): Exclude<ResolvedRuntimeAuthorization, { readonly type: "denied" }> {
-  const resolved = resolveRuntimeAuthorization(runtime.runtimeAuthorization)
+  const resolved = resolveRuntimeAuthorizationForProject(runtime)
   if (resolved.type === "denied") {
     throw new AuthorizationError(
       "runtime:unbound",
@@ -205,27 +236,22 @@ export function assertPrivileged(runtime: AuthorizedRuntime, operation: string):
  * Assert access to process providers that trusted executions and genuine agent runs may use.
  *
  * Agent provenance alone is not authority: the registered capability must be bound to the exact
- * same agent and run before this check succeeds.
+ * same immutable execution before this check succeeds.
  */
 export function assertProviderAccess(
-  runtime: AuthorizedRuntime,
+  runtime: AuthorizedRuntime & { readonly runtimeAuthorization: RuntimeAuthorization },
   execution: ExecutionContext,
   operation: string
 ): void {
-  const resolved = assertRuntimeAuthorizationBound(runtime)
+  const resolved = resolveExecutionScopeAuthorization(runtime.projectId, {
+    execution,
+    authorization: runtime.runtimeAuthorization,
+  })
   if (resolved.type === "unrestricted") {
     return
   }
 
-  const binding = resolved.executionBinding
-  const executor = execution.executor
-  if (
-    binding?.type === "agent" &&
-    executor.type === "agent" &&
-    binding.executionId === execution.id &&
-    binding.agentId === executor.agentId &&
-    binding.runId === executor.runId
-  ) {
+  if (execution.executor.type === "agent") {
     return
   }
 
@@ -253,6 +279,8 @@ function deniedMessage(
       return `[Sixb] Principal '${principalId}' is not allowed to append telemetry for object type '${request.objectTypeId}'.`
     case "action.apply":
       return `[Sixb] Principal '${principalId}' is not allowed to apply action '${request.actionId}'.`
+    case "share.manage":
+      return `[Sixb] Principal '${principalId}' is not allowed to manage Share '${request.shareId}'.`
     case "workflow.run":
       return `[Sixb] Principal '${principalId}' is not allowed to run workflow '${request.workflowId}'.`
     case "sync.run":
@@ -260,9 +288,13 @@ function deniedMessage(
     case "pipeline.run":
       return `[Sixb] Principal '${principalId}' is not allowed to run pipeline '${request.pipelineId}'.`
     case "agent.run":
-      return `[Sixb] Principal '${principalId}' is not allowed to run agent '${request.agentId}'.`
+      return `[Sixb] Principal '${principalId}' is not allowed to run the project Agent.`
     case "logs.observe":
       return `[Sixb] Principal '${principalId}' is not allowed to observe project logs.`
+    case "aiUsage.observe":
+      return `[Sixb] Principal '${principalId}' is not allowed to observe project AI usage.`
+    case "aiUsage.manage":
+      return `[Sixb] Principal '${principalId}' is not allowed to manage project AI usage limits.`
     case "connector.manage":
       return `[Sixb] Principal '${principalId}' is not allowed to manage connector '${request.connectorId}'.`
     case "object.query": {

package/src/authorization/grant-kinds.ts

@@ -8,7 +8,7 @@
  * entry in `GRANT_KINDS` plus the compile errors that forces at every consumer.
  */
 
-import type { GrantDefinition } from "../security/types"
+import type { AgentRunGrant, GrantDefinition } from "../security/types"
 
 export type GrantKind =
   | "access:application"
@@ -17,12 +17,18 @@ export type GrantKind =
   | "edit:object"
   | "append:telemetry"
   | "apply:action"
+  | "share:share"
   | "run:workflow"
   | "run:sync"
   | "run:pipeline"
   | "run:agent"
   | "observe:logs"
+  | "observe:aiUsage"
   | "manage:connector"
+  | "manage:aiUsage"
+
+export type SingletonGrantKind = "run:agent"
+export type TargetedGrantKind = Exclude<GrantKind, SingletonGrantKind>
 
 /** Registered id universes a grant kind ranges over, plus subtype expansion. */
 export interface GrantUniverse {
@@ -30,19 +36,20 @@ export interface GrantUniverse {
   readonly objectTypeIds: ReadonlySet<string>
   readonly datasetIds: ReadonlySet<string>
   readonly actionIds: ReadonlySet<string>
+  readonly shareIds: ReadonlySet<string>
   readonly workflowIds: ReadonlySet<string>
   readonly syncIds: ReadonlySet<string>
   readonly pipelineIds: ReadonlySet<string>
-  readonly agentIds: ReadonlySet<string>
   readonly observableIds: ReadonlySet<string>
   readonly connectorIds: ReadonlySet<string>
+  readonly manageableIds: ReadonlySet<string>
   readonly getSubTypes: (objectTypeId: string) => readonly string[]
 }
 
 /** The registered-id sets a grant kind validates against (no subtype hook). */
 export type GrantUniverseKey = Exclude<keyof GrantUniverse, "getSubTypes">
 
-interface GrantKindSpec {
+interface TargetedGrantKindSpec {
   /** Registered universe the grant's ids must belong to. */
   readonly universeKey: GrantUniverseKey
   /** Subject noun used in validation errors ("unknown <subject> '<id>'"). */
@@ -53,11 +60,22 @@ interface GrantKindSpec {
   readonly expandsSubtypes?: true
 }
 
+interface SingletonGrantKindSpec {
+  /** Project-wide capability with no resource selection; resolves to a boolean. */
+  readonly singleton: true
+  readonly subject: string
+  readonly fix: string
+}
+
 /**
  * The exhaustive grant-kind table. A new grant family is one entry here; the
- * `Record<GrantKind, …>` makes every omission a compile error.
+ * mapped type makes every omission a compile error.
  */
-export const GRANT_KINDS: Record<GrantKind, GrantKindSpec> = {
+export const GRANT_KINDS: {
+  readonly [TKind in GrantKind]: TKind extends SingletonGrantKind
+    ? SingletonGrantKindSpec
+    : TargetedGrantKindSpec
+} = {
   "access:application": {
     universeKey: "applicationIds",
     subject: "application",
@@ -92,6 +110,11 @@ export const GRANT_KINDS: Record<GrantKind, GrantKindSpec> = {
     subject: "action",
     fix: "Add it to 'actions/' or pass it to createSixb({ actions }).",
   },
+  "share:share": {
+    universeKey: "shareIds",
+    subject: "share",
+    fix: "Add it to 'shares/' or pass it to createSixb({ shares }).",
+  },
   "run:workflow": {
     universeKey: "workflowIds",
     subject: "workflow",
@@ -108,25 +131,41 @@ export const GRANT_KINDS: Record<GrantKind, GrantKindSpec> = {
     fix: "Add it to 'pipelines/' or pass it to createSixb({ pipelines }).",
   },
   "run:agent": {
-    universeKey: "agentIds",
+    singleton: true,
     subject: "agent",
-    fix: "Add it to 'agents/' or pass it to createSixb({ agents }).",
+    fix: "Configure models.language and use the exported agent reference in can.run(agent).",
   },
   "observe:logs": {
     universeKey: "observableIds",
     subject: "observability surface",
     fix: 'Use can.observe("logs").',
   },
+  "observe:aiUsage": {
+    universeKey: "observableIds",
+    subject: "observability surface",
+    fix: "Use can.observe(agent.usage).",
+  },
   "manage:connector": {
     universeKey: "connectorIds",
     subject: "connector",
     fix: "Add it to 'connectors/' or pass it to createSixb({ connectors }).",
   },
+  "manage:aiUsage": {
+    universeKey: "manageableIds",
+    subject: "management surface",
+    fix: "Use can.manage(agent.usage).",
+  },
 }
 
 export const GRANT_KIND_KEYS = Object.keys(GRANT_KINDS) as readonly GrantKind[]
+export const TARGETED_GRANT_KIND_KEYS = GRANT_KIND_KEYS.filter(
+  (kind): kind is TargetedGrantKind => kind !== "run:agent"
+)
 
 /** The grant kind a stored grant resolves to. */
+export function grantKindOf(grant: AgentRunGrant): SingletonGrantKind
+export function grantKindOf(grant: Exclude<GrantDefinition, AgentRunGrant>): TargetedGrantKind
+export function grantKindOf(grant: GrantDefinition): GrantKind
 export function grantKindOf(grant: GrantDefinition): GrantKind {
   switch (grant.capability) {
     case "access":
@@ -139,20 +178,38 @@ export function grantKindOf(grant: GrantDefinition): GrantKind {
       return "append:telemetry"
     case "apply":
       return "apply:action"
+    case "share":
+      return "share:share"
     case "run":
       return `run:${grant.target}`
     case "observe":
-      return "observe:logs"
+      return `observe:${grant.target}`
     case "manage":
-      return "manage:connector"
+      return `manage:${grant.target}`
   }
 }
 
-/** A fresh, mutable grant index with one empty id set per kind. */
-export function emptyGrantSets(): Record<GrantKind, Set<string>> {
-  const sets = {} as Record<GrantKind, Set<string>>
-  for (const kind of GRANT_KIND_KEYS) {
-    sets[kind] = new Set<string>()
+/** Mutable grant index: booleans for singleton capabilities, id sets for selected resources. */
+export type MutableGrantIndex = {
+  [TKind in GrantKind]: TKind extends SingletonGrantKind ? boolean : Set<string>
+}
+
+export function emptyGrantSets(): MutableGrantIndex {
+  return {
+    "access:application": new Set(),
+    "view:object": new Set(),
+    "view:dataset": new Set(),
+    "edit:object": new Set(),
+    "append:telemetry": new Set(),
+    "apply:action": new Set(),
+    "share:share": new Set(),
+    "run:workflow": new Set(),
+    "run:sync": new Set(),
+    "run:pipeline": new Set(),
+    "run:agent": false,
+    "observe:logs": new Set(),
+    "observe:aiUsage": new Set(),
+    "manage:connector": new Set(),
+    "manage:aiUsage": new Set(),
   }
-  return sets
 }

package/src/authorization/index.ts

@@ -7,8 +7,10 @@ export {
   assertCanManageConnector,
   assertPrivileged,
   assertProviderAccess,
+  assertRuntimeAuthorizationBound,
   evaluate,
   isAllowed,
+  isRuntimeAllowed,
 } from "./decision"
 export { AuthorizationError } from "./errors"
 export { canViewEvent } from "./event-visibility"

package/src/authorization/resolve.ts

@@ -2,19 +2,19 @@ import type { Principal } from "../auth/types"
 import type { RoleDefinition, Selection } from "../security"
 import {
   emptyGrantSets,
-  GRANT_KIND_KEYS,
   GRANT_KINDS,
   type GrantUniverse,
   grantKindOf,
+  TARGETED_GRANT_KIND_KEYS,
 } from "./grant-kinds"
 import type { AuthorizationContext, GrantIndex, ResolvedRole } from "./types"
 
 /**
- * Expand a role's grants into concrete id sets once at startup.
+ * Resolve a role's grants once at startup.
  *
  * Broad grants (`every.object().except([...])`) expand against the registered
- * universe; object-type grants also expand to subtypes. The result holds only
- * `Set`s, so per-request resolution and runtime checks stay simple `set.has`.
+ * universe; object-type grants also expand to subtypes. Resource grants become
+ * id sets; the project Agent grant becomes a boolean.
  * The per-kind universe and subtype rules come from the `GRANT_KINDS` table, so
  * this loop never enumerates targets by hand.
  */
@@ -22,6 +22,10 @@ export function resolveRoleGrants(role: RoleDefinition, universe: GrantUniverse)
   const grants = emptyGrantSets()
 
   for (const grant of role.grants) {
+    if (grant.capability === "run" && grant.target === "agent") {
+      grants["run:agent"] = true
+      continue
+    }
     const kind = grantKindOf(grant)
     const spec = GRANT_KINDS[kind]
     expandSelection(
@@ -84,7 +88,10 @@ export function resolveAuthorizationContext(input: {
     }
 
     roleIds.push(role.id)
-    for (const kind of GRANT_KIND_KEYS) {
+    if (role.grants["run:agent"]) {
+      grants["run:agent"] = true
+    }
+    for (const kind of TARGETED_GRANT_KIND_KEYS) {
       for (const id of role.grants[kind]) {
         grants[kind].add(id)
       }

package/src/authorization/types.ts

@@ -8,16 +8,18 @@
  */
 
 import type { Principal } from "../auth/types"
-import { emptyGrantSets, type GrantKind } from "./grant-kinds"
+import { emptyGrantSets, type GrantKind, type SingletonGrantKind } from "./grant-kinds"
 
 /**
- * Grants resolved to concrete id sets, keyed by grant kind (`view:object`,
- * `run:sync`, …). Broad grants and object subtypes are already expanded, so
- * enforcement is a single `grants[kind].has(id)` lookup. Keyed by `GrantKind`
+ * Grants keyed by kind (`view:object`, `run:sync`, …). Resource selections resolve
+ * to id sets; project-wide singleton capabilities resolve to booleans.
+ * Broad grants and object subtypes are already expanded. Keyed by `GrantKind`
  * so a new grant family adds one key, not a new bucket every consumer must
  * learn.
  */
-export type GrantIndex = Readonly<Record<GrantKind, ReadonlySet<string>>>
+export type GrantIndex = Readonly<{
+  [TKind in GrantKind]: TKind extends SingletonGrantKind ? boolean : ReadonlySet<string>
+}>
 
 /**
  * A grant index that grants nothing, as the base for a hand-built context — typically in tests.

package/src/bootstrap/discovery.ts

@@ -10,7 +10,6 @@ import { readdir } from "node:fs/promises"
 import { join, relative } from "node:path"
 import { pathToFileURL } from "node:url"
 import { isActionDefinition } from "../actions"
-import { isAgentDefinition } from "../agents"
 import { isConnectorDefinition } from "../connectors"
 import { isDatasetDefinition } from "../datasets"
 import type { OntologyDocumentInput, OntologySource } from "../ontology/registry"
@@ -22,6 +21,7 @@ import { isRuleDefinition } from "../rules"
 import { RuntimeError } from "../runtime/errors"
 import { isScheduleDefinition } from "../schedules"
 import { isGroupDefinition, isMembershipPolicyDefinition, isRoleDefinition } from "../security"
+import { isShareDefinition } from "../shares"
 import { isSyncDefinition } from "../syncs"
 import { isWorkflowDefinition } from "../workflows"
 
@@ -73,7 +73,6 @@ export async function discoverOntologySources(
 
 type DiscoveryModuleKind =
   | "action"
-  | "agent"
   | "connector"
   | "dataset"
   | "group"
@@ -84,6 +83,7 @@ type DiscoveryModuleKind =
   | "role"
   | "rule"
   | "schedule"
+  | "share"
   | "sync"
   | "workflow"
 
@@ -138,7 +138,7 @@ const definitionDiscoveryRegistry = {
     kind: "membershipPolicy",
     isDefinition: isMembershipPolicyDefinition,
   },
-  agents: { directory: ["agents"], kind: "agent", isDefinition: isAgentDefinition },
+  shares: { directory: ["shares"], kind: "share", isDefinition: isShareDefinition },
 } as const satisfies Record<string, DefinitionDiscoveryFamily<unknown>>
 
 type DefinitionFromFamily<TFamily> =

package/src/bootstrap/ontology-type-manifest.ts

@@ -1,4 +1,4 @@
-import { mkdir, readdir, readFile, writeFile } from "node:fs/promises"
+import { access, mkdir, readdir, readFile, writeFile } from "node:fs/promises"
 import { dirname, extname, join, relative, resolve, sep } from "node:path"
 import { pathToFileURL } from "node:url"
 import type { OntologyDocumentInput } from "../ontology/registry"
@@ -75,11 +75,17 @@ export async function generateOntologyTypeManifest(
   const discovery = await discoverOntologyTypeManifest(projectRoot)
 
   if (discovery.moduleCount === 0) {
-    return {
-      ...discovery,
-      path: outFile,
-      written: false,
-      skipped: true,
+    // Leave projects without ontology untouched, but clear a previously generated map.
+    try {
+      await access(outFile)
+    } catch (error) {
+      if (!isNotFoundError(error)) throw error
+      return {
+        ...discovery,
+        path: outFile,
+        written: false,
+        skipped: true,
+      }
     }
   }
 

package/src/datasets/builders.ts

@@ -15,6 +15,7 @@ type DatasetColumnOptions = {
 type DefineDatasetOptions = {
   readonly schema: readonly DatasetColumnDefinition[]
   readonly primaryKey?: DatasetPrimaryKey
+  readonly sequenceBy?: string
   readonly partitionBy?: readonly string[]
   readonly description?: string
 }
@@ -23,6 +24,7 @@ type DeriveDatasetOptions<TParent extends DatasetDefinition> = {
   readonly pick?: readonly DatasetColumnNameOf<TParent>[]
   readonly add?: readonly DatasetColumnDefinition[]
   readonly primaryKey?: DatasetPrimaryKey
+  readonly sequenceBy?: string
   readonly partitionBy?: readonly string[]
   readonly description?: string
 }
@@ -58,8 +60,22 @@ type PrimaryKeyColumnNameOf<TColumns extends readonly DatasetColumnDefinition[]>
 
 type CheckedDefineDatasetOptions<TOptions extends DefineDatasetOptions> = TOptions & {
   readonly primaryKey?: DatasetPrimaryKey<PrimaryKeyColumnNameOf<TOptions["schema"]>>
+  readonly sequenceBy?: SequenceColumnNameOf<TOptions["schema"]>
 }
 
+type SequenceColumnNameOf<TColumns extends readonly DatasetColumnDefinition[]> =
+  string extends ColumnNameOf<TColumns>
+    ? string
+    : {
+        [TName in ColumnNameOf<TColumns>]: ColumnDefinitionOf<TColumns, TName>["type"] extends
+          | "timestamp"
+          | "int64"
+          ? ColumnDefinitionOf<TColumns, TName> extends { readonly nullable: true }
+            ? never
+            : TName
+          : never
+      }[ColumnNameOf<TColumns>]
+
 type PickColumns<
   TColumns extends readonly DatasetColumnDefinition[],
   TNames extends readonly ColumnNameOf<TColumns>[],
@@ -107,8 +123,9 @@ type DatasetColumnResult<
 
 type DatasetDefinitionResult<TId extends string, TOptions extends DefineDatasetOptions> = Omit<
   DatasetDefinition<TId, TOptions["schema"]>,
-  "primaryKey" | "partitionBy" | "description"
+  "primaryKey" | "sequenceBy" | "partitionBy" | "description"
 > &
+  FieldFromOptions<TOptions, "sequenceBy", string> &
   FieldFromOptions<TOptions, "primaryKey", DatasetPrimaryKey> &
   FieldFromOptions<TOptions, "partitionBy", readonly string[]> &
   FieldFromOptions<TOptions, "description", string>
@@ -119,8 +136,9 @@ type DerivedDatasetDefinitionResult<
   TOptions extends DeriveDatasetOptions<TParent> | undefined,
 > = Omit<
   DatasetDefinition<TId, DerivedColumns<TParent, TOptions>>,
-  "primaryKey" | "partitionBy" | "description"
+  "primaryKey" | "sequenceBy" | "partitionBy" | "description"
 > &
+  FieldFromOptions<TOptions, "sequenceBy", string> &
   FieldFromOptions<TOptions, "primaryKey", DatasetPrimaryKey> &
   FieldFromOptions<TOptions, "partitionBy", readonly string[]> &
   FieldFromOptions<TOptions, "description", string>
@@ -130,6 +148,7 @@ type CheckedDeriveDatasetOptions<
   TOptions extends DeriveDatasetOptions<TParent>,
 > = TOptions & {
   readonly primaryKey?: DatasetPrimaryKey<PrimaryKeyColumnNameOf<DerivedColumns<TParent, TOptions>>>
+  readonly sequenceBy?: SequenceColumnNameOf<DerivedColumns<TParent, TOptions>>
 }
 
 export function col<const TName extends string, const TType extends DatasetColumnType>(
@@ -177,6 +196,7 @@ function createDatasetDefinition(id: string, options: DefineDatasetOptions): Dat
         }
       : {}),
     ...(options.partitionBy !== undefined ? { partitionBy: [...options.partitionBy] } : {}),
+    ...(options.sequenceBy !== undefined ? { sequenceBy: options.sequenceBy } : {}),
     ...(options.description !== undefined ? { description: options.description } : {}),
   }
 
@@ -230,6 +250,7 @@ function deriveDatasetDefinition(
   return createDatasetDefinition(id, {
     schema: [...pickedColumns, ...(options.add ?? [])],
     ...(options.primaryKey !== undefined ? { primaryKey: options.primaryKey } : {}),
+    ...(options.sequenceBy !== undefined ? { sequenceBy: options.sequenceBy } : {}),
     ...(options.partitionBy !== undefined ? { partitionBy: options.partitionBy } : {}),
     ...(options.description !== undefined ? { description: options.description } : {}),
   })

package/src/datasets/changes.ts

@@ -1,13 +1,25 @@
 export type MergeChange<Row, Key> =
   | { readonly kind: "upsert"; readonly row: Row }
-  | { readonly kind: "delete"; readonly key: Key }
+  | { readonly kind: "delete"; readonly key: Key; readonly sequence?: string | number | Date }
 
 export const change = {
   upsert<const Row extends object>(row: Row): { readonly kind: "upsert"; readonly row: Row } {
     return { kind: "upsert", row }
   },
 
-  delete<const Key extends object>(key: Key): { readonly kind: "delete"; readonly key: Key } {
-    return { kind: "delete", key }
-  },
+  delete: deleteChange,
+}
+
+function deleteChange<const Key extends object>(
+  key: Key
+): { readonly kind: "delete"; readonly key: Key }
+function deleteChange<const Key extends object, const Sequence extends string | number | Date>(
+  key: Key,
+  options: { readonly sequence: Sequence }
+): { readonly kind: "delete"; readonly key: Key; readonly sequence: Sequence }
+function deleteChange<Key extends object>(
+  key: Key,
+  options?: { readonly sequence: string | number | Date }
+): { readonly kind: "delete"; readonly key: Key; readonly sequence?: string | number | Date } {
+  return { kind: "delete", key, ...(options ? { sequence: options.sequence } : {}) }
 }