You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(plans/unified-bridge): §4 — point at concrete Hydrator types (post PR #407)
PR #407 + the ~11 preceding bO-* feature commits shipped the
concrete OWL/DOLCE/OGIT cross-walk hydrators in
lance_graph_ontology::hydrators::*. §4 of this plan referenced
those surfaces abstractly; this commit tightens to concrete
type pointers.
§4.1 (OWL/DOLCE cross-walk surface) — table now names the
hydrator that populates each MetaAnchors field:
- owl_upper_class + dolce_marker → hydrate_dolce
(OGIT::DOLCE_V1, inherits_from: None, 17-IRI edge whitelist
covering rdfs:subClassOf + owl:equivalentClass + DnS
classify/role-binding + dul:hasPart/isPartOf +
dul:hasTimeInterval/isObservableAt; note the canonical
DOLCE+DUL Endurant→Object/Perdurant→Event rename).
- foundry_object_type → hydrate_schemaorg + hydrate_fibo_be
for the upper-class anchors Foundry typically maps to.
- wikidata_qid → not yet in the hydrator surface; deferred
until a tenant requests Wikidata sync (~50 LOC glue).
§4.3 (NEW — Hydrator inventory) — full surface map:
- Generic substrate: OwlHydrator (the bO-* scaffold every
hydrator instantiates), MetaStructureHydrator trait,
ContextBundle, EntityId, OntologySlot, HydrateErr.
- Layered ontologies (L1 → L4 sector):
· L1: hydrate_dolce (root, inherits_from: None)
· L2: hydrate_owltime / hydrate_provo / hydrate_qudt
(all inherits_from: Some(OGIT::DOLCE_V1.0))
· L3: hydrate_schemaorg (commercial-web)
· Sector: hydrate_skos, hydrate_fibo_fnd,
hydrate_fibo_be (FIBO BE inherits FND)
- Dedicated (non-OWL): SchematronHydrator,
XsdHydrator + collect_xsd_files, SkrHydrator +
hydrate_skr03/skr04/skr03_bau + the three IRI prefix
constants.
- ZUGFeRD/Factur-X: hydrate_zugferd + hydrate_zugferd_rules
(XSD + Schematron over EN16931).
- Full re-export surface from the crate root shown as a
single `use` block for consumer ergonomics.
§4.3 also maps each plan deliverable to the hydrators it uses:
- D-UB-1 names the producer-side shape.
- D-UB-2 (SmbBridge) declares no hydrator dep until OGIT/NTO/SMB/
ships.
- D-UB-3 (lance_cache::ontology_cache_schema) persists each
hydrator's ContextBundle output as the Lance column rows.
- D-UB-4..6 (per-consumer constructors) take an already-hydrated
Arc<OntologyRegistry>; deployment chooses the menu:
· woa-rs: dolce + provo + qudt + schemaorg + fibo_fnd +
skr03/skr04 + future OGIT/NTO/WorkOrder.
· smb-office-rs: same minus WorkOrder, plus skr03_bau +
zugferd + zugferd_rules.
· MedCare-rs: dolce + owltime + provo + qudt + skos +
future OGIT/NTO/Healthcare.
No deliverable IDs renumbered; this is a clarification of §4's
referenced surface against the now-shipped types. Other plan
sections unchanged.
| Cross-walk | Field | Consulted when | Populated by (concrete hydrator) |
119
+
|---|---|---|---|
120
+
| Foundry ObjectType |`foundry_object_type: Option<&'static str>`| Customer requests Foundry-shape export | Not auto-populated; manual cross-walk per `super-domain-rbac-tenancy-v1.md` §10 OQ-1. `lance_graph_ontology::hydrators::hydrate_schemaorg` and `hydrate_fibo_be` provide the upper-class anchors Foundry typically maps to. |
121
+
| OWL upper class |`owl_upper_class: Option<&'static str>`| OWL reasoner runs over the same registry |`lance_graph_ontology::hydrators::hydrate_dolce` (L1 root, `OGIT::DOLCE_V1`, `inherits_from: None`). Resolves `rdfs:subClassOf` / `owl:equivalentClass` chains for the upper-category subsumption (Object / Event / Quality / Abstract). |
122
+
| DOLCE marker |`dolce_marker: DolceMarker` (Endurant / Perdurant / Quality / Abstract) | Per-row philosophical-category tagging |`lance_graph_ontology::hydrators::hydrate_dolce` populates the L1 bundle; downstream hydrators (`hydrate_owltime`, `hydrate_provo`, `hydrate_qudt`, `hydrate_schemaorg`, …) `inherits_from: Some(OGIT::DOLCE_V1.0)` and align via the `dul:isClassifiedBy` / `subClassOf dul:Event|Object|Quality|Abstract` chain DOLCE preserves. **Note:** canonical DOLCE+DUL renames `Endurant → Object` and `Perdurant → Event` per the DUL header — the `DolceMarker` enum either stays on the legacy naming (with downstream consumers aware of the renaming) or migrates at the cost of one source-tree-wide find/replace. Decide before D-UB-3. |
123
+
| Wikidata QID |`wikidata_qid: Option<u64>`| Wikidata sync / sameAs link generation | Not in the current hydrator surface — would need a `hydrate_wikidata` glue (~50 LOC) following the same `OwlHydrator { g, version, domain_name, inherits_from, starting_entity_id }` pattern. Probably deferred until a tenant explicitly requests Wikidata sync. |
124
124
125
125
These are **interop crutches**, not the hot path. The 4-stage `authorize()` never consults them; the per-family codebook is the runtime fast lane. OWL/DOLCE values ride in `FamilyEntry.axiom_blob` for slots that carry semantic obligations (functional / transitive / inverseFunctional / etc., per `GLUE_LAYER_OGIT_TO_OWL_SPEC.md` 1-byte bitfield).
126
126
@@ -148,6 +148,82 @@ Reads are append-only; writes go through `MappingProposal::sha256()`-keyed dedup
148
148
149
149
**This is what makes the codebook "O(1) cached in lancedb column":** the column store IS the cache; reads are scan-then-build-in-memory once at boot; lookups are array-index on `OwlIdentity.slot()` after.
150
150
151
+
### 4.3 Hydrator inventory (post-PR #407)
152
+
153
+
The OWL/DOLCE/OGIT cross-walk surface this plan referenced abstractly is now concrete in `lance_graph_ontology::hydrators::*` (PR #407 + the ~11 preceding feature commits). Every hydrator follows the same shape — a free function `hydrate_<name>(registry: &OntologyRegistry) -> Result<u32, HydrateErr>` that constructs an `OwlHydrator { g: OGIT::<SLOT>.0, version: OGIT::<SLOT>.1, domain_name: "<name>".to_string(), inherits_from: Option<u32>, starting_entity_id: 100 }`, calls `.hydrate(ttl_path, registry)` (or `.hydrate_many(&paths, registry)` for multi-file bundles like DOLCE+DUL+extensions), then registers an edge-IRI whitelist via `registry.register_edge_types(g, &EDGE_WHITELIST)`. The return value is the OGIT `G` slot u32 the bundle landed in.
154
+
155
+
**Generic substrate (the bO-* scaffold every hydrator instantiates):**
156
+
157
+
| Type | Path | Role |
158
+
|---|---|---|
159
+
|`OwlHydrator`|`lance_graph_ontology::hydrators::owl::OwlHydrator`| The generic struct with `g`, `version`, `domain_name`, `inherits_from`, `starting_entity_id`. Reads OWL/Turtle via the existing TTL parser, emits `MappingProposal`s into the registry. |
160
+
|`MetaStructureHydrator`|`lance_graph_ontology::hydrators::owl::MetaStructureHydrator` (trait) | Trait the per-ontology glue implements; `OwlHydrator` is the default impl. Pattern-D meta-structure hydration. |
161
+
|`ContextBundle`|`lance_graph_ontology::hydrators::owl::ContextBundle`| Typed bundle keyed by an OGIT `G` slot. One bundle per hydrator output. |
162
+
|`EntityId`, `OntologySlot`, `HydrateErr`|`lance_graph_ontology::hydrators::owl::*`| Per-entity slot index inside a bundle; the error enum. |
|`SchematronHydrator`|`lance_graph_ontology::hydrators::schematron::SchematronHydrator`| ISO Schematron rule sets | Hydrates Schematron rule patterns (asserts + reports) as ContextBundle entries; used by `hydrate_zugferd_rules` + `hydrate_zugferd_rules_from` for the EN16931 compliance rules ZUGFeRD/Factur-X invoices must satisfy. |
182
+
|`XsdHydrator`|`lance_graph_ontology::hydrators::xsd::XsdHydrator` (+ `collect_xsd_files()` helper) | XML Schema | Hydrates XSD type definitions as ContextBundle entries; used by `hydrate_zugferd` + `hydrate_zugferd_from` for the ZUGFeRD/Factur-X EN16931 invoice schema (PR-bO-16). |
183
+
|`SkrHydrator`|`lance_graph_ontology::hydrators::skr::SkrHydrator`| DATEV SKR charts of accounts | Hydrates the SKR account hierarchy from the CSV data files (`data/skr/SKR03.csv`, `SKR04.csv`, `SKR03_bau.csv`). Consumed by `hydrate_skr03` / `hydrate_skr04` / `hydrate_skr03_bau` (and their `_from` test variants). Three IRI-prefix constants exposed: `SKR03_IRI_PREFIX`, `SKR04_IRI_PREFIX`, `SKR03_BAU_IRI_PREFIX`. |
184
+
185
+
**Re-export surface (consumers import from the crate root, not the submodule):**
**How this plan's deliverables use the hydrator surface:**
215
+
216
+
-**D-UB-1** (consumer-pattern doc) names the `hydrate_<name>(registry)` shape as the producer side of `OntologyRegistry`. Consumers do not call hydrators directly — the bridge constructor (`<repo>_unified_bridge`) takes an already-hydrated `Arc<OntologyRegistry>` and the deployment code chooses which hydrators to run at boot.
217
+
-**D-UB-2** (`SmbBridge` skeleton) declares no hydrator dependency; SMB locks to a future `OGIT::SMB_V1` slot. Once `OGIT/NTO/SMB/` ships, an `hydrate_smb_namespace()` follows the same `OwlHydrator { inherits_from: Some(OGIT::DOLCE_V1.0), ... }` pattern.
218
+
-**D-UB-3** (`lance_cache::ontology_cache_schema()` + `LanceCacheBootStrategy`) persists the per-hydrator `ContextBundle` output as the Lance dataset rows. Each row carries `bridge_id`, `namespace`, `public_name`, `ogit_uri`, `kind`, `dolce_marker`, `owl_characteristics`, `provenance`, `axiom_blob`, `verb_slots`, `centroid_blob` (§4.2 table) — populated by the hydrators that ran at boot.
219
+
-**D-UB-4..6** (per-consumer constructors) all take `Arc<OntologyRegistry>` already hydrated by `hydrate_dolce` + the appropriate L2/L3/sector hydrators for that consumer's namespace. Concretely:
-**smb-office-rs** boots: same as woa-rs minus the WorkOrder namespace, plus `hydrate_skr03_bau` (Baugewerbe) for construction tenants and `hydrate_zugferd` + `hydrate_zugferd_rules` for X-Rechnung output validation.
The bridge constructor never sees `OwlHydrator` directly — it sees a hydrated `OntologyRegistry`. The deployment / `main.rs` of each consumer chooses the hydration menu.
0 commit comments