dataiku-sdk 3.0.0 → 3.1.0

package/dist/src/cli/contract.js

@@ -4,19 +4,31 @@ import { validateCredentials, } from "../auth.js";
 import { getCredentialsPath, saveCredentials, } from "../config.js";
 import { DataikuError, } from "../errors.js";
 import { APP_MANIFEST_CONCURRENCY_CONTROL, } from "../resources/applications.js";
-import { jobBuildTargetTypeFromFlags, json, jsonInput, num, parseBooleanOption, parseJsonObject, recipeInputDatasetsFromFlags, requiredJsonInput, rewritePairsFromFlags, schemaColumnsInput, stringField, textInput, } from "./coerce.js";
+import { encodeGitReferencePath, validateGitReferencePath, } from "../resources/project-git.js";
+import { encodeLibraryPath, PROJECT_LIBRARY_CONCURRENCY_CONTROL, validateLibraryDestinationPath, validateLibraryName, validateLibraryPath, } from "../resources/project-library.js";
+import { CodeEnvDetailsSchema, CodeEnvLogSummaryArraySchema, CodeEnvSummaryArraySchema, CodeEnvUsageArraySchema, CodeEnvVersionForProjectSchema, DatasetDetailsSchema, DatasetSchemaSchema, DatasetSummaryArraySchema, FlowZoneArraySchema, FlowZoneSchema, JobSummaryArraySchema, JobWaitResultSchema, JupyterNotebookContentSchema, JupyterNotebookSummaryArraySchema, NotebookSessionArraySchema, ProjectDetailsSchema, ProjectMetadataSchema, ProjectSummaryArraySchema, RecipeSummaryArraySchema, ScenarioDetailsSchema, ScenarioStatusSchema, ScenarioSummaryArraySchema, SqlNotebookContentSchema, SqlNotebookHistorySchema, SqlNotebookSummaryArraySchema, SqlQueryResponseSchema, } from "../schemas.js";
+import { jobBuildTargetTypeFromFlags, json, jsonInput, num, parseBooleanOption, parseJsonObject, recipeInputDatasetsFromFlags, requiredJsonInput, rewritePairsFromFlags, schemaColumnsInput, sha256Hex, stableHash, stringField, textInput, } from "./coerce.js";
+import { parseCodeRunIntegerFlag, resolveCodeInputWithSource, } from "./commands/code.js";
 import { commands, } from "./commands/index.js";
+import { projectLibraryPutPayload, } from "./commands/project-library.js";
+import { resolveSqlQueryInvocation, } from "./commands/sql.js";
 import { dataikuEnvironmentEnabled, } from "./env.js";
 import { BOOLEAN_FLAGS, FLAG_ALIASES, KNOWN_LONG_FLAGS, SHORT_FLAGS, } from "./flags.js";
 import { flowZoneColor, flowZoneMoveItems, flowZoneName, } from "./helpers/flow-zone.js";
 import { recipeBackupPath, recipeRunShouldWait, } from "./helpers/recipe.js";
 import { encodedProjectEndpointForPlan, planResult, } from "./output.js";
-import { resolveTlsSettings, } from "./runtime.js";
+import { resolveLoginCredentials, } from "./runtime.js";
 import { requireArgs, UsageError, } from "./usage.js";
 import { AGENT_CONTRACT_SCHEMA_ID, AGENT_CONTRACT_VERSION, cliVersionResult, JSON_SCHEMA_DRAFT, } from "./version.js";
 function codeEnvWait(flags) {
     return flags["no-wait"] !== true;
 }
+function codeEnvLang(value, usage) {
+    if (value !== "PYTHON" && value !== "R") {
+        throw new UsageError(`Invalid code environment language ${JSON.stringify(value)}. Usage: ${usage}`);
+    }
+    return value;
+}
 function codeEnvParams(flags) {
     const params = json(flags["params"]) ?? jsonInput(flags) ?? {};
     if (typeof flags["python-interpreter"] === "string") {
@@ -46,23 +58,7 @@ function codeEnvPackageList(flags) {
 export const AUTH_ACTIONS = {
     login: {
         handler: async (flags) => {
-            const tlsSettings = resolveTlsSettings(flags);
-            const useEnv = dataikuEnvironmentEnabled();
-            const url = typeof flags["url"] === "string"
-                ? flags["url"]
-                : useEnv
-                    ? process.env.DATAIKU_URL ?? ""
-                    : "";
-            const apiKey = typeof flags["api-key"] === "string"
-                ? flags["api-key"]
-                : useEnv
-                    ? process.env.DATAIKU_API_KEY ?? ""
-                    : "";
-            const projectKey = typeof flags["project-key"] === "string"
-                ? flags["project-key"]
-                : useEnv
-                    ? process.env.DATAIKU_PROJECT_KEY
-                    : undefined;
+            const { url, apiKey, projectKey, tlsSettings, } = resolveLoginCredentials(flags);
             if (!url || !apiKey) {
                 throw new UsageError("Missing --url and/or --api-key for auth login.", "missing_required_flag", "Pass --url and --api-key, or set DATAIKU_URL and DATAIKU_API_KEY.", { requiredFlags: ["url", "api-key",], env: ["DATAIKU_URL", "DATAIKU_API_KEY",], });
             }
@@ -237,13 +233,13 @@ const VERSION_USAGE = "dss version";
 const VERSION_DESCRIPTION = "Print the CLI version, checkout/build revisions, load source, runtime, and stale-build status as JSON.";
 const VERSION_EXAMPLES = ["dss version", "dss --version",];
 const INSTALL_SKILL_USAGE = "dss install-skill [--global] [--agent NAME] [--target PATH] [--list-agents] [--dry-run] [--plan]";
-const INSTALL_SKILL_DESCRIPTION = "Install the dataiku-dss agent skill for detected coding agents.";
+const INSTALL_SKILL_DESCRIPTION = "Report missing/stale/current skill status and atomically install changed dataiku-dss agent skills.";
 const INSTALL_SKILL_EXAMPLES = [
     "dss install-skill --list-agents",
     "dss install-skill --agent omp --dry-run",
 ];
 export const CLEANUP_USAGE = "dss cleanup --file PATH [--dry-run|--apply] [--continue-on-error]";
-const CLEANUP_DESCRIPTION = "Replay cleanup ledger entries in reverse order.";
+const CLEANUP_DESCRIPTION = "Replay cleanup entries in reverse order; failures include structured code/category/exitCode/retryability summaries.";
 const CLEANUP_EXAMPLES = [
     "dss cleanup --file cleanup.jsonl",
     "dss cleanup --file cleanup.jsonl --apply",
@@ -272,6 +268,12 @@ const ALLOWED_CLEANUP_ACTIONS = new Set([
     "folder delete-file",
     "project delete",
     "app delete-instance",
+    "meaning delete",
+    "notebook delete-jupyter",
+    "notebook delete-sql",
+    "project-library delete",
+    "streaming-endpoint delete",
+    "workspace delete",
 ]);
 export function isAllowedCleanupAction(resource, action) {
     return ALLOWED_CLEANUP_ACTIONS.has(`${resource} ${action}`);
@@ -407,7 +409,202 @@ function structuredExamples(examples, examplePayload) {
         };
     });
 }
-function outputJsonSchema(shape) {
+const PROJECT_LIBRARY_ITEM_OUTPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["name",],
+    properties: {
+        name: { type: "string", },
+        path: { type: "string", },
+        size: { type: "integer", minimum: 0, },
+        mimeType: { type: "string", },
+        hasData: { type: "boolean", },
+        lastModified: { type: "number", },
+        children: { type: "array", items: { type: "object", additionalProperties: true, }, },
+    },
+};
+const NOTEBOOK_SAVE_OUTPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["saved", "resource", "created", "hash",],
+    properties: {
+        saved: { type: "string", },
+        resource: { enum: ["jupyter-notebook", "sql-notebook",], },
+        created: { type: "boolean", },
+        hash: { type: "string", pattern: "^[a-f0-9]{64}$", },
+    },
+};
+const COMMAND_OUTPUT_SCHEMAS = {
+    "code-env.list": CodeEnvSummaryArraySchema,
+    "code-env.get": CodeEnvDetailsSchema,
+    "code-env.list-logs": CodeEnvLogSummaryArraySchema,
+    "code-env.get-log": {
+        oneOf: [
+            {
+                type: "object",
+                required: ["log", "bytes", "truncated", "tailed", "envLang", "envName", "logName",],
+                properties: {
+                    log: { type: "string", },
+                    bytes: { type: "integer", minimum: 0, },
+                    truncated: { type: "boolean", },
+                    tailed: { type: "boolean", },
+                    envLang: { enum: ["PYTHON", "R",], },
+                    envName: { type: "string", },
+                    logName: { type: "string", },
+                },
+            },
+            {
+                type: "object",
+                required: ["path", "bytes", "truncated", "tailed", "envLang", "envName", "logName",],
+                properties: {
+                    path: { type: "string", },
+                    bytes: { type: "integer", minimum: 0, },
+                    truncated: { type: "boolean", },
+                    tailed: { type: "boolean", },
+                    envLang: { enum: ["PYTHON", "R",], },
+                    envName: { type: "string", },
+                    logName: { type: "string", },
+                },
+            },
+        ],
+    },
+    "code-env.version": CodeEnvVersionForProjectSchema,
+    "code-env.usages": CodeEnvUsageArraySchema,
+    "code.run": {
+        type: "object",
+        additionalProperties: false,
+        required: [
+            "outcome",
+            "success",
+            "runId",
+            "elapsedMs",
+            "pollCount",
+            "output",
+            "logTruncated",
+            "maxLogBytes",
+            "cleanup",
+        ],
+        properties: {
+            outcome: { type: "string", },
+            success: { type: "boolean", },
+            runId: { type: "string", },
+            elapsedMs: { type: "number", minimum: 0, },
+            pollCount: { type: "integer", minimum: 0, },
+            output: { type: "string", },
+            log: { type: "string", },
+            logTruncated: { type: "boolean", },
+            maxLogBytes: { type: "integer", minimum: 0, },
+            timedOut: { const: true, },
+            timeoutMs: { type: "integer", minimum: 0, },
+            cleanup: {
+                type: "object",
+                additionalProperties: false,
+                required: ["status",],
+                properties: {
+                    status: { enum: ["deleted", "kept", "failed",], },
+                    error: { type: "string", },
+                },
+            },
+        },
+    },
+    "notebook.list-jupyter": JupyterNotebookSummaryArraySchema,
+    "notebook.get-jupyter": JupyterNotebookContentSchema,
+    "notebook.sessions-jupyter": NotebookSessionArraySchema,
+    "notebook.list-sql": SqlNotebookSummaryArraySchema,
+    "notebook.get-sql": SqlNotebookContentSchema,
+    "notebook.history-sql": SqlNotebookHistorySchema,
+    "notebook.save-jupyter": NOTEBOOK_SAVE_OUTPUT_SCHEMA,
+    "notebook.save-sql": NOTEBOOK_SAVE_OUTPUT_SCHEMA,
+    "project-library.list": { type: "array", items: PROJECT_LIBRARY_ITEM_OUTPUT_SCHEMA, },
+    "project-library.get-bytes": {
+        type: "object",
+        additionalProperties: false,
+        required: ["path", "bytes", "sha256",],
+        properties: {
+            path: { type: "string", },
+            bytes: { type: "integer", minimum: 0, },
+            sha256: { type: "string", pattern: "^[a-f0-9]{64}$", },
+        },
+    },
+    "project-library.put": {
+        type: "object",
+        additionalProperties: false,
+        required: ["updated", "bytes", "sha256",],
+        properties: {
+            updated: { type: "string", },
+            bytes: { type: "integer", minimum: 0, },
+            sha256: { type: "string", pattern: "^[a-f0-9]{64}$", },
+            beforeSha256: { type: "string", pattern: "^[a-f0-9]{64}$", },
+        },
+    },
+    "project-library.diff": {
+        type: "object",
+        additionalProperties: false,
+        required: [
+            "path",
+            "unchanged",
+            "added",
+            "removed",
+            "diff",
+            "diffTruncated",
+            "localSha256",
+            "localBytes",
+            "maxLines",
+        ],
+        properties: {
+            path: { type: "string", },
+            unchanged: { type: "boolean", },
+            added: { type: "integer", minimum: 0, },
+            removed: { type: "integer", minimum: 0, },
+            diff: { type: "string", },
+            diffTruncated: { type: "boolean", },
+            binary: { type: "boolean", },
+            remoteAbsent: { type: "boolean", },
+            remoteSha256: { type: "string", pattern: "^[a-f0-9]{64}$", },
+            remoteBytes: { type: "integer", minimum: 0, },
+            localSha256: { type: "string", pattern: "^[a-f0-9]{64}$", },
+            localBytes: { type: "integer", minimum: 0, },
+            maxLines: { type: "integer", minimum: 0, },
+        },
+    },
+    "project.list": ProjectSummaryArraySchema,
+    "project.get": ProjectDetailsSchema,
+    "project.metadata": ProjectMetadataSchema,
+    "dataset.list": DatasetSummaryArraySchema,
+    "dataset.get": DatasetDetailsSchema,
+    "dataset.schema": DatasetSchemaSchema,
+    "recipe.list": RecipeSummaryArraySchema,
+    "job.list": JobSummaryArraySchema,
+    "job.wait": JobWaitResultSchema,
+    "job.monitor": JobWaitResultSchema,
+    "scenario.list": ScenarioSummaryArraySchema,
+    "scenario.get": ScenarioDetailsSchema,
+    "scenario.status": ScenarioStatusSchema,
+    "flow-zone.list": FlowZoneArraySchema,
+    "flow-zone.get": FlowZoneSchema,
+    "sql.query": {
+        anyOf: [
+            SqlQueryResponseSchema,
+            {
+                type: "object",
+                required: ["queryId", "rowCount", "preview",],
+                additionalProperties: true,
+                properties: {
+                    queryId: { type: "string", },
+                    rowCount: { type: "number", },
+                    preview: { type: "array", items: true, },
+                    truncated: { type: "boolean", },
+                    outputPath: { type: "string", },
+                    written: { type: "string", },
+                },
+            },
+        ],
+    },
+};
+function outputJsonSchema(resource, action, shape) {
+    const precise = COMMAND_OUTPUT_SCHEMAS[registryKey(resource, action)];
+    if (precise)
+        return precise;
     if (shape === "array")
         return { type: "array", items: true, };
     if (shape === "string")
@@ -417,6 +614,9 @@ function outputJsonSchema(shape) {
 function payloadJsonSchema(payloadSchema) {
     if (!payloadSchema)
         return undefined;
+    if (payloadSchema.contentType === "text/plain") {
+        return { type: "string", contentMediaType: "text/plain", };
+    }
     return payloadSchema.jsonShape === "array"
         ? { type: "array", items: true, }
         : { type: "object", additionalProperties: true, };
@@ -564,10 +764,13 @@ export function buildCommandSchemas(resource, action, flags, requiredFlags, requ
     return {
         argv: argvJsonSchema(resource, action, flags, usage, requiredFlags, requiredOneOf),
         ...(payloadSchema ? { input: payloadJsonSchema(payloadSchema), } : {}),
-        output: outputJsonSchema(outputShape),
+        output: outputJsonSchema(resource, action, outputShape),
     };
 }
 const EXPLICIT_REGISTRY_OVERRIDES = {
+    "code.run": {
+        payloadSchema: { stdin: true, contentType: "text/plain", },
+    },
     "dashboard.create": {
         examplePayload: { name: "Agent dashboard", pages: [], },
     },
@@ -620,8 +823,78 @@ function extractUsageFlags(usage) {
     }
     return uniqueStrings(flags).filter((flag) => KNOWN_LONG_FLAGS.has(flag));
 }
-function extractPositionals(usage) {
-    return uniqueStrings([...usage.matchAll(/<([^>]+)>/g),].map((match) => match[1]));
+function extractPositionalArguments(usage) {
+    const positionals = [];
+    const add = (name, required) => {
+        const existing = positionals.find((positional) => positional.name === name);
+        if (existing)
+            existing.required ||= required;
+        else
+            positionals.push({ name, required, });
+    };
+    for (const match of usage.matchAll(/<([^>]+)>/g)) {
+        const before = usage.slice(0, match.index);
+        const openParen = before.lastIndexOf("(");
+        const insideParen = openParen > before.lastIndexOf(")");
+        const closeParen = insideParen ? usage.indexOf(")", match.index) : -1;
+        const group = closeParen >= 0 ? usage.slice(openParen + 1, closeParen) : "";
+        const hasFlagAlternative = group.split("|").some((alternative) => alternative.includes("--"));
+        const required = before.lastIndexOf("[") <= before.lastIndexOf("]")
+            && !hasFlagAlternative;
+        add(match[1], required);
+    }
+    for (const suffix of usage.split("[").slice(1)) {
+        const candidate = suffix.split("]", 1)[0];
+        if (candidate && /^[A-Za-z][A-Za-z0-9_-]*$/.test(candidate))
+            add(candidate, false);
+    }
+    for (const group of topLevelParenGroups(usage)) {
+        const candidate = group.split("|", 1)[0]?.trim();
+        if (candidate && /^[A-Z][A-Z0-9_-]*$/.test(candidate))
+            add(candidate, false);
+    }
+    return positionals;
+}
+const COMMAND_REQUIRED_INPUT_GROUPS = {
+    "notebook.unload-jupyter": [
+        {
+            oneOf: [
+                { positionals: ["name", "sessionId",], },
+                { flags: ["all",], },
+            ],
+        },
+    ],
+    "sql.query": [
+        {
+            oneOf: [
+                { positionals: ["SQL",], },
+                { flags: ["sql",], },
+                { flags: ["sql-file",], },
+                { flags: ["stdin",], },
+            ],
+        },
+        { oneOf: [{ flags: ["connection",], }, { flags: ["dataset",], },], },
+    ],
+    "flow-zone.move": [
+        {
+            oneOf: [
+                { positionals: ["id",], },
+                { flags: ["zone",], },
+                { flags: ["zone-id",], },
+            ],
+        },
+        {
+            oneOf: [
+                { flags: ["dataset",], },
+                { flags: ["recipe",], },
+                { flags: ["folder",], },
+                { flags: ["object",], },
+            ],
+        },
+    ],
+};
+function requiredInputGroups(resource, action) {
+    return COMMAND_REQUIRED_INPUT_GROUPS[registryKey(resource, action)] ?? [];
 }
 function inferSideEffect(resource, action) {
     if (resource === "auth")
@@ -633,6 +906,10 @@ function inferSideEffect(resource, action) {
     }
     if (resource === "install-skill")
         return "write";
+    if (resource === "sql" && action === "query")
+        return "write";
+    if (resource === "ml-task" && action === "train")
+        return "write";
     // Project and dashboard exports stream a rendered/archive artifact and write it
     // locally; the DSS-side resource is untouched.
     if ((resource === "project" || resource === "dashboard") && action === "export")
@@ -668,6 +945,8 @@ export function inferRequiresProject(resource, action, usage) {
         || resource === "install-skill" || resource === "version") {
         return false;
     }
+    if (resource === "sql" && action === "query")
+        return false;
     if (PROJECT_SCOPED_RESOURCES.has(resource))
         return true;
     if (resource === "project-git")
@@ -828,6 +1107,11 @@ const GLOBAL_FLAG_VALUE_HINTS = {
     "ca-cert": { valueType: "PATH", },
     "project-key": { valueType: "KEY", },
     "record-cleanup": { valueType: "PATH", },
+    color: { valueType: "HEX", },
+    data: { valueType: "JSON", },
+    local: { valueType: "JSON", },
+    standard: { valueType: "JSON", },
+    until: { valueType: "STATE", },
 };
 /** Derive a value placeholder (and enum members) for each value flag from its usage token. */
 function extractFlagValueHints(usage) {
@@ -866,6 +1150,7 @@ function inferExitCodes(resource, action, asyncKind) {
         || `${resource}.${action}` === "dataset.assert-count"
         || `${resource}.${action}` === "dataset.assert-schema"
         || `${resource}.${action}` === "data-quality.assert-results"
+        || `${resource}.${action}` === "flow-zone.organize"
         || `${resource}.${action}` === "batch.run";
     return {
         ok: 0,
@@ -877,6 +1162,12 @@ function inferExitCodes(resource, action, asyncKind) {
     };
 }
 function cleanupCommandFromDeleteUsage(resource, action) {
+    if (`${resource}.${action}` === "notebook.save-jupyter") {
+        return "dss notebook delete-jupyter <name> --if-exists";
+    }
+    if (`${resource}.${action}` === "notebook.save-sql") {
+        return "dss notebook delete-sql <id> --if-exists";
+    }
     if (`${resource}.${action}` === "project.import") {
         return "dss project delete <used-project-key> --if-exists --expect-project-incarnation <hash>";
     }
@@ -911,6 +1202,7 @@ export function supportsCleanupLedger(resource, action) {
  */
 const EXPLICIT_DESTRUCTIVE_KEYS = {
     "dataset.upload-file": true,
+    "sql.query": true,
 };
 function inferDestructiveLevel(resource, sideEffect, action) {
     if (sideEffect !== "write")
@@ -930,6 +1222,8 @@ function inferAsyncKind(resource, action) {
     }
     if (resource === "recipe" && action === "run")
         return "job";
+    if (resource === "ml-task" && action === "train")
+        return "job";
     if (resource === "future" && ["get", "peek", "wait", "abort",].includes(action))
         return "future";
     if (resource === "scenario" && ["run", "run-and-wait", "status",].includes(action)) {
@@ -943,6 +1237,11 @@ function inferAsyncKind(resource, action) {
         return "future";
     if (resource === "code" && action === "run")
         return "future";
+    if (resource === "webapp" && action === "restart-backend")
+        return "future";
+    if (resource === "code-env"
+        && ["create", "update-packages", "update-images", "set-jupyter", "delete",].includes(action))
+        return "future";
     if (resource === "app"
         && ["create-instance", "create-successor-instance", "delete-instance",].includes(action)) {
         return "future";
@@ -952,6 +1251,8 @@ function inferAsyncKind(resource, action) {
 function inferIdempotency(resource, sideEffect, action, usage) {
     if (sideEffect === "read")
         return "safe";
+    if (`${resource}.${action}` === "install-skill.run")
+        return "convergent";
     if (action.startsWith("create") && usage.includes("--if-not-exists"))
         return "if-not-exists";
     if (action.startsWith("delete") && usage.includes("--if-exists"))
@@ -990,18 +1291,26 @@ export function inferCleanupHint(resource, action) {
     // tag create has a generic `delete` command to close it out.
     if (resource === "project-git")
         return undefined;
+    const key = `${resource}.${action}`;
+    if (key === "notebook.save-jupyter") {
+        return "When the save reports created:true, delete with `dss notebook delete-jupyter <name> --if-exists`.";
+    }
+    if (key === "notebook.save-sql") {
+        return "When the save reports created:true, delete with `dss notebook delete-sql <id> --if-exists`.";
+    }
     if (!(action.startsWith("create") || action === "clone"))
         return undefined;
-    if (LEDGER_ONLY_CLEANUP_KEYS[`${resource}.${action}`] === true) {
+    if (LEDGER_ONLY_CLEANUP_KEYS[key] === true)
         return LEDGER_ONLY_CLEANUP_HINT;
-    }
     const deleteAction = action === "create-rule"
         ? "delete-rule"
         : action === "create-instance" || action === "create-successor-instance"
             ? "delete-instance"
             : "delete";
     const deleteUsage = commands[resource]?.[deleteAction]?.usage;
-    const ifExists = deleteUsage?.includes("--if-exists") ? " --if-exists" : "";
+    if (!deleteUsage)
+        return undefined;
+    const ifExists = deleteUsage.includes("--if-exists") ? " --if-exists" : "";
     if (resource === "code-env") {
         return `Delete with \`dss code-env delete <lang> <name>${ifExists}\`.`;
     }
@@ -1074,7 +1383,9 @@ function buildRegistryEntry(resource, action, meta) {
             ...allowEmptyPart,
         };
     });
-    const positionals = extractPositionals(meta.usage);
+    const positionalArguments = extractPositionalArguments(meta.usage);
+    const positionals = positionalArguments.map((positional) => positional.name);
+    const inputGroups = requiredInputGroups(resource, action);
     const outputShape = inferOutputShape(resource, action);
     const producesLocalFile = meta.usage.includes("--output PATH")
         || meta.usage.includes("--output-file PATH");
@@ -1090,6 +1401,7 @@ function buildRegistryEntry(resource, action, meta) {
         structuredExamples: structuredExamples(meta.examples, examplePayload),
         flags: flagMetadata,
         positionals,
+        positionalArguments,
         sideEffect,
         requiresAuth,
         requiresProject,
@@ -1104,6 +1416,7 @@ function buildRegistryEntry(resource, action, meta) {
         requiredFlags: uniqueRequiredFlags,
         optionalFlags: uniqueOptionalFlags,
         ...(requiredOneOf.length > 0 ? { requiredOneOf, } : {}),
+        ...(inputGroups.length > 0 ? { requiredInputGroups: inputGroups, } : {}),
         ...(payloadSchema ? { payloadSchema, } : {}),
         schemas: buildCommandSchemas(resource, action, flagMetadata, uniqueRequiredFlags, requiredOneOf, payloadSchema, outputShape, meta.usage),
         ...(unsafe ? { unsafeOutputs: unsafe, } : {}),
@@ -1216,6 +1529,7 @@ function commandRegistryEntryJsonSchema() {
             "usage",
             "flags",
             "positionals",
+            "positionalArguments",
             "sideEffect",
             "requiresAuth",
             "requiresProject",
@@ -1235,6 +1549,15 @@ function commandRegistryEntryJsonSchema() {
             structuredExamples: { type: "array", items: { type: "object", additionalProperties: true, }, },
             flags: { type: "array", items: commandFlagJsonSchema(), },
             positionals: { type: "array", items: { type: "string", }, },
+            positionalArguments: {
+                type: "array",
+                items: {
+                    type: "object",
+                    required: ["name", "required",],
+                    additionalProperties: false,
+                    properties: { name: { type: "string", }, required: { type: "boolean", }, },
+                },
+            },
             sideEffect: { enum: ["read", "write", "auth",], },
             requiresAuth: { type: "boolean", },
             requiresProject: { type: "boolean", },
@@ -1247,6 +1570,7 @@ function commandRegistryEntryJsonSchema() {
             idempotency: { enum: ["safe", "convergent", "if-not-exists", "if-exists", "none",], },
             dryRun: { type: "boolean", },
             requiredFlags: { type: "array", items: { type: "string", }, },
+            requiredInputGroups: { type: "array", items: { type: "object", additionalProperties: true, }, },
             optionalFlags: { type: "array", items: { type: "string", }, },
             schemas: { type: "object", additionalProperties: true, },
             unsafeOutputs: { type: "array", items: { type: "object", additionalProperties: true, }, },
@@ -1275,8 +1599,13 @@ function errorEnvelopeJsonSchema() {
             ok: { const: false, },
             error: { type: "string", },
             code: { type: "string", },
-            category: { enum: ["usage", "dss", "internal",], },
+            category: { enum: ["usage", "permission_or_environment", "dss", "internal",], },
             exitCode: { type: "number", },
+            hint: { type: "string", },
+            status: { type: "number", },
+            retryable: { type: "boolean", },
+            requestId: { type: "string", },
+            details: { type: "object", additionalProperties: true, },
             resource: { type: "string", },
             action: { type: "string", },
             projectKey: { type: "string", },
@@ -1367,6 +1696,8 @@ export function buildAgentContract() {
                 format: "compact-json",
                 success: "single-json-value",
                 failure: "structured-error-object",
+                failureResultDetailLimitBytes: 65_536,
+                fieldProjection: "Missing --fields paths stay null on stdout and emit field_projection_missing on stderr.",
                 richFailureResults: "doctor/batch/cleanup nonzero outcomes are their own compact result on stdout ({ok:false,...}) with the command's exit code; not re-wrapped.",
             },
             stderr: {
@@ -1454,7 +1785,9 @@ function requiredPlanJsonInput(flags, usage) {
     return requiredJsonInput(flags, `--data, --data-file, or --stdin is required. Usage: ${usage}`);
 }
 function requiredPlanPositionals(usage) {
-    return [...stripOptionalUsageGroups(usage).matchAll(/<([^>]+)>/g),].map((match) => match[1]);
+    return extractPositionalArguments(usage)
+        .filter((positional) => positional.required)
+        .map((positional) => positional.name);
 }
 function dataQualityEndpoint(projectKey, datasetName, suffix) {
     return encodedProjectEndpointForPlan(projectKey, `/datasets/${encodeURIComponent(datasetName)}/data-quality${suffix}`);
@@ -1482,11 +1815,6 @@ function projectGitEndpoint(projectKey, suffix) {
 function projectGitFutureEndpoint(jobId) {
     return `${PROJECT_GIT_API_ROOT}/futures/${encodeURIComponent(jobId)}`;
 }
-/** Encode a library reference path per segment, mirroring the resource helper. */
-function encodeGitReferencePath(pathValue) {
-    const normalized = pathValue.replace(/^\/+/, "").replace(/\/+$/, "");
-    return normalized.split("/").map((segment) => encodeURIComponent(segment)).join("/");
-}
 /**
  * `--plan` bypasses the SDK boundary guard, so HTTP(S) URLs with embedded
  * userinfo are rejected here before any plan is printed. SSH/scp-style URLs
@@ -1566,10 +1894,33 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
         return encodedProjectEndpointForPlan(projectKey, suffix);
     };
     const id = args[0];
-    const codeEnvEndpoint = (suffix = "") => `/public/api/admin/code-envs/${encodeURIComponent(args[0])}/${encodeURIComponent(args[1])}${suffix}`;
+    const codeEnvEndpoint = (suffix = "") => `/public/api/admin/code-envs/${encodeURIComponent(codeEnvLang(args[0], entry.usage))}/${encodeURIComponent(args[1])}${suffix}`;
     const statisticsWorksheetsEndpoint = (datasetName) => projectEndpoint(`/datasets/${encodeURIComponent(datasetName)}/statistics/worksheets/`);
     const statisticsWorksheetEndpoint = (datasetName, worksheetId) => `${statisticsWorksheetsEndpoint(datasetName)}${encodeURIComponent(worksheetId)}`;
     switch (`${resource}.${action}`) {
+        case "sql.query": {
+            const payload = resolveSqlQueryInvocation(args, flags, planProjectKeyFromArgs(flags));
+            return {
+                method: "POST",
+                endpoint: "/public/api/sql/queries/",
+                identifiers: {
+                    connection: payload.connection,
+                    dataset: payload.datasetFullName,
+                },
+                payload,
+            };
+        }
+        case "ml-task.train":
+            return {
+                method: "POST",
+                endpoint: projectEndpoint(`/models/lab/${encodeURIComponent(args[0])}/${encodeURIComponent(args[1])}/train`),
+                identifiers: { analysisId: args[0], mlTaskId: args[1], },
+                payload: {
+                    sessionName: flags["session-name"],
+                    runQueue: false,
+                },
+                wait: flags["wait"] === true,
+            };
         case "wiki.create": {
             const name = requiredPlanFlag(flags, "name", entry.usage);
             return {
@@ -1939,17 +2290,72 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
         }
         case "recipe.run":
             return {
+                exact: false,
+                reason: "The job endpoint is exact, but DSS reads the recipe and its outputs before constructing the job payload; use recipe run --dry-run for a resolved payload.",
                 method: "POST",
                 endpoint: projectEndpoint("/jobs/"),
                 identifiers: { recipe: id, },
-                payload: {
-                    recipe: id,
-                    outputResolution: "dynamic",
-                    projectKey,
-                    partition: flags["partition"],
-                },
                 wait: recipeRunShouldWait(flags),
             };
+        case "code.run": {
+            const { script, source, } = resolveCodeInputWithSource(args, flags);
+            const sourceSha256 = sha256Hex(script);
+            const scenarioBase = projectEndpoint("/scenarios/{generatedScenarioId}");
+            const envName = flags["env"];
+            const keepScenario = flags["keep"] === true;
+            const timeoutMs = parseCodeRunIntegerFlag(flags["timeout"], "--timeout") ?? 120_000;
+            const maxLogBytes = flags["full-log"] === true
+                ? 0
+                : parseCodeRunIntegerFlag(flags["max-log-bytes"], "--max-log-bytes") ?? 1_048_576;
+            return {
+                method: "POST",
+                endpoint: projectEndpoint("/scenarios/"),
+                identifiers: {
+                    source,
+                    sourceSha256,
+                    sourceBytes: Buffer.byteLength(script),
+                },
+                requests: [
+                    {
+                        method: "POST",
+                        endpoint: projectEndpoint("/scenarios/"),
+                        payload: {
+                            id: "{generatedScenarioId}",
+                            name: "dss code run ({generatedScenarioId})",
+                            projectKey,
+                            type: "custom_python",
+                            params: {
+                                envSelection: envName
+                                    ? { envMode: "EXPLICIT_ENV", envName, }
+                                    : { envMode: "INHERIT", },
+                            },
+                        },
+                    },
+                    {
+                        method: "PUT",
+                        endpoint: `${scenarioBase}/payload`,
+                        payload: { extension: "py", script: "<omitted>", },
+                        redactedFields: ["payload.script",],
+                    },
+                    { method: "POST", endpoint: `${scenarioBase}/run/`, payload: {}, },
+                    {
+                        method: "GET",
+                        endpoint: `${scenarioBase}/get-run-for-trigger?triggerId={triggerId}&triggerRunId={triggerRunId}`,
+                        repeat: "until scenarioRun.result.outcome or timeout",
+                    },
+                    {
+                        method: "GET",
+                        endpoint: `${scenarioBase}/{runId}/log`,
+                        boundedBytes: maxLogBytes,
+                    },
+                    ...keepScenario ? [] : [{ method: "DELETE", endpoint: scenarioBase, cleanup: true, },],
+                ],
+                wait: {
+                    timeoutMs,
+                    pollEndpoint: `${scenarioBase}/get-run-for-trigger`,
+                },
+            };
+        }
         case "recipe.update":
             return {
                 method: "PUT",
@@ -2710,27 +3116,187 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 identifiers: { dataset: args[0], worksheetId: args[1], },
                 payload: requiredPlanJsonInput(flags, entry.usage),
             };
-        case "bundle.export":
+        case "webapp.create":
+            return {
+                method: "POST",
+                endpoint: projectEndpoint("/webapps/"),
+                payload: requiredPlanJsonInput(flags, entry.usage),
+            };
+        case "webapp.update-settings": {
+            const patch = requiredPlanJsonInput(flags, entry.usage);
+            const expectHash = flags["expect-hash"];
+            if (expectHash !== undefined && !/^[a-fA-F0-9]{64}$/.test(expectHash)) {
+                throw new UsageError("Expected webapp hash must be a 64-character SHA-256 hex digest.");
+            }
+            const endpoint = projectEndpoint(`/webapps/${encodeURIComponent(id)}`);
+            return {
+                exact: false,
+                reason: "Apply GETs the current settings, deep-merges the patch, then PUTs the full object.",
+                method: "PUT",
+                endpoint,
+                identifiers: {
+                    webappId: id,
+                    patchHash: stableHash(patch),
+                    ...(expectHash ? { expectHash: expectHash.toLowerCase(), } : {}),
+                },
+                payload: { patch: "<omitted>", patchHash: stableHash(patch), },
+                requests: [
+                    { method: "GET", endpoint, purpose: "read full settings and verify expectHash", },
+                    {
+                        method: "PUT",
+                        endpoint,
+                        condition: "settings read and expected hash matched",
+                        payload: "<merged full settings>",
+                    },
+                ],
+            };
+        }
+        case "webapp.stop-backend":
+            return {
+                method: "PUT",
+                endpoint: projectEndpoint(`/webapps/${encodeURIComponent(id)}/backend/actions/stop`),
+                identifiers: { webappId: id, },
+                payload: {},
+            };
+        case "webapp.restart-backend": {
+            const endpoint = projectEndpoint(`/webapps/${encodeURIComponent(id)}/backend/actions/restart`);
             return {
                 method: "PUT",
-                endpoint: projectEndpoint(`/bundles/exported/${encodeURIComponent(id)}`),
+                endpoint,
+                identifiers: { webappId: id, },
+                payload: {},
+                wait: {
+                    requested: flags["wait"] === true,
+                    timeoutMs: num(flags["timeout"], "--timeout"),
+                    pollIntervalMs: num(flags["poll-interval"], "--poll-interval"),
+                },
+            };
+        }
+        case "api-service.create":
+            return {
+                method: "POST",
+                endpoint: projectEndpoint(`/apiservices/${encodeURIComponent(id)}`),
+                identifiers: { serviceId: id, },
+                payload: {},
+            };
+        case "api-service.save-settings": {
+            const settings = requiredPlanJsonInput(flags, entry.usage);
+            const expectHash = flags["expect-hash"];
+            if (expectHash !== undefined && !/^[a-fA-F0-9]{64}$/.test(expectHash)) {
+                throw new UsageError("Expected API service settings hash must be a 64-character SHA-256 hex digest.");
+            }
+            const endpoint = projectEndpoint(`/apiservices/${encodeURIComponent(id)}/settings`);
+            const payload = {
+                settings: "<omitted>",
+                settingsHash: stableHash(settings),
+                ...(expectHash ? { expectHash: expectHash.toLowerCase(), } : {}),
+            };
+            return {
+                method: "PUT",
+                endpoint,
+                identifiers: { serviceId: id, },
+                payload,
+                requests: [
+                    ...(expectHash
+                        ? [{ method: "GET", endpoint, purpose: "verify expectHash", },]
+                        : []),
+                    {
+                        method: "PUT",
+                        endpoint,
+                        condition: expectHash ? "hash matched" : "unconditional",
+                        payload,
+                    },
+                ],
+            };
+        }
+        case "api-service.add-prediction-endpoint": {
+            const endpoint = projectEndpoint(`/apiservices/${encodeURIComponent(id)}/settings`);
+            return {
+                exact: false,
+                reason: "Apply GETs the full settings, appends one endpoint, then PUTs the full object.",
+                method: "PUT",
+                endpoint,
+                identifiers: { serviceId: id, endpointId: args[1], savedModelId: args[2], },
+                payload: { id: args[1], type: "STD_PREDICTION", modelRef: args[2], },
+                requests: [
+                    { method: "GET", endpoint, purpose: "read full settings", },
+                    { method: "PUT", endpoint, payload: "<merged full settings>", },
+                ],
+            };
+        }
+        case "api-service.create-package":
+        case "api-service.delete-package":
+        case "api-service.publish-package": {
+            const serviceId = args[0];
+            const packageId = args[1];
+            const packageEndpoint = projectEndpoint(`/apiservices/${encodeURIComponent(serviceId)}/packages/${encodeURIComponent(packageId)}`);
+            if (action === "delete-package") {
+                return {
+                    method: "DELETE",
+                    endpoint: packageEndpoint,
+                    identifiers: { serviceId, packageId, },
+                };
+            }
+            if (action === "publish-package") {
+                return {
+                    method: "POST",
+                    endpoint: `${packageEndpoint}/publish${querySuffix({
+                        publishedServiceId: flags["published-service-id"],
+                    })}`,
+                    identifiers: { serviceId, packageId, },
+                };
+            }
+            return {
+                method: "POST",
+                endpoint: packageEndpoint + querySuffix({
+                    releaseNotes: flags["release-notes"],
+                }),
+                identifiers: { serviceId, packageId, },
+            };
+        }
+        case "bundle.export": {
+            const evaluateProjectStandardsChecks = parseBooleanOption(flags["evaluate-standards-checks"], "--evaluate-standards-checks") ?? true;
+            return {
+                method: "PUT",
+                endpoint: projectEndpoint("/bundles/exported/" + encodeURIComponent(id)) + querySuffix({
+                    releaseNotes: flags["release-notes"],
+                    evaluateProjectStandardsChecks,
+                }),
                 identifiers: { bundleId: id, },
                 payload: {},
             };
+        }
         case "bundle.publish":
             return {
                 method: "POST",
-                endpoint: projectEndpoint(`/bundles/${encodeURIComponent(id)}/publish`),
+                endpoint: projectEndpoint("/bundles/" + encodeURIComponent(id) + "/publish") + querySuffix({
+                    publishedProjectKey: flags["published-project-key"],
+                }),
                 identifiers: { bundleId: id, },
                 payload: {},
             };
-        case "bundle.activate":
+        case "bundle.activate": {
+            const rawScenarios = flags["scenarios"];
+            let scenariosToEnable;
+            if (rawScenarios !== undefined && rawScenarios !== false) {
+                const parsed = json(rawScenarios);
+                if (typeof parsed !== "object"
+                    || parsed === null
+                    || Array.isArray(parsed)
+                    || !Object.values(parsed).every((value) => typeof value === "boolean")) {
+                    throw new UsageError("--scenarios must be a JSON object mapping scenario IDs to true|false.");
+                }
+                scenariosToEnable = parsed;
+            }
             return {
                 method: "POST",
                 endpoint: projectEndpoint(`/bundles/imported/${encodeURIComponent(id)}/actions/activate`),
                 identifiers: { bundleId: id, },
-                payload: {},
+                payload: scenariosToEnable === undefined
+                    ? {}
+                    : { scenariosActiveOnActivation: scenariosToEnable, },
             };
+        }
         case "bundle.preload":
             return {
                 method: "POST",
@@ -2738,40 +3304,151 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 identifiers: { bundleId: id, },
                 payload: {},
             };
-        case "code-env.create":
+        case "project-library.create-file":
+        case "project-library.create-folder": {
+            const libraryPath = validateLibraryPath(id);
+            const kind = action === "create-file" ? "contents" : "folders";
             return {
+                exact: false,
+                reason: "Apply performs a live absence check before POST; --if-not-exists may stop after that read, and create never overwrites an existing item.",
                 method: "POST",
-                endpoint: "/public/api/admin/code-envs/",
-                identifiers: { lang: args[0], name: args[1], },
+                endpoint: projectEndpoint(`/libraries/${kind}/${encodeLibraryPath(libraryPath)}`),
+                identifiers: { path: libraryPath, },
+            };
+        }
+        case "project-library.put": {
+            const libraryPath = validateLibraryPath(id);
+            const endpoint = projectEndpoint(`/libraries/contents/${encodeLibraryPath(libraryPath)}`);
+            const payload = projectLibraryPutPayload(flags);
+            return {
+                method: "POST",
+                endpoint,
+                identifiers: {
+                    path: libraryPath,
+                    concurrencyControl: payload.expectSha256
+                        ? PROJECT_LIBRARY_CONCURRENCY_CONTROL
+                        : "none",
+                },
+                payload,
+                ...(payload.expectSha256
+                    ? {
+                        requests: [
+                            {
+                                method: "GET",
+                                endpoint: `${endpoint}?dataEncoding=base64`,
+                                purpose: "verify expectSha256",
+                            },
+                            { method: "POST", endpoint, condition: "hash matched", payload, },
+                        ],
+                    }
+                    : {}),
+            };
+        }
+        case "project-library.delete": {
+            const libraryPath = validateLibraryPath(id);
+            return {
+                method: "DELETE",
+                endpoint: projectEndpoint(`/libraries/contents/${encodeLibraryPath(libraryPath)}`),
+                identifiers: { path: libraryPath, },
+            };
+        }
+        case "project-library.rename": {
+            const libraryPath = validateLibraryPath(id);
+            const newName = validateLibraryName(args[1]);
+            return {
+                method: "POST",
+                endpoint: projectEndpoint("/libraries/contents-actions/rename/"),
+                identifiers: { path: libraryPath, newName, },
+                payload: { oldPath: `/${libraryPath}`, newName, },
+            };
+        }
+        case "project-library.move": {
+            const libraryPath = validateLibraryPath(id);
+            const destinationFolder = validateLibraryDestinationPath(args[1]);
+            return {
+                method: "POST",
+                endpoint: projectEndpoint("/libraries/contents-actions/move"),
+                identifiers: { path: libraryPath, destinationFolder, },
+                payload: { oldPath: `/${libraryPath}`, newPath: destinationFolder, },
+            };
+        }
+        case "code-env.create": {
+            const wait = codeEnvWait(flags);
+            return {
+                method: "POST",
+                endpoint: `${codeEnvEndpoint()}?wait=${wait}`,
+                identifiers: { lang: codeEnvLang(args[0], entry.usage), name: args[1], },
                 payload: {
-                    envLang: args[0],
-                    envName: args[1],
+                    ...codeEnvParams(flags),
                     deploymentMode: requiredPlanFlag(flags, "deployment-mode", entry.usage),
-                    params: codeEnvParams(flags),
-                    wait: codeEnvWait(flags),
                 },
-                wait: codeEnvWait(flags),
+                wait,
             };
-        case "code-env.set-definition":
+        }
+        case "code-env.set-definition": {
+            const definition = requiredPlanJsonInput(flags, entry.usage);
+            const expectHash = flags["expect-hash"];
+            if (expectHash !== undefined && !/^[a-fA-F0-9]{64}$/.test(expectHash)) {
+                throw new UsageError("--expect-hash must be a 64-character SHA-256 hex digest.");
+            }
+            const endpoint = codeEnvEndpoint();
+            const definitionHash = stableHash(definition);
+            const normalizedExpectHash = expectHash?.toLowerCase();
             return {
+                exact: false,
+                reason: "Apply PUTs the supplied definition object unchanged; this plan omits that body and reports only its hash.",
                 method: "PUT",
-                endpoint: `/public/api/admin/code-envs/${encodeURIComponent(args[0])}/${encodeURIComponent(args[1])}`,
-                identifiers: { lang: args[0], name: args[1], },
-                payload: requiredPlanJsonInput(flags, entry.usage),
+                endpoint,
+                identifiers: {
+                    lang: codeEnvLang(args[0], entry.usage),
+                    name: args[1],
+                    definitionHash,
+                    ...(normalizedExpectHash ? { expectHash: normalizedExpectHash, } : {}),
+                },
+                payload: "<omitted>",
+                ...(normalizedExpectHash
+                    ? {
+                        requests: [
+                            { method: "GET", endpoint, purpose: "verify expectHash", },
+                            {
+                                method: "PUT",
+                                endpoint,
+                                condition: "hash matched",
+                                payload: "<omitted>",
+                                redactedFields: ["payload",],
+                            },
+                        ],
+                    }
+                    : {}),
             };
+        }
         case "code-env.set-packages": {
             const installCorePackages = parseBooleanOption(flags["install-core-packages"], "--install-core-packages");
-            const payload = {
-                specPackageList: codeEnvPackageList(flags).join("\n"),
-            };
-            if (installCorePackages !== undefined) {
-                payload.desc = { installCorePackages, };
+            const expectHash = flags["expect-hash"];
+            if (expectHash !== undefined && !/^[a-fA-F0-9]{64}$/.test(expectHash)) {
+                throw new UsageError("--expect-hash must be a 64-character SHA-256 hex digest.");
             }
+            const endpoint = codeEnvEndpoint();
             return {
+                exact: false,
+                reason: "Apply GETs the full definition, merges only package fields, then PUTs the full result.",
                 method: "PUT",
-                endpoint: codeEnvEndpoint(),
-                identifiers: { lang: args[0], name: args[1], },
-                payload,
+                endpoint,
+                identifiers: { lang: codeEnvLang(args[0], entry.usage), name: args[1], },
+                payload: {
+                    packages: codeEnvPackageList(flags),
+                    ...(installCorePackages !== undefined ? { installCorePackages, } : {}),
+                    ...(expectHash ? { expectHash: expectHash.toLowerCase(), } : {}),
+                },
+                requests: [
+                    { method: "GET", endpoint, purpose: "read full definition and verify expectHash", },
+                    {
+                        method: "PUT",
+                        endpoint,
+                        condition: "definition read and hash matched",
+                        payload: "<merged full definition>",
+                    },
+                ],
             };
         }
         case "code-env.update-packages": {
@@ -2780,15 +3457,25 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
                 : typeof flags["version"] === "string"
                     ? flags["version"]
                     : undefined;
+            const wait = codeEnvWait(flags);
             return {
                 method: "POST",
                 endpoint: `${codeEnvEndpoint("/packages")}${querySuffix({
                     forceRebuildEnv: flags["force-rebuild"] === true,
                     versionToUpdate,
-                    wait: codeEnvWait(flags),
+                    wait,
                 })}`,
-                identifiers: { lang: args[0], name: args[1], },
-                wait: codeEnvWait(flags),
+                identifiers: { lang: codeEnvLang(args[0], entry.usage), name: args[1], },
+                wait,
+            };
+        }
+        case "code-env.update-images": {
+            const wait = codeEnvWait(flags);
+            return {
+                method: "POST",
+                endpoint: `${codeEnvEndpoint("/images")}${querySuffix({ envVersion: flags["env-version"], wait, })}`,
+                identifiers: { lang: codeEnvLang(args[0], entry.usage), name: args[1], },
+                wait,
             };
         }
         case "code-env.set-jupyter": {
@@ -2796,27 +3483,52 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             if (active === undefined) {
                 throw new UsageError("--active is required. Usage: dss code-env set-jupyter <lang> <name> --active true|false");
             }
+            const wait = codeEnvWait(flags);
             return {
                 method: "POST",
-                endpoint: `${codeEnvEndpoint("/jupyter")}${querySuffix({ active, wait: codeEnvWait(flags), })}`,
-                identifiers: { lang: args[0], name: args[1], },
-                wait: codeEnvWait(flags),
+                endpoint: `${codeEnvEndpoint("/jupyter")}${querySuffix({ active, wait, })}`,
+                identifiers: { lang: codeEnvLang(args[0], entry.usage), name: args[1], },
+                wait,
             };
         }
-        case "code-env.delete":
+        case "code-env.delete": {
+            const wait = codeEnvWait(flags);
             return {
                 method: "DELETE",
-                endpoint: `/public/api/admin/code-envs/${encodeURIComponent(args[0])}/${encodeURIComponent(args[1])}`,
-                identifiers: { lang: args[0], name: args[1], },
-                wait: codeEnvWait(flags),
+                endpoint: `${codeEnvEndpoint()}?wait=${wait}`,
+                identifiers: { lang: codeEnvLang(args[0], entry.usage), name: args[1], },
+                wait,
             };
-        case "notebook.save-jupyter":
+        }
+        case "notebook.save-jupyter": {
+            const content = requiredPlanJsonInput(flags, entry.usage);
+            const expectHash = flags["expect-hash"];
+            if (expectHash !== undefined && !/^[a-fA-F0-9]{64}$/.test(expectHash)) {
+                throw new UsageError("Expected notebook hash must be a 64-character SHA-256 hex digest.");
+            }
+            const endpoint = projectEndpoint(`/jupyter-notebooks/${encodeURIComponent(id)}`);
             return {
-                method: "PUT",
-                endpoint: projectEndpoint(`/jupyter-notebooks/${encodeURIComponent(id)}`),
-                identifiers: { name: id, },
-                payload: requiredPlanJsonInput(flags, entry.usage),
+                exact: false,
+                reason: "A fresh GET selects POST when absent or PUT when present; a confirming GET supplies the persisted hash.",
+                endpoint,
+                identifiers: {
+                    name: id,
+                    contentHash: stableHash(content),
+                    ...(expectHash ? { expectHash: expectHash.toLowerCase(), } : {}),
+                },
+                requests: [
+                    { method: "GET", endpoint, purpose: "resolve create/update and check --expect-hash", },
+                    {
+                        method: "POST|PUT",
+                        endpoint,
+                        condition: "POST after not_found; otherwise PUT",
+                        payload: "<omitted>",
+                        redactedFields: ["payload",],
+                    },
+                    { method: "GET", endpoint, purpose: "confirm persisted hash", },
+                ],
             };
+        }
         case "notebook.delete-jupyter":
             return {
                 method: "DELETE",
@@ -2825,24 +3537,75 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             };
         case "notebook.clear-jupyter-outputs":
             return {
-                method: "PUT",
-                endpoint: projectEndpoint(`/jupyter-notebooks/${encodeURIComponent(id)}`),
+                method: "DELETE",
+                endpoint: projectEndpoint(`/jupyter-notebooks/${encodeURIComponent(id)}/outputs`),
                 identifiers: { name: id, },
-                payload: { clearOutputs: true, },
             };
         case "notebook.unload-jupyter":
+            if (flags["all"] === true) {
+                if (args.length > 0)
+                    throw new UsageError(entry.usage);
+                return {
+                    exact: false,
+                    reason: "DSS has no unload-all endpoint; apply lists active notebooks and sessions, then issues one verified session DELETE per result.",
+                    identifiers: { all: true, },
+                    requests: [
+                        { method: "GET", endpoint: projectEndpoint("/jupyter-notebooks/?active=true"), },
+                        {
+                            method: "GET",
+                            endpoint: projectEndpoint("/jupyter-notebooks/{name}/sessions"),
+                            forEach: "active notebook",
+                        },
+                        {
+                            method: "DELETE",
+                            endpoint: projectEndpoint("/jupyter-notebooks/{name}/sessions/{sessionId}"),
+                            forEach: "listed session",
+                        },
+                    ],
+                };
+            }
+            requireArgs(args, 2, entry.usage);
             return {
-                method: "POST",
-                endpoint: projectEndpoint(`/jupyter-notebooks/${encodeURIComponent(args[0])}/sessions/${encodeURIComponent(args[1])}/unload`),
+                method: "DELETE",
+                endpoint: projectEndpoint(`/jupyter-notebooks/${encodeURIComponent(args[0])}/sessions/${encodeURIComponent(args[1])}`),
                 identifiers: { name: args[0], sessionId: args[1], },
             };
-        case "notebook.save-sql":
+        case "notebook.save-sql": {
+            const content = requiredPlanJsonInput(flags, entry.usage);
+            const expectHash = flags["expect-hash"];
+            if (expectHash !== undefined && !/^[a-fA-F0-9]{64}$/.test(expectHash)) {
+                throw new UsageError("Expected notebook hash must be a 64-character SHA-256 hex digest.");
+            }
+            const endpoint = projectEndpoint(`/sql-notebooks/${encodeURIComponent(id)}`);
             return {
-                method: "PUT",
-                endpoint: projectEndpoint(`/sql-notebooks/${encodeURIComponent(id)}`),
-                identifiers: { id, },
-                payload: requiredPlanJsonInput(flags, entry.usage),
+                exact: false,
+                reason: "A fresh GET selects collection POST when absent or entity PUT when present; a confirming GET supplies the persisted hash.",
+                endpoint,
+                identifiers: {
+                    id,
+                    contentHash: stableHash(content),
+                    ...(expectHash ? { expectHash: expectHash.toLowerCase(), } : {}),
+                },
+                requests: [
+                    { method: "GET", endpoint, purpose: "resolve create/update and check --expect-hash", },
+                    {
+                        method: "POST",
+                        endpoint: projectEndpoint("/sql-notebooks/"),
+                        condition: "after not_found",
+                        payload: "<omitted; includes id and projectKey>",
+                        redactedFields: ["payload",],
+                    },
+                    {
+                        method: "PUT",
+                        endpoint,
+                        condition: "when present",
+                        payload: "<omitted>",
+                        redactedFields: ["payload",],
+                    },
+                    { method: "GET", endpoint, purpose: "confirm persisted hash", },
+                ],
             };
+        }
         case "notebook.delete-sql":
             return {
                 method: "DELETE",
@@ -2851,10 +3614,13 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             };
         case "notebook.clear-sql-history":
             return {
-                method: "PUT",
-                endpoint: projectEndpoint(`/sql-notebooks/${encodeURIComponent(id)}/history`),
-                identifiers: { id, cellId: flags["cell-id"], },
-                payload: { retain: num(flags["retain"], "--retain"), },
+                method: "POST",
+                endpoint: projectEndpoint(`/sql-notebooks/${encodeURIComponent(id)}/history/clear`),
+                identifiers: { id, },
+                payload: {
+                    cellId: flags["cell-id"],
+                    numRunsToRetain: num(flags["retain"], "--retain"),
+                },
             };
         case "project.create": {
             const settings = jsonInput(flags) ?? null;
@@ -3225,7 +3991,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             };
         }
         case "project-git.set-library": {
-            const targetPath = id;
+            const targetPath = validateGitReferencePath(id);
             return {
                 method: "PUT",
                 endpoint: projectGitEndpoint(projectKey, `/lib-git-refs/${encodeGitReferencePath(targetPath)}`),
@@ -3240,7 +4006,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             };
         }
         case "project-git.remove-library": {
-            const targetPath = id;
+            const targetPath = validateGitReferencePath(id);
             return {
                 method: "DELETE",
                 endpoint: projectGitEndpoint(projectKey, `/lib-git-refs/${encodeGitReferencePath(targetPath)}${querySuffix({
@@ -3250,7 +4016,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             };
         }
         case "project-git.reset-library": {
-            const targetPath = id;
+            const targetPath = validateGitReferencePath(id);
             return {
                 method: "POST",
                 endpoint: projectGitEndpoint(projectKey, "/lib-git-refs/action/reset"),
@@ -3260,7 +4026,7 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             };
         }
         case "project-git.push-library": {
-            const targetPath = id;
+            const targetPath = validateGitReferencePath(id);
             const message = requiredPlanFlag(flags, "message", entry.usage);
             return {
                 method: "POST",
@@ -3294,12 +4060,9 @@ export function commandPlanShape(resource, action, args, flags, entry, projectKe
             };
         default:
             return {
-                method: action.startsWith("delete") || action === "abort" ? "DELETE" : "POST",
-                endpoint: projectKey
-                    ? projectEndpoint(`/${resource}s/${id ? encodeURIComponent(id) : ""}`)
-                    : undefined,
+                exact: false,
+                reason: `No exact offline request shape is defined for ${resource}.${action}; no endpoint was guessed.`,
                 identifiers: id ? { id, } : undefined,
-                payload: jsonInput(flags),
             };
     }
 }
@@ -3333,7 +4096,7 @@ export const BATCH_PLAN_EXIT_CODES = {
     assertionFailure: 4,
 };
 export const BATCH_USAGE = "dss batch (--data JSON|--data-file PATH|--stdin) [--continue-on-error] [--dry-run]";
-const BATCH_DESCRIPTION = "Run a sequence of dss commands from a JSON array of argv arrays. Fail-fast by default; returns one envelope with a per-step ok/result/error and exits non-zero if any step failed.";
+const BATCH_DESCRIPTION = "Run dss argv arrays fail-fast by default. The result aggregates failed/retryable/failureCodes; process exit remains the first failed step's exit code.";
 export const BATCH_HINT = 'Pass a JSON array of argv arrays, e.g. [["dataset","list"],["recipe","update","r","--data-file","p.json"]].';
 export const BATCH_EXAMPLE_PAYLOAD = [
     ["recipe", "set-payload", "compute_orders", "--file", "code.py", "--no-backup",],