orizu 0.5.39 → 0.5.41

package/src/dataset-readme-workflow.ts

@@ -0,0 +1,80 @@
+import { Cause, Effect, Exit, Result, Schema } from 'effect'
+
+import { datasetTransferTimeoutMs } from './dataset-transfer-policy.js'
+import { authedFetch } from './http.js'
+import { parseJsonResponse } from './json-response.js'
+
+// Loaded only through `await import(...)` from dataset-commands, like delete.
+
+const MAY_BE_SAVED = "The README may already be saved as a new version: check the dataset's README tab before saving again."
+const SAVED_AT_SAME_TIME = 'Another README save for this dataset happened at the same time, so yours was not saved. Run the command again to save it as the next version.'
+
+const SaveReply = Schema.Struct({
+  version: Schema.Struct({
+    id: Schema.String,
+    dataset_id: Schema.String,
+    version_num: Schema.Number,
+    created_at: Schema.String,
+  }),
+})
+
+export type SavedReadmeVersion = typeof SaveReply.Type['version']
+
+// A refusal (4xx) means nothing was saved. After any other failure once the
+// request was sent, a new version may exist; saving again would add another.
+class SaveFailure extends Error {
+  constructor(message: string, readonly mayBeSaved: boolean) { super(message) }
+}
+
+function saveRequest(datasetId: string, markdown: string, timeoutMs: number) {
+  return Effect.suspend(() => {
+    let sent = false
+    let timedOut = false
+    return Effect.tryPromise({
+      try: async signal => {
+        const request = new AbortController()
+        const abort = () => request.abort()
+        const timer = setTimeout(() => { timedOut = true; request.abort() }, timeoutMs)
+        if (signal.aborted) abort()
+        else signal.addEventListener('abort', abort, { once: true })
+        try {
+          const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(datasetId)}/readme`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ markdown }),
+            signal: request.signal,
+          }, () => { sent = true })
+          if (!response.ok) {
+            const message = `Failed to save dataset README: ${await response.text()}`
+            // The unique version number refused a save that lost a race.
+            if (response.status === 409) throw new SaveFailure(`${message}\n${SAVED_AT_SAME_TIME}`, false)
+            throw new SaveFailure(message, response.status < 400 || response.status >= 500)
+          }
+          const data = await parseJsonResponse<unknown>(response, 'Dataset README save')
+          const decoded = Schema.decodeUnknownResult(SaveReply)(data)
+          if (Result.isFailure(decoded)) {
+            throw new SaveFailure(`Dataset README save returned an unexpected response (status ${response.status}).`, true)
+          }
+          return decoded.success.version
+        } finally {
+          clearTimeout(timer)
+          signal.removeEventListener('abort', abort)
+          request.abort()
+        }
+      },
+      catch: cause => {
+        if (timedOut) return new SaveFailure('DATASET_TRANSFER_TIMEOUT: README save exceeded its deadline', sent)
+        if (cause instanceof SaveFailure) return cause
+        return new SaveFailure(cause instanceof Error ? cause.message : String(cause), sent)
+      },
+    })
+  }).pipe(Effect.mapError(failure => new Error(failure.mayBeSaved ? `${failure.message}\n${MAY_BE_SAVED}` : failure.message)))
+}
+
+// One request, never retried: a retry after an unknown outcome could add a
+// duplicate version.
+export async function saveDatasetReadme(datasetId: string, markdown: string): Promise<SavedReadmeVersion> {
+  const exit = await Effect.runPromiseExit(saveRequest(datasetId, markdown, datasetTransferTimeoutMs()))
+  if (Exit.isSuccess(exit)) return exit.value
+  throw Cause.squash(exit.cause)
+}

package/src/dataset-row-workflow.ts

@@ -0,0 +1,248 @@
+import { Cause, Effect, Exit, Result, Schema } from 'effect'
+
+import { datasetTransferTimeoutMs } from './dataset-transfer-policy.js'
+import { extractErrorMessage } from './error-response.js'
+import { parseDatasetFile } from './file-parser.js'
+import { authedFetch } from './http.js'
+import { parseJsonResponse } from './json-response.js'
+
+// Loaded only through `await import(...)` from dataset-commands, like append.
+
+const MAX_REQUEST_BYTES = 3 * 1024 * 1024
+const MAX_CHUNK_ROWS = 10
+const EMPTY_REQUEST_BYTES = Buffer.byteLength('{"rows":[]}', 'utf8')
+
+type DatasetRowEdit = Record<string, unknown> & { id: string }
+
+// 'rejected': the server answered with a refusal, so nothing was written.
+// 'unknown': the request was sent but no trustworthy answer came back.
+type Outcome = 'rejected' | 'unknown' | 'not_sent'
+class RowsRequestFailure extends Error {
+  readonly _tag = 'RowsRequestFailure'
+  constructor(message: string, readonly outcome: Outcome) { super(message) }
+}
+
+const Dataset = Schema.Struct({ id: Schema.String, name: Schema.String, rowCount: Schema.Number })
+const EditAcknowledgement = Schema.Struct({ dataset: Dataset, updatedCount: Schema.Number })
+type EditAcknowledgement = typeof EditAcknowledgement.Type
+
+export interface DatasetRowsOptions {
+  datasetId: string
+  json: boolean
+  printJson: (value: Record<string, unknown>) => void
+  printLine: (value: string) => void
+  sanitize: (value: string) => string
+}
+
+function normalizeRows(rows: Array<Record<string, unknown>>): DatasetRowEdit[] {
+  if (rows.length === 0) {
+    throw new Error('Dataset edit file must contain at least one row')
+  }
+
+  const seenRowIds = new Set<string>()
+  return rows.map((row, index) => {
+    const rowId = typeof row.id === 'string' ? row.id.trim() : ''
+    if (!rowId) {
+      throw new Error(`Dataset edit file rows[${index}] must include a non-empty string id`)
+    }
+    if (seenRowIds.has(rowId)) {
+      throw new Error(`Dataset edit file rows[${index}].id duplicates a previous row id`)
+    }
+    seenRowIds.add(rowId)
+    return { ...row, id: rowId }
+  })
+}
+
+function chunkRows(rows: DatasetRowEdit[], sanitize: (value: string) => string): DatasetRowEdit[][] {
+  const chunks: DatasetRowEdit[][] = []
+  let currentChunk: DatasetRowEdit[] = []
+  let currentBytes = EMPTY_REQUEST_BYTES
+
+  for (const row of rows) {
+    const rowBytes = Buffer.byteLength(JSON.stringify(row), 'utf8')
+    const framedRowBytes = rowBytes + (currentChunk.length > 0 ? 1 : 0)
+    if (
+      currentChunk.length > 0 &&
+      (currentChunk.length >= MAX_CHUNK_ROWS || currentBytes + framedRowBytes > MAX_REQUEST_BYTES)
+    ) {
+      chunks.push(currentChunk)
+      currentChunk = []
+      currentBytes = EMPTY_REQUEST_BYTES
+    }
+
+    const singleRowRequestBytes = EMPTY_REQUEST_BYTES + rowBytes
+    if (singleRowRequestBytes > MAX_REQUEST_BYTES) {
+      throw new Error(
+        `Dataset edit row ${sanitize(row.id)} is ${singleRowRequestBytes} bytes, ` +
+        `which exceeds the ${MAX_REQUEST_BYTES}-byte edit request limit`
+      )
+    }
+
+    currentChunk.push(row)
+    currentBytes += rowBytes + (currentChunk.length > 1 ? 1 : 0)
+  }
+
+  if (currentChunk.length > 0) chunks.push(currentChunk)
+  return chunks
+}
+
+// One rows request with a deadline that covers the whole reply. A deadline,
+// a lost connection or a broken reply after sending is an unknown outcome.
+function rowsRequest<A>(
+  datasetId: string,
+  method: 'PATCH' | 'DELETE',
+  body: unknown,
+  label: string,
+  timeoutMs: number,
+  read: (response: Response) => Promise<A>,
+) {
+  return Effect.suspend(() => {
+    let sent = false
+    let timedOut = false
+    return Effect.tryPromise({
+      try: async signal => {
+        const request = new AbortController()
+        const abort = () => request.abort()
+        const timer = setTimeout(() => { timedOut = true; request.abort() }, timeoutMs)
+        if (signal.aborted) abort()
+        else signal.addEventListener('abort', abort, { once: true })
+        try {
+          const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(datasetId)}/rows`, {
+            method,
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: request.signal,
+          }, () => { sent = true })
+          return await read(response)
+        } finally {
+          clearTimeout(timer)
+          signal.removeEventListener('abort', abort)
+          request.abort()
+        }
+      },
+      catch: cause => {
+        if (timedOut) {
+          return sent
+            ? new RowsRequestFailure(`DATASET_TRANSFER_TIMEOUT: ${label} exceeded its deadline`, 'unknown')
+            : new RowsRequestFailure(`DATASET_TRANSFER_TIMEOUT: ${label} exceeded its deadline before the request was sent`, 'not_sent')
+        }
+        if (cause instanceof RowsRequestFailure) return cause
+        return new RowsRequestFailure(cause instanceof Error ? cause.message : String(cause), sent ? 'unknown' : 'not_sent')
+      },
+    })
+  })
+}
+
+function refusalOutcome(status: number): Outcome {
+  return status >= 400 && status < 500 ? 'rejected' : 'unknown'
+}
+
+function editProgram(options: DatasetRowsOptions & { file: string }, timeoutMs: number) {
+  return Effect.gen(function*() {
+    const chunks = yield* Effect.try({
+      try: () => chunkRows(normalizeRows(parseDatasetFile(options.file).rows), options.sanitize),
+      catch: cause => cause,
+    })
+    let totalUpdated = 0
+    // normalizeRows refuses an empty file, so the loop always sets this.
+    let lastResult!: EditAcknowledgement
+
+    for (let index = 0; index < chunks.length; index += 1) {
+      const chunk = chunks[index]
+      if (!options.json && chunks.length > 1) {
+        options.printLine(`Updating chunk ${index + 1}/${chunks.length} (${chunk.length} rows)...`)
+      }
+      const acknowledged = yield* Effect.result(rowsRequest(options.datasetId, 'PATCH', { rows: chunk }, 'Dataset row edit', timeoutMs, async response => {
+        if (!response.ok) {
+          throw new RowsRequestFailure(`HTTP ${response.status}: ${await extractErrorMessage(response)}`, refusalOutcome(response.status))
+        }
+        const data: unknown = await response.json()
+        const decoded = Schema.decodeUnknownResult(EditAcknowledgement)(data)
+        if (Result.isFailure(decoded)) {
+          throw new RowsRequestFailure(`Server returned an unreadable acknowledgement for a ${chunk.length}-row chunk`, 'unknown')
+        }
+        if (!Number.isInteger(decoded.success.updatedCount) || decoded.success.updatedCount !== chunk.length) {
+          throw new RowsRequestFailure(`Server reported ${String(decoded.success.updatedCount)} updated rows for a ${chunk.length}-row chunk`, 'unknown')
+        }
+        return decoded.success
+      }))
+      if (Result.isFailure(acknowledged)) {
+        const { message, outcome } = acknowledged.failure
+        const advice = outcome === 'unknown'
+          ? 'This chunk may already be applied: check these rows in the dataset before retrying.'
+          : 'Retry with a file containing only the remaining row edits.'
+        return yield* Effect.fail(new Error(
+          `Chunk ${index + 1}/${chunks.length} failed: ${message}\n` +
+          `${totalUpdated} rows from ${index} chunk(s) were already updated. ${advice}`
+        ))
+      }
+      totalUpdated += acknowledged.success.updatedCount
+      lastResult = acknowledged.success
+    }
+
+    if (options.json) {
+      options.printJson({ dataset: lastResult.dataset, updatedCount: totalUpdated })
+      return
+    }
+    options.printLine(
+      `Updated ${totalUpdated} rows in dataset ${options.sanitize(lastResult.dataset.name)} ` +
+      `(${options.sanitize(lastResult.dataset.id)}). Current row count: ${lastResult.dataset.rowCount}`
+    )
+  })
+}
+
+function deleteProgram(options: DatasetRowsOptions & { rowIds: string[] }, timeoutMs: number) {
+  return Effect.gen(function*() {
+    const deleted = yield* rowsRequest(options.datasetId, 'DELETE', { rowIds: options.rowIds }, 'Dataset row removal', timeoutMs, async response => {
+      if (!response.ok) {
+        throw new RowsRequestFailure(await response.text(), refusalOutcome(response.status))
+      }
+      return parseJsonResponse<{
+        dataset: { id: string; name: string; rowCount: number }
+        deletedCount: number
+      }>(response, 'Dataset delete rows')
+    }).pipe(Effect.mapError(({ message, outcome }) => new Error(
+      `Delete rows failed: ${message}` +
+      (outcome === 'unknown' ? '\nThe rows may already be removed: check the dataset before retrying.' : '')
+    )))
+    if (options.json) {
+      options.printJson({ dataset: deleted.dataset, deletedCount: deleted.deletedCount })
+      return
+    }
+    options.printLine(
+      `Deleted ${deleted.deletedCount} rows from dataset ${options.sanitize(deleted.dataset.name)} (${options.sanitize(deleted.dataset.id)}). New row count: ${deleted.dataset.rowCount}`
+    )
+  })
+}
+
+// Ctrl-C or SIGTERM aborts the request in flight. Returns the exit code for
+// an interruption; other failures throw their original error.
+async function runRowsCommand(name: string, program: (timeoutMs: number) => Effect.Effect<void, unknown>): Promise<0 | 130 | 143> {
+  const timeoutMs = datasetTransferTimeoutMs()
+  const controller = new AbortController()
+  let interrupted: 130 | 143 | undefined
+  const interrupt = () => { interrupted ??= 130; controller.abort() }
+  const terminate = () => { interrupted ??= 143; controller.abort() }
+  process.on('SIGINT', interrupt)
+  process.on('SIGTERM', terminate)
+  try {
+    const exit = await Effect.runPromiseExit(program(timeoutMs), { signal: controller.signal })
+    if (interrupted !== undefined) {
+      process.stderr.write(`${name} interrupted. The request in flight may already be applied: check the dataset before retrying.\n`)
+      return interrupted
+    }
+    if (Exit.isFailure(exit)) throw Cause.squash(exit.cause)
+    return 0
+  } finally {
+    process.removeListener('SIGINT', interrupt)
+    process.removeListener('SIGTERM', terminate)
+  }
+}
+
+export function editDatasetRows(options: DatasetRowsOptions & { file: string }): Promise<0 | 130 | 143> {
+  return runRowsCommand('Dataset row edit', timeoutMs => editProgram(options, timeoutMs))
+}
+
+export function deleteDatasetRows(options: DatasetRowsOptions & { rowIds: string[] }): Promise<0 | 130 | 143> {
+  return runRowsCommand('Dataset row removal', timeoutMs => deleteProgram(options, timeoutMs))
+}

package/src/dataset-split-reads.ts

@@ -0,0 +1,43 @@
+import { Effect, Result, Schema } from 'effect'
+import { writeFileSync } from 'node:fs'
+
+import { authedFetch } from './http.js'
+import { extractErrorMessage } from './error-response.js'
+import { datasetTransferTimeoutMs } from './dataset-transfer-policy.js'
+
+const SplitExport = Schema.Struct({
+  split_set_id: Schema.String, dataset_version_id: Schema.String,
+  name: Schema.String, strategy: Schema.String, seed: Schema.NullOr(Schema.Number), metadata: Schema.Unknown,
+  partitions: Schema.Array(Schema.Struct({ name: Schema.String, row_ids: Schema.Array(Schema.String), metadata: Schema.Unknown })),
+})
+const SplitList = Schema.Struct({
+  dataset_version_id: Schema.String,
+  split_sets: Schema.Array(Schema.Struct({ id: Schema.String, name: Schema.String, strategy: Schema.String, seed: Schema.NullOr(Schema.Number), partitions: Schema.Array(Schema.Struct({ name: Schema.String, row_count: Schema.Number })) })),
+})
+
+async function read<A>(path: string, decode: (value: unknown) => A): Promise<A> {
+  const result = await Effect.runPromise(Effect.result(Effect.tryPromise({
+    try: async signal => {
+      const response = await authedFetch(path, { signal })
+      if (!response.ok) throw new Error(await extractErrorMessage(response))
+      try { return decode(await response.json()) } catch (cause) { throw new Error('Dataset split response is incomplete or unreadable', { cause }) }
+    }, catch: cause => cause instanceof Error ? cause : new Error('Dataset split read failed', { cause }),
+  }).pipe(Effect.timeoutOrElse({ duration: datasetTransferTimeoutMs(), orElse: () => Effect.fail(new Error('Dataset split read exceeded its deadline')) }))))
+  if (Result.isFailure(result)) throw result.failure
+  return result.success
+}
+
+export function listDatasetSplits(versionId: string) { return read(`/api/cli/dataset-versions/${encodeURIComponent(versionId)}/split-sets`, Schema.decodeUnknownSync(SplitList)) }
+export function showDatasetSplit(setId: string) { return read(`/api/cli/split-sets/${encodeURIComponent(setId)}`, Schema.decodeUnknownSync(SplitExport)) }
+
+export async function downloadPinnedDatasetSplit(versionId: string, setId: string, split: string, format: string, filename: string) {
+  const query = new URLSearchParams({ split_set: setId, split, format })
+  const result = await Effect.runPromise(Effect.result(Effect.tryPromise({
+    try: async signal => {
+      const response = await authedFetch(`/api/cli/dataset-versions/${encodeURIComponent(versionId)}/download?${query}`, { signal })
+      if (!response.ok) throw new Error(`Download failed: ${await extractErrorMessage(response)}`)
+      return new Uint8Array(await response.arrayBuffer())
+    }, catch: cause => cause instanceof Error ? cause : new Error('Dataset split download failed', { cause }),
+  }).pipe(Effect.timeoutOrElse({ duration: datasetTransferTimeoutMs(), orElse: () => Effect.fail(new Error('Dataset split download exceeded its deadline')) }), Effect.flatMap(bytes => Effect.try({ try: () => writeFileSync(filename, bytes, { mode: 0o600 }), catch: cause => new Error('Could not save dataset split download', { cause }) })))))
+  if (Result.isFailure(result)) throw result.failure
+}

package/src/dataset-transfer-upload.ts

@@ -2,6 +2,7 @@ import { Context, Effect, Layer, Result } from 'effect'
 
 import { ensureDatasetUploadSnapshot } from './dataset-upload-snapshot.js'
 import { datasetTransferTimeoutMs } from './dataset-transfer-policy.js'
+import { datasetVersionSnapshot, type DatasetVersionFailure, type DatasetVersionResponse } from './dataset-version-workflow.js'
 import { extractErrorMessage } from './error-response.js'
 import { authedFetch } from './http.js'
 import { parseJsonResponse, sanitizeTerminalText } from './json-response.js'
@@ -12,7 +13,6 @@ export interface DatasetUploadResponse {
   readmeVersion?: { id: string; version_num: number; created_at: string } | null
 }
 
-interface DatasetSnapshot { datasetVersion: { id: string } }
 interface DatasetAppendResponse { dataset: { id: string; name: string; rowCount: number }; appendedCount: number }
 type UploadRows = Array<Record<string, unknown>>
 type UploadSource = { kind: 'jsonl'; file: string } | { kind: 'rows'; rows: UploadRows; sourceType: 'csv' | 'json' | 'jsonl' }
@@ -41,10 +41,17 @@ class DatasetInputFailure extends Error {
 interface DatasetUploadApi {
   create: (rows: UploadRows, sourceType: string) => Effect.Effect<DatasetUploadResponse, DatasetWriteFailure>
   append: (id: string, rows: UploadRows) => Effect.Effect<DatasetAppendResponse, DatasetWriteFailure>
-  snapshot: (id: string) => Effect.Effect<DatasetSnapshot, DatasetWriteFailure>
+  snapshot: (id: string) => Effect.Effect<DatasetVersionResponse, DatasetVersionFailure>
 }
 const DatasetUploadApi = Context.Service<DatasetUploadApi>('orizu/DatasetUploadApi')
 
+// authedFetch raises this code only when it sent nothing, or after the server
+// answered 401 (it writes nothing) and the stored credentials changed, so it
+// refused to replay. Either way nothing was written (ORI-2431).
+function isAuthContextChange(cause: unknown) {
+  return cause instanceof Error && cause.message.startsWith('ORIZU_AUTH_CONTEXT_CHANGED:')
+}
+
 // Only the existing authentication client's rejected-token refresh may replay a
 // request. No transient/transport retries belong around these non-idempotent writes.
 function post<T>(path: string, body: unknown, context: string, prefix: string, timeoutMs: number): Effect.Effect<T, DatasetWriteFailure> {
@@ -62,7 +69,7 @@ function post<T>(path: string, body: unknown, context: string, prefix: string, t
         return await parseJsonResponse<T>(response, context)
       },
       catch: cause => cause instanceof DatasetWriteFailure ? cause : new DatasetWriteFailure(
-        cause instanceof Error ? cause.message : String(cause), requestStarted ? 'unknown' : 'rejected', { cause },
+        cause instanceof Error ? cause.message : String(cause), requestStarted && !isAuthContextChange(cause) ? 'unknown' : 'rejected', { cause },
       ),
     }).pipe(Effect.timeoutOrElse({
       duration: timeoutMs,
@@ -79,7 +86,7 @@ function liveUploadApi(options: DatasetUploadOptions) {
       ...(options.readmeMarkdown !== null ? { readmeMarkdown: options.readmeMarkdown } : {}),
     }, 'Dataset upload', 'Upload failed', timeoutMs),
     append: (id, rows) => post<DatasetAppendResponse>(`/api/cli/datasets/${encodeURIComponent(id)}/rows`, { rows }, 'Dataset append', 'Append failed', timeoutMs),
-    snapshot: id => post<DatasetSnapshot>(`/api/cli/datasets/${encodeURIComponent(id)}/versions`, {}, 'Dataset version create', 'Failed to create dataset version', timeoutMs),
+    snapshot: id => datasetVersionSnapshot(id, {}, timeoutMs),
   })
 }
 
@@ -140,6 +147,6 @@ function uploadProgram(options: DatasetUploadOptions) {
   })
 }
 
-export function transferDatasetUpload(options: DatasetUploadOptions): Promise<{ data: DatasetUploadResponse; version: DatasetSnapshot }> {
+export function transferDatasetUpload(options: DatasetUploadOptions): Promise<{ data: DatasetUploadResponse; version: DatasetVersionResponse }> {
   return expectedPromise(uploadProgram(options).pipe(Effect.scoped, Effect.provide(liveUploadApi(options))))
 }

package/src/dataset-upload-snapshot.ts

@@ -1,3 +1,5 @@
+import { DatasetVersionFailure, VERSION_MAY_BE_CREATED } from './dataset-version-workflow.js'
+
 interface UploadedDatasetIdentity {
   id: string
   name: string
@@ -20,6 +22,8 @@ export async function ensureDatasetUploadSnapshot<T extends DatasetVersionSnapsh
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error)
     const retryCommand = `orizu datasets versions create --dataset ${dataset.id}`
+    // After an unclear outcome the version may exist; check before retrying.
+    const mayBeCreated = error instanceof DatasetVersionFailure && error.mayBeCreated
 
     if (jsonOutput) {
       throw new Error(JSON.stringify({
@@ -29,13 +33,16 @@ export async function ensureDatasetUploadSnapshot<T extends DatasetVersionSnapsh
         dataset_id: dataset.id,
         dataset_version_id: null,
         retry_command: retryCommand,
+        ...(mayBeCreated ? { may_be_created: true } : {}),
       }))
     }
 
     throw new Error(
       `Dataset upload completed but dataset version creation failed: ${detail}\n` +
       `Dataset ${dataset.name} (${dataset.id}) was created with ${dataset.rowCount} rows. ` +
-      `Retry only the snapshot step with: ${retryCommand}`
+      (mayBeCreated
+        ? `${VERSION_MAY_BE_CREATED} If it is not there, create it with: ${retryCommand}`
+        : `Retry only the snapshot step with: ${retryCommand}`)
     )
   }
 }

package/src/dataset-version-workflow.ts

@@ -0,0 +1,105 @@
+import { Cause, Effect, Exit, Result, Schema } from 'effect'
+
+import { datasetTransferTimeoutMs } from './dataset-transfer-policy.js'
+import { extractErrorMessage, isJsonErrorResponsePayload } from './error-response.js'
+import { authedFetch } from './http.js'
+import { parseJsonResponse } from './json-response.js'
+
+// Loaded only through `await import(...)`, like the README and delete workflows.
+
+export const VERSION_MAY_BE_CREATED = "The version may already be created: check the dataset's versions in the web app before creating it again."
+// What the server says when it cannot tell whether the version was saved.
+const SERVER_MAY_BE_CREATED = 'Dataset version may already be created'
+
+const CreateReply = Schema.Struct({
+  datasetVersion: Schema.Struct({
+    id: Schema.NonEmptyString,
+    rowCount: Schema.Number,
+    artifactFormat: Schema.optional(Schema.String),
+    artifactStoragePath: Schema.optional(Schema.String),
+  }),
+})
+
+export type DatasetVersionResponse = typeof CreateReply.Type
+
+export interface DatasetVersionRequest {
+  versionLabel?: string | null
+  readmeMarkdown?: string | null
+}
+
+// The version may exist when the server says so, when the reply was lost or
+// unreadable after the request was sent, or when a 5xx did not come from the
+// app (a gateway giving up while the app kept working). Any other error reply
+// is a clear refusal.
+export class DatasetVersionFailure extends Error {
+  readonly _tag = 'DatasetVersionFailure'
+  constructor(message: string, readonly mayBeCreated: boolean) { super(message) }
+}
+
+async function appErrorOf(response: Response): Promise<string | null> {
+  try {
+    const payload: unknown = await response.json()
+    return isJsonErrorResponsePayload(response, payload) ? payload.error : null
+  } catch {
+    return null
+  }
+}
+
+// One request, never retried: a retry after an unknown outcome could add a
+// second version.
+export function datasetVersionSnapshot(datasetId: string, options: DatasetVersionRequest, timeoutMs: number): Effect.Effect<DatasetVersionResponse, DatasetVersionFailure> {
+  return Effect.suspend(() => {
+    let sent = false
+    let timedOut = false
+    return Effect.tryPromise({
+      try: async signal => {
+        const request = new AbortController()
+        const abort = () => request.abort()
+        const timer = setTimeout(() => { timedOut = true; request.abort() }, timeoutMs)
+        if (signal.aborted) abort()
+        else signal.addEventListener('abort', abort, { once: true })
+        try {
+          const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(datasetId)}/versions`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              ...(options.versionLabel ? { versionLabel: options.versionLabel } : {}),
+              ...(options.readmeMarkdown !== undefined && options.readmeMarkdown !== null
+                ? { readmeMarkdown: options.readmeMarkdown }
+                : {}),
+            }),
+            signal: request.signal,
+          }, () => { sent = true })
+          if (!response.ok) {
+            const serverError = await appErrorOf(response.clone())
+            const message = `Failed to create dataset version: ${await extractErrorMessage(response)}`
+            throw new DatasetVersionFailure(message, response.status < 400 || serverError === SERVER_MAY_BE_CREATED || (response.status >= 500 && serverError === null))
+          }
+          const data = await parseJsonResponse<unknown>(response, 'Dataset version create')
+          const decoded = Schema.decodeUnknownResult(CreateReply)(data)
+          if (Result.isFailure(decoded)) {
+            throw new DatasetVersionFailure(`Dataset version create returned an unexpected response (status ${response.status}).`, true)
+          }
+          return decoded.success
+        } finally {
+          clearTimeout(timer)
+          signal.removeEventListener('abort', abort)
+          request.abort()
+        }
+      },
+      catch: cause => {
+        if (timedOut) return new DatasetVersionFailure('DATASET_TRANSFER_TIMEOUT: Dataset version create exceeded its deadline', sent)
+        if (cause instanceof DatasetVersionFailure) return cause
+        return new DatasetVersionFailure(cause instanceof Error ? cause.message : String(cause), sent)
+      },
+    })
+  })
+}
+
+export async function createDatasetVersionSnapshot(datasetId: string, options: DatasetVersionRequest): Promise<DatasetVersionResponse> {
+  const exit = await Effect.runPromiseExit(datasetVersionSnapshot(datasetId, options, datasetTransferTimeoutMs()).pipe(
+    Effect.mapError(failure => new Error(failure.mayBeCreated ? `${failure.message}\n${VERSION_MAY_BE_CREATED}` : failure.message)),
+  ))
+  if (Exit.isSuccess(exit)) return exit.value
+  throw Cause.squash(exit.cause)
+}

package/src/feedback-cli.ts

@@ -419,15 +419,15 @@ function resolveProjectContext(
   return { teamSlug: workspaceTeam, projectSlug: null }
 }
 
-function lastErrorForContext(
+async function lastErrorForContext(
   configDirectory: string,
   serverBaseUrl: string,
   teamSlug: string | null,
   now: number,
   printErr: (message: string) => void,
   scrubNotice: (message: string) => string
-): LastErrorRecord | null {
-  const record = readLastErrorRecord(configDirectory)
+): Promise<LastErrorRecord | null> {
+  const record = await readLastErrorRecord(configDirectory)
   if (!record || !isLastErrorRecordShape(record)) return null
   if (teamSlug === null) {
     printErr('last error not attached: no team context')
@@ -633,7 +633,7 @@ export async function feedbackCommand(args: string[], io: FeedbackCliIo): Promis
     const values = { ...fromFile, ...parsed.values }
     const lastError = parsed.suppressLastError
       ? null
-      : lastErrorForContext(
+      : await lastErrorForContext(
         configDirectory,
         baseUrl,
         projectContext.teamSlug,

package/src/help.ts

@@ -948,17 +948,43 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
     summary: 'Create a dataset version.',
     group: 'Datasets',
   },
+  {
+    path: ['datasets', 'splits', 'list'],
+    usage: 'orizu datasets splits list <datasetVersionId> [--json]',
+    summary: 'Discover saved split sets, partition names and row counts for an immutable dataset version.',
+    group: 'Datasets',
+    options: [{ name: '--json', help: 'Print saved split sets and partition row counts as JSON.' }],
+    examples: ['orizu datasets splits list DATASET_VERSION_ID --json'],
+  },
+  {
+    path: ['datasets', 'splits', 'show'],
+    usage: 'orizu datasets splits show <splitSetId> [--json]',
+    summary: 'Inspect the pinned version, set identity and exact ordered row membership of every partition, including empty splits.',
+    group: 'Datasets',
+    options: [{ name: '--json', help: 'Export reusable assignments: name, strategy, seed, metadata and partitions [{name, row_ids}], with source identity for inspection. Import uses the explicit target version.' }],
+    examples: ['orizu datasets splits show SPLIT_SET_ID --json > split.json', 'orizu datasets splits create TARGET_DATASET_VERSION_ID --from-file split.json --json'],
+  },
   {
     path: ['datasets', 'splits', 'create'],
     usage: 'orizu datasets splits create <datasetVersionId> [--from-file <split.json>] [--json]',
-    summary: 'Create a split set for a dataset version.',
+    summary: 'Create a split set for the explicit target dataset version. --from-file accepts splits show JSON; canonical row IDs must exist in the target.',
     group: 'Datasets',
   },
   {
     path: ['datasets', 'download'],
-    usage: 'orizu datasets download [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--format <csv|json|jsonl>] [--out <path>]',
-    summary: 'Download a dataset.',
+    usage: 'orizu datasets download [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--dataset-version <id> --split-set <id> --split <name>] [--format <csv|json|jsonl>] [--out <path>]',
+    summary: 'Download live dataset rows, or one named split from an immutable version with canonical row IDs and existing fields in partition order. Pinned reads require all three selectors and JSON or JSONL; incomplete artifacts fail without falling back to live rows.',
     group: 'Datasets',
+    options: [
+      { name: '--dataset <datasetId|datasetUrl>', help: 'Dataset for an existing live download.' },
+      { name: '--project <team/project>', help: 'Project scope for live dataset selection.' },
+      { name: '--dataset-version <id>', help: 'Immutable version for a pinned split download; requires --split-set and --split.' },
+      { name: '--split-set <id>', help: 'Saved assignment set belonging to the selected version.' },
+      { name: '--split <name>', help: 'Exact partition name, for example validation. For names beginning with --, use --split=--validation (also --split=--json or --split=--help).' },
+      { name: '--format <csv|json|jsonl>', help: 'Output format. Pinned split downloads support json and jsonl only.' },
+      { name: '--out <path>', help: 'Write rows to a file.' },
+    ],
+    examples: ['orizu datasets download --dataset-version DATASET_VERSION_ID --split-set SPLIT_SET_ID --split validation --format jsonl --out validation.jsonl', 'orizu datasets download --dataset DATASET_ID --format jsonl --out dataset.jsonl'],
   },
   {
     path: ['datasets', 'append'],