dataiku-sdk 1.1.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,10 +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 Node/Bun runtime, 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.
+`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
 
@@ -135,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
@@ -182,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
@@ -189,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.
@@ -200,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
@@ -233,12 +243,24 @@ 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.

package/bin/dss.js

@@ -1,117 +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;
-
-// Published dist carries dist/build-metadata.json with the revision it was
-// built from. Forward 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.
-const distMetadataPath = path.resolve(here, "../dist/build-metadata.json",);
-if (!usesSourceCli) {
-	env.DSS_LOAD_SOURCE = "dist";
-	delete env.DSS_BUILD_REVISION;
-	try {
-		const metadata = JSON.parse(fs.readFileSync(distMetadataPath, "utf-8",),);
-		const revision = metadata.buildRevision;
-		if (typeof revision === "string" && /^[0-9a-f]{40}$/.test(revision,)) {
-			env.DSS_BUILD_REVISION = revision;
-		}
-	} catch {
-		// Dist without build metadata: provenance still reports dist source.
-	}
-}
-
-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

@@ -1 +1 @@
-{"format":1,"buildRevision":"70487e2275a70acce6862f126a89b1bc852ebb11"}
+{"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/project-library.js

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, } from "node:fs";
+import * as fs from "node:fs";
 import { readStdinText, } from "../coerce.js";
 import { encodedProjectEndpoint, planResult, } from "../output.js";
 import { requireArgs, UsageError, } from "../usage.js";
@@ -68,8 +68,8 @@ export const projectLibraryCommands = {
             if (!out)
                 throw new UsageError("--output PATH is required.", "missing_required_flag");
             const bytes = await c.projectLibrary.getFileBytes(a[0], f["project-key"]);
-            writeFileSync(out, bytes);
-            return { path: out, bytes: bytes.length, };
+            const written = await Bun.write(out, bytes, { createPath: false, });
+            return { path: out, bytes: written, };
         },
         usage: "dss project-library get-bytes <path> --output PATH [--project-key KEY]",
         description: "Download a project library file's raw bytes to a local file.",
@@ -126,7 +126,7 @@ export const projectLibraryCommands = {
             const content = typeof f["content"] === "string"
                 ? f["content"]
                 : typeof f["file"] === "string"
-                    ? readFileSync(f["file"], "utf-8")
+                    ? fs.readFileSync(f["file"], "utf-8")
                     : await readStdinText();
             await c.projectLibrary.addOrUpdateFile(a[0], content, pk);
             return { updated: a[0], };

package/dist/src/cli/contract.js

@@ -2315,6 +2315,8 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 identifiers: {
                     appId: id,
                     targetProjectKey,
+                    preflightExecuted: false,
+                    preflightWillRunDuringApply: true,
                     incarnationControl: "client-side-non-atomic-future-target-and-creation-tag-join",
                     incarnationObservationRequests: [
                         {
@@ -2337,7 +2339,13 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                             method: "GET",
                             endpoint: "/public/api/projects/",
                             when: "conditional",
-                            intent: "Fallback list probe issued only when the direct project GET is forbidden (403) to confirm the target is absent; an unconfirmed target rejects creation.",
+                            intent: "Fallback list probe issued only when the direct project GET is forbidden (403). Presence proves a collision; absence cannot prove availability.",
+                        },
+                        {
+                            method: "GET",
+                            endpoint: `/public/api/apps/${encodeURIComponent(id)}/instances/`,
+                            when: "conditional",
+                            intent: "Fallback app-instance list probe issued when the direct project GET is forbidden (403). Presence proves a collision; absence still rejects creation as unverifiable.",
                         },
                     ],
                     note: "Strict preflight: the instance POST runs only after the payload targetProjectKey is confirmed absent. Creation never writes into an existing or unprovable project.",
@@ -2399,6 +2407,8 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                     appId: id,
                     sourceProjectKey,
                     targetProjectKey,
+                    preflightExecuted: false,
+                    preflightWillRunDuringApply: true,
                     ...(targetProjectName !== undefined ? { targetProjectName, } : {}),
                     copyPermissions,
                     incarnationControl: "client-side-non-atomic-future-target-and-creation-tag-join",
@@ -2437,7 +2447,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                             method: "GET",
                             endpoint: "/public/api/projects/",
                             when: "conditional",
-                            intent: "Fallback list probe issued only when the direct project GET is forbidden (403) to confirm the target is absent; an unconfirmed target rejects creation.",
+                            intent: "Fallback list probe issued only when the direct project GET is forbidden (403). Presence proves a collision; absence cannot prove availability and rejects creation.",
                         },
                     ],
                     ...(copyPermissions

package/dist/src/cli/helpers/app-successor.d.ts

@@ -87,12 +87,22 @@ export declare function futureTargetIdentity(result: unknown): {
     projectKey: string;
     field: "targetProjectKey" | "projectKey";
 } | null;
+interface TargetAbsenceContext {
+    appId: string;
+    visibleAppInstanceKeys?: readonly (string | undefined)[];
+}
 /**
  * Creation cleanup is safe only when the target was proven absent before POST.
  * A hidden 403 is not absence: project listing can prove a collision, but it
  * cannot prove that an inaccessible project does not exist.
  */
-export declare function requireAbsentProjectTarget(client: DataikuClient, targetProjectKey: string, targetFlag: "--to" | "targetProjectKey"): Promise<void>;
+export declare function requireAbsentProjectTarget(client: DataikuClient, targetProjectKey: string, targetFlag: "--to" | "targetProjectKey", context: TargetAbsenceContext): Promise<void>;
+/**
+ * Run every read-only gate used by successor creation without changing the
+ * template version or issuing the creation POST. Its manifest hash is suitable
+ * for the subsequent set-manifest-version --expect-hash guard.
+ */
+export declare function preflightSuccessorInstance(client: DataikuClient, request: SuccessorInstanceRequest, usage: string): Promise<Record<string, unknown>>;
 /**
  * Create a new app instance from the current template version alongside an
  * existing instance. Classic app instances have no public upgrade endpoint, so
@@ -100,7 +110,9 @@ export declare function requireAbsentProjectTarget(client: DataikuClient, target
  * and deliberately retired.
  *
  * After the creation POST this function never throws. A post-POST failure
- * returns a failed-wait result carrying the target project key, so the CLI still
- * exits 4 and the cleanup ledger still records an addressable successor.
+ * returns a failed-wait result. Only a DSS future ID or verified project
+ * incarnation can authorize cleanup; an ambiguous POST with neither stays
+ * indeterminate and produces no cleanup entry.
  */
 export declare function createSuccessorInstance(client: DataikuClient, request: SuccessorInstanceRequest, usage: string): Promise<Record<string, unknown>>;
+export {};

package/dist/src/cli/helpers/app-successor.js

@@ -150,6 +150,7 @@ export async function verifyAppInstance(client, appId, projectKey, expectVersion
 }
 const SUCCESSOR_REMEDIATION = "The successor project may exist: replay the recorded cleanup entry, which future-gates deletion when DSS supplied a future ID. Without a cleanup entry, inspect the creation future and wait for it to become terminal before deleting the requested successor project. The predecessor project was not modified.";
 const CREATE_REJECTED_REMEDIATION = "DSS refused the creation request, so no successor project was created: fix the reported problem and retry. The predecessor project was not modified.";
+const SUCCESSOR_UNBOUND_REMEDIATION = "DSS may have accepted the successor request, but no future ID or project incarnation is available to authorize cleanup. Inspect the app's instances and DSS task history; do not delete the requested key until creation is known terminal and its identity is verified. The predecessor project was not modified.";
 /**
  * True only when DSS definitively refused a write: a non-retryable 4xx with a
  * classified client-side taxonomy. Transport failures (status 0), 5xx, retryable
@@ -186,7 +187,19 @@ export function futureTargetIdentity(result) {
  * A hidden 403 is not absence: project listing can prove a collision, but it
  * cannot prove that an inaccessible project does not exist.
  */
-export async function requireAbsentProjectTarget(client, targetProjectKey, targetFlag) {
+export async function requireAbsentProjectTarget(client, targetProjectKey, targetFlag, context) {
+    if (context.visibleAppInstanceKeys?.includes(targetProjectKey) === true) {
+        throw new UsageError(`Target project ${targetProjectKey} already exists as an app instance.`, "validation_failed", `Choose an unused ${targetFlag}: app instance creation never writes into an existing project.`, {
+            targetProjectKey,
+            targetFlag,
+            directTargetProbe: "not-executed",
+            targetVisibleInProjectList: null,
+            targetVisibleInAppInstances: true,
+            appInstancesProbe: 200,
+            preflightExecuted: true,
+            creationPostAttempted: false,
+        });
+    }
     try {
         const existing = await readIfExists(() => client.projects.get(targetProjectKey));
         if (existing === undefined)
@@ -195,10 +208,61 @@ export async function requireAbsentProjectTarget(client, targetProjectKey, targe
     catch (error) {
         if (!(error instanceof DataikuError) || error.status !== 403)
             throw error;
-        const accessible = await client.projects.list();
-        if (!accessible.some((project) => project.projectKey === targetProjectKey)) {
-            throw new UsageError(`Could not confirm target project ${targetProjectKey} is absent.`, "validation_failed", "Grant project-list/details visibility or choose a target key whose absence DSS can confirm; creation never risks cleanup against an unproven target.", { targetProjectKey, targetFlag, targetProbe: "forbidden-and-not-listable", });
+        let projectListProbe = 200;
+        let targetVisibleInProjectList;
+        try {
+            const accessible = await client.projects.list();
+            targetVisibleInProjectList = accessible.some((project) => project.projectKey === targetProjectKey);
+        }
+        catch (projectListError) {
+            if (!(projectListError instanceof DataikuError) || projectListError.status !== 403) {
+                throw projectListError;
+            }
+            projectListProbe = 403;
+            targetVisibleInProjectList = null;
         }
+        let appInstancesProbe = 200;
+        let visibleAppInstanceKeys = context.visibleAppInstanceKeys;
+        if (visibleAppInstanceKeys === undefined) {
+            try {
+                visibleAppInstanceKeys = (await client.applications.listInstances(context.appId))
+                    .map((instance) => instance.projectKey);
+            }
+            catch (appInstancesError) {
+                if (!(appInstancesError instanceof DataikuError) || appInstancesError.status !== 403) {
+                    throw appInstancesError;
+                }
+                appInstancesProbe = 403;
+                visibleAppInstanceKeys = [];
+            }
+        }
+        const targetVisibleInAppInstances = appInstancesProbe === 200
+            ? visibleAppInstanceKeys?.includes(targetProjectKey) ?? false
+            : null;
+        const probeDetails = {
+            targetProjectKey,
+            targetFlag,
+            directTargetProbe: 403,
+            projectListProbe,
+            targetVisibleInProjectList,
+            targetVisibleInAppInstances,
+            appInstancesProbe,
+            preflightExecuted: true,
+            creationPostAttempted: false,
+        };
+        if (targetVisibleInProjectList !== true && targetVisibleInAppInstances !== true) {
+            throw new UsageError(`Could not confirm target project ${targetProjectKey} is absent.`, "target_absence_unverifiable", "DSS exposes no permission-independent project-key availability endpoint, and app-instance creation has no published atomic duplicate-key guarantee. Retry with an identity that has global project visibility; creation was not attempted.", {
+                ...probeDetails,
+                targetProbe: "forbidden-and-not-listable",
+                deploymentMasksUnknownProjects: "possible-but-unproven",
+                supportedRecoveryModes: ["grant-global-project-visibility",],
+                unavailableRecoveryModes: [
+                    "use-supported-key-availability-endpoint",
+                    "server-atomic-create",
+                ],
+            });
+        }
+        throw new UsageError(`Target project ${targetProjectKey} already exists.`, "validation_failed", `Choose an unused ${targetFlag}: app instance creation never writes into an existing project.`, probeDetails);
     }
     throw new UsageError(`Target project ${targetProjectKey} already exists.`, "validation_failed", `Choose an unused ${targetFlag}: app instance creation never writes into an existing project.`, { targetProjectKey, targetFlag, });
 }
@@ -226,12 +290,26 @@ async function preflightSuccessor(client, request, usage) {
     if (source.projectAppType !== "APP_INSTANCE") {
         throw new UsageError(`Project ${from} is a ${source.projectAppType ?? "non-app"} project, not a classic Dataiku App instance.`, "validation_failed", "--from must name an APP_INSTANCE project; app templates are versioned with `dss app set-manifest-version`.", { sourceProjectKey: from, projectAppType: source.projectAppType ?? null, });
     }
-    await requireAbsentProjectTarget(client, to, "--to");
+    await requireAbsentProjectTarget(client, to, "--to", {
+        appId,
+        visibleAppInstanceKeys: instances.map((instance) => instance.projectKey),
+    });
     const templateManifest = await client.applications.getAppManifest(appId);
     const templateVersion = rawVersion(templateManifest);
     if (templateVersion === null) {
         throw new UsageError(`App template ${appId} has no manifest version, so a successor instance cannot be verified against it.`, "validation_failed", "Set the template version first with `dss app set-manifest-version --manifest-version V --project-key <templateProjectKey>`.", { appId, });
     }
+    const templateReferenceValidation = await client.applications.validateAppManifest(templateManifest, appId);
+    if (!templateReferenceValidation.valid) {
+        throw new UsageError(`App template ${appId} failed manifest reference validation.`, "validation_failed", "Fix the template manifest references before changing its version or creating a successor.", {
+            appId,
+            manifestHash: templateReferenceValidation.manifestHash,
+            checks: templateReferenceValidation.checks,
+            errors: templateReferenceValidation.errors,
+            preflightExecuted: true,
+            creationPostAttempted: false,
+        });
+    }
     const sourcePermissions = request.copyPermissions
         ? await client.projects.getPermissions(from)
         : undefined;
@@ -243,6 +321,7 @@ async function preflightSuccessor(client, request, usage) {
         targetExists: false,
         templateManifestHash: stableHash(templateManifest),
         templateVersion,
+        templateReferenceValidation,
         ...(sourcePermissions
             ? {
                 sourcePermissions,
@@ -251,6 +330,52 @@ async function preflightSuccessor(client, request, usage) {
             : {}),
     };
 }
+/**
+ * Run every read-only gate used by successor creation without changing the
+ * template version or issuing the creation POST. Its manifest hash is suitable
+ * for the subsequent set-manifest-version --expect-hash guard.
+ */
+export async function preflightSuccessorInstance(client, request, usage) {
+    const preflight = await preflightSuccessor(client, request, usage);
+    return {
+        action: "successor-preflight",
+        preflight: "passed",
+        preflightExecuted: true,
+        creationPostAttempted: false,
+        versionMutationAttempted: false,
+        appId: request.appId,
+        source: {
+            projectKey: request.from,
+            projectAppType: preflight.sourceProjectAppType,
+            version: preflight.sourceVersion,
+            manifestHash: preflight.sourceManifestHash,
+            ...(preflight.sourcePermissionsHash
+                ? { permissionsHash: preflight.sourcePermissionsHash, }
+                : {}),
+        },
+        target: {
+            projectKey: request.to,
+            name: preflight.targetProjectName,
+            exists: false,
+        },
+        targetPreflight: "confirmed-absent",
+        template: {
+            projectKey: request.appId,
+            version: preflight.templateVersion,
+            manifestHash: preflight.templateManifestHash,
+            referenceValidation: {
+                valid: preflight.templateReferenceValidation.valid,
+                checks: preflight.templateReferenceValidation.checks,
+                errors: preflight.templateReferenceValidation.errors,
+            },
+        },
+        copyPermissions: request.copyPermissions,
+        next: {
+            setVersion: `dss app set-manifest-version --manifest-version <VERSION> --expect-hash ${preflight.templateManifestHash} --project-key ${request.appId}`,
+            createSuccessor: `dss app create-successor-instance ${request.appId} --from ${request.from} --to ${request.to}${request.name !== undefined ? ` --name ${JSON.stringify(request.name)}` : ""}${request.copyPermissions ? " --copy-permissions" : ""}`,
+        },
+    };
+}
 /**
  * Create a new app instance from the current template version alongside an
  * existing instance. Classic app instances have no public upgrade endpoint, so
@@ -258,8 +383,9 @@ async function preflightSuccessor(client, request, usage) {
  * and deliberately retired.
  *
  * After the creation POST this function never throws. A post-POST failure
- * returns a failed-wait result carrying the target project key, so the CLI still
- * exits 4 and the cleanup ledger still records an addressable successor.
+ * returns a failed-wait result. Only a DSS future ID or verified project
+ * incarnation can authorize cleanup; an ambiguous POST with neither stays
+ * indeterminate and produces no cleanup entry.
  */
 export async function createSuccessorInstance(client, request, usage) {
     const { appId, from, to, } = request;
@@ -312,12 +438,17 @@ export async function createSuccessorInstance(client, request, usage) {
             projectKey: to,
             target: { projectKey: to, name: preflight.targetProjectName, },
             success: false,
-            state: "CREATE_FAILED",
+            state: rejected ? "CREATE_FAILED" : "INDETERMINATE",
             elapsedMs: 0,
             pollCount: 0,
             stage: "create",
-            cleanupEligible: !rejected,
-            remediation: rejected ? CREATE_REJECTED_REMEDIATION : SUCCESSOR_REMEDIATION,
+            outcome: rejected ? "rejected" : "indeterminate",
+            creationPostAttempted: true,
+            cleanupEligible: false,
+            recoveryCommands: rejected
+                ? []
+                : [`dss app instances ${appId}`,],
+            remediation: rejected ? CREATE_REJECTED_REMEDIATION : SUCCESSOR_UNBOUND_REMEDIATION,
             ...safeErrorSummary(error),
         };
     }
@@ -342,11 +473,13 @@ export async function createSuccessorInstance(client, request, usage) {
             stage: "create",
             ...(instance ? { instance, } : {}),
             ...(jobId !== undefined ? { futureId: jobId, jobId, } : {}),
-            cleanupEligible: true,
+            cleanupEligible: jobId !== undefined,
             error: "DSS named a different target project in the creation response.",
             expected: { projectKey: to, },
             actual: { projectKey: echoedTarget, },
-            remediation: SUCCESSOR_REMEDIATION,
+            remediation: jobId !== undefined
+                ? SUCCESSOR_REMEDIATION
+                : SUCCESSOR_UNBOUND_REMEDIATION,
         };
     }
     const base = {
@@ -381,13 +514,16 @@ export async function createSuccessorInstance(client, request, usage) {
                         : "scalar",
             }),
             success: false,
-            state: "UNTRACKABLE",
+            state: "INDETERMINATE",
             elapsedMs: 0,
             pollCount: 0,
             stage: "future-wait",
-            cleanupEligible: true,
+            outcome: "indeterminate",
+            creationPostAttempted: true,
+            cleanupEligible: false,
             error: "DSS returned no instance-creation future ID, so the successor instance cannot be verified.",
-            remediation: SUCCESSOR_REMEDIATION,
+            remediation: SUCCESSOR_UNBOUND_REMEDIATION,
+            recoveryCommands: [`dss app instances ${appId}`,],
         };
     }
     else {
@@ -408,6 +544,7 @@ export async function createSuccessorInstance(client, request, usage) {
                 pollCount: 0,
                 stage: "future-wait",
                 cleanupEligible: true,
+                recoveryCommands: [`dss future wait ${jobId}`, `dss app instances ${appId}`,],
                 remediation: SUCCESSOR_REMEDIATION,
                 ...safeErrorSummary(error),
             };
@@ -451,6 +588,9 @@ export async function createSuccessorInstance(client, request, usage) {
     if (!waited.success) {
         return failure(waited.state, "future-wait", {
             error: "The instance-creation future did not complete successfully.",
+            recoveryCommands: jobId !== undefined
+                ? [`dss future wait ${jobId}`, `dss app instances ${appId}`,]
+                : [`dss app instances ${appId}`,],
         });
     }
     try {

package/dist/src/cli/version.d.ts

@@ -12,7 +12,7 @@ export declare function isFullRevision(value: unknown): boolean;
 export declare function gitFullRevision(packageRoot: string | undefined): string | undefined;
 export declare function gitRevision(packageRoot: string | undefined): string | undefined;
 export type CliLoadSource = "source" | "dist";
-export type CliRuntime = "bun" | "node";
+export type CliRuntime = "bun";
 export declare function detectLoadSource(modulePath?: string): CliLoadSource;
 export declare function buildMetadataRevision(packageRoot: string | undefined): string | undefined;
 /**
@@ -37,6 +37,7 @@ export interface CliVersionPayload {
     buildRevision: string | null;
     staleBuild: boolean;
 }
+/** Bun is the only supported runtime; the field is retained for payload stability. */
 export declare function detectRuntime(): CliRuntime;
 export declare function buildVersionPayload(input: {
     packageVersion: string;

package/dist/src/cli/version.js

@@ -182,8 +182,9 @@ export function sourceTreeNewerThanBuild(packageRoot) {
         return false;
     }
 }
+/** Bun is the only supported runtime; the field is retained for payload stability. */
 export function detectRuntime() {
-    return process.versions.bun ? "bun" : "node";
+    return "bun";
 }
 export function buildVersionPayload(input) {
     const isDist = input.loadSource === "dist";

package/dist/src/cli.js

@@ -1241,8 +1241,11 @@ function buildErrorReport(err) {
             ok: false,
             error: err.message,
             code: err.code,
-            category: "usage",
+            category: err.code === "target_absence_unverifiable"
+                ? "permission_or_environment"
+                : "usage",
             exitCode,
+            ...(err.code === "target_absence_unverifiable" ? { retryable: false, } : {}),
             ...(err.hint ? { hint: err.hint, } : {}),
             ...(err.details ? { details: err.details, } : {}),
             ...context,

package/dist/src/client.js

@@ -1,4 +1,4 @@
-import { openAsBlob, readFileSync, } from "node:fs";
+import { readFileSync, } from "node:fs";
 import { basename, } from "node:path";
 import { getCACertificates, } from "node:tls";
 import { Value, } from "@sinclair/typebox/value";
@@ -479,7 +479,7 @@ export class DataikuClient {
         });
     }
     async uploadResponse(path, filePath, fileName) {
-        const fileBlob = await openAsBlob(filePath);
+        const fileBlob = Bun.file(filePath);
         const formData = new FormData();
         formData.append("file", fileBlob, fileName ?? basename(filePath));
         return this.fetchWithRetry(`${this.baseUrl}${path}`, {

package/dist/src/errors.d.ts

@@ -1,5 +1,5 @@
 export type DataikuErrorCategory = "not_found" | "forbidden" | "validation" | "transient" | "unknown";
-export type StableErrorCode = "usage_error" | "unknown_flag" | "missing_required_arg" | "missing_required_flag" | "invalid_flag_value" | "conflicting_input_sources" | "invalid_enum" | "not_found" | "permission_denied" | "validation_failed" | "transient" | "long_running_failure" | "command_result_failure" | "assertion_failed" | "ambiguous_outcome" | "internal_error";
+export type StableErrorCode = "usage_error" | "unknown_flag" | "missing_required_arg" | "missing_required_flag" | "invalid_flag_value" | "conflicting_input_sources" | "invalid_enum" | "not_found" | "permission_denied" | "target_absence_unverifiable" | "validation_failed" | "transient" | "long_running_failure" | "command_result_failure" | "assertion_failed" | "ambiguous_outcome" | "internal_error";
 export declare function dataikuErrorCode(category: DataikuErrorCategory): StableErrorCode;
 export interface DataikuErrorTaxonomy {
     category: DataikuErrorCategory;

package/dist/src/resources/folders.js

@@ -1,7 +1,4 @@
-import { createWriteStream, } from "node:fs";
-import { resolve, } from "node:path";
-import { Readable, } from "node:stream";
-import { pipeline, } from "node:stream/promises";
+import * as nodePath from "node:path";
 import { FolderDetailsSchema, FolderItemArraySchema, FolderSummaryArraySchema, } from "../schemas.js";
 import { deepMerge, } from "../utils/deep-merge.js";
 import { sanitizeFileName, } from "../utils/sanitize.js";
@@ -72,10 +69,11 @@ export class FoldersResource extends BaseResource {
         const normalizedPath = normalizeRemotePath(path);
         const pEnc = encodeURIComponent(normalizedPath);
         const res = await this.client.stream(`/public/api/projects/${this.enc(opts?.projectKey)}/managedfolders/${fEnc}/contents/${pEnc}`);
-        const dest = opts?.localPath ?? resolve(process.cwd(), inferDownloadFileName(normalizedPath));
-        const nodeStream = Readable.fromWeb(res.body);
-        const fileOut = createWriteStream(dest);
-        await pipeline(nodeStream, fileOut);
+        if (!res.body)
+            throw new Error("folders.download response did not include a body");
+        const dest = opts?.localPath
+            ?? nodePath.resolve(process.cwd(), inferDownloadFileName(normalizedPath));
+        await Bun.write(dest, new Response(res.body), { createPath: false, });
         return dest;
     }
     upload(folderId, path, localPath, projectKey) {

package/dist/src/resources/projects.js

@@ -1,5 +1,3 @@
-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";
@@ -159,14 +157,7 @@ export class ProjectsResource extends BaseResource {
         const res = await this.postStream(`/public/api/projects/${encodeURIComponent(projectKey)}/export`, options ?? {});
         if (!res.body)
             throw new Error("projects.exportArchive response did not include a body");
-        const file = createWriteStream(filePath);
-        try {
-            await res.body.pipeTo(Writable.toWeb(file));
-        }
-        catch (error) {
-            file.destroy();
-            throw error;
-        }
+        await Bun.write(filePath, new Response(res.body), { createPath: false, });
     }
     /** Upload a project archive and return its temporary import handle. */
     async prepareProjectImport(filePath) {

package/dist/src/skill.js

@@ -1,4 +1,3 @@
-import { execFileSync, } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -61,24 +60,11 @@ export const AGENTS = {
         content: skillContent,
     },
 };
-// ---------------------------------------------------------------------------
-// Agent detection
-// ---------------------------------------------------------------------------
-function binaryExists(name) {
-    const cmd = process.platform === "win32" ? "where" : "which";
-    try {
-        execFileSync(cmd, [name,], { stdio: "pipe", });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 export function detectAgents() {
     const home = os.homedir();
     const found = [];
     for (const [id, def,] of Object.entries(AGENTS)) {
-        const hasBinary = binaryExists(def.binary);
+        const hasBinary = Bun.which(def.binary) !== null;
         const hasConfigDir = fs.existsSync(path.join(home, def.configDir));
         if (hasBinary && (!def.configDirRequired || hasConfigDir)) {
             found.push({ id, def, via: "binary", });
@@ -90,9 +76,6 @@ export function detectAgents() {
     return found;
 }
 // ---------------------------------------------------------------------------
-// Skill installation
-// ---------------------------------------------------------------------------
-// ---------------------------------------------------------------------------
 // Workspace root detection
 // ---------------------------------------------------------------------------
 const WORKSPACE_MARKERS = [".git",];

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

@@ -17,7 +17,7 @@ export interface ProjectArchiveInspection {
  * 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
+ * bounded memory (manual `Bun.hash.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

package/dist/src/utils/project-archive.js

@@ -1,6 +1,5 @@
 import StreamZip from "node-stream-zip";
 import { stat, } from "node:fs/promises";
-import { crc32, } from "node:zlib";
 import { ClientValidationError, } from "../errors.js";
 const MANIFEST_MEMBER = "export-manifest.json";
 const DATASETS_ROOT = "project_config/datasets";
@@ -106,7 +105,7 @@ function isUnsafeMemberPath(name) {
 /**
  * Stream one member through a bounded-memory CRC-32/size check. The library's
  * own verification is bypassed for data-descriptor records (bit 3 set), so the
- * manual `node:zlib.crc32` computation covers every record uniformly.
+ * manual `Bun.hash.crc32` computation covers every record uniformly.
  *
  * When `accumulate` is set, buffered content never exceeds `maxBytes`: the
  * buffer is dropped as soon as the cap is reached while the member is still
@@ -130,7 +129,7 @@ function streamMember(zip, entry, accumulate, maxBytes = Number.POSITIVE_INFINIT
         stream.on("data", (chunk) => {
             const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
             bytes += buffer.length;
-            crc = crc32(buffer, crc) >>> 0;
+            crc = Bun.hash.crc32(buffer, crc) >>> 0;
             if (!content || truncated)
                 return;
             if (bytes > maxBytes) {
@@ -307,7 +306,7 @@ function residueIssue(member, counts) {
  * 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
+ * bounded memory (manual `Bun.hash.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

package/dist/src/utils/stable-hash.js

@@ -1,6 +1,5 @@
-import { createHash, } from "node:crypto";
 export function sha256Hex(value) {
-    return createHash("sha256").update(value).digest("hex");
+    return new Bun.CryptoHasher("sha256").update(value).digest("hex");
 }
 /** Locale-independent UTF-16 code-unit order for deterministic machine output. */
 export function compareStrings(a, b) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dataiku-sdk",
-	"version": "1.1.0",
+	"version": "2.0.0",
 	"description": "Dataiku DSS SDK and CLI for programmatic access to DSS REST APIs",
 	"type": "module",
 	"workspaces": [
@@ -19,15 +19,14 @@
 		"packages/types/dist/"
 	],
 	"engines": {
-		"node": ">=22.15.0",
-		"bun": ">=1.3.14"
+		"bun": ">=1.4.0"
 	},
 	"scripts": {
-		"build": "tsc && node scripts/generate-build-metadata.mjs && tsc -p packages/types/tsconfig.json",
-		"prepack": "node scripts/sync-plugin-version.mjs --check && tsc && node scripts/generate-build-metadata.mjs && tsc -p packages/types/tsconfig.json",
-		"prepublishOnly": "node scripts/sync-plugin-version.mjs --check && tsc && node scripts/generate-build-metadata.mjs && tsc -p packages/types/tsconfig.json",
-		"check": "tsc --noEmit && node scripts/sync-plugin-version.mjs --check",
-		"version": "node scripts/sync-plugin-version.mjs && git add plugin.json",
+		"build": "tsc && bun scripts/generate-build-metadata.mjs && tsc -p packages/types/tsconfig.json",
+		"prepack": "bun scripts/sync-plugin-version.mjs --check && tsc && bun scripts/generate-build-metadata.mjs && tsc -p packages/types/tsconfig.json",
+		"prepublishOnly": "bun scripts/sync-plugin-version.mjs --check && tsc && bun scripts/generate-build-metadata.mjs && tsc -p packages/types/tsconfig.json",
+		"check": "tsc --noEmit && bun scripts/sync-plugin-version.mjs --check",
+		"version": "bun scripts/sync-plugin-version.mjs && git add plugin.json",
 		"lint": "oxlint src/",
 		"lint:fix": "oxlint --fix src/",
 		"format": "dprint fmt",
@@ -41,7 +40,7 @@
 		"test:integration:rigorous:mutating": "cross-env RUN_DATAIKU_INTEGRATION=1 RUN_DATAIKU_INTEGRATION_MUTATING=1 bun test tests/integration-rigorous.test.ts"
 	},
 	"devDependencies": {
-		"@types/bun": "^1.3.14",
+		"@types/bun": "^1.4.0",
 		"cross-env": "^10.1.0",
 		"dprint": "^0.55.2",
 		"js-tiktoken": "1.0.21",

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "dataiku-sdk",
-	"version": "1.1.0",
+	"version": "2.0.0",
 	"description": "Dataiku DSS SDK and agent-oriented CLI for programmatic access to DSS REST APIs.",
 	"homepage": "https://github.com/clssck/dataiku-sdk",
 	"repository": "https://github.com/clssck/dataiku-sdk",

package/skills/dataiku-dss/SKILL.md

@@ -7,14 +7,14 @@ description: >-
   dss commands run --fields RESOURCE.ACTION.
 license: MIT
 compatibility: >-
-  Requires the dss CLI, network access to a Dataiku DSS instance, and configured
-  DATAIKU_URL and DATAIKU_API_KEY credentials. Source-checkout fallback requires Bun.
+  Requires the dss CLI, network access to a Dataiku DSS instance, configured
+  DATAIKU_URL and DATAIKU_API_KEY credentials, and Bun >= 1.4.0.
 ---
 
 # Dataiku DSS agent CLI
 
 Use `dss` when an agent needs to inspect or change Dataiku DSS resources: projects, datasets, recipes, jobs, scenarios, folders, notebooks, SQL, variables, code envs, and connections.
-If the installed `dss` binary is unavailable but the repository checkout is the current workspace, prefer `bun --no-env-file src/cli.ts ...` or `bun --no-env-file ./bin/dss.js ...`. Node users can invoke the same cross-runtime launcher as `node ./bin/dss.js ...`; when `dist/` has not been built, it delegates to Bun. From another working directory, pass the checkout's absolute `bin/dss.js` path to Bun or Node.
+If the installed `dss` binary is unavailable but the repository checkout is the current workspace, prefer `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.
 
 ## Contract
@@ -126,7 +126,8 @@ recipient-sharing, or UI-click operations that the public DSS API does not expos
 dss app validate-manifest --project-key APP_TEMPLATE
 dss app compare-manifest APP_ID --project-key RELEASE_INSTANCE
 dss app manifest-version --project-key APP_TEMPLATE
-dss app set-manifest-version --manifest-version 1.4.0 --project-key APP_TEMPLATE
+dss app successor-preflight APP_ID --from RELEASE_INSTANCE --to RELEASE_INSTANCE_V2 --copy-permissions
+dss app set-manifest-version --manifest-version 1.4.0 --expect-hash PREFLIGHT_TEMPLATE_MANIFEST_HASH --project-key APP_TEMPLATE
 # targetProjectKey in instance.json must be confirmed absent
 dss app create-instance APP_ID --data-file instance.json --wait --record-cleanup cleanup.jsonl
 dss app create-successor-instance APP_ID --from RELEASE_INSTANCE --to RELEASE_INSTANCE_V2 --copy-permissions --record-cleanup cleanup.jsonl
@@ -137,39 +138,30 @@ dss app permissions-diff --project-key RELEASE_INSTANCE --file permissions.json
 dss app permissions-restore --project-key RELEASE_INSTANCE --file permissions.json --dry-run
 ```
 
-An invalid manifest exits non-zero with the validation result in the structured error details.
-Review the cleanup preview before `dss cleanup --file cleanup.jsonl --apply`. Every new entry is
-bound to the canonical DSS URL. App cleanup records a `creationTag` hash observed after the DSS
-future identifies its target key; unconfirmed creation stops unresolved. The future target and
-later `creationTag` are independent, non-atomic observations because 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 unable to
-eliminate replacement in the remaining check-to-DELETE gap. Apply validates the full ledger before
-any request and rejects legacy, mixed-server, mismatched-server, or unbound app cleanup entries.
-The successor's cleanup ledger entry targets only the new project key;
-the predecessor is never targeted. Some DSS deployments return 403 for an unknown target project:
-instance creation requires confirmed target absence before POST, so an inaccessible target absent
-from the visible project list is still rejected as unconfirmed rather than risking cleanup against
-a pre-existing project. A definitive create rejection never produces a cleanup entry.
+Run `successor-preflight` before changing the template version. It validates the template,
+predecessor, target, and optional ACL snapshot, performs no mutation, and returns the template
+manifest hash for the next `set-manifest-version --expect-hash` guard.
+
+A masked `403` absent from both visible lists is rejected as
+`target_absence_unverifiable` / `permission_or_environment`; lists prove collisions, not absence.
+DSS exposes no permission-independent public key-availability endpoint or guaranteed
+non-overwriting duplicate-key rejection, so no force or server-atomic bypass is supported. Use
+global project visibility. A definitive rejection writes no cleanup entry. An ambiguous POST
+without a returned future ID or verified incarnation is `INDETERMINATE` and also produces no cleanup
+entry. Future-addressable cleanup waits for target identity and `creationTag`; the predecessor is
+never targeted. Ledgers bind the canonical DSS URL, project key, and concrete project incarnation,
+and reject legacy, mixed-server, mismatched-server, or unbound app cleanup entries. Static plans
+expose `preflightExecuted:false` and `preflightWillRunDuringApply:true`.
 
 `app set-manifest-version` reports
-`concurrencyControl:"client-side-non-atomic-stale-read-check"`. `--expect-hash SHA256` refuses the
-write when the manifest already changed, but the PUT itself stays unconditional: this command can
-overwrite a writer that commits inside the read-then-write window, and the post-write read cannot
-detect that lost update when this command's payload wins. Never treat the hash as a serializing lock.
-An ambiguous manifest PUT or verification read exits non-zero with `persisted:null`,
-`after:null`, and `outcome:"indeterminate"`; it never claims success or rejection.
-
-The API key authenticates public REST only. `app verify-instance` reports `apiReady:true`,
-`status:"API_VERIFIED_UI_PENDING"`, and `uiPublicationVerified:false`. Its `visual-ui` gate
-requires a pre-authenticated SSO browser session or dedicated UI test identity and evidence from
-exercising the affected tiles, forms, and actions; the CLI never marks that external gate complete.
-Permission snapshots have an integrity hash bound to the canonical DSS URL, project key, and
-observed concrete project incarnation from `creationTag`; diff and restore reject detected server,
-key, or incarnation mismatches. DSS exposes no conditional permission PUT, so these client-side checks
-narrow and detect key-reuse races but cannot serialize the final check with the write. Snapshots
-contain access-control identities; keep them mode `0600` and commit them only when repository
-policy permits.
+`concurrencyControl:"client-side-non-atomic-stale-read-check"`. `--expect-hash` is a stale-read
+guard; the PUT is unconditional. Never treat the hash as a serializing lock. Ambiguous writes report
+`outcome:"indeterminate"`.
+
+The API key authenticates public REST only. `app verify-instance` reports
+`status:"API_VERIFIED_UI_PENDING"`; its external SSO gate requires exercising the affected tiles,
+forms, and actions. Permission snapshots bind identity and permissions to the server/project
+incarnation and reject mismatches.
 
 ## Project Git