@salesforce/afv-skills 1.40.0 → 1.41.0

package/skills/platform-datamask-run/references/api-surface.md

@@ -0,0 +1,130 @@
+# Data Mask API Surface Reference
+
+The defining characteristic of Data Mask automation is that its entities live on **different API
+surfaces**. Reaching for the wrong one is the primary cause of failed/stuck runs. This file is the
+authoritative map.
+
+## Per-entity surface
+
+| Entity | Role | Surface | Reachable by |
+|--------|------|---------|--------------|
+| `DataMaskPolicy` | The masking policy shell (config) | Tooling API / Metadata API | `sf data query --use-tooling-api`, MDAPI deploy (thin shell only) |
+| `DataMaskPolicyObject` | Object targeted by a policy (+ its optional row filter) | **Tooling API only** | Tooling query + insert |
+| `DataMaskPolicyField` | Field + masking treatment | **Tooling API only** | Tooling query + insert |
+| `DataMaskPolicyJobRun` | The job (a single run) | **Standard data API** | `sf data query` (plain SOQL) |
+| `DataMaskPolicyJobRunDtl` | Per-object job detail (child) | **Standard data API** | `sf data query` (plain SOQL) |
+| `DataMaskCustomValueLibrary` | Custom replacement-value library | **Standard data API** | `sf data query` (plain SOQL) |
+
+`DataMaskPolicyJobRunDtl` is a child of `DataMaskPolicyJobRun` via the lookup
+**`DataMaskPolicyJobRunId`**. `DataMaskPolicy` Ids carry the **`8dm`** key prefix.
+
+> **`DataMaskPolicy` is a THIN Metadata API type.** `sf org list metadata-types` returns
+> `DataMaskPolicy` (directory `dataMaskPolicies`) with **no child components** (`childXmlNames: []`).
+> Only `<label>`, `<description>`, and `<runOnRefresh>` serialize into its metadata — object and
+> field membership is **NOT** part of the Metadata API shape (there is no inline `<policyObjects>` /
+> `<policyFields>`, and no standalone `DataMaskPolicyObject` / `DataMaskPolicyField` Metadata API
+> type). Membership lives entirely in the Tooling entities `DataMaskPolicyObject` and
+> `DataMaskPolicyField`, which you both **query and insert**. So authoring a complete policy is a
+> **two-step** operation: (1) Metadata-deploy the thin shell (in **mdapi format** — `--metadata-dir`
+> + `package.xml`; a source-format `--source-dir` deploy fails "Could not infer a metadata type"),
+> then (2) Tooling-insert the object + field rows against it. The Metadata deploy must come first:
+> it creates the policy with an active revision, without which the Tooling child insert fails
+> `INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY`. See `policy-authoring.md` for the full recipe.
+> `DataMaskPolicyField` treatment columns are `MaskingCategory` (`library` / `replaceRandom`) +
+> `MaskValue` (a snake_case library token) — there is **no `MaskingRuleType` column**.
+
+> **Schedule fields live ON the policy** — there is no separate schedule entity. `RunFrequency`
+> (`once` / `daily` / `weekly` / `monthly`), `ScheduledStart`, and `RunOnRefresh` are fields on
+> `DataMaskPolicy` (confirmed via Tooling describe), so scheduling folds into policy create/update.
+
+> **Row-subset ("sample") filtering lives ON `DataMaskPolicyObject`, NOT on the policy.** There is
+> **no `sampleSize` field** anywhere on `DataMaskPolicy`, and **no `LIMIT`** — Data Mask has no
+> row-cap concept. To mask only a subset, set `FilterEnabled = true` and a **selective** predicate
+> that genuinely matches fewer rows in `WhereCriteria` (a **40-char** SOQL-style predicate, e.g.
+> `LastName LIKE '%son%'`); `RawFilterData` holds the structured form the engine actually executes.
+> The masked count equals the number of rows the predicate matches. A `LIMIT` is **silently
+> ignored** (`LastName != 'X' LIMIT 20` masks the whole table — 407 rows — because the predicate is
+> always-true). Confirmed live. See `policy-authoring.md` → "Masking only a subset".
+> **`RawFilterData`'s `operation` must be one of** `eq`, `ne`, `lt`, `gt`, `ge`, `le`, `contains`,
+> `not_contains`, `in`, `not_in` — anything else (e.g. `startsWith`) fails the run with a `422`.
+> **The predicate must also be valid SOQL** — Data Mask runs a planning `SELECT count() ... WHERE
+> <predicate>`, so `Id != 'null'` fails the whole job (`invalid ID field: null`). Filter on a text
+> field like `LastName`, not `Id`.
+
+### What fails, and why
+
+```bash
+# WRONG — these are Tooling/MDAPI entities, not standard-data-API objects:
+sf sobject describe --sobject DataMaskPolicy --target-org <alias>          # -> NOT_FOUND
+sf data query --query "SELECT Id FROM DataMaskPolicy" --target-org <alias> # -> INVALID_TYPE
+
+# RIGHT — policy config via Tooling API:
+sf data query --use-tooling-api --target-org <alias> \
+  --query "SELECT Id, DeveloperName, MasterLabel FROM DataMaskPolicy"
+
+# RIGHT — job + job-detail via standard API:
+sf data query --target-org <alias> \
+  --query "SELECT Id, Status, Type, TotalRecords FROM DataMaskPolicyJobRun ORDER BY CreatedDate DESC LIMIT 5"
+sf data query --target-org <alias> \
+  --query "SELECT Id, DataMaskPolicyJobRunId, Status FROM DataMaskPolicyJobRunDtl WHERE DataMaskPolicyJobRunId = '<jobRunId>'"
+```
+
+## Status picklist values (`DataMaskPolicyJobRun.Status`)
+
+```text
+pending, scheduled, running, completed, completed_with_errors, failed, canceled
+```
+
+- **Mid-run (not terminal):** `pending`, `scheduled`, `running`
+- **Terminal (success/failure):** `completed`, `completed_with_errors`, `failed`
+- **Terminal after abort:** `canceled`  ← note the single "l"
+
+`DataMaskPolicyJobRun.Type` picklist: `auto`, `manual`, `scheduled`.
+
+Never report a mid-run value as the final status — poll until a terminal value appears.
+
+> **Case differs by surface.** These SOQL picklist values are **lowercase**. The run/abort REST
+> responses return the same states **UPPERCASE** (`RUNNING`, `CANCELED`). Poll for terminal state
+> against the lowercase SOQL value — do not compare it to the run-API response string.
+
+## Run / abort REST endpoints
+
+Base: `/services/data/v67.0/platform/data-resilience/data-mask`
+
+- Version must be **`v67.0` or later** (Core release 262, where these endpoints were added).
+- There is **no `/connect/` segment** — the path is `/services/data/v67.0/platform/...`. A `connect`
+  segment or a pre-v67 version returns `NOT_FOUND`. (This was the top failure mode — verified live.)
+- The id is bound as a **path segment**, not a body field.
+
+### Start a run
+```text
+POST /services/data/v67.0/platform/data-resilience/data-mask/policies/{policyId}/run
+```
+- Empty JSON body `{}` (`sf api request rest` requires `--body` on a POST; the API takes no payload).
+- **`200`** → accepted; response `{ jobRunId, policyId, status: "RUNNING", message: "Job started successfully" }` (status UPPERCASE).
+- `403` → org is production (Data Mask runs are sandbox-only; runtime sandbox guard).
+- `409`/`CONFLICT` → a run is already in progress for that policy.
+
+### Abort a run
+```text
+POST /services/data/v67.0/platform/data-resilience/data-mask/jobs/{jobRunId}/abort
+```
+- Empty JSON body `{}`.
+- **`200`** → abort accepted, response `status: "CANCELED"`, `message: "Job abort requested"` (async — confirm with a SOQL re-query).
+- `404` → unknown job run id.
+- `409` → job is not in a `running` state (already terminal or still `scheduled`).
+- After a successful abort, `DataMaskPolicyJobRun.Status` (SOQL, lowercase) becomes `canceled`.
+
+### Calling the run API from the CLI
+```bash
+# Write an empty JSON object to a file, then pass it with an @ prefix:
+printf '{}' > ./empty-body.json
+sf api request rest \
+  "/services/data/v67.0/platform/data-resilience/data-mask/policies/<policyId>/run" \
+  --method POST --body @./empty-body.json --target-org <alias>
+```
+`sf api request rest` handles auth/session automatically — no need to extract a token by hand.
+**A file body needs the `@` prefix** (`--body @./empty-body.json`) — without it the literal path
+string is sent as the body and the API returns `JSON_PARSER_ERROR`. The file just needs `{}`.
+If you must call it from Apex (`HttpRequest`), use `URL.getOrgDomainURL()` +
+`UserInfo.getSessionId()` for the base URL and bearer token.

package/skills/platform-datamask-run/references/policy-authoring.md

@@ -0,0 +1,185 @@
+# Authoring a DataMaskPolicy
+
+`DataMaskPolicy` is a **thin Metadata API shell**. Only three elements serialize into its
+metadata — `<label>`, `<description>`, `<runOnRefresh>`. Object and field membership is **NOT**
+part of the Metadata API shape (`DataMaskPolicy` has `childXmlNames: []` — there is no inline
+`<policyObjects>` / `<policyFields>`). Membership lives in two separate **Tooling API** entities,
+`DataMaskPolicyObject` and `DataMaskPolicyField`, which you insert as rows.
+
+Authoring a complete, runnable policy from scratch is therefore a **two-step** operation:
+
+1. **Metadata API deploy** the thin `DataMaskPolicy` shell. This is what creates the policy *with
+   an active revision* — the child rows in step 2 depend on it.
+2. **Tooling API insert** the `DataMaskPolicyObject` (one per target object) and its
+   `DataMaskPolicyField` rows (one per masked field).
+
+> **Order matters.** If you create the parent via the Tooling API instead of a Metadata deploy,
+> it has no active revision, and the child insert fails with
+> `INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY`. Always Metadata-deploy the shell first.
+
+Reuse an existing policy when one fits; author a new one only when needed.
+
+## Reuse first
+```bash
+sf data query --use-tooling-api --target-org <alias> \
+  --query "SELECT Id, DeveloperName, MasterLabel FROM DataMaskPolicy"
+```
+If a policy already targets the object/fields you need, use its `Id` and skip authoring.
+
+## Step 1 — Metadata-deploy the thin shell
+
+The `.dataMaskPolicy` metadata file carries ONLY these three elements. `<masterLabel>`,
+`<developerName>`, `<sampleSize>`, and any membership element are **rejected** — they are not part
+of the type. (There is **no `sampleSize` field anywhere** on `DataMaskPolicy` — to mask only a
+subset of records, use the row filter on `DataMaskPolicyObject`; see "Masking only a subset" below.)
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<DataMaskPolicy xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>Contact PII Mask</label>
+    <description>Masks core Contact PII in sandbox.</description>
+    <runOnRefresh>false</runOnRefresh>
+</DataMaskPolicy>
+```
+
+Deploy it in **mdapi (metadata) format** with a `package.xml`. `DataMaskPolicy` has **no
+source-format SDR registry entry**, so a `--source-dir` deploy fails with *"Could not infer a
+metadata type"*. Lay the file out as `dataMaskPolicies/Contact_PII_Mask.dataMaskPolicy` alongside
+a `package.xml`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>Contact_PII_Mask</members>
+        <name>DataMaskPolicy</name>
+    </types>
+    <version>67.0</version>
+</Package>
+```
+
+```bash
+sf project deploy start --metadata-dir <mdapi-dir> --target-org <alias>
+```
+
+The developer name of the created policy is the metadata member name (`Contact_PII_Mask`). Resolve
+its Id before step 2:
+```bash
+sf data query --use-tooling-api --target-org <alias> \
+  --query "SELECT Id FROM DataMaskPolicy WHERE DeveloperName = 'Contact_PII_Mask'"
+```
+
+## Step 2 — Tooling-insert the object + field membership
+
+Insert one `DataMaskPolicyObject` per target object, then one `DataMaskPolicyField` per masked
+field against that object's Id.
+
+```bash
+# One object row
+sf data create record --use-tooling-api --sobject DataMaskPolicyObject --target-org <alias> \
+  --values "ParentPolicyId=<policyId> ObjectReference=Contact FilterEnabled=false RunInSerialMode=false"
+# → returns the DataMaskPolicyObject Id, use it as <objectId> below
+
+# One field row per masked field
+sf data create record --use-tooling-api --sobject DataMaskPolicyField --target-org <alias> \
+  --values "ParentPolicyObjectId=<objectId> FieldReference=FirstName MaskingCategory=library MaskValue=first_name"
+```
+
+### Field treatment columns
+
+Each `DataMaskPolicyField` carries a `MaskingCategory` plus a `MaskValue` — there is **no
+`MaskingRuleType` column** (older docs claiming values like `RandomEmail` / `RandomPhoneNumber`
+were wrong; that column does not exist).
+
+- `MaskingCategory` — `library` (pick a value from the built-in library, the common case) or
+  `replaceRandom` (random replacement).
+- `MaskValue` — a snake_case library token identifying the value set. Verified tokens include:
+  `first_name`, `last_name`, `email`, `phone`, `street`, `city`, `state`, `postal_code`,
+  `country`, `account_name`, `URL`.
+
+## Choosing treatments
+
+Match the `MaskValue` to the field's semantics — do **not** apply one blanket replacement:
+
+| Field | MaskingCategory | MaskValue |
+|-------|-----------------|-----------|
+| FirstName | `library` | `first_name` |
+| LastName | `library` | `last_name` |
+| Email | `library` | `email` |
+| Phone / MobilePhone | `library` | `phone` |
+| MailingStreet | `library` | `street` |
+| MailingCity | `library` | `city` |
+| MailingState | `library` | `state` |
+| MailingPostalCode | `library` | `postal_code` |
+| MailingCountry | `library` | `country` |
+
+Do not mask system fields (`Id`, `CreatedDate`, `OwnerId`, etc.).
+
+## Editing membership
+
+To **add** a field, insert another `DataMaskPolicyField` row. To **remove** one, delete its row:
+```bash
+sf data delete record --use-tooling-api --sobject DataMaskPolicyField \
+  --record-id <fieldRowId> --target-org <alias>
+```
+The parent `DataMaskPolicy` shell does not need to be redeployed to change membership.
+
+## Masking only a subset of records (a "sample" run)
+
+There is **no `sampleSize`** on `DataMaskPolicy`, and **there is no `LIMIT`** — Data Mask has no
+row-cap concept. To process only a subset of an object's rows, you write a **selective `WHERE`
+predicate** that genuinely matches fewer rows, on the **`DataMaskPolicyObject`** row (not on the
+policy). The masked count equals however many rows satisfy that predicate — so the predicate itself
+*is* the subset. Three columns control it:
+
+| Column | Type | Purpose |
+|--------|------|---------|
+| `FilterEnabled` | boolean | `true` turns the row filter on (default `false` = mask the whole object) |
+| `WhereCriteria` | string, **max 40 chars** | A SOQL-style predicate — the human-readable form, e.g. `LastName LIKE '%son%'` |
+| `RawFilterData` | textarea (JSON) | The **structured** form the engine actually executes (see the op list below) |
+
+> **The engine masks exactly the rows the predicate matches — there is no `LIMIT`.** A `LIMIT`
+> clause in `WhereCriteria` is silently ignored: `LastName != 'X' LIMIT 20` masked **all 407**
+> Contacts, because `LastName != 'X'` matches every row and the `LIMIT` did nothing. To mask a
+> subset you must pick a predicate that is **actually selective** — e.g. `LastName LIKE '%son%'`
+> (25 rows) or `MailingState = 'NY'` (3 rows), verified with a `SELECT COUNT()` first. An
+> always-true predicate is **not** a subset.
+>
+> **`RawFilterData` is what runs — its `operation` must be one of the engine's supported ops:**
+> `eq`, `ne`, `lt`, `gt`, `ge`, `le`, `contains`, `not_contains`, `in`, `not_in`. Anything else
+> (e.g. `startsWith`) fails the run with a `422` `literal_error`. `LIKE '%son%'` maps to
+> `{"operation":"contains","value":"son"}`; `= 'NY'` maps to `{"operation":"eq","value":"NY"}`.
+> `WhereCriteria` and `RawFilterData` must express the **same** predicate.
+>
+> **The predicate must also be valid SOQL** (Data Mask runs a planning `SELECT count() FROM <object>
+> WHERE <predicate>` from it). **Do NOT filter on `Id`.** `Id != 'null'` fails with `invalid ID
+> field: null` / `INVALID_QUERY_FILTER_OPERATOR` and makes the whole **job fail** with 0 records
+> masked. Filter on a text field (`LastName`, `MailingState`, …), not `Id`.
+
+Set them when you insert (or update) the object row. Example — mask the Contacts whose last name
+contains `son` (a real subset; verify the count with `SELECT count() FROM Contact WHERE LastName
+LIKE '%son%'` first). `RawFilterData` mirrors it with `operation: contains`:
+```bash
+sf data create record --use-tooling-api --sobject DataMaskPolicyObject --target-org <alias> \
+  --values "ParentPolicyId=<policyId> ObjectReference=Contact RunInSerialMode=false \
+FilterEnabled=true WhereCriteria=\"LastName LIKE '%son%'\" \
+RawFilterData={\"type\":\"and\",\"filters\":[{\"type\":\"field_filter\",\"field\":\"LastName\",\"operation\":\"contains\",\"value\":\"son\"}]}"
+```
+To turn an existing object row into a subset run, update it instead:
+```bash
+sf data update record --use-tooling-api --sobject DataMaskPolicyObject --record-id <objectId> \
+  --target-org <alias> --values "FilterEnabled=true WhereCriteria=\"LastName LIKE '%son%'\" \
+RawFilterData={\"type\":\"and\",\"filters\":[{\"type\":\"field_filter\",\"field\":\"LastName\",\"operation\":\"contains\",\"value\":\"son\"}]}"
+```
+After the run, confirm the masked count in `DataMaskPolicyJobRunDtl` matches the predicate's row
+count and is **less than** `SELECT COUNT() FROM Contact` — proving it masked a subset, not the whole
+table. `WhereCriteria` is only **40 characters**, so keep the predicate short.
+
+## Verifying the policy after creation
+```bash
+# Confirm the object + field membership landed
+sf data query --use-tooling-api --target-org <alias> \
+  --query "SELECT Id, FieldReference, MaskingCategory, MaskValue FROM DataMaskPolicyField \
+           WHERE ParentPolicyObjectId = '<objectId>'"
+```
+Use the policy `Id` as `<policyId>` in the run/abort sequence (`run-and-abort.md`).

package/skills/platform-datamask-run/references/run-and-abort.md

@@ -0,0 +1,116 @@
+# Run / Poll / Report — and Cancel
+
+The operational commands for a Data Mask run. Assumes a policy already exists (see
+`policy-authoring.md` to create one) and the target org is a **sandbox**.
+
+These map to the two workflows in `SKILL.md`: **Workflow A (mask & report)** uses steps 0–4;
+**Workflow B (cancel a run)** uses steps 5–7 and is run only when the request is to abort/cancel.
+Pick one by the request — a mask-and-report task does not include a cancel.
+
+Throughout, `<alias>` is the target org, `<policyId>` the `DataMaskPolicy.Id`, `<jobRunId>` the id
+returned by the run-start call.
+
+## 0. Confirm sandbox + context
+```bash
+sf org display --target-org <alias> --json
+```
+Check `result.isSandbox === true`. Note `result.instanceUrl`. Data Mask run endpoints return `403`
+on production.
+
+## 1. Identify the policy
+```bash
+sf data query --use-tooling-api --target-org <alias> \
+  --query "SELECT Id, DeveloperName, MasterLabel FROM DataMaskPolicy"
+```
+Pick the policy that targets the PII you intend to mask (or create one — see `policy-authoring.md`).
+
+## 2. Start the run (REST run API)
+```bash
+printf '{}' > ./empty-body.json
+sf api request rest \
+  "/services/data/v67.0/platform/data-resilience/data-mask/policies/<policyId>/run" \
+  --method POST --body @./empty-body.json --target-org <alias>
+```
+`--body` must point at a file containing `{}` **with an `@` prefix** (`--body @./empty-body.json`) —
+`sf api request rest` requires a body on POST even though this endpoint takes no payload, and without
+the `@` the literal path string is sent as the body (→ `JSON_PARSER_ERROR`). Version must be **`v67.0`+** and there is **no `/connect/`
+segment** (either mistake returns `NOT_FOUND`). Sample response (HTTP **200**):
+```json
+{ "jobRunId": "1aG...", "policyId": "8dm...", "status": "RUNNING", "message": "Job started successfully" }
+```
+Capture `jobRunId`. A `409`/`CONFLICT` means a run is already active for this policy.
+
+> **Status case differs by surface.** The run API returns **UPPERCASE** status strings
+> (`RUNNING`, `CANCELED`), while the `DataMaskPolicyJobRun.Status` SOQL picklist is **lowercase**
+> (`running`, `canceled`). Poll for terminal state against the **SOQL** value (lowercase) — that is
+> what `scripts/poll-job.sh` checks. `DataMaskPolicy` Ids carry the `8dm` prefix.
+
+## 3. Poll to terminal
+```bash
+sf data query --target-org <alias> \
+  --query "SELECT Id, Status, Type, TotalRecords FROM DataMaskPolicyJobRun WHERE Id = '<jobRunId>'"
+```
+Repeat on a bounded interval until `Status` is one of `completed`, `completed_with_errors`,
+`failed`. `scheduled`/`running` are NOT terminal. `scripts/poll-job.sh` automates this with a
+timeout.
+
+## 4. Report from the detail object
+Per-object masked results live on the child, not the parent:
+```bash
+sf data query --target-org <alias> \
+  --query "SELECT Id, DataMaskPolicyJobRunId, Status FROM DataMaskPolicyJobRunDtl WHERE DataMaskPolicyJobRunId = '<jobRunId>'"
+```
+Report the concrete masked-record count and per-object success/failure from these rows. Do not
+report a number you did not read from here.
+
+## 5. Abort the currently-running job — ONLY when the user asked to cancel
+Steps 5–7 are the **abort** flow. Run them **only when the prompt explicitly asks to cancel/abort**
+a run — a "create and run" or "edit and run" task is complete after step 4.
+
+Aborting is an **on-demand action against a job that is already in progress**: take that job's
+`jobRunId` (and note its `DataMaskPolicyId` — you need it to start a replacement run if the window is
+missed), wait for `DataMaskPolicyJobRun.Status = running`, and go straight to the abort (step 6).
+You can only abort a running job. Do **not** use the terminal poll from step 3 here — it waits until
+the job is *done*. Use the poller's `running` mode, which returns the instant the job is abortable:
+```bash
+POLL_MODE=running bash scripts/poll-job.sh <alias> <jobRunId> 900 15
+```
+- Exit `0` (prints `running`) → abort now (step 6).
+- Exit `3` → the job reached a terminal state before `running` was caught; the window is gone. Start
+  a fresh run (step 2, using the policy Id you noted) and poll the new `jobRunId`.
+- Exit `1` (timeout) → re-query the job. If still non-terminal, re-run the poller once more; if
+  `running`, abort; if terminal, treat as exit 3 (fresh run + poll).
+
+**Only if no job is currently running** (the one you were watching already finished, or you're
+reproducing the run→abort flow end-to-end) start a fresh run (repeat step 2) to have a live job to
+cancel, poll (`POLL_MODE=running`) until `Status = running`, then abort — targeting that live run,
+never an older already-terminal one.
+
+## 6. Abort (REST run API)
+```bash
+sf api request rest \
+  "/services/data/v67.0/platform/data-resilience/data-mask/jobs/<jobRunId>/abort" \
+  --method POST --body @./empty-body.json --target-org <alias>
+```
+- `200` → accepted (response `status: "CANCELED"`, `message: "Job abort requested"`). `409` → not in `running` state.
+- Do **not** abort by deleting/updating the `DataMaskPolicyJobRun` row via DML — that is not a real
+  cancellation.
+
+## 7. Confirm the abort
+Cancellation is asynchronous. Re-query until the status settles:
+```bash
+sf data query --target-org <alias> \
+  --query "SELECT Id, Status FROM DataMaskPolicyJobRun WHERE Id = '<jobRunId>'"
+```
+Only report the abort as successful once `Status = canceled`.
+
+## Failure decision table
+
+| Symptom | Meaning | Action |
+|---------|---------|--------|
+| run-start `403` | Production org | Data Mask is sandbox-only; switch to a sandbox |
+| run-start `409` | Run already active | Poll the existing run or wait |
+| abort `409` | Job not `running` | Re-check status; may already be terminal or still `scheduled` |
+| abort `200`, SOQL status still `running` | Async cancel in flight | Keep polling until `canceled` |
+| run/abort `NOT_FOUND` | Wrong path — `/connect/` segment present or version < v67 | Use `/services/data/v67.0/platform/data-resilience/data-mask/...` (no `connect`) |
+| status stuck `scheduled` | Job hasn't picked up yet | Keep polling within the cap; not an error yet |

package/skills/platform-datamask-run/scripts/poll-job.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# poll-job.sh — poll a DataMaskPolicyJobRun, with a bounded timeout. Two modes:
+#   terminal (default) — wait until the job REACHES a terminal state (used by Workflow A, run→report)
+#   running            — wait until the job ENTERS the `running` state (used by Workflow B, abort)
+#
+# DataMaskPolicyJobRun is a STANDARD data-API object (unlike DataMaskPolicy, which is
+# Tooling/MDAPI), so plain `sf data query` works here.
+#
+# Usage:
+#   poll-job.sh <orgAlias> <jobRunId> [maxSeconds] [intervalSeconds]   # terminal mode (default)
+#   POLL_MODE=running poll-job.sh <orgAlias> <jobRunId> [maxSeconds] [intervalSeconds]
+# Defaults: maxSeconds=600, intervalSeconds=20
+#
+# WHY THESE DEFAULTS: Data Mask jobs run on a backend pool/scheduler with a ~5-10 minute floor —
+# even a tiny (20-row) job typically does not reach a terminal state or emit detail rows for several
+# minutes after the run starts. A short cap (e.g. 180s) gives up BEFORE the job can possibly finish,
+# so the default cap is 600s (10 min) with a 20s interval to keep the query volume low. Do NOT poll
+# on a tight (sub-10s) interval — it just burns tool calls against a job that cannot finish sooner.
+#
+# TERMINAL MODE: The parent DataMaskPolicyJobRun.Status can LAG the real job state (it may read
+# `pending`/`running` for a while after masking finished). So this poller ALSO checks
+# DataMaskPolicyJobRunDtl: once a `total_records_masked` detail row exists, the job is effectively
+# done and we stop, even if the parent status hasn't caught up. Ground truth is the detail rows.
+#
+# RUNNING MODE (for abort): exits the instant the parent status reads `running` — the only state in
+# which the abort endpoint accepts the request (a `pending`/`scheduled` job 409s). Because the pool
+# floor delays the `running` window by minutes, poll with a modest interval (e.g. 15s). If the job
+# races past `running` straight to a terminal state before we catch it, that window is gone and the
+# abort would be pointless — the poller reports the terminal status and exits 3 so the caller can
+# start a fresh run rather than abort a job that already finished.
+#
+# Exit codes:
+#   terminal mode: 0 = terminal status OR masked-count detail row observed (signal on stdout);
+#                  1 = timed out; 2 = bad args.
+#   running mode:  0 = `running` observed (prints `running`); 1 = timed out; 2 = bad args;
+#                  3 = job reached a terminal state before `running` was seen (prints that status).
+
+set -euo pipefail
+
+ORG="${1:-}"
+JOB_ID="${2:-}"
+MAX_SECONDS="${3:-600}"
+INTERVAL="${4:-20}"
+POLL_MODE="${POLL_MODE:-terminal}"
+
+if [[ -z "$ORG" || -z "$JOB_ID" ]]; then
+  echo "usage: [POLL_MODE=running] poll-job.sh <orgAlias> <jobRunId> [maxSeconds] [intervalSeconds]" >&2
+  exit 2
+fi
+
+case "$POLL_MODE" in
+  terminal|running) ;;
+  *) echo "poll-job: POLL_MODE must be 'terminal' or 'running' (got '${POLL_MODE}')" >&2; exit 2 ;;
+esac
+
+# Terminal statuses (incl. canceled after an abort). scheduled/running/pending are NOT terminal.
+is_terminal() {
+  case "$1" in
+    completed|completed_with_errors|failed|canceled) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+elapsed=0
+while (( elapsed < MAX_SECONDS )); do
+  status="$(
+    sf data query --target-org "$ORG" \
+      --query "SELECT Status FROM DataMaskPolicyJobRun WHERE Id = '${JOB_ID}'" \
+      --json 2>/dev/null \
+    | python3 -c "import json,sys; r=json.load(sys.stdin).get('result',{}).get('records',[]); print(r[0]['Status'] if r else 'UNKNOWN')"
+  )"
+  echo "[poll-job] ${JOB_ID} status=${status} (${elapsed}s/${MAX_SECONDS}s) mode=${POLL_MODE}"
+
+  if [[ "$POLL_MODE" == "running" ]]; then
+    # Abort window: stop the instant the job is `running` (the only abortable state).
+    if [[ "$status" == "running" ]]; then
+      echo "running"
+      exit 0
+    fi
+    # If it slipped past `running` to a terminal state, the abort window is gone — signal the caller.
+    if is_terminal "$status"; then
+      echo "[poll-job] job reached terminal '${status}' before 'running' was observed — abort window missed" >&2
+      echo "$status"
+      exit 3
+    fi
+  else
+    if is_terminal "$status"; then
+      echo "$status"
+      exit 0
+    fi
+
+    # Ground-truth check: a masked-count detail row means the job finished even if the parent lags.
+    masked="$(
+      sf data query --target-org "$ORG" \
+        --query "SELECT Value FROM DataMaskPolicyJobRunDtl WHERE DataMaskPolicyJobRunId = '${JOB_ID}' AND Subtype = 'total_records_masked'" \
+        --json 2>/dev/null \
+      | python3 -c "import json,sys; r=json.load(sys.stdin).get('result',{}).get('records',[]); print(r[0]['Value'] if r else '')"
+    )"
+    if [[ -n "$masked" ]]; then
+      echo "[poll-job] detail row total_records_masked=${masked} — job effectively complete (parent status=${status})"
+      echo "completed"
+      exit 0
+    fi
+  fi
+
+  sleep "$INTERVAL"
+  elapsed=$(( elapsed + INTERVAL ))
+done
+
+if [[ "$POLL_MODE" == "running" ]]; then
+  echo "[poll-job] TIMEOUT after ${MAX_SECONDS}s — job never reached 'running'" >&2
+else
+  echo "[poll-job] TIMEOUT after ${MAX_SECONDS}s — neither terminal status nor masked-count detail row observed" >&2
+fi
+exit 1

package/skills/platform-dataspace-access-configure/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: platform-dataspace-access-configure
-description: "Use this skill to configure Salesforce Data Cloud DataSpace access for permission sets. Grants dataspace-level access via MDAPI PermissionSet XML with dataspaceScopes elements, and optionally grants object-level access to specific DMO, DLO, or CIO objects via the Object Access Grants Connect API. TRIGGER when: user needs to create or update a permission set that includes DataSpace access, grant a permission set access to a specific dataspace, configure dataAccessLevel or objectAccessLevel for a dataspace scope, add RBAC object access grants for Data Cloud objects, or list or remove object access grants for a permission set and DataSpace pair. DO NOT TRIGGER when: the task is a generic permission set without any dataspace access (use platform-permission-set-generate), the request is about data ingestion or streams (use data360-prepare), or the work involves creating dataspaces themselves rather than granting access to them."
+description: "Use this skill to configure or inspect Salesforce Data Cloud DataSpace access for permission sets. Grants dataspace-level access via MDAPI PermissionSet XML with dataspaceScopes elements, optionally grants object-level access to DMO, DLO, or CIO objects via the Object Access Grants Connect API, and inspects existing scopes via read-only PermissionSet metadata retrieval. TRIGGER when: user needs to create or update a permission set with DataSpace access, grant access to a specific dataspace, list permission sets with access to a DataSpace, configure dataAccessLevel/objectAccessLevel, add RBAC object access grants, or list/remove object access grants for a permission set + DataSpace pair. DO NOT TRIGGER when: the task is a generic permission set without dataspace access (use platform-permission-set-generate), the request is about data ingestion/streams (use data360-prepare), or the work involves creating dataspaces themselves rather than granting access to them."
 metadata:
   version: "1.0"
   domains: ["Platform", "Data 360"]
@@ -8,6 +8,8 @@ metadata:
   cliTools:
     - tool: ["jq"]
       semver: ">=1.6.0"
+    - tool: ["python3"]
+      semver: ">=3.6"
     - tool: ["sf"]
       semver: ">=2.0.0"
 ---
@@ -32,6 +34,7 @@ Pick exactly one case from the table below before writing any files. Each case h
 | **A. Create new permset with DS access** | "create a permission set called X with dataspace scope Y" | does NOT exist yet | `permissionsets/<Name>.permissionset-meta.xml` **and** `package.xml` |
 | **B. Add DS access to existing permset** | "grant existing permission set X access to dataspace Y" | already deployed (may contain other permissions) | patched `permissionsets/<Name>.permissionset-meta.xml` **and** `package.xml` — see Case B workflow below |
 | **C. Object-level grant only** | "grant permset X access to object Z (in dataspace Y)" — permset + scope already configured | already deployed with `dataspaceScopes` | `api-request.json` (Connect API body). NO permission set XML, NO `package.xml` |
+| **D. Inspect existing DS access** | "which permission sets have access to dataspace Y?" | any | chat/report only. NO deployable files, NO runtime API mutation |
 
 Only emit the files listed for the case you picked. Emitting Case A/B files for a Case C prompt (or vice versa) is a correctness failure — extra files change the deployment shape.
 
@@ -44,7 +47,7 @@ Only emit the files listed for the case you picked. Emitting Case A/B files for
    sf project retrieve start --metadata PermissionSet:<Name> --target-org <alias>
    ```
 2. Open the retrieved `permissionsets/<Name>.permissionset-meta.xml`. Keep every element already there.
-3. Insert the `<dataspaceScopes>` block for the target DataSpace (element order in the file does not matter for MDAPI). If the file already has a `<dataspaceScopes>` block **for this same DataSpace**, replace only that block. Leave every `<dataspaceScopes>` block for other DataSpaces untouched — one block per DataSpace, and removing a block revokes that DataSpace grant.
+3. Insert the `<dataspaceScopes>` block for the target DataSpace (element order in the file does not matter for MDAPI). If the file already has a `<dataspaceScopes>` block **for this same DataSpace**, replace only that block. Leave every `<dataspaceScopes>` block for other DataSpaces untouched — one block per DataSpace. For a requested scope removal, remove only the matching block and deploy; omitting the block revokes that DataSpace grant. Verify by retrieving the PermissionSet and confirming the matching `<dataspaceScopes>` block is absent.
 4. Write `package.xml` listing the permset in `<members>`.
 5. Redeploy with `sf project deploy start`.
 
@@ -56,6 +59,7 @@ Trigger this skill when the user wants to:
 - Create a permission set that grants access to a Data Cloud DataSpace
 - Add or modify `dataspaceScopes` on an existing permission set
 - Grant a permission set access to specific DMO / DLO / CIO objects in a DataSpace
+- List which permission sets have a DataSpace scope and inspect its access levels
 - Configure `dataAccessLevel` and `objectAccessLevel` for a DataSpace scope
 - List or remove object access grants for a permission set + DataSpace pair
 
@@ -131,6 +135,50 @@ sf project deploy start --source-dir force-app/main/default/permissionsets/ --ta
 
 ---
 
+## Read-Only DataSpace Scope Inspection — Case D
+
+Use Case D when the user asks which permission sets have access to a DataSpace,
+or asks to inspect `dataAccessLevel` and `objectAccessLevel` without making a
+change.
+
+**Never query `DataspaceScope` or `DataspaceScopeAccess` with SOQL.** Those
+objects are not a supported query surface for this relationship. Do not try
+SOQL as discovery, fallback, or troubleshooting.
+
+1. Retrieve PermissionSet metadata into an isolated temporary local project and
+   output directory. Do not retrieve into the user's existing metadata tree. Save
+   the skill repository path first (as an absolute path if possible):
+   ```bash
+   REPO_ROOT="<absolute/path/to/sf-skills-internal>"  # or $(pwd) if you're in the repo root
+   WORK_DIR=$(mktemp -d)
+   sf project generate --name dataspace-scope-inspection --output-dir "$WORK_DIR"
+   cd "$WORK_DIR/dataspace-scope-inspection"
+    sf project retrieve start --json \
+      --metadata "PermissionSet:*" --target-org <alias> \
+      --output-dir "$WORK_DIR/retrieved"
+    ```
+    Inspect the JSON result before continuing. A nonzero command status, a failed
+    `result.status`, warnings, or an unexpectedly low `result.fileProperties`
+    count means the retrieve may be incomplete. Report that limitation rather
+    than treating the result as empty, and do not fall back to SOQL.
+2. Run the inspection script from the skill directory (do not rely on relative paths
+   after `cd` changed the working directory). Supply the retrieved directory and optional DataSpace name:
+   ```bash
+   "$REPO_ROOT/skills/platform-dataspace-access-configure/scripts/inspect-dataspace-scopes.sh" \
+     "$WORK_DIR/retrieved" "<DataSpace API name, if given>"
+   ```
+   Report the output to the user, one result per line.
+
+Case D is read-only with respect to the org. Do not deploy metadata, assign a
+permission set, execute Apex, perform record DML, or make a POST, PUT, PATCH, or
+DELETE request. Do not generate `package.xml`, PermissionSet XML, or
+`api-request.json` in the user's workspace as part of inspection. Remove the
+temporary work directory after reporting: `rm -rf "$WORK_DIR"`. The scope-level
+`objectAccessLevel` is not an inventory of explicit object grants; inspect those
+separately with the read-only object-access-grants endpoint only when requested.
+
+---
+
 ## Layer 2 — Object-Level Access (Connect API) — Case C
 
 Only needed when `objectAccessLevel` is not `BY_POLICY`, or when governance policies do not cover the target objects. Grants are runtime — **no MDAPI deploy, no `package.xml`, no permission set XML**. The only artifact for a Case C task is a single `api-request.json` describing the Connect API call.
@@ -304,7 +352,7 @@ sf org api rest --target-org <alias> \
 | Prefer `BY_POLICY` when data governance policies exist | Delegates row/column filtering to central policy — no per-object grants needed |
 | One `<dataspaceScopes>` block per DataSpace | Repeat the block for multiple DataSpaces on the same permission set |
 | Org must have Data Cloud provisioned to deploy `<dataspaceScopes>` | On non-Data-Cloud orgs, the element is ignored or rejected |
-| Do not query `DataspaceScope` / `DataspaceScopeAccess` via SOQL | Not queryable; use MDAPI retrieve to inspect existing grants |
+| Do not query `DataspaceScope` / `DataspaceScopeAccess` via SOQL | Not queryable; use Case D PermissionSet Metadata API retrieval to inspect existing scopes. Never use SOQL as a fallback. |
 
 ---