orizu 0.5.39 → 0.5.40

package/src/dataset-delete-workflow.ts

@@ -0,0 +1,72 @@
+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 append.
+
+const MAY_BE_DELETED = 'The dataset may already be deleted: check with `orizu datasets list --status all` before retrying.'
+
+const DeleteReply = Schema.Struct({ dataset: Schema.Struct({ id: Schema.String }) })
+
+// A refusal (4xx) means nothing was deleted. After any other failure once the
+// request was sent, the delete may have committed, and it cannot be undone.
+class DeleteFailure extends Error {
+  constructor(message: string, readonly mayBeDeleted: boolean) { super(message) }
+}
+
+function deleteRequest(datasetId: string, project: string | null, 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)}`, {
+            method: 'DELETE',
+            signal: request.signal,
+          }, () => { sent = true })
+          if (!response.ok) {
+            const message = `Delete failed: ${await response.text()}`
+            // A dependency refusal: archiving keeps the dataset and its references.
+            if (response.status === 409) {
+              const archive = `orizu datasets archive ${datasetId}${project ? ` --project ${project}` : ''}`
+              throw new DeleteFailure(`${message}\nArchive it instead: \`${archive}\``, false)
+            }
+            throw new DeleteFailure(message, response.status < 400 || response.status >= 500)
+          }
+          const data = await parseJsonResponse<unknown>(response, 'Dataset delete')
+          const decoded = Schema.decodeUnknownResult(DeleteReply)(data)
+          if (Result.isFailure(decoded)) {
+            throw new DeleteFailure(`Dataset delete returned an unexpected response (status ${response.status}).`, true)
+          }
+          return decoded.success.dataset
+        } finally {
+          clearTimeout(timer)
+          signal.removeEventListener('abort', abort)
+          request.abort()
+        }
+      },
+      catch: cause => {
+        if (timedOut) return new DeleteFailure('DATASET_TRANSFER_TIMEOUT: Dataset delete exceeded its deadline', true)
+        if (cause instanceof DeleteFailure) return cause
+        return new DeleteFailure(cause instanceof Error ? cause.message : String(cause), sent)
+      },
+    })
+  }).pipe(Effect.mapError(failure => new Error(failure.mayBeDeleted ? `${failure.message}\n${MAY_BE_DELETED}` : failure.message)))
+}
+
+// Runs after the typed confirmation. Nothing to clean up, so signals keep
+// Node's default handling.
+// `project` (team/project), when known, goes into the archive hint.
+export async function deleteDataset(datasetId: string, project: string | null): Promise<{ id: string }> {
+  const exit = await Effect.runPromiseExit(deleteRequest(datasetId, project, datasetTransferTimeoutMs()))
+  if (Exit.isSuccess(exit)) return exit.value
+  throw Cause.squash(exit.cause)
+}

package/src/dataset-lock-workflow.ts

@@ -0,0 +1,74 @@
+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 append.
+
+const MAY_BE_LOCKED = 'The dataset may already be locked: running `orizu datasets lock` again is safe and shows its current state.'
+
+const LockedDataset = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  rowCount: Schema.Number,
+  lockedAt: Schema.String,
+  lockedBy: Schema.NullOr(Schema.String),
+})
+const LockReply = Schema.Struct({ dataset: LockedDataset })
+export type LockedDataset = typeof LockedDataset.Type
+
+// A refusal (4xx) means nothing was locked. After any other failure once the
+// request was sent, the lock may have committed; locking again is harmless.
+class LockFailure extends Error {
+  constructor(message: string, readonly mayBeLocked: boolean) { super(message) }
+}
+
+function lockRequest(datasetId: string, reason: string | null, 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)}/lock`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(reason ? { reason } : {}),
+            signal: request.signal,
+          }, () => { sent = true })
+          if (!response.ok) {
+            throw new LockFailure(`Lock failed: ${await response.text()}`, response.status < 400 || response.status >= 500)
+          }
+          const data = await parseJsonResponse<unknown>(response, 'Dataset lock')
+          const decoded = Schema.decodeUnknownResult(LockReply)(data)
+          if (Result.isFailure(decoded)) {
+            throw new LockFailure(`Dataset lock returned an unexpected response (status ${response.status}).`, true)
+          }
+          return decoded.success.dataset
+        } finally {
+          clearTimeout(timer)
+          signal.removeEventListener('abort', abort)
+          request.abort()
+        }
+      },
+      catch: cause => {
+        if (timedOut) return new LockFailure('DATASET_TRANSFER_TIMEOUT: Dataset lock exceeded its deadline', true)
+        if (cause instanceof LockFailure) return cause
+        return new LockFailure(cause instanceof Error ? cause.message : String(cause), sent)
+      },
+    })
+  }).pipe(Effect.mapError(failure => new Error(failure.mayBeLocked ? `${failure.message}\n${MAY_BE_LOCKED}` : failure.message)))
+}
+
+// Nothing to clean up, so signals keep Node's default handling.
+export async function lockDataset(datasetId: string, reason: string | null): Promise<LockedDataset> {
+  const exit = await Effect.runPromiseExit(lockRequest(datasetId, reason, datasetTransferTimeoutMs()))
+  if (Exit.isSuccess(exit)) return exit.value
+  throw Cause.squash(exit.cause)
+}

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/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'],

package/src/hosted-boot.ts

@@ -150,6 +150,7 @@ export function deriveBootStatusUrl(agentTokenUrl: string): string {
  *  secret defensively before sending. */
 const MAX_BOOT_REASON_CHARS = 800
 const TURN_STATUS_ATTEMPT_TIMEOUT_MS = 10_000
+export const HOSTED_TURN_PROGRESS_REPORT_MS = 5 * 60_000
 
 function resolveTestPositiveInteger(
   processEnv: Record<string, string | undefined>,
@@ -241,7 +242,7 @@ async function postRequiredIdleReady(opts: {
 async function postTurnStatus(opts: {
   bootStatusUrl: string
   bootSecret: string
-  status: 'turn_started' | 'turn_completed' | 'turn_failed'
+  status: 'turn_started' | 'turn_progress' | 'turn_completed' | 'turn_failed'
   runId: string
   reason?: string | null
   fetchImpl: BootFetch
@@ -1283,6 +1284,7 @@ export async function runHostedBoot(opts: RunHostedBootOptions): Promise<HostedB
         minimumDelayMs: bearerRotationMinimumDelayMs,
       })
       const promptInterruptController = new AbortController()
+      let nextProgressAt = now()
       const interruptPollController = new AbortController()
       const interruptPoll = pollHostedSessionDuringTurn({
         baseUrl: env.baseUrl,
@@ -1312,6 +1314,19 @@ export async function runHostedBoot(opts: RunHostedBootOptions): Promise<HostedB
             bearerProvider: () => readFile(bearerFileAbs).trim(),
             interruptSignal: promptInterruptController.signal,
             onDiagnostic: log,
+            onProgress: async () => {
+              if (now() < nextProgressAt) return
+              nextProgressAt = now() + HOSTED_TURN_PROGRESS_REPORT_MS
+              try {
+                await postTurnStatus({
+                  bootStatusUrl: env.bootStatusUrl, bootSecret: env.bootSecret,
+                  status: 'turn_progress', runId: current.runId, fetchImpl, sleep,
+                  attemptTimeoutMs: turnStatusAttemptTimeoutMs,
+                })
+              } catch {
+                log('turn progress acknowledgement unavailable')
+              }
+            },
           }
         )
       } finally {