# Purposeful operation results

**AIM 3.3.0rc8. Publisher `aim_output_v1`; public `aim_operation_result_v1`.**
This is independent of `play_task_host_v1` progress and `target_outcome_summary_v1`.
The service, wire and event versions remain 1.0. It is not a raw-output/debug option.

## Capability and catalog negotiation

`capabilities.operation_results` advertises publisher/result protocols, scopes, modes,
limits and qualification. Each catalog operation has `result: null` or a declaration:

```yaml
result:
  protocol: aim_output_v1
  schema: host_capabilities_v1
  scope: per_host
  required: true
  sensitivity: safe
  max_bytes_per_host: 1048576
  schema_file: host_capabilities_v1.yml
```

`schema_file` is a basename under the catalog's `schemas/` directory. Core resolves it
into `data_schema` for public `list_playbooks` and `PreparedRun.result_contract` output.
Clients never pass a schema file or payload in an execute request. Schema/source bytes
participate in the review revision. A changed schema requires preparation/review again.
No hard-coded playbook dispatch exists in Core.

## Publisher convention

```yaml
- name: AIM | Publish operation result
  ansible.builtin.set_stats:
    per_host: true
    aggregate: false
    data:
      aim_output:
        protocol: aim_output_v1
        schema: host_capabilities_v1
        data:
          is_dc: '{{ is_dc | default(false) | bool }}'
          is_dhcp_server: '{{ is_dhcp_server | default(false) | bool }}'
          is_hyperv_host: '{{ is_hyperv_host | default(false) | bool }}'
          has_veeam_vbr: '{{ has_veeam_vbr | default(false) | bool }}'
          has_veeam_vbo: '{{ has_veeam_vbo | default(false) | bool }}'
          has_veeam_em: '{{ has_veeam_em | default(false) | bool }}'
          is_unifi_controller: '{{ is_unifi_controller | default(false) | bool }}'
          is_unifi_os_server: '{{ is_unifi_os_server | default(false) | bool }}'
```

Use exactly one publication per requested host/run. Do not loop publishers, publish
preliminary values under the same key, or aggregate dictionaries accidentally. For a
global declaration use `per_host: false` and exactly one global publication (beware
run_once with serial batches). The bundled schemas are all per-host.

The callback observes only an actual set_stats result with a matching declaration,
false aggregation and matching scope. It records sensitivity provenance and reconciles
that value with final custom statistics. An unrelated custom stat, a debug task named
"Publish", or a forged final statistic is not an output source. `no_log` publishers
are withheld; custom stats alone cannot erase their provenance. Report from a reviewed
normalizer with selected non-secret fields, not arbitrary registered result dictionaries.

Publishing set_stats is controller-side and adds no remote package/module dependency.
Native console rendering remains unchanged; use the existing debug summaries for CLI
operators. External clients obtain reports only at finalization, not through debug text.

## Final public object

Every RunResult adds `operation_result`, null for an undeclared operation. Otherwise:

```json
{
  "protocol": "aim_operation_result_v1",
  "schema": "host_capabilities_v1",
  "scope": "per_host",
  "required": true,
  "complete": true,
  "check_mode": false,
  "hosts": {
    "host01.example": {
      "schema": "host_capabilities_v1",
      "status": "available",
      "data": {"is_dc": false, "is_dhcp_server": false, "is_hyperv_host": false,
        "has_veeam_vbr": false, "has_veeam_vbo": false, "has_veeam_em": false,
        "is_unifi_controller": false, "is_unifi_os_server": false},
      "error": null
    }
  },
  "global": null
}
```

For global scope, `hosts` is empty and `global` holds the same entry shape. Schema and
scope come from the catalog, not client input. Host keys come from reviewed targets.
The existing final result event contains the same object as the final response. There
is no separate live operation-data event; read final authoritative results in either
summary or detail mode.

Entry status:

| Status | Meaning |
|---|---|
| available | Complete final data received, schema/limit/safety validation passed |
| missing | Final accounting arrived but this report slot was not published |
| withheld | Sensitive publisher or known supplied secret matched output |
| invalid | Schema, provenance or size validation rejected the publication |
| not_started | Execution did not start; there is no operation data |
| indeterminate | Work may have started but no complete final report stream exists |

Unavailable entries have `data: null`; never replace them with `{}`/zero/false in a UI.
`complete` describes report availability, not execution success or payload-specific
completeness. A patch report has its own `data.complete` for update evidence. A failed
service-start operation can have an available, complete report listing failed services.

If native exit is nonzero, preserve the native/Core failure and retain any valid reports
from the final stats. If native execution exits 0 but required output is missing,
withheld, invalid or incomplete, Core returns failed/result_validation with native
exit_code 0. Native target outcomes still describe their Ansible stats. This is an
intentional additional report-contract check, not a redefinition of native stats.
Optional missing reports do not fail an otherwise successful run; invalid submitted
reports do. Never replay automatically after result-validation failure.

## Generic schema subset and safety

The schema validator is standard-library-only, shared by callback and Core. Supported
JSON Schema keywords: `type` (including nullable type arrays), `properties`, `required`,
boolean `additionalProperties`, `items`, `enum`, `maxItems`, `maxLength`, `minimum`,
`maximum`, and documentation `description`. `$ref`, arbitrary validators and executable
schema extensions are not supported. Objects are closed unless explicitly declared open.
The only shipped open subtree is already parsed/redacted Checkmk `sections`.

Limits: maximum depth 20, 200,000 nodes per value, 20,000 items per collection, 8,192
characters per string, 1 MiB encoded envelope per host/global slot and 16 MiB per run.
Catalogs can lower the per-host byte cap. Data is chunked privately into <=2,048-byte
pieces; malformed sequences, duplicate publications, torn frames and oversize data are
rejected, never silently truncated. NaN/Infinity, binary objects, cycles and unknown
closed-object properties are rejected. Schemas and output labels must be static public
controller source.

Obvious secret field names are disallowed in schemas; redacted dynamic config keys
can only hold the exact `[REDACTED]` marker. Known supplied credentials matching public
strings are withheld again at the Core boundary. These measures are defense in depth,
not a general secret scanner. Config/other strings literally containing an undisclosed
secret remain an author/operator responsibility. Never publish environments, invocation,
exception objects, arbitrary debug values, commands or private keys.

`checkmk_user_config_v1` preserves parsed sections but redacts recognized password/token/
passphrase/credential/community fields, command/argument/environment bodies, MRPE
commands, URL credentials and obvious inline secrets. `redacted_paths` explains what
was withheld. Comments/formatting are not YAML data. The operation may read only basename
`check_mk.user.yml`, <=512 KiB, from a trusted configured path. It never modifies the file.
Unknown settings remain visible unless filtered; do not advertise this as guaranteed
secret-free content. No general arbitrary-file reader is added.

## Current schemas and exact semantic boundaries

Normative field shapes: `playbooks/schemas/<schema>.yml` (also in catalog metadata).

| Schema | Data meaning |
|---|---|
| host_capabilities_v1 | Eight booleans, source detection facts; no inventory membership edits |
| filesystem_usage_v1 | Selected operational mounts/volumes; byte quantities and nullable observations; Windows uses attached storage volumes from community.windows.win_disk_facts and excludes mapped/network drives |
| event_log_export_v1 | Channel names, age and target file paths; no log contents or controller download; check mode has no exported paths |
| service_start_summary_v1 | Before stopped services, policy eligibility, attempts, exclusions, actual after observations and fixed per-attempt failures |
| patch_summary_v1 | Per-package net version-set changes on Debian/RedHat, or Windows update IDs/titles/KBs with installed flags; never arbitrary manager dictionaries |
| managed_cleanup_preview_v1 | Managed filename candidates and observed deletions; no unknown-file purge |
| checkmk_user_config_v1 | Parsed/redacted sections and file metadata, not raw YAML/debug output |
| checkmk_agent_state_v1 | Installed status/version from registry/package query, actual service states, package/config/check changes |
| checkmk_agent_config_v1 | Named section/config/check change actions; no raw before/after values or file diffs |

### Services

`initially_stopped` is the observation before action. `eligible` applies auto/delayed-start
and configured include/exclude policy. `attempted` excludes skipped and check-mode actions.
`newly_running` is the observed stopped-to-started transition, including a concurrent
external start; `started_count` counts only attempted services now running. It is not
proof that the start return alone kept a service alive. `still_stopped` includes excluded
services; `unobserved` means missing after observations. Non-running attempted services
appear in `failed_to_start` with name, fixed reason/message and nullable numeric native
code. Failed reasons include dependency_failed, permission_denied, service_disabled,
start_timeout, service_not_found, logon_failed, start_failed, not_running_after_start and
state_unavailable. Localized unrecognized errors use generic start_failed; no raw text.
An unavailable post-query fails the run instead of inventing a successful observation.

### Packages and Checkmk

Linux queries native package databases before/after the update/reboot policy, preserving
architecture and parallel installed version sets. `updates` lists updated/installed/
removed rows and separate counters. Old/new arrays are empty where the package did not
exist. Snapshots cannot identify an intermediate reinstall with unchanged final versions
or attribute concurrent external package changes; do not run another package manager
concurrently. Check mode reports no completed changes, not predicted upgrade versions.
No silently shortened list: exceeding limits becomes explicit validation failure.

Windows reports native updates marked installed, pending/failed records and numeric
failure codes. A mismatch between native installed count and detailed records marks
`data.complete: false`, rather than fabricating records. Supported scope remains Windows
Update under configured categories, not every third-party package installer. Reboot
facts retain their observed meaning; check mode never claims a performed reboot.

Checkmk versions can be null (unavailable/ambiguous); do not fall back to the filename.
Config changes are section/file-level, not field-level raw diffs. `deployed_checks` means
selected file-copy tasks completed; `changed_checks` identifies changed copy results.
Check-mode changes are predictions; mode is always explicit. Unknown files are neither
counted nor scanned: policy is `untouched_not_enumerated`, not an invented preserved count.

## Errors and consumer behavior

Report errors: operation_result_missing, operation_result_invalid,
operation_result_withheld, operation_result_limit, operation_result_incomplete.
Messages contain no payload/exception content. Preserve final Core/native status;
show report issues separately; no credential retry or task replay is implied.

Treat this candidate as an implementation awaiting native 2.19.11/managed-host acceptance.
Upstream interfaces consulted: Ansible 2.19.11 `plugins/action/set_stats.py`,
`executor/stats.py`, and callback result contracts; ansible.windows >=3.8.0,<4.0.0 win_updates and
win_service_info return definitions. Consultation is not native testing.


## Patch wave and reboot semantics (3.3.0rc8)

`patch_summary_v1` reports package/update evidence independently from reboot policy. Linux
retains the rc2 package-manager transaction model. Windows delegates each selected patch
wave to one native `ansible.windows.win_updates` `state: installed` invocation with
`reboot: false`. The collection and Windows Update Agent own update ordering/coordination
inside that wave; AIM does not schedule updates individually.

The returned update dictionary is normalized into reviewed installed/failed records. A
module-level failure with no per-update records becomes a bounded generic failed-wave record;
raw failure text, exceptions and arbitrary module dictionaries are not published.

A newly required reboot with `os_patching_reboot: false` does not invalidate successful
installation: `reboot_required`/`reboot_required_after` are true and `reboot_deferred` is
true. The run stops. On a later run, a detected pre-existing reboot with automatic reboot
still disabled publishes `evidence: preflight_reboot_state`, `complete: false`,
`blocked_reason: preexisting_reboot_required`, then fails before new patch work starts.

When automatic reboot is enabled, AIM waits for the native update wave to return before
performing its reviewed message/delay/reboot. By default
`os_patching_rescan_after_reboot: false`; any AIM-performed reboot ends the run with
`continuation_required: true` and `remaining_updates_known: false`. This includes a reboot
that was already required before patching began. A new operator-approved run owns discovery
of the next patch state.

If the operator explicitly sets post-reboot continuation true, AIM may invoke another native
Windows update wave after reboot. Continuation is bounded to 12 wave invocations per run. A
failed wave is never automatically replayed or used as authority to continue.

When a Windows wave completes without reboot, AIM performs one final read-only search. This
does not install newly applicable updates. `remaining_updates_known` is then true and
`pending` contains that final observation; `continuation_required` indicates whether another
operator-approved run has applicable work.

`patch_cycles` counts native Windows install-wave invocations entered in the run and
`rescan_after_reboot` echoes the reviewed option. Those fields are Windows-specific and are
optional in the closed schema so existing Linux result shape remains stable.

Windows `failed_updates` contains only bounded safe fields: update identity/title, normalized
unsigned HRESULT and hex form, a fixed reason and fixed message. Known reasons include
`operation_in_progress`, `install_not_allowed`, `not_applicable`,
`exclusive_install_conflict`, `self_update_in_progress`, `no_connection`, and `timeout`.
Raw Windows Update failure strings are not published. `0x80240016` maps to
`install_not_allowed`; it does not prove a reboot was pending because Windows also uses that
HRESULT while another installation is active. Only the independent preflight can report
`preexisting_reboot_required`.

`reboot_required_before` records the pre-run observation. `reboot_performed` is true when
AIM completed an approved reboot. `reboot_required_after` and the legacy
`reboot_required` field describe the final pending state represented by the report.
`reboot_delay_minutes` echoes the reviewed delay. The user-facing reboot message itself is
not copied into the structured result.

Windows, Debian and RedHat use platform-native reboot-required signals; RedHat preflight
is conservative when `needs-restarting` is not already present. Report fields never imply
that every possible vendor-specific reboot indicator was discovered.