Skip to content

BenchX environment policy

urn:benchx:schema:environment-policy:0.1.0 · version 0.1.0 · schema.json · source

A named, versioned list of rules the runner enforces, verifies, or records before and during a run (docs/design/runner-schema.md §4). Referenced by a work order's environment_policy {name, version} and by coordinates.environment.identity.policy as "name@version".

Implementer note

The check vocabulary is open (core checks in §4.1 plus a namespaced x-.* prefix), so check and parameters are not constrained to a closed set here; the runner rejects a check it has no handler for. on_fail is fixed by tier and therefore not a free choice: enforce always refuses on failure (§4's table), so it is omitted rather than restated; record never fails, so it is omitted too; only verify carries an explicit on_fail (refuse or warn, per rule). Every check token, and any detail appended to a reason built from one (e.g. policy-unsatisfied-, runner-schema.md §6), must itself match the result schema's reason pattern (letters/digits joined by '.' or '-', no '_'), which is why gpu.clocks-locked replaces the original gpu.clocks_locked in §4.1.

Properties

Property Required Type Description
schema_version yes constant "benchx/environment-policy/0.1.0"
name yes token
version yes nonEmptyString
rules yes array of rule (min items 1)

No other properties are allowed.

Definitions

Reusable subschemas referenced from the tables above and from other schemas.

rule

Property Required Type Description
check yes token Core vocabulary (runner-schema.md §4.1) or a namespaced project check (x-arrow., x-cupy.).
tier yes one of "enforce", "verify", "record"
parameters object Check-specific parameters, such as {"n": 1} for threads.max or {"cpus": "0-7"} for cpu.affinity.
on_fail one of "refuse", "warn"

No other properties are allowed.

Rules:

  • If tier is "enforce", then forbids on_fail.
  • If tier is "verify", then requires on_fail.
  • If tier is "record", then forbids on_fail.

Examples

{
  "schema_version": "benchx/environment-policy/0.1.0",
  "name": "laptop-default",
  "version": "1.0.0",
  "rules": [
    { "check": "threads.max", "tier": "enforce", "parameters": { "n": 1 } },
    { "check": "cpu.governor", "tier": "record" },
    { "check": "cpu.boost", "tier": "record" },
    { "check": "cpu.smt", "tier": "record" },
    { "check": "gpu.device", "tier": "enforce", "parameters": { "index": 0 } },
    { "check": "accel.sync", "tier": "enforce", "parameters": { "mode": "device-sync" } },
    { "check": "load.quiescent", "tier": "record" },
    {
      "check": "hardware.present",
      "tier": "verify",
      "on_fail": "warn",
      "parameters": { "cpu_model_pattern": "*", "min_ram_bytes": 8589934592 }
    },
    { "check": "tree.clean", "tier": "record" },
    { "check": "thermal.throttle", "tier": "record" },
    { "check": "thermal.temperature", "tier": "record", "parameters": { "sample_interval_s": 5 } }
  ]
}

{
  "schema_version": "benchx/environment-policy/0.1.0",
  "name": "tuned-node",
  "version": "1.0.0",
  "rules": [
    { "check": "threads.max", "tier": "enforce", "parameters": { "n": 1 } },
    { "check": "cpu.affinity", "tier": "enforce", "parameters": { "cpus": "0-7" } },
    { "check": "cpu.governor", "tier": "verify", "on_fail": "refuse", "parameters": { "governor": "performance" } },
    { "check": "cpu.boost", "tier": "verify", "on_fail": "refuse", "parameters": { "boost": false } },
    { "check": "cpu.smt", "tier": "verify", "on_fail": "warn" },
    { "check": "gpu.device", "tier": "enforce", "parameters": { "index": 0 } },
    { "check": "gpu.clocks-locked", "tier": "verify", "on_fail": "refuse", "parameters": { "mhz": 1500 } },
    { "check": "accel.sync", "tier": "enforce", "parameters": { "mode": "device-sync" } },
    {
      "check": "load.quiescent",
      "tier": "verify",
      "on_fail": "refuse",
      "parameters": { "max_1m_load": 2, "window_s": 60 }
    },
    {
      "check": "hardware.present",
      "tier": "verify",
      "on_fail": "refuse",
      "parameters": { "cpu_model_pattern": "*", "gpu_count": 1, "min_ram_bytes": 34359738368 }
    },
    { "check": "tree.clean", "tier": "verify", "on_fail": "refuse" },
    {
      "check": "thermal.throttle",
      "tier": "verify",
      "on_fail": "warn",
      "parameters": { "counters": ["thermal_throttle_count"] }
    },
    { "check": "thermal.temperature", "tier": "record", "parameters": { "sample_interval_s": 5 } }
  ]
}