dataiku-sdk 1.0.0 → 2.0.0

package/README.md

@@ -4,7 +4,7 @@ Agent-only TypeScript SDK and `dss` CLI for Dataiku DSS automation.
 
 ## Platform support
 
-The published `dss` CLI supports Linux, macOS, and Windows under Bun >= 1.3.14 or Node.js >= 22.15.0. The release gate runs Bun 1.3.14 with Node 24 on all three operating systems, plus a lightweight minimum-Node 22.15 package smoke on Linux. The runtime dependency is pure JavaScript, so the same package also runs on runtime-supported x64 and ARM64 systems.
+The published `dss` CLI requires Bun >= 1.4.0 and supports Linux, macOS, and Windows. The release gate runs Bun 1.4.0 on all three operating systems. The runtime dependency is pure JavaScript, so the same package also runs on every Bun-supported x64 and ARM64 system.
 
 Run directly with Bun:
 
@@ -17,9 +17,11 @@ Or install the npm binary:
 ```text
 npm install --global dataiku-sdk
 ```
+The installed `dss` bin bootstraps Bun with automatic `.env` preloading disabled, so Bun >= 1.4.0 must be on `PATH`; the CLI's own `.env` handling stays authoritative. `bunx --bun` forces Bun's Node-compatibility mode, which provides the same no-preload guarantee across operating systems.
 
-Bun is the primary development runtime and package manager. Examples below assume an installed `dss` binary. From a checkout, use `bun --no-env-file src/cli.ts ...` or the cross-runtime `bun --no-env-file ./bin/dss.js ...` launcher. Node users can invoke the same launcher as `node ./bin/dss.js ...`; if `dist/` is absent, it delegates to Bun. From another working directory, pass the checkout's absolute `bin/dss.js` path to Bun or Node.
+Bun is the only supported runtime and the package manager. Examples below assume an installed `dss` binary. From a checkout, use `bun --no-env-file src/cli.ts ...` or the packaged launcher `bun --no-env-file ./bin/dss.js ...`. From another working directory, pass the checkout's absolute `bin/dss.js` path to Bun.
 `--no-env-file` disables Bun's automatic preloading only; the CLI still applies its documented `.env` handling unless `DATAIKU_DISABLE_ENV=1` is set.
+`dss version` reports whether the running code came from `source` or `dist`, the runtime (always `bun`), the packaged build revision when available, and `staleBuild` when that revision differs from the checkout. Release builds generate `dist/build-metadata.json`; source snapshots without Git metadata still build but report no build revision.
 
 ## CLI contract
 
@@ -119,7 +121,14 @@ The command saves credentials and returns `{ "saved": true, "path": "..." }`.
 dss version
 dss doctor --fast
 dss project list
+dss project inspect-archive ./project.zip
+dss project import ./project.zip --target-project-key IMPORTED_PROJECT --record-cleanup cleanup.jsonl
 dss dataset list --project-key MYPROJ
+dss dataset files uploaded_input --project-key MYPROJ
+dss dataset upload-file uploaded_input ./new.csv --file-name new.csv --project-key MYPROJ
+dss dataset assert-count jmp_doe_ready --expected 12 --project-key MYPROJ
+dss dataset assert-schema jmp_doe_ready --data-file expected-schema.json --project-key MYPROJ
+dss data-quality assert-results jmp_doe_ready --project-key MYPROJ
 dss recipe get-payload compute_orders --project-key MYPROJ
 dss recipe get-payload compute_orders --output code.py --project-key MYPROJ
 dss install-skill --dry-run
@@ -127,7 +136,8 @@ dss app validate-manifest --project-key MYAPP_INSTANCE
 dss app compare-manifest my-app --project-key MYAPP_INSTANCE
 dss app create-instance my-app --data '{"targetProjectKey":"MYAPP_INSTANCE"}' --wait --record-cleanup cleanup.jsonl
 dss app manifest-version --project-key MYAPP_TEMPLATE
-dss app set-manifest-version --manifest-version 1.4.0 --project-key MYAPP_TEMPLATE
+dss app successor-preflight my-app --from MYAPP_INSTANCE --to MYAPP_INSTANCE_V2 --copy-permissions
+dss app set-manifest-version --manifest-version 1.4.0 --expect-hash PREFLIGHT_TEMPLATE_MANIFEST_HASH --project-key MYAPP_TEMPLATE
 dss app create-successor-instance my-app --from MYAPP_INSTANCE --to MYAPP_INSTANCE_V2 --copy-permissions --record-cleanup cleanup.jsonl
 dss app verify-instance my-app --project-key MYAPP_INSTANCE_V2 --expect-version 1.4.0
 dss app permissions-snapshot --project-key MYAPP_INSTANCE --output permissions.json
@@ -136,6 +146,28 @@ dss app permissions-restore --project-key MYAPP_INSTANCE --file permissions.json
 dss cleanup --file cleanup.jsonl
 dss cleanup --file cleanup.jsonl --apply
 ```
+`project import` performs both public API stages: archive upload, then import processing. It
+first validates ZIP integrity, safe unique member paths, the export manifest, and provable Flow
+references locally. Verified success reports DSS's actual project key, explicit remapping, and a
+`creationTag` incarnation hash; `--record-cleanup` records an incarnation-bound guarded delete.
+It exits nonzero when DSS returns `success:false` even if both HTTP requests succeeded. A timeout,
+5xx, malformed response, missing used key, or failed post-import identity read is
+`ambiguous_outcome` and retains the temporary import ID for inspection before retry.
+
+`dataset upload-file` only adds a filename that is not already present and verifies its byte
+length afterward. DSS 14.7 exposes no public UploadedFiles delete or replacement endpoint;
+the command refuses an existing filename before POST instead of triggering DSS's opaque 500.
+For replacement, import a successor project archive containing the desired upload.
+
+`dataset preview` returns `truncated` and `limit`; it probes one row past the requested cap instead
+of presenting a capped sample as an exact count. `dataset assert-count`, `dataset assert-schema`,
+and `data-quality assert-results` return `satisfied` and exit `4`/`assertion_failed` on a failed
+postcondition, so they can be used as `batch` steps. Multi-job `job monitor` and `job watch`
+aggregate child failures and also exit `4` when any watched job fails.
+
+`doctor` reads the documented `DSS-Version` and `DSS-API-Version` response headers plus the HTTP
+`Date` header from the public project-list call. Feature support remains behavioral: the CLI does
+not call an undocumented feature endpoint or infer licensed capabilities from a version string.
 
 ### Application release safety
 
@@ -152,6 +184,12 @@ dss app compare-manifest APP_ID --project-key RELEASE_INSTANCE
 # Read the raw `version` from the public app manifest (string fields only; never appVersion).
 dss app manifest-version --project-key APP_TEMPLATE
 
+# Run every read-only successor gate before changing the template version. This validates the
+# template references, verifies the predecessor, proves target absence, and optionally snapshots
+# the predecessor ACL. Keep template.manifestHash from the result for the next command.
+dss app successor-preflight APP_ID \
+  --from RELEASE_INSTANCE --to RELEASE_INSTANCE_V2 --copy-permissions
+
 # Write version/versionNotes through the public app-manifest endpoint. This is NOT a publish
 # transaction: it only changes the raw manifest metadata. --expect-hash SHA256 is a non-atomic
 # stale-read guard, not a conditional write: it refuses the write when the manifest already
@@ -159,7 +197,8 @@ dss app manifest-version --project-key APP_TEMPLATE
 # overwrite a write landing between its read and PUT, and the final read cannot detect that lost
 # update when this command's payload wins. Every result reports
 # concurrencyControl: "client-side-non-atomic-stale-read-check".
-dss app set-manifest-version --manifest-version 1.4.0 --project-key APP_TEMPLATE
+dss app set-manifest-version --manifest-version 1.4.0 \
+  --expect-hash PREFLIGHT_TEMPLATE_MANIFEST_HASH --project-key APP_TEMPLATE
 
 # Create an instance only after its target key is confirmed absent, wait on the DSS future, and
 # record deterministic cleanup.
@@ -170,7 +209,8 @@ dss app create-instance APP_ID \
 # Roll out a new template version to an existing instance as an additive successor: the old
 # instance is never modified or deleted, and the command always waits on the DSS future
 # (there is no --wait flag). The recorded cleanup entry targets only the new project key. If DSS
-# accepts creation but returns no future ID, cleanup stops unresolved instead of racing creation.
+# may have accepted creation but no future ID is returned, the outcome is indeterminate and no
+# unbound cleanup entry is written.
 dss app create-successor-instance APP_ID \
   --from RELEASE_INSTANCE --to RELEASE_INSTANCE_V2 \
   --name "Release instance v2" --copy-permissions --record-cleanup cleanup.jsonl
@@ -203,18 +243,32 @@ managed-folder IDs, and runtime-form parameter names against supported public pr
 
 Some DSS deployments hide unknown project keys behind `403` instead of returning `404`.
 Instance creation requires confirmed target absence before POST: an inaccessible target not present
-in the visible project list is still unconfirmed and is rejected rather than risking cleanup
-against a pre-existing project. A definitive create rejection never produces a cleanup entry.
+in the visible project and app-instance lists is still unconfirmed and is rejected with
+`target_absence_unverifiable` / `permission_or_environment` rather than risking cleanup against a
+pre-existing project. Choosing another key does not solve deployments that mask every unknown key.
+DSS exposes no permission-independent public availability endpoint, and its published app-instance
+API does not guarantee duplicate-key rejection before any write or non-overwrite behavior, so
+there is no unsafe force or unconfirmed-target bypass. Use an identity with global project
+visibility. A definitive create rejection never produces a cleanup entry; an ambiguous POST
+without a future ID or verified
+incarnation also produces no cleanup entry.
+
+Static create plans describe, but do not execute, these reads:
+`preflightExecuted:false` and `preflightWillRunDuringApply:true`. Run `successor-preflight` when
+live read evidence is required before changing the template version.
 
 Every new cleanup entry records the canonical DSS URL. App-instance cleanup records a
-`creationTag` hash observed after the DSS future identifies the target key; unconfirmed creation
-stops unresolved. The future target and later `creationTag` are independent, non-atomic
+`creationTag` hash observed after the DSS future identifies the target key; a future-addressable
+entry stops unresolved until the future names that key and its incarnation can be bound. An
+ambiguous POST with no future ID produces no entry. The future target and later `creationTag` are independent, non-atomic
 observations: the public API exposes neither an immutable project ID joined to the future nor a
 conditional DELETE. Cleanup rechecks type and `creationTag` immediately before deletion, rejecting
 detected key reuse, but cannot eliminate replacement in the remaining check-to-DELETE gap.
 `cleanup --apply` validates the full ledger before issuing any request and rejects legacy entries
 without server identity, mixed-server ledgers, entries for another DSS URL, and app cleanup entries
-without a valid incarnation binding.
+without a valid incarnation binding. Project-import cleanup uses the same rule: the ledger binds
+the actual imported key and verified `creationTag` hash, and `project delete
+--expect-project-incarnation` refuses a reused or unverifiable key before DELETE.
 
 Saving `version`/`versionNotes` in the public app manifest is a metadata write, not a publish
 transaction. If the manifest PUT or its verification read has an ambiguous transport/server

package/bin/dss.js

@@ -1,98 +1,87 @@
 #!/usr/bin/env node
+// npm bin for the dss CLI. Bun is the only runtime that executes CLI code.
+// A Node-launched npm shim only bootstraps Bun with automatic .env loading
+// disabled; `bunx --bun` enters Bun's Node-compatibility mode, which disables
+// that loading before this module runs.
 import { spawnSync, } from "node:child_process";
-import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath, pathToFileURL, } from "node:url";
 
-const args = process.argv.slice(2,);
-const optionArgs = args.includes("--",) ? args.slice(0, args.indexOf("--",),) : args;
-const here = path.dirname(fileURLToPath(import.meta.url,),);
-const distCliPath = path.resolve(here, "../dist/src/cli.js",);
-const sourceCliPath = path.resolve(here, "../src/cli.ts",);
-const cliPath = fs.existsSync(distCliPath,) ? distCliPath : sourceCliPath;
-const cliUrl = pathToFileURL(cliPath,).href;
+const runningUnderBun = typeof process.versions.bun === "string";
+const bunNodeCompatibilityMode = runningUnderBun
+	&& (
+		path.basename(process.argv0,).toLowerCase().startsWith("node",)
+		|| (
+			process.env.npm_lifecycle_event === "bunx"
+			&& ["dss", "dataiku-sdk",].includes(process.env.npm_lifecycle_script ?? "",)
+			&& /^bun(?:\.exe)?$/i.test(path.basename(process.env.npm_execpath ?? "",),)
+		)
+	);
+const envFileAutoloadDisabled = process.execArgv.includes("--no-env-file",)
+	|| bunNodeCompatibilityMode;
 
-function flagValue(names,) {
-	for (let i = 0; i < optionArgs.length; i++) {
-		const arg = optionArgs[i];
-		for (const name of names) {
-			if (arg === name) return optionArgs[i + 1];
-			if (arg.startsWith(`${name}=`,)) return arg.slice(name.length + 1,);
-		}
-	}
-	return undefined;
-}
-
-function hasFlag(names,) {
-	return names.some((name,) => optionArgs.includes(name,));
-}
-
-async function loadSavedTlsSettings() {
-	try {
-		const { loadCredentials, } = await import("../dist/src/config.js");
-		const creds = loadCredentials();
-		return {
-			caCertPath: creds?.caCertPath,
-			tlsRejectUnauthorized: creds?.tlsRejectUnauthorized,
-		};
-	} catch {
-		return {};
-	}
-}
-
-const savedTls = await loadSavedTlsSettings();
-const env = { ...process.env, };
-const explicitCaCert = flagValue(["--ca-cert", "--extra-ca-certs",],);
-if (explicitCaCert) {
-	env.NODE_EXTRA_CA_CERTS = explicitCaCert;
-} else if (!env.NODE_EXTRA_CA_CERTS && savedTls.caCertPath) {
-	env.NODE_EXTRA_CA_CERTS = savedTls.caCertPath;
-}
-
-if (hasFlag(["--insecure", "--skip-tls-verify",],)) {
-	env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
-} else if (
-	env.NODE_TLS_REJECT_UNAUTHORIZED === undefined && savedTls.tlsRejectUnauthorized === false
-) {
-	env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
-}
-
-const runningOnBun = Boolean(process.versions.bun,);
-const usesSourceCli = cliPath === sourceCliPath;
-const runtimeBin = runningOnBun ? process.execPath : usesSourceCli ? "bun" : process.execPath;
-const runtimeArgs = runningOnBun || usesSourceCli ? ["--no-env-file",] : ["--use-system-ca",];
-const result = spawnSync(
-	runtimeBin,
-	[...runtimeArgs, cliPath, ...args,],
-	{
-		stdio: "inherit",
-		env,
-	},
-);
-
-if (result.error) {
-	const message = usesSourceCli
-		? `Unable to start Bun runtime for source dss CLI (${result.error.message}).`
-		: `Unable to start ${
-			runningOnBun ? "Bun" : "Node"
-		} runtime for packaged dss CLI (${result.error.message}); falling back to the current runtime.`;
-	if (usesSourceCli) {
+if (!runningUnderBun) {
+	const result = spawnSync(
+		"bun",
+		["--no-env-file", fileURLToPath(import.meta.url,), ...process.argv.slice(2,),],
+		{ stdio: "inherit", env: process.env, },
+	);
+	if (result.error) {
 		process.stdout.write(`${
 			JSON.stringify({
 				type: "error",
 				ok: false,
-				error: message,
+				error: "Unable to start the required Bun runtime.",
 				code: "internal_error",
 				category: "internal",
 				exitCode: 2,
+				hint: "Install Bun >= 1.4.0 and ensure `bun` is on PATH.",
 			},)
 		}\n`,);
 		process.exitCode = 2;
+	} else if (result.signal) {
+		process.kill(process.pid, result.signal,);
 	} else {
-		await import(cliUrl);
+		process.exitCode = result.status ?? 1;
 	}
-} else if (result.signal) {
-	process.kill(process.pid, result.signal,);
+} else if (!envFileAutoloadDisabled) {
+	process.stdout.write(`${
+		JSON.stringify({
+			type: "error",
+			ok: false,
+			error: "Bun automatic .env loading must be disabled for the dss launcher.",
+			code: "env_autoload_enabled",
+			category: "usage",
+			exitCode: 1,
+			hint: "Use `bunx --bun dataiku-sdk` or pass `--no-env-file` before the script path.",
+		},)
+	}\n`,);
+	process.exitCode = 1;
 } else {
-	process.exit(result.status ?? 1,);
+	const here = import.meta.dir;
+	const distCliPath = path.resolve(here, "../dist/src/cli.js",);
+	const sourceCliPath = path.resolve(here, "../src/cli.ts",);
+	const usesDistCli = await Bun.file(distCliPath,).exists();
+	const cliPath = usesDistCli ? distCliPath : sourceCliPath;
+
+	// Published dist carries dist/build-metadata.json with the revision it was
+	// built from. Hand it to the CLI so provenance can report dist source and its
+	// build revision; only a full lowercase hexadecimal revision is accepted, so an
+	// inherited or corrupt variable never stands in for packaged metadata.
+	if (usesDistCli) {
+		process.env.DSS_LOAD_SOURCE = "dist";
+		delete process.env.DSS_BUILD_REVISION;
+		try {
+			const metadata = await Bun.file(path.resolve(here, "../dist/build-metadata.json",),).json();
+			const revision = metadata.buildRevision;
+			if (typeof revision === "string" && /^[0-9a-f]{40}$/.test(revision,)) {
+				process.env.DSS_BUILD_REVISION = revision;
+			}
+		} catch {
+			// Dist without build metadata: provenance still reports dist source.
+		}
+	}
+
+	// Same process, same argv: the CLI sees process.argv.slice(2) exactly as before.
+	await import(pathToFileURL(cliPath,).href);
 }

package/dist/build-metadata.json

@@ -0,0 +1 @@
+{"format":1,"buildRevision":"730725833d165213e28d6affee90bd3c1b012ec9"}

package/dist/src/cli/commands/api-service.js

@@ -1,4 +1,3 @@
-import { writeFileSync, } from "node:fs";
 import { requiredJsonInput, } from "../coerce.js";
 import { requireArgs, UsageError, } from "../usage.js";
 export const apiServiceCommands = {
@@ -100,9 +99,11 @@ export const apiServiceCommands = {
             if (!out)
                 throw new UsageError("--output PATH is required.", "missing_required_flag");
             const res = await c.apiServices.downloadPackageArchive(a[0], a[1], f["project-key"]);
-            const buf = Buffer.from(await res.arrayBuffer());
-            writeFileSync(out, buf);
-            return { path: out, bytes: buf.length, };
+            if (!res.body) {
+                throw new Error("apiServices.downloadPackageArchive response did not include a body");
+            }
+            const bytes = await Bun.write(out, new Response(res.body), { createPath: false, });
+            return { path: out, bytes, };
         },
         usage: "dss api-service download-package <serviceId> <packageId> --output PATH [--project-key KEY]",
         description: "Download an API service package archive to a local file.",

package/dist/src/cli/commands/app.js

@@ -2,16 +2,17 @@ import { ClientValidationError, DataikuError, } from "../../errors.js";
 import { projectIncarnationHash, } from "../../utils/project-incarnation.js";
 import { jsonInput, num, parseBooleanOption, plainRecord, requiredJsonInput, requiredStringFlag, stringField, } from "../coerce.js";
 import { appPermissionsHash, appPermissionsVerificationError, assertAppPermissionsSnapshotBinding, buildAppPermissionsSnapshot, diffAppPermissions, readAppPermissionsSnapshot, writeAppPermissionsSnapshot, } from "../helpers/app-permissions.js";
-import { createSuccessorInstance, futureTargetIdentity, isDefinitiveRejection, requireAbsentProjectTarget, safeErrorSummary, verifyAppInstance, VISUAL_UI_GATE, } from "../helpers/app-successor.js";
+import { createSuccessorInstance, futureTargetIdentity, isDefinitiveRejection, preflightSuccessorInstance, requireAbsentProjectTarget, safeErrorSummary, verifyAppInstance, VISUAL_UI_GATE, } from "../helpers/app-successor.js";
 import { CommandResultFailure, } from "../output.js";
 import { requireArgs, requireNoArgs, UsageError, } from "../usage.js";
 const CREATE_INSTANCE_USAGE = "dss app create-instance <appId> (--data JSON|--data-file PATH|--stdin) [--wait] [--timeout MS] [--poll-interval MS]";
 const MANIFEST_VERSION_USAGE = "dss app manifest-version [--project-key KEY]";
 const SET_MANIFEST_VERSION_USAGE = "dss app set-manifest-version (--manifest-version V|--version-notes NOTES) [--expect-hash SHA256] [--dry-run] [--project-key KEY]";
 const CREATE_SUCCESSOR_USAGE = "dss app create-successor-instance <appId> --from KEY --to KEY [--name NAME] [--copy-permissions] [--timeout MS] [--poll-interval MS] [--dry-run] [--record-cleanup PATH]";
+const SUCCESSOR_PREFLIGHT_USAGE = "dss app successor-preflight <appId> --from KEY --to KEY [--name NAME] [--copy-permissions]";
 const VERIFY_INSTANCE_USAGE = "dss app verify-instance <appId> --project-key KEY [--expect-version V]";
 const DELETE_INSTANCE_USAGE = "dss app delete-instance --project-key KEY [--future-id ID] [--expect-project-incarnation SHA256] [--unconfirmed-creation] [--timeout MS] [--poll-interval MS]";
-const CREATE_INSTANCE_INDETERMINATE_REMEDIATION = "DSS may have accepted the creation, but no future ID proves when it settles. The recorded cleanup entry intentionally stops as unresolved; inspect `dss app instances <appId>` and retry deletion only after creation is known terminal.";
+const CREATE_INSTANCE_INDETERMINATE_REMEDIATION = "DSS may have accepted the creation, but no future ID or project incarnation authorizes cleanup. Inspect `dss app instances <appId>` and DSS task history; delete only after creation is known terminal and the target identity is verified.";
 const CREATE_INSTANCE_REJECTED_REMEDIATION = "DSS refused the creation request, so no instance project was created: fix the reported problem and retry.";
 const DELETE_INSTANCE_FUTURE_REMEDIATION = "The supplied creation future could not authorize deletion. Inspect that future and the target project, then retry only with a future whose terminal result reports this project.";
 const DELETE_INSTANCE_UNCONFIRMED_REMEDIATION = "Creation may still be running and DSS returned no future ID. Inspect the app's instances and wait until creation is known terminal before running delete-instance without --unconfirmed-creation.";
@@ -116,7 +117,9 @@ export const appCommands = {
                 throw new UsageError("Instance creation payload must include a non-empty targetProjectKey.", "validation_failed", `Usage: ${CREATE_INSTANCE_USAGE}`);
             }
             body.targetProjectKey = requestedProjectKey;
-            await requireAbsentProjectTarget(c, requestedProjectKey, "targetProjectKey");
+            await requireAbsentProjectTarget(c, requestedProjectKey, "targetProjectKey", {
+                appId: a[0],
+            });
             let created;
             try {
                 created = await c.applications.createInstance(a[0], body);
@@ -124,15 +127,19 @@ export const appCommands = {
             catch (error) {
                 // A definitive rejection proves nothing was created; anything else
                 // (5xx, retryable 4xx, transport failure) leaves the outcome
-                // unknown and stays cleanup-eligible against the requested key.
+                // unknown. Without a returned future ID or verified incarnation,
+                // cleanup cannot be authorized.
                 const rejected = isDefinitiveRejection(error);
                 return {
                     success: false,
-                    state: "CREATE_FAILED",
+                    state: rejected ? "CREATE_FAILED" : "INDETERMINATE",
                     elapsedMs: 0,
                     pollCount: 0,
                     projectKey: requestedProjectKey,
-                    cleanupEligible: !rejected,
+                    outcome: rejected ? "rejected" : "indeterminate",
+                    creationPostAttempted: true,
+                    cleanupEligible: false,
+                    recoveryCommands: rejected ? [] : [`dss app instances ${a[0]}`,],
                     remediation: rejected
                         ? CREATE_INSTANCE_REJECTED_REMEDIATION
                         : CREATE_INSTANCE_INDETERMINATE_REMEDIATION,
@@ -143,11 +150,13 @@ export const appCommands = {
             if (!instance) {
                 return {
                     success: false,
-                    state: "UNTRACKABLE",
+                    state: "INDETERMINATE",
                     elapsedMs: 0,
                     pollCount: 0,
                     projectKey: requestedProjectKey,
-                    cleanupEligible: true,
+                    outcome: "indeterminate",
+                    creationPostAttempted: true,
+                    cleanupEligible: false,
                     responseKind: created === undefined
                         ? "empty"
                         : created === null
@@ -157,6 +166,7 @@ export const appCommands = {
                                 : "scalar",
                     error: "DSS accepted instance creation without returning a structured creation state.",
                     remediation: CREATE_INSTANCE_INDETERMINATE_REMEDIATION,
+                    recoveryCommands: [`dss app instances ${a[0]}`,],
                 };
             }
             // The create endpoint's `jobId` is a DSS future ID (the official client wraps it in
@@ -174,7 +184,7 @@ export const appCommands = {
                     projectKey: requestedProjectKey,
                     instance,
                     ...(jobId !== undefined ? { futureId: jobId, jobId, } : {}),
-                    cleanupEligible: true,
+                    cleanupEligible: jobId !== undefined,
                     error: "DSS named a different target project in the creation response.",
                     expected: { projectKey: requestedProjectKey, },
                     actual: { projectKey: echoedTarget, },
@@ -251,14 +261,17 @@ export const appCommands = {
             if (!jobId) {
                 return {
                     success: false,
-                    state: "UNTRACKABLE",
+                    state: "INDETERMINATE",
                     elapsedMs: 0,
                     pollCount: 0,
                     projectKey: requestedProjectKey,
                     instance,
-                    cleanupEligible: true,
-                    error: "DSS returned no instance-creation future ID. The instance may still have been created; inspect app instances or replay the recorded cleanup entry.",
+                    outcome: "indeterminate",
+                    creationPostAttempted: true,
+                    cleanupEligible: false,
+                    error: "DSS returned no instance-creation future ID. The instance may still have been created; inspect app instances before any recovery action.",
                     remediation: CREATE_INSTANCE_INDETERMINATE_REMEDIATION,
+                    recoveryCommands: [`dss app instances ${a[0]}`,],
                 };
             }
             let waited;
@@ -278,6 +291,7 @@ export const appCommands = {
                     instance,
                     jobId,
                     cleanupEligible: true,
+                    recoveryCommands: [`dss future wait ${jobId}`, `dss app instances ${a[0]}`,],
                     remediation: CREATE_INSTANCE_INDETERMINATE_REMEDIATION,
                     ...safeErrorSummary(error),
                 };
@@ -343,6 +357,25 @@ export const appCommands = {
             'dss app create-instance my-app --data \'{"targetProjectKey":"NEWPROJ"}\' --wait --timeout 120000 --poll-interval 2000',
         ],
     },
+    "successor-preflight": {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, SUCCESSOR_PREFLIGHT_USAGE);
+            return preflightSuccessorInstance(c, {
+                appId: a[0],
+                from: requiredStringFlag(f, "from", SUCCESSOR_PREFLIGHT_USAGE),
+                to: requiredStringFlag(f, "to", SUCCESSOR_PREFLIGHT_USAGE),
+                ...(f["name"] !== undefined ? { name: f["name"], } : {}),
+                copyPermissions: parseBooleanOption(f["copy-permissions"], "--copy-permissions") ?? false,
+                dryRun: true,
+            }, SUCCESSOR_PREFLIGHT_USAGE);
+        },
+        usage: SUCCESSOR_PREFLIGHT_USAGE,
+        description: "Run every read-only successor gate before changing the template version: validate the template, verify the predecessor, prove target absence, and optionally snapshot the predecessor ACL.",
+        examples: [
+            "dss app successor-preflight my-app --from OLD_INSTANCE --to NEW_INSTANCE",
+            "dss app successor-preflight my-app --from OLD_INSTANCE --to NEW_INSTANCE --copy-permissions",
+        ],
+    },
     "create-successor-instance": {
         handler: async (c, a, f) => {
             requireArgs(a, 1, CREATE_SUCCESSOR_USAGE);

package/dist/src/cli/commands/bundle.js

@@ -1,4 +1,3 @@
-import { writeFileSync, } from "node:fs";
 import { requireArgs, UsageError, } from "../usage.js";
 export const bundleCommands = {
     "list-exported": {
@@ -34,9 +33,11 @@ export const bundleCommands = {
             if (!out)
                 throw new UsageError("--output PATH is required.", "missing_required_flag");
             const res = await c.bundles.downloadExportedArchive(a[0], f["project-key"]);
-            const buf = Buffer.from(await res.arrayBuffer());
-            writeFileSync(out, buf);
-            return { path: out, bytes: buf.length, };
+            if (!res.body) {
+                throw new Error("bundles.downloadExportedArchive response did not include a body");
+            }
+            const bytes = await Bun.write(out, new Response(res.body), { createPath: false, });
+            return { path: out, bytes, };
         },
         usage: "dss bundle download-exported <bundleId> --output PATH [--project-key KEY]",
         description: "Download an exported Design-node bundle archive to a local file.",

package/dist/src/cli/commands/data-quality.js

@@ -2,6 +2,18 @@ import { deepMerge, } from "../../utils/deep-merge.js";
 import { num, parseBooleanOption, requiredJsonInput, } from "../coerce.js";
 import { encodedProjectEndpoint, readIfExists, skipResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
+/**
+ * A data quality result counts as passing only when it actually carries a
+ * verdict and every verdict it carries reports OK. A result with no outcome
+ * and no status has proven nothing, and a result whose fields disagree
+ * (outcome ERROR alongside status OK) is a failure — never a pass.
+ */
+function resultReportsOk(result) {
+    const verdicts = [result.outcome, result.status,]
+        .filter((value) => typeof value === "string" && value.trim().length > 0)
+        .map((value) => value.trim().toUpperCase());
+    return verdicts.length > 0 && verdicts.every((value) => value === "OK");
+}
 export const dataQualityCommands = {
     rules: {
         handler: (c, a, f) => {
@@ -160,6 +172,36 @@ export const dataQualityCommands = {
         description: "Get latest data quality rule results for a dataset.",
         examples: ["dss data-quality last-results orders",],
     },
+    "assert-results": {
+        handler: async (c, a, f) => {
+            requireArgs(a, 1, "dss data-quality assert-results <dataset>");
+            const ruleId = f["rule-id"];
+            const pk = f["project-key"];
+            const results = await c.dataQuality.lastResults(a[0], { ruleId, projectKey: pk, });
+            const selected = results.filter((result) => ruleId === undefined || result.id === ruleId || result.ruleId === ruleId);
+            const failed = selected
+                .filter((result) => !resultReportsOk(result))
+                .map((result) => ({
+                ruleId: result.id ?? result.ruleId ?? result.name ?? null,
+                outcome: result.outcome ?? null,
+                status: result.status ?? null,
+            }));
+            return {
+                satisfied: selected.length > 0 && failed.length === 0,
+                dataset: a[0],
+                ...(ruleId !== undefined ? { ruleId, } : {}),
+                checked: selected.length,
+                failed,
+                ...(selected.length === 0 ? { reason: "no_results", } : {}),
+            };
+        },
+        usage: "dss data-quality assert-results <dataset> [--rule-id ID] [--project-key KEY]",
+        description: "Assert the latest data quality results: at least one selected rule must exist and every selected result must report OK. Returns { satisfied, checked, failed } with failed rule ids/outcomes only; a failed assertion exits 4 with assertion_failed.",
+        examples: [
+            "dss data-quality assert-results orders",
+            "dss data-quality assert-results orders --rule-id RULE_ID",
+        ],
+    },
     history: {
         handler: (c, a, f) => {
             requireArgs(a, 1, "dss data-quality history <dataset>");

package/dist/src/cli/commands/dataset.d.ts

@@ -1,2 +1,25 @@
 import type { CommandMeta } from "../types.js";
+export interface DatasetSchemaDifference {
+    /** Path from the schema root in dot/bracket notation, e.g. `columns[2].type`. */
+    path: string;
+    kind: "added" | "removed" | "changed";
+    /** SHA-256 of the deterministic JSON rendering of the expected subtree. */
+    expectedHash?: string;
+    /** SHA-256 of the deterministic JSON rendering of the actual subtree. */
+    actualHash?: string;
+}
+export interface DatasetSchemaComparison {
+    equal: boolean;
+    expectedHash: string;
+    actualHash: string;
+    differences: DatasetSchemaDifference[];
+    totalDifferences: number;
+    differencesTruncated: boolean;
+}
+/**
+ * Compare two schema values deterministically — object key order never matters
+ * — and report each structural difference as a concise per-path entry carrying
+ * subtree hashes instead of subtree values.
+ */
+export declare function compareDatasetSchemas(expected: unknown, actual: unknown): DatasetSchemaComparison;
 export declare const datasetCommands: Record<string, CommandMeta>;