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
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
//! Inject declared items into config files owned by another program.
//!
//! A config file you want to manage from a repository is often not yours alone.
//! The application writes to it too — a model choice, a remembered permission, a
//! UI toggle. Owning the whole file (symlink, template render, `cp`) throws
//! those away. Owning nothing means the repository cannot configure anything.
//!
//! So this crate injects *items* and leaves everything else alone. One rule
//! covers every operation: **apply what is provably ours, report what is not,
//! never overwrite a disagreement.**
//!
//! # The unit is an item, not a file format
//!
//! Managing config from above means declaring, per item, what its value should
//! be. Whether that item lives at a key path in a JSON document, inside a
//! marker-delimited span of a text file, or as a file in a directory is a
//! question of *representation* — how the item is addressed, read, and written.
//! It does not change what the management decision is.
//!
//! That split is the whole architecture:
//!
//! - [`policy`] decides. One table, no knowledge of any format.
//! - [`port::Store`] is the interface a representation implements.
//! - [`adapter`] holds the implementations ([JSON documents][adapter::json],
//! [marker-delimited spans][adapter::marker]).
//! - [`engine`] walks the items and applies the decisions.
//! - [`prior`] persists provenance for representations that cannot hold it
//! inline.
//!
//! Adding a representation means adding an adapter. No other module changes.
//!
//! # Three inputs, not two
//!
//! The central invariant: **a decision needs three values, not two.**
//!
//! | | |
//! |---|---|
//! | `declared` | what the repository says the value should be |
//! | `prior` | what this tool wrote on its last run |
//! | `observed` | what is in the target right now |
//!
//! Comparing only `declared` against `observed` cannot answer the question that
//! matters, which is *who wrote the value that is there*. Without `prior`, a
//! value this tool wrote itself is indistinguishable from a value the other
//! program wrote, so every change to a declaration looks like a conflict and no
//! value can ever be updated or withdrawn.
//!
//! `prior` collapses that ambiguity into [`port::Ownership`], which is what the
//! policy actually branches on. The same three-way shape is what Terraform
//! compares (configuration, state, remote) and what Kubernetes server-side apply
//! records per field manager.
//!
//! # The contract
//!
//! [`policy::decide`] is total over this table and nothing else decides
//! anything:
//!
//! | declared | ownership | observed | decision | why |
//! |---|---|---|---|---|
//! | yes | `Unknown` | absent | `Add` | first run |
//! | yes | `Unknown` | equal | `Skip` | already agreed; ownership is recorded, adopting the item |
//! | yes | `Unknown` | differs | `Refuse(Conflict)` | ownership cannot be claimed, so the value stays |
//! | yes | `Ours` | equal | `Skip` | already correct |
//! | yes | `Ours` | differs | `Update` | the old value is provably ours |
//! | yes | `Diverged` | any | `Refuse(HandEdited)` | someone changed what we wrote |
//! | yes | `Removed` | absent | `Refuse(RemovedByOther)` | the deletion was deliberate; do not resurrect it |
//! | no | `Ours` | present | `Retract` | ours, and no longer declared |
//! | no | other | any | `Skip` | not ours |
//!
//! Two properties follow, and both are relied on elsewhere:
//!
//! - **Nothing is written or removed unless ownership is `Ours`**, except `Add`,
//! which writes only where there was nothing.
//! - **Re-running with an unchanged declaration produces only `Skip`.** Every
//! decision that changes the target moves ownership to `Ours` with the
//! declared value, which is the `Skip` row on the next run.
//!
//! # Provenance lives wherever the representation allows
//!
//! Ownership requires remembering what was written. Where that record lives is
//! the adapter's choice, because it depends on what the target can carry:
//!
//! | adapter | provenance |
//! |---|---|
//! | [`adapter::marker`] | inline — a digest in the begin marker |
//! | [`adapter::json`] | side-car, via [`prior`] |
//!
//! Text can hold a comment, so a marker-delimited region is self-describing and
//! needs no external file. JSON cannot hold a comment, and adding a reserved key
//! to another program's document would be a modification that program never
//! asked for and might reject. So JSON provenance goes to a side-car file that
//! belongs to this tool.
//!
//! Provenance is local to the machine holding the target, never to the
//! repository holding the declaration: it records what was written *here*, and
//! two machines will legitimately differ.
//!
//! **When provenance is unavailable** — a lost side-car, a target read from
//! stdin — every item reads as [`port::Ownership::Unknown`]. The table above
//! then permits only `Add` and `Skip`, so the tool degrades to add-only. That is
//! a loss of capability, never a loss of data.
//!
//! # Values cross the port as text
//!
//! Items carry a [`port::Repr`]: the value in a canonical textual form. The core
//! compares and displays reprs and never inspects their structure.
//!
//! This is deliberately *not* a shared intermediate representation. Each adapter
//! canonicalises into its own dialect and parses back from it, so a TOML value
//! would round-trip through TOML text rather than through JSON. Routing every
//! format through one structural type would silently drop what that type cannot
//! hold — comments, key order, and the distinctions between a TOML datetime, an
//! integer, and a float — which is precisely the data this crate exists to
//! preserve.
//!
//! # Example
//!
//! ```
//! use cfggraft::policy::{decide, Decision};
//! use cfggraft::port::{Observed, Ownership, Repr, State};
//!
//! // A value this tool wrote last run, with the declaration since changed.
//! let state = State::new(Observed::Present(Repr::new("\"1\"")), Ownership::Ours);
//! assert_eq!(decide(Some(&Repr::new("\"2\"")), &state), Decision::Update);
//!
//! // The same observation without provenance is not ours to touch.
//! let state = State::new(Observed::Present(Repr::new("\"1\"")), Ownership::Unknown);
//! assert!(matches!(decide(Some(&Repr::new("\"2\"")), &state), Decision::Refuse(_)));
//! ```
//!
//! # Adding an adapter
//!
//! Implement [`port::Store`] and add a variant to [`adapter::Adapter`]. The
//! trait is six methods: expand the declaration into items, list what was owned,
//! report an item's state, write, retract, and finish. Decisions, reporting,
//! exit codes, and the `--force` and `--retract` policies are already handled.
//!
//! Dispatch is an enum rather than a trait object because the set of adapters is
//! closed within this crate; the trait exists to state the contract an adapter
//! must meet.
// This crate's contract *is* its documentation, so an undocumented public item
// is an unstated contract rather than a missing nicety.
pub use ;