dataiku-sdk 1.0.0 → 1.1.0

package/dist/src/resources/datasets.js

@@ -134,46 +134,52 @@ export function validateStreamColumns(headerRow, expectedColumns) {
     }
     return warnings;
 }
-function buildPreviewTimeoutError(timeoutMs) {
-    return new DataikuError(0, "Request Timeout", `Dataset preview timed out after ${timeoutMs}ms while waiting for rows.`);
+function buildStreamTimeoutError(timeoutMs, action) {
+    return new DataikuError(0, "Request Timeout", `Dataset ${action} timed out after ${timeoutMs}ms while waiting for rows.`);
 }
-async function readChunkWithTimeout(reader, remainingMs, timeoutMs) {
-    return new Promise((resolveChunk, rejectChunk) => {
-        const timer = setTimeout(() => {
-            void reader.cancel(buildPreviewTimeoutError(timeoutMs)).catch(() => { });
-            rejectChunk(buildPreviewTimeoutError(timeoutMs));
-        }, remainingMs);
-        reader.read().then((result) => {
-            clearTimeout(timer);
-            resolveChunk(result);
-        }, (error) => {
-            clearTimeout(timer);
-            rejectChunk(error);
-        });
+async function readChunkWithTimeout(reader, remainingMs, timeoutMs, action) {
+    const { promise, resolve, reject, } = Promise.withResolvers();
+    const timer = setTimeout(() => {
+        void reader.cancel(buildStreamTimeoutError(timeoutMs, action)).catch(() => { });
+        reject(buildStreamTimeoutError(timeoutMs, action));
+    }, remainingMs);
+    reader.read().then((result) => {
+        clearTimeout(timer);
+        resolve(result);
+    }, (error) => {
+        clearTimeout(timer);
+        reject(error);
     });
+    return promise;
 }
 async function collectPreviewRows(body, maxDataRows, timeoutMs, onHeader) {
     const state = createTsvStreamState();
     let columns;
     const rows = [];
     let done = false;
+    let truncated = false;
     const startedAt = Date.now();
     const reader = body.getReader();
+    let columnCount = 0;
     const handleRow = (row) => {
-        if (done || isBlankRow(row))
+        if (done)
             return;
         if (columns === undefined) {
+            if (isBlankRow(row))
+                return;
             columns = row;
+            columnCount = row.length;
             onHeader?.(row);
             return;
         }
+        if (isBlankRow(row) && columnCount !== 1)
+            return;
         if (rows.length >= maxDataRows) {
+            truncated = true;
             done = true;
             return;
         }
         rows.push(row);
-        if (rows.length >= maxDataRows)
-            done = true;
     };
     try {
         while (true) {
@@ -183,15 +189,73 @@ async function collectPreviewRows(body, maxDataRows, timeoutMs, onHeader) {
             }
             const remainingMs = timeoutMs - (Date.now() - startedAt);
             if (remainingMs <= 0)
-                throw buildPreviewTimeoutError(timeoutMs);
-            const result = await readChunkWithTimeout(reader, remainingMs, timeoutMs);
+                throw buildStreamTimeoutError(timeoutMs, "preview");
+            const result = await readChunkWithTimeout(reader, remainingMs, timeoutMs, "preview");
             if (result.done)
                 break;
             consumeTsvChunk(Buffer.from(result.value).toString("utf-8"), state, handleRow);
         }
         if (!done)
             flushTsvStream(state, handleRow);
-        return { columns: columns ?? [], rows, };
+        return { columns: columns ?? [], rows, truncated, };
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/**
+ * Count data rows in a streamed TSV response (header row excluded), stopping
+ * as soon as `stopAfter` rows have been seen so a mismatched dataset is never
+ * fully scanned. Returns the exact count when the stream ends before the cap,
+ * or `stopAfter` — a lower bound — once the cap is reached.
+ */
+async function collectTsvRowCount(body, stopAfter, timeoutMs) {
+    const state = createTsvStreamState();
+    let headerSeen = false;
+    let count = 0;
+    let bounded = false;
+    const startedAt = Date.now();
+    const reader = body.getReader();
+    let columnCount = 0;
+    const handleRow = (row) => {
+        if (bounded)
+            return;
+        if (!headerSeen) {
+            if (isBlankRow(row))
+                return;
+            headerSeen = true;
+            columnCount = row.length;
+            return;
+        }
+        // An empty line is structurally invalid in a multi-column TSV (blank
+        // rows are tolerated and skipped), but for single-column datasets an
+        // empty line is a real data row carrying an empty string value and
+        // must be counted. The stream parser only emits rows for real line
+        // terminators, so the synthetic trailing newline never produces one.
+        if (isBlankRow(row) && columnCount !== 1)
+            return;
+        count += 1;
+        if (count >= stopAfter)
+            bounded = true;
+    };
+    try {
+        while (true) {
+            if (bounded) {
+                void reader.cancel().catch(() => { });
+                break;
+            }
+            const remainingMs = timeoutMs - (Date.now() - startedAt);
+            if (remainingMs <= 0) {
+                throw buildStreamTimeoutError(timeoutMs, "row count assertion");
+            }
+            const result = await readChunkWithTimeout(reader, remainingMs, timeoutMs, "row count assertion");
+            if (result.done)
+                break;
+            consumeTsvChunk(Buffer.from(result.value).toString("utf-8"), state, handleRow);
+        }
+        if (!bounded)
+            flushTsvStream(state, handleRow);
+        return { count, bounded, };
     }
     finally {
         reader.releaseLock();
@@ -202,15 +266,21 @@ function tsvToCsvTransform(maxDataRows, stats, onHeader) {
     const maxRows = Math.max(1, maxDataRows);
     let headerSeen = false;
     let done = false;
+    let columnCount = 0;
     const handleRow = (row, push) => {
-        if (done || isBlankRow(row))
+        if (done)
             return;
         if (!headerSeen) {
+            if (isBlankRow(row))
+                return;
             headerSeen = true;
+            columnCount = row.length;
             onHeader?.(row);
             push(`${rowToCsv(row)}\n`);
             return;
         }
+        if (isBlankRow(row) && columnCount !== 1)
+            return;
         if (stats.rows >= maxRows) {
             stats.truncated = true;
             done = true;
@@ -337,6 +407,21 @@ function cloneDatasetParams(params) {
     }
     return cloned;
 }
+function parseUploadedFiles(raw, datasetName) {
+    if (!Array.isArray(raw)) {
+        throw new ClientValidationError(`DSS returned an invalid uploaded-files list for dataset ${datasetName}.`, "validation_failed", "Expected an array from the UploadedFiles dataset file endpoint.");
+    }
+    return raw.map((item, index) => {
+        if (!item
+            || typeof item !== "object"
+            || Array.isArray(item)
+            || typeof item.filename !== "string"
+            || item.filename === "") {
+            throw new ClientValidationError(`DSS returned invalid metadata for uploaded file ${String(index)} in dataset ${datasetName}.`, "validation_failed", "Expected every uploaded file to include a non-empty filename.");
+        }
+        return item;
+    });
+}
 export function buildDatasetCloneSettings(source, targetName, projectKey, opts) {
     const params = {
         ...cloneDatasetParams(source.params),
@@ -395,6 +480,14 @@ export class DatasetsResource extends BaseResource {
         const dsEnc = encodeURIComponent(datasetName);
         await this.client.put(`/public/api/projects/${this.enc(projectKey)}/datasets/${dsEnc}/schema`, { columns, });
     }
+    /**
+     * Get the raw dataset schema object exactly as the DSS schema endpoint
+     * returns it, without schema validation — used for deterministic comparison.
+     */
+    async getSchemaObject(datasetName, projectKey) {
+        const dsEnc = encodeURIComponent(datasetName);
+        return this.client.get(`/public/api/projects/${this.enc(projectKey)}/datasets/${dsEnc}/schema`);
+    }
     /**
      * Preview dataset rows as structured data: column names plus row arrays,
      * mirroring the sql query shape ({ columns, rows, rowCount }). Streams TSV
@@ -407,7 +500,9 @@ export class DatasetsResource extends BaseResource {
         const maxRows = Math.max(1, Math.min(opts?.maxRows ?? 50, 500));
         const timeoutMs = Math.max(1, opts?.timeoutMs ?? this.client.getRequestTimeoutMs());
         const dsEnc = encodeURIComponent(datasetName);
-        const res = await this.client.stream(`/public/api/projects/${this.enc(opts?.projectKey)}/datasets/${dsEnc}/data/?format=tsv-excel-header&limit=${maxRows}`);
+        // 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.client.stream(`/public/api/projects/${this.enc(opts?.projectKey)}/datasets/${dsEnc}/data/?format=tsv-excel-header&limit=${maxRows + 1}`);
         const onHeader = opts?.validateColumns
             ? (headerRow) => {
                 const warnings = validateStreamColumns(headerRow, opts.validateColumns);
@@ -416,10 +511,39 @@ export class DatasetsResource extends BaseResource {
                 }
             }
             : undefined;
-        if (!res.body)
-            return { columns: [], rows: [], rowCount: 0, };
-        const { columns, rows, } = await collectPreviewRows(res.body, maxRows, timeoutMs, onHeader);
-        return { columns: columns.map((name) => ({ name, })), rows, rowCount: rows.length, };
+        if (!res.body) {
+            return { columns: [], rows: [], rowCount: 0, truncated: false, limit: maxRows, };
+        }
+        const { columns, rows, truncated, } = await collectPreviewRows(res.body, maxRows, timeoutMs, onHeader);
+        return {
+            columns: columns.map((name) => ({ name, })),
+            rows,
+            rowCount: rows.length,
+            truncated,
+            limit: maxRows,
+        };
+    }
+    /**
+     * Count dataset rows by streaming the TSV data endpoint and stopping as soon
+     * as `expected + 1` rows have been seen, so a mismatched dataset is never
+     * fully scanned. Returns the observed count together with `exact` (false when
+     * the probe cap was reached, i.e. the count is a lower bound) and whether the
+     * count satisfies the assertion.
+     */
+    async assertRowCount(datasetName, expected, projectKey) {
+        if (!Number.isSafeInteger(expected) || expected < 0) {
+            throw new ClientValidationError("expected row count must be a non-negative safe integer", "validation_failed");
+        }
+        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}`);
+        if (!res.body) {
+            return { expected: target, count: 0, exact: true, satisfied: target === 0, };
+        }
+        const { count, bounded, } = await collectTsvRowCount(res.body, probe, timeoutMs);
+        return { expected: target, count, exact: !bounded, satisfied: !bounded && count === target, };
     }
     /** Get dataset metadata (tags, custom fields, checklists). */
     async metadata(datasetName, projectKey) {
@@ -559,6 +683,7 @@ export class DatasetsResource extends BaseResource {
             ? params.table
             : null;
         const normalizedType = (type ?? "").toLowerCase();
+        const uploadedFiles = normalizedType.includes("uploaded");
         const fileBacked = !table
             && (normalizedType.includes("filesystem")
                 || normalizedType.includes("uploaded")
@@ -566,7 +691,7 @@ export class DatasetsResource extends BaseResource {
                 || path !== null);
         const formatType = details.formatType ?? null;
         const warnings = [];
-        if (fileBacked && !path) {
+        if (fileBacked && !uploadedFiles && !path) {
             warnings.push("File-backed dataset has no writable storage path configured.");
         }
         if (fileBacked && !formatType) {
@@ -585,6 +710,52 @@ export class DatasetsResource extends BaseResource {
             note: "Validates build configuration only; it does not verify storage file existence or materialized data.",
         };
     }
+    /** List files stored by an UploadedFiles dataset. */
+    async listUploadedFiles(datasetName, projectKey) {
+        const raw = await this.client.get(`/public/api/projects/${this.enc(projectKey)}/datasets/${encodeURIComponent(datasetName)}/uploaded/files`);
+        return parseUploadedFiles(raw, datasetName);
+    }
+    /** Add a new file to an UploadedFiles dataset and verify its byte length. */
+    async uploadDatasetFile(datasetName, localPath, opts) {
+        const fileName = opts.fileName.trim();
+        if (fileName === "") {
+            throw new ClientValidationError("fileName must be a non-empty uploaded filename.");
+        }
+        const localFile = await fs.promises.stat(localPath);
+        if (!localFile.isFile()) {
+            throw new ClientValidationError(`${localPath} is not a regular file.`);
+        }
+        const projectKey = this.resolveProjectKey(opts.projectKey);
+        const details = await this.get(datasetName, projectKey);
+        if (details.type?.toLowerCase() !== "uploadedfiles") {
+            throw new ClientValidationError(`Dataset ${datasetName} is ${details.type ?? "an unknown type"}, not UploadedFiles.`, "validation_failed", "Use dataset upload-file only with an UploadedFiles dataset.");
+        }
+        const existing = (await this.listUploadedFiles(datasetName, projectKey))
+            .filter((file) => file.filename === fileName);
+        if (existing.length !== 0) {
+            throw new ClientValidationError(`Uploaded file ${fileName} already exists in dataset ${datasetName}.`, "validation_failed", "DSS 14.7's public API can add uploaded files but cannot replace or delete them. Use a new filename or import a successor project archive containing the replacement.");
+        }
+        const endpoint = `/public/api/projects/${encodeURIComponent(projectKey)}/datasets/${encodeURIComponent(datasetName)}/uploaded/files`;
+        await this.client.upload(endpoint, localPath, fileName);
+        const afterMatches = (await this.listUploadedFiles(datasetName, projectKey))
+            .filter((file) => file.filename === fileName);
+        const after = afterMatches[0];
+        if (afterMatches.length !== 1
+            || after === undefined
+            || after.length !== localFile.size) {
+            throw new ClientValidationError(`DSS did not verify upload of ${fileName} to dataset ${datasetName}.`, "ambiguous_outcome", "The upload returned successfully, but the uploaded-files listing did not show exactly one target with the local byte length. Inspect the dataset before retrying.", {
+                expectedBytes: localFile.size,
+                matchingFiles: afterMatches,
+            });
+        }
+        return {
+            datasetName,
+            projectKey,
+            fileName,
+            bytes: localFile.size,
+            after,
+        };
+    }
     /** Clone dataset settings, preserving connection/storage, format, and schema fields. */
     async clone(sourceName, targetName, opts = {}) {
         const pk = this.resolveProjectKey(opts.projectKey);

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

@@ -64,10 +64,30 @@ export interface ProjectImportUploadResult {
     id: string;
     [key: string]: unknown;
 }
+export interface ProjectImportSettings {
+    targetProjectKey?: string;
+    remapping?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface ProjectImportProcessResult {
+    /** Present on definitive responses; a missing or non-boolean value makes the outcome indeterminate. */
+    success?: boolean;
+    /** Project key DSS actually created (after remapping). Definitive success includes it. */
+    usedProjectKey?: string;
+    [key: string]: unknown;
+}
+export interface ProjectImportResult extends ProjectImportProcessResult {
+    importId: string;
+    /** Key the import was bound to: the explicit settings target, else the archive manifest's key. Known on success. */
+    requestedProjectKey?: string;
+    /** True when usedProjectKey differs from requestedProjectKey (set only when both are known). */
+    remapped?: boolean;
+    /** SHA-256 fingerprint of the landed project's creationTag. Present on verified success. */
+    projectIncarnationHash?: string;
+}
 export declare class ProjectsResource extends BaseResource {
     private httpInternals;
     private postStream;
-    private uploadJson;
     /** Create a new project. */
     createProject(projectKey: string, name: string, ownerLogin: string, settings?: ProjectLifecycleSettings | null): Promise<Record<string, unknown>>;
     /** Delete a project using the lifecycle endpoint. */
@@ -76,8 +96,21 @@ export declare class ProjectsResource extends BaseResource {
     duplicate(projectKey: string, targetProjectKey: string, targetProjectName: string, options?: ProjectDuplicateOptions): Promise<Record<string, unknown>>;
     /** Export a project archive to a local file. */
     exportArchive(projectKey: string, filePath: string, options?: ProjectExportOptions): Promise<void>;
-    /** Upload a project archive and return the temporary import id. */
-    importProjectFromArchive(filePath: string): Promise<ProjectImportUploadResult>;
+    /** Upload a project archive and return its temporary import handle. */
+    prepareProjectImport(filePath: string): Promise<ProjectImportUploadResult>;
+    /** Process an uploaded archive into a DSS project. */
+    processProjectImport(importId: string, settings?: ProjectImportSettings): Promise<ProjectImportProcessResult>;
+    /**
+     * Upload and process a project archive.
+     *
+     * The archive is validated locally before anything is uploaded. Definitive
+     * failures surface the process response verbatim (with `importId`); every
+     * indeterminate path throws ClientValidationError(`ambiguous_outcome`).
+     * Verified success carries the actually-used project key, the requested
+     * key when known (with explicit `remapped` reporting), and the landed
+     * project's incarnation hash for identity-bound cleanup and guarded deletes.
+     */
+    importProjectFromArchive(filePath: string, settings?: ProjectImportSettings): Promise<ProjectImportResult>;
     /** Get project permissions. */
     getPermissions(projectKey?: string): Promise<ProjectPermissions>;
     /** Set project permissions. */

package/dist/src/resources/projects.js

@@ -1,7 +1,10 @@
-import { createWriteStream, openAsBlob, } from "node:fs";
+import { createWriteStream, } from "node:fs";
 import { Writable, } from "node:stream";
+import { ClientValidationError, DataikuError, } from "../errors.js";
 import { ProjectDetailsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, } from "../schemas.js";
 import { normalizeFlowGraph, } from "../utils/flow-map.js";
+import { assertImportableProjectArchive, } from "../utils/project-archive.js";
+import { projectIncarnationHash, } from "../utils/project-incarnation.js";
 import { BaseResource, } from "./base.js";
 function fetchWithTimeout(label, timeoutMs, fetcher) {
     return new Promise((resolve) => {
@@ -100,6 +103,7 @@ function truncateFlowMap(normalized, maxNodes, maxEdges) {
 const DEFAULT_MAX_NODES = 300;
 const DEFAULT_MAX_EDGES = 600;
 const DEFAULT_METADATA_TIMEOUT_MS = 1_500;
+const PROJECT_IMPORT_AMBIGUOUS_REMEDIATION = "Import processing left DSS state indeterminate. Inspect the archive with `dss project inspect-archive <file>` and the live projects with `dss project list` before retrying the import.";
 export class ProjectsResource extends BaseResource {
     httpInternals() {
         return this.client;
@@ -116,18 +120,6 @@ export class ProjectsResource extends BaseResource {
             body: JSON.stringify(body),
         });
     }
-    async uploadJson(path, filePath, fileName) {
-        const http = this.httpInternals();
-        const fileBlob = await openAsBlob(filePath);
-        const formData = new FormData();
-        formData.append("file", fileBlob, fileName);
-        const res = await http.fetchWithRetry(`${http.baseUrl}${path}`, {
-            method: "POST",
-            headers: { Authorization: `Bearer ${http.apiKey}`, },
-            body: formData,
-        });
-        return res.json();
-    }
     /** Create a new project. */
     async createProject(projectKey, name, ownerLogin, settings) {
         return this.client.post("/public/api/projects/", {
@@ -176,9 +168,128 @@ export class ProjectsResource extends BaseResource {
             throw error;
         }
     }
-    /** Upload a project archive and return the temporary import id. */
-    async importProjectFromArchive(filePath) {
-        return this.uploadJson("/public/api/projects/import/upload", filePath, "tmp-import.zip");
+    /** Upload a project archive and return its temporary import handle. */
+    async prepareProjectImport(filePath) {
+        const upload = await this.client.uploadJson("/public/api/projects/import/upload", filePath, "tmp-import.zip");
+        if (!upload || typeof upload.id !== "string" || upload.id.trim() === "") {
+            throw new ClientValidationError("DSS accepted the project archive upload but did not return a temporary import id.", "ambiguous_outcome", "The archive may remain in temporary DSS storage, but no project import was started. Inspect DSS before retrying.");
+        }
+        return upload;
+    }
+    /** Process an uploaded archive into a DSS project. */
+    async processProjectImport(importId, settings = {}) {
+        const body = Object.keys(settings).length === 0 ? { _: "_", } : settings;
+        try {
+            const response = await this.client.post(`/public/api/projects/import/${encodeURIComponent(importId)}/process`, body);
+            // An empty or null 2xx body carries no definitive outcome: DSS may
+            // have created the project, partially processed it, or done nothing.
+            if (!response) {
+                throw new ClientValidationError("DSS accepted the import process request but returned no response body: the project may or may not have been created.", "ambiguous_outcome", PROJECT_IMPORT_AMBIGUOUS_REMEDIATION, {
+                    importId,
+                    ...(typeof settings.targetProjectKey === "string"
+                        && settings.targetProjectKey.trim() !== ""
+                        ? { targetProjectKey: settings.targetProjectKey, }
+                        : {}),
+                });
+            }
+            return response;
+        }
+        catch (error) {
+            // A transport timeout or server-side 5xx leaves the import outcome
+            // unknowable: the project may or may not exist. Surface that as an
+            // ambiguous outcome — never as a definitive failure. A 2xx
+            // response that carried a non-JSON body has the same property.
+            if (error instanceof DataikuError
+                && (error.status === 0
+                    || error.status >= 500
+                    || (error.status >= 200 && error.status < 300))) {
+                throw new ClientValidationError(error.status >= 200 && error.status < 300
+                    ? "DSS returned a non-JSON process response: the import outcome is indeterminate and the project may or may not have been created."
+                    : "DSS returned no definitive import result: the project may or may not have been created.", "ambiguous_outcome", PROJECT_IMPORT_AMBIGUOUS_REMEDIATION, {
+                    importId,
+                    ...(typeof settings.targetProjectKey === "string"
+                        && settings.targetProjectKey.trim() !== ""
+                        ? { targetProjectKey: settings.targetProjectKey, }
+                        : {}),
+                });
+            }
+            throw error;
+        }
+    }
+    /**
+     * Upload and process a project archive.
+     *
+     * The archive is validated locally before anything is uploaded. Definitive
+     * failures surface the process response verbatim (with `importId`); every
+     * indeterminate path throws ClientValidationError(`ambiguous_outcome`).
+     * Verified success carries the actually-used project key, the requested
+     * key when known (with explicit `remapped` reporting), and the landed
+     * project's incarnation hash for identity-bound cleanup and guarded deletes.
+     */
+    async importProjectFromArchive(filePath, settings = {}) {
+        // Fatal archive problems abort before any DSS call or upload.
+        const inspection = await assertImportableProjectArchive(filePath);
+        const requestedProjectKey = typeof settings.targetProjectKey === "string"
+            && settings.targetProjectKey.trim() !== ""
+            ? settings.targetProjectKey
+            : inspection.sourceProjectKey;
+        const upload = await this.prepareProjectImport(filePath);
+        const result = await this.processProjectImport(upload.id, settings);
+        const importId = upload.id;
+        if (typeof result.success !== "boolean") {
+            throw new ClientValidationError("DSS returned a process response without a boolean success field: the import outcome is indeterminate.", "ambiguous_outcome", PROJECT_IMPORT_AMBIGUOUS_REMEDIATION, {
+                importId,
+                ...(requestedProjectKey !== undefined
+                    ? { targetProjectKey: requestedProjectKey, }
+                    : {}),
+            });
+        }
+        if (result.success === false) {
+            // Definitive DSS-side failure: keep the response authoritative and
+            // let the command layer report it as a plain command failure.
+            return { ...result, success: false, importId, };
+        }
+        const usedProjectKey = typeof result.usedProjectKey === "string"
+            && result.usedProjectKey.trim() !== ""
+            ? result.usedProjectKey
+            : undefined;
+        if (usedProjectKey === undefined) {
+            throw new ClientValidationError("DSS reported import success but did not name the project that was created.", "ambiguous_outcome", PROJECT_IMPORT_AMBIGUOUS_REMEDIATION, {
+                importId,
+                ...(requestedProjectKey !== undefined
+                    ? { targetProjectKey: requestedProjectKey, }
+                    : {}),
+            });
+        }
+        // Verify the claimed landing and capture identity for cleanup binding.
+        let details;
+        try {
+            details = await this.get(usedProjectKey);
+        }
+        catch (error) {
+            if (error instanceof DataikuError
+                && (error.status === 404 || error.status === 0 || error.status >= 500)) {
+                throw new ClientValidationError(`DSS reported import success for project ${usedProjectKey}, but the project could not be re-read for verification.`, "ambiguous_outcome", PROJECT_IMPORT_AMBIGUOUS_REMEDIATION, { importId, usedProjectKey, });
+            }
+            throw error;
+        }
+        const incarnation = projectIncarnationHash(usedProjectKey, details);
+        if (incarnation === undefined) {
+            throw new ClientValidationError(`DSS imported project ${usedProjectKey}, but returned no creationTag identity.`, "ambiguous_outcome", "Refusing to claim identity-bound success without a project-incarnation hash. Verify the project identity before any cleanup or guarded delete.", { importId, usedProjectKey, });
+        }
+        return {
+            ...result,
+            success: true,
+            importId,
+            usedProjectKey,
+            projectIncarnationHash: incarnation,
+            ...(requestedProjectKey === undefined
+                ? {}
+                : {
+                    requestedProjectKey,
+                    remapped: requestedProjectKey !== usedProjectKey,
+                }),
+        };
     }
     /** Get project permissions. */
     async getPermissions(projectKey) {

package/dist/src/utils/project-archive.d.ts

@@ -0,0 +1,32 @@
+export type ProjectArchiveIssueSeverity = "error" | "warning";
+export interface ProjectArchiveIssue {
+    severity: ProjectArchiveIssueSeverity;
+    code: string;
+    message: string;
+    member?: string;
+}
+export interface ProjectArchiveInspection {
+    filePath: string;
+    sizeBytes: number;
+    memberCount: number;
+    sourceProjectKey?: string;
+    valid: boolean;
+    issues: ProjectArchiveIssue[];
+}
+/**
+ * Inspect a DSS project export ZIP archive without extracting anything to
+ * disk: enumerate every central-directory record, validate member paths
+ * independently, stream every file member through a size/CRC-32 check with
+ * bounded memory (manual `node:zlib.crc32`, covering data-descriptor
+ * records), parse `export-manifest.json` and the source project key, and run
+ * the generic dangling-reference/orphan-member graph checks. Identity,
+ * history and machine-specific residue is reported only as warnings carrying
+ * member paths and pattern counts, never matched values.
+ */
+export declare function inspectProjectArchive(filePath: string): Promise<ProjectArchiveInspection>;
+/**
+ * Like `inspectProjectArchive`, but throws a `ClientValidationError` with the
+ * `validation_failed` code when the inspection contains any error-severity
+ * issue, so the archive cannot be imported.
+ */
+export declare function assertImportableProjectArchive(filePath: string): Promise<ProjectArchiveInspection>;