Skip to content

test: pin the documented WL label form - #64

Merged
jdsika merged 1 commit into
mainfrom
test/pin-wl-label-form
Sep 18, 2026
Merged

jdsika merged 1 commit into
mainfrom
test/pin-wl-label-form

Conversation

@jdsika

@jdsika jdsika commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

Follow-up to #63, from an adversarial review of it.

The gap

docs/api.md (lines 47 and 534) documents generated blank-node labels as
b followed by 12 hex digits, with an optional numeric collision suffix.
Consumers match on that shape rather than merely checking that labels changed -
linkml asserts this exact form in three separate modules to confirm its
--diff-stable flag actually reached the serializer:

  • tests/linkml_runtime/test_utils/test_rdf_canonicalize.py
  • tests/linkml/test_scripts/test_diff_stable.py
  • .github/tests/test_diff_stable_install.py

Nothing in this repository defended that form. The wl tests check injectivity,
stability, cardinality and tie-suffix ordering, but never the label shape. So
widening the hash to 16 hex digits would have passed all 1259 tests, silently
falsified the documentation, and broken linkml - with the canary from #61 as the
first signal. That works, but it is an expensive way to discover that we changed
our own documented format.

Change

WL-LABEL-FORM in the requirement catalog, with two tests in
tests/wl/test_wl_contracts.py:

  • test_labels_have_the_documented_form - every label is b + 12 hex digits,
    and an untied label is exactly 13 characters
  • test_tied_labels_share_one_base_and_add_numeric_suffixes - tied nodes share
    one base and differ only by _1, _2, with the reported labels matching what
    wl_relabel_quads actually emits

Also

Two cleanups in #63's module, found in the same review: two tests took a
parse_format parameter they never used (ruff's selected rules E,F,W,B do not
flag unused arguments), and _reordered's docstring said "opposite order" while
the helper sorts descending.

Verification

1261 passed (2 new), coverage 96.01% against the 95% gate,
check_requirements.py verifies 50 supported requirements,
check_standards.py clean, ruff check src tests scripts clean.

No src/ change, so no behavior change, no emitted-byte change, and no
changelog entry or release.

docs/api.md states that generated blank-node labels are "b" followed by 12
hex digits, with an optional numeric collision suffix, and consumers match
on that shape rather than merely checking that labels changed: linkml
asserts this exact form in three separate modules to confirm its
--diff-stable flag reached the serializer.

Nothing here defended it. Widening the hash would have passed this suite,
silently falsified the documentation, and broken linkml, with the canary as
the first signal - an expensive way to learn we changed our own documented
format. Add WL-LABEL-FORM with positive evidence for the base form and
boundary evidence for the tie suffix.

Also drop a parameter two naturalistic-document tests never used, and
correct _reordered's docstring, which described the wrong ordering.
@jdsika
jdsika merged commit 2ae79c4 into main Sep 18, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant