docs: record final-review follow-ups (deployed-snapshot normalization gap I-1; CLI native-form help example)

This commit is contained in:
Joseph Doherty
2026-06-16 18:34:34 -04:00
parent c53b621b85
commit dc9f31537a
@@ -60,5 +60,19 @@ Already-exported `.bundle` files are external artifacts we cannot reach to rewri
## Out of scope / follow-ups
- **Deployed-config snapshot is a fourth, un-normalized List-value store (latent gap, I-1).**
`DeployedConfigSnapshot.ConfigurationJson` + `RevisionHash` freeze the flattened config at
deploy time. The staleness/diff path (`DeploymentService.GetDeploymentComparisonAsync`
`DiffService.AttributesEqual` ordinal compare + `RevisionHashService` SHA over the raw
`Value`) compares that frozen blob against a freshly-flattened (now native-form) config. If a
List attribute was ever *deployed* in old-form, the snapshot stays old-form → a spurious
"Changed" diff + false staleness flag until redeployed. This **cannot fire against current
data** (no List attributes were ever deployed — see the Reality Note), so it is recorded as a
known latent gap, not fixed. If hardening is wanted before List attributes are deployed at
scale: route the deserialized snapshot's List values through `Decode→Encode` in
`GetDeploymentComparisonAsync` before the diff/hash (symmetric with the other normalizers).
- CLI `template attribute` help still illustrates `--value` with a quoted string-list example;
add a native-form numeric example (e.g. `[10,20]`) so users don't hand-author quoted numbers
that get silently re-normalized. Doc-only; the quoted form still decodes.
- Rewriting already-exported bundle files (unreachable).
- This pairs naturally with follow-up **#93/M3** (populate `InstanceAttributeOverride.ElementDataType` on write); if done, the override normalizer could read the column directly instead of joining to the template attribute. Not required here.