feat(calendar): publish clean Naruon event projection contract

CHANGELOG.d/naruon-calendar-projection-contract.md

@@ -0,0 +1,16 @@
+# Naruon calendar projection contract
+
+## Added
+
+- Add a strict, bounded v1 consumer contract for calendar occurrences already authorized and policy-filtered by Naruon, including occurrence identity, provider revision, timezone/all-day semantics, disclosure level, and observed provenance.
+- Export the projection parser, immutable result types, media type, schema version, and read client through the public LineageWeave package surface.
+- Add a reusable bounded JSON response read so oversized pages are rejected before allocation and parsing.
+
+## Changed
+
+- Clarify that LineageWeave owns post-grounded commitments and issue/todo records, while Naruon owns provider CalDAV synchronization, revisions, writeback, retry, and reconciliation.
+- Replace the misleading CalDAV label on the earlier custom JSON `/events` feed with an explicit pseudo-CalDAV correction.
+
+## Security
+
+- Reject unsafe base URLs, whitespace/control-bearing service tokens, unbounded response bodies, invalid numeric controls, oversized pages/windows, naive timestamps, duplicate occurrences, unknown fields/vocabularies, and URL-shaped opaque references.

CHANGELOG.md

@@ -72,6 +72,11 @@ 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.
+- Provider response parsing now rejects malformed chat envelopes without
+  exposing provider response bodies, exception text, or secrets through
+  buyer-facing APIs and persisted ingestion failure details. RankWeave, OIDC,
+  TEPP, structured VISION, summaries, chat, and extraction channels now retain
+  stable next-action-safe failure messages.
 - 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

backend/app/auth.py

@@ -56,7 +56,7 @@ def _jwks(settings: Settings, *, force_refresh: bool = False) -> dict:
         except (HttpClientError, OSError, ValueError) as exc:
             raise HTTPException(
                 status.HTTP_503_SERVICE_UNAVAILABLE,
-                f"could not fetch OIDC JWKS for {settings.oidc_issuer}: {exc}",
+                "could not fetch OIDC JWKS: identity provider unavailable",
             ) from exc
         _jwks_cache[cache_key] = cached
     return cached
@@ -134,7 +134,7 @@ def _decode_access_token(token: str, settings: Settings) -> dict:
     except HTTPException:
         raise
     except jwt.PyJWTError as exc:
-        raise HTTPException(status.HTTP_401_UNAUTHORIZED, f"invalid token: {exc}") from exc
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "invalid access token") from exc
     subject = claims.get("sub")
     if not isinstance(subject, str) or not subject.strip():
         raise HTTPException(status.HTTP_401_UNAUTHORIZED, "access token has no subject")

backend/app/main.py

@@ -2763,7 +2763,7 @@ async def chat_about_post(
     try:
         with use_llm_metadata(post_metadata):
             answer = await asyncio.to_thread(client.answer, question, sources)
-    except (HttpClientError, KeyError, OSError, ValueError) as exc:
+    except (HttpClientError, KeyError, OSError, TypeError, ValueError) as exc:
         raise HTTPException(
             status.HTTP_503_SERVICE_UNAVAILABLE,
             "Post chat is unavailable: contextual-orchestrator returned no complete evidence object",

backend/app/post_content_worker.py

@@ -37,6 +37,7 @@
 _RECOVERY_INTERVAL_SECONDS = 30.0
 _INCOMPLETE_FAILURE_CODE = "post_content_ingestion_incomplete"
 _ATTEMPT_LIMIT_FAILURE_CODE = "post_content_ingestion_attempt_limit"
+_SOURCE_BODY_MISSING_FAILURE_CODE = "post_content_source_body_missing"
 _UNEXPECTED_FAILURE_DETAIL = "post-content provider operation failed; retry the ingestion job"
 
 
@@ -229,10 +230,22 @@ async def process_post_content_job(
     if row is None:
         return
     attempt_count = int(row["job_attempt_count"]) + 1
+    raw_body = row["post_body"]
+    if not isinstance(raw_body, str) or not raw_body.strip():
+        _logger.warning(
+            "post content ingestion skipped: source post has no body",
+            extra={"post_id": post_id},
+        )
+        await _finish_job(
+            pool,
+            post_id,
+            FAILED,
+            failure_code=_SOURCE_BODY_MISSING_FAILURE_CODE,
+            detail_text="source post has no body",
+            expected_attempt_count=attempt_count,
+        )
+        return
     try:
-        raw_body = row["post_body"]
-        if not isinstance(raw_body, str) or not raw_body.strip():
-            raise ValueError("source post has no body")
         metadata = build_post_llm_metadata(post_id, row)
         embedding_client = embedding_factory()
         structure_client = structure_factory()

backend/tests/test_api.py

@@ -3547,6 +3547,29 @@ def answer(self, question: str, sources) -> ChatAnswer:
     assert "What happened here that no seed already answers?" in events[0]["summary"]
 
 
+def test_post_chat_malformed_provider_reply_is_unavailable(
+    client, demo_analyst_token, seeded_db, monkeypatch
+) -> None:
+    """A malformed provider envelope must not escape as an HTTP 500."""
+
+    class _MalformedChatClient:
+        available = True
+
+        def answer(self, question: str, sources) -> None:
+            del question, sources
+            raise TypeError("provider message content is not a string")
+
+    monkeypatch.setattr("backend.app.main._post_chat_client", lambda: _MalformedChatClient())
+    response = client.post(
+        f"/api/posts/{seeded_db['own_private_post_id']}/chat",
+        json={"question": "What happened here?"},
+        headers={"Authorization": f"Bearer {demo_analyst_token}"},
+    )
+
+    assert response.status_code == 503
+    assert "no complete evidence object" in response.json()["detail"]
+
+
 def test_live_chat_provider_error_does_not_leak_raw_error(
     client, demo_analyst_token, seeded_db, monkeypatch
 ) -> None:

backend/tests/test_auth_jwks.py

@@ -9,7 +9,8 @@
 import pytest
 from fastapi import HTTPException
 
-import backend.app.auth as auth
+from backend.app import auth
+from lineageweave.http_client import HttpClientError
 
 
 def _segment(value: dict) -> str:
@@ -173,3 +174,42 @@ def test_decode_rejects_missing_subject(monkeypatch: pytest.MonkeyPatch) -> None
     with pytest.raises(HTTPException) as error:
         auth._decode_access_token("token", settings)
     assert error.value.status_code == 401
+
+
+def test_decode_hides_raw_jwt_provider_error(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(auth, "_signing_key", lambda settings, token: "signing-key")
+
+    def fail_decode(*args: object, **kwargs: object) -> dict:
+        raise auth.jwt.InvalidTokenError("provider secret")
+
+    monkeypatch.setattr(auth.jwt, "decode", fail_decode)
+    settings = SimpleNamespace(
+        oidc_issuer="https://id.example",
+        oidc_audience="lineageweave-api",
+        oidc_clock_skew_seconds=5,
+    )
+
+    with pytest.raises(HTTPException) as error:
+        auth._decode_access_token("token", settings)
+    assert error.value.detail == "invalid access token"
+    assert "provider secret" not in str(error.value.detail)
+
+
+def test_jwks_hides_raw_identity_provider_error(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(
+        auth,
+        "get_json",
+        lambda *_args, **_kwargs: (_ for _ in ()).throw(
+            HttpClientError("identity provider secret")
+        ),
+    )
+    settings = SimpleNamespace(
+        oidc_issuer="https://id.example",
+        oidc_discovery_uri="https://id.example/.well-known/openid-configuration",
+        oidc_jwks_uri_override="",
+    )
+
+    with pytest.raises(HTTPException) as error:
+        auth._jwks(settings)
+    assert error.value.detail == "could not fetch OIDC JWKS: identity provider unavailable"
+    assert "identity provider secret" not in str(error.value.detail)

docs/adr/0030-external-llm-gateway-environment.md

@@ -52,12 +52,19 @@ runtime, with masking enabled; the repository contains no provider secret.
 The contextual-orchestrator service remains the only LLM boundary. LineageWeave
 does not call the provider gateway directly and does not create a fallback
 local score, summary, extraction, or answer when the gateway is unavailable.
+Provider response envelopes and exceptions are also a trust boundary: clients
+extract only the expected content and expose stable, next-action-safe error
+messages. Raw provider response bodies, exception text, prompts, and secrets
+must never be returned through a buyer-facing API or persisted failure detail.
 
 ## Consequences
 
 - Provider changes are deployment configuration, not source changes.
 - A missing or invalid gateway credential fails at the orchestrator boundary;
   it must not be replaced by a fabricated channel result.
+- A provider failure is logged with internal correlation context where
+  operational logging permits, but the buyer receives a stable unavailable
+  message that tells them to retry or restore the provider configuration.
 - `CONTEXTUAL_ORCHESTRATOR_ALLOWED_PROVIDER_HOSTS` must explicitly allow the
   hostname selected by `LLM_GATEWAY_API_URL`; wildcard allowlists are forbidden.
 - Local Compose development permits only the explicitly enumerated

docs/adr/0038-calendar-source-contract.md

@@ -1,37 +1,53 @@
-# ADR 0038: Separate CalDAV events from internal commitments
+# ADR 0038: Separate external calendar events from internal commitments
 
-- Status: Accepted
+- Status: Superseded in part by ADR 0203
 - Date: 2026-08-18
 
 ## Context
 
-The buyer Calendar destination needs both external calendar events and
+The buyer Calendar destination needs both external calendar observations and
 actionable records derived from LineageWeave posts. They have different
-ownership and evidence boundaries. PR #251 defines CalDAV as an independent
-consumer port, while the current application already stores authorized
-commitments and issue tickets.
+ownership and evidence boundaries. The application already stores authorized
+commitments and issue tickets, while the first external adapter read a custom
+JSON `GET {CALDAV_BASE_URL}/events` feed.
 
-## Decision
+That feed was not a CalDAV client or server contract. It did not implement RFC
+4791 WebDAV discovery/REPORT, RFC 5545 recurrence and timezone semantics, RFC
+6578 synchronization, provider revisions, or provider authorization. Product
+and code language must not represent it as shipped CalDAV interoperability.
 
-`GET /api/calendar` returns two independent collections:
+## Original decision retained
 
-- `events`: events read from `CALDAV_BASE_URL/events` through
-  `lineageweave.caldav_client`; malformed external rows are ignored.
+The Buyer Calendar returns two independent collections:
+
+- `events`: externally observed calendar occurrences; and
 - `commitments`: the existing authorized internal commitment projection,
   filtered by the requesting account's `post_read` RBAC and post ABAC rules.
 
-When CalDAV is unset or temporarily unavailable, `events` is empty and the
-response includes a next action in `calendar_sources`; the internal
-commitments remain available. The backend never invents an external event.
+When the external calendar channel is unset or temporarily unavailable,
+`events` is empty and the internal commitments remain available. The backend
+never invents an external event.
+
+LineageWeave does not add a second calendar database, CalDAV server, provider
+credential store, or writeback engine.
+
+## Superseding decision
+
+ADR 0203 replaces the custom `/events` transport and CalDAV naming with a
+versioned, read-only Naruon calendar projection contract. Naruon is the authority
+for customer-owned provider access, source registry, synchronization, provider
+revisions, writeback, retries, and reconciliation. LineageWeave consumes only
+bounded, already-authorized `observed` occurrence projections.
 
-This checkpoint does not add a second calendar database. A persistent event
-store and sync history may be added when offline access, change tracking, or
-CalDAV write-back becomes a product requirement.
+The original separation between `events` and `commitments` remains mandatory.
+An external event is not converted to an internal issue or commitment without a
+separate source-grounded LineageWeave decision and evidence trail.
 
 ## Consequences
 
-- The Calendar screen is useful with the existing synthetic commitment data,
-  even without an external calendar server.
-- External events cannot be mistaken for post-grounded commitments.
-- CalDAV transport failures do not turn the entire buyer surface into a
-  fail-closed blank screen.
+- The Calendar remains useful with authorized commitment data when Naruon is
+  unavailable.
+- External observations cannot be mistaken for post-grounded commitments.
+- Product documentation no longer represents a custom JSON feed as CalDAV.
+- Runtime activation waits for Naruon's matching read endpoint and service
+  audience; absence continues to fail closed rather than fabricate events.