feat: add bounded ontology and provenance explorer (v2.13.0)

.env.example

@@ -46,4 +46,10 @@ LLM_GATEWAY_EMBEDDING_MODEL=
 LLM_API_GATEWAY=
 LLM_API_KEY=
 CALDAV_BASE_URL=
+RANKWEAVE_DISABLED=
+
+# Optional process HMAC for GET /api/ontology/neighborhood source continuation.
+# Empty keeps truncated-without-cursor. Do not reuse OIDC or orchestrator secrets.
+# Must be at least 32 bytes when source paging is enabled.
+ONTOLOGY_SOURCE_CURSOR_SECRET=
 CONTEXTUAL_ORCHESTRATOR_ALLOWED_PROVIDER_HOSTS=

AGENTS.md

@@ -10,7 +10,9 @@ scattered short records. See [ARCHITECTURE.md](ARCHITECTURE.md) for the
 design, [ADR 0084](docs/adr/0084-lineage-research-grounding.md) for the
 normative research-grounding policy, and
 [`docs/lineage-bi-research-notes.md`](docs/lineage-bi-research-notes.md) for
-supporting literature and aggregate evidence.
+supporting literature and aggregate evidence. Event Lineage (reconstructed
+post-to-post parents) is distinct from the typed ontology neighborhood
+(ADR 0168); source-window continuation is ADR 0124. Do not mix those graphs.
 
 ## Hard rule: no real data in repository artifacts
 

ARCHITECTURE.md

@@ -79,6 +79,8 @@ flowchart LR
 | `post_chat.py` | Pluggable in-popup chat's reason-and-cite step (retrieve step lives in `backend/app/post_chat_ingestion.py`) |
 | `commitment_extraction.py` | Pluggable LLM derivation of a customer commitment (promise + deadline) from a post; `Null` default, `ContextualOrchestrator` real impl |
 | `ontology.py` | Loads `docs/ontology/lineageweave-kg.ttl`, the formal OWL 2/RDFS/SKOS vocabulary for the Knowledge Graph's node/edge types (ADR 0004) |
+| `ontology_neighborhood.py` | Bounded typed ontology/provenance neighborhood (ADR 0168); PostgreSQL stays authoritative, OWL subclass is not an instance edge |
+| `ontology_source_cursor.py` | Opaque HMAC source-window continuation (ADR 0124); keyset pagination, never OFFSET |
 | `period_report.py` | Fit GRM/GPCM on persisted IRT rows, FIPC-select, EAP-score a period (ADR 0003 slice 3; Bock & Mislevy, 1982) |
 | `fixtures.py` | Synthetic demo dataset -- no real data ships in this repo |
 | `server.py` | Legacy stdlib HTTP server for the library-level synthetic fixture demo; production uses FastAPI/PostgreSQL |

CHANGELOG.d/2.13.0-ontology-explorer.md

@@ -0,0 +1,17 @@
+# 2.13.0 — Ontology provenance explorer
+
+- Added `GET /api/ontology/neighborhood` as a bounded typed instance graph
+  (ADR 0168 / issue #341), distinct from Event Lineage.
+- PostgreSQL stays authoritative; OWL/RDF/JSON-LD is a projection.
+- SKOS broader comes from `corporate_entity.parent_entity_id`; OWL subclass
+  is rejected as an instance edge.
+- Hidden endpoints remove the edge with no omitted-count side channel.
+- Catalog metadata is the only source for node truth and timestamps; missing
+  labels and unauthorized endpoints are omitted without leaking counts.
+- Neighborhood SQL now bounds traversal from the focus node, and CSV/JSON-LD
+  exports remain aligned with the active Buyer search filter.
+- Workspace surface: Keyman **Inspect ontology neighborhood**, exact-value table,
+  CSV/JSON-LD export, and Storybook states. No second GNB destination.
+- Session-token removal clears a previously loaded neighborhood. Static catalog
+  snapshots hide live refocus. Corporate parents require their own visible-post
+  evidence. OWL-Time is cited as a W3C Candidate Recommendation Draft.

CHANGELOG.d/2.13.0-provider-error-boundary.md

@@ -0,0 +1,4 @@
+## Fixed
+
+- Keep contextual-orchestrator, OIDC, RankWeave, TEPP, and durable-ingestion diagnostics behind stable product error boundaries while retaining the original exception for server-side chaining.
+- Keep browser 5xx and transport failures behind the same stable client error boundary.

CHANGELOG.d/2.14.0-ontology-source-cursor.md

@@ -0,0 +1,10 @@
+# 2.14.0 — Ontology source-window continuation
+
+- Added a versioned opaque `src.v2.` AES-GCM cursor so buyers can continue an
+  authorized ontology neighborhood beyond the bounded SQL source window
+  (ADR 0124/0125 / issue #363); the custom v1 keystream format is rejected.
+- Continuation uses keyset pagination of the recursive candidate window, not
+  `OFFSET`. Tamper, scope, version, expiry, and snapshot drift fail closed.
+- `ONTOLOGY_SOURCE_CURSOR_SECRET` is a process secret, never an OIDC or
+  orchestrator credential. Missing or short secrets withhold the cursor.
+- The explorer accumulates subsequent pages without losing selected evidence.

CHANGELOG.md

@@ -8,6 +8,13 @@ All notable changes to this project are documented here. Format follows
 
 ### Added
 
+- Ontology neighborhoods can continue beyond the bounded SQL source window
+  with a versioned opaque HMAC cursor and keyset pagination (ADR 0124 / #363).
+  A missing process secret keeps the truncated-without-cursor contract.
+- Bounded ontology/provenance neighborhood (`GET /api/ontology/neighborhood`)
+  with typed Post/Person/CorporateEntity/Team nodes, SKOS broader distinct
+  from OWL subclass, truth-status vocabulary, knowledge-cutoff binding, and
+  a Keyman-panel explorer that is not Event Lineage (ADR 0168 / #341).
 - Corroborated SKOS `altLabel` / `prefLabel` pairs now expand corporate
   catalog candidates so a synthetic short form (`AGP`) and full form
   (`Aurora Grid Power`) bind one `corporate_entity` row instead of
@@ -48,6 +55,17 @@ All notable changes to this project are documented here. Format follows
 - `make smoke` and `make seed` now run through the locked project `uv`
   environment, so local OIDC and synthetic-data workflows resolve the same
   pinned dependencies as CI.
+- Ontology neighborhoods now enforce request bounds before database access,
+  apply node-level ABAC, omit unlabeled endpoints, preserve catalog-owned node
+  metadata, and keep typed endpoint IDs unambiguous. Workspace CSV and JSON-LD
+  exports now represent the same filtered graph.
+- All OpenAI-compatible chat-completion consumers now validate the shared
+  response envelope before parsing it, preventing malformed provider bodies
+  from escaping as raw `KeyError` or response-shape details.
+- Ontology Explorer now clears a previously loaded neighborhood when the
+  session token is removed, hides live refocus on static catalog snapshots,
+  and looks up corporate-parent visibility independently of the child. OWL-Time
+  is cited as a W3C Candidate Recommendation Draft.
 
 ## [2.12.26] - 2026-08-24
 

backend/app/analysis_run_ingestion.py

@@ -148,6 +148,15 @@
     order by run.requested_at desc
 """
 
+_COUNTS_BY_RUN_SQL = """
+    select run.analysis_run_id, counts.count_type_code, counts.count_value
+    from analysis_run run
+    join analysis_source_count counts
+      on counts.analysis_source_snapshot_id = run.analysis_source_snapshot_id
+    where run.analysis_run_id = any($1::uuid[])
+    order by counts.count_type_code
+"""
+
 
 def scope_grouping_key(row: Any) -> str | None:
     """Persist the reconstruct grouping key for the run's authorized scope.
@@ -195,16 +204,9 @@ async def _counts_by_run(
     """Load aggregate snapshot counts for the given runs."""
     if not run_ids:
         return {}
-    # Safe SQL: this immutable aggregate query has closed schema text; run ids are bound below.
+    # Safe SQL: this immutable aggregate query has closed schema text; run ids remain bound below.
     rows = await conn.fetch(  # nosemgrep: python.lang.security.audit.sqli.asyncpg-sqli.asyncpg-sqli
-        f"""
-        select run.analysis_run_id, counts.count_type_code, counts.count_value
-        from analysis_run run
-        join analysis_source_count counts
-          on counts.analysis_source_snapshot_id = run.analysis_source_snapshot_id
-        where run.analysis_run_id = any($1::uuid[])
-        order by counts.count_type_code
-        """,
+        _COUNTS_BY_RUN_SQL,
         run_ids,
     )
     grouped: dict[str, list[asyncpg.Record]] = {}

backend/app/config.py

@@ -62,6 +62,7 @@ class Settings:
     tepp_api_key: str
     caldav_base_url: str
     rankweave_disabled: bool
+    ontology_source_cursor_secret: str
 
     @property
     def keycloak_jwks_uri(self) -> str:
@@ -175,4 +176,5 @@ def load_settings() -> Settings:
         .strip()
         .lower()
         in {"1", "true", "yes", "on"},
+        ontology_source_cursor_secret=os.environ.get("ONTOLOGY_SOURCE_CURSOR_SECRET", "").strip(),
     )

backend/app/global_ask_queue.py

@@ -280,7 +280,21 @@ async def process_global_ask_job(
         # the task silently and strand the row `running` until orphan
         # recovery (observed live) — every failure settles the job.
         _logger.exception("global ask job failed for job_id=%s", job_id)
-        detail = str(exc) or f"job exceeded the {JOB_DEADLINE_SECONDS}s deadline"
+        if isinstance(exc, (PermissionError, ConnectionError)):
+            # Raised locally with a pre-authored, safe message (permission
+            # state / missing config) — never a provider-boundary leak.
+            detail = str(exc)
+        elif isinstance(exc, asyncio.TimeoutError):
+            detail = f"job exceeded the {JOB_DEADLINE_SECONDS}s deadline"
+        else:
+            # Provider responses/exceptions can carry credentials, gateway
+            # diagnostics, or model output (ADR 0123): never persist the
+            # raw exception text as a durable `failure_detail`. The
+            # traceback just logged keeps it for operator debugging only.
+            detail = (
+                "Ask Agent is unavailable: contextual-orchestrator returned "
+                "no complete evidence object"
+            )
         async with pool.acquire() as conn:
             await conn.execute(
                 """