Skip to content

docs: fix six SPEC.md text-accuracy issues - #152

Merged
OmarAlJarrah merged 1 commit into
mainfrom
e7-specmd-accuracy
Jul 20, 2026
Merged

docs: fix six SPEC.md text-accuracy issues#152
OmarAlJarrah merged 1 commit into
mainfrom
e7-specmd-accuracy

Conversation

@OmarAlJarrah

@OmarAlJarrah OmarAlJarrah commented Jul 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Summary

  • Removed [CONF-104]'s query pair-count DoS cap, which directly contradicted [ERR-32] and [QUERY-24] (and pointed its own cross-reference at the section that contradicts it); the shipped QueryParameters code and the two more specific requirements already agree there's no cap.
  • Brought section 12.2's UriParseError catalog in line with the shipped sealed interface: dropped the nonexistent InvalidAuthority variant and the offset fields on EmptyHost/InvalidPort that don't exist in code, fixed InputTooLong's and LimitExceeded's field types (Int, not Long), and added the shipped LimitExceeded and the two Iri* variants that were missing. LimitExceeded/ResourceLimit are documented as implemented (they now ship in the codebase), and [ERR-18] describes the two IRI-only variants. Also noted that an unterminated IPv6 authority (http://[::1/) surfaces as InvalidHost/Ipv6Malformed, not a separate authority-level error.
  • Fixed [MODEL-14]/[MODEL-16]/[MODEL-21], which named the Host variant properties ascii/raw/encoded — the shipped Host.kt names all three value.
  • Removed "user, password" from [MODEL-46]'s nullable-accessor list: Url exposes non-null username/password, and Uri has no per-field accessors at all; [MODEL-48]/[NORM-30] already describe this correctly elsewhere.
  • Renumbered the later-defined halves of the duplicated [NORM-30]/[NORM-31] tags to [NORM-33]/[NORM-34] and updated the Appendix A index; the code comments that cite [NORM-30]/[NORM-31] already point at the earlier (unchanged) definitions, so no source changes were needed.
  • Changed the abstract's "Kotlin/JVM library" to "Kotlin Multiplatform library" to match the rest of the document and the actual target list (jvm, js, wasmJs, android, native).

All changes are text-only edits to docs/SPEC.md; no code was touched.

Test plan

  • Proofread the full diff against the current content of docs/SPEC.md and the actual shipped code it describes (UriParseError.kt, Host.kt, ResourceLimit.kt, QueryParameters.kt, SerializeShared.kt/UriSerializer.kt/UrlSerializer.kt).
  • Confirmed no NORM-30/NORM-31 code citations needed updating (they all reference the definitions that kept their original tags).
  • Rebased onto current main: the resource-limit feature has since landed, so ResourceLimit/LimitExceeded are documented as implemented (with Int field types) rather than deferred, and the catalog keeps the shipped LimitExceeded variant.
  • Doc-only change; no Gradle build required per repo policy.

Closes #108
Closes #109
Closes #116
Closes #120
Closes #121
Closes #122

@OmarAlJarrah
docs: align SPEC.md error/host/model catalogs with the shipped code
41ef214 
Bring several normative catalogs in docs/SPEC.md back in line with the code
they describe:

- 12.2 UriParseError catalog: drop the non-existent InvalidAuthority variant
  and the offset fields on EmptyHost/InvalidPort that the code does not carry,
  correct InputTooLong/LimitExceeded field types to Int, and add the two
  shipped IriInvalidCodePoint / IriBidiFormattingCharacter variants that were
  missing. [ERR-10] and the reject/normalize table now describe an
  unterminated authority as surfacing through the host variants
  (InvalidHost/Ipv6Malformed, ForbiddenHostCodePoint) rather than a dedicated
  authority error, and [ERR-18] documents the two IRI-only variants.
- 3 Host catalog: RegName/IpFuture/Opaque expose their payload as `value`
  (not ascii/raw/encoded), matching Host.kt; [MODEL-16]/[MODEL-21] and the
  Appendix A rows follow.
- [MODEL-46]: drop `user`/`password` from the nullable-accessor list — Url
  exposes non-null username/password and Uri has no per-field accessor.
- Remove [CONF-104]'s query pair-count DoS cap, which contradicted the no-cap
  rule now stated explicitly in [ERR-32]; QueryParameters applies no such cap.
- Renumber the duplicated [NORM-30]/[NORM-31] tags (the toUrl bridge pair) to
  [NORM-33]/[NORM-34] and reorder the Appendix A index; the kept definitions
  and every code/doc citation continue to point at the originals.
- Abstract: describe kuri as a Kotlin Multiplatform library, matching the
  target list.
@OmarAlJarrah
OmarAlJarrah merged commit 2bb3c98 into main Jul 20, 2026
15 checks passed
@OmarAlJarrah
OmarAlJarrah deleted the e7-specmd-accuracy branch July 20, 2026 17:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment