Conformance Levels

HushSpec defines four conformance levels. Each level subsumes the levels below it. On main, the Rust, TypeScript, Python, and Go SDKs all implement the published evaluator fixture corpus; see the SDK Conformance Matrix for the per-language feature breakdown.

Quick Reference#

Level	Name	Requirements	Use Case
0	Parser	Parse valid YAML, reject invalid YAML, require `hushspec`	Any tool that reads HushSpec documents
1	Validator	Type checking, unknown field rejection, enum validation, uniqueness constraints, regex validation	Editors, linters, schema validators, authoring tools
2	Merger	Resolve `extends`, implement all three merge strategies, reject cycles	Composers, loaders, and policy distribution tools
3	Evaluator	Accept actions, produce structured decisions, implement precedence, pass evaluator fixtures	SDK evaluators, middleware, and full security engines

Level 0: Parser#

A Level 0 implementation can:

Parse valid HushSpec YAML into a structured representation
Reject syntactically invalid YAML
Reject documents that omit the required hushspec version field

Level 1: Validator#

A Level 1 implementation additionally:

Validates field types and constraints
Rejects unknown fields at any nesting level
Validates enum values such as severity, mode, default, and merge_strategy
Enforces uniqueness constraints such as secret-pattern names
Validates numeric constraints and regex syntax

Level 2: Merger#

A Level 2 implementation additionally:

Resolves extends references via at least one strategy such as filesystem or built-ins
Implements deep_merge, merge, and replace
Detects and rejects circular inheritance

Level 3: Evaluator#

A Level 3 implementation additionally:

Accepts an action plus a resolved HushSpec document
Produces a structured result with a final allow, warn, or deny decision
Implements strict precedence: deny > warn > allow
Passes the published evaluator fixtures, which are versioned and schema-validated

Action Types#

A Level 3 evaluator must handle the published action vocabulary:

file_read - reading a filesystem path
file_write - writing to a filesystem path
patch_apply - applying a diff or patch
shell_command - executing a shell command
tool_call - invoking a tool or MCP function
egress - making an outbound network request
computer_use - performing a computer-use action
input_inject - injecting keyboard, mouse, or touch input

Decision Precedence#

When multiple rules apply to the same action, the most restrictive decision wins. A single deny overrides any number of warn or allow outcomes, and a warn overrides allow.

Audit Trail#

Decision receipts are not part of the level definition itself, but a production-quality Level 3 implementation should be able to emit structured decision receipts with the matched rule path and reason. The receipt contract is defined in hushspec-receipt.v0.schema.json.

Testing Conformance#

The authoritative conformance corpus lives in the fixtures/ directory. Fixtures are grouped by specification module:

fixtures/core/
fixtures/posture/
fixtures/origins/
fixtures/detection/

Each module contains one or more of these categories:

Subdirectory	Purpose	Conformance Level
`valid/`	Documents that must parse and validate successfully	Level 0 & 1
`invalid/`	Documents that must be rejected during validation	Level 1
`merge/`	Base/child pairs with expected merge results	Level 2
`evaluation/`	Policies with action/decision test cases	Level 3

Evaluation Fixture Format#

Level 3 fixtures embed a policy and a list of action cases:

yaml

hushspec_test: "0.1.0"
description: "Egress rule evaluation"

policy:
  hushspec: "0.1.0"
  rules:
    egress:
      allow:
        - "*.openai.com"
      default: "block"

cases:
  - description: "Allowed domain passes"
    action:
      type: "egress"
      target: "api.openai.com"
    expect:
      decision: "allow"

  - description: "Unknown domain is blocked"
    action:
      type: "egress"
      target: "evil.example.com"
    expect:
      decision: "deny"

The schema for this fixture format is hushspec-evaluator-test.v0.schema.json.

How the Repo Verifies It#

There is no single generic “run conformance against an arbitrary SDK” command. Instead, the reference repository verifies conformance through native test suites and CI:

Each SDK loads the same fixture corpus in its own test harness
The shared-fixtures CI job runs those fixture-driven tests across Rust, TypeScript, Python, and Go
The cross-sdk-roundtrip CI job compares normalized outputs across SDKs

For policy authors, h2h test is still useful for exercising evaluator fixtures locally:

bash

# Run one evaluator fixture
h2h test fixtures/core/evaluation/egress.test.yaml

# Run every evaluator fixture in a directory
h2h test --fixtures fixtures/core/evaluation/

# Override the embedded fixture policy while iterating locally
h2h test --policy policy.yaml --fixtures ./tests/