Mapping-set selection and rc.2 x-oold-context transform

[simontaurus]

Changes

• oold.utils.mappings (new): promote, mapping_sets, chain, context_of, synonym_entries. This is the profile-based selection OOLD-EXT-4966 describes; it complements validation.context_resolution.promoted_terms, which deliberately never chooses a synonym (OOLD-EXT-8f62). Ported from oold-reference-schemas/scripts/{_shared,build_docs}.py and verified equivalent against that implementation on the quantities module (all schemas, all three mapping sets plus consensus). Two deliberate extensions over the port: mapping_set_id may be a list (the spec allows it), and a @reverse synonym promotes to @reverse rather than an invalid @id+@reverse pair.
• oold.utils.transform (replaced): to_rdf / from_rdf / transform over x-oold-context. Export promotes a named set; import rewrites every exactMatch synonym onto the primary IRI (no set needed), inverts @reverse relations, frames @graph input via validation.frame.schema_to_frame, and bridges document shapes when a promoted fragment carries @nest and a set is named. Readings A/B/C/E of Mapping-set selection can bridge document shapes via @nest, and the spec should say so oold-schema#135 are reproduced exactly and pinned as regression tests, including the boundary that vocabulary is bridged without a selection and shape is not.
• tests/test_transform.py rewritten: the name* alias cases are re-encoded as x-oold-context with the same inputs and expected outputs, so the change of notation provably does not change what the transformation produces.

Breaking change

jsonld_to_jsonld / json_to_json and the pre-spec name* alias notation are removed. Only tests/test_transform.py referenced them in this repository. The commit is deliberately typed feat: rather than feat!: so semantic-release does not force a major bump; retype if a major is wanted.

Verification

• 618 passed, 8 skipped on top of current main; make check green.
• First consumer: schema-playground in https://github.com/OO-LD/oold-playgrounds/tree/feat/schema-playground vendors exactly these modules pending this PR; once released they can be deleted there.

Closes the mappings/transform part of the migration listed in https://github.com/OO-LD/oold-playgrounds/blob/feat/schema-playground/schema-playground/README.md#pending-upstream-migration

[github-actions]

Release preview

Merging this PR would release v0.21.0 (current: v0.20.0).

Changelog preview (truncated)

## v0.21.0 (2026-09-12)

### Documentation

- **validation**: Correct how pyld actually fails on each count
  ([#150](https://github.com/OO-LD/oold-python/pull/150),
  [`4556612`](https://github.com/OO-LD/oold-python/commit/455661251a7ca5681608a0c2391dd77ae0e33775))

- **validation**: Document the fault status in the how-to
  ([#152](https://github.com/OO-LD/oold-python/pull/152),
  [`6b31fd3`](https://github.com/OO-LD/oold-python/commit/6b31fd37af1c9c97b9a4aecb5d3583f9aa30ccf6))

- **validation**: Give the context walker a true justification
  ([#150](https://github.com/OO-LD/oold-python/pull/150),
  [`4556612`](https://github.com/OO-LD/oold-python/commit/455661251a7ca5681608a0c2391dd77ae0e33775))

- **validation**: State what --offline pins and what nothing pins
  ([#149](https://github.com/OO-LD/oold-python/pull/149),
  [`abcad76`](https://github.com/OO-LD/oold-python/commit/abcad7665a235169eab7465e16f36b4aefda92e4))

### Features

- **utils**: Mapping-set selection and rc.2 x-oold-context transform
  ([`156b9b0`](https://github.com/OO-LD/oold-python/commit/156b9b0e4a95732c8059cbd060610d1413047a2c))

### Testing

- **validation**: Check context equality over every schema, not thirteen
  ([#153](https://github.com/OO-LD/oold-python/pull/153),
  [`d47f39e`](https://github.com/OO-LD/oold-python/commit/d47f39e95a748531f15eca4b3bbf1de9159bff7d))

- **validation**: Pin the pyld equivalence the docstring argues from
  ([#150](https://github.com/OO-LD/oold-python/pull/150),
  [`4556612`](https://github.com/OO-LD/oold-python/commit/455661251a7ca5681608a0c2391dd77ae0e33775))

_{Preview via python-semantic-release and conventional commits.}

[github-actions]

📊 Benchmark Results

Click to see benchmark comparison

📊 Benchmark Comparison (threshold: 1.3x)
============================================================

⚠️  Performance Regressions:
  ❌ test_complex_graph: 0.0011s → 0.0017s (+55.3%, ratio: 1.55x)

✅ Performance Improvements:
  ✅ test_subclass_inheritance: 0.0543s → 0.0405s (-25.3%, ratio: 0.75x)

➖ Unchanged (within threshold):
  ➖ test_simple_dict_document_store: 0.0012s → 0.0012s (+0.7%)
  ➖ test_sqlite_document_store: 0.0013s → 0.0013s (+0.8%)
  ➖ test_local_sparql_store: 0.0289s → 0.0286s (-1.2%)
  ➖ test_oneof_subschema: 0.0438s → 0.0465s (+6.2%)
  ➖ test_enum_docstrings: 0.0402s → 0.0441s (+9.7%)
  ➖ test_class_hierarchy: 0.0372s → 0.0441s (+18.5%)
  ➖ test_core[v1]: 0.0279s → 0.0348s (+24.7%)
  ➖ test_core[v2]: 0.0328s → 0.0384s (+17.2%)
  ➖ test_schema_generation[v1]: 0.0012s → 0.0012s (-0.2%)
  ➖ test_schema_generation[v2]: 0.0020s → 0.0020s (-0.4%)
  ➖ test_simple_json: 0.0004s → 0.0005s (+18.6%)

============================================================
Summary: 1 regressions, 1 improvements, 11 unchanged
============================================================

⚠️  Regressions detected but not failing build (informational only)

Threshold: 1.3x (30% slower triggers a regression warning)

Note: Benchmarks are informational only and won't fail the build.

_{💡 Tip: Download the benchmark-results artifact for detailed JSON data}

[codecov]

Codecov Report

❌ Patch coverage is 87.68473% with 25 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/oold/utils/transform.py	86.2%	7 Missing and 8 partials ⚠️
src/oold/utils/mappings.py	89.3%	4 Missing and 6 partials ⚠️

📢 Thoughts on this report? Let us know!