dataiku-sdk 3.2.0 → 3.3.0

package/skills/dataiku-dss/references/app-releases.md

@@ -1,6 +1,6 @@
 # Application releases
 
-Release gates: validate → compare → version → successor → verify → permissions.
+Snapshot sharing → validate → compare → version → successor → verify access.
 Manifest `version` is raw metadata, **not publishing**. New instances inherit it; existing instances never upgrade in place. Create/verify an additive successor, preserve the predecessor, retire separately. No private publish/recreate/rename, recipient-sharing, or UI-click APIs may be inferred.
 
 ```text
@@ -9,19 +9,20 @@ dss app compare-manifest APP_ID --project-key RELEASE_INSTANCE
 dss app manifest-version --project-key APP_TEMPLATE
 dss app successor-preflight APP_ID --from RELEASE_INSTANCE --to RELEASE_INSTANCE_V2 --copy-permissions
 dss app set-manifest-version --manifest-version 1.4.0 --expect-hash PREFLIGHT_TEMPLATE_MANIFEST_HASH --project-key APP_TEMPLATE
-# targetProjectKey in instance.json must be confirmed absent
 dss app create-instance APP_ID --data-file instance.json --wait --record-cleanup cleanup.jsonl
 dss app create-successor-instance APP_ID --from RELEASE_INSTANCE --to RELEASE_INSTANCE_V2 --copy-permissions --record-cleanup cleanup.jsonl
 dss app verify-instance APP_ID --project-key RELEASE_INSTANCE_V2 --expect-version 1.4.0
-dss cleanup --file cleanup.jsonl
+dss cleanup --file cleanup.jsonl --apply
 dss app permissions-snapshot --project-key RELEASE_INSTANCE --output permissions.json
 dss app permissions-diff --project-key RELEASE_INSTANCE --file permissions.json
 dss app permissions-restore --project-key RELEASE_INSTANCE --file permissions.json --dry-run
 ```
 
-- Run `successor-preflight` **before** changing the version: non-mutating validation of template, predecessor, target, optional ACL snapshot; returns the template manifest hash for `set-manifest-version --expect-hash`.
-- A masked `403`, even absent from both visible lists, fails as `target_absence_unverifiable` / `permission_or_environment`: lists prove collisions, not absence. DSS has no permission-independent public key-availability endpoint or guaranteed non-overwriting duplicate-key rejection. No force/server-atomic bypass; use global project visibility.
+- Run `successor-preflight` **before** changing the version: validate template, predecessor, optional ACLs, and an explicit target's absence; returns the template manifest hash for `set-manifest-version --expect-hash`. Omitting `--to` skips only target-absence checks, not source/template checks or apply-time target identity verification.
+- Omit `targetProjectKey` (create) or `--to` (successor) for a cryptographically random key, no visibility probes; preserve the name (defaults to key). Preflight/plan allocate nothing and omit `target.projectKey` — generated successor results carry `targetProjectKeyGeneratedDuringApply` and `targetPreflight:"not-applicable-generated-key"`; apply generates the key once before its single POST and binds cleanup through the future target plus `creationTag`. Collision risk is negligible, not zero.
+- Explicit keys/`--to` require confirmed absence. Masked `403` → `target_absence_unverifiable` / `permission_or_environment`, even if unlisted. No public availability/atomic duplicate guarantee or force bypass; exact keys need global visibility.
 - Definitive rejection: no cleanup entry. Ambiguous POST without a future ID or verified incarnation: `INDETERMINATE`, no cleanup entry. Future-addressable cleanup waits for target identity and `creationTag`; never targets the predecessor.
-- Ledgers bind canonical DSS URL, project key, concrete incarnation; reject legacy, mixed-server, mismatched-server, or unbound app entries. Static plans: `preflightExecuted:false`, `preflightWillRunDuringApply:true`.
+- Ledgers bind canonical DSS URL, project key, concrete incarnation; reject legacy, mixed-server, mismatched-server, or unbound app entries. Explicit-key plans: `preflightExecuted:false`, `preflightWillRunDuringApply:true`. Cleanup is rollback; omit `--apply` to preview.
 - `set-manifest-version` reports `concurrencyControl:"client-side-non-atomic-stale-read-check"`: `--expect-hash` guards stale reads, **not a lock**; PUT is unconditional. Ambiguous writes: `outcome:"indeterminate"`.
-- API keys authenticate public REST only. `verify-instance` reports `status:"API_VERIFIED_UI_PENDING"`; complete external SSO verification by exercising affected tiles, forms, actions. Permission snapshots bind identities/permissions to server/project incarnation and reject mismatches.
+- People absent from the originator flow can lose sharing across a template update, recreation, or successor. Snapshot live `user`/`group` access before, `permissions-diff` after, then restore approved missing access without removing new grants — `permissions-restore` is SAME-instance only and PUTs the whole object: preview and reconcile intervening changes first.
+- API keys authenticate public REST only. `verify-instance` reports `status:"API_VERIFIED_UI_PENDING"`; complete external SSO verification by exercising affected tiles, forms, actions. Permission snapshots bind to server and project incarnation, so a predecessor snapshot cannot be restored onto a successor — copy permissions at creation (`--copy-permissions`), compare predecessor/successor rules, and verify the intended identity's access before retiring the predecessor.

package/skills/dataiku-dss/references/discovery.md

@@ -13,17 +13,17 @@
 
 ```text
 dss commands run
-dss commands run --fields dataset
+dss agent contract --fields commands.actions.dataset
 dss commands run --fields dataset.create
-dss commands run --fields dataset.create.usage,dataset.create.description,dataset.create.flags,dataset.create.examples
+dss commands run --fields dataset.preview.usage,dataset.preview.description,dataset.preview.flags,dataset.preview.examples
 dss commands run --output commands.json
 dss agent contract --fields protocol,agentContractVersion,cli,stdio,planning,compatibility
 dss agent contract --fields commands.actions
 ```
 
-`commands run` defaults to a resource→action-name summary (~1k tokens), never full entries. Bootstrap with the six-field `agent contract` projection above (~250 tokens): protocol/schema compatibility, streams, discovery commands, planning, compatibility guarantees. Fetch `schemas` or `commands` only as needed.
+`commands run` defaults to a resource→action-name summary (~1.6k tokens), never full entries. For a known resource, project `commands.actions.RESOURCE` from `agent contract` (~64 tokens for dataset). Bootstrap once with the six-field projection above (~250 tokens); fetch `schemas` or `commands` only as needed.
 
-Look up syntax before invoking. `--fields RESOURCE` selects all its entries; `RESOURCE.ACTION` one complete entry; append `.FIELD` for nested metadata. Prefer `usage,description,flags,examples` for initial invocation discovery. Full entries canonically describe flags, positionals, side effects, auth, output, idempotency, dry-run, structured examples, payload schemas, unsafe outputs, cleanup, and exits.
+Look up syntax before invoking. `--fields RESOURCE` selects every full entry (potentially large); `RESOURCE.ACTION` one complete entry; append `.FIELD` for nested metadata. Reads: prefer `usage,description,flags,examples`. Writes: fetch the full entry directly once, not compact-then-full. It includes flags, positionals, side effects, auth, output, idempotency, dry-run, examples, payload schemas, unsafe outputs, cleanup, and exits.
 
 Comma-separate selectors to batch lookups. Keys echo selectors: `--fields dataset.create` → `{"dataset.create":{...}}`. Empty `--fields` fails usage validation, never dumps everything. Unknown resources/actions exit 1 with compact JSON errors listing valid options.