P0: Strict two-map/two-head open-vocabulary segmentation foundation

[InsightofSPb]

Summary

This PR introduces the P0 foundation for open-vocabulary heritage-facade segmentation.

Ontology v2 defines 12 stable semantic concepts, but they are not represented as 12 mutually exclusive model channels. The canonical supervised representation uses two separate target maps and two output heads so ornament geometry can overlap with damage.

Target representation

Main target

Y_main stores stable semantic IDs:

{0, 1, 2, 3, 4, 5, 6, 7, 9, 10, 11, 255}

The canonical main output has 11 mutually exclusive channels:

semantic ID:  0 1 2 3 4 5 6 7 9 10 11
main channel: 0 1 2 3 4 5 6 7 8  9 10

Semantic IDs are converted to contiguous channel indices only at the model/loss boundary. Predictions are converted back to semantic IDs when exported.

Ornament target

Semantic concept 8 is ornament_region: visible decorative geometry independent of its damage or surface condition.

Y_ornament is stored separately:

{0, 1, 255}

Therefore, the same pixel may represent both corrosion and ornament geometry:

Y_main[pixel] = 7
Y_ornament[pixel] = 1

The canonical supervised boundary expects:

main_logits:      [N, 11, H, W]
ornament_logits:  [N,  1, H, W]

The two outputs are never collapsed through cross-head argmax or last-mask-wins logic.

Legacy heritage_facades_v1_11classes remains an explicit separate single-mask schema. Flattened legacy masks cannot be losslessly converted into overlapping v2 targets without the original annotations.

What this PR adds

• strict ontology-v2 loading and deterministic ontology hashing;
• explicit semantic-ID-to-head/channel projection;
• fail-closed handling of unknown and ambiguous labels;
• stateless runtime vocabularies and prototypes with deterministic specification hashes;
• raw cosine-similarity scoring without an internal softmax;
• main cross-entropy and ornament BCE-with-logits loss helpers;
• differentiable zero loss for completely ignored targets;
• explicit legacy-v1 and two-map-v2 dataset validation;
• facade/source/path leakage detection;
• row-based valid and failed sample accounting;
• deterministic JSON-serializable reproducibility metadata;
• CPU-only unit, contract, and end-to-end tests;
• Python 3.9 GitHub Actions validation.

Validation and reproducibility

Validation reports include:

• ontology version and hash;
• complete semantic-ID-to-head/channel mapping;
• validator component and schema versions;
• source and split fingerprints;
• facade and source-ID overlaps;
• reused physical paths;
• warnings and errors;
• manifest-row, valid-sample, failed-sample, mask, and verified-image counts.

The metadata object is intended as an integration point for future shared experiment tracking. This PR does not introduce a competing ledger, registry, or provenance JSONL file.

Verification

GitHub Actions run:

https://github.com/InsightofSPb/Compress_to_prevent/actions/runs/32167722590

Results:

python -m compileall -q ovs_heritage  — passed
pytest -q ovs_heritage/tests         — 70 passed in 1.86s
ruff check ovs_heritage              — All checks passed

Final reviewed commit:

f659d8d245f369c96a13496fd4feb1b77c9ad907

Out of scope

This P0 PR does not include:

• complete two-head model integration or training;
• P1 open-vocabulary retention training;
• LPOSS, DINO, or ConCor integration;
• conversion of the real dataset;
• reconstruction of overlaps from flattened legacy masks;
• modifications to historical masks, checkpoints, or metrics;
• alignment, compression, temporal scoring, or H0/H1 changes;
• a complete experiment ledger or general component registry;
• GPU training or long experiments.

LPOSS integration and its positive regression tests remain future P1 work.