@sixb/core 0.1.3 → 0.1.5

package/src/agents/context-compaction.ts

@@ -0,0 +1,261 @@
+import { stableJsonStringify } from "../json"
+import type { AgentMessageRecord } from "../storage/agents/types"
+import type { AgentMessage, AgentMessagePart } from "./message"
+
+export const AGENT_CONTEXT_ESTIMATOR_VERSION = 1 as const
+
+const CHARS_PER_TOKEN = 4
+const REQUEST_OVERHEAD_TOKENS = 8
+const MESSAGE_OVERHEAD_TOKENS = 8
+const TOOL_OVERHEAD_TOKENS = 16
+const STEP_OVERHEAD_TOKENS = 2
+const IMAGE_ALLOWANCE_TOKENS = 1_200
+const FILE_TEXT_INLINE_MAX_BYTES = 50 * 1024
+const FILE_TEXT_INLINE_TOTAL_MAX_BYTES = 200 * 1024
+const TOOL_RESULT_SUMMARY_MAX_CHARS = 2_000
+
+export interface AgentContextEstimateTool {
+  readonly name: string
+  readonly description: string
+  /** Deterministic JSON-schema serialization sent for this tool. */
+  readonly inputSchema: string
+}
+
+export interface EstimateAgentContextRequestTokensInput {
+  readonly systemPrompt: string
+  readonly tools: readonly AgentContextEstimateTool[]
+  readonly messages: readonly AgentMessage[]
+}
+
+export interface AgentContextTokenEstimate {
+  readonly tokens: number
+  readonly estimatorVersion: typeof AGENT_CONTEXT_ESTIMATOR_VERSION
+}
+
+export interface AgentContextCompactionBoundary {
+  readonly messagesToSummarize: readonly AgentMessageRecord[]
+  readonly retainedMessages: readonly AgentMessageRecord[]
+  readonly summarizedThroughSeq: number
+}
+
+/** Compaction begins only once the estimated request crosses the reserved input budget. */
+export function shouldCompactAgentContext(input: {
+  readonly estimatedInputTokens: number
+  readonly inputBudgetTokens: number
+}): boolean {
+  return input.estimatedInputTokens > input.inputBudgetTokens
+}
+
+/** Estimate the provider request shape with one stable, conservative character heuristic. */
+export function estimateAgentContextRequestTokens(
+  input: EstimateAgentContextRequestTokensInput
+): AgentContextTokenEstimate {
+  const toolTokens = input.tools.reduce(
+    (total, tool) =>
+      total +
+      TOOL_OVERHEAD_TOKENS +
+      textTokens(tool.name) +
+      textTokens(tool.description) +
+      textTokens(tool.inputSchema),
+    0
+  )
+  return {
+    tokens:
+      REQUEST_OVERHEAD_TOKENS +
+      textTokens(input.systemPrompt) +
+      toolTokens +
+      estimateAgentContextMessagesTokens(input.messages).tokens,
+    estimatorVersion: AGENT_CONTEXT_ESTIMATOR_VERSION,
+  }
+}
+
+/** Estimate message-only growth after a provider-usage anchor. */
+export function estimateAgentContextMessagesTokens(
+  messages: readonly AgentMessage[]
+): AgentContextTokenEstimate {
+  const attachments = { textBytesRemaining: FILE_TEXT_INLINE_TOTAL_MAX_BYTES }
+  let tokens = 0
+  for (const message of messages) {
+    tokens += estimateMessageTokens(message, attachments)
+  }
+  return { tokens, estimatorVersion: AGENT_CONTEXT_ESTIMATOR_VERSION }
+}
+
+/** Select the safe user boundary whose retained tail is closest to the configured recent budget. */
+export function selectAgentContextCompactionBoundary(input: {
+  readonly messages: readonly AgentMessageRecord[]
+  readonly keepRecentTokens: number
+}): AgentContextCompactionBoundary | null {
+  if (input.messages.length < 2) return null
+
+  let retainedTokens = 0
+  let boundaryIndex: number | null = null
+  let closestDistance = Number.POSITIVE_INFINITY
+  for (let index = input.messages.length - 1; index > 0; index -= 1) {
+    retainedTokens += estimateAgentContextMessagesTokens([input.messages[index]!]).tokens
+    if (input.messages[index]?.role !== "user") continue
+
+    const distance = Math.abs(input.keepRecentTokens - retainedTokens)
+    if (distance <= closestDistance) {
+      boundaryIndex = index
+      closestDistance = distance
+    }
+    if (retainedTokens >= input.keepRecentTokens) break
+  }
+
+  if (boundaryIndex === null) return null
+
+  const summarizedThroughSeq = input.messages[boundaryIndex - 1]?.seq
+  if (summarizedThroughSeq === undefined) return null
+  return {
+    messagesToSummarize: input.messages.slice(0, boundaryIndex),
+    retainedMessages: input.messages.slice(boundaryIndex),
+    summarizedThroughSeq,
+  }
+}
+
+/** Serialize durable conversation content as escaped quoted data for the summary model. */
+export function serializeAgentMessagesForSummary(messages: readonly AgentMessageRecord[]): string {
+  const lines = ["<sixb_conversation_history>"]
+  for (const message of messages) {
+    lines.push(
+      `  <message id="${escapeXml(message.id)}" seq="${message.seq}" role="${message.role}">`
+    )
+    message.parts.forEach((part, partIndex) => {
+      lines.push(...serializeSummaryPart(message, part, partIndex))
+    })
+    lines.push("  </message>")
+  }
+  lines.push("</sixb_conversation_history>")
+  return lines.join("\n")
+}
+
+function estimateMessageTokens(
+  message: AgentMessage,
+  attachments: { textBytesRemaining: number }
+): number {
+  let tokens = MESSAGE_OVERHEAD_TOKENS
+  for (const part of message.parts) {
+    switch (part.type) {
+      case "text":
+      case "reasoning":
+        tokens += textTokens(part.text)
+        break
+      case "step-start":
+        tokens += STEP_OVERHEAD_TOKENS
+        break
+      case "context":
+        tokens += textTokens(stableJsonStringify(part.context))
+        break
+      case "tool-call":
+        tokens +=
+          TOOL_OVERHEAD_TOKENS +
+          textTokens(part.toolName) +
+          textTokens(stableJsonStringify(part.input)) +
+          (part.state === "output-available"
+            ? textTokens(stableJsonStringify(part.output))
+            : textTokens(part.errorText))
+        break
+      case "file": {
+        const file = part.fileRef
+        tokens += textTokens(
+          [file.blobId, file.digest, file.fileName, file.mediaType, file.logicalPath]
+            .filter((value): value is string => value !== undefined)
+            .join(" ")
+        )
+        if (message.role !== "assistant") {
+          if (looksLikeImage(file.mediaType, file.fileName)) {
+            tokens += IMAGE_ALLOWANCE_TOKENS
+          } else {
+            const inlineBytes = Math.min(
+              file.sizeBytes,
+              FILE_TEXT_INLINE_MAX_BYTES,
+              attachments.textBytesRemaining
+            )
+            attachments.textBytesRemaining -= inlineBytes
+            tokens += Math.ceil(inlineBytes / CHARS_PER_TOKEN)
+          }
+        }
+        break
+      }
+    }
+  }
+  return tokens
+}
+
+function serializeSummaryPart(
+  message: AgentMessageRecord,
+  part: AgentMessagePart,
+  partIndex: number
+): string[] {
+  const indent = "    "
+  switch (part.type) {
+    case "text":
+      return [`${indent}<text>${escapeXml(part.text)}</text>`]
+    case "reasoning":
+    case "step-start":
+      return []
+    case "context":
+      return part.context.kind === "object"
+        ? [
+            `${indent}<object_context origin="${part.origin}" object_type_id="${escapeXml(part.context.ref.objectTypeId)}" primary_id="${escapeXml(part.context.ref.primaryId)}" />`,
+          ]
+        : [
+            `${indent}<app_context origin="${part.origin}" id="${escapeXml(part.context.id)}" label="${escapeXml(part.context.label)}">`,
+            `${indent}  <description>${escapeXml(part.context.description)}</description>`,
+            `${indent}  <value format="json">${escapeXml(stableJsonStringify(part.context.value))}</value>`,
+            `${indent}</app_context>`,
+          ]
+    case "file": {
+      const file = part.fileRef
+      const attributes = [
+        `message_id="${escapeXml(message.id)}"`,
+        `part_index="${partIndex}"`,
+        `blob_id="${escapeXml(file.blobId)}"`,
+        `digest="${escapeXml(file.digest)}"`,
+        `size_bytes="${file.sizeBytes}"`,
+        ...(file.fileName === undefined ? [] : [`file_name="${escapeXml(file.fileName)}"`]),
+        ...(file.mediaType === undefined ? [] : [`media_type="${escapeXml(file.mediaType)}"`]),
+        ...(file.logicalPath === undefined
+          ? []
+          : [`logical_path="${escapeXml(file.logicalPath)}"`]),
+      ]
+      return [`${indent}<file ${attributes.join(" ")} />`]
+    }
+    case "tool-call": {
+      const output =
+        part.state === "output-available"
+          ? truncateToolResult(stableJsonStringify(part.output))
+          : truncateToolResult(part.errorText)
+      return [
+        `${indent}<tool_call id="${escapeXml(part.toolCallId)}" name="${escapeXml(part.toolName)}" state="${part.state}">`,
+        `${indent}  <input format="json">${escapeXml(stableJsonStringify(part.input))}</input>`,
+        `${indent}  <result>${escapeXml(output)}</result>`,
+        `${indent}</tool_call>`,
+      ]
+    }
+  }
+}
+
+function truncateToolResult(value: string): string {
+  if (value.length <= TOOL_RESULT_SUMMARY_MAX_CHARS) return value
+  return `${value.slice(0, TOOL_RESULT_SUMMARY_MAX_CHARS)}\n[truncated ${value.length - TOOL_RESULT_SUMMARY_MAX_CHARS} characters]`
+}
+
+function looksLikeImage(mediaType: string | undefined, fileName: string | undefined): boolean {
+  if (mediaType?.toLowerCase().startsWith("image/")) return true
+  return /\.(?:avif|gif|jpe?g|png|webp)$/i.test(fileName ?? "")
+}
+
+function textTokens(value: string): number {
+  return Math.ceil(new TextEncoder().encode(value).byteLength / CHARS_PER_TOKEN)
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;")
+}

package/src/agents/ids.ts

@@ -18,6 +18,11 @@ export function createAgentMessageId(): string {
   return `agt_msg_${randomUUID()}`
 }
 
+/** One deterministic context-checkpoint identity per conversational run. */
+export function agentContextCheckpointId(runId: string): string {
+  return `agt_ctx_${runId}`
+}
+
 /** A queue delivery's fencing token for writes to an `agent_runs` record. */
 export function createAgentRunExecutionToken(): string {
   return `agt_exec_${randomUUID()}`

package/src/agents/index.ts

@@ -53,6 +53,20 @@ export {
   MAX_AGENT_CONTEXT_ENTRIES,
   normalizeAgentContextEntries,
 } from "./context"
+export type {
+  AgentContextCompactionBoundary,
+  AgentContextEstimateTool,
+  AgentContextTokenEstimate,
+  EstimateAgentContextRequestTokensInput,
+} from "./context-compaction"
+export {
+  AGENT_CONTEXT_ESTIMATOR_VERSION,
+  estimateAgentContextMessagesTokens,
+  estimateAgentContextRequestTokens,
+  selectAgentContextCompactionBoundary,
+  serializeAgentMessagesForSummary,
+  shouldCompactAgentContext,
+} from "./context-compaction"
 export { serializeAgentContextForModel } from "./context-model"
 export { resolveAgentContextParts } from "./context-resolution"
 export type {
@@ -75,6 +89,7 @@ export {
   AgentToolResultValidationError,
 } from "./errors"
 export {
+  agentContextCheckpointId,
   createAgentMessageId,
   createAgentRunExecutionToken,
   createAgentRunId,
@@ -93,15 +108,6 @@ export {
   type AgentToolCallPart,
   type AgentToolCallState,
 } from "./message"
-export {
-  type BuildAgentSystemPromptInput,
-  type BuildWorkflowOutputFinalizerPromptInput,
-  buildAgentSystemPrompt,
-  buildWorkflowOutputFinalizerPrompt,
-  DEFAULT_AGENT_SYSTEM_CONTEXT,
-  DEFAULT_AGENT_WORKFLOW_SYSTEM_CONTEXT,
-  DEFAULT_WORKFLOW_OUTPUT_FINALIZER_SYSTEM_CONTEXT,
-} from "./prompt"
 export {
   type RequestAgentRunInput,
   type RequestAgentRunResult,
@@ -109,6 +115,7 @@ export {
   retryAgentRun,
 } from "./request"
 export type {
+  AgentCompactionFailureCode,
   AgentRunControlStreamId,
   AgentRunFailure,
   AgentRunFinishedEvent,
@@ -116,6 +123,7 @@ export type {
   AgentRunStreamId,
 } from "./streams"
 export {
+  AGENT_COMPACTION_FAILURE_CODES,
   AGENT_RUN_CANCEL_RECORD,
   AGENT_RUN_STREAM_SCHEMA_VERSION,
   agentRunControlStreamDefinition,
@@ -137,6 +145,7 @@ export type {
 export { projectAgentThreadModelContext } from "./thread-context-projection"
 export { isAgentToolResult } from "./tool-result"
 export type {
+  AgentContextConfig,
   AgentDefinition,
   AgentLoopConfig,
   AgentReasoningLevel,

package/src/agents/streams.ts

@@ -4,6 +4,7 @@ import type { SixbFailure } from "../errors/types"
 import { isJsonValue, isPlainRecord, type JsonValue } from "../json"
 import {
   AGENT_RUN_FAILURE_CODES,
+  type AgentContextCheckpointReason,
   type AgentRunFailureCode,
   type AgentRunRecord,
 } from "../storage/agents/types"
@@ -189,11 +190,35 @@ export async function subscribeAgentRunCancel(
 /** Exact portable failure exposed by a terminal Agent run stream event. */
 export type AgentRunFailure = SixbFailure<AgentRunFailureCode>
 
+export const AGENT_COMPACTION_FAILURE_CODES = [
+  "context_limit_exceeded",
+  "summary_failed",
+  "checkpoint_failed",
+] as const
+export type AgentCompactionFailureCode = (typeof AGENT_COMPACTION_FAILURE_CODES)[number]
+
 export type AgentRunStreamEvent =
   | (AgentRunStreamEventBase & {
       readonly type: "agent.run.started"
       readonly modelId?: string
     })
+  | (AgentRunStreamEventBase & {
+      readonly type: "agent.compaction.started"
+      readonly reason: AgentContextCheckpointReason
+      readonly estimatedInputTokensBefore: number
+    })
+  | (AgentRunStreamEventBase & {
+      readonly type: "agent.compaction.completed"
+      readonly reason: AgentContextCheckpointReason
+      readonly checkpointId: string
+      readonly estimatedInputTokensBefore: number
+      readonly estimatedInputTokensAfter: number
+    })
+  | (AgentRunStreamEventBase & {
+      readonly type: "agent.compaction.failed"
+      readonly reason: AgentContextCheckpointReason
+      readonly errorCode: AgentCompactionFailureCode
+    })
   | (AgentRunStreamEventBase & {
       readonly type: "agent.ui.chunk"
       readonly chunkIndex: number
@@ -263,6 +288,23 @@ export function isAgentRunStreamEvent(value: unknown): value is AgentRunStreamEv
   switch (value.type) {
     case "agent.run.started":
       return value.modelId === undefined || typeof value.modelId === "string"
+    case "agent.compaction.started":
+      return (
+        isAgentContextCheckpointReason(value.reason) &&
+        isTokenEstimate(value.estimatedInputTokensBefore)
+      )
+    case "agent.compaction.completed":
+      return (
+        isAgentContextCheckpointReason(value.reason) &&
+        typeof value.checkpointId === "string" &&
+        isTokenEstimate(value.estimatedInputTokensBefore) &&
+        isTokenEstimate(value.estimatedInputTokensAfter)
+      )
+    case "agent.compaction.failed":
+      return (
+        isAgentContextCheckpointReason(value.reason) &&
+        AGENT_COMPACTION_FAILURE_CODES.includes(value.errorCode as AgentCompactionFailureCode)
+      )
     case "agent.ui.chunk":
       return (
         Number.isInteger(value.chunkIndex) &&
@@ -282,6 +324,14 @@ export function isAgentRunStreamEvent(value: unknown): value is AgentRunStreamEv
   }
 }
 
+function isAgentContextCheckpointReason(value: unknown): value is AgentContextCheckpointReason {
+  return value === "threshold" || value === "overflow"
+}
+
+function isTokenEstimate(value: unknown): value is number {
+  return Number.isSafeInteger(value) && (value as number) >= 0
+}
+
 function isTerminalAgentRunStatus(value: unknown): value is "succeeded" | "failed" | "cancelled" {
   return value === "succeeded" || value === "failed" || value === "cancelled"
 }
@@ -305,6 +355,12 @@ export function agentRunStreamIdempotencyKey(event: AgentRunStreamEvent): string
   switch (event.type) {
     case "agent.run.started":
       return `${event.runId}:${event.attempt}:started`
+    case "agent.compaction.started":
+      return `${event.runId}:${event.attempt}:compaction:${event.reason}:started`
+    case "agent.compaction.completed":
+      return `${event.runId}:${event.attempt}:compaction:${event.checkpointId}:completed`
+    case "agent.compaction.failed":
+      return `${event.runId}:${event.attempt}:compaction:${event.reason}:failed:${event.errorCode}`
     case "agent.ui.chunk":
       return `${event.runId}:${event.attempt}:chunk:${event.chunkIndex}`
     case "agent.message.finalized":

package/src/agents/types.ts

@@ -26,6 +26,15 @@ export const AGENT_REASONING_LEVELS = [
   "xhigh",
 ] as const satisfies readonly AgentReasoningLevel[]
 
+export interface AgentContextConfig {
+  /** Override the provider context-window size inferred by the agent worker. */
+  readonly windowTokens?: number
+  /** Tokens reserved for the next response and compaction work. */
+  readonly reserveTokens?: number
+  /** Approximate recent-message budget retained verbatim after compaction. */
+  readonly keepRecentTokens?: number
+}
+
 /**
  * Loop / stop controls for an agent run.
  *
@@ -35,6 +44,9 @@ export interface AgentLoopConfig {
   readonly stopWhen?: {
     readonly maxSteps?: number
   }
+  readonly context?: AgentContextConfig
+  /** Automatic provider prompt caching. Defaults to `auto`; use `off` to opt out. */
+  readonly caching?: "auto" | "off"
 }
 
 type Simplify<T> = { [K in keyof T]: T[K] } & {}

package/src/agents/validation.ts

@@ -10,6 +10,7 @@ import type { GroupDefinition, SecurityDefinitionCatalog } from "../security"
 import { AgentDefinitionError } from "./errors"
 import {
   AGENT_REASONING_LEVELS,
+  type AgentContextConfig,
   type AgentDefinition,
   type AgentLoopConfig,
   type AgentReasoningLevel,
@@ -159,14 +160,47 @@ export function validateAgentToolsAtStartup(agents: readonly AgentDefinition[]):
   }
 }
 
-export function assertValidLoopConfig(loop: AgentLoopConfig | undefined): void {
+export function resolveAgentLoopConfig(
+  loop: AgentLoopConfig | undefined
+): AgentLoopConfig | undefined {
+  if (loop === undefined) return undefined
+
   const maxSteps = loop?.stopWhen?.maxSteps
-  if (maxSteps === undefined) {
-    return
+  if (maxSteps !== undefined && (!Number.isSafeInteger(maxSteps) || maxSteps <= 0)) {
+    throw new AgentDefinitionError(
+      "[Sixb] Agent loop.stopWhen.maxSteps must be a positive safe integer."
+    )
   }
-  if (!Number.isInteger(maxSteps) || maxSteps <= 0) {
+  if (loop.caching !== undefined && loop.caching !== "auto" && loop.caching !== "off") {
+    throw new AgentDefinitionError("[Sixb] Agent loop.caching must be 'auto' or 'off'.")
+  }
+
+  const context = loop.context ? snapshotAgentContextConfig(loop.context) : undefined
+  return Object.freeze({
+    ...(loop.stopWhen === undefined
+      ? {}
+      : { stopWhen: Object.freeze({ ...(maxSteps === undefined ? {} : { maxSteps }) }) }),
+    ...(context === undefined ? {} : { context }),
+    ...(loop.caching === undefined ? {} : { caching: loop.caching }),
+  })
+}
+
+function snapshotAgentContextConfig(context: AgentContextConfig): AgentContextConfig {
+  const snapshot: Record<string, number> = {}
+  for (const field of ["windowTokens", "reserveTokens", "keepRecentTokens"] as const) {
+    const value = context[field]
+    if (value === undefined) continue
+    assertPositiveSafeInteger(value, field)
+    snapshot[field] = value
+  }
+
+  return Object.freeze(snapshot)
+}
+
+function assertPositiveSafeInteger(value: unknown, field: string): asserts value is number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
     throw new AgentDefinitionError(
-      "[Sixb] Agent loop.stopWhen.maxSteps must be a positive finite integer."
+      `[Sixb] Agent loop.context.${field} must be a positive safe integer.`
     )
   }
 }

package/src/http/api-routes.ts

@@ -131,6 +131,13 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     accessToken: true,
     agentApi: true,
   },
+  {
+    operationId: "queryObjectLinks",
+    method: "POST",
+    path: "/api/objects/query/links",
+    accessToken: true,
+    agentApi: true,
+  },
   {
     operationId: "countObjects",
     method: "POST",
@@ -159,13 +166,6 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     accessToken: true,
     agentApi: true,
   },
-  {
-    operationId: "listObjectLinks",
-    method: "GET",
-    path: "/api/objects/:objectTypeId/:objectId/links",
-    accessToken: true,
-    agentApi: true,
-  },
   // The four write routes. Bearer-capable because their execution facade enforces authorization
   // (`edit:object` / `append:telemetry`), which is exactly the precondition this table requires.
   // NOT agent-proxied: letting an agent turn write objects on its own is a separate decision, and

package/src/index.ts

@@ -77,7 +77,12 @@ export type {
   ActionRuntimeFacade,
   ActionSubject,
   ActionTargetObject,
+  ActionTelemetryHistoryBatchInput,
+  ActionTelemetryHistoryBatchResult,
+  ActionTelemetryHistorySeriesInput,
   ActionTelemetryObjectSet,
+  ActionTelemetryPropertyToken,
+  ActionTelemetryReadFacade,
   ActionValidationContext,
   ActionValidator,
   ActionWritebackContext,
@@ -574,6 +579,7 @@ export type {
   ObjectQueryPredicateIn,
   ObjectQueryPredicateNot,
   ObjectQueryProject,
+  ObjectQueryRefs,
   ObjectQueryResultShape,
   ObjectQuerySet,
   ObjectQuerySetOperation,
@@ -854,6 +860,8 @@ export type {
 export type {
   ExecutionObjectByIdHandle,
   ExecutionObjectSet,
+  ObjectQueryLinksInput,
+  ObjectQueryLinksResult,
   ObjectsRuntime,
 } from "./objects/execution"
 export type { PipelineRunsRuntime, PipelinesRuntime } from "./pipelines/execution"
@@ -941,6 +949,7 @@ export type {
 // ── Agents ──────────────────────────────────────────────────
 
 export type {
+  AgentContextConfig,
   AgentContextEntryInput,
   AgentContextInput,
   AgentContextOrigin,
@@ -1013,6 +1022,15 @@ export {
   requestAgentRun,
 } from "./agents"
 
+// ── Models ──────────────────────────────────────────────────
+
+export type {
+  LanguageModelCatalog,
+  LanguageModelEntry,
+  ModelCatalog,
+  ModelCatalogInput,
+} from "./models"
+
 // ── Scheduling ──────────────────────────────────────────────
 
 export { CronValidationError } from "./schedules"
@@ -1034,6 +1052,7 @@ export type {
   ProjectionTargetByKind,
   SourceEditConflictResolution,
   TelemetryProjectionDefinition,
+  TelemetryProjectionPropertyMapping,
 } from "./projections"
 
 export {

package/src/lake-storage/types.ts

@@ -84,7 +84,8 @@ export interface DatasetWriteCommitResult extends DatasetVersion {
    * report `unchanged` and reuse it for commits that cannot change visible
    * dataset content: a snapshot whose rows equal the latest visible rows
    * (order-insensitive, with equal duplicate counts), or an append of zero
-   * rows.
+   * rows. Without a latest version, an empty snapshot or append still creates
+   * the first addressable dataset version.
    */
   readonly outcome: "created" | "unchanged"
 }