[Ontology] Add a heterogeneous ontology and provenance explorer separate from Event Lineage

[seonghobae]

Buyer problem

The current Buyer DAG is intentionally a reconstructed record/Event Lineage view. Its nodes are source posts/records and its edges are inferred parent-to-child lineage links. The formal LineageWeave ontology, however, also defines heterogeneous concepts and properties such as Post, Person, CorporateEntity, our-side/counterparty person classes, mentions, affiliatedWith, coMentionedWith, entity-role relations, and SKOS broader/narrower hierarchy.

A buyer cannot currently inspect those ontology relationships as a real graph. Calling the Event Lineage DAG an ontology graph therefore overstates what the surface renders and leaves the following questions unanswered:

• Which people, organizations, teams, projects, and posts are connected?
• What typed property connects them?
• Is the relation authoritative, observed, inferred, proposed, superseded, or rejected?
• During which valid interval did the relation apply?
• Which authorized source evidence and provenance activity support it?
• Which nodes or edges were omitted by authorization or evidence limits?

PR #330 improves the existing Event Lineage renderer with direction, dates, accessible controls, scrolling, exact fused-score evidence, Storybook states, and an explicit truth boundary. This issue is a separate product capability; it must not turn #330 into a mixed lineage/ontology graph.

Product boundary

Event Lineage remains

• Post/record nodes only.
• Reconstructed parent-to-child lineage.
• Lineage depth, source dates, fused score, and later channel evidence.
• Explicitly inferred and non-causal unless separate evidence establishes otherwise.

Ontology Explorer adds

• Heterogeneous nodes: post, person, corporate entity, team, and project when those types exist in the governed catalog.
• Typed ontology/KG edges with canonical property IRI and localized label.
• Truth status, provenance, valid/system time, and source evidence.
• Bounded neighborhood traversal and evidence-first inspection.

The relational application database remains authoritative. OWL/RDF/JSON-LD is a governed projection and interoperability contract, not a second mutable source of truth.

Required data and API contract

Provide a bounded endpoint such as:

GET /api/ontology/neighborhood

with explicit query parameters for:

focus_node_type
focus_node_id
maximum_depth
maximum_nodes
maximum_edges
allowed_property_codes
knowledge_cutoff
cursor

Return typed objects rather than an arbitrary graph bag:

ontology_graph_node
- node_id
- node_type_code
- ontology_class_iri
- display_label
- truth_status_code
- valid_from
- valid_to
- recorded_at
- evidence_count

ontology_graph_edge
- edge_id
- source_node_id
- target_node_id
- property_code
- ontology_property_iri
- property_label
- truth_status_code
- valid_from
- valid_to
- recorded_at
- provenance_reference
- evidence_references

Requirements:

• Run RBAC/ABAC and source-eligibility checks before a node, edge, count, label, or path enters the response.
• Remove an edge if either endpoint is not visible.
• Do not reveal hidden-neighborhood counts through totals, truncation text, or cursor behavior.
• Reject unknown node/property types, dangling endpoints, cross-tenant references, non-finite numeric metadata, excessive traversal depth, and unbounded requests.
• Do not expose arbitrary Cypher, SPARQL UPDATE, SQL, or caller-supplied query fragments.
• Preserve deterministic ordering and stable opaque identifiers.
• Distinguish authoritative, observed, inferred, proposed, superseded, and rejected; never promote inference because it is displayed.
• Bind historical views to available_time <= knowledge_cutoff; current-only facts without a time contract stay out of an as-of response.

Buyer surface

Extend the existing Buyer relationship/evidence surface rather than creating a second application or misleading GNB destination.

Required behavior:

• Node type has redundant visual encoding: shape/icon plus text, never color alone.
• Edge label shows the governed property label; the canonical IRI is available in evidence details.
• Truth status and temporal validity are visible without hover-only interaction.
• Selecting a node opens its authorized evidence and offers the next valid traversal action.
• Selecting an edge opens property, provenance, validity, source evidence, and limitation details.
• A legend explains node types, edge truth status, and the distinction from Event Lineage.
• Bounded expand/collapse, search within the loaded graph, focus reset, and deterministic layout.
• Exact-value table exposes the same visible nodes/edges for keyboard, screen reader, touch, print, CSV/JSON-LD export, and audit.
• Narrow viewports use a readable alternative layout rather than shrinking the whole graph.
• Empty, partial, truncated, hidden-evidence, stale-evidence, rejected-proposal, and access-denied states name the buyer's next action.

Figma and Storybook

Use the safe LineageWeave buyer design-system file recorded in ADR 0002:

Figma File ID: 1Su3lDRmiZdcUs47t1QwIX

Create sanitized, synthetic frames before implementation for:

• desktop ontology neighborhood;
• mobile/narrow exact-value-first view;
• node evidence drawer;
• edge/provenance drawer;
• legend and filtering;
• empty, truncated, partial, denied, and stale states.

Record frame IDs in a collision-free ADR. Build reusable design-token-backed Storybook components and interaction states; no confidential source frame or production identity may enter the repository.

RED → GREEN acceptance

1. A synthetic Post -> mentions -> Person -> affiliatedWith -> CorporateEntity path round-trips through PostgreSQL and the typed API with exact IRIs and provenance.
2. A SKOS broader/narrower corporate hierarchy remains distinct from OWL class subsumption.
3. An inferred edge is never serialized or announced as authoritative.
4. A hidden endpoint removes the edge and all count/path side channels.
5. A cutoff query excludes evidence that became available later.
6. Unsupported or dangling ontology terms fail closed rather than rendering an “unknown” authoritative relation.
7. Keyboard users can select every visible node and edge and reach the same evidence available to pointer users.
8. Screen readers receive interactive descendants; no enclosing ARIA img hides graph controls.
9. Exact-value table, print, CSV, and JSON-LD contain the same authorized visible graph.
10. Layout remains deterministic for a fixed payload and does not overlap labels in the supported bounded fixture sizes.
11. Storybook includes every required state and production build succeeds.
12. PostgreSQL integration, frontend tests, accessibility tests, i18n consistency, security, SAST, production statement/branch coverage, and public docstrings satisfy repository gates.

Standards and doctoring

Use and cite in APA 7th format:

• RDF 1.1 Concepts and Abstract Syntax.
• RDF Schema 1.1.
• OWL 2 Web Ontology Language.
• SKOS Simple Knowledge Organization System.
• PROV-O.
• OWL-Time.
• JSON-LD 1.1.
• SHACL for projection validation where applicable.
• WCAG 2.2 for graph interaction and exact-value alternatives.

Update docs/doctoring/REFERENCES.md, docs/doctoring/STANDARD_TRACEABILITY.md, the product/technical gap baseline, architecture diagrams, Storybook inventory, and CHANGELOG in the implementation PR.

Dependency and merge gate

• Do not mix this capability into PR feat: make Event Lineage directional and evidence-readable #330; feat: make Event Lineage directional and evidence-readable #330 remains the bounded Event Lineage readability/accessibility slice.
• Implement only after the Buyer ontology/evidence boundary from feat: deliver workspace evidence board and source-grounded ontology surface #258 is integrated or restacked on its exact accepted successor.
• Reuse released accessible graph primitives from feat: make Event Lineage directional and evidence-readable #330 when available, but do not couple to its mutable feature branch.
• Coordinate with [Event Lineage] Persist and explain channel evidence #274/feat: expose exact Event Lineage channel evidence #287 for channel evidence without treating reconstruction channels as ontology properties.
• Exact-current-head CI/security/coverage, resolved review threads, independent approval, and protected merge remain mandatory. No force push, self-approval, or inference-to-authority promotion.

[seonghobae]

Cycle 2026-08-21T12:15 KST: GitHub writes work as seonghobae (token still reports empty X-OAuth-Scopes on REST; MCP/gh/git push succeed). main@ef6f5a5 after #347. Implementing this issue on feat/ontology-provenance-explorer-v2130 from current main — typed neighborhood assembler + ingestion already exist locally. Will open a PR onto main (not mixed into #330 / #258 / #74 stacks). Independent exact-head APPROVE required; no self-approve.

[seonghobae]

Implementation opened as #349 onto main.

Exact head: 30f604fb0e82735bd2f077dd3c164341f9857104 (feat/ontology-provenance-explorer-v2130). Independent exact-head APPROVE required; no self-approve.

[seonghobae]

Protected delivery is now present on main through PR #349 (merge commit 9b0b71a). The merged stack includes the typed heterogeneous ontology/provenance explorer, authorization-bounded API, exact-value and JSON-LD parity, deterministic layout, accessible interaction, Storybook states, standards traceability, and its #369 continuation child. Closing this delivery issue; authenticated production acceptance remains tracked in docs/product-technical-gap-baseline.md rather than being inferred from source alone.