Handling config parameters where the device mutates the value

[alexandernorth]

There are cases where a device might accept a value, but mutate it internally such that the next get request returns a deviating value. We should not re-apply the configuration in this case, as we are not changing the value.

This can happen for e.g. secrets where plaintext is applied and the device runs a hash and stores the hashed value. The next get would return the hashed value which would be a deviation and either reported or the plaintext re-pushed to the device.

We should have a system in place to ignore this deviation in certain cases.

[steiler]

Clarifying expectations for mutate-on-write leaves

Before diving into a solution, let's pin down what we're actually asking here — there are three separate open questions bundled into this issue:

1. What does "ignore deviation" actually mean for a leaf like this?
2. What triggers a re-push to the device, given data-server only pushes diffs?
3. How do we even know that a given leaf is a "write value != read value" kind of leaf?

These are genuinely separate decisions, so let's take them one at a time.

1. What should "ignore deviation" mean here?

Two candidate interpretations:

Option	Description	Verdict
Generic suppress-reporting flag	"Don't report a deviation on this path, full stop"	Rejected — we already have this shape of thing for non-revertive intents (report drift honestly, don't auto-correct); a generic ignore flag would hide real drift too, not just the expected mutation. Too dangerous.
A different comparison baseline	Compare Running against something other than the raw intent value, specifically for these leaves	Proposed — see below

2. What triggers a re-push?

Nothing new. The existing trigger is unchanged: a caller submits a TransactionSet whose merged intent value for that path actually changed. There's no background reconciliation loop today that re-pushes based on detected drift, and we shouldn't add one — that would reintroduce the exact unwanted-reapply problem this issue is trying to avoid.

3. How do we flag "this leaf mutates on write"?

Proposed: reuse the existing dual-source pattern already used for sensitive leaves rather than invent a new mechanism (details below).

---

Proposed mechanism: confirmed applied value

Answering (1) directly: introduce a new baseline, the confirmed applied value — the value read back from the device immediately after our own successful write for a given owner — and compare Running against that instead of the raw intent value, for leaves classified as mutate-on-write.

sequenceDiagram
    participant I as Intent (plaintext)
    participant DS as data-server
    participant Dev as Device
    participant R as Running

    I->>DS: TransactionSet (new value)
    DS->>Dev: apply (push plaintext)
    Dev-->>DS: read-back (mutated, e.g. hash)
    DS->>DS: store as "confirmed applied value" for (owner, path)
    DS->>R: write read-back value (not plaintext)
    Note over DS,R: Deviation check now compares<br/>Running vs confirmed applied value —<br/>not vs Intent — so the expected<br/>hash never reports NOT_APPLIED

Loading

• Capture: after a successful apply, for paths classified as mutate-on-write, do a targeted read-back and store it as the confirmed applied value for that (owner, path).
• Compare: deviation calculation diffs Running against this stored value instead of the intent's literal value, for that leaf only.
• Fallback: no confirmed value yet for the current owner → falls back to today's plain intent-vs-running comparison (a leaf that was never actually written still correctly reports NOT_APPLIED).
• Refresh: when the intent value changes and gets re-pushed, the old confirmed value is simply superseded by a fresh read-back — no separate invalidation step, which is why (2) needs no new trigger.
• Side benefit: this read-back also fixes a related bug — TransactionSet currently writes the pushed plaintext into Running optimistically, before any real confirmation (pkg/datastore/transaction_rpc.go:395). The targeted read-back fixes that for these leaves as a side effect.

Classification (answering 3): dual source, unioned

Same pattern as sensitive leaves, not a new mechanism:

Source	Sensitive-leaf precedent	Mutate-on-write equivalent
Schema-level	sdcio-ext:sensitive YANG extension (ADR 0003)	new extension, name TBD
Intent-level	sensitive_paths per-path marker at TransactionSet (#460)	analogous per-path marker
Combination rule	union (OR) across all non-running intents in merged views (ADR 0004)	same — union, since deviation computation is itself a merged view

Union beats "only the currently-winning owner's declaration" because ownership of a leaf can change hands over time; classification should stay stable regardless of who currently owns it. The confirmed-applied-value baseline itself still only ever belongs to the current owner (via the fallback above) — the two concerns don't need the same scoping rule.

Open questions before implementation

• Exact schema extension name (mutate-on-write is a placeholder).
• Read-back failure / async device settling (e.g. requires reboot/commit).
• Leaf-list instance handling — one classification per leaf-list, or per instance?
• Where the confirmed applied value is persisted, and its lifecycle across a datastore restart.
• Rollback interaction (TransactionCancel/timeout).

Full write-up: PRD on feature/mutate-on-write-leaf-deviations.