dataiku-sdk 1.0.0 → 2.0.0

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/helpers/cleanup.js

@@ -4,7 +4,7 @@ export function projectArg(projectKey) {
 }
 export function cleanupLedgerEntry(resource, action, args, flags, result, projectKey) {
     if (!(action.startsWith("create") || action === "clone" || action === "duplicate"
-        || action === "upload"))
+        || action === "import" || action === "upload"))
         return undefined;
     const record = resultRecord(result);
     if (record.skipped !== undefined)
@@ -190,6 +190,35 @@ export function cleanupLedgerEntry(resource, action, args, flags, result, projec
                 path: args[1],
                 cleanup: { argv: ["folder", "delete-file", args[0], args[1], ...withProject,], },
             };
+        case "project.import": {
+            const usedProjectKey = stringField(record, ["usedProjectKey",]);
+            const recordedIncarnation = stringField(record, ["projectIncarnationHash",]);
+            const boundIncarnation = recordedIncarnation
+                && /^[0-9a-f]{64}$/.test(recordedIncarnation)
+                ? recordedIncarnation
+                : undefined;
+            // Only a verified success may produce a cleanup entry, and it must
+            // bind the concrete landed project incarnation: replaying an
+            // unbound delete could remove a replacement project that reused the
+            // key. Never emit legacy/unbound project entries.
+            if (!usedProjectKey || !boundIncarnation)
+                return undefined;
+            return {
+                ...base,
+                projectKey: usedProjectKey,
+                name: usedProjectKey,
+                cleanup: {
+                    argv: [
+                        "project",
+                        "delete",
+                        usedProjectKey,
+                        "--if-exists",
+                        "--expect-project-incarnation",
+                        boundIncarnation,
+                    ],
+                },
+            };
+        }
         case "app.create-instance":
         case "app.create-successor-instance": {
             const targetKey = stringField(record, ["projectKey", "targetProjectKey",]);

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

@@ -21,7 +21,8 @@ export declare function commandFailureExitCode(result: unknown): number | undefi
  * Stable error code for a command-level failure report. A failed synchronous
  * assertion (exit 4) is a distinct outcome from a failed long-running remote
  * operation (also exit 4), so agents must never see `long_running_failure`
- * for a result that finished synchronously with `unchanged: false`.
+ * for a result that finished synchronously with `unchanged: false` or
+ * `satisfied: false`.
  */
 export declare function commandFailureCode(result: unknown, exitCode: number): StableErrorCode;
 export declare class CommandResultFailure extends Error {
@@ -44,6 +45,7 @@ export declare function planResult(resource: string, action: string, options: {
     payload?: unknown;
     localWrites?: unknown;
     plannedAndDryRun?: boolean;
+    requests?: unknown;
     wait?: unknown;
 }): Record<string, unknown>;
 export declare function encodedProjectEndpoint(client: DataikuClient, projectKey: string | undefined, suffix: string): string;

package/dist/src/cli/output.js

@@ -87,10 +87,10 @@ export function isFailedWaitResult(result) {
         && (typeof record.state === "string" || typeof record.outcome === "string");
 }
 export function isAssertionFailureResult(result) {
-    return result !== null
-        && typeof result === "object"
-        && !Array.isArray(result)
-        && result.unchanged === false;
+    if (result === null || typeof result !== "object" || Array.isArray(result))
+        return false;
+    const record = result;
+    return record.unchanged === false || record.satisfied === false;
 }
 function isNestedAssertionFailureResult(result) {
     if (result === null || typeof result !== "object" || Array.isArray(result))
@@ -121,7 +121,8 @@ export function commandFailureExitCode(result) {
  * Stable error code for a command-level failure report. A failed synchronous
  * assertion (exit 4) is a distinct outcome from a failed long-running remote
  * operation (also exit 4), so agents must never see `long_running_failure`
- * for a result that finished synchronously with `unchanged: false`.
+ * for a result that finished synchronously with `unchanged: false` or
+ * `satisfied: false`.
  */
 export function commandFailureCode(result, exitCode) {
     if (isAssertionFailureResult(result) || isNestedAssertionFailureResult(result)) {
@@ -150,7 +151,10 @@ export function commandFailureMessage(result) {
         return `Command completed with failed long-running result${state ? `: ${state}` : ""}.`;
     }
     if (isAssertionFailureResult(result)) {
-        return "Command completed with failed assertion result.";
+        const record = result;
+        return record.unchanged === false
+            ? "Command completed with failed assertion result."
+            : "Command completed with unsatisfied assertion result.";
     }
     if (isNestedAssertionFailureResult(result)) {
         return "Command completed with nested failed assertion result.";
@@ -188,6 +192,7 @@ export function planResult(resource, action, options) {
         ...(options.endpoint ? { endpoint: options.endpoint, } : {}),
         ...(options.payload !== undefined ? { payload: options.payload, } : {}),
         ...(options.localWrites !== undefined ? { localWrites: options.localWrites, } : {}),
+        ...(options.requests !== undefined ? { requests: options.requests, } : {}),
         ...(options.wait !== undefined ? { wait: options.wait, } : {}),
         idempotency: options.idempotency,
         async: options.asyncKind,

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

@@ -1,5 +1,6 @@
 import type { DataikuClient } from "../client.js";
 export type CommandHandler = (client: DataikuClient, args: string[], flags: Record<string, string | boolean>) => Promise<unknown>;
+export type LocalCommandHandler = (args: string[], flags: Record<string, string | boolean>) => Promise<unknown>;
 export interface CommandPayloadSchema {
     stdin?: boolean;
     dataFlag?: boolean;
@@ -19,6 +20,7 @@ export interface CommandRegistryOverride {
 }
 export interface CommandMeta extends CommandRegistryOverride {
     handler: CommandHandler;
+    localHandler?: LocalCommandHandler;
     usage: string;
     description?: string;
     examples?: string[];

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

@@ -1,14 +1,57 @@
 export declare function findPackageRoot(): string | undefined;
 export declare function packageVersion(packageRoot: string | undefined): string;
 export declare function gitDirectory(packageRoot: string): string;
+export declare function isFullRevision(value: unknown): boolean;
+/**
+ * Full checkout HEAD revision (40-lowercase-hex) — the basis for staleness
+ * comparison. Resolution follows Git's own layouts: a detached revision, then
+ * loose refs in the worktree git dir, then the shared store reached through
+ * `commondir`, then packed-refs in each. Anything that is not a full
+ * lowercase hexadecimal revision is rejected.
+ */
+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";
+export declare function detectLoadSource(modulePath?: string): CliLoadSource;
+export declare function buildMetadataRevision(packageRoot: string | undefined): string | undefined;
+/**
+ * Whether compiled CLI output predates any source input. The build metadata
+ * file is written after `tsc`, so its mtime is the build-completion marker.
+ * Installed packages omit `src/`; without both sides there is no drift claim.
+ */
+export declare function sourceTreeNewerThanBuild(packageRoot: string | undefined): boolean;
+/**
+ * CLI provenance payload. `source` distinguishes a source checkout run from a
+ * published dist run; `runtime` names the executing runtime. `buildRevision`
+ * is only ever claimed by a dist build that carries build metadata — source
+ * execution never claims one. `staleBuild` is true only when the running dist
+ * build revision differs from the checkout or a source input is newer than the
+ * build-completion marker.
+ */
+export interface CliVersionPayload {
+    version: string;
+    gitRevision: string | null;
+    source: CliLoadSource;
+    runtime: CliRuntime;
+    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;
+    checkoutRevision: string | undefined;
+    checkoutFullRevision: string | undefined;
+    loadSource: string | undefined;
+    buildRevision: string | undefined;
+    sourceNewerThanBuild?: boolean;
+    runtime: CliRuntime;
+}): CliVersionPayload;
 export declare const PACKAGE_ROOT: string | undefined;
 export declare const CLI_VERSION: string;
 export declare const CLI_GIT_REVISION: string | undefined;
 export declare const AGENT_CONTRACT_VERSION = 2;
 export declare const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
 export declare const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v2.json";
-export declare function cliVersionResult(): {
-    version: string;
-    gitRevision: string | null;
-};
+export declare function cliVersionResult(): CliVersionPayload;

package/dist/src/cli/version.js

@@ -1,4 +1,4 @@
-import { readFileSync, } from "node:fs";
+import { readdirSync, readFileSync, statSync, } from "node:fs";
 import { dirname, resolve, } from "node:path";
 import { fileURLToPath, } from "node:url";
 export function findPackageRoot() {
@@ -36,22 +36,175 @@ export function gitDirectory(packageRoot) {
     }
     return resolve(packageRoot, ".git");
 }
+/**
+ * A full lowercase hexadecimal revision is the only provenance claim trusted.
+ * Git is never invoked from runtime version reporting; revisions are resolved
+ * directly from the filesystem layouts Git documents.
+ */
+const FULL_REVISION_PATTERN = /^[0-9a-f]{40}$/;
+export function isFullRevision(value) {
+    return typeof value === "string" && FULL_REVISION_PATTERN.test(value);
+}
+function readGitFile(base, relative) {
+    try {
+        return readFileSync(resolve(base, relative), "utf-8").trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function isSafeRefName(ref) {
+    return (ref.length > 0
+        && !ref.startsWith("/")
+        && !ref.endsWith("/")
+        && !ref.includes("\\")
+        && !ref.split("/").includes(".."));
+}
+/** Resolve an entry from packed-refs; peeled `^` lines never match a ref. */
+function packedRefFile(base, ref) {
+    let contents;
+    try {
+        contents = readFileSync(resolve(base, "packed-refs"), "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+    for (const line of contents.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0 || trimmed.startsWith("#") || trimmed.startsWith("^"))
+            continue;
+        const splitAt = trimmed.indexOf(" ");
+        if (splitAt <= 0)
+            continue;
+        const hash = trimmed.slice(0, splitAt);
+        if (isFullRevision(hash) && trimmed.slice(splitAt + 1).trim() === ref)
+            return hash;
+    }
+    return undefined;
+}
+/**
+ * The shared git dir behind a linked worktree or submodule checkout: the
+ * `commondir` file inside the worktree's git dir, resolved relative to that
+ * dir. Normal checkouts (no `commondir` file) share their own git dir.
+ */
+function gitCommonDirectory(gitDir) {
+    try {
+        const commondir = readFileSync(resolve(gitDir, "commondir"), "utf-8").trim();
+        return commondir.length > 0 ? resolve(gitDir, commondir) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Full checkout HEAD revision (40-lowercase-hex) — the basis for staleness
+ * comparison. Resolution follows Git's own layouts: a detached revision, then
+ * loose refs in the worktree git dir, then the shared store reached through
+ * `commondir`, then packed-refs in each. Anything that is not a full
+ * lowercase hexadecimal revision is rejected.
+ */
+export function gitFullRevision(packageRoot) {
+    if (!packageRoot)
+        return undefined;
+    const gitDir = gitDirectory(packageRoot);
+    const head = readGitFile(gitDir, "HEAD");
+    if (!head)
+        return undefined;
+    if (isFullRevision(head))
+        return head;
+    if (!head.startsWith("ref:"))
+        return undefined;
+    const ref = head.slice("ref:".length).trim();
+    if (!isSafeRefName(ref))
+        return undefined;
+    for (const base of [gitDir, gitCommonDirectory(gitDir),]) {
+        if (!base)
+            continue;
+        const loose = readGitFile(base, ref);
+        if (loose && isFullRevision(loose))
+            return loose;
+        const packed = packedRefFile(base, ref);
+        if (packed)
+            return packed;
+    }
+    return undefined;
+}
 export function gitRevision(packageRoot) {
+    const full = gitFullRevision(packageRoot);
+    return full ? full.slice(0, 7) : undefined;
+}
+export function detectLoadSource(modulePath = fileURLToPath(import.meta.url)) {
+    return modulePath.replaceAll("\\", "/").includes("/dist/") ? "dist" : "source";
+}
+export function buildMetadataRevision(packageRoot) {
     if (!packageRoot)
         return undefined;
     try {
-        const gitDir = gitDirectory(packageRoot);
-        const head = readFileSync(resolve(gitDir, "HEAD"), "utf-8").trim();
-        if (!head.startsWith("ref:"))
-            return head.slice(0, 7);
-        const ref = head.slice("ref:".length).trim();
-        const full = readFileSync(resolve(gitDir, ref), "utf-8").trim();
-        return full.slice(0, 7);
+        const metadata = JSON.parse(readFileSync(resolve(packageRoot, "dist", "build-metadata.json"), "utf-8"));
+        return typeof metadata.buildRevision === "string"
+            && isFullRevision(metadata.buildRevision)
+            ? metadata.buildRevision
+            : undefined;
     }
     catch {
         return undefined;
     }
 }
+/**
+ * Whether compiled CLI output predates any source input. The build metadata
+ * file is written after `tsc`, so its mtime is the build-completion marker.
+ * Installed packages omit `src/`; without both sides there is no drift claim.
+ */
+export function sourceTreeNewerThanBuild(packageRoot) {
+    if (!packageRoot)
+        return false;
+    try {
+        const buildMtimeMs = statSync(resolve(packageRoot, "dist", "build-metadata.json")).mtimeMs;
+        const pending = [resolve(packageRoot, "src"),];
+        while (pending.length > 0) {
+            const path = pending.pop();
+            if (!path)
+                break;
+            const stat = statSync(path);
+            if (stat.mtimeMs > buildMtimeMs)
+                return true;
+            if (!stat.isDirectory())
+                continue;
+            for (const entry of readdirSync(path, { withFileTypes: true, })) {
+                if (entry.isDirectory() || entry.isFile()) {
+                    pending.push(resolve(path, entry.name));
+                }
+            }
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/** Bun is the only supported runtime; the field is retained for payload stability. */
+export function detectRuntime() {
+    return "bun";
+}
+export function buildVersionPayload(input) {
+    const isDist = input.loadSource === "dist";
+    // Source execution never claims a build revision, even if the environment
+    // happens to carry one.
+    const buildRevision = isDist && input.buildRevision ? input.buildRevision : null;
+    const staleBuild = isDist
+        && ((buildRevision !== null
+            && input.checkoutFullRevision !== undefined
+            && input.checkoutFullRevision !== buildRevision)
+            || input.sourceNewerThanBuild === true);
+    return {
+        version: input.packageVersion,
+        gitRevision: input.checkoutRevision ?? null,
+        source: isDist ? "dist" : "source",
+        runtime: input.runtime,
+        buildRevision,
+        staleBuild,
+    };
+}
 export const PACKAGE_ROOT = findPackageRoot();
 export const CLI_VERSION = packageVersion(PACKAGE_ROOT);
 export const CLI_GIT_REVISION = gitRevision(PACKAGE_ROOT);
@@ -59,5 +212,19 @@ export const AGENT_CONTRACT_VERSION = 2;
 export const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
 export const AGENT_CONTRACT_SCHEMA_ID = "https://clssck.github.io/dataiku-sdk/schemas/agent-contract-v2.json";
 export function cliVersionResult() {
-    return { version: CLI_VERSION, gitRevision: CLI_GIT_REVISION ?? null, };
+    const loadSource = process.env["DSS_LOAD_SOURCE"] ?? detectLoadSource();
+    const envBuildRevision = process.env["DSS_BUILD_REVISION"];
+    return buildVersionPayload({
+        packageVersion: CLI_VERSION,
+        checkoutRevision: CLI_GIT_REVISION,
+        checkoutFullRevision: gitFullRevision(PACKAGE_ROOT),
+        loadSource,
+        buildRevision: isFullRevision(envBuildRevision)
+            ? envBuildRevision
+            : (loadSource === "dist" ? buildMetadataRevision(PACKAGE_ROOT) : undefined),
+        sourceNewerThanBuild: loadSource === "dist"
+            ? sourceTreeNewerThanBuild(PACKAGE_ROOT)
+            : false,
+        runtime: detectRuntime(),
+    });
 }