dataiku-sdk 3.9.0 → 4.0.0

package/dist/src/client.js

@@ -211,7 +211,13 @@ export class DataikuClient {
     maxResponseBodyBytes;
     retryMaxAttempts;
     verbose;
-    tlsOptions;
+    /**
+     * Connection pool carrying this client's TLS settings (custom CA, disabled
+     * verification). A session never shares connections with plain `fetch` or
+     * another client, so a connection opened with relaxed TLS cannot serve a
+     * client that expects strict verification. Default-TLS clients use plain fetch.
+     */
+    session;
     onTrace;
     onValidationWarning;
     /* Resource namespaces — lazily initialized to break circular imports */
@@ -606,7 +612,8 @@ export class DataikuClient {
         const rawMax = config?.retryMaxAttempts ?? DEFAULT_RETRY_MAX_ATTEMPTS;
         this.retryMaxAttempts = Math.min(Math.max(1, rawMax), MAX_RETRY_ATTEMPTS_CAP);
         this.verbose = config?.verbose === true;
-        this.tlsOptions = config ? buildFetchTlsOptions(config) : undefined;
+        const tls = config ? buildFetchTlsOptions(config) : undefined;
+        this.session = tls ? new Bun.FetchSession({ tls, }) : undefined;
         this.onTrace = config?.onTrace ?? defaultTrace;
         this.onValidationWarning = config?.onValidationWarning ?? defaultValidationWarning;
     }
@@ -691,7 +698,8 @@ export class DataikuClient {
      * When the response exceeds the cap, earlier bytes are discarded, only
      * the tail is kept and `truncated` is true — so callers that need the end
      * of a large document (e.g. job logs) stay bounded without losing the most
-     * recent content. The read runs under the request deadline.
+     * recent content. The request timeout applies per received chunk (a stall
+     * deadline), not to the whole transfer.
      */
     async getTextTailLimited(path, maxBytes) {
         const limit = Math.max(0, Math.floor(maxBytes));
@@ -1080,6 +1088,11 @@ export class DataikuClient {
      * Returns `truncated: true` when bytes had to be dropped. Bytes that fall
      * in the middle of a UTF-8 character are dropped from both ends so the
      * decoded text never contains a replacement character.
+     *
+     * The request timeout applies per chunk (a stall deadline), like the
+     * streaming path: a large body that keeps arriving is read to EOF however
+     * long the whole transfer takes, while a body that stops sending for longer
+     * than the timeout fails with the body-read timeout error.
      */
     async readBodyTextTail(res, maxBytes) {
         const limit = Math.max(0, Math.floor(maxBytes));
@@ -1090,13 +1103,9 @@ export class DataikuClient {
         let writeOffset = 0;
         let retainedBytes = 0;
         let truncated = false;
-        const startedAt = Date.now();
         try {
             while (true) {
-                const remainingMs = this.requestTimeoutMs - (Date.now() - startedAt);
-                if (remainingMs <= 0)
-                    throw buildBodyReadTimeoutError(this.requestTimeoutMs);
-                const { done, value, } = await readChunkWithDeadline(reader, remainingMs, this.requestTimeoutMs);
+                const { done, value, } = await readChunkWithDeadline(reader, this.requestTimeoutMs, this.requestTimeoutMs);
                 if (done)
                     break;
                 if (limit === 0) {
@@ -1187,9 +1196,8 @@ export class DataikuClient {
                     ...init,
                     method,
                     signal: controller.signal,
+                    ...(this.session ? { session: this.session, } : {}),
                 };
-                if (this.tlsOptions)
-                    requestInit.tls = this.tlsOptions;
                 const res = await fetch(url, requestInit);
                 this.logTrace({
                     phase: "response",

package/dist/src/generated/action-output-schemas.json

@@ -1119,6 +1119,12 @@
                 "timedOut": {
                     "type": "boolean"
                 },
+                "cancelled": {
+                    "type": "boolean"
+                },
+                "resume": {
+                    "type": "string"
+                },
                 "progress": {
                     "type": "object",
                     "required": [
@@ -1187,6 +1193,12 @@
                 "timedOut": {
                     "type": "boolean"
                 },
+                "cancelled": {
+                    "type": "boolean"
+                },
+                "resume": {
+                    "type": "string"
+                },
                 "progress": {
                     "type": "object",
                     "required": [
@@ -1577,6 +1589,12 @@
                             "string",
                             "null"
                         ]
+                    },
+                    "isDev": {
+                        "type": [
+                            "boolean",
+                            "null"
+                        ]
                     }
                 }
             }

package/dist/src/index.d.ts

@@ -22,7 +22,7 @@ export { FoldersResource, } from "./resources/folders.js";
 export { type DssTask, FuturesResource, type FutureWaitOptions, } from "./resources/futures.js";
 export { type DssGroup, type GroupCreateRequest, GroupsResource, } from "./resources/groups.js";
 export { InsightsResource, } from "./resources/insights.js";
-export { type JobBuildAndWaitOptions, type JobBuildOptions, type JobBuildTarget, type JobBuildTargetType, type JobLogFilter, type JobLogProgress, type JobLogSummary, type JobLogUnavailableReason, JobsResource, type JobWaitOutcome, parseJobLogProgress, } from "./resources/jobs.js";
+export { type JobBuildAndWaitOptions, type JobBuildOptions, type JobBuildTarget, type JobBuildTargetType, type JobLogDetails, type JobLogFilter, type JobLogProgress, type JobLogSummary, type JobLogUnavailableReason, JobsResource, type JobWaitOutcome, parseJobLogProgress, } from "./resources/jobs.js";
 export * from "./resources/knowledge-banks.js";
 export * from "./resources/llms.js";
 export { type MacroResultOptions, type MacroRunFailure, type MacroRunHandle, type MacroRunOptions, type MacroRunWaitedResult, MacrosResource, type MacroWaitOptions, } from "./resources/macros.js";

package/dist/src/resources/datasets.d.ts

@@ -135,9 +135,19 @@ export declare class DatasetsResource extends BaseResource {
     /**
      * TSV data stream of at most `limit` rows. A column or partition selection
      * uses the documented POST variant of the data endpoint (body `columns`,
-     * `partitions`, `format`, `sampling`); otherwise the GET endpoint.
+     * `partitions`, `format`, `sampling`); otherwise the GET endpoint. Both carry
+     * a client-generated `readSessionId` for {@link verifyStreamComplete}.
      */
     private dataStream;
+    /**
+     * A data stream that ended normally may still be incomplete: DSS sends 200
+     * headers before reading the data, so a server-side read failure only cuts
+     * the body short. As dataikuapi does, ask DSS whether the read session
+     * finished; it answers non-2xx (DataikuError) when it did not. Only called
+     * after the body was read to its end — a stream the client cancelled at
+     * its row cap is not complete by design.
+     */
+    private verifyStreamComplete;
     /**
      * Preview dataset rows as structured data: column names plus row arrays,
      * mirroring the sql query shape ({ columns, rows, rowCount }). Streams TSV

package/dist/src/resources/datasets.js

@@ -1,6 +1,5 @@
 import * as fs from "node:fs";
 import * as nodePath from "node:path";
-import { StringDecoder, } from "node:string_decoder";
 import { ClientValidationError, DataikuError, } from "../errors.js";
 import { DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, } from "../schemas.js";
 import { deepMerge, } from "../utils/deep-merge.js";
@@ -28,8 +27,44 @@ function formatLimitBytes(bytes) {
         return `${bytes / (1024 * 1024)} MiB`;
     return `${bytes} B`;
 }
-function tsvLimitError(what, limit) {
-    return new DataikuError(0, "Dataset TSV Limit", `Dataset TSV ${what} exceeded ${formatLimitBytes(limit)}; streaming was aborted to guard against unbounded memory use.`);
+const TSV_ERROR_COLUMN_NAME_MAX = 40;
+/**
+ * Describe the column whose cell is being read when a field/row budget trips:
+ * the header name once the header row has been parsed, otherwise the 0-based
+ * column index. Error summaries are bounded (~200 chars), so the name is
+ * shortened to keep the `--columns` hint inside the visible message.
+ */
+function describeTsvColumn(state) {
+    const index = state.currentRow.length;
+    const name = state.header?.[index];
+    if (name === undefined)
+        return `column index ${index}`;
+    const shown = name.length > TSV_ERROR_COLUMN_NAME_MAX
+        ? `${name.slice(0, TSV_ERROR_COLUMN_NAME_MAX)}...`
+        : name;
+    return `column "${shown}"`;
+}
+/**
+ * A client-side size budget, not a DSS or transport failure: retrying the same
+ * read cannot succeed, so this is a non-retryable input error whose fix is a
+ * narrower selection (--columns).
+ */
+function tsvLimitError(what, limit, state) {
+    const exceeded = `Dataset TSV ${what} exceeded ${formatLimitBytes(limit)}`;
+    const cellLimit = formatLimitBytes(state.limits.maxFieldBytes);
+    let message;
+    if (what === "field") {
+        message = `${exceeded} in ${describeTsvColumn(state)} (a single cell is limited to ${cellLimit}); exclude it with --columns.`;
+    }
+    else if (what === "row") {
+        message = `${exceeded} (a single cell is limited to ${cellLimit}); reached in ${describeTsvColumn(state)}. Exclude large columns with --columns.`;
+    }
+    else {
+        message = `${exceeded}; streaming was aborted to guard against unbounded memory use.`;
+    }
+    return new ClientValidationError(message, "validation_failed", what === "response"
+        ? "Narrow the read with --columns, --partitions, or a lower row limit."
+        : "Select fewer columns with --columns so the oversized cell is not read.");
 }
 /** Characters that evaluate a spreadsheet cell as a formula. */
 const FORMULA_SIGILS = "=+-@";
@@ -75,6 +110,7 @@ function createTsvStreamState(limits = {
     return {
         currentField: "",
         currentRow: [],
+        header: undefined,
         inQuotes: false,
         pendingQuoteInQuotes: false,
         fieldBytes: 0,
@@ -91,10 +127,10 @@ function appendFieldText(state, text) {
     state.fieldBytes += bytes;
     state.rowBytes += bytes;
     if (state.fieldBytes > state.limits.maxFieldBytes) {
-        throw tsvLimitError("field", state.limits.maxFieldBytes);
+        throw tsvLimitError("field", state.limits.maxFieldBytes, state);
     }
     if (state.rowBytes > state.limits.maxRowBytes) {
-        throw tsvLimitError("row", state.limits.maxRowBytes);
+        throw tsvLimitError("row", state.limits.maxRowBytes, state);
     }
     state.currentField += text;
 }
@@ -105,11 +141,20 @@ function endField(state) {
     state.fieldBytes = 0;
     state.rowBytes += 1; // count the delimiter byte
 }
+/** Hand a completed row to `onRow`, remembering the first non-blank row as the header. */
+function emitRow(state, onRow) {
+    const row = state.currentRow;
+    state.currentRow = [];
+    state.rowBytes = 0;
+    if (state.header === undefined && !isBlankRow(row))
+        state.header = row;
+    onRow(row);
+}
 function consumeTsvChunk(text, state, onRow) {
     // Response budget: bound total decoded bytes regardless of row structure.
     state.responseBytes += Buffer.byteLength(text, "utf-8");
     if (state.responseBytes > state.limits.maxResponseBytes) {
-        throw tsvLimitError("response", state.limits.maxResponseBytes);
+        throw tsvLimitError("response", state.limits.maxResponseBytes, state);
     }
     let i = 0;
     if (state.pendingQuoteInQuotes) {
@@ -193,10 +238,7 @@ function consumeTsvChunk(text, state, onRow) {
         if (ch === "\n") {
             endField(state);
             i = special + 1;
-            const row = state.currentRow;
-            state.currentRow = [];
-            state.rowBytes = 0;
-            onRow(row);
+            emitRow(state, onRow);
             continue;
         }
         // "\r" — carriage return: skipped, as in the original parser.
@@ -213,10 +255,7 @@ function flushTsvStream(state, onRow) {
     state.currentRow.push(state.currentField);
     state.currentField = "";
     state.fieldBytes = 0;
-    const row = state.currentRow;
-    state.currentRow = [];
-    state.rowBytes = 0;
-    onRow(row);
+    emitRow(state, onRow);
 }
 function rowToCsv(row, spreadsheetSafe) {
     return row.map((field) => csvEscape(field, spreadsheetSafe)).join(",");
@@ -264,7 +303,7 @@ async function readChunkWithTimeout(reader, remainingMs, timeoutMs, action) {
 }
 async function collectPreviewRows(body, maxDataRows, timeoutMs, onHeader) {
     const state = createTsvStreamState();
-    const decoder = new StringDecoder("utf-8");
+    const decoder = new TextDecoder("utf-8", { ignoreBOM: true, });
     let columns;
     const rows = [];
     let done = false;
@@ -304,10 +343,10 @@ async function collectPreviewRows(body, maxDataRows, timeoutMs, onHeader) {
             const result = await readChunkWithTimeout(reader, remainingMs, timeoutMs, "preview");
             if (result.done)
                 break;
-            consumeTsvChunk(decoder.write(result.value), state, handleRow);
+            consumeTsvChunk(decoder.decode(result.value, { stream: true, }), state, handleRow);
         }
         if (!done) {
-            const tail = decoder.end();
+            const tail = decoder.decode();
             if (tail !== "")
                 consumeTsvChunk(tail, state, handleRow);
             flushTsvStream(state, handleRow);
@@ -332,7 +371,7 @@ async function collectPreviewRows(body, maxDataRows, timeoutMs, onHeader) {
  */
 async function collectTsvRowCount(body, stopAfter, timeoutMs) {
     const state = createTsvStreamState();
-    const decoder = new StringDecoder("utf-8");
+    const decoder = new TextDecoder("utf-8", { ignoreBOM: true, });
     let headerSeen = false;
     let count = 0;
     let bounded = false;
@@ -373,10 +412,10 @@ async function collectTsvRowCount(body, stopAfter, timeoutMs) {
             const result = await readChunkWithTimeout(reader, remainingMs, timeoutMs, "row count assertion");
             if (result.done)
                 break;
-            consumeTsvChunk(decoder.write(result.value), state, handleRow);
+            consumeTsvChunk(decoder.decode(result.value, { stream: true, }), state, handleRow);
         }
         if (!bounded) {
-            const tail = decoder.end();
+            const tail = decoder.decode();
             if (tail !== "")
                 consumeTsvChunk(tail, state, handleRow);
             flushTsvStream(state, handleRow);
@@ -402,7 +441,7 @@ async function collectTsvRowCount(body, stopAfter, timeoutMs) {
 const CSV_BATCH_BYTES = 64 * 1024;
 function tsvToCsvTransform(maxDataRows, stats, onHeader, spreadsheetSafe = true) {
     const state = createTsvStreamState();
-    const decoder = new StringDecoder("utf-8");
+    const decoder = new TextDecoder("utf-8", { ignoreBOM: true, });
     const encoder = new TextEncoder();
     const maxRows = Math.max(1, maxDataRows);
     let headerSeen = false;
@@ -454,7 +493,7 @@ function tsvToCsvTransform(maxDataRows, stats, onHeader, spreadsheetSafe = true)
     // which cancels the response and makes download() remove the partial file.
     return new TransformStream({
         transform(chunk, controller) {
-            consumeTsvChunk(decoder.write(chunk), state, (row) => handleRow(row, (line) => queueLine(controller, line)));
+            consumeTsvChunk(decoder.decode(chunk, { stream: true, }), state, (row) => handleRow(row, (line) => queueLine(controller, line)));
             if (done) {
                 // Truncation reached: emit the batch queued so far, end the output,
                 // and cancel the rest of the response.
@@ -463,7 +502,7 @@ function tsvToCsvTransform(maxDataRows, stats, onHeader, spreadsheetSafe = true)
             }
         },
         flush(controller) {
-            const tail = decoder.end();
+            const tail = decoder.decode();
             if (tail !== "") {
                 consumeTsvChunk(tail, state, (row) => handleRow(row, (line) => queueLine(controller, line)));
             }
@@ -660,19 +699,35 @@ export class DatasetsResource extends BaseResource {
     /**
      * TSV data stream of at most `limit` rows. A column or partition selection
      * uses the documented POST variant of the data endpoint (body `columns`,
-     * `partitions`, `format`, `sampling`); otherwise the GET endpoint.
+     * `partitions`, `format`, `sampling`); otherwise the GET endpoint. Both carry
+     * a client-generated `readSessionId` for {@link verifyStreamComplete}.
      */
     async dataStream(datasetName, limit, projectKey, selection) {
+        const readSessionId = crypto.randomUUID();
         const path = `/public/api/projects/${this.enc(projectKey)}/datasets/${encodeURIComponent(datasetName)}/data/`;
         if (!selection?.columns?.length && !selection?.partitions) {
-            return this.client.stream(`${path}?format=tsv-excel-header&limit=${limit}`);
+            const res = await this.client.stream(`${path}?format=tsv-excel-header&limit=${limit}&readSessionId=${readSessionId}`);
+            return { res, readSessionId, };
         }
-        return this.client.postStream(path, {
+        const res = await this.client.postStream(path, {
             format: "tsv-excel-header",
             ...(selection.columns?.length ? { columns: selection.columns, } : {}),
             ...(selection.partitions ? { partitions: selection.partitions, } : {}),
             sampling: { samplingMethod: "HEAD_SEQUENTIAL", maxRecords: limit, },
+            readSessionId,
         });
+        return { res, readSessionId, };
+    }
+    /**
+     * A data stream that ended normally may still be incomplete: DSS sends 200
+     * headers before reading the data, so a server-side read failure only cuts
+     * the body short. As dataikuapi does, ask DSS whether the read session
+     * finished; it answers non-2xx (DataikuError) when it did not. Only called
+     * after the body was read to its end — a stream the client cancelled at
+     * its row cap is not complete by design.
+     */
+    async verifyStreamComplete(datasetName, projectKey, readSessionId) {
+        await this.client.getTextLimited(`/public/api/projects/${this.enc(projectKey)}/datasets/${encodeURIComponent(datasetName)}/finish-streaming/?readSessionId=${readSessionId}`, 64 * 1024);
     }
     /**
      * Preview dataset rows as structured data: column names plus row arrays,
@@ -691,7 +746,7 @@ export class DatasetsResource extends BaseResource {
         const timeoutMs = Math.max(1, opts?.timeoutMs ?? this.client.getRequestTimeoutMs());
         // Probe one row past the cap so callers learn whether the dataset holds
         // more rows than requested without materializing the full dataset.
-        const res = await this.dataStream(datasetName, maxRows + 1, opts?.projectKey, opts);
+        const { res, readSessionId, } = await this.dataStream(datasetName, maxRows + 1, opts?.projectKey, opts);
         const onHeader = opts?.validateColumns
             ? (headerRow) => {
                 const warnings = validateStreamColumns(headerRow, opts.validateColumns);
@@ -704,6 +759,8 @@ export class DatasetsResource extends BaseResource {
             return { columns: [], rows: [], rowCount: 0, truncated: false, limit: maxRows, };
         }
         const { columns, rows, truncated, } = await collectPreviewRows(res.body, maxRows, timeoutMs, onHeader);
+        if (!truncated)
+            await this.verifyStreamComplete(datasetName, opts?.projectKey, readSessionId);
         return {
             columns: columns.map((name) => ({ name, })),
             rows,
@@ -730,12 +787,13 @@ export class DatasetsResource extends BaseResource {
         const target = expected;
         const probe = target + 1;
         const timeoutMs = Math.max(1, this.client.getRequestTimeoutMs());
-        const dsEnc = encodeURIComponent(datasetName);
-        const res = await this.client.stream(`/public/api/projects/${this.enc(projectKey)}/datasets/${dsEnc}/data/?format=tsv-excel-header&limit=${probe}`);
+        const { res, readSessionId, } = await this.dataStream(datasetName, probe, projectKey, undefined);
         if (!res.body) {
             return { expected: target, count: 0, exact: true, satisfied: target === 0, };
         }
         const { count, bounded, } = await collectTsvRowCount(res.body, probe, timeoutMs);
+        if (!bounded)
+            await this.verifyStreamComplete(datasetName, projectKey, readSessionId);
         return { expected: target, count, exact: !bounded, satisfied: !bounded && count === target, };
     }
     /** Get dataset metadata (tags, custom fields, checklists). */
@@ -873,7 +931,7 @@ export class DatasetsResource extends BaseResource {
      */
     async download(datasetName, opts) {
         const limit = Math.max(1, opts?.limit ?? 100_000);
-        const res = await this.dataStream(datasetName, limit + 1, opts?.projectKey, opts);
+        const { res, readSessionId, } = await this.dataStream(datasetName, limit + 1, opts?.projectKey, opts);
         const safeDatasetName = sanitizeFileName(datasetName, "dataset");
         const filePath = opts?.outputPath?.endsWith(".gz") || opts?.outputPath?.endsWith(".csv")
             ? nodePath.resolve(opts.outputPath)
@@ -895,6 +953,9 @@ export class DatasetsResource extends BaseResource {
         try {
             // Native streaming write with backpressure; no Node stream layer.
             await Bun.write(filePath, new Response(csv));
+            if (!stats.truncated) {
+                await this.verifyStreamComplete(datasetName, opts?.projectKey, readSessionId);
+            }
         }
         catch (error) {
             // A failed export (byte-limit overflow, network error) must never

package/dist/src/resources/jobs.d.ts

@@ -9,6 +9,20 @@ import { BaseResource } from "./base.js";
  */
 export type JobBuildTargetType = "DATASET" | "MANAGED_FOLDER" | "MODEL_EVALUATION_STORE";
 export type JobLogFilter = "stdout" | "stderr" | "user" | "errors";
+/** A retrieved job log plus what the byte-bounded download dropped or scanned. */
+export interface JobLogDetails {
+    /** Redacted, filtered and line-limited log text (what {@link JobsResource.log} returns). */
+    text: string;
+    /**
+     * True when the log exceeded the byte cap and only its most recent bytes
+     * were retained: earlier lines were never scanned or filtered.
+     */
+    truncated: boolean;
+    /** Lines in the retained log before filtering and the line limit. */
+    scannedLines: number;
+    /** Byte cap applied to the download (the most recent this-many bytes are kept). */
+    maxLogBytes: number;
+}
 export interface JobLogProgress {
     lastProgressLine?: string;
     doneLine?: string;
@@ -83,11 +97,14 @@ export declare class JobsResource extends BaseResource {
      * Use `0` or `-1` to return the log without line truncation. Credential-like
      * JSON pairs (`"jobTicketSecret":"..."`) are redacted.
      *
-     * The download is byte-bounded and deadline-covered: at most `maxLogBytes`
-     * (default 10 MiB) of the *most recent* log output is retained, so a
-     * collaborator-influenced oversized log cannot exhaust client memory while
-     * the line limit previously only applied after a full unbounded download.
-     * Logs up to the cap are returned in full.
+     * The download is byte-bounded: at most `maxLogBytes` (default 10 MiB) of
+     * the *most recent* log output is retained, so a collaborator-influenced
+     * oversized log cannot exhaust client memory while the line limit
+     * previously only applied after a full unbounded download. The request
+     * timeout is a stall deadline (per received chunk), so a large log that
+     * keeps arriving is not cut off by a total-transfer budget. Logs up to the
+     * cap are returned in full. Use {@link logDetails} to learn whether bytes
+     * were dropped.
      */
     log(jobId: string, opts?: {
         activity?: string;
@@ -97,6 +114,19 @@ export declare class JobsResource extends BaseResource {
         maxLogBytes?: number;
         projectKey?: string;
     }): Promise<string>;
+    /**
+     * Same retrieval as {@link log}, additionally reporting whether the
+     * byte-bounded download dropped early log bytes (`truncated`) and how many
+     * lines were scanned before filtering (`scannedLines`).
+     */
+    logDetails(jobId: string, opts?: {
+        activity?: string;
+        logId?: string;
+        logFilter?: JobLogFilter;
+        maxLogLines?: number;
+        maxLogBytes?: number;
+        projectKey?: string;
+    }): Promise<JobLogDetails>;
     logFromUrl(logUrl: string, opts?: {
         maxLogLines?: number;
         maxLogBytes?: number;

package/dist/src/resources/jobs.js

@@ -66,6 +66,12 @@ function jobBuildDefinition(targets, defaultProjectKey, opts) {
 function jobLogLines(log) {
     return log.split(/\r?\n/).map((line) => line.trimEnd());
 }
+function countLogLines(log) {
+    if (!log)
+        return 0;
+    const lines = jobLogLines(log);
+    return lines[lines.length - 1] === "" ? lines.length - 1 : lines.length;
+}
 /**
  * DSS tags recipe subprocess output by reader thread: `[null-out-N]` carries
  * the child's stdout and `[null-err-N]` its stderr. The legacy fallback is an
@@ -81,6 +87,13 @@ const LEGACY_STDERR_RECORD = /^\s*stderr:/i;
  * continuation of that record (exception chain, JVM frames, ...).
  */
 const DSS_RECORD_HEADER = /^\[\d{4}\/\d{2}\/\d{2}-\d{2}:\d{2}:\d{2}\.\d{3}\]/;
+/**
+ * Job-level outcome line the job engine writes outside any record, e.g.
+ * `2026-10-12T09:13:22.189: Job is incompatible with build state: [...]` when
+ * another running job already builds the target. It carries no level word but
+ * is the only reason DSS gives for such a failure.
+ */
+const JOB_OUTCOME_LINE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}: \S/;
 const ERROR_KEYWORDS = /\b(error|failed|failure|exception|traceback)\b/i;
 /**
  * Exception class names ending in the `Exception`/`Error` suffix (e.g.
@@ -149,7 +162,7 @@ function lineMatchesLogFilter(line, filter) {
         case "stderr":
             return normalized.includes("[null-err-") || LEGACY_STDERR_RECORD.test(line);
         case "errors":
-            return isErrorContent(line);
+            return isErrorContent(line) || JOB_OUTCOME_LINE.test(line);
         case "user":
             return !/^\d{4}[-/]\d{2}[-/]\d{2}/.test(line)
                 && !normalized.includes("backend-log")
@@ -195,6 +208,11 @@ function filterJobLogToErrors(lines) {
             }
             pyTraceback = false;
         }
+        if (JOB_OUTCOME_LINE.test(line)) {
+            kept.push(line);
+            recordMatches = false;
+            continue;
+        }
         if (isHeader) {
             recordMatches = isErrorContent(stripJsonPayloads(line)) || PY_FILE_FRAME.test(message);
             if (recordMatches && (PY_TRACEBACK_HEAD.test(message) || PY_FILE_FRAME.test(message))) {
@@ -322,22 +340,39 @@ export class JobsResource extends BaseResource {
      * Use `0` or `-1` to return the log without line truncation. Credential-like
      * JSON pairs (`"jobTicketSecret":"..."`) are redacted.
      *
-     * The download is byte-bounded and deadline-covered: at most `maxLogBytes`
-     * (default 10 MiB) of the *most recent* log output is retained, so a
-     * collaborator-influenced oversized log cannot exhaust client memory while
-     * the line limit previously only applied after a full unbounded download.
-     * Logs up to the cap are returned in full.
+     * The download is byte-bounded: at most `maxLogBytes` (default 10 MiB) of
+     * the *most recent* log output is retained, so a collaborator-influenced
+     * oversized log cannot exhaust client memory while the line limit
+     * previously only applied after a full unbounded download. The request
+     * timeout is a stall deadline (per received chunk), so a large log that
+     * keeps arriving is not cut off by a total-transfer budget. Logs up to the
+     * cap are returned in full. Use {@link logDetails} to learn whether bytes
+     * were dropped.
      */
     async log(jobId, opts) {
+        return (await this.logDetails(jobId, opts)).text;
+    }
+    /**
+     * Same retrieval as {@link log}, additionally reporting whether the
+     * byte-bounded download dropped early log bytes (`truncated`) and how many
+     * lines were scanned before filtering (`scannedLines`).
+     */
+    async logDetails(jobId, opts) {
         const jobEnc = encodeURIComponent(jobId);
         const query = opts?.activity ? `?activity=${encodeURIComponent(opts.activity)}` : "";
         // DSS cat-activity-log URLs require a browser session; API-key callers must use the public log endpoint.
         const path = `/public/api/projects/${this.enc(opts?.projectKey)}/jobs/${jobEnc}/log/${query}`;
         const maxLogBytes = Math.max(1, opts?.maxLogBytes ?? DEFAULT_MAX_LOG_BYTES);
-        const { text, } = await this.client.getTextTailLimited(path, maxLogBytes);
+        const { text, truncated, } = await this.client.getTextTailLimited(path, maxLogBytes);
         // Single download choke point (logFromUrl and wait/summary go through here):
         // DSS logs embed the job ticket secret in start_session JSON.
-        return limitJobLog(filterJobLog(redactCredentialPairs(text), opts?.logFilter), opts?.maxLogLines);
+        const redacted = redactCredentialPairs(text);
+        return {
+            text: limitJobLog(filterJobLog(redacted, opts?.logFilter), opts?.maxLogLines),
+            truncated,
+            scannedLines: countLogLines(redacted),
+            maxLogBytes,
+        };
     }
     async logFromUrl(logUrl, opts) {
         const parsed = new URL(logUrl, "http://dss.local");
@@ -438,6 +473,28 @@ export class JobsResource extends BaseResource {
         const startedAt = Date.now();
         let pollCount = 0;
         let lastJ;
+        // The wait only stops polling: the job keeps running in DSS and is never
+        // cancelled, so the result says so explicitly.
+        const timedOutResult = (last, elapsedMs) => {
+            const bs = last?.baseStatus ?? {};
+            const gs = last?.globalState ?? {};
+            return {
+                success: false,
+                jobId,
+                state: bs.state ?? "unknown",
+                type: bs.def?.type ?? "unknown",
+                elapsedMs,
+                pollCount,
+                timedOut: true,
+                cancelled: false,
+                progress: {
+                    done: gs.done ?? 0,
+                    failed: gs.failed ?? 0,
+                    running: gs.running ?? 0,
+                    total: gs.total ?? null,
+                },
+            };
+        };
         while (true) {
             const elapsedBeforeMs = Date.now() - startedAt;
             // The first observation always happens, even when the budget is
@@ -445,24 +502,7 @@ export class JobsResource extends BaseResource {
             // the loop reports the structured timeout from the last observed
             // state instead of issuing a request the budget cannot cover.
             if (lastJ !== undefined && elapsedBeforeMs >= timeout) {
-                const bs = lastJ.baseStatus ?? {};
-                const def = bs.def ?? {};
-                const gs = lastJ.globalState ?? {};
-                return {
-                    success: false,
-                    jobId,
-                    state: bs.state ?? "unknown",
-                    type: def.type ?? "unknown",
-                    elapsedMs: elapsedBeforeMs,
-                    pollCount,
-                    timedOut: true,
-                    progress: {
-                        done: gs.done ?? 0,
-                        failed: gs.failed ?? 0,
-                        running: gs.running ?? 0,
-                        total: gs.total ?? null,
-                    },
-                };
+                return timedOutResult(lastJ, elapsedBeforeMs);
             }
             pollCount += 1;
             // Requests issued while budget remains are bounded by the remaining
@@ -482,21 +522,8 @@ export class JobsResource extends BaseResource {
                 // error escape the loop.
                 if (!isRequestDeadlineError(error, startedAt + timeout))
                     throw error;
-                return {
-                    success: false,
-                    jobId,
-                    state: "unknown",
-                    type: "unknown",
-                    elapsedMs: Date.now() - startedAt,
-                    pollCount,
-                    timedOut: true,
-                    progress: {
-                        done: 0,
-                        failed: 0,
-                        running: 0,
-                        total: null,
-                    },
-                };
+                // A deadline mid-poll keeps the last state a previous poll observed.
+                return timedOutResult(lastJ, Date.now() - startedAt);
             }
             lastJ = j;
             const bs = j.baseStatus ?? {};