Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-0031: Unified Artifact Edit Engine with SSOT and Format Adapters

Status: accepted | Date: 2026-02-27

References: ADR-0029, ADR-0030, ADR-0001, ADR-0017, ADR-0007, RFC-0002

Context

govctl artifact editing has evolved from simple field updates into nested path edits (per ADR-0029) with parser hardening work (per ADR-0030). The current implementation now mixes parser logic, alias/legacy normalization, verb-path validation, dispatch generation, and artifact-specific read/write behavior across large files.

Problem Statement

We currently pay complexity twice:

  1. We maintain substantial command semantics in hand-written Rust control flow.
  2. We effectively treat JSON and TOML as separate operational paths in parts of the stack, even though the underlying operation is the same: read structured document, modify addressed node, validate, write.

This increases code volume, review difficulty, and risk of behavioral drift between artifacts and formats.

Before/After (architecture intent)

  • Before: parser + routing + validation + handlers are coupled, with format concerns leaking into command logic.
  • After: one semantic edit engine (parse -> canonicalize -> resolve -> plan -> validate -> execute) with thin format adapters.

Constraints

  • Preserve resource-first and verb semantics from RFC-0002 and ADR-0017.
  • Preserve index and matcher semantics from ADR-0007 (0-based indexing, negative indices from end, existing conflict diagnostics).
  • Preserve user-facing path syntax and compatibility promises from ADR-0029 and ADR-0030.
  • Respect storage decisions from ADR-0001: ADR/Work artifacts remain TOML at rest unless separately decided.
  • Keep deterministic diagnostics and stable error codes for automation scripts.

Options Considered

  • Option A: Continue incremental cleanup of current architecture.
  • Option B: Standardize internal editing on JSON only (convert TOML at boundaries, no dedicated TOML adapter contract).
  • Option C: Introduce a single SSOT-driven semantic edit engine with explicit JSON/TOML adapters.

Decision

We will adopt Option C: a single SSOT-driven semantic edit engine with explicit format adapters.

Core Architecture

  1. Single semantic pipeline for all artifacts and formats:
    • parse -> canonicalize -> resolve -> plan -> validate -> execute
  2. Single SSOT model (edit-model.json + JSON Schema) defines:
    • field tree, indexability, verb capability matrix
    • alias/legacy mapping and conflict policy
    • validator bindings and handler IDs
  3. Single execution engine consumes typed EditPlan operations.
  4. Thin format adapters implement storage-specific read/write behavior:
    • JsonAdapter
    • TomlAdapter

Parser Selection

Per ADR-0030, parser implementation will use winnow (not a grammar generator), while grammar remains documented in PEG/EBNF style.

Field-token acceptance is strict:

  • parser accepts syntactic segments
  • resolver accepts only SSOT-known canonical fields/aliases
  • unknown fields fail with deterministic diagnostics

Compatibility and Convergence Policy

  • Existing path syntax and legacy forms from ADR-0029 remain supported during migration.
  • Canonical names take precedence over aliases on conflict.
  • Documentation will prefer canonical path syntax; legacy forms are compatibility-only.
  • Legacy form deprecation warnings begin after full V2 parity is reached.

Migration Plan

  1. Phase 1 (foundation): Introduce V2 SSOT, parser, typed EditPlan, and adapter interfaces behind feature-gated path.
  2. Phase 2 (shadow mode): Run V1 and V2 for ADR/Work operations; compare planned ops and rendered outcomes in tests.
  3. Phase 3 (cutover): Switch ADR/Work to V2, then RFC/Clause.
  4. Phase 4 (cleanup): Remove V1 dispatch branches, remove hand-written artifact/field/verb matches, tighten lint/test gates.

Completion Criteria

V2 is considered complete only when:

  • adding a new editable field requires SSOT changes only (no manual dispatch branching)
  • JSON and TOML share one semantic engine
  • compatibility test suite for legacy paths passes in V2 mode

Consequences

Positive

  • Reduces long-term maintenance cost by centralizing edit semantics in one engine.
  • Eliminates JSON/TOML behavioral drift risk by sharing the same plan/validation pipeline.
  • Makes parser and resolver behavior auditable through SSOT and generated tables.
  • Improves extensibility: new fields and verbs are primarily SSOT additions.

Negative

  • Migration complexity is significant because V1 and V2 must coexist temporarily.
    • Mitigation: enforce a bounded coexistence window (max two releases) with explicit phase exit criteria and deletion checklist.
  • Generator/SSOT errors can affect many paths at once.
    • Mitigation: schema validation at build-time, generated-table snapshot tests, and golden command fixtures per artifact/verb.
  • Temporary dual operation styles (legacy vs canonical path forms) can confuse users.
    • Mitigation: docs prefer canonical syntax immediately; legacy usage prints guidance warnings after V2 parity milestone.
  • Documentation and contributor onboarding work increases initially.
    • Mitigation: track docs updates as required migration work items and block V2 cutover completion until docs/tests are updated.

Neutral

  • Runtime overhead should remain negligible for CLI-scale paths, but this will be measured with parser and end-to-end micro-benchmarks before finalizing ADR status.

Alternatives Considered

Option A: Continue incremental cleanup on current architecture (rejected)

  • Pros: Lowest immediate implementation risk, No major migration event required
  • Cons: Continues structural duplication and code growth, Does not solve JSON/TOML semantic divergence risk
  • Rejected because: It optimizes short-term churn but leaves the root architecture problem unsolved.

Option B: Standardize internal editing on JSON only (rejected)

  • Pros: Maximizes reuse of mature JSON tooling and standards, Simplifies internal document mutation mechanics
  • Cons: Introduces conversion boundary risk for TOML-only semantics and formatting expectations, Weakens direct TOML-at-rest operational clarity established by ADR-0001
  • Rejected because: It shifts complexity to conversion boundaries and does not provide a first-class TOML contract.

Option C: SSOT-driven semantic engine with explicit JSON/TOML adapters (accepted)

  • Pros: Preserves storage-format independence while unifying semantic behavior, Enables SSOT-driven extensibility with lower long-term maintenance cost
  • Cons: Requires staged migration and temporary dual-path operation, Demands high-quality generator and parity tests to avoid systemic regressions