doca-structured-tools-contract

# DOCA structured-tools contract **Where to start:** Reach for this skill whenever a workflow says *"prefer the structured tool per `doca-structured-tools-contract`"*. Read [`## The agent behavior contract`](#the-agent-behavior-contract) first, then the matching schema in [`## Schemas`](#schemas). If the host has the structured tool, prefer its output; if not, fall back to the manual chain in the same section and **always report which path was taken**. **Scope boundary.** Writing library code is not a structured-tools question: name the library skill and stop. Checking a spec before commit IS in scope: apply the validate-before-commit schema. ## Example questions this skill answers well See [`references/examples.md`](references/examples.md). ## When to load this skill Load this skill whenever another skill's workflow says *prefer the structured tool*, OR the user wants a one-shot answer consolidating multiple manual commands. Concretely: - A per-artifact skill's Command appendix references this skill. - The user asks "is there one command that tells me X about my DOCA install". - The user asks "how do I know X is valid before I commit" for a library with a validate-before-commit call. - The agent computed the manual answer and wants to surface the structured-tool one-liner for next time. Do **not** load for general DOCA orientation, library API questions, or install-from-scratch guidance — use the matching library skill + `doca-public-knowledge-map` + `doca-setup`. Running probes and fallbacks requires shell access to the target host, directly or via user-run commands. ## Ground rules for any agent using this skill 1. **Detect first; never assume the tool is present.** Each schema names the *probe command* deciding whether the tool is installed; run it before treating schema output as authoritative. 2. **Prefer structured when present; fall back to manual when not.** When the probe succeeds and output validates against the selected schema, the structured JSON is the source of truth. When the probe fails or output is invalid, walk the manual chain and synthesize the equivalent answer. 3. **Report which path you took.** Open the answer with *"using structured `<helper>` (path: `<path>`)"* OR *"falling back to manual chain (structured `<helper>` probe failed: `<reason>`)"*, substituting the schema-selected helper and the actual probe failure; never report a different helper than selected. 4. **Schemas are locked here; per-skill overlays are NOT.** A per-artifact skill MAY add a Command-appendix row that *uses* a schema; it MUST NOT redefine it. Schema growth happens here; consuming appendixes inherit it. 5. **Never invent a JSON field not in the schema.** Extra fields in pasted JSON are advisory; quote the schema as the boundary. 6. **Schemas describe contracts, not implementations.** The executables satisfying them are deferred to a subsequent PR; this skill exists so other skills can be *infra-aware* before they ship. So **no helper named here is installed anywhere today** — never present one as available or send the user to install it. Probe, report absent in one line, then answer from the manual fallback. 7. **Privilege is never implicit.** A fallback command requiring `sudo` is emitted for the user to run or executed only through an approved privileged channel — never silently elevate because the helper was absent. If none exists, ask the user to run it or report the gap. ## The agent behavior contract A four-step loop run every time a Command appendix references this contract: 1. **Detect.** Run the schema's probe command. Examples: `command -v doca-env`, `test -f /opt/mellanox/doca/share/version-matrix.json`, `command -v doca-capability-snapshot`. Probes are read-only and safe. Helpers are deferred to PR2, so failed probes are expected. 2. **Prefer.** If the probe succeeds, invoke the structured tool and parse its JSON per the schema in [`## Schemas`](#schemas). It is authoritative only when parsing succeeds and every required field has the documented type. Malformed JSON, missing fields, or type mismatches fail the structured path: report that failure and use step 3. Ignore extra fields as advisory (rule 5). Do NOT run the manual chain "to double check" valid structured output — it replaces the chain. 3. **Fall back.** If the probe fails, walk the manual chain in the same schema section, combining outputs in the listed order. If a manual command is unavailable, surface the gap and route to the matching skill (typically `doca-setup`). If that cannot resolve it, name the missing commands, state the answer cannot be completed, and stop rather than presenting partial data as complete. 4. **Report.** Open the answer with one of: - *"Using structured `<tool>` (path: `<path>`)."* — probe succeeded and output validated. - *"Falling back to manual chain (structured `<tool>` probe failed: `<reason>`)."* — probe failed. Include the probe command and reason; for `command -v`, failure means not on `PATH`, not definitively absent. Do not suggest installing it (rule 6). - *"Falling back to manual chain (`<tool>` output failed schema validation: `<reason>`)."* — the helper exists but its output is malformed, missing required fields, or invalid types. The report step proves the agent tried the helper first. ## Schemas Select the schema from the question shape: env/install state uses `doca-env`; capability minimum-version lookup uses `version-matrix`; per-device library capabilities use `capability-snapshot`; spec validation uses `validate-before-commit`; host-vs-DPU comparison uses the two collect-state schemas. When a per-skill Command appendix names a schema, use it directly. Each subsection names ONE structured tool, its probe, its top-level JSON shape, and the manual chain walked when the probe fails. ### doca-env --json schema **Detection probe:** `command -v doca-env` (same `$PATH` location as `doca_caps` when installed). **Top-level shape (JSON object):** | Field | Type | Notes | | --- | --- | --- | | `version` | object | `pkg_config` / `applications_version` / `doca_caps` / `bfb` (string\|null) / `consistent` (bool) | | `devices` | array of object | per visible PCIe function: `pcie_address` (e.g. `0000:03:00.0`), `kind` (`PF`\|`VF`\|`SF`), `name`, `representor_of` (string\|null), `state` (`active`\|`down`\|`unknown`), `mtu` (number) | | `libraries` | array of object | one per public DOCA library: `pkg_config_name`, `installed` (bool), `pc_path` (string\|null) | | `sample_paths` | array of object | one per library: `library`, `path` (on-disk samples root) | | `drivers` | object | `mlx5_core_loaded` (bool), `mlx5_ib_loaded` (bool), `kernel_version` (string) | | `hugepages` | object | `available_2m` (number), `available_1g` (number), `mount_point` (string\|null) | | `host_kind` | string | `host` \| `bluefield` \| `unknown` | | `bf_mode` | string \| null | `smartnic` \| `dpu` \| `switch` \| `null` (when `host_kind != bluefield`) | **Manual fallback chain** (in order; combine outputs to synthesize the same answer): 1. `pkg-config --modversion doca-common` → `version.pkg_config` 2. `cat /opt/mellanox/doca/applications/VERSION` → `version.applications_version` 3. `doca_caps --version` → `version.doca_caps` 4. `doca_caps --list-devs` → `devices` array (PCIe address + kind + representor) 5. Find `doca-common.pc` first: if `find /opt/mellanox/doca -name doca-common.pc -print -quit` is empty, stop, surface the partial-install gap, and route to `doca-setup`; never expand an empty glob. Otherwise set `PCDIR` to its directory and run `for pc in "$PCDIR"/*.pc; do pkg-config --exists "$(basename "$pc" .pc)" && echo "$pc"; done` → `libraries` array. If `PCDIR` is not a directory or no module resolves, surface the gap and route to `doca-setup`. `PCDIR` is commonly `/opt/mellanox/doca/lib/<arch>-linux-gnu/pkgconfig` on DOCA 3.3+, or `/opt/mellanox/doca/infrastructure/lib/pkgconfig` on legacy / split-profile installs. 6. `ls /opt/mellanox/doca/samples/` → `sample_paths` array 7. `lsmod | grep -E '^mlx5_(core|ib)'` + `uname -r` → `drivers` object 8. `cat /proc/meminfo | grep -i Huge` → `hugepages` object 9. `dmidecode -s system-product-name` (or `cat /proc/device-tree/model` on BlueField) → `host_kind` 10. `mlxconfig -d <pcie> q INTERNAL_CPU_MODEL` → `bf_mode` (when `host_kind == bluefield`) ### version-matrix.json schema **Detection probe:** `test -f /opt/mellanox/doca/share/version-matrix.json`. **Top-level shape (JSON object):** | Field | Type | Notes | | --- | --- | --- | | `schema_version` | string | semver of THIS contract; bumps on schema changes | | `generated_at` | string | ISO-8601 generation timestamp | | `entries` | array of object | one row per (library, capability) pair | **Per-entry shape:** | Field | Type | Notes | | --- | --- | --- | | `library` | string | `pkg-config` module name (`doca-flow`, `doca-rdma`, `doca-comch`, …) | | `capability` | string | machine-readable cap name; the per-library Command appendix lists which `doca_<lib>_cap_*` query it maps to | | `display_name` | string | human-readable label; quoted when reporting | | `min_doca_version` | string | first DOCA release in which the capability was available (semver) | | `max_doca_version` | string \| null | last release it was available in (null = still available) | | `source_url` | string | the public docs URL the row was derived from | | `source_quote` | string | the exact public-docs prose that established the row | **Manual fallback chain:** 1. Identify the library + capability via the matching skill's CAPABILITIES.md table. 2. Fetch its per-library doc page via `doca-public-knowledge-map`. 3. Search it for the capability name; extract and quote the *"available since"* prose verbatim. 4. Cross-check `pkg-config --modversion doca-<library>` on the user's host; if it is older than the *"available since"* line, the capability is not on this install regardless of the docs. ### capability-snapshot schema **Detection probe:** `command -v doca-capability-snapshot` (same `$PATH` as `doca_caps` when installed). **Top-level shape (JSON object):** | Field | Type | Notes | | --- | --- | --- | | `snapshot_at` | string | ISO-8601 timestamp | | `doca_version` | string | `doca_caps --version` at snapshot time | | `host_kind` | string | `host` \| `bluefield` | | `devices` | array of object | one per `doca_devinfo`: `pcie_address`, `library_capabilities` (map of library → capability flags) | **Manual fallback chain:** 1. `doca_caps --list-devs` → device enumeration 2. Per-device detail: `doca_caps --pci-addr <bdf>` (side-effect free; see `doca-caps`). Only if a capability it does not print is required, use the library's own `## test` workflow from its shipped sample; never write new test code for a snapshot. ### validate-before-commit schema **Detection probe:** `command -v doca-validate`. A library-specific constructor-time validation surface is not a detection probe and may mutate state. The public Flow header ships no `doca_flow_pipe_validate` symbol: never invent one, and never use `doca_flow_pipe_create` to test for the helper. **Top-level shape (JSON object):** | Field | Type | Notes | | --- | --- | --- | | `library` | string | which DOCA library the spec is for | | `spec_path` | string | on-disk path to the spec being validated | | `result` | string | `pass` \| `fail` \| `skip` | | `checks` | array of object | per-check: `name`, `status` (`pass` \| `fail` \| `skip`), `details`, `remediation` (string \| null) | **Manual fallback chain:** 1. Find the library-specific validate surface in the matching skill's `## test` workflow. For some libs this is a dedicated `_validate` call; constructor-time checks inside a mutating `_create` are not read-only validators. In particular, `doca_flow_pipe_create` belongs to `doca-flow TASKS.md ## test` after its preconditions; never invoke it as a pre-commit probe. If the caller requires read-only validation and the API exposes no dedicated validator, report `result: skip`, route to the per-library `## test` workflow, and stop (skip steps 2 and 3). 2. Invoke that read-only validator (never a mutating `_create`) before any commit / create / submit call. 3. Map outcomes deliberately: `DOCA_ERROR_INVALID_VALUE` and `DOCA_ERROR_NOT_SUPPORTED` are `result: fail`; permission, transport, unavailable-device, and other operational errors are `result: skip`, with the `doca_error_get_descr()` text and remediation in a `checks` entry. Never turn an inability to run validation into a spec failure. ### collect-host-state and collect-dpu-state schemas Select the helper for the side where commands execute: host uses `doca-collect-host-state`; BlueField uses `doca-collect-dpu-state`. Both being present does not imply cross-side access; for a diff, collect independently on each side and compare. **Detection probes:** `command -v doca-collect-host-state` (host) / `command -v doca-collect-dpu-state` (BlueField). **Top-level shape (JSON object), shared by both:** | `side` | string | `host` \| `dpu` | | `doca_version` | string | `doca_caps --version` | | `firmware_version` | string | `flint -d <pcie> q` output (sudo) | | `kernel_version` | string | `uname -r` | | `mlx5_modules` | array of string | loaded `mlx5_*` modules | | `bf_mode` | string \| null | `smartnic` \| `dpu` \| `switch` \| null | | `devices` | array of object | per-PCIe-function: `pcie_address`, `kind` (`PF` \| `VF` \| `SF`), `state`, `mtu`, `representor_of` | **Manual fallback chain (per side):** 1. `doca_caps --version` → `doca_version` 2. `uname -r` → `kernel_version` 3. `lsmod | grep mlx5` → `mlx5_modules`