YAML DSL

Version: v1alpha1 API Version: yuzu.io/v1alpha1 Status: Normative specification Audience: Content authors, integrators, plugin developers Basis: docs/Instruction-Engine.md design document

Table of Contents

1. Overview
2. Document Structure
3. Kind: InstructionDefinition
4. Kind: InstructionSet
5. Kind: PolicyFragment (Phase 5)
6. Kind: Policy (Phase 5)
7. Kind: TriggerTemplate (Phase 4)
8. Kind: ProductPack (Phase 7)
9. Expression Language
10. Parameter Type System
11. Result Column Type System
12. Concurrency Model
13. Error Code Taxonomy
14. Substrate Primitive Reference

1. Overview

Yuzu’s YAML DSL defines the content model for the instruction engine. All instruction content — definitions, grouping, policy, triggers, and distribution bundles — is authored as YAML documents conforming to this specification.

Every document begins with apiVersion: yuzu.io/v1alpha1 and a kind field that determines its schema. The six kinds form a compositional hierarchy:

ProductPack
 +-- InstructionSet[]
      +-- InstructionDefinition[]
           |-- Parameter Schema
           |-- Result Schema
           +-- Execution Spec (plugin + action + defaults)

PolicyFragment
 |-- Check: ref -> InstructionDefinition
 |-- Compliance expression
 |-- Fix: ref -> InstructionDefinition
 +-- PostCheck: ref -> InstructionDefinition

Policy
 |-- Scope (device targeting)
 |-- Fragment ref + parameter bindings
 |-- Trigger refs
 +-- Rollout strategy

TriggerTemplate
 |-- Source type (interval, file, service, event_log, registry, startup)
 |-- Parameter schema
 +-- Debounce config

A definition can exist standalone (without a set or pack). Sets are the permission boundary. Packs are the distribution boundary.

2. Document Structure

Every YAML document MUST contain the following top-level fields:

3. Kind: InstructionDefinition

The core unit of the content model. Every ad-hoc command, scheduled task, policy check, and remediation action is an InstructionDefinition.

3.1 Full Schema

metadata

spec

spec.execution

spec.execution.stagger

spec.parameters

A JSON Schema subset. The root object describes the parameter shape.

Each parameter descriptor supports:

spec.parameters.properties.<name>.validation

Constructs shipped definitions use beyond the tables above

The server’s parameter-schema canonicaliser accepts these forms and publishes the result as input_schema (GET /api/v1/discover/instructions, MCP discover_instructions):

• type: integer is accepted next to int32/int64. int32 is a numeric string on the wire (Section 10) but is published as integer with the int32 range.
• type: array with items: {type: string}.
• required: true on a property is the same as listing it in the root required.
• maxLength, minLength, pattern, enum, minimum and maximum may be written flat on the property; a flat key beats the same key under validation.
• hidden: true is accepted as a no-op hint (no effect on validation; not published). displayName is dropped from the published schema.

Shipped definitions under content/definitions/ and content/packs/ must meet the description-lint floors enforced by scripts/ci/check-definition-descriptions.py: metadata.description of at least 40 characters (and not just the name or id), every parameter description at least 10 characters, every result column described, and metadata.tags non-empty. To fix a baselined failure, edit the YAML and delete the fixed entry from scripts/ci/definition-descriptions-baseline.json, otherwise the STALE check fails.

spec.result

Each column object:

spec.result.aggregation

spec.gather

spec.response

spec.approval

spec.permissions

Advisory content metadata, not enforced by the server. Neither field has a server-side representation: executeRoles’ labels (endpoint-admin, security-admin, …) are a content-authoring convention that matches no seeded RBAC role (Administrator/PlatformEngineer/Operator/ ApiTokenManager/ITServiceOwner/Viewer/Reviewer/ForensicsAnalyst), and embed_content.py drops the entire permissions block at build time — it never reaches the running server. Actual execute-time enforcement is spec.approval.mode (see above); actual author-time enforcement is the InstructionDefinition:Write RBAC permission on the create/update route, unrelated to authorRoles. Both fields may still be authored for human-readable documentation of intent, but neither controls anything at runtime.

spec.compatibility

spec.legacy_shim

spec.visualization

Optional chart configuration consumed by the dashboard’s instruction-response views and the GET /api/v1/executions/{id}/visualization REST endpoint (issue #253). When omitted, the response view shows the standard tabular layout only — no chart card is rendered.

Field naming. This block uses camelCase, matching the rest of apiVersion: yuzu.io/v1alpha1. The engine also accepts the legacy snake_case names (label_field, value_field, …) as deprecated aliases — they will be removed in a future API version. Author new specs against the camelCase names.

Multi-chart definitions. A definition can declare more than one chart by using the canonical plural form spec.visualizations: [<vis>, ...]. The singular spec.visualization: <vis> is accepted as syntactic sugar for a single-element list and is normalised at ingest. The dashboard renders all charts as a deck (<div class="yuzu-chart-deck">); the REST endpoint takes an optional ?index=N query parameter (default 0) to address individual charts and includes chart_index and chart_count in every response payload so callers can iterate.

Limitations. The engine caps each chart at 10 000 underlying response rows; the read is also capped at 50 MiB of response payload. rows_capped: true means the row cap cut the read; when either cap cut it the payload also carries result_truncated_by_cap: true and truncation_cause (row_cap or byte_cap), and the dashboard shows a “Partial result” notice in the chart card. The engine also caps total distinct labels at 10 000 (defense-in-depth against a misbehaving plugin emitting unbounded label cardinality).

Authoring through the dashboard YAML editor strips visualization. When saving a definition via the dashboard’s CodeMirror editor (POST /api/instructions/yaml), the schema-aware extractor (instruction_yaml::parse_definition_yaml) indexes id, name, plugin, action, type, description, concurrency, approval from the YAML source (canonical nested or flat schema) but does NOT extract spec.visualization into the indexed visualization_spec column. The chart spec is preserved in yaml_source (verbatim source of truth) but not indexed, so the chart deck does not render the chart until the definition is re-imported via POST /api/v1/definitions/import (JSON envelope, full visualization extraction) or until the next server restart triggers the bundled-content auto-import. Author chart-bearing definitions through the JSON import path or the in-tree content/definitions/ library, not the editor save. Tracked as a known gap pending yaml-cpp Windows MSVC resolution (#625).

The engine returns a self-contained payload the dashboard’s renderer (/static/yuzu-charts.js) can draw without a second request:

{
  "data": {
    "chart_type": "pie",
    "title": "Service States",
    "labels": ["running", "stopped", "paused"],
    "series": [{"name": "Count", "data": [42, 7, 1]}],
    "meta": {"responses_total": 50, "responses_succeeded": 50, "responses_failed": 0}
  },
  "meta": {"api_version": "v1"}
}

For datetime_series the shape replaces labels with x (epoch-seconds array) and adds "x_axis": "datetime".

Example — count distinct process names across the fleet (plugin procfetch emits PID|Name|Path|SHA-1; labelField: 1 selects the Name column):

spec:
  visualization:
    type: pie
    processor: single_series
    title: Top processes
    labelField: 1
    maxCategories: 8

Example — events-over-time per agent (default xField uses the response’s wall-clock timestamp; one data point per response):

spec:
  visualization:
    type: line
    processor: datetime_series
    title: Events per second

Example — multiple charts on one definition (issue #587). The dashboard renders both side by side:

spec:
  visualizations:
    - type: pie
      processor: single_series
      title: Top processes
      labelField: 1
      maxCategories: 8
    - type: line
      processor: datetime_series
      title: Process count over time

spec.responseTemplates

Optional list of named response-view configurations consumed by the dashboard’s filter bar dropdown and the GET/POST/PUT/DELETE /api/v1/definitions/{id}/response-templates REST endpoints (issue #254, Phase 8.2). When omitted, the engine synthesises a single __default__ template from spec.result.columns (preferred) or the plugin’s column schema, so every definition has at least one selectable view without authoring.

Example — a “Failures only” view for a vulnerability scan definition:

spec:
  responseTemplates:
    - name: Failures only
      columns: [Severity, Title, Detail]
      sort: {column: Severity, dir: desc}
      filters:
        - {column: Severity, op: equals, value: high}
    - name: Critical view
      default: true
      columns: [Severity, Category, Title]
      filters:
        - {column: Severity, op: equals, value: critical}

Authoring through the dashboard YAML editor strips response templates. Same caveat as spec.visualization — the extractor used by POST /api/instructions/yaml does not index spec.responseTemplates into the indexed column. Use POST /api/v1/definitions/import (JSON envelope) or the in-tree content/definitions/ library, or call POST /api/v1/definitions/{id}/response-templates directly to author templates against an already-imported definition.

spec.offload

Optional per-instruction override for the response-offload control plane (issue #255, Phase 8.3). Targets are global config registered through POST /api/v1/offload-targets with their own URL, auth (none / bearer / basic / hmac), event filter, and batch size. By default every enabled target whose event_types filter matches the fired event receives a copy of the payload. spec.offload.targets restricts that fan-out to a named subset for a specific definition.

Example — an inventory-collection definition that only ships its responses to the siem-archive target (other webhooks/offload targets do not receive these events):

spec:
  offload:
    targets: [siem-archive]

spec.offload.targets is not extracted by the dashboard YAML editor or the JSON import endpoint. The field is preserved verbatim in the yaml_source source-of-truth column on instruction_definitions but is not denormalised into an indexed column and is not consulted by the dispatcher in this revision. Authoring this field has no current effect on fan-out behaviour. See the runtime caveat below.

Runtime correlation is opt-in. The agent.registered and execution.completed events fan out globally to every enabled offload target whose event_types filter matches, regardless of spec.offload.targets. The store’s OffloadTargetStore::fire_event accepts an optional target_filter argument that callers can use to restrict fan-out to a named subset, but the agent-service dispatch path does not currently extract the filter from the originating definition. Wiring the dispatcher to walk command_id → execution_id → definition_id → InstructionStore::get_definition and read spec.offload.targets is tracked as a follow-up.

status

3.2 Complete Example

apiVersion: yuzu.io/v1alpha1
kind: InstructionDefinition
metadata:
  id: crossplatform.service.inspect
  displayName: Inspect Service Status
  version: 1.2.0
  description: Returns the current state, startup type, and PID of a named service.
  tags:
    - services
    - operations
spec:
  type: question                         # question (read-only) | action (may modify state)
  platforms:
    - windows
    - linux
    - darwin
  execution:
    plugin: services
    action: inspect
    concurrency: per-device              # only per-device is enforced — see Section 12
    stagger:
      maxDelaySeconds: 0                 # 0 = no stagger
      fixedDelaySeconds: 0               # 0 = no fixed delay
  parameters:
    type: object
    required:
      - serviceName
    properties:
      serviceName:
        type: string
        displayName: Service Name
        description: The name of the service to inspect.
        validation:
          maxLength: 256
      verbose:
        type: boolean
        default: false
  result:
    columns:
      - name: serviceName
        type: string
      - name: state
        type: string
      - name: startupType
        type: string
      - name: pid
        type: int32
    aggregation:
      groupBy:
        - state
      operations:
        - count
  readablePayload: "Inspect service '${serviceName}'"
  gather:
    ttlSeconds: 300                      # agent must respond within this window
  response:
    retentionDays: 90
  approval:
    mode: auto                           # auto | role-gated | always
  permissions:
    executeRoles:
      - endpoint-operator
      - endpoint-admin
    authorRoles:
      - content-author
  compatibility:
    minAgentVersion: 0.9.0
    requiredPlugins:
      - services
  legacy_shim:
    enabled: true                        # auto-generate from plugin descriptor if true
  visualization:                         # optional — omit if no chart is needed
    type: pie
    processor: single_series
    title: Service State Distribution
    labelField: 1                        # 0-based index into spec.result.columns: 1 = state
    maxCategories: 8
status:
  phase: proposed

4. Kind: InstructionSet

The grouping unit and permission boundary. Sets aggregate definitions, policy fragments, and workflow templates under a shared permission model.

4.1 Full Schema

metadata

metadata.permissions

Advisory content metadata, not enforced by the server — same status as spec.permissions above (#1398); none of the three fields below has a server-side representation or reads through to any RBAC check.

metadata.contents

metadata.defaults

metadata.publishing

status

4.2 Complete Example

apiVersion: yuzu.io/v1alpha1
kind: InstructionSet
metadata:
  id: core.crossplatform.services
  displayName: Cross-Platform Service Management
  version: 1.0.0
  description: Inspect, start, stop, and restart services across all platforms.
  platforms:
    - windows
    - linux
    - darwin
  permissions:
    executeRoles:
      - endpoint-operator
      - endpoint-admin
    authorRoles:
      - content-author
      - endpoint-admin
    approveRoles:
      - endpoint-admin
  contents:
    instructionDefinitions:
      - crossplatform.service.inspect
      - crossplatform.service.start
      - crossplatform.service.stop
      - crossplatform.service.restart
      - crossplatform.service.set_start_mode
    policyFragments:
      - fragment.service.must_be_running
    workflowTemplates:
      - workflow.restart_then_verify
  defaults:
    approvalMode: role-gated
    responseRetentionDays: 30
    targetEstimationRequiredAbove: 500
  publishing:
    signed: true
    visibility: org
status:
  phase: proposed

5. Kind: PolicyFragment (Phase 5)

Implementation phase: Phase 5 — Policy engine. Not yet implemented.

A reusable check/fix block that encapsulates a compliance check, optional remediation, and post-check verification. Fragments are composed into Policies (Section 6) for deployment to device scopes.

5.1 Full Schema

metadata

spec

spec.inputs

spec.check

spec.compliance

spec.compliance.states

spec.fix

spec.postCheck

spec.debounce

spec.exceptionModel

status

5.2 Complete Example

apiVersion: yuzu.io/v1alpha1
kind: PolicyFragment
metadata:
  id: fragment.service.must_be_running
  displayName: Service must be running
  version: 1.0.0
  description: Reusable fragment that checks a service and optionally restarts it.
spec:
  platforms:
    - windows
    - linux
    - darwin
  inputs:
    type: object
    required:
      - serviceName
    properties:
      serviceName:
        type: string
      autoRemediate:
        type: boolean
        default: true
  check:
    ref: crossplatform.service.inspect
    with:
      serviceName: ${inputs.serviceName}
  compliance:
    expression: result.state == "running"
    states:
      compliant: result.state == "running"
      noncompliant: result.state != "running"
      error: result.error != null
  fix:
    when: ${inputs.autoRemediate} == true
    ref: crossplatform.service.restart
    with:
      serviceName: ${inputs.serviceName}
  postCheck:
    ref: crossplatform.service.inspect
    with:
      serviceName: ${inputs.serviceName}
  debounce:
    minIntervalSeconds: 300
  exceptionModel:
    allowTemporarySuppressions: true
status:
  phase: proposed

6. Kind: Policy (Phase 5)

Implementation phase: Phase 5 — Policy engine. Corrected 2026-09-11 (Gate-of-record pass 5, arch-P5-1): this banner was stale. PolicyStore is implemented and live in production (server/core/src/policy_store.cpp, compliance_routes.cpp) — policies are created and evaluated today; remediation is operator-initiated, never automatic (see §16 of docs/capability-map.md and docs/user-manual/policy-engine.md). What is genuinely not implemented is the spec.triggers[] schema documented in this section (ref:/with: references to a TriggerTemplate) — see the caveat under spec.triggers[] below for what the shipped parser actually accepts.

A Policy binds a PolicyFragment to a device scope and a set of triggers. Policies are the deployment unit for compliance enforcement.

6.1 Full Schema

metadata

spec

spec.scope

spec.scope.selector

Note: For advanced targeting, use the Scope DSL expression language (Section 9) in the scope expression field of an execution rather than the selector shorthand.

spec.assignment

spec.fragment

spec.triggers[]

Each trigger object:

Implementation caveat (added 2026-09-11, Gate-of-record pass 5, arch-P5-1): the shipped PolicyStore parser does not implement this ref:/with: schema at all. It reads each trigger entry for a bare type: key (extract_yaml_value(item_block, "type")) and, when type: interval, an interval_seconds: key — there is no TriggerTemplate resolution, no ref: lookup, anywhere in policy_store.cpp. A trigger object written exactly as this table specifies (ref: + optional with:, no type: key) parses with an empty trigger_type and is silently dropped — not stored at all, not even as an unrecognized/errored trigger: if (!t.trigger_type.empty()) triggers.push_back(...) (server/core/src/policy_store.cpp:678-679) simply skips it. A policy authored per this exact schema therefore has zero triggers in the database and falls back to the 3600-second interval default (see docs/user-manual/policy-engine.md § Trigger Configuration). The shipped, working schema is - type: interval / interval_seconds: <seconds> per-entry — type values other than interval are accepted and stored (unlike ref:, which is dropped) but do not affect evaluation cadence either. This is a real gap between this normative spec and the implementation, not a documentation nuance: content authored to this table’s schema silently does nothing. Tracked as issue #4244.

spec.schedule

spec.rollout

spec.approvals

spec.compliance

spec.exceptions

status

6.2 Complete Example

**This example’s triggers: block uses the ref:/with: schema documented above — see the implementation caveat under spec.triggers[]: the shipped parser drops these entries (zero triggers stored), and the policy falls back to the 3600-second interval default rather than the ref: trigger.interval.five_minutes / ref: trigger.service_status_changed cadence this example implies. This example is kept as-is because it is the normative schema, unmodified by an implementation gap — do not copy its triggers: block into a real policy and expect it to work; use the shipped type: interval / interval_seconds: form from docs/user-manual/policy-engine.md instead. (Added 2026-09-11, Gate-of-record pass 5, arch-P5-1.)

apiVersion: yuzu.io/v1alpha1
kind: Policy
metadata:
  id: policy.windows.spooler.running
  displayName: Windows Print Spooler must be running
  version: 1.0.0
  description: Ensures the Spooler service remains in the running state.
spec:
  scope:
    selector:
      platform: windows
      tags:
        - print-enabled
  assignment:
    mode: dynamic
    managementGroups:
      - workstations
  fragment:
    ref: fragment.service.must_be_running
    with:
      serviceName: Spooler
      autoRemediate: true
  triggers:
    - ref: trigger.interval.five_minutes
    - ref: trigger.service_status_changed
      with:
        serviceName: Spooler
  schedule:
    cron: "*/15 * * * *"
    timezone: UTC
  rollout:
    strategy: gradual
    maxConcurrentPercent: 10
  approvals:
    requiredForInitialDeploy: true
    requiredForRemediationChange: true
  compliance:
    cacheTtlSeconds: 300
    responseRetentionDays: 90
    emitEventsOnStateChange: true
  exceptions:
    allowDeviceLevelExemption: true
    exemptionMaxDays: 14
status:
  phase: proposed

7. Kind: TriggerTemplate (Phase 4)

Implementation phase: Phase 4 — Agent infrastructure. Not yet implemented.

A TriggerTemplate defines an event source that can initiate policy evaluation or instruction execution on the agent.

7.1 Full Schema

metadata

spec

spec.source

Trigger source types:

spec.debounce

spec.delivery

spec.outputs

A JSON Schema subset describing the structured payload produced when the trigger fires. This payload is available to downstream consumers (policy evaluations, instruction parameter bindings).

status

7.2 Complete Example

apiVersion: yuzu.io/v1alpha1
kind: TriggerTemplate
metadata:
  id: trigger.windows.eventlog.pattern
  displayName: Windows Event Log Pattern Trigger
  version: 1.0.0
  description: Fires when a matching Windows event log record appears.
spec:
  platforms:
    - windows
  source:
    type: windows-event-log    # interval | filesystem | service | windows-event-log | registry | agent-startup
  parameters:
    type: object
    required:
      - channel
    properties:
      channel:
        type: string
      provider:
        type: string
      eventIds:
        type: array
        items:
          type: integer
      messageRegex:
        type: string
  debounce:
    mode: keyed
    keyExpression: "${channel}:${provider}:${eventId}"
    minIntervalSeconds: 60
  delivery:
    mode: local-agent
    persistTriggerEvents: true
  outputs:
    type: object
    properties:
      timestamp:
        type: string
      channel:
        type: string
      provider:
        type: string
      eventId:
        type: integer
      computer:
        type: string
      message:
        type: string
status:
  phase: proposed

8. Kind: ProductPack (Phase 7)

Implementation phase: Phase 7 — Scale and integration. Not yet implemented.

A ProductPack is a signed distribution bundle containing instruction sets, definitions, policy fragments, policies, trigger templates, dashboards, and documentation. Packs are the unit of distribution and trust.

8.1 Full Schema

metadata

spec

spec.publisher

spec.compatibility

spec.contents

spec.dependencies

spec.security

spec.security.signing

spec.security.signature

spec.security.checksums

spec.security.trustChain

spec.distribution

status

8.2 Complete Example

apiVersion: yuzu.io/v1alpha1
kind: ProductPack
metadata:
  id: pack.core.endpoint-ops
  displayName: Core Endpoint Operations Pack
  version: 1.0.0
  description: Signed bundle of baseline operational content for core endpoint management.
spec:
  publisher:
    name: Yuzu Core
    contact: platform@example.invalid
  compatibility:
    minServerVersion: 0.9.0
    minAgentVersion: 0.9.0
    requiredApiVersions:
      - yuzu.io/v1alpha1
  contents:
    instructionSets:
      - core.crossplatform.services
      - core.crossplatform.processes
    instructionDefinitions:
      - crossplatform.service.inspect
      - crossplatform.service.restart
      - crossplatform.process.list
      - crossplatform.process.kill
    policyFragments:
      - fragment.service.must_be_running
    policies:
      - policy.windows.spooler.running
    triggerTemplates:
      - trigger.interval.five_minutes
      - trigger.windows.eventlog.pattern
    dashboards:
      - compliance.overview
    docs:
      - docs/pack-overview.md
  dependencies:
    plugins:
      - services
      - processes
      - event_logs
    packs: []
  security:
    signing:
      algorithm: ed25519
      keyId: yuzu-core-release-2026
      keyFingerprint: "SHA256:..."
    signature:
      manifestHash: <sha256-of-manifest>
      value: <base64-ed25519-signature>
    checksums:
      manifestSha256: <sha256>
    trustChain:
      rootKeyFingerprint: "SHA256:..."
      signingKeyCertificate: <base64-der>
    revocationListUrl: "https://packs.yuzu.example/crl.json"
  distribution:
    format: tar.zst
    importMode: staged
    allowPartialImport: false
status:
  phase: proposed

9. Expression Language

9.1 Scope DSL

The scope engine (server/core/src/scope_engine.cpp) implements a recursive-descent parser for device targeting expressions. This DSL is used in spec.scope fields and dashboard filter expressions.

Grammar

expr       ::= or_expr
or_expr    ::= and_expr ('OR' and_expr)*
and_expr   ::= not_expr ('AND' not_expr)*
not_expr   ::= 'NOT' not_expr | primary
primary    ::= '(' expr ')' | condition
condition  ::= IDENT op value
op         ::= '==' | '!=' | 'LIKE' | '<' | '>' | '<=' | '>=' | 'IN' | 'CONTAINS'
value      ::= QUOTED_STRING | '(' value_list ')' | IDENT
value_list ::= value (',' value)*

Operators

Combinators

Features

• Case-insensitive keyword matching (AND, OR, NOT, LIKE, IN, CONTAINS)
• Wildcard LIKE with * (match any characters) and ? (match single character) globbing
• Numeric comparison with std::from_chars fallback to std::stod (Apple libc++ compatibility)
• Case-insensitive substring search via CONTAINS
• Maximum nesting depth of 10
• AttributeResolver callback decouples parsing from data access

Examples

ostype == "windows" AND tag:env == "production"
hostname LIKE "web-*" OR hostname LIKE "api-*"
arch IN ("x86_64", "aarch64") AND NOT tag:quarantined == "true"
agent_version >= "0.9.0"

9.2 Planned Scope DSL Extensions

Note: EXISTS, MATCHES, len(), and startswith() are implemented in the scope engine today (the “planned” label predates them). Tag presence lowers to EXISTS tag:<name> — see §9.3.

9.3 Scope walking — composable scope (fromResultSet:)

Scope walking (capability §30, docs/scope-walking-design.md) lets a scope target the members of a previously-saved result set — Yuzu’s composable-scope primitive. A result set is a per-operator, TTL-bounded, lineage-tracked set of device ids built from an earlier query.

Scope atom. The scope engine accepts a bare atom from_result_set:<id-or-alias> (implemented, scope_engine.cpp). It resolves to the members of the referenced set and composes with attribute predicates via AND / OR / NOT. Membership is owner-checked at evaluation: a set the dispatching operator does not own resolves to zero devices (no cross-operator targeting). Offline / stale members drop silently.

from_result_set:rs_01HXYZ AND ostype == "windows"

YAML authoring form. Where a spec.scope: block is accepted, the mapping form may carry fromResultSet: (a canonical rs_ id or a per-operator alias), optionally refined by a selector: composed with AND:

spec:
  scope:
    fromResultSet: "windows-chrome-suspects"   # id or per-operator alias
    selector:                                    # optional refinement (AND-ed)
      platform: windows
      tags:
        - production
  assignment:
    mode: static

This lowers to the scope-engine string from_result_set:windows-chrome-suspects AND ostype == "windows" AND EXISTS tag:production — selector.platform → ostype == "<value>" (lower-cased); each selector.tags entry → EXISTS tag:<name> (a presence check, since Yuzu tags are key=value).

Validation (at YAML load):

1. fromResultSet may not be combined with assignment.managementGroups — a result set already defines a fixed device set; layering management-group filtering on top is rejected.
2. When fromResultSet is present, assignment.mode must be static (an omitted mode defaults to static). dynamic is rejected — the point of a result set is a fixed target.
3. References resolve at invocation time, not load time. An InstructionDefinition carrying a fromResultSet: that has since expired is still valid YAML; an invocation-time resolution failure (the set is absent, expired, or not owned — including a set deleted in the window between the pre-dispatch owner-check gate and the registry’s own membership read, closed as a TOCTOU by #4981 PR-1) is recorded as an instruction.scope_resolution_failed audit row (INSTRUCTION_SCOPE_RESOLUTION_FAILED) carrying the result-set id and reason, and — as of governance M1, 2026-07-29 — aborts the entire dispatch: zero devices are targeted, including devices matched by other scope atoms (a paired scope.evaluation_aborted row records reason=owner_check_failed, or one of db_degraded/principal_unresolved/presence_degraded/unresolvable for the other abort classes — see docs/user-manual/rest-api.md’s audit-event table for the full vocabulary). The previous behavior (proceed with only that reference zeroed) inverted to a fleet-wide match under a NOT combinator and is gone.
4. fromResultSet (id or alias), selector.platform, and each selector.tags entry must contain only letters, digits, and _ . : * - (the scope-ident charset). A space, quote, or operator character is rejected at load — these values are lowered into a scope-engine token, so anything else would produce an unparseable or ambiguous expression. Choose result-set aliases (name) from this charset; an alias with a space cannot be referenced from a scope.
5. The scope: block must use block form (scope: on its own line, children indented beneath). Inline flow-mapping (scope: {fromResultSet: x}) is rejected — the runtime YAML scanner reads only the block form.

Tag presence (EXISTS tag:<name>) requires the tag to have a non-empty value; a device carrying a tag with an empty value is treated as not having it.

Current support (this release):

• Aliases in a from_result_set: ref are resolved at the dispatch layer against the dispatching operator’s owned sets (a canonical rs_ id is used verbatim). The /api/scope/estimate preview resolves them too.
• Instruction definitions validate a spec.scope block at import; the operator still supplies the from_result_set: scope at dispatch time. (A definition-embedded scope that auto-applies at dispatch is a follow-up.)
• Policies do not yet support fromResultSet: — a policy is evaluated continuously while a result set is TTL-bounded; create_policy rejects it with a clear error. (Tracked for a follow-up that adds a policy owner + pinned-set semantics.)

See docs/scope-walking-design.md §7 and the Chrome-IR walkthrough (§10).

9.4 CEL (Common Expression Language)

Yuzu implements a CEL-compatible expression evaluator (server/core/src/cel_eval.cpp) for typed policy evaluation expressions. CEL is not used for device targeting (the scope DSL is simpler and sufficient for that purpose).

Where CEL applies:

• spec.compliance.expression in PolicyFragments
• spec.fix.when conditional expressions in PolicyFragments
• spec.rollout.condition for staged rollouts in Policies
• WorkflowStep.condition for conditional workflow steps

Where the scope DSL stays:

• All device targeting (spec.scope.selector)
• ScopeEngine evaluation in the dispatch path
• Dashboard filter expressions

Type System

Variables from instruction results are provided as strings and automatically coerced to typed values: "true"/"false" to bool, integer strings to int, float strings to double, ISO 8601 strings to timestamp.

Operators

String + performs concatenation. Timestamp arithmetic: timestamp + duration = timestamp, timestamp - timestamp = duration.

Built-in Functions

Backward Compatibility

Legacy compliance expressions using AND, OR, NOT, contains, and startswith keywords continue to work. The evaluator accepts both CEL syntax (&&, ||, !, .contains(), .startsWith()) and legacy keyword syntax. New fragments are automatically migrated to CEL syntax via cel::migrate_expression().

Precedence note: The keyword NOT has lower precedence than comparison operators (for backward compatibility), so NOT result.status == 'failed' is parsed as NOT (result.status == 'failed'). The CEL ! operator has standard unary precedence, so !result.status == 'failed' is parsed as (!result.status) == 'failed'. Use parentheses when mixing styles to avoid ambiguity.

Safety Limits

Examples

# Basic compliance check
result.status == 'running'

# Typed comparison with arithmetic
result.cpu_percent < 90 && result.memory_mb > 512

# Ternary for computed compliance
result.score >= 80 ? true : false

# Timestamp comparison
timestamp(result.last_check) + duration('1h') > timestamp(result.current_time)

# List membership
result.os in ['windows', 'linux', 'darwin']

# String functions
result.hostname.startsWith('web-') && result.hostname.matches('^web-\\d+$')

# Combined check with duration
result.uptime_seconds > 3600 && result.status == 'running'

10. Parameter Type System

InstructionDefinition parameters and PolicyFragment inputs use the following type set:

Parameters are transmitted as map<string, string> in the CommandRequest protobuf message. POST /api/instructions/{id}/execute validates the request’s parameter values against the declared type and constraints before dispatch; no other dispatch surface does yet.

Validation Constraints

11. Result Column Type System

Result schemas declare typed columns for structured output. These types enable downstream consumption by ClickHouse, Splunk, CSV export, and the dashboard aggregation engine.

The clob type indicates a potentially large text field. The server may apply configurable truncation to clob columns to limit storage consumption.

12. Concurrency Model

Corrected 2026-08-31 (ADR-1007) — only per-device is actually enforced. An earlier revision of this section described 5 modes as shipped; a real-usage audit of content/definitions/*.yaml plus a direct read of the dispatch path found that only per-device has ever been enforced, and the other four values are either unspecified or attach exclusively to catalog-only definitions that never dispatch through the agent path at all. concurrency_mode is not validated anywhere in the load/CRUD path — any string is accepted verbatim, so a typo or an unsupported value is silently treated as no limit, never rejected.

Enforcement (per-device)

Enforced server-side, not agent-side as an earlier revision of this spec described — see ADR-1007 for why (the wire CommandRequest carries no definition_id, and building agent-side dedup would require a proto + gateway change with no correctness benefit once the server-side design is made race-free). The server holds a claim (a dedicated Postgres table, race-free via a partial unique index — not the concurrency_locks an earlier revision of this section described, which was never built) on (definition_id, agent_id) at dispatch time and releases it when that agent’s execution reaches a terminal state. An agent already holding a claim for the same definition is excluded from the dispatch — for a single-target dispatch this means “no agents reached”; there is no queueing (an earlier revision of this section claimed an at-limit execution “enters a wait queue” — no such mechanism has ever existed, agent or server side). The caller may retry once the in-flight execution completes. Error code 3003 (kConcurrencyBlocked) is registered in the taxonomy for this condition but is not currently surfaced through the dispatch response — see ADR-1007’s follow-ups.

Not covered: raw MCP execute_instruction and raw REST command dispatch (no definition_id in scope — cannot be gated by definition), and fleet-broadcast dispatch of a per-device definition (scope: __all__) — both real, deliberate gaps, not oversights.

One release exception: cancelling an execution does not release its claim (no agent-side cancel/kill path exists, so the claim stays open exactly as if the execution were still running, until a terminal response or the reconciler’s TTL bound — at most one hour — releases it). A per-device definition dispatched via a workflow step releases and renews the same way as any other dispatch path (a command_id-keyed fallback covers it, since workflow-step dispatch still doesn’t correlate a real execution id) — see ADR-1007.

plugin: server / server_internal / _server definitions

The 42 shipped definitions using per-definition/global/global-singleton are catalog/discovery metadata for the management API and dashboard, not live execution artifacts — no agent plugin named server/server_internal/_server exists. Their real functionality (directory sync, deployment orchestration, policy CRUD, etc.) is implemented by dedicated REST routes calling dedicated C++ objects directly, which never consult concurrency_mode. Where real concurrent-call protection is needed for one of these operations, it is implemented directly on the handler (see DirectorySync::sync_entra’s re-entrancy guard, ADR-1007) rather than through this DSL field.

YAML Syntax

spec:
  execution:
    concurrency: per-device          # default — the only mode actually enforced
    # concurrency: per-definition    # accepted, NOT enforced — see above
    # concurrency: per-set           # accepted, NOT enforced, unspecified grouping — see above
    # concurrency: unlimited         # no limits (also the practical effect of any unsupported value)

13. Error Code Taxonomy

Errors are categorized into four domains with non-overlapping numeric ranges.

1xxx — Plugin Errors

2xxx — Transport Errors

3xxx — Orchestration Errors

Names above are the taxonomy’s actual registered names (server/core/src/error_codes.cpp) — this row set was corrected from a stale naming scheme this table had carried (ORCH_* prefixes that never matched the code). Like 3003, none of 3001/3002/3004/3005 currently has a production call site that emits it — the retry column states the DESIGNED behavior per the taxonomy entry, not an observed one.

4xxx — Agent Errors

Retry Semantics

14. Substrate Primitive Reference

This section enumerates the stable builtin primitives that content authors target. Each primitive maps to a backing plugin and one or more agent actions. Platform availability is marked per column.

Status key:

• Verified — grounded in existing plugin code in agents/plugins/
• Planned — in roadmap with GitHub issue
• Proposed — recommended in design document

14.1 System and Identity

14.2 Process and Execution

14.3 Services and Daemons

14.4 User, Session, and Identity

14.5 Network

14.6 Software and Patching

14.7 Filesystem and Content Staging

storage.free (crossplatform.storage.free) reports total_bytes, free_bytes, and percent_used for a single volume; the path parameter selects the volume (default C:\ on Windows, / on Linux/macOS); the free figure is quota-aware caller headroom (FreeBytesAvailableToCaller / f_bavail); query each volume in a separate call.

14.8 Security and Compliance

14.9 Registry and WMI (Windows)

14.10 Agent Key-Value Storage

14.11 Workflow Primitives

14.12 Trigger Primitives

14.13 Governance Primitives

14.14 Device Discovery

14.15 Echo

echo.compatibility — Emit the live OS compatibility matrix for every registered capture source (process, tcp, service, user, perf, procperf, netqual, module, software, arp, dns, netconn, mapdrive, power, removable, usage). Returns one header|... line followed by N row|source|os|status|capture_method|notes lines. Status values: supported | constrained | planned | unsupported. Read-only static metadata; safe to call at any frequency. Use to verify which sources are wired on the current agent OS before configuring network_capture_method; the mechanism actually in force is reported as network_capture_method_effective by the status action (always polling today).

echo.collect_perf — Record one device performance sample (CPU/memory/disk/network) into $Perf_Live, and — when procperf_enabled is set (on by default) — one per-application top-N sample into $ProcPerf_Live on the same tick (output line echo|collect_procperf|N|...). Trigger-driven on the perf_interval_seconds cadence (default 30 s; Windows and Linux — macOS records nothing until its collector lands); a manual invocation forces one immediate sample. Note: a tick whose core counter read fails (e.g. a hardened container masking /proc/stat on Linux, or an NT-counter read failure on Windows) reports counters_unavailable on any OS the registry lists as supported for perf/procperf, and unsupported_platform only where no perf collector exists (macOS today) — so a supported platform whose reads are failing is distinguishable from an unsupported one. The per-source streak is in echo.status (perf_last_status / perf_consecutive_failures, and identically procperf_last_status / procperf_consecutive_failures). The first sample after agent start is a baseline (records no row). See the Echo user manual for the perf/procperf tiers and their perf_enabled / procperf_enabled / perf_interval_seconds configuration.

echo.fleet_snapshot — Enumerate running processes, open network connections, and host-bound IPs and emit a single fleet_snapshot.v1 JSON document. Each list is capped at 4096 entries; truncation is flagged via truncated_processes / truncated_connections. Cmdlines are redacted per the active redaction patterns (defaults always apply). When the operator has paused the process or tcp source, the corresponding list is empty and process_source_paused / tcp_source_paused markers appear in the document. Consumed by the server-side FleetTopologyStore for the /viz/fleet 3D renderer (PR ladder 1-11). Dispatched on demand by the server at the topology cache TTL (default 60 s); not typically invoked manually.

14.16 Test and Debug

testing.chargen.start — Start an RFC 864 character generator session for throughput benchmarking. Generates a continuous stream of printable ASCII characters to measure agent-to-server data-plane performance.

testing.chargen.stop — Stop all running chargen sessions on the target device.