The Healing Engine

Yamlr operates as the Kubernetes Configuration Resolution Plane, bridging diagnostic discovery and automated remediation.

The Healing Engine was built to execute multi-file manifest repairs deterministically without introducing typographical regressions, indentation shifts, or dropping critical developer comments.

1. Visual Diffing & Dry-Run Verification

Safety is the foundational trust pillar of Yamlr. By default, yamlr heal operates safely:

bash
# Preview unified diffs without modifying a single byte on disk
yamlr heal manifests/ --dry-run
# or use the dedicated diff viewer:
yamlr diff manifests/

Before writing to disk, Yamlr renders a color-coded unified diff showing the exact AST mutations proposed. To apply changes atomically:

bash
# Atomically apply validated remediations to disk
yamlr heal manifests/ --apply

2. 3-Tier Integrity Gate

The Healing Engine operates on a principle of absolute architectural integrity. When a manifest is repaired, Yamlr passes the mutated Concrete Syntax Tree (CST) through a strict 3-tier validation gauntlet before committing the write:

[PHY] (The Physical Syntax Layer): Validates YAML syntax, indentation boundaries, scalar quoting, and list-marker closures.
[KBS] (The Kubernetes Schema Layer): Validates the resource against the official Kubernetes OpenAPI schema for the target version (defaulting to 1.30).
[SEM] (The Cross-Resource Semantic Layer): Validates the ResourceGraph for relational consistency (e.g., verifying that a repaired Service selector matches real Deployment labels, and that referenced ConfigMap keys exist).

If a proposed remediation fails any of these three layers, Yamlr aborts the write and flags the issue for manual engineering review.

3. Comment-Preserving Concrete Syntax Tree (CST)

Traditional YAML parsers deserialize into unstructured dictionaries, discarding comments, blank lines, and custom indentation when writing back out.

Yamlr employs a native Concrete Syntax Tree (CST) engine:

Preserves all # developer comments, licensing headers, and inline explanations.
Retains existing multi-line string formatting (literal | and folded > blocks).
Fixes structural errors (e.g., Map vs. List mismatches such as env: { name: "DB" } to env: [ { name: "DB" } ]) in-place without context loss.

4. Atomic Write-Ahead Logging (WAL) & Rollback

Engineers require unconditional reversibility before allowing automated tools to touch GitOps repositories.

Yamlr integrates an Atomic Write-Ahead Log (WAL) engine:

Prior to modifying any file on disk, Yamlr journals the exact file state to .yamlr/wal/.
If an interruption or unexpected outcome occurs, execute yamlr rollback to immediately restore manifests to their pre-mutation state.

bash
# Instantly roll back to previous verified state
yamlr rollback manifests/