quadlet-lens 0.1.0

Loss-aware parsing, validation, and rendering of version-aware Quadlet documents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

# API stability policy

QuadletLens is pre-1.0, but version 0.1 establishes a supported integration line for BoxFerry and
independent tools that need native Quadlet parsing, modeling, document-set resolution, and
evidence-backed Podman capability queries. This policy is recorded by
[ADR 0008](decisions/0008-versioned-public-api-and-release-contract.md).

## The 0.1.x contract

Within the 0.1.x line:

- patch releases preserve source compatibility for the supported public entry points;
- public APIs use QuadletLens-owned types;
- the module paths exercised by `tests/public_api.rs` remain available;
- diagnostic code strings remain machine-readable contracts;
- preservation rendering stays byte-identical and canonical syntax rendering remains
  deterministic for the same valid input;
- parsing, modeling, document-set resolution, capability evaluation, and rendering perform no
  filesystem discovery, process execution, unit installation, or runtime mutation; and
- all supported public APIs compile on Rust 1.85.0 or newer.

Bug fixes may change a result that contradicted these contracts or retained conformance evidence.
Such a change needs a regression test and changelog entry. A patch release must not silently drop
authored syntax, flatten repeated entries, expand systemd specifiers, or broaden capability
evidence beyond reviewed ranges.

## Supported entry points

| Concern | Public modules |
| --- | --- |
| Source and diagnostics | `source`, `diagnostic` |
| Loss-aware syntax and rendering | `syntax` |
| Native typed documents and document sets | `model`, `path` |
| Versioned Podman capability evidence | `capability` |

The compile-and-behavior contract in `tests/public_api.rs` exercises these stages as an external
crate consumer would. The modules remain separate: QuadletLens does not hide source loading,
target selection, filesystem lookup, Podman execution, or systemd operations behind a convenience
API.

## Changes before 1.0

An intentional public break requires the next 0.x minor version, migration guidance in the release
notes, and an ADR when the architecture changes. Consumers that cannot absorb that cadence should
use an exact dependency requirement or commit their lockfile.

Enums intended to grow are marked `#[non_exhaustive]` before the first release. Existing public
enums without that marker require a breaking release when adding a variant would break exhaustive
matches.

## Not promised by 0.1

The 0.1 contract does not claim:

- complete coverage of every Quadlet unit type, key, or systemd value grammar;
- typed target-aware rendering;
- runtime, rootless/rootful, SELinux, cgroup, network, or systemd activation behavior;
- support evidence beyond the finite catalogue range or its capability-specific evidence; or
- long-term 1.x compatibility.

Before 1.0, the project will define supported release lifetimes, deprecation periods, and the 1.x
diagnostic-code policy through a superseding ADR.