Skip to content

docs: OSM as 6th domain instance + RDF-OWL §10 Phase 2a/2b shipped + 2c queued #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AdaWorldAPI merged 1 commit into from
Jun 5, 2026
Merged

docs: OSM as 6th domain instance + RDF-OWL §10 Phase 2a/2b shipped + 2c queued #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 78 additions & 16 deletions docs/DOMAIN-INSTANCES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@
| **Elixir / HIRO** | migration target (OLD stack) | `docs/ELIXIR-HIRO-PREFETCH.md` + `crates/ogar-from-elixir` | scaffold; merged |
| **Odoo / ERP** | **production instance** | `docs/ODOO-TRANSCODING.md` + a production ERP deployment | shipping |
| **HIPAA / healthcare** | **production instance** | a production healthcare (HIPAA) deployment | shipping |
| **Geospatial / OSM** | calibration (geographic) | `docs/RDF-OWL-ALIGNMENT.md §10` Phase 2c + `lance-graph` PR #473 `cesium-osm-substrate-v1.md` (D-OSM-1..7) | spec'd; runtime addendum shipped; `ogar-from-osm-pbf` queued |

The first three are how the substrate is *calibrated* (chess proves the
Semantik/Syntax/Pragmatik trichotomy separates cleanly; OpenProject
Expand Down Expand Up @@ -122,31 +123,92 @@ A production HIPAA deployment proves the firewall split is a
*requirement*, not a nicety: a real HIPAA-compliant system needs fast
inner auth AND durable outer audit, and ships exactly that separation.

### 2.6 Geospatial / OSM — geographic calibration

**What OSM proves: geography doesn't break the IR.** OSM IDs are
*already* prefix-structured (`country/region/city/street/house`), so
the adapter is doing identity-*extraction*, not identity-construction
Comment on lines +128 to +130

@chatgpt-codex-connector chatgpt-codex-connector Bot Jun 5, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Correct the OSM ID hierarchy assumption

This treats OSM element IDs as geographic prefixes, but OSM nodes/ways/relations use numeric IDs in per-element-type ID spaces, not country/region/city/street/house paths (the OSM data model notes that different element types can share the same ID and be unrelated/geographically distant: https://wiki.openstreetmap.org/wiki/Data_model). In the ogar-from-osm-pbf plan, relying on identity-extraction from IDs would produce non-local or colliding NiblePath keys; the geographic prefix needs to be derived separately from coordinates/tiles or relations instead of the raw OSM ID.

Useful? React with 👍 / 👎.

— a much smaller surface than typical. Three OSM Classes (`Node`,
`Way`, `Relation`) lift via the queued `ogar-from-osm-pbf` adapter
(`docs/RDF-OWL-ALIGNMENT.md §10` Phase 2c). Exercises:

- **Spatial prefix-locality** — Cesium TMS quadkey as `NiblePath`
prefix, per Q2 coordination outcome locked in `lance-graph` PR #473
§2. HHTL trie routes `osm/<quadkey>/way/123` byte-identically to
`ogit-erp/sale.order/42` and `fma/Femur`. The *runtime session's*
Cesium tile pyramid math (`crates/cesium/src/sse.rs` +
`implicit_tiling.rs`) already uses quadkey addressing; aligning
OGAR routes both sides through the same address arithmetic.

- **Tag-as-Class final / Arrow-list v1 fallback** — Q1 coordination
outcome locked in `lance-graph` PR #473 §2. Final shape: Tag is a
`Class` related via `has_tag: HasMany<Tag>` (SPO-natural emission
`(Way#123, ogar:hasTag, Tag#building=yes)`); v1 implementation
ships the Arrow `List<Struct>` fallback in `D-OSM-1/2` for
cardinality control while Tag interning matures. The IR (`Class`
shape) carries no OSM-specific dialect — same ADR-023 discipline
Odoo's `_inherit`/`_inherits` already follows.

- **Palette256 codec (ADR-024) adopts its third domain.** OSM tag
values cluster within a tile (most zoom-21 tiles have ≤256
distinct tag values); per-tile palette + const-table lookup
yields ~5-10× compression on way attributes. The `D-OSM-2`
Arrow→Lance ingest reports ρ-vs-reference per the ADR-024
adoption checklist (lance-graph PR #473's §11 callout — the
runtime session's commitment after ADR-024 merged in PR #39).

- **The OGAR-crossing deliverable is `D-OSM-3`** — the SPO triple
lift in `lance-graph-ontology`. That's the producer-side contract
the `ogar-from-osm-pbf` adapter consumes. OGAR session signed off
on the surface in 2026-06-05 cross-session coordination; the
adapter is unblocked.

**The geographic litmus complements the anatomical one: the same
compile-time HHTL primitive resolves `Femur is_a LongBone` AND
`Marienplatz is_in Munich` in sub-microsecond.** That's the
falsifiable property — measurable, not aspirational. If it holds,
*"instance proves universality"* is non-trivial; if it fails on
either, the substrate is leaking dialect into the codec.

The OSM instance is calibration-grade like Chess and OpenProject (no
production deployment owned by the workspace yet), but the *runtime
side* — Cesium tilesets, Lance-backed OSM datasets, 3DGS splat
batches over OSM building footprints — is shipping per the
`cesium-osm-substrate-v1.md` deliverable line. The OGAR side
contributes the schema lift; the runtime side contributes the
rendering substrate; together they form the geographic counterpart
to the FMA-bones anatomical case (`docs/RDF-OWL-ALIGNMENT.md §6`).

## 3. Capability coverage matrix

Which domain proves which substrate capability (Foundry-parity columns
from `SUBSTRATE-ENDGAME.md §5.2`):

| Capability | Chess | OpenProject | Elixir/HIRO | Odoo/ERP | HIPAA |
|---|:--:|:--:|:--:|:--:|:--:|
| Ontology (Class/Association) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Action types / lifecycle FSM | ✓ | ✓ | ✓ (gen_statem) | ✓ (workflows) | ✓ |
| `Postpone` / `StateTimeout` | ✓ (premove/clock) | partial | ✓ | — | — |
| `Depends` (data-causal) | — | ✓ (reactive) | ✓ | ✓ (`@api.depends`) | — |
| Time-versioned / time-travel | ✓ | ✓ (paper-trail) | ✓ | ✓ | ✓ (audit) |
| **Row-level permissions** | — | partial (RBAC) | — | partial | **✓ (HIPAA, palette256)** |
| **Immutable audit** | — | ✓ (journals) | — | ✓ | **✓ (HIPAA, signed)** |
| Multi-language frontends | (Rust) | Ruby | Elixir | Python (Odoo)+SeaORM | Rust |
| Money/decimal fidelity | — | — | — | **✓ (ERP)** | — |
| Migration scaffold | — | ✓ (target) | ✓ (spine) | (already Rust) | (already Rust) |
| Capability | Chess | OpenProject | Elixir/HIRO | Odoo/ERP | HIPAA | OSM |
|---|:--:|:--:|:--:|:--:|:--:|:--:|
| Ontology (Class/Association) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Action types / lifecycle FSM | ✓ | ✓ | ✓ (gen_statem) | ✓ (workflows) | ✓ | — |
| `Postpone` / `StateTimeout` | ✓ (premove/clock) | partial | ✓ | — | — | — |
| `Depends` (data-causal) | — | ✓ (reactive) | ✓ | ✓ (`@api.depends`) | — | — |
| Time-versioned / time-travel | ✓ | ✓ (paper-trail) | ✓ | ✓ | ✓ (audit) | ✓ (changesets) |
| **Row-level permissions** | — | partial (RBAC) | — | partial | **✓ (HIPAA, palette256)** | — (ODbL-public) |
| **Immutable audit** | — | ✓ (journals) | — | ✓ | **✓ (HIPAA, signed)** | ✓ (OSM changeset history) |
| Multi-language frontends | (Rust) | Ruby | Elixir | Python (Odoo)+SeaORM | Rust | Rust (via `osmpbf`) |
| Money/decimal fidelity | — | — | — | **✓ (ERP)** | — | — |
| Migration scaffold | — | ✓ (target) | ✓ (spine) | (already Rust) | (already Rust) | (already Rust) |
| **Spatial prefix routing** (Cesium TMS quadkey via NiblePath) | — | — | — | — | — | **✓ (OSM)** |
| **Palette256 codec adoption** (ADR-024) | — | — | — | — | ✓ (security) | **✓ (tag values + tile-local coords)** |

**Coverage observation:** no single domain exercises everything, but the
five together cover the full surface. The HIPAA instance is the *only*
six together cover the full surface. The HIPAA instance is the *only*
one that hard-proves row-level perms + signed audit (the Security Mesh);
the Odoo/ERP instance is the *only* one that hard-proves money/decimal
fidelity + production `@api.depends`. The calibration trio
(chess/OP/HIRO) proves the lifecycle + migration core. **That's why all
five matter** — drop any and a capability loses its production witness.
fidelity + production `@api.depends`; the OSM instance is the *only*
one that hard-proves spatial prefix routing (Cesium TMS quadkey as
`NiblePath`) AND drives the second production adoption of the
palette256 codec from ADR-024. The calibration trio (chess/OP/HIRO)
proves the lifecycle + migration core. **That's why all six matter**
— drop any and a capability loses its production witness.

## 4. Why the two production instances change the Foundry argument

Expand Down
4 changes: 3 additions & 1 deletion docs/RDF-OWL-ALIGNMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -734,7 +734,9 @@ same TTL.
| Phase | Deliverable | Sized | Status |
|---|---|---|---|
| **1** | This doc (`docs/RDF-OWL-ALIGNMENT.md`) | 1 PR | **this PR** |
| **2** | `ogar-adapter-ttl` crate scaffold — parse / emit / round-trip against `vocab/ogar.ttl` | 1 sprint | Next OGAR PR after #25 P2 fix + surrealql AST walk |
| **2a** | `ogar-adapter-ttl` crate scaffold — parse / emit / round-trip against `vocab/ogar.ttl` | 1 sprint | **Shipped** (PR #37, merged 2026-06-05) |
| **2b** | `ogar-adapter-clickhouse-ddl` crate — CREATE TABLE → `Class` + emit; sqlparser ClickHouseDialect; composes with bardioc PR #19's `substrate-b-shadow::ClickHouseQuery` | 1 sprint | **Shipped** (PR #38 + #40 dotted-name fix, merged 2026-06-05) |
| **2c** | `ogar-from-osm-pbf` crate scaffold — consumes `osmpbf` (b-r-u) + `D-OSM-3`'s SPO triple lift contract from `lance-graph` PR #473 (`cesium-osm-substrate-v1.md`). Three fixed Classes (`Node`/`Way`/`Relation`); Cesium TMS quadkey as `NiblePath` prefix (Q2 outcome); Tag-as-Class final shape with Arrow `List<Struct>` v1 fallback (Q1 outcome). Reports ρ-vs-reference per ADR-024 adoption checklist on first per-country PBF run | 1 sprint | Queued — D-OSM-1/2/3 critical path upstream; landing after runtime-side D-OSM-3 SPO surface is observable |
| **3** | `ogar-knowable-from::vart-backend` feature — wires VART as the cache | 1 sprint | Concurrent with phase 2 |
| **4** | `ogar-pattern` crate — recognition library + confidence scoring + 10-15 patterns (FMA-D, FIBO-FND, schema.org, SKR, PROV-O-audit, etc.) | 2 sprints | After phase 2 |
| **5** | `ogar-actionable` crate — lifecycle extraction + `ActionDef` / `KausalSpec` proposal | 2 sprints | After phase 4 |
Expand Down
Loading