Skip to content

State the real text-form contract for wrapper sets, and what isn't checked yet #59

Closed

Description

@CaffeinatedCoder

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) and Parse(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:

Activity

  1. added this to the 9.1.0 milestone on Oct 17, 2026
  2. removed this from the 9.1.0 milestone on Oct 17, 2026
  3. CaffeinatedCoder commented on Oct 17, 2026

    @CaffeinatedCoder
    OwnerAuthor

    Moved off 9.1.0 into the backlog (#83), with no milestone.

    release/9.x has 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.

  4. CaffeinatedCoder commented on Oct 18, 2026

    @CaffeinatedCoder
    OwnerAuthor

    Superseded by #53 (10.0.0). docs/value-sets.md#keep-the-text-form-of-the-underlying-type now 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 claim S07-decorative-format-fails-loudly is anchored to that text. The 9.1.0 interim wording this issue asked for is no longer needed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/value-setsValue set families and wrapper aritiesdocumentationImprovements or additions to documentationpackage/coreAffects CodoMetis.ValueRanges

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions