Repository navigation
Description
The docs promise a check that the code doesn't make. docs/value-sets.md#the-text-form-contract says:
A decorative format (
"CUST-{value}") fails loudly at the persistence boundary with an error naming the contract.
For the core wrapper arities that's only true when the decoration is something the primitive's grammar rejects. A decorated string, or a number that's simply wrong, is written without complaint, and can come back as a different element (#53).
For 9.1.0, state the contract as it really is and say what isn't checked yet:
- The contract: an element's
ToString(format, invariant)andParse(text, invariant)must be exact inverses.Parse(element.ToString())returns an element equal to the original, and the text is the backing primitive's own form. - What's checked today: the five NodaTime arities check the round trip. The integer, decimal, Guid and temporal arities reject only text their primitive can't parse.
StringSet<T>checks nothing, because any text is a valid string. - What breaks if it's violated: data that can't be read back, or a value that changes on every round trip, with no error.
- The fix: 10.0.0 checks the round trip for every arity (Wrapper set arities don't check that an element's text form round-trips #53).
Pages: docs/value-sets.md (the contract section and its table), docs/architecture.md (the text-form contract paragraph and the BridgedElementTypeMapping bullet, which says the contract "fails loudly here"), and the value set XML docs if they repeat the promise.
Coordination:
- Adopt the plain-docs voice and rewrite the consumer docs in it #38 rewrites
docs/value-sets.mdin the plain-docs voice, so write this on top of it. - Claim
S07-decorative-format-fails-loudlyintest/oracles/claims.jsonquotes the sentence above. Re-anchor it to the corrected text, and keep the Wrapper set arities don't check that an element's text form round-trips #53 candidate rows registered: the behaviour stays wrong until 10.0.0.
Activity
CaffeinatedCoder commentedon Oct 17, 2026
Moved off 9.1.0 into the backlog (#83), with no milestone.
release/9.xhas been cut, and 9.1.0 ships with the work that's already finished. Nothing has started on this issue, and it shouldn't hold up the tag. Docs, tests and internal work aren't tied to a version, so this doesn't need a milestone until someone picks it up.When someone picks it up, it goes under the epic of the release it will ship in and takes that milestone. A 9.x minor would need the change cherry-picked onto
release/9.x.CaffeinatedCoder commentedon Oct 18, 2026
Superseded by #53 (10.0.0).
docs/value-sets.md#keep-the-text-form-of-the-underlying-typenow states the contract as the code enforces it: the whole round trip is checked on every write and read for every core arity, with the exception types and a "Before 10.0, only the grammar was checked" note, and claimS07-decorative-format-fails-loudlyis anchored to that text. The 9.1.0 interim wording this issue asked for is no longer needed.