Module diff 

Applyable policy diffs — “diffs as the lingua franca” (dx-spec §5).

Every suggestion Keel makes — keel init --diff adds/removes, doctor fix suggestions, and (future) keel flows add and keel mcp propose_policy — is emitted as an applyable diff, because agents apply diffs reliably and paraphrase prose unreliably. Callers describe a change as PolicyOps against the current keel.toml text; propose returns a Proposal:

• patch — a unified diff (a/keel.toml → b/keel.toml, or /dev/null when the file does not exist yet) that git apply or patch -p1 applies cleanly, \ No newline at end of file markers included.
• changes — structured {path, before, after} hunks for machines (comments are a text-level concern; they appear only in the patch).
• new_text — the full proposed file, for callers that write directly.

Edits are surgical: they operate on the TOML document (toml_edit), not a value round-trip, so user formatting and comments outside the touched regions survive byte-for-byte. Everything here is a pure function of its inputs — identical inputs yield byte-identical output (dx-spec §5).

Structs

ChangeHunk

One structured change: the TOML path plus the JSON value on each side (null = absent). Emitted depth-first over sorted keys — deterministic.

PolicyPath

A path into the policy document, segment by segment — e.g. ["target", "api.example.com", "retry"]. Display renders the TOML dotted-key form (target."api.example.com".retry), quoting segments that are not bare keys, so paths stay unambiguous even when a target name contains dots.

Proposal

The applyable result of propose: serialize it (or embed it in a larger report) and both audiences are served — patch for git apply, changes for structured consumption.

Enums

DiffError

Why a proposal could not be built.

PolicyOp

One edit to the policy document. Within a proposal, Set and Remove apply first (in order) as document surgery; every AppendBlock is then appended to the rendered text (blank-line separated), so pre-rendered blocks keep their comments verbatim.

Functions

propose

Build an applyable proposal: apply ops to current (the keel.toml text; None = the file does not exist, which is distinct from Some("") — it selects the /dev/null creation header) and return the patch + structured changes. Untouched regions of current survive byte-for-byte.

resolve_dotted_path

Resolve a serde_path_to_error-style dotted path (e.g. target.api.example.com.retry.attempts, where the target key itself contains dots) against the document, greedily matching the longest key at each level. Array indices (on[1]) are stripped. When the path descends into a non-table value with segments left over, the path to that value is returned — it is the entry to fix. Returns None when nothing matches.

unified_diff

Render a unified diff between two texts: git-compatible headers, three context lines, \ No newline at end of file markers. Lines are compared with their terminators, so a missing final newline diffs correctly. Deterministic — a pure function of its inputs.