Skip to content

Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.

align reads SKOS, scoring stops capping exact names, ties are reported, certify can fail, clashes get a command (#314)

Fabio Rovaifec2b4713bba
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1b47c802..7753be1e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -28,6 +28,38 @@ All notable changes to Open Ontologies are documented here.
reports `search_finished` and `constructs_not_modelled`, which now include
`owl:hasSelf`, property disjointness, `owl:AllDifferent` and restrictions on
datatype properties.
+- **`align` reads SKOS.** It read `owl:Class` only, so a pure SKOS taxonomy
+ produced zero candidates and said nothing about why. A `skos:Concept` is now
+ aligned with its preferred, alternative and hidden labels, its
+ `skos:broader`/`skos:broaderTransitive` parents, and its `skos:definition`
+ shown to the reviewer. An entity that is also an `owl:Class` is read as
+ before.
+- **A perfect name no longer caps at 0.85, and agreement no longer costs
+ confidence.** The weighted sum now averages over the signals that carry
+ evidence for the pair (`informative_signals`, `evidence_coverage`), and a
+ structural signal counts as support when the two sides share a feature the
+ other can name. The old fusion is `--scoring legacy` and reproduces the
+ published OAEI Anatomy figure byte for byte; the new default scores F1 0.833
+ there at the equivalent threshold. The default auto-apply threshold is 0.95
+ under the new scoring (0.85 under legacy), the same strictness on each scale.
+- **Ties are reported, never dropped.** A row stable matching kept over an
+ equally scored one names the loser under `tied_with`, is marked `ambiguous`,
+ and goes to review instead of into the graph. `--cardinality many-to-one`
+ keeps several source terms on one coarser target.
+- **`crosswalk-certify` compares only what can be compared.** An ancestor with
+ no counterpart through the mapping, on either side, is a coverage gap named
+ on the row and no longer downgrades it; a SKOS scheme's hierarchy is its
+ `skos:broader` closure, so the check can now fail on SKOS input; a row with
+ nothing to compare is `not_refuted_nothing_compared` rather than upheld; and
+ the SSSOM predicate column never strengthens a claim.
+
+### Added
+
+- **`crosswalk-probe`** (CLI subcommand and batch verb): carry a crosswalk's
+ subsumptions into the target and report the clashes they add. Witness
+ individuals make a TBox-only taxonomy able to clash; clashes the target has
+ on its own are reported apart. Exits 1 on a contradiction.
+
- Keep the last active ontology intact when parsing a replacement source, cache, or refresh fails; publish successful replacements in one graph transaction.
- Bound wildcard repository filtering to pattern/filename pairs so repeated stars cannot stall `onto_repo_list`.
- Sanitize quotes and ASCII control bytes in mapped IRI components so valid structured data does not fail RDF ingestion.
diff --git a/CLAUDE.md b/CLAUDE.md
index abd20e78..81b392d5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -98,7 +98,7 @@ Claude dynamically decides the next tool call based on what the previous tool re
| `onto_crosswalk` | To look up clinical terminology mappings (ICD-10 ↔ SNOMED ↔ MeSH) |
| `onto_enrich` | To add skos:exactMatch triples linking classes to clinical codes |
| `onto_validate_clinical` | To check class labels against clinical crosswalk terminology |
-| `onto_align` | To detect alignment candidates (equivalentClass, exactMatch, subClassOf) between two ontologies using 7 weighted signals (6 structural + embedding similarity when embeddings are loaded). Labels are matched with their parsed BCP-47 language tag; with the multilingual embedder loaded, cross-lingual pairs that share no surface tokens (e.g. `Dog`↔`Chien`) are admitted via the embedding signal. Restrict the languages consulted with `[language] preferred = [...]` / `OPEN_ONTOLOGIES_LANGUAGES` (empty = all) |
+| `onto_align` | To detect alignment candidates (equivalentClass, exactMatch, subClassOf) between two ontologies or SKOS vocabularies (`owl:Class` and `skos:Concept`; a concept's names include `skos:hiddenLabel` and its parents are `skos:broader`) using 7 weighted signals (6 structural + embedding similarity when embeddings are loaded). Confidence is the weighted mean over the signals that count for the pair, named in `informative_signals` (`scoring: "legacy"` reproduces the published OAEI figures). `cardinality: "many-to-one"` keeps several source terms on one target; a tie is reported under `tied_with`, marked `ambiguous` and sent to review, never dropped. Labels are matched with their parsed BCP-47 language tag; with the multilingual embedder loaded, cross-lingual pairs that share no surface tokens (e.g. `Dog`↔`Chien`) are admitted via the embedding signal. Restrict the languages consulted with `[language] preferred = [...]` / `OPEN_ONTOLOGIES_LANGUAGES` (empty = all) |
| `onto_align_feedback` | To accept/reject alignment candidates for self-calibrating confidence weights |
| `onto_communities` | To cluster the entity graph and get a SKELETON per community (size, top members by degree, internal relations, bridges to other communities). Deterministic modularity optimisation, no model involved. Write one report per skeleton, then answer corpus-wide questions ("what are the themes", "summarise this corpus") from the reports instead of traversing from an anchor entity, which such questions do not have. The GraphRAG global-search pattern with the expensive half left to the orchestrator |
| `onto_support_check` | To check whether claims are backed by the sources they cite. Returns which claims cite NO source (computed) and, for the rest, verification TASKS: the claim as a sentence, the source, what to decide. Complements `onto_vocab_check`: conformance asks whether a claim is expressible, support asks whether it is true to its source, and a claim can fail either independently |
@@ -234,7 +234,7 @@ preferred = []
`onto_align` partitions candidates into three buckets by confidence:
-- `auto_applied`: confidence ≥ `high_threshold` (default 0.85) — applied as triples
+- `auto_applied`: confidence ≥ `high_threshold` (default 0.95; 0.85 under `scoring: "legacy"`, the same strictness on that scale) and not ambiguous — applied as triples
- `borderline`: confidence in [`low_threshold`, `high_threshold`) (default low 0.4) — surfaced with rich `context` (source/target labels, source/target parents) for review
- below `low_threshold`: dropped
diff --git a/Cargo.lock b/Cargo.lock
index 39fe1567..c410b166 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3903,9 +3903,9 @@ dependencies = [
[[package]]
name = "rustls"
-version = "0.23.45"
+version = "0.23.46"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0d41d731c7d2f962d1ccc364cec258de3c0e93b38c2fb3ba97ac74513048d634"
+checksum = "48e13bd8c0e9365c43cfa5c9e8f9ad49d3c8444926c9aac819e0e4dc503c8fdf"
dependencies = [
"once_cell",
"ring",
diff --git a/README.md b/README.md
index c5142043..514d220a 100644
--- a/README.md
+++ b/README.md
@@ -337,14 +337,17 @@ A crosswalk states a match type. Nothing checked that statement. The engine now
An `exactMatch` that the entailments do not support comes back downgraded. The report gives the reason. It also names every term the crosswalk does not carry. That second list is the one that disappears from most crosswalk files. The output is valid SSSOM, so your tools read it today.
-A second question is sharper than a downgrade. The engine carries the translated claims into the target and reasons again. A clash means the target denies what the mapping carried in. That is a disagreement, and a person must settle it.
+The check compares where two terms sit in their hierarchies. It does not compare what the terms mean. Two sibling terms under one mapped parent look the same to it. So it can refute a match type, and it never makes a claim stronger. A parent that the mapping does not carry is a gap, and the report names it. A row with nothing to compare says so and is not certified.
+
+A second question is sharper than a downgrade. The engine carries the translated claims into the target and reasons again. A clash means the target denies what the mapping carried in. That is a disagreement, and a person must settle it. Run it with `crosswalk-probe`.
Contexts can disagree. Birds fly. Penguins are birds, and penguins do not fly. One graph that holds both is inconsistent, and this engine finds the clash. Each module reasons alone instead. A fact earns "true everywhere" when k modules of n entail it.
A number can now carry a certificate. `oo-matcert` recomputes a matrix product from the definition. It prints `MatCert.mul_of_check` when it accepts. Integers only, and that is the condition for the sentence to hold. Freivalds costs less and gives a probability, so it stays an opinion with its bound printed. Floating point reports a tolerance, because a proof over the real numbers says nothing about IEEE-754.
```bash
-open-ontologies batch plan.json # crosswalk-certify, modules --threshold k, matcert
+open-ontologies batch plan.json # crosswalk-certify, crosswalk-probe, modules --threshold k, matcert
+open-ontologies crosswalk-probe source.ttl target.ttl mapping.tsv # exits 1 on a clash
```
## What the tool proves
diff --git a/README.zh-CN.md b/README.zh-CN.md
index a9fea905..df7d357a 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -307,14 +307,17 @@ rdfs9 <ex:myCup> <rdf:type> <ex:Drink> <ex:myCup> <rdf:type> <e
蕴涵不支持的 `exactMatch` 会被降级返回。报告给出理由。它还列出对照表没有收录的每一个词。后面这份清单,正是大多数对照表文件里会消失的那一份。输出是合法的 SSSOM,你现有的工具今天就能读。
-还有一个比降级更尖锐的问题。引擎把翻译后的声明带进目标方,再推理一次。出现冲突,说明目标方否定了对照表带进去的东西。那是分歧,需要人来裁决。
+这项检查比较的是两个词在各自层级中的位置,而不是它们的含义。在同一个已映射父项之下的两个兄弟词,在它看来是一样的。所以它可以否定一个匹配类型,但从不把一个声明变得更强。对照表没有带过去的父项是覆盖缺口,报告会点名。没有任何东西可比较的行会如实说明,并且不被认证。
+
+还有一个比降级更尖锐的问题。引擎把翻译后的声明带进目标方,再推理一次。出现冲突,说明目标方否定了对照表带进去的东西。那是分歧,需要人来裁决。用 `crosswalk-probe` 运行它。
语境之间可以互相矛盾。鸟会飞。企鹅是鸟,而企鹅不会飞。一张图同时装下两者就不一致,本引擎会找出这个冲突。改成每个模块单独推理。一条事实要在 n 个模块中有 k 个蕴涵它,才算"处处为真"。
数字现在也能带证书。`oo-matcert` 按定义重算矩阵乘积。接受时它打印 `MatCert.mul_of_check`。只接受整数,这正是那句话成立的条件。Freivalds 代价更低但给的是概率,所以它只是意见,并附上自己的界。浮点只报告容差,因为在实数上的证明对 IEEE-754 什么也没说。
```bash
-open-ontologies batch plan.json # crosswalk-certify, modules --threshold k, matcert
+open-ontologies batch plan.json # crosswalk-certify, crosswalk-probe, modules --threshold k, matcert
+open-ontologies crosswalk-probe source.ttl target.ttl mapping.tsv # exits 1 on a clash
```
## 本工具证明了什么
diff --git a/benchmark/oaei/README.md b/benchmark/oaei/README.md
index 7dd312fd..018f4bdb 100644
--- a/benchmark/oaei/README.md
+++ b/benchmark/oaei/README.md
@@ -30,6 +30,8 @@ python3 run_oaei_benchmark.py
Measured with `onto_align` at `min_confidence = 0.8`, stable 1-to-1 matching, label penalty on zero structural evidence. No external background knowledge (UMLS, BioPortal, LLM oracle) is used. Raw output in `results/oaei_results.json` and `results/conference_results.json`.
+**These rows are the legacy fusion.** The default scoring changed (see [`docs/alignment.md`](../../docs/alignment.md)): confidence is now a weighted mean over the signals that carry evidence for the pair, so a name-only match is no longer multiplied by 0.85. The figures below reproduce with `--scoring legacy`; the Anatomy row reproduces byte for byte (1,152 correspondences, set hash `469e0e04cb58`). Under the new default the Anatomy track scores P 0.946 / R 0.745 / **F1 0.833** (1,194) at `min_confidence = 0.94`, which is `0.80 / 0.85`, the threshold equivalent to the run below, and P 0.957 / R 0.732 / F1 0.829 (1,159) at the new default 0.95. Rank in the OAEI 2025 field is unchanged at 9th of 13. The Conference track has not been re-run under the new default, because its data is not in this checkout; its row is legacy only.
+
| Track | Precision | Recall | F1 | Predicted | Reference | Runtime |
|---|---:|---:|---:|---:|---:|---:|
| Anatomy | 0.960 | 0.730 | **0.829** | 1,152 | 1,516 | 47s |
diff --git a/benchmark/oaei/run_ablation.py b/benchmark/oaei/run_ablation.py
index d25d1165..063a8eda 100644
--- a/benchmark/oaei/run_ablation.py
+++ b/benchmark/oaei/run_ablation.py
@@ -84,7 +84,7 @@ for name, weights in CONFIGS.items():
print('Running alignment...')
t0 = time.time()
result = subprocess.run(
- [BINARY, 'align', MOUSE, HUMAN, '--min-confidence', THRESHOLD, '--dry-run'],
+ [BINARY, 'align', MOUSE, HUMAN, '--min-confidence', THRESHOLD, '--dry-run', '--scoring', 'legacy'],
capture_output=True, text=True, timeout=600
)
elapsed = time.time() - t0
diff --git a/benchmark/oaei/run_ablation_no_stable.py b/benchmark/oaei/run_ablation_no_stable.py
index 5ea016f6..c131522a 100644
--- a/benchmark/oaei/run_ablation_no_stable.py
+++ b/benchmark/oaei/run_ablation_no_stable.py
@@ -64,7 +64,7 @@ RESULTS = {'with_stable': [], 'without_stable': []}
print('\n=== WITH stable matching (varying threshold) ===')
for threshold in ['0.70', '0.75', '0.80', '0.85']:
result = subprocess.run(
- [BINARY, 'align', MOUSE, HUMAN, '--min-confidence', threshold, '--dry-run'],
+ [BINARY, 'align', MOUSE, HUMAN, '--min-confidence', threshold, '--dry-run', '--scoring', 'legacy'],
capture_output=True, text=True, timeout=600
)
if result.returncode != 0: continue
@@ -117,7 +117,7 @@ if stable_block_start in original_src:
for threshold in ['0.80', '0.85']:
result = subprocess.run(
- [BINARY, 'align', MOUSE, HUMAN, '--min-confidence', threshold, '--dry-run'],
+ [BINARY, 'align', MOUSE, HUMAN, '--min-confidence', threshold, '--dry-run', '--scoring', 'legacy'],
capture_output=True, text=True, timeout=600
)
if result.returncode != 0: continue
diff --git a/benchmark/oaei/run_conference.py b/benchmark/oaei/run_conference.py
index 41a60490..29cc5bb6 100644
--- a/benchmark/oaei/run_conference.py
+++ b/benchmark/oaei/run_conference.py
@@ -47,7 +47,7 @@ for ref_file in sorted(glob.glob(f'{CONF_DIR}/reference/*.rdf')):
if not reference: continue
result = subprocess.run(
- [BINARY, 'align', src, tgt, '--min-confidence', '0.80', '--dry-run'],
+ [BINARY, 'align', src, tgt, '--min-confidence', '0.80', '--dry-run', '--scoring', 'legacy'],
capture_output=True, text=True, timeout=120
)
if result.returncode != 0: continue
diff --git a/benchmark/oaei/run_oaei_benchmark.py b/benchmark/oaei/run_oaei_benchmark.py
index 858575ff..bfdf3413 100644
--- a/benchmark/oaei/run_oaei_benchmark.py
+++ b/benchmark/oaei/run_oaei_benchmark.py
@@ -194,6 +194,7 @@ async def run_anatomy_benchmark(session) -> dict:
"target": human_path,
"min_confidence": 0.85,
"dry_run": True,
+ "scoring": "legacy",
})
elapsed = time.time() - start
print(f" Alignment completed in {elapsed:.1f}s")
diff --git a/benchmark/oaei/run_oaei_llm_benchmark.py b/benchmark/oaei/run_oaei_llm_benchmark.py
index 0cf06fca..14baf21c 100644
--- a/benchmark/oaei/run_oaei_llm_benchmark.py
+++ b/benchmark/oaei/run_oaei_llm_benchmark.py
@@ -204,6 +204,7 @@ async def main():
"target": human_path,
"min_confidence": LOW_CONFIDENCE,
"dry_run": True,
+ "scoring": "legacy",
})
align_time = time.time() - start
print(f"Structural alignment completed in {align_time:.1f}s")
diff --git a/docs/alignment.md b/docs/alignment.md
index 3fb48e9e..45e3a47a 100644
--- a/docs/alignment.md
+++ b/docs/alignment.md
@@ -1,27 +1,114 @@
# Schema Alignment
-Detect `owl:equivalentClass`, `skos:exactMatch`, `rdfs:subClassOf` candidates between two ontologies using 7 weighted signals:
+Detect `owl:equivalentClass`, `skos:exactMatch`, `rdfs:subClassOf` candidates between two ontologies, two SKOS vocabularies, or one of each.
+
+## What is aligned
+
+| Entity | Names | Parents | Shown to the reviewer |
+| ------ | ----- | ------- | --------------------- |
+| `owl:Class` | `rdfs:label`, `skos:prefLabel`, `skos:altLabel`, OBO exact and related synonyms | `rdfs:subClassOf` to a named class | labels, parents, `skos:definition` |
+| `skos:Concept` that is not also an `owl:Class` | `rdfs:label`, `skos:prefLabel`, `skos:altLabel`, `skos:hiddenLabel` | `skos:broader`, `skos:broaderTransitive`, `rdfs:subClassOf` | labels, parents, `skos:definition` |
+
+An entity typed both `owl:Class` and `skos:Concept` is read once, as a class, so an OWL ontology aligns exactly as it did before SKOS support. Definitions are shown to the reviewer in the borderline `context` block and never scored: string similarity over prose measures phrasing, not meaning.
+
+## Signals
| Signal | Weight | What it measures |
| ------ | ------ | ---------------- |
-| Label similarity | 0.20 | Jaro-Winkler on normalized labels (camelCase split, lowercased) |
-| Property overlap | 0.15 | Jaccard on domain property + range signatures |
-| Parent overlap | 0.12 | Jaccard on rdfs:subClassOf parent local names |
-| Instance overlap | 0.12 | Jaccard on shared individuals by local name |
-| Restriction similarity | 0.12 | Jaccard on OWL restriction signatures (property->filler) |
-| Neighborhood similarity | 0.09 | Jaccard on 2-hop property neighborhood |
+| Label similarity | 0.20 | Best of Jaro-Winkler and token Jaccard on normalized labels (camelCase split, lowercased) |
+| Property overlap | 0.15 | Domain properties and their ranges |
+| Parent overlap | 0.12 | Parents (see the table above) |
+| Instance overlap | 0.12 | Shared individuals by local name |
+| Restriction similarity | 0.12 | OWL restriction signatures (property->filler) |
+| Neighborhood similarity | 0.09 | 2-hop property neighborhood |
| Embedding similarity | 0.20 | Cosine similarity on text embeddings (requires `onto_embed`) |
-When compiled without the `embeddings` feature, alignment uses the first 6 signals with the original weights (0.25, 0.20, 0.15, 0.15, 0.15, 0.10).
+When compiled without the `embeddings` feature, alignment uses the first 6 signals with the weights (0.25, 0.20, 0.15, 0.15, 0.15, 0.10). Use `onto_align_feedback` to accept or reject candidates; feedback is stored in SQLite and recalibrates the weights once ten rows carry signal values.
+
+## How the signals become one confidence
+
+`--scoring informative` (the default) takes a weighted mean over the signals that **count** for the pair, and leaves every other signal out of both the numerator and the denominator:
+
+- The name always counts. Every entity has one, if only its IRI's local name.
+- The embedding similarity counts when both sides have a vector. A cosine is a measured distance, so a low one is evidence against.
+- A structural signal counts only as **support**, at 1.0, when the two sides share at least one feature that the other vocabulary can name. A parent, range or restriction filler is recognised across vocabularies by IRI local name or by a shared normalized label, because two independently built vocabularies almost never share local names (`MA_0000003` against `NCI_C12345`).
+
+A structural feature the other side has no name for cannot be compared at all, and is left out. A shared feature that is missing is not evidence that the terms differ: under the open-world reading the other side did not say it, ontologies differ in granularity, and multiple inheritance gives one term different direct parents in different places. Counting such a zero as disagreement cost 0.076 F1 on OAEI Anatomy at threshold 0.94 (0.757 against 0.833). Counting a partial overlap at its Jaccard value would make one shared parent out of three score lower than none. Binary support is monotone: more agreement can only raise the confidence.
+
+Each candidate says what its confidence rests on:
+
+```json
+"confidence": 1.0,
+"informative_signals": ["label_similarity"],
+"evidence_coverage": 0.25
+```
+
+`evidence_coverage` is the share of the total weight held by the signals that counted. A 1.0 that rests on a name alone reads as exactly that. The top level carries `"scoring": "informative_renormalised"` and a `scoring_means` sentence.
+
+One weakness is stated rather than hidden: siblings share parents, so a weak name under a shared parent gains confidence it may not deserve ("Cat" and "Bat" under "Mammal"). The learned weights are the place to correct that. Reject such pairs with `onto_align_feedback` and the parent weight falls.
+
+### The legacy fusion, kept for the published figures
+
+`--scoring legacy` reproduces the fusion every published alignment figure in this repository was measured with: `label_similarity x 0.85` when every structural signal is zero, otherwise the weighted sum over **all** signals, including those with no data on either side. Two consequences are why it is no longer the default:
+
+- A perfect name match between two flat lists cannot score above 0.85.
+- Agreement costs confidence. The same name with the same parent scored `0.25 + 0.15 = 0.40`, under half of what the same pair scored with the parent deleted.
+
+The OAEI Anatomy result (P 0.960, R 0.730, F1 0.829, 1,152 correspondences, set hash `469e0e04cb58`) reproduces byte for byte with `--scoring legacy --min-confidence 0.80`.
-Candidates above the confidence threshold are auto-applied to the main graph. Use `onto_align_feedback` to accept/reject candidates — feedback is stored in SQLite and used to self-calibrate signal weights over time.
+### Thresholds
+
+The legacy fusion compresses every name-only confidence by 0.85, so the same threshold means different things on the two scales: a legacy threshold `t` corresponds to `t / 0.85` under the default. The default auto-apply threshold follows the scoring so that auto-apply stays as strict as it was: **0.95** under `informative`, **0.85** under `legacy`. Under legacy, 0.85 auto-applied a pair with no structural evidence only for an exact name.
+
+Measured on OAEI Anatomy, one-to-one, no background knowledge:
+
+| Scoring | Threshold | Precision | Recall | F1 | Correspondences |
+| ------- | --------: | --------: | -----: | -: | --------------: |
+| legacy | 0.80 | 0.960 | 0.730 | **0.829** | 1,152 |
+| informative | 0.80 | 0.600 | 0.811 | 0.690 | 2,051 |
+| informative | 0.85 | 0.698 | 0.808 | 0.749 | 1,756 |
+| informative | 0.90 | 0.850 | 0.791 | 0.819 | 1,411 |
+| informative | 0.94 | 0.946 | 0.745 | **0.833** | 1,194 |
+| informative | 0.95 (default) | 0.957 | 0.732 | **0.829** | 1,159 |
+| informative | 0.97 | 0.969 | 0.708 | 0.819 | 1,108 |
+
+0.94 is `0.80 / 0.85`, the threshold equivalent to the published run, chosen by that arithmetic and not by the sweep.
+
+## One-to-one, many-to-one, and ties
+
+`--cardinality one-to-one` (the default) keeps the best target for each source and the best source for each target. That constraint is what lifted Anatomy precision, and it is wrong whenever the source is **finer** than the target: several source codes that each correctly map to one coarser target code lose all but one row. `--cardinality many-to-one` keeps the best target for every source and lets targets repeat.
+
+When a row is dropped because a kept row scored the same, within 0.001 (one unit of the printed precision), the kept row won on IRI spelling and not on evidence. The tie is never resolved silently:
+
+```json
+"ambiguous": true,
+"tied_with": [{"source_iri": "...", "target_iri": "...", "confidence": 1.0}],
+"requires_review": true
+```
+
+An ambiguous row goes to the borderline bucket and is never written into the graph, because the engine did not choose it. The top level carries `ambiguous_count`. Sharing a target under many-to-one is not a tie.
## CLI Usage
```bash
-# Compare two ontology files (dry run)
-open-ontologies align source.ttl target.ttl --min-confidence 0.7 --dry-run
+# Compare two vocabularies (dry run); default scoring and threshold
+open-ontologies align source.ttl target.ttl --dry-run
+
+# A detailed source list onto a coarser SKOS taxonomy
+open-ontologies align source.ttl taxonomy.ttl --cardinality many-to-one --dry-run
+
+# Reproduce a published OAEI figure
+open-ontologies align mouse.owl human.owl --scoring legacy --min-confidence 0.80 --dry-run
# Accept a candidate
open-ontologies align-feedback --source http://ex.org/Dog --target http://other.org/Canine --accept
```
+
+Over MCP, `onto_align` takes the same choices as `scoring` and `cardinality`.
+
+## Checking a crosswalk after it is written
+
+Alignment proposes rows. Two batch verbs check rows that already exist, from an SSSOM TSV:
+
+- `crosswalk-certify SOURCE TARGET MAPPINGS.tsv [--sssom OUT.tsv]` compares the position of each subject and object in their hierarchies, through the mapping. For a SKOS scheme the hierarchy is the `skos:broader` closure. A downgrade is a refutation. An upheld row means only that nothing visible refutes it: two siblings under one mapped parent look identical, so the predicate column never strengthens a claim. An ancestor with no counterpart through the mapping is a coverage gap, named on the row and never counted as a disagreement, and a row with nothing to compare is `not_refuted_nothing_compared` and not certified.
+- `crosswalk-probe SOURCE TARGET MAPPINGS.tsv` (also a CLI subcommand) carries the source's subsumptions into the target through the mapping and reports any clash the carried claims add, such as a `cax-dw` disjointness violation. One witness individual is typed into each receiving class so that a TBox-only taxonomy can clash at all, and clashes the target has on its own are reported under `target_alone` rather than blamed on the mapping. It exits 1 when the mapping adds a clash.
diff --git a/docs/assets/certified-claims.py b/docs/assets/certified-claims.py
index ba473e83..a73e7504 100644
--- a/docs/assets/certified-claims.py
+++ b/docs/assets/certified-claims.py
@@ -38,7 +38,7 @@ TEXT = {
"down": "downgraded",
"gap": "{n} term the crosswalk does not carry",
"gaps": "{n} terms the crosswalk does not carry",
- "because": "the target has no word for ies:ResponsibleActor, so nothing stronger is defensible",
+ "because": "the target does not put Person or Organisation under ResponsibleActor, so each is the narrower term",
"entails": "entails {n}",
"promoted": "{n} fact entailed in {k} of {t} modules",
"contested": "{n} held by fewer, and named rather than dropped",
@@ -70,7 +70,7 @@ TEXT = {
"down": "降级",
"gap": "{n} 个词对照表未收录",
"gaps": "{n} 个词对照表未收录",
- "because": "目标方没有 ies:ResponsibleActor 对应的词,因此更强的声明都立不住",
+ "because": "目标方没有把 Person 和 Organisation 放在 ResponsibleActor 之下,因此二者都是更窄的词",
"entails": "蕴涵 {n}",
"promoted": "{n} 条事实在 {t} 个模块中的 {k} 个里被蕴涵",
"contested": "{n} 条只有更少模块持有,逐条列出而不丢弃",
@@ -170,7 +170,10 @@ def main(cw_path, mod_path, mc_path, out_path, lang="en"):
for row in cw["rows"]:
claimed, supported = short(row["claimed"]), short(row["supported"])
down = row["downgraded"]
- col = WARN if down else OK
+ # A row nothing could be compared on is not upheld, and must not be
+ # drawn in the colour of one.
+ unchecked = row.get("certification", "").startswith("not_refuted")
+ col = WARN if down else (DIM if unchecked else OK)
A(f'<text x="{x + 16:.0f}" y="{y}" font-size="10.5" fill="{INK}">'
f'{esc(must_fit(short(row["subject"]), 10.5, CW_ - 150, "crosswalk subject"))}</text>')
A(f'<text x="{x + CW_ - 16:.0f}" y="{y}" font-size="10" text-anchor="end" fill="{col}">'
diff --git a/docs/assets/certified-claims.svg b/docs/assets/certified-claims.svg
index 6fcb3bae..3d7b5d89 100644
--- a/docs/assets/certified-claims.svg
+++ b/docs/assets/certified-claims.svg
@@ -7,18 +7,18 @@
<text x="50" y="110" font-size="11.5" font-weight="800" letter-spacing="0.6" fill="#7dd3fc">A CROSSWALK'S MATCH TYPE</text>
<text x="50" y="126" font-size="10" fill="#64748b">claimed, then checked against what each side entails</text>
<text x="50" y="154" font-size="10.5" fill="#e2e8f0">Person</text>
-<text x="350" y="154" font-size="10" text-anchor="end" fill="#fbbf24">exactMatch → relatedMatch</text>
+<text x="350" y="154" font-size="10" text-anchor="end" fill="#fbbf24">exactMatch → broadMatch</text>
<text x="50" y="171" font-size="10.5" fill="#e2e8f0">Organisation</text>
-<text x="350" y="171" font-size="10" text-anchor="end" fill="#fbbf24">exactMatch → relatedMatch</text>
+<text x="350" y="171" font-size="10" text-anchor="end" fill="#fbbf24">exactMatch → broadMatch</text>
<text x="50" y="188" font-size="10.5" fill="#e2e8f0">Entity</text>
-<text x="350" y="188" font-size="10" text-anchor="end" fill="#34d399">exactMatch → exactMatch</text>
-<text x="50" y="205" font-size="10.5" fill="#e2e8f0">Event</text>
+<text x="350" y="188" font-size="10" text-anchor="end" fill="#64748b">exactMatch → exactMatch</text>
+<text x="50" y="205" font-size="10.5" fill="#e2e8f0">ResponsibleActor</text>
<text x="350" y="205" font-size="10" text-anchor="end" fill="#34d399">exactMatch → exactMatch</text>
<line x1="50" y1="216" x2="350" y2="216" stroke="#1e3a5f"/>
<text x="50" y="234" font-size="10" fill="#94a3b8">1 term the crosswalk does not carry</text>
-<text x="58" y="249" font-size="10" fill="#64748b">· ResponsibleActor</text>
-<text x="50" y="275" font-size="10" fill="#fbbf24">the target has no word for ies:ResponsibleActor, so</text>
-<text x="50" y="289" font-size="10" fill="#fbbf24">nothing stronger is defensible</text>
+<text x="58" y="249" font-size="10" fill="#64748b">· Event</text>
+<text x="50" y="275" font-size="10" fill="#fbbf24">the target does not put Person or Organisation under</text>
+<text x="50" y="289" font-size="10" fill="#fbbf24">ResponsibleActor, so each is the narrower term</text>
<rect x="384" y="84" width="332" height="280" rx="11" fill="#0b1428" stroke="#1e3a5f" stroke-width="1"/>
<text x="400" y="110" font-size="11.5" font-weight="800" letter-spacing="0.6" fill="#7dd3fc">CONTEXTS THAT DISAGREE</text>
<text x="400" y="126" font-size="10" fill="#64748b">each module reasons alone; a fact earns “true everywhere”</text>
diff --git a/docs/assets/certified-claims.zh-CN.svg b/docs/assets/certified-claims.zh-CN.svg
index fdaeedfd..92f1d053 100644
--- a/docs/assets/certified-claims.zh-CN.svg
+++ b/docs/assets/certified-claims.zh-CN.svg
@@ -7,18 +7,18 @@
<text x="50" y="110" font-size="11.5" font-weight="800" letter-spacing="0.6" fill="#7dd3fc">对照表的匹配类型</text>
<text x="50" y="126" font-size="10" fill="#64748b">先声明,再对照两边的蕴涵核验</text>
<text x="50" y="154" font-size="10.5" fill="#e2e8f0">Person</text>
-<text x="350" y="154" font-size="10" text-anchor="end" fill="#fbbf24">exactMatch → relatedMatch</text>
+<text x="350" y="154" font-size="10" text-anchor="end" fill="#fbbf24">exactMatch → broadMatch</text>
<text x="50" y="171" font-size="10.5" fill="#e2e8f0">Organisation</text>
-<text x="350" y="171" font-size="10" text-anchor="end" fill="#fbbf24">exactMatch → relatedMatch</text>
+<text x="350" y="171" font-size="10" text-anchor="end" fill="#fbbf24">exactMatch → broadMatch</text>
<text x="50" y="188" font-size="10.5" fill="#e2e8f0">Entity</text>
-<text x="350" y="188" font-size="10" text-anchor="end" fill="#34d399">exactMatch → exactMatch</text>
-<text x="50" y="205" font-size="10.5" fill="#e2e8f0">Event</text>
+<text x="350" y="188" font-size="10" text-anchor="end" fill="#64748b">exactMatch → exactMatch</text>
+<text x="50" y="205" font-size="10.5" fill="#e2e8f0">ResponsibleActor</text>
<text x="350" y="205" font-size="10" text-anchor="end" fill="#34d399">exactMatch → exactMatch</text>
<line x1="50" y1="216" x2="350" y2="216" stroke="#1e3a5f"/>
<text x="50" y="234" font-size="10" fill="#94a3b8">1 个词对照表未收录</text>
-<text x="58" y="249" font-size="10" fill="#64748b">· ResponsibleActor</text>
-<text x="50" y="275" font-size="10" fill="#fbbf24">目标方没有 ies:ResponsibleActor</text>
-<text x="50" y="289" font-size="10" fill="#fbbf24">对应的词,因此更强的声明都立不住</text>
+<text x="58" y="249" font-size="10" fill="#64748b">· Event</text>
+<text x="50" y="275" font-size="10" fill="#fbbf24">目标方没有把 Person 和 Organisation 放在 ResponsibleActor</text>
+<text x="50" y="289" font-size="10" fill="#fbbf24">之下,因此二者都是更窄的词</text>
<rect x="384" y="84" width="332" height="280" rx="11" fill="#0b1428" stroke="#1e3a5f" stroke-width="1"/>
<text x="400" y="110" font-size="11.5" font-weight="800" letter-spacing="0.6" fill="#7dd3fc">互相矛盾的语境</text>
<text x="400" y="126" font-size="10" fill="#64748b">每个模块单独推理;事实要自己挡得“处处为真”</text>
diff --git a/docs/assets/claims/crosswalk.json b/docs/assets/claims/crosswalk.json
index 8f8d37ef..a048f9c9 100644
--- a/docs/assets/claims/crosswalk.json
+++ b/docs/assets/claims/crosswalk.json
@@ -1 +1 @@
-{"command":"crosswalk-certify","result":{"checked":4,"downgraded":2,"gaps":1,"means":"each side was reasoned INDEPENDENTLY under OWL 2 RL and the entailed named ancestors were compared through the mapping itself. A supported predicate means nothing this engine can see refutes it. It is NOT a proof: the comparison is over 29 of OWL 2 RL's 78 rules, and an axiom no rule fires on contributes to neither side. Run onto_dlp_boundary to see which of your axioms were invisible. No Lean checker has a theorem about SKOS match types, so nothing here is certified in this repository's sense of that word.","rows":[{"because":"1 entailed ancestor(s) of the subject have no image in the target vocabulary, so the two cannot be compared where it matters most. This is the case a crosswalk hides: the target does not carry the distinction.","claimed":"http://www.w3.org/2004/02/skos/core#exactMatch","downgraded":true,"object":"http://hqdm.example/Person","object_ancestors":["http://hqdm.example/Thing"],"subject":"http://ies.example/Person","subject_ancestors":["http://ies.example/Entity","http://ies.example/ResponsibleActor"],"supported":"http://www.w3.org/2004/02/skos/core#relatedMatch","untranslatable":["http://ies.example/ResponsibleActor"]},{"because":"1 entailed ancestor(s) of the subject have no image in the target vocabulary, so the two cannot be compared where it matters most. This is the case a crosswalk hides: the target does not carry the distinction.","claimed":"http://www.w3.org/2004/02/skos/core#exactMatch","downgraded":true,"object":"http://hqdm.example/Organisation","object_ancestors":["http://hqdm.example/Thing"],"subject":"http://ies.example/Organisation","subject_ancestors":["http://ies.example/Entity","http://ies.example/ResponsibleActor"],"supported":"http://www.w3.org/2004/02/skos/core#relatedMatch","untranslatable":["http://ies.example/ResponsibleActor"]},{"because":"both sides entail the same ancestors once translated, and nothing was lost in translation.","claimed":"http://www.w3.org/2004/02/skos/core#exactMatch","downgraded":false,"object":"http://hqdm.example/Thing","object_ancestors":[],"subject":"http://ies.example/Entity","subject_ancestors":[],"supported":"http://www.w3.org/2004/02/skos/core#exactMatch","untranslatable":[]},{"because":"both sides entail the same ancestors once translated, and nothing was lost in translation.","claimed":"http://www.w3.org/2004/02/skos/core#exactMatch","downgraded":false,"object":"http://hqdm.example/Activity","object_ancestors":["http://hqdm.example/Thing"],"subject":"http://ies.example/Event","subject_ancestors":["http://ies.example/Entity"],"supported":"http://www.w3.org/2004/02/skos/core#exactMatch","untranslatable":[]}],"unmapped":[{"reason":"the crosswalk carries no row for this term, so a reader cannot tell whether it was considered and rejected or never looked at","side":"source","term":"http://ies.example/ResponsibleActor"}],"verdict":"checked_by_this_engine"},"seq":0}
+{"command":"crosswalk-certify","result":{"checked":4,"downgraded":2,"gaps":1,"means":"each side was reasoned INDEPENDENTLY under OWL 2 RL and the entailed named ancestors were compared through the mapping itself. What this checks is the POSITION of the two terms in their hierarchies, not what they mean: a downgrade is a refutation (the subject sits under a mapped concept the object does not, or the reverse), and an upheld row means only that nothing this engine can see refutes it. Two siblings under one mapped parent have identical translated ancestors, so a row pairing the wrong sibling is upheld exactly as the right one is, which is why the predicate column never strengthens a claim. Only ancestors both sides can name are compared: an ancestor with no counterpart through the mapping is a coverage gap, named on the row and never counted as a disagreement, and a row with nothing comparable, including a term with no hierarchy at all, is not_refuted_nothing_compared and is NOT certified. A SKOS scheme's hierarchy is its skos:broader closure. It is NOT a proof: the comparison is over 29 of OWL 2 RL's 78 rules, and an axiom no rule fires on contributes to neither side. Run onto_dlp_boundary to see which of your axioms were invisible. No Lean checker has a theorem about SKOS match types, so nothing here is certified in this repository's sense of that word.","rows":[{"because":"the subject is under every ancestor the object is under, and more, so the subject is the MORE SPECIFIC concept and the object is the broader one.","certification":"downgraded","claimed":"http://www.w3.org/2004/02/skos/core#exactMatch","downgraded":true,"object":"http://hqdm.example/Person","object_ancestors":["http://hqdm.example/Thing"],"object_uncovered":[],"subject":"http://ies.example/Person","subject_ancestors":["http://ies.example/Entity","http://ies.example/ResponsibleActor"],"supported":"http://www.w3.org/2004/02/skos/core#broadMatch","untranslatable":[]},{"because":"the subject is under every ancestor the object is under, and more, so the subject is the MORE SPECIFIC concept and the object is the broader one.","certification":"downgraded","claimed":"http://www.w3.org/2004/02/skos/core#exactMatch","downgraded":true,"object":"http://hqdm.example/Organisation","object_ancestors":["http://hqdm.example/Thing"],"object_uncovered":[],"subject":"http://ies.example/Organisation","subject_ancestors":["http://ies.example/Entity","http://ies.example/ResponsibleActor"],"supported":"http://www.w3.org/2004/02/skos/core#broadMatch","untranslatable":[]},{"because":"nothing to compare: neither term has an ancestor the mapping carries across, so the hierarchy can neither support nor refute this row and it is NOT certified.","certification":"not_refuted_nothing_compared","claimed":"http://www.w3.org/2004/02/skos/core#exactMatch","downgraded":false,"object":"http://hqdm.example/Thing","object_ancestors":[],"object_uncovered":[],"subject":"http://ies.example/Entity","subject_ancestors":[],"supported":"http://www.w3.org/2004/02/skos/core#exactMatch","untranslatable":[]},{"because":"both sides entail the same ancestors once translated, over every ancestor the mapping lets the two compare.","certification":"upheld","claimed":"http://www.w3.org/2004/02/skos/core#exactMatch","downgraded":false,"object":"http://hqdm.example/ResponsibleActor","object_ancestors":["http://hqdm.example/Thing"],"object_uncovered":[],"subject":"http://ies.example/ResponsibleActor","subject_ancestors":["http://ies.example/Entity"],"supported":"http://www.w3.org/2004/02/skos/core#exactMatch","untranslatable":[]}],"unmapped":[{"reason":"the crosswalk carries no row for this term, so a reader cannot tell whether it was considered and rejected or never looked at","side":"source","term":"http://ies.example/Event"}],"verdict":"checked_by_this_engine"},"seq":0}
diff --git a/docs/assets/claims/hqdm-side.ttl b/docs/assets/claims/hqdm-side.ttl
index 6d69a099..ff796a12 100644
--- a/docs/assets/claims/hqdm-side.ttl
+++ b/docs/assets/claims/hqdm-side.ttl
@@ -1,9 +1,12 @@
-# The other side. It has Person and Organisation, but it does NOT put them
-# under a common responsible-actor class: both hang straight off the top.
+# The other side. It HAS a responsible-actor class, but it does NOT put Person
+# or Organisation under it: both hang straight off the top. The mapping below
+# carries ResponsibleActor across, so the two hierarchies can be compared there
+# and they disagree.
@prefix hqdm: <http://hqdm.example/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
-hqdm:Person a owl:Class ; rdfs:subClassOf hqdm:Thing .
-hqdm:Organisation a owl:Class ; rdfs:subClassOf hqdm:Thing .
-hqdm:Thing a owl:Class .
-hqdm:Activity a owl:Class ; rdfs:subClassOf hqdm:Thing .
+hqdm:Person a owl:Class ; rdfs:subClassOf hqdm:Thing .
+hqdm:Organisation a owl:Class ; rdfs:subClassOf hqdm:Thing .
+hqdm:ResponsibleActor a owl:Class ; rdfs:subClassOf hqdm:Thing .
+hqdm:Thing a owl:Class .
+hqdm:Activity a owl:Class ; rdfs:subClassOf hqdm:Thing .
diff --git a/docs/assets/claims/mapping.tsv b/docs/assets/claims/mapping.tsv
index 4f2a33e4..609d6e25 100644
--- a/docs/assets/claims/mapping.tsv
+++ b/docs/assets/claims/mapping.tsv
@@ -2,4 +2,4 @@ subject_id predicate_id object_id
http://ies.example/Person skos:exactMatch http://hqdm.example/Person
http://ies.example/Organisation skos:exactMatch http://hqdm.example/Organisation
http://ies.example/Entity skos:exactMatch http://hqdm.example/Thing
-http://ies.example/Event skos:exactMatch http://hqdm.example/Activity
+http://ies.example/ResponsibleActor skos:exactMatch http://hqdm.example/ResponsibleActor
diff --git a/docs/benchmarks.md b/docs/benchmarks.md
index e04071e3..9c45cfd3 100644
--- a/docs/benchmarks.md
+++ b/docs/benchmarks.md
@@ -90,7 +90,7 @@ Full writeup, including the three-bug analysis and reproduction commands: [`benc
## OAEI Ontology Alignment
-Anatomy 0.829 F1 (9th of 13 in the OAEI 2025 field), Conference 0.438 (below every participating system and both baselines). Full field, both baselines, and the stable-matching ablation: [`benchmark/oaei/README.md`](../benchmark/oaei/README.md)
+Anatomy 0.829 F1 (9th of 13 in the OAEI 2025 field), Conference 0.438 (below every participating system and both baselines), both measured with the fusion now behind `--scoring legacy`. Under the current default Anatomy scores 0.833 at the equivalent threshold; Conference has not been re-run. Full field, both baselines, and the stable-matching ablation: [`benchmark/oaei/README.md`](../benchmark/oaei/README.md)
## Claim Verification — Compiled Reasoning vs HermiT
diff --git a/docs/determinism.md b/docs/determinism.md
index deee9e1a..1d60c2b9 100644
--- a/docs/determinism.md
+++ b/docs/determinism.md
@@ -90,6 +90,10 @@ been quoted for a quantity whose third decimal was not a property of the system.
## Reproducing
+The alignment hash below is for the fusion that produced the recorded figure,
+which is no longer the default and is selected with `--scoring legacy`
+([alignment](alignment.md)).
+
```bash
# Tableaux: run the conformance binary repeatedly; all runs must agree.
for i in $(seq 1 12); do cargo test --test owl2_conformance_test 2>&1 | grep "^test result"; done
@@ -99,7 +103,7 @@ for i in 1 2 3 4 5; do
./target/release/open-ontologies align \
benchmark/oaei/data/anatomy/mouse.owl \
benchmark/oaei/data/anatomy/human.owl \
- --min-confidence 0.80 --dry-run \
+ --scoring legacy --min-confidence 0.80 --dry-run \
| python3 -c "import json,sys,hashlib; c=json.load(sys.stdin)['candidates']; \
p=[(x['source_iri'],x['target_iri']) for x in c]; \
print(len(c), hashlib.sha256(repr(sorted(p)).encode()).hexdigest()[:12])"
diff --git a/docs/tool-reference.md b/docs/tool-reference.md
index a32e8a1b..43548ae1 100644
--- a/docs/tool-reference.md
+++ b/docs/tool-reference.md
@@ -89,7 +89,7 @@ it withheld.
| `onto_action_apply_concurrent` | Fire a tick of concurrent BC+ actions atomically. |
| `onto_action_list` | List the names of all action schemas registered in this server's Dynamics store. |
| `onto_action_register` | Persist a named action schema (Dynamics layer #43). |
-| `onto_align` | Detect alignment candidates (owl:equivalentClass, skos:exactMatch, rdfs:subClassOf) between two ontologies using label similarity, property overlap, parent overlap, instance overlap, restriction patterns, and graph neighborhood. |
+| `onto_align` | Detect alignment candidates (owl:equivalentClass, skos:exactMatch, rdfs:subClassOf) between two ontologies or SKOS vocabularies (owl:Class and skos:Concept) using label similarity, property overlap, parent overlap, instance overlap, restriction patterns, and graph neighborhood. |
| `onto_align_feedback` | Accept or reject an alignment candidate to improve future confidence scoring. |
| `onto_align_flora` | End-to-end FLORA alignment (#38). |
| `onto_align_fuzzy` | FLORA-style fuzzy-logic alignment adjudication (#38, ISWC 2025 Best Paper). |
diff --git a/src/align.rs b/src/align.rs
index c8b96270..2a7028c7 100644
--- a/src/align.rs
+++ b/src/align.rs
@@ -4,6 +4,188 @@ use crate::drift::jaro_winkler;
use crate::graph::GraphStore;
use crate::state::StateDb;
+const SKOS_NS: &str = "http://www.w3.org/2004/02/skos/core#";
+
+/// How the weighted-sum fusion turns per-signal scores into one confidence.
+///
+/// `Informative` is the default. A signal enters the weighted mean only when
+/// BOTH sides of the pair carry data for it, and the mean is taken over the
+/// weights of those signals alone, so a signal nobody could measure neither
+/// helps nor hurts. One side having data and the other none is ignorance and
+/// not disagreement: a SKOS concept has no `rdfs:domain` properties because
+/// SKOS does not model them, not because it differs from an OWL class that
+/// has some. Structural features are compared by IRI local name OR by a
+/// shared normalised label, because two independently built vocabularies
+/// almost never share local names (`MA_0000003` against `NCI_C12345`) and a
+/// comparison by name alone would report disagreement where there is only a
+/// different spelling of the identifier.
+///
+/// `Legacy` is the fusion every published alignment figure in this repository
+/// was measured with, kept so those figures stay reproducible: when every
+/// structural signal is zero, `label_similarity * 0.85`; otherwise the plain
+/// weighted sum over all signals, in which a signal with no data on either
+/// side still carries its weight times zero. Two consequences are why it is
+/// no longer the default: a perfect name match can never score above 0.85,
+/// and agreement COSTS confidence (same name and same parent scored 0.40,
+/// less than half the same pair with the parent deleted).
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
+pub enum Scoring {
+ #[default]
+ Informative,
+ Legacy,
+}
+
+impl Scoring {
+ pub fn parse(s: &str) -> anyhow::Result<Self> {
+ match s.trim().to_ascii_lowercase().replace('-', "_").as_str() {
+ "informative" | "informative_renormalised" | "renormalised" | "default" => {
+ Ok(Self::Informative)
+ }
+ "legacy" => Ok(Self::Legacy),
+ other => anyhow::bail!(
+ "unknown scoring {other:?}: expected \"informative\" (default) or \"legacy\""
+ ),
+ }
+ }
+
+ /// The auto-apply threshold that keeps auto-apply as strict as it was.
+ ///
+ /// Under the legacy fusion a pair with no structural evidence scored
+ /// `0.85 x name similarity`, so the 0.85 default auto-applied only exact
+ /// names. The informative fusion no longer compresses the scale, so the
+ /// same strictness needs a higher number: 0.95 admits names that differ
+ /// only in a character or two. Measured on OAEI Anatomy, 0.95 under this
+ /// fusion gives precision 0.957 against 0.960 for legacy at 0.80.
+ pub fn default_high_threshold(self) -> f64 {
+ match self {
+ Self::Informative => 0.95,
+ Self::Legacy => 0.85,
+ }
+ }
+
+ pub fn as_str(self) -> &'static str {
+ match self {
+ Self::Informative => "informative_renormalised",
+ Self::Legacy => "legacy",
+ }
+ }
+
+ fn means(self) -> &'static str {
+ match self {
+ Self::Informative => {
+ "confidence is the weighted mean of the signals listed in each candidate's \
+ informative_signals, which are the signals BOTH sides carry data for; a \
+ signal measurable on one side only is left out rather than counted as zero. \
+ evidence_coverage is the share of the total weight those signals hold, so a \
+ high confidence resting on a name alone reads as exactly that."
+ }
+ Self::Legacy => {
+ "legacy fusion, kept to reproduce published figures: label_similarity x 0.85 \
+ when every structural signal is zero, otherwise the weighted sum over ALL \
+ signals, including those with no data on either side."
+ }
+ }
+ }
+}
+
+/// Whether a target may be claimed by more than one source.
+///
+/// `OneToOne` is the default and is what the published Anatomy figure was
+/// measured with: a greedy stable matching keeps the best target for each
+/// source and the best source for each target, which removes most false
+/// positives on a track whose reference alignment is itself 1:1. It is wrong
+/// whenever the source is FINER than the target: several source codes that
+/// each correctly map to one coarser target code would lose all but one row.
+/// `ManyToOne` keeps the best target for every source and lets targets repeat,
+/// which is the right constraint for mapping a detailed source list onto a
+/// coarser taxonomy.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
+pub enum Cardinality {
+ #[default]
+ OneToOne,
+ ManyToOne,
+}
+
+impl Cardinality {
+ pub fn parse(s: &str) -> anyhow::Result<Self> {
+ match s.trim().to_ascii_lowercase().replace(['-', ':'], "_").as_str() {
+ "one_to_one" | "1_1" | "1to1" => Ok(Self::OneToOne),
+ "many_to_one" | "n_1" | "nto1" => Ok(Self::ManyToOne),
+ other => anyhow::bail!(
+ "unknown cardinality {other:?}: expected \"one-to-one\" (default) or \"many-to-one\""
+ ),
+ }
+ }
+
+ pub fn as_str(self) -> &'static str {
+ match self {
+ Self::OneToOne => "one_to_one",
+ Self::ManyToOne => "many_to_one",
+ }
+ }
+}
+
+/// Everything `align` takes besides the two vocabularies.
+#[derive(Clone, Debug)]
+pub struct AlignOptions {
+ pub high_threshold: f64,
+ pub low_threshold: f64,
+ pub dry_run: bool,
+ /// `"weighted_sum"` or `"rrf"`.
+ pub fusion: String,
+ pub scoring: Scoring,
+ pub cardinality: Cardinality,
+}
+
+impl Default for AlignOptions {
+ fn default() -> Self {
+ Self {
+ high_threshold: Scoring::default().default_high_threshold(),
+ low_threshold: 0.4,
+ dry_run: false,
+ fusion: "weighted_sum".to_string(),
+ scoring: Scoring::default(),
+ cardinality: Cardinality::default(),
+ }
+ }
+}
+
+/// Two confidences closer than this are a tie. One unit of the printed
+/// precision: a reader cannot tell them apart, so the engine must not pretend
+/// to have chosen between them.
+const TIE_EPSILON: f64 = 0.001 + 1e-9;
+
+/// What an entity is, which decides where its parents are read from.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum EntityKind {
+ /// Typed `owl:Class`. Read exactly as before SKOS support existed.
+ OwlClass,
+ /// Typed `skos:Concept` and not `owl:Class`.
+ SkosConcept,
+}
+
+/// The names one side of an alignment has.
+#[derive(Debug, Default)]
+struct Vocabulary {
+ /// Normalised labels per class or concept IRI.
+ labels: std::collections::HashMap<String, Vec<String>>,
+ /// `id:<local name>` for every IRI in the store and `label:<label>` for
+ /// every class label.
+ universe: std::collections::HashSet<String>,
+}
+
+/// The structural features of one entity, read once and reused for every
+/// pair it takes part in.
+#[derive(Debug, Clone, Default)]
+struct Features {
+ properties: Vec<String>,
+ ranges: Vec<String>,
+ parents: Vec<String>,
+ instances: Vec<String>,
+ restrictions: Vec<(String, String)>,
+ neighborhood: Vec<String>,
+}
+
/// Schema alignment engine — detects equivalentClass/exactMatch/subClassOf
/// candidates between two ontologies using weighted signals.
pub struct AlignmentEngine {
@@ -87,6 +269,8 @@ impl AlignmentEngine {
let entry = class_map.entry(iri.clone()).or_insert_with(|| ClassInfo {
iri: iri.clone(),
labels: Vec::new(),
+ kind: EntityKind::OwlClass,
+ definitions: Vec::new(),
});
for key in ["label", "altLabel"] {
@@ -103,6 +287,74 @@ impl AlignmentEngine {
}
}
+ // SKOS concepts that are not also OWL classes. A punned entity typed
+ // both stays on the OWL path above, so nothing an OWL ontology already
+ // produced can change. A concept's names are its preferred,
+ // alternative and hidden labels; `skos:hiddenLabel` exists precisely
+ // to carry the misspellings and abbreviations a matcher should find.
+ let skos_query = format!(
+ r#"SELECT ?class ?label WHERE {{
+ ?class a <{SKOS_NS}Concept> .
+ FILTER NOT EXISTS {{ ?class a <http://www.w3.org/2002/07/owl#Class> }}
+ FILTER(isIRI(?class))
+ OPTIONAL {{
+ ?class <http://www.w3.org/2000/01/rdf-schema#label>|<{SKOS_NS}prefLabel>|<{SKOS_NS}altLabel>|<{SKOS_NS}hiddenLabel> ?label
+ }}
+ }}"#
+ );
+ if let Ok(result) = store.sparql_select_union(&skos_query)
+ && let Ok(parsed) = serde_json::from_str::<serde_json::Value>(&result)
+ && let Some(rows) = parsed["results"].as_array()
+ {
+ for row in rows {
+ let Some(raw_iri) = row["class"].as_str() else { continue };
+ let iri = raw_iri.trim_matches(|c| c == '<' || c == '>').to_string();
+ let entry = class_map.entry(iri.clone()).or_insert_with(|| ClassInfo {
+ iri: iri.clone(),
+ labels: Vec::new(),
+ kind: EntityKind::SkosConcept,
+ definitions: Vec::new(),
+ });
+ if let Some(raw) = row["label"].as_str() {
+ let label = crate::language::parse_literal(raw);
+ if !label.text.is_empty()
+ && crate::language::label_matches_policy(&label, preferred)
+ && !entry.labels.contains(&label)
+ {
+ entry.labels.push(label);
+ }
+ }
+ }
+ }
+
+ // Definitions, for the reviewer. They never enter a score: a
+ // definition is prose, and string similarity over prose measures
+ // phrasing rather than meaning.
+ let def_query = format!(
+ "SELECT ?class ?def WHERE {{ ?class <{SKOS_NS}definition> ?def . FILTER(isIRI(?class)) }}"
+ );
+ if let Ok(result) = store.sparql_select_union(&def_query)
+ && let Ok(parsed) = serde_json::from_str::<serde_json::Value>(&result)
+ && let Some(rows) = parsed["results"].as_array()
+ {
+ for row in rows {
+ let (Some(c), Some(d)) = (row["class"].as_str(), row["def"].as_str()) else { continue };
+ let iri = c.trim_matches(|c| c == '<' || c == '>');
+ if let Some(entry) = class_map.get_mut(iri) {
+ let def = crate::language::parse_literal(d);
+ if !def.text.is_empty()
+ && crate::language::label_matches_policy(&def, preferred)
+ && !entry.definitions.contains(&def.text)
+ {
+ entry.definitions.push(def.text);
+ }
+ }
+ }
+ for info in class_map.values_mut() {
+ info.definitions.sort();
+ }
+ }
+
// If no policy-matching label was found, fall back to the IRI local
// name as a language-neutral label.
for info in class_map.values_mut() {
@@ -134,14 +386,28 @@ impl AlignmentEngine {
Self::extract_iris(store, &query, "prop")
}
- /// Extract rdfs:subClassOf parents for a class.
- fn extract_parents(store: &GraphStore, class_iri: &str) -> Vec<String> {
- let query = format!(
- r#"SELECT DISTINCT ?parent WHERE {{
- <{class_iri}> <http://www.w3.org/2000/01/rdf-schema#subClassOf> ?parent .
- FILTER(isIRI(?parent))
- }}"#
- );
+ /// The parents of an entity.
+ ///
+ /// An OWL class keeps the query it always had, `rdfs:subClassOf` to a named
+ /// class, so nothing an OWL ontology produced before can move. A SKOS
+ /// concept's parents are what SKOS calls them: `skos:broader` and
+ /// `skos:broaderTransitive`, plus any `rdfs:subClassOf` a hybrid vocabulary
+ /// also states.
+ fn extract_parents(store: &GraphStore, class_iri: &str, kind: EntityKind) -> Vec<String> {
+ let query = match kind {
+ EntityKind::OwlClass => format!(
+ r#"SELECT DISTINCT ?parent WHERE {{
+ <{class_iri}> <http://www.w3.org/2000/01/rdf-schema#subClassOf> ?parent .
+ FILTER(isIRI(?parent))
+ }}"#
+ ),
+ EntityKind::SkosConcept => format!(
+ r#"SELECT DISTINCT ?parent WHERE {{
+ <{class_iri}> <{SKOS_NS}broader>|<{SKOS_NS}broaderTransitive>|<http://www.w3.org/2000/01/rdf-schema#subClassOf> ?parent .
+ FILTER(isIRI(?parent))
+ }}"#
+ ),
+ };
Self::extract_iris(store, &query, "parent")
}
@@ -178,47 +444,16 @@ impl AlignmentEngine {
.collect()
}
- /// Compute property signature overlap (Jaccard on domain properties + ranges).
- fn property_overlap(store_a: &GraphStore, class_a: &str, store_b: &GraphStore, class_b: &str) -> f64 {
- let props_a = Self::extract_properties(store_a, class_a);
- let props_b = Self::extract_properties(store_b, class_b);
- let ranges_a = Self::extract_ranges(store_a, class_a);
- let ranges_b = Self::extract_ranges(store_b, class_b);
-
- // Combine property local names + range local names for comparison
- let sig_a: Vec<String> = props_a.iter().chain(ranges_a.iter()).map(|s| local_name(s)).collect();
- let sig_b: Vec<String> = props_b.iter().chain(ranges_b.iter()).map(|s| local_name(s)).collect();
-
- jaccard_similarity(&sig_a, &sig_b)
- }
-
- /// Compute parent overlap (Jaccard on rdfs:subClassOf parents by local name).
- fn parent_overlap(store_a: &GraphStore, class_a: &str, store_b: &GraphStore, class_b: &str) -> f64 {
- let parents_a: Vec<String> = Self::extract_parents(store_a, class_a)
- .iter().map(|s| local_name(s)).collect();
- let parents_b: Vec<String> = Self::extract_parents(store_b, class_b)
- .iter().map(|s| local_name(s)).collect();
- jaccard_similarity(&parents_a, &parents_b)
- }
-
- /// Compute instance overlap — shared individuals typed under both classes (by local name).
- fn instance_overlap(store_a: &GraphStore, class_a: &str, store_b: &GraphStore, class_b: &str) -> f64 {
- let query_a = format!(
- r#"SELECT DISTINCT ?ind WHERE {{ ?ind a <{class_a}> . FILTER(isIRI(?ind)) }}"#
+ /// Read every structural feature of one entity. Called once per entity
+ /// that survives the label pre-filter, not once per pair.
+ fn features(store: &GraphStore, info: &ClassInfo) -> Features {
+ let class = info.iri.as_str();
+ let instances = Self::extract_iris(
+ store,
+ &format!(r#"SELECT DISTINCT ?ind WHERE {{ ?ind a <{class}> . FILTER(isIRI(?ind)) }}"#),
+ "ind",
);
- let query_b = format!(
- r#"SELECT DISTINCT ?ind WHERE {{ ?ind a <{class_b}> . FILTER(isIRI(?ind)) }}"#
- );
- let inds_a: Vec<String> = Self::extract_iris(store_a, &query_a, "ind")
- .iter().map(|s| local_name(s)).collect();
- let inds_b: Vec<String> = Self::extract_iris(store_b, &query_b, "ind")
- .iter().map(|s| local_name(s)).collect();
- jaccard_similarity(&inds_a, &inds_b)
- }
-
- /// Compute restriction similarity — compare owl:someValuesFrom / owl:allValuesFrom restrictions.
- fn restriction_similarity(store_a: &GraphStore, class_a: &str, store_b: &GraphStore, class_b: &str) -> f64 {
- let restriction_query = |class: &str| format!(
+ let restriction_query = format!(
r#"SELECT DISTINCT ?prop ?filler WHERE {{
<{class}> <http://www.w3.org/2000/01/rdf-schema#subClassOf> ?r .
?r a <http://www.w3.org/2002/07/owl#Restriction> .
@@ -230,37 +465,18 @@ impl AlignmentEngine {
}}
}}"#
);
-
- let extract_restriction_sigs = |store: &GraphStore, class: &str| -> Vec<String> {
- let query = restriction_query(class);
- let result = match store.sparql_select_union(&query) {
- Ok(r) => r,
- Err(_) => return Vec::new(),
- };
- let parsed: serde_json::Value = match serde_json::from_str(&result) {
- Ok(v) => v,
- Err(_) => return Vec::new(),
- };
- parsed["results"]
- .as_array()
- .unwrap_or(&Vec::new())
- .iter()
- .filter_map(|row| {
- let prop = row["prop"].as_str()?;
- let filler = row["filler"].as_str()?;
- Some(format!("{}→{}", local_name(prop), local_name(filler)))
- })
- .collect()
- };
-
- let sigs_a = extract_restriction_sigs(store_a, class_a);
- let sigs_b = extract_restriction_sigs(store_b, class_b);
- jaccard_similarity(&sigs_a, &sigs_b)
- }
-
- /// Compute graph neighborhood similarity — 2-hop property comparison.
- fn neighborhood_similarity(store_a: &GraphStore, class_a: &str, store_b: &GraphStore, class_b: &str) -> f64 {
- let neighborhood_query = |class: &str| format!(
+ // The raw terms are kept, angle brackets and all, because the legacy
+ // signature was built from them and must stay byte-identical.
+ let restrictions = store
+ .sparql_select_union(&restriction_query)
+ .ok()
+ .and_then(|r| serde_json::from_str::<serde_json::Value>(&r).ok())
+ .and_then(|v| v["results"].as_array().cloned())
+ .unwrap_or_default()
+ .iter()
+ .filter_map(|row| Some((row["prop"].as_str()?.to_string(), row["filler"].as_str()?.to_string())))
+ .collect();
+ let neighborhood_query = format!(
r#"SELECT DISTINCT ?prop WHERE {{
{{
?prop <http://www.w3.org/2000/01/rdf-schema#domain> <{class}> .
@@ -272,12 +488,119 @@ impl AlignmentEngine {
}}
}}"#
);
+ Features {
+ properties: Self::extract_properties(store, class),
+ ranges: Self::extract_ranges(store, class),
+ parents: Self::extract_parents(store, class, info.kind),
+ instances,
+ restrictions,
+ neighborhood: Self::extract_iris(store, &neighborhood_query, "prop"),
+ }
+ }
+
+ /// The five structural signals as the legacy fusion computed them: Jaccard
+ /// over IRI local names. Byte-identical to the per-pair functions this
+ /// replaced, which the Anatomy hash in `docs/determinism.md` checks.
+ fn legacy_structural(a: &Features, b: &Features) -> [f64; 5] {
+ let locals = |v: &[String]| v.iter().map(|s| local_name(s)).collect::<Vec<_>>();
+ let sig = |f: &Features| {
+ f.properties.iter().chain(f.ranges.iter()).map(|s| local_name(s)).collect::<Vec<_>>()
+ };
+ let restr = |f: &Features| {
+ f.restrictions
+ .iter()
+ .map(|(p, x)| format!("{}→{}", local_name(p), local_name(x)))
+ .collect::<Vec<_>>()
+ };
+ [
+ jaccard_similarity(&sig(a), &sig(b)),
+ jaccard_similarity(&locals(&a.parents), &locals(&b.parents)),
+ jaccard_similarity(&locals(&a.instances), &locals(&b.instances)),
+ jaccard_similarity(&restr(a), &restr(b)),
+ jaccard_similarity(&locals(&a.neighborhood), &locals(&b.neighborhood)),
+ ]
+ }
- let neigh_a: Vec<String> = Self::extract_iris(store_a, &neighborhood_query(class_a), "prop")
- .iter().map(|s| local_name(s)).collect();
- let neigh_b: Vec<String> = Self::extract_iris(store_b, &neighborhood_query(class_b), "prop")
- .iter().map(|s| local_name(s)).collect();
- jaccard_similarity(&neigh_a, &neigh_b)
+ /// The five structural signals with the informativeness of each.
+ ///
+ /// Two rules, and they are the same rule twice. A feature counts only when
+ /// the OTHER vocabulary has a name for it at all: a parent the other side
+ /// has no term for cannot be compared, and its absence over there is a
+ /// coverage gap rather than a disagreement (the same reasoning
+ /// `crosswalk::certify` applies to an ancestor with no image). And a
+ /// signal is informative only when both sides keep at least one
+ /// comparable feature. Classes (parents, ranges, restriction fillers) are
+ /// recognised by local name OR by a shared normalised label; properties
+ /// and individuals by local name, as before.
+ fn informative_structural(a: &Features, va: &Vocabulary, b: &Features, vb: &Vocabulary) -> [(f64, bool); 5] {
+ type Keys = std::collections::BTreeSet<String>;
+ let id = |iri: &str| -> Keys { std::iter::once(format!("id:{}", local_name(iri))).collect() };
+ let class_keys = |iri: &str, v: &Vocabulary| -> Keys {
+ let mut k = id(iri);
+ for l in v.labels.get(iri).into_iter().flatten() {
+ k.insert(format!("label:{l}"));
+ }
+ k
+ };
+ // Keep the items the other vocabulary can name.
+ let named_in = |items: Vec<Keys>, other: &Vocabulary| -> Vec<Keys> {
+ items.into_iter().filter(|k| k.iter().any(|x| other.universe.contains(x))).collect()
+ };
+ let props = |f: &Features, v: &Vocabulary, other: &Vocabulary| {
+ let mut items: Vec<Keys> = dedup(&f.properties).iter().map(|p| id(p)).collect();
+ items.extend(dedup(&f.ranges).iter().map(|r| class_keys(r, v)));
+ named_in(items, other)
+ };
+ let classes = |list: &[String], v: &Vocabulary, other: &Vocabulary| {
+ named_in(dedup(list).iter().map(|c| class_keys(c, v)).collect(), other)
+ };
+ let ids = |list: &[String], other: &Vocabulary| named_in(dedup(list).iter().map(|c| id(c)).collect(), other);
+ let restr = |f: &Features, v: &Vocabulary, other: &Vocabulary| {
+ let mut seen = std::collections::BTreeSet::new();
+ f.restrictions
+ .iter()
+ .filter(|r| seen.insert((*r).clone()))
+ .filter_map(|(p, x)| {
+ let p = local_name(p.trim_matches(|c| c == '<' || c == '>'));
+ let filler: Vec<String> = class_keys(x.trim_matches(|c| c == '<' || c == '>'), v)
+ .into_iter()
+ .filter(|k| other.universe.contains(k))
+ .collect();
+ // Comparable only when the other side names both the
+ // property and the filler.
+ if !other.universe.contains(&format!("id:{p}")) || filler.is_empty() {
+ return None;
+ }
+ Some(filler.into_iter().map(|k| format!("{p}→{k}")).collect::<Keys>())
+ })
+ .collect::<Vec<_>>()
+ };
+ [
+ soft_jaccard(&props(a, va, vb), &props(b, vb, va)),
+ soft_jaccard(&classes(&a.parents, va, vb), &classes(&b.parents, vb, va)),
+ soft_jaccard(&ids(&a.instances, vb), &ids(&b.instances, va)),
+ soft_jaccard(&restr(a, va, vb), &restr(b, vb, va)),
+ soft_jaccard(&ids(&a.neighborhood, vb), &ids(&b.neighborhood, va)),
+ ]
+ }
+
+ /// The names one vocabulary has: every IRI's local name, and every
+ /// normalised label of every class or concept.
+ fn vocabulary(store: &GraphStore, classes: &[ClassInfo]) -> Vocabulary {
+ let labels: std::collections::HashMap<String, Vec<String>> = classes
+ .iter()
+ .map(|c| (c.iri.clone(), c.labels.iter().map(|l| normalize_label(&l.text)).collect()))
+ .collect();
+ let mut universe: std::collections::HashSet<String> = labels
+ .values()
+ .flatten()
+ .map(|l| format!("label:{l}"))
+ .collect();
+ let q = "SELECT DISTINCT ?x WHERE { { ?x ?p ?o } UNION { ?s ?x ?o } UNION { ?s ?p ?x } FILTER(isIRI(?x)) }";
+ for iri in Self::extract_iris(store, q, "x") {
+ universe.insert(format!("id:{}", local_name(&iri)));
+ }
+ Vocabulary { labels, universe }
}
/// Compute label similarity between two classes (best match across all label variants).
@@ -379,8 +702,31 @@ impl AlignmentEngine {
dry_run: bool,
fusion: &str,
) -> anyhow::Result<String> {
+ self.align_with_options(
+ source,
+ target,
+ &AlignOptions {
+ high_threshold,
+ low_threshold,
+ dry_run,
+ fusion: fusion.to_string(),
+ ..AlignOptions::default()
+ },
+ )
+ }
+
+ /// The full form: thresholds, fusion, the scoring of the weighted sum
+ /// (`Scoring`) and whether targets may repeat (`Cardinality`).
+ pub fn align_with_options(
+ &self,
+ source: &str,
+ target: Option<&str>,
+ opts: &AlignOptions,
+ ) -> anyhow::Result<String> {
+ let (high_threshold, dry_run, fusion) = (opts.high_threshold, opts.dry_run, opts.fusion.as_str());
+ let scoring = opts.scoring;
// Clamp: degenerate range means "everything above high_threshold; nothing borderline".
- let low_threshold = low_threshold.min(high_threshold);
+ let low_threshold = opts.low_threshold.min(high_threshold);
// Active language policy (empty = keep all languages / multilingual).
let preferred = crate::runtime::preferred_languages();
// For RRF the inline weighted-sum confidence is throwaway (recomputed after
@@ -416,6 +762,21 @@ impl AlignmentEngine {
// Get learned weights (or defaults)
let weights = self.get_learned_weights();
+ let total_weight: f64 = weights.iter().sum();
+
+ // What each side can name, so a parent or a restriction filler can be
+ // recognised across two vocabularies that spell it differently, and so
+ // a feature the other side has no name for is left out rather than
+ // scored as a disagreement. Not needed by the legacy fusion.
+ let (source_vocab, target_vocab) = match scoring {
+ Scoring::Informative => (
+ Self::vocabulary(&source_store, &source_classes),
+ Self::vocabulary(target_ref, &target_classes),
+ ),
+ Scoring::Legacy => (Vocabulary::default(), Vocabulary::default()),
+ };
+ let mut target_features: std::collections::HashMap<String, Features> =
+ std::collections::HashMap::new();
// HNSW prefilter (optional, transparent): when both source and target class
// IRIs have embeddings in the vecstore, use HNSW to compute a per-source
@@ -463,6 +824,7 @@ impl AlignmentEngine {
let mut candidates: Vec<serde_json::Value> = Vec::new();
for sc in &source_classes {
+ let mut source_features: Option<Features> = None;
// HNSW prefilter: if we computed a shortlist for this source, skip
// targets outside the shortlist. If the prefilter map exists but has
// no entry for THIS source (e.g. source had no embedding), fall back
@@ -495,13 +857,16 @@ impl AlignmentEngine {
// only answer for a resident store, and would silently
// score every pair at 0.0 under text-vector eviction.
match (vs.load_text_vec(&sc.iri), vs.load_text_vec(&tc.iri)) {
- (Some(a), Some(b)) => Self::embedding_similarity_score(&a, &b),
- _ => 0.0,
+ (Some(a), Some(b)) => Some(Self::embedding_similarity_score(&a, &b)),
+ _ => None,
}
} else {
- 0.0
+ None
}
};
+ #[cfg(feature = "embeddings")]
+ let (embedding_sim, embedding_present) =
+ (embedding_sim.unwrap_or(0.0), embedding_sim.is_some());
// Pre-filter: skip pairs where label similarity is too low.
// Raised from 0.7 to 0.75 to reduce false positives on anatomy-style
@@ -517,36 +882,86 @@ impl AlignmentEngine {
continue;
}
- let prop_overlap = Self::property_overlap(&source_store, &sc.iri, target_ref, &tc.iri);
- let parent_ovlp = Self::parent_overlap(&source_store, &sc.iri, target_ref, &tc.iri);
- let inst_overlap = Self::instance_overlap(&source_store, &sc.iri, target_ref, &tc.iri);
- let restr_sim = Self::restriction_similarity(&source_store, &sc.iri, target_ref, &tc.iri);
- let neigh_sim = Self::neighborhood_similarity(&source_store, &sc.iri, target_ref, &tc.iri);
+ let sf = source_features.get_or_insert_with(|| Self::features(&source_store, sc));
+ let tf = target_features
+ .entry(tc.iri.clone())
+ .or_insert_with(|| Self::features(target_ref, tc));
+ let structural: [(f64, bool); 5] = match scoring {
+ Scoring::Legacy => Self::legacy_structural(sf, tf).map(|v| (v, true)),
+ Scoring::Informative => {
+ Self::informative_structural(sf, &source_vocab, tf, &target_vocab)
+ }
+ };
+ let [prop_overlap, parent_ovlp, inst_overlap, restr_sim, neigh_sim] = structural.map(|(v, _)| v);
#[cfg(feature = "embeddings")]
let signals = [label_sim, prop_overlap, parent_ovlp, inst_overlap, restr_sim, neigh_sim, embedding_sim];
-
#[cfg(not(feature = "embeddings"))]
let signals = [label_sim, prop_overlap, parent_ovlp, inst_overlap, restr_sim, neigh_sim];
- // Compute confidence. When structural signals are all zero
- // (common in lightweight OWL files), fall back to the strongest
- // lexical/semantic signal with a penalty rather than the weighted
- // sum (which would be ~0.25 * label_sim and too low to pass any
- // threshold).
- let structural_sum: f64 = signals[1..6].iter().sum();
- let confidence: f64 = if structural_sum == 0.0 {
- // No structural evidence: apply a 15% penalty to the best
- // available signal. With embeddings this lets a strong
- // cross-lingual embedding match still surface (typically as a
- // borderline candidate for review).
- #[cfg(feature = "embeddings")]
- let best_signal = label_sim.max(embedding_sim);
- #[cfg(not(feature = "embeddings"))]
- let best_signal = label_sim;
- best_signal * 0.85
- } else {
- signals.iter().zip(weights.iter()).map(|(s, w)| s * w).sum()
+ // Which signals count for THIS pair, and the value each brings.
+ //
+ // The name always counts: every entity has one, if only its
+ // IRI's local name. So does an embedding similarity when both
+ // sides have a vector, because a cosine is a measured distance
+ // and a low one is real evidence against.
+ //
+ // A structural signal counts only as SUPPORT: when the two
+ // sides share at least one feature the other side can name,
+ // and then as 1.0. A shared parent, property, range,
+ // restriction or individual is evidence the two terms sit in
+ // the same place. The absence of a shared one is not evidence
+ // they do not: under the open-world reading the other side
+ // simply did not say it, ontologies differ in granularity and
+ // use multiple inheritance, and a term with a different direct
+ // parent can be the same term. Counting a zero as disagreement
+ // cost 0.07 F1 on OAEI Anatomy; counting a partial overlap at
+ // its Jaccard value would make one shared parent out of three
+ // score WORSE than none, which no reading of the evidence
+ // supports. Binary support is monotone: adding agreement can
+ // only raise the confidence.
+ #[allow(unused_mut)]
+ let mut counted: Vec<(bool, f64)> = std::iter::once((true, label_sim))
+ .chain(structural.iter().map(|(v, comparable)| {
+ if *comparable && *v > 0.0 { (true, 1.0) } else { (false, 0.0) }
+ }))
+ .collect();
+ #[cfg(feature = "embeddings")]
+ counted.push((embedding_present, embedding_sim));
+ let informative: Vec<bool> = counted.iter().map(|(c, _)| *c).collect();
+
+ let (confidence, coverage): (f64, f64) = match scoring {
+ Scoring::Legacy => {
+ // When structural signals are all zero, fall back to the
+ // strongest lexical/semantic signal with a 15% penalty;
+ // otherwise the weighted sum over every signal.
+ let structural_sum: f64 = signals[1..6].iter().sum();
+ let c = if structural_sum == 0.0 {
+ #[cfg(feature = "embeddings")]
+ let best_signal = label_sim.max(embedding_sim);
+ #[cfg(not(feature = "embeddings"))]
+ let best_signal = label_sim;
+ best_signal * 0.85
+ } else {
+ signals.iter().zip(weights.iter()).map(|(s, w)| s * w).sum()
+ };
+ (c, 1.0)
+ }
+ Scoring::Informative => {
+ // The weighted mean over the signals that count. A
+ // signal that carries no evidence for this pair is left
+ // out of both the numerator and the denominator, so it
+ // neither helps nor hurts.
+ let (mut num, mut den) = (0.0_f64, 0.0_f64);
+ for ((counts, value), w) in counted.iter().zip(weights.iter()) {
+ if *counts {
+ num += value * w;
+ den += w;
+ }
+ }
+ let c = if den > 0.0 { num / den } else { 0.0 };
+ (c, if total_weight > 0.0 { den / total_weight } else { 0.0 })
+ }
};
// Drop pairs below the low threshold entirely (for RRF, this is
@@ -573,7 +988,7 @@ impl AlignmentEngine {
signals_json["embedding_similarity"] = serde_json::json!((embedding_sim * 1000.0).round() / 1000.0);
}
- candidates.push(serde_json::json!({
+ let mut candidate = serde_json::json!({
"source_iri": sc.iri,
"target_iri": tc.iri,
"relation": relation,
@@ -581,7 +996,17 @@ impl AlignmentEngine {
"signals": signals_json,
"applied": false,
"requires_review": requires_review,
- }));
+ });
+ if scoring == Scoring::Informative {
+ candidate["informative_signals"] = serde_json::json!(Self::SIGNAL_NAMES
+ .iter()
+ .zip(informative.iter())
+ .filter(|(_, i)| **i)
+ .map(|(n, _)| *n)
+ .collect::<Vec<_>>());
+ candidate["evidence_coverage"] = serde_json::json!((coverage * 1000.0).round() / 1000.0);
+ }
+ candidates.push(candidate);
}
}
@@ -613,32 +1038,75 @@ impl AlignmentEngine {
.then_with(|| a["target_iri"].as_str().unwrap_or("").cmp(b["target_iri"].as_str().unwrap_or("")))
});
- // Stable matching: for each source class, keep only the top-scoring target.
- // For each target class, keep only the top-scoring source.
- // This enforces a 1-to-1 matching constraint that dramatically reduces
- // false positives on benchmarks like OAEI Anatomy.
+ // Stable matching. One-to-one keeps the top-scoring target for each
+ // source and the top-scoring source for each target, which is what cut
+ // false positives on OAEI Anatomy. Many-to-one keeps the top target for
+ // each source and lets targets repeat, for a source finer than its
+ // target.
+ //
+ // A row dropped because a kept row scored the same (within
+ // TIE_EPSILON) lost to IRI spelling, not to evidence. It is named on
+ // the kept row under `tied_with`, the kept row is marked `ambiguous`,
+ // and an ambiguous row goes to review: the engine did not choose it,
+ // so it must not write it.
{
- let mut used_sources: std::collections::HashSet<String> = std::collections::HashSet::new();
- let mut used_targets: std::collections::HashSet<String> = std::collections::HashSet::new();
- candidates.retain(|c| {
+ let one_to_one = opts.cardinality == Cardinality::OneToOne;
+ let mut kept: Vec<serde_json::Value> = Vec::with_capacity(candidates.len());
+ let mut by_source: std::collections::HashMap<String, usize> = std::collections::HashMap::new();
+ let mut by_target: std::collections::HashMap<String, usize> = std::collections::HashMap::new();
+ for c in candidates.drain(..) {
let src = c["source_iri"].as_str().unwrap_or("").to_string();
let tgt = c["target_iri"].as_str().unwrap_or("").to_string();
- if used_sources.contains(&src) || used_targets.contains(&tgt) {
- false
- } else {
- used_sources.insert(src);
- used_targets.insert(tgt);
- true
+ let blocked_by_source = by_source.get(&src).copied();
+ let blocked_by_target = if one_to_one { by_target.get(&tgt).copied() } else { None };
+ if blocked_by_source.is_none() && blocked_by_target.is_none() {
+ by_source.insert(src, kept.len());
+ if one_to_one {
+ by_target.insert(tgt, kept.len());
+ }
+ kept.push(c);
+ continue;
}
- });
+ let conf = c["confidence"].as_f64().unwrap_or(0.0);
+ let mut blockers = vec![blocked_by_source, blocked_by_target];
+ blockers.dedup();
+ for k in blockers.into_iter().flatten() {
+ let kept_conf = kept[k]["confidence"].as_f64().unwrap_or(0.0);
+ if (kept_conf - conf).abs() <= TIE_EPSILON {
+ let entry = serde_json::json!({
+ "source_iri": src,
+ "target_iri": tgt,
+ "confidence": conf,
+ });
+ match kept[k]["tied_with"].as_array_mut() {
+ Some(list) => list.push(entry),
+ None => kept[k]["tied_with"] = serde_json::json!([entry]),
+ }
+ }
+ }
+ }
+ for c in &mut kept {
+ let ambiguous = c["tied_with"].as_array().is_some_and(|l| !l.is_empty());
+ if !ambiguous {
+ c["tied_with"] = serde_json::json!([]);
+ }
+ c["ambiguous"] = serde_json::json!(ambiguous);
+ if ambiguous {
+ c["requires_review"] = serde_json::json!(true);
+ }
+ }
+ candidates = kept;
}
+ let ambiguous_count = candidates.iter().filter(|c| c["ambiguous"] == true).count();
// Auto-apply above high_threshold.
let mut applied_count = 0;
if !dry_run {
for candidate in &mut candidates {
- let conf = candidate["confidence"].as_f64().unwrap_or(0.0);
- if conf >= high_threshold {
+ // `requires_review` rather than the bare threshold: an
+ // ambiguous row clears the threshold and is still not the
+ // engine's choice to write.
+ if !candidate["requires_review"].as_bool().unwrap_or(true) {
let source_iri = candidate["source_iri"].as_str().unwrap();
let target_iri = candidate["target_iri"].as_str().unwrap();
let relation = candidate["relation"].as_str().unwrap();
@@ -672,14 +1140,32 @@ impl AlignmentEngine {
.get(t_iri.as_str())
.map(|c| c.labels.iter().map(|l| l.tagged()).collect())
.unwrap_or_default();
- let s_parents = Self::extract_parents(&source_store, &s_iri);
- let t_parents = Self::extract_parents(target_ref, &t_iri);
+ let s_info = source_class_map.get(s_iri.as_str());
+ let t_info = target_class_map.get(t_iri.as_str());
+ let s_parents = Self::extract_parents(
+ &source_store,
+ &s_iri,
+ s_info.map(|c| c.kind).unwrap_or(EntityKind::OwlClass),
+ );
+ let t_parents = Self::extract_parents(
+ target_ref,
+ &t_iri,
+ t_info.map(|c| c.kind).unwrap_or(EntityKind::OwlClass),
+ );
candidate["context"] = serde_json::json!({
"source_labels": s_labels,
"target_labels": t_labels,
"source_parents": s_parents,
"target_parents": t_parents,
});
+ // Definitions only when there are some, so the context of a
+ // vocabulary that carries none is unchanged.
+ let s_defs = s_info.map(|c| c.definitions.clone()).unwrap_or_default();
+ let t_defs = t_info.map(|c| c.definitions.clone()).unwrap_or_default();
+ if !s_defs.is_empty() || !t_defs.is_empty() {
+ candidate["context"]["source_definitions"] = serde_json::json!(s_defs);
+ candidate["context"]["target_definitions"] = serde_json::json!(t_defs);
+ }
}
// Partition into auto-applied vs borderline buckets (back-compat: `candidates`
@@ -723,6 +1209,11 @@ impl AlignmentEngine {
// Back-compat alias — older callers read "threshold".
"threshold": high_threshold,
"summary_for_review": summary_for_review,
+ "scoring": scoring.as_str(),
+ "scoring_means": scoring.means(),
+ "cardinality": opts.cardinality.as_str(),
+ "ambiguous_count": ambiguous_count,
+ "tie_epsilon": 0.001,
}).to_string())
}
@@ -983,10 +1474,48 @@ fn jaccard_similarity(a: &[String], b: &[String]) -> f64 {
pub struct ClassInfo {
pub iri: String,
/// Labels with their parsed language tags. Populated from rdfs:label /
- /// skos:prefLabel / skos:altLabel (and OBO synonyms), filtered by the
- /// active language policy. Falls back to a single language-neutral label
- /// derived from the IRI local name when no policy-matching label exists.
+ /// skos:prefLabel / skos:altLabel (and OBO synonyms; for a SKOS concept
+ /// also skos:hiddenLabel), filtered by the active language policy. Falls
+ /// back to a single language-neutral label derived from the IRI local name
+ /// when no policy-matching label exists.
pub labels: Vec<crate::language::Label>,
+ /// Whether this is an OWL class or a SKOS concept, which decides where
+ /// its parents are read from.
+ pub kind: EntityKind,
+ /// `skos:definition` values, shown to the reviewer and never scored.
+ pub definitions: Vec<String>,
+}
+
+/// Each element of `v` once, in first-seen order.
+fn dedup(v: &[String]) -> Vec<&String> {
+ let mut seen = std::collections::HashSet::new();
+ v.iter().filter(|x| seen.insert(x.as_str())).collect()
+}
+
+/// Jaccard over items that each carry a SET of keys, two items matching when
+/// their key sets meet. Returns the similarity and whether it is informative,
+/// which needs at least one item on each side.
+///
+/// When every item carries exactly one key this is ordinary set Jaccard. The
+/// matching is greedy in input order, which is deterministic and at most one
+/// item short of a maximum matching per conflict; nothing here needs more.
+fn soft_jaccard(
+ a: &[std::collections::BTreeSet<String>],
+ b: &[std::collections::BTreeSet<String>],
+) -> (f64, bool) {
+ if a.is_empty() || b.is_empty() {
+ return (0.0, false);
+ }
+ let mut used = vec![false; b.len()];
+ let mut matched = 0usize;
+ for ka in a {
+ if let Some(j) = (0..b.len()).find(|&j| !used[j] && !ka.is_disjoint(&b[j])) {
+ used[j] = true;
+ matched += 1;
+ }
+ }
+ let union = a.len() + b.len() - matched;
+ (matched as f64 / union as f64, true)
}
/// Extract local name from an IRI (after last # or /).
@@ -1037,6 +1566,8 @@ mod tests {
let a = ClassInfo {
iri: "http://ex.org/Dog".into(),
labels: vec![crate::language::Label::new("Dog", None)],
+ kind: EntityKind::OwlClass,
+ definitions: vec![],
};
let b = ClassInfo {
iri: "http://other.org/Canine".into(),
@@ -1044,6 +1575,8 @@ mod tests {
crate::language::Label::new("Dog", None),
crate::language::Label::new("Canine", None),
],
+ kind: EntityKind::OwlClass,
+ definitions: vec![],
};
// Exact label match should give 1.0
let sim = AlignmentEngine::label_similarity(&a, &b);
@@ -1182,10 +1715,14 @@ mod tests {
let a = ClassInfo {
iri: "http://ex.org/DomesticCat".into(),
labels: vec![crate::language::Label::new("DomesticCat", None)],
+ kind: EntityKind::OwlClass,
+ definitions: vec![],
};
let b = ClassInfo {
iri: "http://other.org/HouseCat".into(),
labels: vec![crate::language::Label::new("Domestic Cat", None)],
+ kind: EntityKind::OwlClass,
+ definitions: vec![],
};
let sim = AlignmentEngine::label_similarity(&a, &b);
assert!(sim > 0.95, "CamelCase split should match: {}", sim);
diff --git a/src/batch.rs b/src/batch.rs
index 8a75080a..487e93a7 100644
--- a/src/batch.rs
+++ b/src/batch.rs
@@ -155,6 +155,9 @@ impl BatchRunner {
"ingest" => self.exec_ingest(&cmd.args),
"induce" => self.exec_induce(&cmd.args),
"crosswalk-certify" | "crosswalk_certify" => Self::exec_crosswalk(&cmd.args),
+ "crosswalk-probe" | "crosswalk_probe" | "contradiction-probe" | "contradiction_probe" => {
+ Self::exec_crosswalk_probe(&cmd.args)
+ }
"modules" | "distributed" => Self::exec_modules(&cmd.args),
"matcert" => Self::exec_matcert(&cmd.args),
"drift" => self.exec_drift(&cmd.args),
@@ -702,6 +705,22 @@ impl BatchRunner {
}
}
+ /// Carry a crosswalk's claims into the target and look for a clash.
+ ///
+ /// The sharper question beside `crosswalk-certify`: not whether the two
+ /// sides differ in granularity but whether the target's own axioms DENY
+ /// something the mapping carries in. Its own stores, for the same reason
+ /// as `crosswalk-certify`. Reports `exit_code: 1` when the mapping adds a
+ /// clash, so a batch that runs it fails on a contradiction.
+ fn exec_crosswalk_probe(args: &[String]) -> Value {
+ let pos: Vec<&String> = args.iter().filter(|a| !a.starts_with("--")).collect();
+ if pos.len() < 3 {
+ return json!({"error": "crosswalk-probe needs SOURCE TARGET MAPPINGS.tsv"});
+ }
+ crate::crosswalk::probe_files(pos[0], pos[1], pos[2])
+ .unwrap_or_else(|e| json!({"error": e.to_string()}))
+ }
+
/// Reason each module alone, then promote what k of n agree on.
///
/// Modules are `NAME=FILE` pairs. Separate arguments rather than one
diff --git a/src/crosswalk.rs b/src/crosswalk.rs
index b3a89fb7..42d9f578 100644
--- a/src/crosswalk.rs
+++ b/src/crosswalk.rs
@@ -31,9 +31,37 @@
//! `tests/crosswalk_certify_test.rs` pins it with a worked example rather
//! than trusting this paragraph.
//! * `b` is the more specific one: `narrowMatch`.
-//! * The two disagree in both directions, or an ancestor has no image in the
-//! target at all: `relatedMatch`, which is the weakest thing SKOS lets you
-//! say and the honest answer when the vocabularies do not line up.
+//! * The two disagree in both directions: `relatedMatch`, which is the
+//! weakest thing SKOS lets you say and the honest answer when the
+//! vocabularies do not line up.
+//!
+//! # Only what can be compared is compared
+//!
+//! An ancestor of the subject that the mapping carries no row for has no
+//! image in the target, so nothing over there can agree or disagree with it.
+//! The same holds the other way for an ancestor of the object that no row
+//! maps onto. Both are COVERAGE gaps: they are named on the row
+//! (`untranslatable`, `object_uncovered`), the unmapped source terms are
+//! listed under `unmapped`, and the row's `certification` word says the
+//! comparison was partial. Neither is evidence that the two terms differ, and
+//! neither downgrades the claim. This used to be otherwise: an untranslatable
+//! ancestor forced `relatedMatch`, so one missing row for a section heading
+//! downgraded every term beneath it, and a target-side section with no
+//! source counterpart turned every correct `exactMatch` from a flat list into
+//! `narrowMatch`. A feasibility run on a food-waste taxonomy downgraded every
+//! row that way, which made the check carry no information at all.
+//!
+//! # What a supported predicate establishes, and what it cannot
+//!
+//! The comparison is between POSITIONS in two hierarchies, read through the
+//! mapping. It can refute a claim (the subject sits under a mapped concept
+//! the object does not), and it can fail to refute one. It cannot confirm
+//! that two terms mean the same thing: two siblings under one mapped parent
+//! have identical translated ancestors, so a row pairing the wrong sibling is
+//! upheld exactly as the right one is. That is why the output never
+//! STRENGTHENS a claim: a row that claimed `closeMatch` keeps `closeMatch` in
+//! the SSSOM predicate column even when the hierarchy is compatible with
+//! `exactMatch`, because compatibility is not evidence of identity.
//!
//! # What is NOT checked, and is said rather than hidden
//!
@@ -89,8 +117,19 @@ pub struct Certified {
pub object_ancestors: BTreeSet<String>,
/// Subject ancestors the mapping cannot carry into the target vocabulary.
/// A non-empty set here is the Foundry case: the target cannot express
- /// something the source says.
+ /// something the source says. A coverage gap, named rather than scored.
pub untranslatable: BTreeSet<String>,
+ /// Object ancestors that no mapping row maps onto, so nothing on the
+ /// source side can be compared with them. The same gap from the other
+ /// side.
+ pub object_uncovered: BTreeSet<String>,
+ /// One word for what the check did: `downgraded`, `upheld` (compared,
+ /// nothing missing), `upheld_with_coverage_gap` (compared, some
+ /// ancestors could not be), or `not_refuted_nothing_compared` (no
+ /// ancestor on either side could be compared, whether because there is
+ /// no hierarchy or because the mapping carries none of it, so the row is
+ /// neither refuted nor supported by anything and is not certified).
+ pub certification: &'static str,
/// Why, in one sentence a reader can act on.
pub because: String,
}
@@ -117,50 +156,78 @@ fn strip(t: &str) -> String {
/// ENTAILS, not about what its author happened to write down. That is the
/// whole point: a crosswalk that looks right against asserted triples can be
/// wrong against entailed ones.
+///
+/// This is the hierarchy the contradiction probe carries into the target as
+/// `rdfs:subClassOf`, so it holds subsumption and nothing else.
fn ancestors(store: &Arc<GraphStore>) -> anyhow::Result<BTreeMap<String, BTreeSet<String>>> {
Reasoner::run_full(store, "owl-rl", true, InferenceTarget::DefaultGraph, None)?;
let q = "SELECT ?c ?p WHERE { ?c <http://www.w3.org/2000/01/rdf-schema#subClassOf> ?p . \
FILTER(!isBlank(?c) && !isBlank(?p) && ?c != ?p) }";
- let js: serde_json::Value = serde_json::from_str(&store.sparql_select(q)?)?;
+ let mut out = collect_pairs(store, q)?;
+ for v in out.values_mut() {
+ // owl:Thing is entailed above everything and distinguishes nothing.
+ v.retain(|p| !p.ends_with("#Thing"));
+ }
+ out.retain(|_, v| !v.is_empty());
+ Ok(out)
+}
+
+/// The hierarchy the match-type check compares: entailed superclasses, and
+/// for a SKOS vocabulary its broader concepts.
+///
+/// A SKOS scheme states its hierarchy with `skos:broader` and never with
+/// `rdfs:subClassOf`. Read through subclass axioms alone, every concept of a
+/// pure SKOS scheme had no ancestors, every row compared two empty sets, and
+/// every row was upheld: a deliberately wrong crosswalk certified clean, so
+/// the check could not fail on SKOS input at all. `skos:broaderTransitive` is
+/// transitive and `skos:broader` is its sub-property (SKOS reference, 8.6.4),
+/// so the transitive closure over both is what a SKOS scheme entails. The
+/// closure reaches each concept's top concept, which is the axis
+/// `skos:topConceptOf` marks, so the axis takes part in the comparison
+/// whenever the mapping carries a row for it. Scheme membership
+/// (`skos:inScheme`) is not read as an ancestor: every concept of a scheme
+/// shares it, so it cannot tell two concepts of one scheme apart, and an
+/// unmapped scheme would only add the same coverage gap to every row.
+///
+/// `broader` is not subsumption, which is why this set stays out of the
+/// contradiction probe.
+fn hierarchy(store: &Arc<GraphStore>) -> anyhow::Result<BTreeMap<String, BTreeSet<String>>> {
+ let mut out = ancestors(store)?;
+ let q = "SELECT DISTINCT ?c ?p WHERE { \
+ ?c (<http://www.w3.org/2004/02/skos/core#broader>|<http://www.w3.org/2004/02/skos/core#broaderTransitive>)+ ?p . \
+ FILTER(isIRI(?c) && isIRI(?p) && ?c != ?p) }";
+ for (c, ps) in collect_pairs(store, q)? {
+ out.entry(c).or_default().extend(ps);
+ }
+ Ok(out)
+}
+
+fn collect_pairs(
+ store: &Arc<GraphStore>,
+ query: &str,
+) -> anyhow::Result<BTreeMap<String, BTreeSet<String>>> {
+ let js: serde_json::Value = serde_json::from_str(&store.sparql_select(query)?)?;
let mut out: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
for row in js["results"].as_array().cloned().unwrap_or_default() {
let (Some(c), Some(p)) = (row["c"].as_str(), row["p"].as_str()) else { continue };
- let (c, p) = (strip(c), strip(p));
- // owl:Thing is entailed above everything and distinguishes nothing.
- if p.ends_with("#Thing") {
- continue;
- }
- out.entry(c).or_default().insert(p);
+ out.entry(strip(c)).or_default().insert(strip(p));
}
Ok(out)
}
/// The tightest SKOS predicate two ancestor sets support.
///
-/// Returns the predicate and the sentence explaining it. Superset means MORE
-/// ancestors, which means the more specific concept: a concept under more
-/// things is lower in the hierarchy.
-fn tightest(
- sub_in_target: &BTreeSet<String>,
- obj: &BTreeSet<String>,
- untranslatable: &BTreeSet<String>,
-) -> (&'static str, String) {
- if !untranslatable.is_empty() {
- let n = untranslatable.len();
- return (
- "relatedMatch",
- format!(
- "{n} entailed ancestor(s) of the subject have no image in the target \
- vocabulary, so the two cannot be compared where it matters most. This is \
- the case a crosswalk hides: the target does not carry the distinction."
- ),
- );
- }
+/// Both sets are already restricted to what can be compared: the subject's
+/// ancestors that have an image, translated, and the object's ancestors that
+/// are an image. Returns the predicate and the sentence explaining it.
+/// Superset means MORE ancestors, which means the more specific concept: a
+/// concept under more things is lower in the hierarchy.
+fn tightest(sub_in_target: &BTreeSet<String>, obj: &BTreeSet<String>) -> (&'static str, String) {
if sub_in_target == obj {
return (
"exactMatch",
- "both sides entail the same ancestors once translated, and nothing was lost in \
- translation."
+ "both sides entail the same ancestors once translated, over every ancestor the \
+ mapping lets the two compare."
.to_string(),
);
}
@@ -194,13 +261,16 @@ pub fn certify(
target: &Arc<GraphStore>,
mappings: &[Mapping],
) -> anyhow::Result<(Vec<Certified>, Vec<Gap>)> {
- let sa = ancestors(source)?;
- let ta = ancestors(target)?;
+ let sa = hierarchy(source)?;
+ let ta = hierarchy(target)?;
// The mapping is its own translation table, which is the point: a bridge
// is checked against itself rather than against a second, unstated one.
let fwd: BTreeMap<&str, &str> =
mappings.iter().map(|m| (m.subject.as_str(), m.object.as_str())).collect();
+ // Every target term some row maps onto. An object ancestor outside this
+ // set has no counterpart the source could be compared with.
+ let images: BTreeSet<&str> = mappings.iter().map(|m| m.object.as_str()).collect();
let mut rows = Vec::new();
for m in mappings {
@@ -220,20 +290,54 @@ pub fn certify(
}
}
}
+ let (o_comparable, object_uncovered): (BTreeSet<String>, BTreeSet<String>) =
+ o_anc.iter().cloned().partition(|c| images.contains(c.as_str()));
- let (supported, because) = tightest(&translated, &o_anc, &untranslatable);
+ let (supported, mut because) = tightest(&translated, &o_comparable);
let claimed = m.predicate.rsplit(['#', '/']).next().unwrap_or("").to_string();
let rank = |p: &str| TIGHTEST_FIRST.iter().position(|q| *q == p).unwrap_or(usize::MAX);
+ // Stronger than the evidence, by the SKOS ordering. A claim that was
+ // already weaker than the evidence is not "upgraded" here: the file
+ // said less than it could, which is not a defect.
+ let downgraded = rank(&claimed) < rank(supported);
+ let gap = !untranslatable.is_empty() || !object_uncovered.is_empty();
+ let compared = !translated.is_empty() || !o_comparable.is_empty();
+ if gap {
+ because.push_str(&format!(
+ " {} ancestor(s) of the subject have no image in the target and {} ancestor(s) \
+ of the object have no counterpart in the source; they could not be compared, \
+ which is a gap in the mapping's coverage and not evidence that the two terms \
+ differ.",
+ untranslatable.len(),
+ object_uncovered.len()
+ ));
+ }
+ if !compared {
+ because = format!(
+ "nothing to compare: neither term has an ancestor the mapping carries across, \
+ so the hierarchy can neither support nor refute this row and it is NOT \
+ certified.{}",
+ if gap { " The ancestors that exist have no counterpart through the mapping." } else { "" }
+ );
+ }
+ let certification = if downgraded {
+ "downgraded"
+ } else if !compared {
+ "not_refuted_nothing_compared"
+ } else if gap {
+ "upheld_with_coverage_gap"
+ } else {
+ "upheld"
+ };
rows.push(Certified {
mapping: m.clone(),
supported,
- // Stronger than the evidence, by the SKOS ordering. A claim that was
- // already weaker than the evidence is not "upgraded" here: the file
- // said less than it could, which is not a defect.
- downgraded: rank(&claimed) < rank(supported),
+ downgraded,
subject_ancestors: s_anc,
object_ancestors: o_anc,
untranslatable,
+ object_uncovered,
+ certification,
because,
});
}
@@ -269,18 +373,31 @@ pub fn report(rows: &[Certified], gaps: &[Gap]) -> serde_json::Value {
"claimed": r.mapping.predicate,
"supported": format!("{SKOS}{}", r.supported),
"downgraded": r.downgraded,
+ "certification": r.certification,
"because": r.because,
"subject_ancestors": r.subject_ancestors.iter().collect::<Vec<_>>(),
"object_ancestors": r.object_ancestors.iter().collect::<Vec<_>>(),
"untranslatable": r.untranslatable.iter().collect::<Vec<_>>(),
+ "object_uncovered": r.object_uncovered.iter().collect::<Vec<_>>(),
})).collect::<Vec<_>>(),
"unmapped": gaps.iter().map(|g| serde_json::json!({
"term": g.term, "side": g.side, "reason": g.reason,
})).collect::<Vec<_>>(),
"verdict": "checked_by_this_engine",
"means": "each side was reasoned INDEPENDENTLY under OWL 2 RL and the entailed named \
- ancestors were compared through the mapping itself. A supported predicate \
- means nothing this engine can see refutes it. It is NOT a proof: the \
+ ancestors were compared through the mapping itself. What this checks is the \
+ POSITION of the two terms in their hierarchies, not what they mean: a \
+ downgrade is a refutation (the subject sits under a mapped concept the \
+ object does not, or the reverse), and an upheld row means only that nothing \
+ this engine can see refutes it. Two siblings under one mapped parent have \
+ identical translated ancestors, so a row pairing the wrong sibling is upheld \
+ exactly as the right one is, which is why the predicate column never \
+ strengthens a claim. Only ancestors both sides can name are compared: an \
+ ancestor with no counterpart through the mapping is a coverage gap, named on \
+ the row and never counted as a disagreement, and a row with nothing \
+ comparable, including a term with no hierarchy at all, is \
+ not_refuted_nothing_compared and is NOT certified. A SKOS scheme's hierarchy is \
+ its skos:broader closure. It is NOT a proof: the \
comparison is over 29 of OWL 2 RL's 78 rules, and an axiom no rule fires on \
contributes to neither side. Run onto_dlp_boundary to see which of your \
axioms were invisible. No Lean checker has a theorem about SKOS match types, \
@@ -292,22 +409,33 @@ pub fn report(rows: &[Certified], gaps: &[Gap]) -> serde_json::Value {
///
/// Extra columns rather than a new format, so a reader who already has SSSOM
/// tooling gets this as a strict upgrade and nobody is asked to adopt
-/// anything. `predicate_id` carries the SUPPORTED predicate, because a file
-/// whose predicate column still said `exactMatch` after this ran would be
-/// worse than no check at all.
+/// anything. `predicate_id` carries the SUPPORTED predicate when the claim was
+/// downgraded, because a file whose predicate column still said `exactMatch`
+/// after this ran would be worse than no check at all. Otherwise it keeps the
+/// CLAIMED predicate: a hierarchy that is compatible with `exactMatch` cannot
+/// tell two siblings apart, so writing `exactMatch` over a claimed
+/// `closeMatch` would manufacture a certainty nobody supplied.
pub fn to_sssom(rows: &[Certified], gaps: &[Gap]) -> String {
let mut out = String::from(
"subject_id\tpredicate_id\tobject_id\tmapping_justification\t\
claimed_predicate_id\tcertification\tcomment\n",
);
for r in rows {
+ let written = if r.downgraded {
+ format!("skos:{}", r.supported)
+ } else {
+ match r.mapping.predicate.strip_prefix(SKOS) {
+ Some(local) => format!("skos:{local}"),
+ None => r.mapping.predicate.clone(),
+ }
+ };
out.push_str(&format!(
- "{}\tskos:{}\t{}\tsemapv:LogicalReasoning\t{}\t{}\t{}\n",
+ "{}\t{}\t{}\tsemapv:LogicalReasoning\t{}\t{}\t{}\n",
r.mapping.subject,
- r.supported,
+ written,
r.mapping.object,
r.mapping.predicate,
- if r.downgraded { "downgraded" } else { "upheld" },
+ r.certification,
r.because.replace('\t', " "),
));
}
@@ -409,6 +537,23 @@ pub fn certify_files(
/// notion of contradiction, so what counts as a disagreement here is exactly
/// what counts as one everywhere else in this engine.
///
+/// Two things make the answer mean what it says.
+///
+/// * WITNESSES. Those detectors need an individual: `cax-dw` fires on a thing
+/// typed with two disjoint classes, and a class made unsatisfiable by a
+/// carried subsumption is invisible while nothing is typed with it. A
+/// taxonomy or a crosswalk is all TBox and has no individuals, so without
+/// help every probe of one would come back clean by construction. Each
+/// target class that receives a carried claim therefore gets one fresh
+/// witness individual, which turns "this class can have no members" into a
+/// clash the detectors see.
+/// * A BASELINE. The witnesses are also typed into the target ALONE, without
+/// the carried claims, and reasoned. A target that clashes on its own, or
+/// whose own classes are unsatisfiable, is reported under `target_alone`
+/// and is not blamed on the mapping: only clashes the carried claims ADD
+/// count. Reasoning here is monotone, so the probe can only add clashes,
+/// and a higher count is exactly the mapping's contribution.
+///
/// The limit travels with the answer: those ten are the rules this engine
/// LOOKS FOR, out of the seventeen in OWL 2 RL that conclude false. A clean
/// probe is not a proof of compatibility.
@@ -423,6 +568,7 @@ pub fn contradiction_probe(
let mut carried = Vec::new();
let mut nt = String::new();
+ let mut receivers: BTreeSet<String> = BTreeSet::new();
for (c, anc) in &sa {
let Some(ci) = fwd.get(c.as_str()) else { continue };
for a in anc {
@@ -431,30 +577,88 @@ pub fn contradiction_probe(
"<{ci}> <http://www.w3.org/2000/01/rdf-schema#subClassOf> <{ai}> .\n"
));
carried.push(serde_json::json!({"subject": ci, "ancestor": ai, "from": c}));
+ receivers.insert((*ci).to_string());
}
}
- let probe = Arc::new(GraphStore::new());
- probe.load_turtle(target_ttl, None)?;
- probe.load_turtle(&nt, None)?;
- let out = Reasoner::run_full(&probe, "owl-rl", false, InferenceTarget::DefaultGraph, None)?;
- let r: serde_json::Value = serde_json::from_str(&out)?;
- let found = r["inconsistency"]["found"] == serde_json::Value::Bool(true);
+ let mut witnesses_nt = String::new();
+ let mut witnesses = Vec::new();
+ for (n, class) in receivers.iter().enumerate() {
+ let w = format!("urn:open-ontologies:crosswalk-probe:witness:{n}");
+ witnesses_nt.push_str(&format!(
+ "<{w}> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <{class}> .\n"
+ ));
+ witnesses.push(serde_json::json!({"witness": w, "typed": class}));
+ }
+
+ let reason = |with_carried: bool| -> anyhow::Result<serde_json::Value> {
+ let store = Arc::new(GraphStore::new());
+ store.load_turtle(target_ttl, None)?;
+ store.load_turtle(&witnesses_nt, None)?;
+ if with_carried {
+ store.load_turtle(&nt, None)?;
+ }
+ let out = Reasoner::run_full(&store, "owl-rl", false, InferenceTarget::DefaultGraph, None)?;
+ Ok(serde_json::from_str(&out)?)
+ };
+ let alone = reason(false)?;
+ let probed = reason(true)?;
+ let count = |r: &serde_json::Value| {
+ if r["inconsistency"]["found"] == serde_json::Value::Bool(true) {
+ r["inconsistency"]["clash_count"].as_u64().unwrap_or(1)
+ } else {
+ 0
+ }
+ };
+ let (before, after) = (count(&alone), count(&probed));
+ let found = after > before;
+ let verdict = if found {
+ "the_target_denies_what_the_mapping_carried"
+ } else if before > 0 {
+ "no_contradiction_added_by_the_mapping_but_the_target_clashes_on_its_own"
+ } else {
+ "no_contradiction_among_the_rules_this_engine_looks_for"
+ };
Ok(serde_json::json!({
"carried": carried.len(),
"carried_claims": carried,
+ "witnesses": witnesses,
"contradicted": found,
- "clashes": r["inconsistency"]["clashes"],
- "by_rule": r["inconsistency"]["by_rule"],
- "verdict": if found { "the_target_denies_what_the_mapping_carried" }
- else { "no_contradiction_among_the_rules_this_engine_looks_for" },
+ "clashes_added_by_the_mapping": after - before,
+ "clashes": probed["inconsistency"]["clashes"],
+ "by_rule": probed["inconsistency"]["by_rule"],
+ "target_alone": {
+ "clash_count": before,
+ "by_rule": alone["inconsistency"]["by_rule"],
+ },
+ "verdict": verdict,
+ // A contradiction is a finding a script must not walk past.
+ "exit_code": if found { 1 } else { 0 },
"means": "the target's own axioms, plus the source's entailed subsumptions translated \
- through the mapping, reasoned together. A contradiction here is a DISAGREEMENT \
- and not a granularity gap: either the mapping row is wrong or the two \
- ontologies encode incompatible claims, and a person has to decide which. A \
- clean probe is NOT proof of compatibility: ten of the seventeen OWL 2 RL \
- rules that conclude false are looked for, and nothing was checked about the \
- other seven.",
+ through the mapping, reasoned together, with one witness individual typed \
+ into every target class that received a carried claim so that a class the \
+ claims make unsatisfiable shows up as a clash. Only clashes the carried \
+ claims ADD are counted; clashes the target has with the witnesses alone are \
+ reported under target_alone and are not blamed on the mapping. A \
+ contradiction here is a DISAGREEMENT and not a granularity gap: either the \
+ mapping row is wrong or the two ontologies encode incompatible claims, and a \
+ person has to decide which. A clean probe is NOT proof of compatibility: ten \
+ of the seventeen OWL 2 RL rules that conclude false are looked for, and \
+ nothing was checked about the other seven.",
}))
}
+
+/// Run the contradiction probe from three files, as the command line hands
+/// them over. The target may be in any RDF format the engine reads.
+pub fn probe_files(
+ source_path: &str,
+ target_path: &str,
+ mapping_path: &str,
+) -> anyhow::Result<serde_json::Value> {
+ let source = Arc::new(GraphStore::new());
+ source.load_file(source_path)?;
+ let target_ttl = GraphStore::read_as_turtle(target_path)?;
+ let mappings = parse_sssom(&std::fs::read_to_string(mapping_path)?)?;
+ contradiction_probe(&source, &target_ttl, &mappings)
+}
diff --git a/src/inputs.rs b/src/inputs.rs
index dbf26ce1..ee4ad135 100644
--- a/src/inputs.rs
+++ b/src/inputs.rs
@@ -787,10 +787,12 @@ pub struct OntoAlignInput {
pub source: String,
/// Target ontology: inline Turtle content or file path. If omitted, aligns against loaded store
pub target: Option<String>,
- /// Minimum confidence threshold for auto-apply (default 0.85). Back-compat alias for
- /// `high_threshold` — if both are set, `high_threshold` wins.
+ /// Minimum confidence threshold for auto-apply (default 0.95, or 0.85 under
+ /// `scoring: "legacy"`). Back-compat alias for `high_threshold` — if both are
+ /// set, `high_threshold` wins.
pub min_confidence: Option<f64>,
- /// Confidence threshold above which a candidate is auto-applied (default 0.85, or
+ /// Confidence threshold above which a candidate is auto-applied (default 0.95, or
+ /// 0.85 under `scoring: "legacy"`, the same strictness on each scale; or
/// `min_confidence` if provided for back-compat). Candidates above this land in
/// `auto_applied`.
pub high_threshold: Option<f64>,
@@ -808,6 +810,18 @@ pub struct OntoAlignInput {
/// choice; the weighted_sum self-calibrates from `onto_align_feedback` over time.
#[serde(default)]
pub fusion: Option<String>,
+ /// How the weighted sum becomes a confidence. "informative" (default): the
+ /// weighted mean over the signals BOTH sides carry data for, each candidate
+ /// naming them in `informative_signals`. "legacy": the fusion the published
+ /// OAEI figures were measured with (label x 0.85 when no structural signal
+ /// fires, otherwise the weighted sum over all signals).
+ #[serde(default)]
+ pub scoring: Option<String>,
+ /// "one-to-one" (default) keeps one row per source and per target.
+ /// "many-to-one" lets several source terms map to the same target, which
+ /// is right when the source is finer than the target.
+ #[serde(default)]
+ pub cardinality: Option<String>,
}
#[derive(Deserialize, JsonSchema)]
diff --git a/src/main.rs b/src/main.rs
index 608ba72c..a99da0d0 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -895,12 +895,41 @@ enum Commands {
source: String,
/// Target ontology file (if omitted, aligns against loaded store)
target: Option<String>,
- /// Minimum confidence threshold (default 0.85)
- #[arg(long, default_value = "0.85")]
- min_confidence: f64,
+ /// Minimum confidence threshold (default 0.95, or 0.85 with
+ /// `--scoring legacy`, which is the same strictness on each scale)
+ #[arg(long)]
+ min_confidence: Option<f64>,
/// Dry run — show candidates without inserting triples
#[arg(long)]
dry_run: bool,
+ /// How the weighted sum becomes a confidence: `informative` (default:
+ /// the weighted mean over the signals both sides carry data for) or
+ /// `legacy` (the fusion the published OAEI figures were measured with)
+ #[arg(long, default_value = "informative")]
+ scoring: String,
+ /// `one-to-one` (default) keeps one row per source and per target;
+ /// `many-to-one` lets several source terms map to one target, for a
+ /// source list finer than its target
+ #[arg(long, default_value = "one-to-one")]
+ cardinality: String,
+ },
+ /// Carry a crosswalk's claims into the target and report any clash
+ ///
+ /// The source's entailed subsumptions are translated through the mapping
+ /// (an SSSOM TSV) and reasoned together with the target's axioms. A clash
+ /// the carried claims ADD means the target denies what the mapping says:
+ /// a wrong row, or two ontologies that disagree. One witness individual is
+ /// typed into each receiving class so a TBox-only taxonomy can clash at
+ /// all, and clashes the target has on its own are reported apart. Exits 1
+ /// when the mapping adds a clash. The same check runs in `batch` as
+ /// `crosswalk-probe`.
+ CrosswalkProbe {
+ /// The ontology the mapping's subjects come from
+ source: String,
+ /// The ontology the mapping's objects come from
+ target: String,
+ /// The crosswalk, as SSSOM TSV (subject_id, predicate_id, object_id)
+ mappings: String,
},
/// Accept or reject an alignment candidate
AlignFeedback {
@@ -3717,7 +3746,10 @@ async fn async_main() -> anyhow::Result<()> {
target,
min_confidence,
dry_run,
+ scoring,
+ cardinality,
} => {
+ use open_ontologies::align::{AlignOptions, Cardinality, Scoring};
let (db, graph) = setup(&cli.data_dir)?;
let source_ttl = std::fs::read_to_string(&source)?;
let target_ttl = match target {
@@ -3725,10 +3757,39 @@ async fn async_main() -> anyhow::Result<()> {
None => None,
};
let engine = open_ontologies::align::AlignmentEngine::new(db, graph);
- let result = engine
- .align(&source_ttl, target_ttl.as_deref(), min_confidence, dry_run)
- .unwrap_or_else(|e| format!(r#"{{"error":"{}"}}"#, e));
- output_result(&result, cli.pretty);
+ // The command line has one threshold, so the borderline bucket is
+ // empty here exactly as it always was: low == high.
+ let result = Scoring::parse(&scoring)
+ .and_then(|scoring| {
+ let cardinality = Cardinality::parse(&cardinality)?;
+ let min_confidence =
+ min_confidence.unwrap_or_else(|| scoring.default_high_threshold());
+ engine.align_with_options(
+ &source_ttl,
+ target_ttl.as_deref(),
+ &AlignOptions {
+ high_threshold: min_confidence,
+ low_threshold: min_confidence,
+ dry_run,
+ scoring,
+ cardinality,
+ ..AlignOptions::default()
+ },
+ )
+ })
+ .unwrap_or_else(|e| serde_json::json!({"error": e.to_string()}).to_string());
+ output_result_with_exit(&result, cli.pretty);
+ }
+ Commands::CrosswalkProbe {
+ source,
+ target,
+ mappings,
+ } => {
+ // Runs here rather than through a daemon: it builds its own two
+ // stores and never reads the loaded one.
+ let result = open_ontologies::crosswalk::probe_files(&source, &target, &mappings)
+ .unwrap_or_else(|e| serde_json::json!({"error": e.to_string()}));
+ output_result_with_exit(&result.to_string(), cli.pretty);
}
Commands::AlignFeedback {
source,
diff --git a/src/server.rs b/src/server.rs
index 38ce13cb..74aa315f 100644
--- a/src/server.rs
+++ b/src/server.rs
@@ -2969,7 +2969,7 @@ impl OpenOntologiesServer {
}
}
- #[tool(name = "onto_align", description = "Detect alignment candidates (owl:equivalentClass, skos:exactMatch, rdfs:subClassOf) between two ontologies using label similarity, property overlap, parent overlap, instance overlap, restriction patterns, and graph neighborhood. Auto-applies high-confidence matches above threshold.")]
+ #[tool(name = "onto_align", description = "Detect alignment candidates (owl:equivalentClass, skos:exactMatch, rdfs:subClassOf) between two ontologies or SKOS vocabularies (owl:Class and skos:Concept) using label similarity, property overlap, parent overlap, instance overlap, restriction patterns, and graph neighborhood. Confidence is the weighted mean over the signals that carry evidence for the pair (`scoring`: informative, or legacy for the published OAEI figures). `cardinality`: one-to-one or many-to-one. Ties are reported under `tied_with` and never auto-applied. Auto-applies high-confidence matches above threshold.")]
async fn onto_align(&self, Parameters(input): Parameters<OntoAlignInput>) -> String {
let engine = crate::align::AlignmentEngine::new(self.db.clone(), self.graph.clone());
@@ -2998,20 +2998,46 @@ impl OpenOntologiesServer {
None => None,
};
- let high = input.high_threshold.or(input.min_confidence).unwrap_or(0.85);
+ let dry_run = input.dry_run.unwrap_or(false);
+ let fusion = input.fusion.as_deref().unwrap_or("weighted_sum");
+ let scoring = match crate::align::Scoring::parse(input.scoring.as_deref().unwrap_or("informative")) {
+ Ok(s) => s,
+ Err(e) => return Self::err_json(e),
+ };
+ let high = input
+ .high_threshold
+ .or(input.min_confidence)
+ .unwrap_or_else(|| scoring.default_high_threshold());
// Default low_threshold = 0.4 surfaces a borderline bucket for LLM-orchestrated review.
// Callers wanting the old strict behaviour pass low_threshold == high_threshold.
let low = input.low_threshold.unwrap_or(0.4).min(high);
- let dry_run = input.dry_run.unwrap_or(false);
- let fusion = input.fusion.as_deref().unwrap_or("weighted_sum");
+ let cardinality = match crate::align::Cardinality::parse(input.cardinality.as_deref().unwrap_or("one-to-one")) {
+ Ok(c) => c,
+ Err(e) => return Self::err_json(e),
+ };
+ let opts = crate::align::AlignOptions {
+ high_threshold: high,
+ low_threshold: low,
+ dry_run,
+ fusion: fusion.to_string(),
+ scoring,
+ cardinality,
+ };
- match engine.align_with_fusion(&source, target.as_deref(), high, low, dry_run, fusion) {
+ match engine.align_with_options(&source, target.as_deref(), &opts) {
Ok(result) => {
self.lineage().record(
&self.session_id,
"AL",
"align",
- &format!("high={},low={},fusion={}", high, low, fusion),
+ &format!(
+ "high={},low={},fusion={},scoring={},cardinality={}",
+ high,
+ low,
+ fusion,
+ scoring.as_str(),
+ cardinality.as_str()
+ ),
);
result
}
diff --git a/tests/align_borderline_test.rs b/tests/align_borderline_test.rs
index ce4b97cf..9e4e15de 100644
--- a/tests/align_borderline_test.rs
+++ b/tests/align_borderline_test.rs
@@ -40,6 +40,20 @@ const TARGET: &str = r#"
tg:Cat a owl:Class ; rdfs:label "Cat" ; rdfs:subClassOf tg:Animal .
"#;
+/// The same hierarchy with every name one letter off. An exact name with
+/// nothing else to compare now scores 1.0 (see
+/// `tests/align_informative_scoring_test.rs`), so mid-confidence candidates
+/// need names that are close and not equal.
+const NEAR_TARGET: &str = r#"
+ @prefix owl: <http://www.w3.org/2002/07/owl#> .
+ @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+ @prefix tg: <http://target.org/> .
+
+ tg:Animals a owl:Class ; rdfs:label "Animals" .
+ tg:Dogs a owl:Class ; rdfs:label "Dogs" ; rdfs:subClassOf tg:Animals .
+ tg:Cats a owl:Class ; rdfs:label "Cats" ; rdfs:subClassOf tg:Animals .
+"#;
+
#[test]
fn degenerate_thresholds_preserve_legacy_behaviour() {
// low == high → no borderline bucket. Output shape matches the old align() semantics.
@@ -72,10 +86,9 @@ fn borderline_bucket_collects_mid_confidence_candidates() {
let (db, graph) = setup();
let engine = AlignmentEngine::new(db, graph);
- // high=0.95 is above what label-only matching produces here; low=0.4 catches
- // the label-similarity-only matches.
+ // high=0.95 is above what near-miss names produce here; low=0.4 catches them.
let result_str = engine
- .align_with_thresholds(SOURCE, Some(TARGET), 0.95, 0.4, true)
+ .align_with_thresholds(SOURCE, Some(NEAR_TARGET), 0.95, 0.4, true)
.expect("align_with_thresholds");
let result: serde_json::Value = serde_json::from_str(&result_str).expect("json");
@@ -135,7 +148,7 @@ fn summary_for_review_present_when_borderline_nonempty() {
let engine = AlignmentEngine::new(db, graph);
let result_str = engine
- .align_with_thresholds(SOURCE, Some(TARGET), 0.95, 0.4, true)
+ .align_with_thresholds(SOURCE, Some(NEAR_TARGET), 0.95, 0.4, true)
.expect("align_with_thresholds");
let result: serde_json::Value = serde_json::from_str(&result_str).expect("json");
diff --git a/tests/align_informative_scoring_test.rs b/tests/align_informative_scoring_test.rs
new file mode 100644
index 00000000..d612a2de
--- /dev/null
+++ b/tests/align_informative_scoring_test.rs
@@ -0,0 +1,428 @@
+//! Confidence is a weighted mean over the signals that carry information for
+//! the pair, not over every signal the engine knows.
+//!
+//! The old fusion had two branches. When every structural signal was zero it
+//! returned `label_similarity * 0.85`, so a perfect name match between two flat
+//! lists could never score above 0.85 however exact it was. When any
+//! structural signal was non-zero it returned the plain weighted sum, in which
+//! a signal with no data on either side still contributed its weight times
+//! zero. The second branch made agreement COST confidence: two classes with
+//! the same name and the same parent scored `0.25 + 0.15 = 0.40`, less than
+//! half what the same pair scored with the parent deleted.
+//!
+//! Neither branch is a choice anyone would defend. A signal with no data on
+//! one side is ignorance, not disagreement: a SKOS concept has no
+//! `rdfs:domain` properties because SKOS does not model them, not because the
+//! concept differs from an OWL class that has some. So a signal now enters the
+//! mean only when BOTH sides carry data for it, and the mean is taken over the
+//! weights of those signals alone. Each candidate names the signals that
+//! counted (`informative_signals`) and the share of the total weight they hold
+//! (`evidence_coverage`), so a 1.0 that rests on a name alone reads as exactly
+//! that.
+
+use open_ontologies::align::AlignmentEngine;
+use open_ontologies::graph::GraphStore;
+use open_ontologies::state::StateDb;
+use serde_json::Value;
+use std::collections::HashMap;
+use std::sync::Arc;
+
+fn engine_with(db: StateDb) -> AlignmentEngine {
+ AlignmentEngine::new(db, Arc::new(GraphStore::new()))
+}
+
+fn fresh_db() -> StateDb {
+ let dir = tempfile::tempdir().unwrap();
+ let db = StateDb::open(&dir.path().join("state.db")).unwrap();
+ std::mem::forget(dir);
+ db
+}
+
+fn run(engine: &AlignmentEngine, source: &str, target: &str) -> Value {
+ run_low(engine, source, target, 0.4)
+}
+
+fn run_low(engine: &AlignmentEngine, source: &str, target: &str, low: f64) -> Value {
+ let out = engine
+ .align_with_thresholds(source, Some(target), 0.85, low, true)
+ .expect("align runs");
+ serde_json::from_str(&out).expect("JSON")
+}
+
+fn only(result: &Value, source_tail: &str) -> Value {
+ result["candidates"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .find(|c| c["source_iri"].as_str().unwrap().ends_with(source_tail))
+ .unwrap_or_else(|| panic!("no candidate for {source_tail}: {result}"))
+ .clone()
+}
+
+const FLAT_SOURCE: &str = r#"
+ @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ @prefix s: <http://flat-a.example/> .
+ s:exact a skos:Concept ; skos:prefLabel "Landfill"@en .
+ s:weak a skos:Concept ; skos:prefLabel "Sewer treatment"@en .
+"#;
+
+const FLAT_TARGET: &str = r#"
+ @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ @prefix t: <http://flat-b.example/> .
+ t:LF a skos:Concept ; skos:prefLabel "Landfill"@en .
+ t:SW a skos:Concept ; skos:prefLabel "Sewage"@en .
+"#;
+
+#[test]
+fn an_exact_name_between_two_flat_lists_reaches_high_confidence() {
+ let r = run(&engine_with(fresh_db()), FLAT_SOURCE, FLAT_TARGET);
+ let exact = only(&r, "/exact");
+ let conf = exact["confidence"].as_f64().unwrap();
+ assert!(
+ conf > 0.99,
+ "two flat lists have nothing to compare but names, so an exact name is all the \
+ evidence there is and it is perfect. The old fusion capped this at 0.85: {exact}"
+ );
+ assert_eq!(exact["applied"], false, "dry run");
+ assert_eq!(exact["requires_review"], false, "{exact}");
+}
+
+#[test]
+fn a_weak_name_between_two_flat_lists_cannot() {
+ let r = run(&engine_with(fresh_db()), FLAT_SOURCE, FLAT_TARGET);
+ let weak = only(&r, "/weak");
+ let conf = weak["confidence"].as_f64().unwrap();
+ let label = weak["signals"]["label_similarity"].as_f64().unwrap();
+ assert!(label < 0.85, "the fixture is built for a weak name: {weak}");
+ assert!(
+ (conf - label).abs() < 1e-9,
+ "with a name as the only evidence, confidence IS the name similarity: {weak}"
+ );
+ assert_eq!(
+ weak["requires_review"], true,
+ "a weak name alone must land in review, never auto-applied: {weak}"
+ );
+}
+
+#[test]
+fn the_output_names_the_signals_that_counted() {
+ let r = run(&engine_with(fresh_db()), FLAT_SOURCE, FLAT_TARGET);
+ assert_eq!(r["scoring"], "informative_renormalised", "{r}");
+ let exact = only(&r, "/exact");
+ let informative: Vec<&str> = exact["informative_signals"]
+ .as_array()
+ .unwrap_or_else(|| panic!("informative_signals missing: {exact}"))
+ .iter()
+ .filter_map(|v| v.as_str())
+ .collect();
+ assert_eq!(informative, vec!["label_similarity"], "{exact}");
+ let coverage = exact["evidence_coverage"].as_f64().unwrap();
+ assert!(
+ coverage > 0.0 && coverage < 0.5,
+ "a confidence of 1.0 resting on the name alone must say how little of the \
+ evidence it rests on: {exact}"
+ );
+}
+
+const OWL_PARENT_SOURCE: &str = r#"
+ @prefix owl: <http://www.w3.org/2002/07/owl#> .
+ @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+ @prefix a: <http://parents-a.example/> .
+ a:Animal a owl:Class ; rdfs:label "Animal" .
+ a:Dog a owl:Class ; rdfs:label "Dog" ; rdfs:subClassOf a:Animal .
+"#;
+
+const OWL_PARENT_TARGET: &str = r#"
+ @prefix owl: <http://www.w3.org/2002/07/owl#> .
+ @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+ @prefix b: <http://parents-b.example/> .
+ b:Animal a owl:Class ; rdfs:label "Animal" .
+ b:Dog a owl:Class ; rdfs:label "Dog" ; rdfs:subClassOf b:Animal .
+"#;
+
+#[test]
+fn agreeing_structure_never_lowers_confidence() {
+ // Same name, same parent. The old weighted sum scored this 0.40, because
+ // four signals with no data on either side still carried their weight.
+ let r = run(
+ &engine_with(fresh_db()),
+ OWL_PARENT_SOURCE,
+ OWL_PARENT_TARGET,
+ );
+ let dog = only(&r, "/Dog");
+ assert!(
+ dog["signals"]["parent_overlap"].as_f64().unwrap() > 0.99,
+ "{dog}"
+ );
+ assert!(
+ dog["confidence"].as_f64().unwrap() > 0.99,
+ "a matching parent is more evidence for the match, not less: {dog}"
+ );
+}
+
+/// The same flat names as `FLAT_*`, but each concept now sits under a parent,
+/// and the two parents differ. Both parents exist on both sides, so each side
+/// CAN name the other's parent: the two simply did not put the term in the
+/// same place.
+const DISAGREEING_SOURCE: &str = r#"
+ @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ @prefix s: <http://dis-a.example/> .
+ s:Destinations a skos:Concept ; skos:prefLabel "Waste destinations"@en .
+ s:Sites a skos:Concept ; skos:prefLabel "Geological formations"@en .
+ s:exact a skos:Concept ; skos:prefLabel "Landfill"@en ; skos:broader s:Destinations .
+"#;
+
+const DISAGREEING_TARGET: &str = r#"
+ @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ @prefix t: <http://dis-b.example/> .
+ t:Destinations a skos:Concept ; skos:prefLabel "Waste destinations"@en .
+ t:Sites a skos:Concept ; skos:prefLabel "Geological formations"@en .
+ t:LF a skos:Concept ; skos:prefLabel "Landfill"@en ; skos:broader t:Sites .
+"#;
+
+/// The same again, with a second parent on each side, one of them shared.
+const PARTLY_AGREEING_SOURCE: &str = r#"
+ @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ @prefix s: <http://part-a.example/> .
+ s:Destinations a skos:Concept ; skos:prefLabel "Waste destinations"@en .
+ s:Sites a skos:Concept ; skos:prefLabel "Geological formations"@en .
+ s:Disposal a skos:Concept ; skos:prefLabel "Disposal"@en .
+ s:exact a skos:Concept ; skos:prefLabel "Landfill"@en ; skos:broader s:Destinations , s:Disposal .
+"#;
+
+const PARTLY_AGREEING_TARGET: &str = r#"
+ @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ @prefix t: <http://part-b.example/> .
+ t:Destinations a skos:Concept ; skos:prefLabel "Waste destinations"@en .
+ t:Sites a skos:Concept ; skos:prefLabel "Geological formations"@en .
+ t:Disposal a skos:Concept ; skos:prefLabel "Disposal"@en .
+ t:LF a skos:Concept ; skos:prefLabel "Landfill"@en ; skos:broader t:Sites , t:Disposal .
+"#;
+
+#[test]
+fn a_parent_not_shared_is_not_a_denial_and_partial_agreement_never_scores_below_none() {
+ // Open world: the target not putting Landfill under destinations is not
+ // the target saying it is NOT a destination. Ontologies differ in
+ // granularity and use multiple inheritance, and on OAEI Anatomy counting
+ // such a zero as disagreement cost 0.07 F1. So it neither helps nor hurts.
+ let flat = only(
+ &run(&engine_with(fresh_db()), FLAT_SOURCE, FLAT_TARGET),
+ "/exact",
+ );
+ let dis = only(
+ &run(
+ &engine_with(fresh_db()),
+ DISAGREEING_SOURCE,
+ DISAGREEING_TARGET,
+ ),
+ "/exact",
+ );
+ assert_eq!(
+ dis["signals"]["parent_overlap"], 0.0,
+ "the fixture shares no parent: {dis}"
+ );
+ assert_eq!(dis["confidence"], flat["confidence"], "{dis}");
+ assert!(
+ !dis["informative_signals"]
+ .to_string()
+ .contains("parent_overlap"),
+ "a parent nobody shares carries no evidence and must not be listed as counting: {dis}"
+ );
+
+ // One shared parent out of three is MORE evidence than none, so it must
+ // not score lower. A weighted mean that took the Jaccard value (1/3)
+ // would put this pair below the one above.
+ let part = only(
+ &run(
+ &engine_with(fresh_db()),
+ PARTLY_AGREEING_SOURCE,
+ PARTLY_AGREEING_TARGET,
+ ),
+ "/exact",
+ );
+ let jaccard = part["signals"]["parent_overlap"].as_f64().unwrap();
+ assert!(
+ jaccard > 0.0 && jaccard < 1.0,
+ "the fixture shares one parent of three: {part}"
+ );
+ assert!(
+ part["confidence"].as_f64().unwrap() >= dis["confidence"].as_f64().unwrap(),
+ "agreement can only raise confidence: partly={part} none={dis}"
+ );
+ assert!(
+ part["informative_signals"]
+ .to_string()
+ .contains("parent_overlap"),
+ "{part}"
+ );
+}
+
+#[test]
+fn a_parent_on_one_side_only_neither_helps_nor_hurts() {
+ let flat = only(
+ &run(&engine_with(fresh_db()), FLAT_SOURCE, FLAT_TARGET),
+ "/exact",
+ );
+ let one_sided = only(
+ &run(&engine_with(fresh_db()), FLAT_SOURCE, DISAGREEING_TARGET),
+ "/exact",
+ );
+ assert_eq!(one_sided["confidence"], flat["confidence"], "{one_sided}");
+}
+
+/// A near name under a shared parent: the case the learned weights decide.
+const NEAR_SOURCE: &str = r#"
+ @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ @prefix s: <http://near-a.example/> .
+ s:Destinations a skos:Concept ; skos:prefLabel "Waste destinations"@en .
+ s:near a skos:Concept ; skos:prefLabel "Sewer treatment"@en ; skos:broader s:Destinations .
+"#;
+
+const NEAR_TARGET: &str = r#"
+ @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ @prefix t: <http://near-b.example/> .
+ t:Destinations a skos:Concept ; skos:prefLabel "Waste destinations"@en .
+ t:SW a skos:Concept ; skos:prefLabel "Sewage"@en ; skos:broader t:Destinations .
+"#;
+
+#[test]
+fn learned_weights_still_move_the_score() {
+ // Self-calibration must survive the change. A shared parent lifts a weak
+ // name; train the weights to distrust parents (siblings share them too)
+ // and the lift must shrink.
+ let db = fresh_db();
+ let before = only(
+ &run_low(&engine_with(db.clone()), NEAR_SOURCE, NEAR_TARGET, 0.0),
+ "/near",
+ );
+ assert!(
+ before["informative_signals"]
+ .to_string()
+ .contains("parent_overlap"),
+ "{before}"
+ );
+
+ let eng = engine_with(db.clone());
+ for i in 0..6 {
+ let accepted: HashMap<String, f64> = [
+ ("label_similarity".to_string(), 1.0),
+ ("parent_overlap".to_string(), 0.0),
+ ]
+ .into();
+ eng.record_feedback(
+ &format!("http://a/{i}"),
+ "http://b/x",
+ "skos:exactMatch",
+ true,
+ Some(&accepted),
+ )
+ .unwrap();
+ let rejected: HashMap<String, f64> = [
+ ("label_similarity".to_string(), 0.8),
+ ("parent_overlap".to_string(), 1.0),
+ ]
+ .into();
+ eng.record_feedback(
+ &format!("http://c/{i}"),
+ "http://d/x",
+ "skos:exactMatch",
+ false,
+ Some(&rejected),
+ )
+ .unwrap();
+ }
+ let after = only(
+ &run_low(&engine_with(db), NEAR_SOURCE, NEAR_TARGET, 0.0),
+ "/near",
+ );
+ let (b, a) = (
+ before["confidence"].as_f64().unwrap(),
+ after["confidence"].as_f64().unwrap(),
+ );
+ let label = after["signals"]["label_similarity"].as_f64().unwrap();
+ assert!((0.0..=1.0).contains(&a), "{after}");
+ assert!(
+ a < b,
+ "weights that distrust parents must shrink the lift a shared parent gives: before={b} after={a}"
+ );
+ assert!(
+ a >= label,
+ "and the lift cannot turn into a penalty: {after}"
+ );
+}
+
+#[test]
+fn the_legacy_fusion_is_kept_behind_a_flag_and_reproduces_the_old_numbers() {
+ // Every published alignment figure (OAEI Anatomy F1 0.829, Conference
+ // 0.438) was measured with the old fusion, so it stays reachable. These
+ // are the two numbers the old code produced on these fixtures: the 0.85
+ // cap on a perfect flat name, and the weighted sum of name and parent for
+ // the same name and same parent. That sum is 0.25 + 0.15 = 0.40 with the
+ // six default weights, and 0.20 + 0.12 = 0.32 when the embeddings feature
+ // adds a seventh signal and rescales the rest (no vectors are loaded here,
+ // so the embedding term contributes 0).
+ use open_ontologies::align::{AlignOptions, Scoring};
+ let legacy = AlignOptions {
+ scoring: Scoring::Legacy,
+ dry_run: true,
+ ..AlignOptions::default()
+ };
+ let eng = engine_with(fresh_db());
+ let flat: Value = serde_json::from_str(
+ &eng.align_with_options(FLAT_SOURCE, Some(FLAT_TARGET), &legacy)
+ .unwrap(),
+ )
+ .unwrap();
+ assert_eq!(flat["scoring"], "legacy");
+ assert_eq!(only(&flat, "/exact")["confidence"], 0.85, "{flat}");
+ let parents: Value = serde_json::from_str(
+ &eng.align_with_options(
+ OWL_PARENT_SOURCE,
+ Some(OWL_PARENT_TARGET),
+ &AlignOptions {
+ low_threshold: 0.0,
+ ..legacy.clone()
+ },
+ )
+ .unwrap(),
+ )
+ .unwrap();
+ #[cfg(not(feature = "embeddings"))]
+ let expected = 0.25 + 0.15;
+ #[cfg(feature = "embeddings")]
+ let expected = 0.20 + 0.12;
+ let got = only(&parents, "/Dog")["confidence"].as_f64().unwrap();
+ assert!((got - expected).abs() < 1e-9, "expected {expected}, got {got}: {parents}");
+}
+
+#[test]
+fn the_command_line_takes_the_scoring_flag() {
+ let dir = tempfile::tempdir().unwrap();
+ let (s, t) = (dir.path().join("s.ttl"), dir.path().join("t.ttl"));
+ std::fs::write(&s, FLAT_SOURCE).unwrap();
+ std::fs::write(&t, FLAT_TARGET).unwrap();
+ let run = |scoring: &str| -> (Option<i32>, Value) {
+ let out = std::process::Command::new(env!("CARGO_BIN_EXE_open-ontologies"))
+ .arg("--data-dir")
+ .arg(dir.path().join("data"))
+ .args(["align"])
+ .arg(&s)
+ .arg(&t)
+ .args(["--min-confidence", "0.5", "--dry-run", "--scoring", scoring])
+ .output()
+ .unwrap();
+ let v = serde_json::from_slice(&out.stdout).unwrap_or(Value::Null);
+ (out.status.code(), v)
+ };
+ let (code, v) = run("legacy");
+ assert_eq!(code, Some(0), "{v}");
+ assert_eq!(only(&v, "/exact")["confidence"], 0.85, "{v}");
+ let (_, v) = run("informative");
+ assert_eq!(only(&v, "/exact")["confidence"], 1.0, "{v}");
+ let (code, v) = run("no-such-scoring");
+ assert_eq!(
+ code,
+ Some(1),
+ "an unknown scoring is an error, not a silent default: {v}"
+ );
+}
diff --git a/tests/align_skos_test.rs b/tests/align_skos_test.rs
new file mode 100644
index 00000000..4adb08ad
--- /dev/null
+++ b/tests/align_skos_test.rs
@@ -0,0 +1,188 @@
+//! `align` against SKOS vocabularies, and against a mix of OWL and SKOS.
+//!
+//! The candidate generator used to read `?c a owl:Class` and nothing else, so a
+//! pure SKOS taxonomy, which declares `skos:Concept` and never `owl:Class`,
+//! produced no candidates at all. Nothing said why: the report was a clean
+//! `total_candidates: 0`, which reads as "these two vocabularies share no
+//! terms" when the truth was "one side was never read". A feasibility run
+//! mapping a food-waste source list onto a SKOS taxonomy hit exactly that.
+//!
+//! A SKOS concept carries the same three things the scorer needs from a class,
+//! under different predicates: its names (`skos:prefLabel`, `skos:altLabel`,
+//! `skos:hiddenLabel`), its parents (`skos:broader`, `skos:broaderTransitive`)
+//! and its definition (`skos:definition`). These tests pin each of them on
+//! small synthetic fixtures. OWL behaviour is not touched: an entity typed
+//! `owl:Class` is read exactly as before, which the OWL-only tests in
+//! `src/align.rs` and the Anatomy hash in `docs/determinism.md` keep honest.
+
+use open_ontologies::align::AlignmentEngine;
+use open_ontologies::graph::GraphStore;
+use open_ontologies::state::StateDb;
+use serde_json::Value;
+use std::sync::Arc;
+
+fn engine() -> AlignmentEngine {
+ let dir = tempfile::tempdir().unwrap();
+ let db = StateDb::open(&dir.path().join("state.db")).unwrap();
+ // The directory must outlive the engine's connection.
+ std::mem::forget(dir);
+ AlignmentEngine::new(db, Arc::new(GraphStore::new()))
+}
+
+fn run(source: &str, target: &str, high: f64, low: f64) -> Value {
+ let out = engine()
+ .align_with_thresholds(source, Some(target), high, low, true)
+ .expect("align runs");
+ serde_json::from_str(&out).expect("align returns JSON")
+}
+
+fn pair<'a>(result: &'a Value, source_tail: &str, target_tail: &str) -> Option<&'a Value> {
+ result["candidates"].as_array().unwrap().iter().find(|c| {
+ c["source_iri"].as_str().unwrap().ends_with(source_tail)
+ && c["target_iri"].as_str().unwrap().ends_with(target_tail)
+ })
+}
+
+/// A source list as a reporting template would publish it: flat, coded
+/// concepts, one name each, some names reaching the target only through an
+/// alternative or hidden label.
+const SKOS_SOURCE: &str = r#"
+ @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ @prefix src: <http://source.example/list/> .
+ src:c01 a skos:Concept ; skos:prefLabel "Bakery"@en .
+ src:c02 a skos:Concept ; skos:prefLabel "Milk products"@en ; skos:altLabel "Dairy products"@en .
+ src:c03 a skos:Concept ; skos:prefLabel "Frozen desserts"@en ; skos:hiddenLabel "Edible ices"@en .
+"#;
+
+/// A two-level taxonomy: every leaf has a `skos:broader` parent and a
+/// definition. No `owl:Class` anywhere, which is what a SKOS scheme looks like.
+const SKOS_TARGET: &str = r#"
+ @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ @prefix tx: <http://target.example/tax#> .
+ tx:Scheme a skos:ConceptScheme .
+ tx:PC a skos:Concept ; skos:prefLabel "Product category"@en ; skos:topConceptOf tx:Scheme .
+ tx:BAK a skos:Concept ; skos:prefLabel "Bakery"@en ; skos:broader tx:PC ;
+ skos:definition "Bread and ordinary bakery wares."@en .
+ tx:DRY a skos:Concept ; skos:prefLabel "Dairy products"@en ; skos:broader tx:PC .
+ tx:ICE a skos:Concept ; skos:prefLabel "Edible ices"@en ; skos:broaderTransitive tx:PC .
+"#;
+
+#[test]
+fn a_pure_skos_target_yields_candidates() {
+ let r = run(SKOS_SOURCE, SKOS_TARGET, 0.85, 0.4);
+ assert!(
+ r["total_candidates"].as_u64().unwrap_or(0) >= 3,
+ "three source concepts share a name with three target concepts; a SKOS target \
+ read as empty would report none: {r}"
+ );
+ assert!(
+ pair(&r, "c01", "#BAK").is_some(),
+ "prefLabel to prefLabel: {r}"
+ );
+}
+
+#[test]
+fn alternative_and_hidden_labels_are_names() {
+ let r = run(SKOS_SOURCE, SKOS_TARGET, 0.85, 0.4);
+ let dairy = pair(&r, "c02", "#DRY").unwrap_or_else(|| panic!("altLabel route missing: {r}"));
+ assert!(
+ dairy["signals"]["label_similarity"].as_f64().unwrap() > 0.99,
+ "{dairy}"
+ );
+ let ices = pair(&r, "c03", "#ICE").unwrap_or_else(|| panic!("hiddenLabel route missing: {r}"));
+ assert!(
+ ices["signals"]["label_similarity"].as_f64().unwrap() > 0.99,
+ "{ices}"
+ );
+}
+
+#[test]
+fn broader_is_read_as_the_parent_and_definitions_reach_the_reviewer() {
+ // A high threshold above 1 puts every candidate in the borderline bucket,
+ // which is the bucket that carries the reviewer's context block.
+ let r = run(SKOS_SOURCE, SKOS_TARGET, 1.01, 0.0);
+ let bak = pair(&r, "c01", "#BAK").unwrap_or_else(|| panic!("no Bakery pair: {r}"));
+ let parents: Vec<&str> = bak["context"]["target_parents"]
+ .as_array()
+ .unwrap_or_else(|| panic!("no target_parents: {bak}"))
+ .iter()
+ .filter_map(|p| p.as_str())
+ .collect();
+ assert_eq!(
+ parents,
+ vec!["http://target.example/tax#PC"],
+ "skos:broader is the parent: {bak}"
+ );
+ let defs = bak["context"]["target_definitions"].to_string();
+ assert!(
+ defs.contains("Bread and ordinary bakery wares."),
+ "skos:definition reaches the reviewer: {bak}"
+ );
+
+ let ice = pair(&r, "c03", "#ICE").unwrap_or_else(|| panic!("no ices pair: {r}"));
+ assert!(
+ ice["context"]["target_parents"]
+ .to_string()
+ .contains("tax#PC"),
+ "skos:broaderTransitive is a parent too: {ice}"
+ );
+}
+
+/// An OWL ontology on one side and a SKOS scheme on the other: the case of a
+/// data model being mapped onto a reporting taxonomy.
+const OWL_SOURCE: &str = r#"
+ @prefix owl: <http://www.w3.org/2002/07/owl#> .
+ @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+ @prefix m: <http://model.example/> .
+ m:Bakery a owl:Class ; rdfs:label "Bakery" .
+ m:DairyProducts a owl:Class ; rdfs:label "Dairy products" .
+ m:Vehicle a owl:Class ; rdfs:label "Vehicle" .
+"#;
+
+#[test]
+fn owl_classes_align_onto_skos_concepts_and_back() {
+ let forward = run(OWL_SOURCE, SKOS_TARGET, 0.85, 0.4);
+ assert!(
+ pair(&forward, "/Bakery", "#BAK").is_some(),
+ "OWL to SKOS: {forward}"
+ );
+ assert!(
+ pair(&forward, "/DairyProducts", "#DRY").is_some(),
+ "OWL to SKOS: {forward}"
+ );
+ assert!(
+ forward["candidates"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .all(|c| !c["source_iri"].as_str().unwrap().ends_with("Vehicle")),
+ "a class with no counterpart must not be matched: {forward}"
+ );
+
+ let backward = run(SKOS_TARGET, OWL_SOURCE, 0.85, 0.4);
+ assert!(
+ pair(&backward, "#BAK", "/Bakery").is_some(),
+ "SKOS to OWL: {backward}"
+ );
+}
+
+#[test]
+fn an_entity_that_is_both_a_class_and_a_concept_is_read_once() {
+ // Punning is legal and common in SKOS-OWL hybrids. The entity must appear
+ // once, read as a class, rather than twice with a duplicate candidate.
+ let punned = r#"
+ @prefix owl: <http://www.w3.org/2002/07/owl#> .
+ @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+ @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ @prefix p: <http://punned.example/> .
+ p:Bakery a owl:Class , skos:Concept ; rdfs:label "Bakery" ; skos:prefLabel "Bakery"@en .
+ "#;
+ let r = run(punned, SKOS_TARGET, 0.85, 0.4);
+ let hits = r["candidates"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .filter(|c| c["source_iri"].as_str().unwrap().ends_with("/Bakery"))
+ .count();
+ assert_eq!(hits, 1, "{r}");
+}
diff --git a/tests/align_ties_test.rs b/tests/align_ties_test.rs
new file mode 100644
index 00000000..38057451
--- /dev/null
+++ b/tests/align_ties_test.rs
@@ -0,0 +1,255 @@
+//! The 1-to-1 selection must never resolve a tie silently.
+//!
+//! Stable matching keeps the best target for each source and the best source
+//! for each target. When two targets score the same for one source, the
+//! winner is whichever IRI sorts first, which is a fact about spelling and not
+//! about the vocabularies, and the loser used to vanish from the report. A
+//! reviewer then saw one confident row and no hint that a second, equally good
+//! reading existed. Ties (confidences within one unit of the printed
+//! precision) are now named on the surviving row under `tied_with`, the row is
+//! flagged `ambiguous`, and an ambiguous row goes to review rather than being
+//! written into the graph, because the engine did not choose it.
+
+use open_ontologies::align::AlignmentEngine;
+use open_ontologies::graph::GraphStore;
+use open_ontologies::state::StateDb;
+use serde_json::Value;
+use std::sync::Arc;
+
+fn engine(graph: Arc<GraphStore>) -> AlignmentEngine {
+ let dir = tempfile::tempdir().unwrap();
+ let db = StateDb::open(&dir.path().join("state.db")).unwrap();
+ std::mem::forget(dir);
+ AlignmentEngine::new(db, graph)
+}
+
+fn parse(s: String) -> Value {
+ serde_json::from_str(&s).unwrap()
+}
+
+const ONE_SOURCE: &str = r#"
+ @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ @prefix s: <http://ties-src.example/> .
+ s:redistribution a skos:Concept ; skos:prefLabel "Redistribution"@en .
+ s:landfill a skos:Concept ; skos:prefLabel "Landfill"@en .
+"#;
+
+/// Two target concepts carry the same name: one under destinations, one under
+/// the material hierarchy. Both are perfect name matches for the source.
+const TWO_TARGETS: &str = r#"
+ @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ @prefix t: <http://ties-tgt.example/> .
+ t:WD-RED a skos:Concept ; skos:prefLabel "Redistribution"@en .
+ t:FH-RED a skos:Concept ; skos:prefLabel "Redistribution"@en .
+ t:WD-LF a skos:Concept ; skos:prefLabel "Landfill"@en .
+"#;
+
+#[test]
+fn a_tied_target_is_named_and_not_dropped() {
+ let r = parse(
+ engine(Arc::new(GraphStore::new()))
+ .align_with_thresholds(ONE_SOURCE, Some(TWO_TARGETS), 0.85, 0.4, true)
+ .unwrap(),
+ );
+ let red = r["candidates"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .find(|c| {
+ c["source_iri"]
+ .as_str()
+ .unwrap()
+ .ends_with("redistribution")
+ })
+ .unwrap_or_else(|| panic!("no row for the tied source: {r}"))
+ .clone();
+ let kept = red["target_iri"].as_str().unwrap();
+ let tied: Vec<String> = red["tied_with"]
+ .as_array()
+ .unwrap_or_else(|| panic!("the tie must be reported on the surviving row: {red}"))
+ .iter()
+ .map(|t| t["target_iri"].as_str().unwrap().to_string())
+ .collect();
+ let other = if kept.ends_with("WD-RED") {
+ "FH-RED"
+ } else {
+ "WD-RED"
+ };
+ assert!(
+ tied.iter().any(|t| t.ends_with(other)),
+ "the losing target must be named: {red}"
+ );
+ assert_eq!(red["ambiguous"], true, "{red}");
+ assert_eq!(
+ red["requires_review"], true,
+ "the engine did not choose this row, so a person must: {red}"
+ );
+ assert!(r["ambiguous_count"].as_u64().unwrap_or(0) >= 1, "{r}");
+
+ let lf = r["candidates"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .find(|c| c["source_iri"].as_str().unwrap().ends_with("landfill"))
+ .unwrap()
+ .clone();
+ assert_eq!(
+ lf["ambiguous"], false,
+ "a clear winner is not ambiguous: {lf}"
+ );
+ assert!(
+ lf["tied_with"].as_array().is_none_or(|a| a.is_empty()),
+ "{lf}"
+ );
+}
+
+#[test]
+fn an_ambiguous_row_is_not_written_into_the_graph() {
+ let graph = Arc::new(GraphStore::new());
+ let r = parse(
+ engine(graph.clone())
+ .align_with_thresholds(ONE_SOURCE, Some(TWO_TARGETS), 0.85, 0.4, false)
+ .unwrap(),
+ );
+ let red = r["candidates"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .find(|c| {
+ c["source_iri"]
+ .as_str()
+ .unwrap()
+ .ends_with("redistribution")
+ })
+ .unwrap()
+ .clone();
+ assert_eq!(red["applied"], false, "{red}");
+ // The unambiguous Landfill row is the only triple written.
+ assert_eq!(r["applied_count"], 1, "{r}");
+ assert_eq!(graph.triple_count(), 1);
+}
+
+#[test]
+fn a_tie_on_the_target_side_is_named_too() {
+ // Two sources with the same name compete for one target.
+ let two_sources = r#"
+ @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ @prefix s: <http://ties-src2.example/> .
+ s:a a skos:Concept ; skos:prefLabel "Landfill"@en .
+ s:b a skos:Concept ; skos:prefLabel "Landfill"@en .
+ "#;
+ let one_target = r#"
+ @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ @prefix t: <http://ties-tgt2.example/> .
+ t:LF a skos:Concept ; skos:prefLabel "Landfill"@en .
+ "#;
+ let r = parse(
+ engine(Arc::new(GraphStore::new()))
+ .align_with_thresholds(two_sources, Some(one_target), 0.85, 0.4, true)
+ .unwrap(),
+ );
+ let rows = r["candidates"].as_array().unwrap();
+ assert_eq!(rows.len(), 1, "one-to-one keeps one row: {r}");
+ let tied = rows[0]["tied_with"].to_string();
+ assert!(
+ tied.contains("ties-src2.example/"),
+ "the losing source must be named: {r}"
+ );
+ assert_eq!(rows[0]["ambiguous"], true);
+}
+
+/// A source FINER than its target: three source channels that each, correctly,
+/// map to one coarser target code.
+const FINE_SOURCE: &str = r#"
+ @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ @prefix s: <http://fine.example/> .
+ s:a a skos:Concept ; skos:prefLabel "Redistribution"@en .
+ s:b a skos:Concept ; skos:prefLabel "Redistribution (charity)"@en ; skos:hiddenLabel "Redistribution"@en .
+ s:c a skos:Concept ; skos:prefLabel "Landfill"@en .
+"#;
+
+const COARSE_TARGET: &str = r#"
+ @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ @prefix t: <http://coarse.example/> .
+ t:RED a skos:Concept ; skos:prefLabel "Redistribution"@en .
+ t:LF a skos:Concept ; skos:prefLabel "Landfill"@en .
+"#;
+
+#[test]
+fn many_to_one_keeps_every_source_that_maps_to_one_target() {
+ use open_ontologies::align::{AlignOptions, Cardinality};
+ let eng = engine(Arc::new(GraphStore::new()));
+ let opts = |cardinality| AlignOptions {
+ cardinality,
+ dry_run: true,
+ ..AlignOptions::default()
+ };
+ let rows = |v: &Value| -> Vec<(String, String)> {
+ v["candidates"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .map(|c| {
+ (
+ c["source_iri"].as_str().unwrap().to_string(),
+ c["target_iri"].as_str().unwrap().to_string(),
+ )
+ })
+ .collect()
+ };
+
+ let one = parse(
+ eng.align_with_options(
+ FINE_SOURCE,
+ Some(COARSE_TARGET),
+ &opts(Cardinality::OneToOne),
+ )
+ .unwrap(),
+ );
+ assert_eq!(
+ rows(&one)
+ .iter()
+ .filter(|(_, t)| t.ends_with("/RED"))
+ .count(),
+ 1,
+ "{one}"
+ );
+ // Under one-to-one the second source is not silently gone either: it tied.
+ assert_eq!(one["ambiguous_count"], 1, "{one}");
+
+ let many = parse(
+ eng.align_with_options(
+ FINE_SOURCE,
+ Some(COARSE_TARGET),
+ &opts(Cardinality::ManyToOne),
+ )
+ .unwrap(),
+ );
+ assert_eq!(many["cardinality"], "many_to_one");
+ let r = rows(&many);
+ assert!(
+ r.contains(&(
+ "http://fine.example/a".into(),
+ "http://coarse.example/RED".into()
+ )),
+ "{many}"
+ );
+ assert!(
+ r.contains(&(
+ "http://fine.example/b".into(),
+ "http://coarse.example/RED".into()
+ )),
+ "{many}"
+ );
+ assert!(
+ r.contains(&(
+ "http://fine.example/c".into(),
+ "http://coarse.example/LF".into()
+ )),
+ "{many}"
+ );
+ assert_eq!(
+ many["ambiguous_count"], 0,
+ "sharing a target is not a tie under many-to-one: {many}"
+ );
+}
diff --git a/tests/crosswalk_certify_test.rs b/tests/crosswalk_certify_test.rs
index 91f77fe4..0804446d 100644
--- a/tests/crosswalk_certify_test.rs
+++ b/tests/crosswalk_certify_test.rs
@@ -90,27 +90,205 @@ fn a_truthful_exact_match_is_upheld() {
let p = rows.iter().find(|r| r.mapping.subject.ends_with("/Person")).expect("row");
assert_eq!(p.supported, "exactMatch", "{}", p.because);
assert!(!p.downgraded, "a claim the evidence supports must not be reported as downgraded");
+ assert_eq!(p.certification, "upheld", "{}", p.because);
}
#[test]
-fn an_ancestor_the_target_cannot_express_forces_a_related_match() {
- // THE FOUNDRY CASE. The mapping carries no image for s:Person, so the
- // target cannot express something the source says about s:Employee. No
- // comparison of the two is defensible beyond relatedMatch.
+fn an_uncovered_ancestor_alone_does_not_refute_an_exact_match() {
+ // The mapping carries no row for s:Person, so nothing in the target can be
+ // compared with it. That is a COVERAGE gap, and it is already reported:
+ // s:Person is listed as unmapped. It is not evidence that s:Employee and
+ // t:Employee differ, because over everything both sides CAN be compared on
+ // (Agent) they agree. It used to force relatedMatch on every descendant,
+ // which turned one missing row into a downgrade of the whole subtree; a
+ // feasibility run on a food-waste taxonomy downgraded every row that way.
let partial = vec![
m("http://src.example/Employee", EXACT, "http://tgt.example/Employee"),
m("http://src.example/Agent", EXACT, "http://tgt.example/Agent"),
];
- let (rows, _) = certify(&store(SOURCE), &store(TARGET), &partial).expect("certifies");
+ let (rows, gaps) = certify(&store(SOURCE), &store(TARGET), &partial).expect("certifies");
let emp = rows.iter().find(|r| r.mapping.subject.ends_with("Employee")).expect("row");
- assert_eq!(emp.supported, "relatedMatch", "{}", emp.because);
+ assert_eq!(emp.supported, "exactMatch", "{}", emp.because);
+ assert!(!emp.downgraded, "{}", emp.because);
assert!(
emp.untranslatable.iter().any(|u| u.ends_with("/Person")),
- "the report must NAME the ancestor that has no image, or a reader cannot act on it: \
- {:?}",
+ "the ancestor with no image must still be NAMED, or a reader cannot act on it: {:?}",
emp.untranslatable
);
+ assert_eq!(emp.certification, "upheld_with_coverage_gap", "{}", emp.because);
assert!(emp.because.contains("no image"), "and say so in words: {}", emp.because);
+ assert!(
+ gaps.iter().any(|g| g.term.ends_with("/Person")),
+ "the gap is reported where it belongs, as an unmapped term"
+ );
+}
+
+#[test]
+fn a_real_disagreement_still_downgrades_when_an_ancestor_is_also_uncovered() {
+ // s:Employee now also sits under s:Payroll, which nothing maps. That gap
+ // must not mask the disagreement that IS visible: s:Employee is under
+ // Person, t:Employee is not, and Person is mapped on both sides.
+ let source = "@prefix s: <http://src.example/> .\n\
+ s:Employee a owl:Class ; rdfs:subClassOf s:Person , s:Payroll .\n\
+ s:Payroll a owl:Class .\n\
+ s:Person a owl:Class ; rdfs:subClassOf s:Agent .\n\
+ s:Agent a owl:Class .\n";
+ let (rows, _) = certify(&store(source), &store(TARGET), &full_mapping()).expect("certifies");
+ let emp = rows.iter().find(|r| r.mapping.subject.ends_with("Employee")).expect("row");
+ assert_eq!(emp.supported, "broadMatch", "{}", emp.because);
+ assert!(emp.downgraded);
+ assert_eq!(emp.certification, "downgraded");
+ assert!(emp.untranslatable.iter().any(|u| u.ends_with("/Payroll")), "{:?}", emp.untranslatable);
+}
+
+#[test]
+fn a_target_ancestor_with_no_source_counterpart_does_not_refute_either() {
+ // A FLAT source list mapped onto a two-level taxonomy. The target puts
+ // Bakery under a section the source has no term for. The old comparison
+ // read that as "the object is the more specific concept" and downgraded a
+ // correct exactMatch to narrowMatch. It is the same coverage gap seen from
+ // the other side, and is named under `object_uncovered`.
+ let flat = "@prefix s: <http://src.example/> .\n\
+ s:Bakery a owl:Class .\n";
+ let tax = "@prefix t: <http://tgt.example/> .\n\
+ t:BAK a owl:Class ; rdfs:subClassOf t:ProductCategory .\n\
+ t:ProductCategory a owl:Class .\n";
+ let one = vec![m("http://src.example/Bakery", EXACT, "http://tgt.example/BAK")];
+ let (rows, _) = certify(&store(flat), &store(tax), &one).expect("certifies");
+ let r = &rows[0];
+ assert_eq!(r.supported, "exactMatch", "{}", r.because);
+ assert!(!r.downgraded);
+ assert!(
+ r.object_uncovered.iter().any(|u| u.ends_with("ProductCategory")),
+ "{:?}",
+ r.object_uncovered
+ );
+ assert_eq!(
+ r.certification, "not_refuted_nothing_compared",
+ "nothing on either side could be compared, so the row is not refuted and is not \
+ confirmed either, and the word must say which: {}",
+ r.because
+ );
+}
+
+#[test]
+fn a_weaker_claim_is_never_upgraded_in_the_output() {
+ // Two siblings under one mapped parent have identical translated ancestor
+ // sets, so the hierarchy cannot tell them apart and "supports" exactMatch
+ // for ANY pairing of them, right or wrong. Writing that predicate into the
+ // file would turn a cautious closeMatch into an exactMatch on evidence that
+ // says nothing about the two terms themselves.
+ let src = "@prefix s: <http://src.example/> .\n\
+ s:Milk a owl:Class ; rdfs:subClassOf s:Food .\n\
+ s:Food a owl:Class .\n";
+ let tgt = "@prefix t: <http://tgt.example/> .\n\
+ t:Beverages a owl:Class ; rdfs:subClassOf t:Food .\n\
+ t:Dairy a owl:Class ; rdfs:subClassOf t:Food .\n\
+ t:Food a owl:Class .\n";
+ let close = "http://www.w3.org/2004/02/skos/core#closeMatch";
+ let maps = vec![
+ m("http://src.example/Milk", close, "http://tgt.example/Beverages"),
+ m("http://src.example/Food", EXACT, "http://tgt.example/Food"),
+ ];
+ let (rows, gaps) = certify(&store(src), &store(tgt), &maps).expect("certifies");
+ let milk = rows.iter().find(|r| r.mapping.subject.ends_with("Milk")).expect("row");
+ let tsv = to_sssom(&rows, &gaps);
+ let line = tsv.lines().find(|l| l.contains("src.example/Milk")).expect("row");
+ assert!(
+ line.contains("\tskos:closeMatch\t"),
+ "the predicate column may weaken a claim, never strengthen it: {line} ({})",
+ milk.because
+ );
+ let js = report(&rows, &gaps).to_string();
+ assert!(js.contains("siblings"), "the report must say the check cannot tell siblings apart: {js}");
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// SKOS input: the gate must be able to fail
+// ───────────────────────────────────────────────────────────────────────────
+
+/// A source list with three axes, its hierarchy stated the SKOS way.
+const SKOS_SOURCE: &str = "@prefix skos: <http://www.w3.org/2004/02/skos/core#> .\n\
+ @prefix s: <http://src.example/> .\n\
+ s:Destinations a skos:Concept .\n\
+ s:WasteTypes a skos:Concept .\n\
+ s:Products a skos:Concept .\n\
+ s:Landfill a skos:Concept ; skos:broader s:Destinations .\n\
+ s:PlateWaste a skos:Concept ; skos:broader s:WasteTypes .\n\
+ s:Bakery a skos:Concept ; skos:broaderTransitive s:Products .\n";
+
+/// The taxonomy it is mapped onto: the same three axes under other names.
+const SKOS_TARGET: &str = "@prefix skos: <http://www.w3.org/2004/02/skos/core#> .\n\
+ @prefix t: <http://tgt.example/> .\n\
+ t:Scheme a skos:ConceptScheme .\n\
+ t:WD a skos:Concept ; skos:topConceptOf t:Scheme .\n\
+ t:WT a skos:Concept ; skos:topConceptOf t:Scheme .\n\
+ t:PC a skos:Concept ; skos:topConceptOf t:Scheme .\n\
+ t:LF a skos:Concept ; skos:broader t:WD .\n\
+ t:PW a skos:Concept ; skos:broader t:WT .\n\
+ t:BAK a skos:Concept ; skos:broader t:PC .\n";
+
+fn axes() -> Vec<Mapping> {
+ vec![
+ m("http://src.example/Destinations", EXACT, "http://tgt.example/WD"),
+ m("http://src.example/WasteTypes", EXACT, "http://tgt.example/WT"),
+ m("http://src.example/Products", EXACT, "http://tgt.example/PC"),
+ ]
+}
+
+#[test]
+fn a_deliberately_wrong_skos_crosswalk_is_rejected() {
+ // Landfill is a destination and Plate waste a waste type; the rows cross
+ // axes. Read through rdfs:subClassOf alone, both sides of every row had
+ // no ancestors at all and this crosswalk certified clean, 0 downgrades:
+ // the check could not fail on SKOS input.
+ let mut maps = axes();
+ maps.push(m("http://src.example/Landfill", EXACT, "http://tgt.example/PW"));
+ maps.push(m("http://src.example/PlateWaste", EXACT, "http://tgt.example/BAK"));
+ let (rows, _) = certify(&store(SKOS_SOURCE), &store(SKOS_TARGET), &maps).expect("certifies");
+ for tail in ["/Landfill", "/PlateWaste"] {
+ let r = rows.iter().find(|r| r.mapping.subject.ends_with(tail)).expect("row");
+ assert!(r.downgraded, "{tail} crosses axes and must be refuted: {}", r.because);
+ assert_eq!(r.supported, "relatedMatch", "{}", r.because);
+ assert_eq!(r.certification, "downgraded");
+ }
+}
+
+#[test]
+fn a_correct_skos_crosswalk_is_upheld() {
+ let mut maps = axes();
+ maps.push(m("http://src.example/Landfill", EXACT, "http://tgt.example/LF"));
+ maps.push(m("http://src.example/PlateWaste", EXACT, "http://tgt.example/PW"));
+ maps.push(m("http://src.example/Bakery", EXACT, "http://tgt.example/BAK"));
+ let (rows, _) = certify(&store(SKOS_SOURCE), &store(SKOS_TARGET), &maps).expect("certifies");
+ for tail in ["/Landfill", "/PlateWaste", "/Bakery"] {
+ let r = rows.iter().find(|r| r.mapping.subject.ends_with(tail)).expect("row");
+ assert!(!r.downgraded, "{tail}: {}", r.because);
+ assert_eq!(r.certification, "upheld", "{tail}: {}", r.because);
+ }
+}
+
+#[test]
+fn a_row_with_nothing_to_compare_is_not_certified() {
+ // The same wrong rows WITHOUT the axis rows. Nothing either side says can
+ // be compared through the mapping, so the honest answer is that nothing
+ // was checked. The row must not read as upheld.
+ let maps = vec![
+ m("http://src.example/Landfill", EXACT, "http://tgt.example/PW"),
+ m("http://src.example/PlateWaste", EXACT, "http://tgt.example/BAK"),
+ ];
+ let (rows, gaps) = certify(&store(SKOS_SOURCE), &store(SKOS_TARGET), &maps).expect("certifies");
+ for r in &rows {
+ assert_eq!(r.certification, "not_refuted_nothing_compared", "{}", r.because);
+ assert!(r.because.contains("NOT certified"), "{}", r.because);
+ }
+ let tsv = to_sssom(&rows, &gaps);
+ assert!(!tsv.contains("\tupheld\t"), "nothing in the file may say upheld: {tsv}");
+
+ // And a term with no hierarchy at all, on both sides, is the same case.
+ let flat = vec![m("http://src.example/Destinations", EXACT, "http://tgt.example/WD")];
+ let (rows, _) = certify(&store(SKOS_SOURCE), &store(SKOS_TARGET), &flat).expect("certifies");
+ assert_eq!(rows[0].certification, "not_refuted_nothing_compared", "{}", rows[0].because);
}
#[test]
@@ -178,14 +356,19 @@ fn the_report_does_not_claim_a_word_it_has_not_earned() {
/// `s:Employee` is `t:Machine`, and the source entails `s:Employee ⊑ s:Person`
/// which maps to `t:Employee`. So the probe carries in `t:Machine ⊑
/// t:Employee`, and the target's own disjointness denies it.
+///
+/// There is no individual here. This fixture used to carry `t:m1 a
+/// t:Machine , t:Employee`, which made the target inconsistent ON ITS OWN, so
+/// the probe reported a clash whatever the mapping said: the test could not
+/// fail. A TBox alone is what a crosswalk usually connects, and the probe's
+/// witness individuals are what let it see a clash there.
const HOSTILE_TARGET: &str = "@prefix t: <http://tgt.example/> .\n\
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .\n\
@prefix owl: <http://www.w3.org/2002/07/owl#> .\n\
t:Employee a owl:Class ; rdfs:subClassOf t:Agent ; owl:disjointWith t:Machine .\n\
t:Machine a owl:Class .\n\
t:Person a owl:Class ; rdfs:subClassOf t:Agent .\n\
- t:Agent a owl:Class .\n\
- t:m1 a t:Machine , t:Employee .\n";
+ t:Agent a owl:Class .\n";
#[test]
fn a_target_that_denies_what_the_mapping_carries_is_reported_as_a_contradiction() {
@@ -202,6 +385,25 @@ fn a_target_that_denies_what_the_mapping_carries_is_reported_as_a_contradiction(
"and the probe must say WHAT it carried across, or the result is unactionable: {js}"
);
assert_eq!(js["verdict"], "the_target_denies_what_the_mapping_carried");
+ assert_eq!(
+ js["target_alone"]["clash_count"], 0,
+ "the clash must come from the mapping, not from a target that clashes anyway: {js}"
+ );
+ assert_eq!(js["exit_code"], 1, "{js}");
+}
+
+#[test]
+fn a_target_that_clashes_on_its_own_is_not_blamed_on_the_mapping() {
+ use open_ontologies::crosswalk::contradiction_probe;
+ let broken = format!("{HOSTILE_TARGET}@prefix t: <http://tgt.example/> .\nt:m1 a t:Machine , t:Employee .\n");
+ let js = contradiction_probe(&store(SOURCE), &broken, &full_mapping()).expect("probes");
+ assert_eq!(js["contradicted"], false, "an honest mapping into a broken target: {js}");
+ assert!(js["target_alone"]["clash_count"].as_u64().unwrap_or(0) > 0, "{js}");
+ assert_eq!(
+ js["verdict"],
+ "no_contradiction_added_by_the_mapping_but_the_target_clashes_on_its_own",
+ "{js}"
+ );
}
#[test]
diff --git a/tests/crosswalk_probe_cli_test.rs b/tests/crosswalk_probe_cli_test.rs
new file mode 100644
index 00000000..8c05f8c6
--- /dev/null
+++ b/tests/crosswalk_probe_cli_test.rs
@@ -0,0 +1,180 @@
+//! The contradiction probe, reached the way a user reaches it.
+//!
+//! `crosswalk::contradiction_probe` carries a crosswalk's claims into the
+//! target and reports a clash when the target's own axioms deny them. It had
+//! no caller outside its unit tests, so the README's sentence about clash
+//! reporting described something no command could do. It is now the
+//! `crosswalk-probe` subcommand and the batch verb of the same name, beside
+//! `crosswalk-certify`, and these tests drive both through the binary.
+
+mod common;
+
+use serde_json::Value;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+const SOURCE: &str = "@prefix s: <http://src.example/> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+s:Employee a owl:Class ; rdfs:subClassOf s:Person .
+s:Person a owl:Class ; rdfs:subClassOf s:Agent .
+s:Agent a owl:Class .
+";
+
+/// Employees and machines are disjoint here, and there is no individual at
+/// all: a taxonomy-shaped target, which is what a crosswalk usually connects.
+const TARGET: &str = "@prefix t: <http://tgt.example/> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+t:Employee a owl:Class ; rdfs:subClassOf t:Agent ; owl:disjointWith t:Machine .
+t:Machine a owl:Class .
+t:Person a owl:Class ; rdfs:subClassOf t:Agent .
+t:Agent a owl:Class .
+";
+
+/// One wrong row: s:Employee onto t:Machine. The source puts Employee under
+/// Person, Person maps onto t:Employee, so the mapping carries `t:Machine ⊑
+/// t:Employee` into a target that says the two are disjoint.
+const WRONG: &str = "subject_id\tpredicate_id\tobject_id
+http://src.example/Employee\tskos:exactMatch\thttp://tgt.example/Machine
+http://src.example/Person\tskos:exactMatch\thttp://tgt.example/Employee
+http://src.example/Agent\tskos:exactMatch\thttp://tgt.example/Agent
+";
+
+const RIGHT: &str = "subject_id\tpredicate_id\tobject_id
+http://src.example/Employee\tskos:exactMatch\thttp://tgt.example/Employee
+http://src.example/Person\tskos:exactMatch\thttp://tgt.example/Person
+http://src.example/Agent\tskos:exactMatch\thttp://tgt.example/Agent
+";
+
+fn write(dir: &Path, name: &str, body: &str) -> PathBuf {
+ let p = dir.join(name);
+ let _gate = common::exec_gate();
+ std::fs::write(&p, body).unwrap();
+ p
+}
+
+fn run(dir: &Path, args: &[&Path]) -> (Option<i32>, Value) {
+ let out = {
+ let _gate = common::exec_gate();
+ Command::new(env!("CARGO_BIN_EXE_open-ontologies"))
+ .arg("--data-dir")
+ .arg(dir.join("data"))
+ .args(args)
+ .output()
+ .unwrap()
+ };
+ let text = String::from_utf8_lossy(&out.stdout);
+ let line = text.lines().find(|l| l.starts_with('{')).unwrap_or("null");
+ (
+ out.status.code(),
+ serde_json::from_str(line).unwrap_or(Value::Null),
+ )
+}
+
+#[test]
+fn the_subcommand_reports_a_clash_the_mapping_carries_in() {
+ let d = tempfile::tempdir().unwrap();
+ let (s, t, m) = (
+ write(d.path(), "s.ttl", SOURCE),
+ write(d.path(), "t.ttl", TARGET),
+ write(d.path(), "wrong.tsv", WRONG),
+ );
+ let (code, v) = run(d.path(), &[Path::new("crosswalk-probe"), &s, &t, &m]);
+ assert_eq!(v["contradicted"], true, "{v}");
+ assert_eq!(
+ v["verdict"], "the_target_denies_what_the_mapping_carried",
+ "{v}"
+ );
+ assert_eq!(
+ v["target_alone"]["clash_count"], 0,
+ "the target alone is consistent: {v}"
+ );
+ assert!(
+ v["by_rule"]["cax-dw"].as_u64().unwrap_or(0) > 0,
+ "the disjointness is the clash: {v}"
+ );
+ assert!(
+ v["carried_claims"]
+ .to_string()
+ .contains("tgt.example/Machine"),
+ "and it says what it carried across: {v}"
+ );
+ assert_eq!(code, Some(1), "a contradiction must fail the command: {v}");
+}
+
+#[test]
+fn the_subcommand_reports_no_clash_for_an_honest_mapping() {
+ let d = tempfile::tempdir().unwrap();
+ let (s, t, m) = (
+ write(d.path(), "s.ttl", SOURCE),
+ write(d.path(), "t.ttl", TARGET),
+ write(d.path(), "right.tsv", RIGHT),
+ );
+ let (code, v) = run(d.path(), &[Path::new("crosswalk-probe"), &s, &t, &m]);
+ assert_eq!(v["contradicted"], false, "{v}");
+ assert_eq!(
+ v["verdict"], "no_contradiction_among_the_rules_this_engine_looks_for",
+ "{v}"
+ );
+ assert!(
+ v["carried"].as_u64().unwrap_or(0) > 0,
+ "something was carried and checked: {v}"
+ );
+ assert!(
+ v["means"]
+ .as_str()
+ .unwrap_or("")
+ .contains("NOT proof of compatibility"),
+ "a clean probe names its limit: {v}"
+ );
+ assert_eq!(code, Some(0), "{v}");
+}
+
+#[test]
+fn the_batch_verb_runs_the_same_probe() {
+ let d = tempfile::tempdir().unwrap();
+ let (s, t, m) = (
+ write(d.path(), "s.ttl", SOURCE),
+ write(d.path(), "t.ttl", TARGET),
+ write(d.path(), "wrong.tsv", WRONG),
+ );
+ let plan = serde_json::json!([{
+ "command": "crosswalk-probe",
+ "args": [s.to_str().unwrap(), t.to_str().unwrap(), m.to_str().unwrap()],
+ }]);
+ let p = write(d.path(), "plan.json", &plan.to_string());
+ let (code, v) = run(
+ d.path(),
+ &[Path::new("--no-connect"), Path::new("batch"), &p],
+ );
+ assert_eq!(v["command"], "crosswalk-probe", "{v}");
+ assert_eq!(v["result"]["contradicted"], true, "{v}");
+ assert_eq!(
+ code,
+ Some(1),
+ "the batch carries the probe's exit code: {v}"
+ );
+}
+
+#[test]
+fn a_missing_argument_is_an_error_not_a_clean_probe() {
+ let d = tempfile::tempdir().unwrap();
+ let p = write(
+ d.path(),
+ "plan.json",
+ r#"[{"command":"crosswalk-probe","args":["only-one.ttl"]}]"#,
+ );
+ let (code, v) = run(
+ d.path(),
+ &[Path::new("--no-connect"), Path::new("batch"), &p],
+ );
+ assert!(
+ v["result"]["error"]
+ .as_str()
+ .unwrap_or("")
+ .contains("SOURCE TARGET MAPPINGS"),
+ "{v}"
+ );
+ assert_eq!(code, Some(1));
+}
diff --git a/web/try/api/index.py b/web/try/api/index.py
index 6be3bc65..3fd027a8 100644
--- a/web/try/api/index.py
+++ b/web/try/api/index.py
@@ -21,6 +21,7 @@ import shutil
import stat
import subprocess
import tempfile
+import threading
import time
from http.server import BaseHTTPRequestHandler
from pathlib import Path
@@ -32,20 +33,98 @@ MAX_BYTES = 1_000_000
TIMEOUT_S = 40
+# Held while this process has a file open for WRITING in the engine directory,
+# and across every fork-and-exec of a binary from it. Linux refuses to exec a
+# file any process holds open for writing (ETXTBSY, `[Errno 26] Text file
+# busy`), and a child forked by one thread inherits the write descriptor
+# another thread is holding until the child itself execs. Writes are rare (one
+# per cold start) and a spawn holds the lock only until exec, not while the
+# engine runs, so nothing waits behind a 40-second request.
+_FORK_LOCK = threading.Lock()
+
+
+def _engine_dir() -> Path:
+ return Path(tempfile.gettempdir()) / "oo-engine"
+
+
+def _installed(dst: Path, size: int) -> bool:
+ try:
+ st = dst.stat()
+ except FileNotFoundError:
+ return False
+ return st.st_size == size and bool(st.st_mode & stat.S_IXUSR)
+
+
+def _install(src: Path, name: str) -> Path:
+ """Put an executable copy of `src` at a fixed path in the scratch directory.
+
+ The deployment bundle is read-only and may not keep the mode bit, so the
+ binary is copied once per warm instance. The copy used to be written in
+ place: `copyfile` straight onto the final path, then `chmod`. Concurrent
+ cold-start invocations raced on that path. One could find the file present
+ and the right size but not yet executable, another could truncate and
+ rewrite it while a third was executing it, and on Linux the write itself
+ failed with `[Errno 26] Text file busy` because the binary was running.
+
+ Now the copy is written under a unique name in the same directory, made
+ executable, and moved over the final path with `os.replace`, which is
+ atomic within one filesystem. The final path therefore only ever names a
+ complete executable file, it is never opened for writing, and a binary
+ already running keeps its own inode when a newer copy replaces it. A call
+ that finds a complete executable copy already there returns at once.
+ """
+ dst = _engine_dir() / name
+ size = src.stat().st_size
+ if _installed(dst, size):
+ return dst
+ dst.parent.mkdir(parents=True, exist_ok=True)
+ with _FORK_LOCK:
+ if _installed(dst, size):
+ return dst
+ fd, tmp = tempfile.mkstemp(prefix=f".{name}.", dir=str(dst.parent))
+ try:
+ with os.fdopen(fd, "wb") as out, open(src, "rb") as inp:
+ shutil.copyfileobj(inp, out)
+ out.flush()
+ os.fsync(out.fileno())
+ os.chmod(tmp, 0o755)
+ os.replace(tmp, dst)
+ except BaseException:
+ try:
+ os.unlink(tmp)
+ except FileNotFoundError:
+ pass
+ raise
+ return dst
+
+
+def _run(cmd: list[str], **kwargs) -> subprocess.CompletedProcess:
+ """`subprocess.run`, with the fork-to-exec window inside `_FORK_LOCK`.
+
+ `Popen` returns only once the child has exec'd (it waits on CPython's
+ error pipe), so holding the lock around it and not around the wait keeps
+ an install from overlapping any child's fork without serialising the runs.
+ """
+ timeout = kwargs.pop("timeout", None)
+ with _FORK_LOCK:
+ proc = subprocess.Popen(
+ cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, **kwargs
+ )
+ try:
+ out, err = proc.communicate(timeout=timeout)
+ except subprocess.TimeoutExpired:
+ proc.kill()
+ proc.communicate()
+ raise
+ return subprocess.CompletedProcess(cmd, proc.returncode, out, err)
+
+
def engine() -> Path:
- """The binary, executable, in a writable place. The deployment bundle is
- read-only and may not keep the mode bit, so it is copied once per warm
- instance into the scratch directory."""
+ """The binary, executable, in a writable place. See `_install`."""
override = os.environ.get("OO_BIN")
if override:
return Path(override)
- src = HERE / "_bin" / "open-ontologies"
- dst = Path(tempfile.gettempdir()) / "oo-engine" / "open-ontologies"
- if not dst.exists() or dst.stat().st_size != src.stat().st_size:
- dst.parent.mkdir(parents=True, exist_ok=True)
- shutil.copyfile(src, dst)
- dst.chmod(dst.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
- return dst
+ return _install(HERE / "_bin" / "open-ontologies", "open-ontologies")
def checker() -> Path | None:
@@ -56,12 +135,7 @@ def checker() -> Path | None:
src = Path(override) if override else (HERE / "_bin" / "oo-cert")
if not src.exists():
return None
- dst = Path(tempfile.gettempdir()) / "oo-engine" / "oo-cert"
- if not dst.exists() or dst.stat().st_size != src.stat().st_size:
- dst.parent.mkdir(parents=True, exist_ok=True)
- shutil.copyfile(src, dst)
- dst.chmod(dst.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
- return dst
+ return _install(src, "oo-cert")
def run_checker(cert_dir: Path) -> dict:
@@ -73,9 +147,9 @@ def run_checker(cert_dir: Path) -> dict:
c = checker()
if c is None:
return {"absent": True, "means": "this release carries no oo-cert, so nothing was checked here"}
- proc = subprocess.run(
+ proc = _run(
[str(c), str(cert_dir / "asserted.tsv"), str(cert_dir / "derivations.tsv")],
- capture_output=True, text=True, timeout=TIMEOUT_S,
+ timeout=TIMEOUT_S,
)
line = next((l for l in proc.stdout.splitlines() if l.startswith("{")), "")
try:
@@ -117,9 +191,9 @@ def run_batch(workdir: Path, script: str) -> list[dict]:
data_dir = workdir / "data"
data_dir.mkdir(exist_ok=True)
t0 = time.time()
- proc = subprocess.run(
+ proc = _run(
[str(engine()), "--data-dir", str(data_dir), "batch", str(workdir / "script.txt")],
- capture_output=True, text=True, timeout=TIMEOUT_S, cwd=str(workdir),
+ timeout=TIMEOUT_S, cwd=str(workdir),
)
out = []
for line in proc.stdout.splitlines():
diff --git a/web/try/test_engine_install.py b/web/try/test_engine_install.py
new file mode 100644
index 00000000..64dc3c3f
--- /dev/null
+++ b/web/try/test_engine_install.py
@@ -0,0 +1,118 @@
+"""Cold starts must not race on the engine binary.
+
+ python3 -m unittest web/try/test_engine_install.py
+
+The function copies the bundled binary into the scratch directory before it
+can run it. Concurrent cold-start invocations used to copy and chmod onto the
+same final path, and the page answered 500 with `[Errno 26] Text file busy`.
+These tests reproduce the race with many threads on one fake bundle. The first
+two run anywhere; the third needs Linux, because only Linux refuses to open a
+running executable for writing, and is skipped elsewhere with a reason.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+import unittest
+from pathlib import Path
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parent / "api"))
+import index # noqa: E402
+
+
+def spawn(cmd: list[str]) -> subprocess.CompletedProcess:
+ # The page spawns through `_run`, which keeps a fork out of an install's
+ # write window. Use it when it exists so the test exercises what ships.
+ run = getattr(index, "_run", None)
+ if run is not None:
+ return run(cmd, timeout=30)
+ return subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+
+
+class EngineInstall(unittest.TestCase):
+ def setUp(self):
+ self.tmp = Path(tempfile.mkdtemp(prefix="oo-try-test-"))
+ self.bundle = self.tmp / "bundle"
+ (self.bundle / "_bin").mkdir(parents=True)
+ self.scratch = self.tmp / "scratch"
+ self.scratch.mkdir()
+ os.environ.pop("OO_BIN", None)
+ self.patches = [
+ mock.patch.object(index, "HERE", self.bundle),
+ mock.patch("tempfile.gettempdir", return_value=str(self.scratch)),
+ ]
+ for p in self.patches:
+ p.start()
+
+ def tearDown(self):
+ for p in self.patches:
+ p.stop()
+ shutil.rmtree(self.tmp, ignore_errors=True)
+
+ def fake_engine(self, marker: str, pad_lines: int = 60000) -> None:
+ # A shell script whose only output is its LAST line, padded so a copy
+ # takes long enough to be caught half-written. A truncated copy runs
+ # and prints nothing; a copy without its mode bit cannot run at all.
+ body = "#!/bin/sh\n" + ("# padding padding padding padding\n" * pad_lines) + f"echo {marker}\n"
+ (self.bundle / "_bin" / "open-ontologies").write_text(body)
+
+ def test_concurrent_cold_starts_only_ever_run_a_complete_binary(self):
+ self.fake_engine("ENGINE_OK")
+ n = 24
+ barrier = threading.Barrier(n)
+ results: list[object] = [None] * n
+
+ def cold_start(i: int) -> None:
+ barrier.wait()
+ try:
+ proc = spawn([str(index.engine())])
+ results[i] = (proc.returncode, proc.stdout.strip(), proc.stderr.strip()[-200:])
+ except Exception as e: # noqa: BLE001
+ results[i] = e
+
+ threads = [threading.Thread(target=cold_start, args=(i,)) for i in range(n)]
+ for t in threads:
+ t.start()
+ for t in threads:
+ t.join()
+ bad = [r for r in results if r != (0, "ENGINE_OK", "")]
+ self.assertEqual(bad, [], f"{len(bad)} of {n} concurrent cold starts did not run the whole binary")
+
+ def test_a_present_binary_is_not_rewritten_and_no_partial_copies_are_left(self):
+ self.fake_engine("ENGINE_OK", pad_lines=10)
+ first = index.engine()
+ inode = first.stat().st_ino
+ again = index.engine()
+ self.assertEqual(first, again)
+ self.assertEqual(again.stat().st_ino, inode, "an installed binary must not be rewritten")
+ leftovers = [p.name for p in first.parent.iterdir() if p.name != first.name]
+ self.assertEqual(leftovers, [], "no temporary copy may be left behind")
+ self.assertEqual(spawn([str(again)]).stdout.strip(), "ENGINE_OK")
+
+ @unittest.skipUnless(sys.platform.startswith("linux"), "ETXTBSY is a Linux error; macOS lets a running binary be written")
+ def test_a_new_binary_can_replace_one_that_is_running(self):
+ # The production failure, exactly: a real executable is running from
+ # the installed path while another invocation installs a different
+ # one. Writing in place fails with Errno 26 on Linux.
+ sleep, true = shutil.which("sleep"), shutil.which("true")
+ self.assertTrue(sleep and true)
+ shutil.copyfile(sleep, self.bundle / "_bin" / "open-ontologies")
+ running = subprocess.Popen([str(index.engine()), "3"])
+ try:
+ shutil.copyfile(true, self.bundle / "_bin" / "open-ontologies")
+ if os.path.getsize(sleep) == os.path.getsize(true):
+ self.skipTest("sleep and true are the same size here, so no reinstall is triggered")
+ replaced = index.engine()
+ self.assertEqual(spawn([str(replaced)]).returncode, 0)
+ finally:
+ running.kill()
+ running.wait()
+
+
+if __name__ == "__main__":
+ unittest.main()