feat: validate project history through TEPP temporal contract (v2.20.0)

ARCHITECTURE.md

@@ -281,8 +281,8 @@ HTML. `src/api.ts` calls the FastAPI backend directly with the token
 Keycloak issued; `src/App.tsx` renders a git-branch SVG of
 `GET /api/lineage` (click a node to open that post; `post_admin` can
 rebuild), the post list with a named Weekly VOC ISO-8601 week filter
-(ADR 0092; opening that filtered post focuses Event Lineage, ADR 0093).
-Calendar commitments use the same Event Lineage focus path (ADR 0094).
+(ADR 0092; opening that filtered post focuses Event Lineage, ADR 0093),
+Calendar commitments use the same Event Lineage focus path (ADR 0094),
 Customer master related posts use the same Event Lineage focus path
 (ADR 0095). Ask Agent cited posts use the same Event Lineage focus path
 (ADR 0096). A linked Event Lineage node opened from a focused popup keeps

backend/app/main.py

@@ -198,6 +198,7 @@
     require_summary_source_body,
 )
 from backend.app.post_eligibility import SOURCE_POST_ELIGIBILITY_SQL
+from backend.app.project_history_api import router as project_history_router
 from backend.app.demo_scope import (
     fetch_demo_corporate_entity_ids,
     has_real_source_context,
@@ -257,6 +258,7 @@ async def lifespan(app: FastAPI):
     allow_methods=["GET", "POST", "PATCH"],
     allow_headers=["Authorization"],
 )
+app.include_router(project_history_router)
 
 
 def _require_post_read(account: CurrentAccount) -> None:

backend/app/project_history.py

@@ -0,0 +1,220 @@
+"""ABAC-safe PostgreSQL projection for Buyer project histories."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from datetime import datetime
+from typing import Any, Protocol
+
+from backend.app.post_eligibility import SOURCE_POST_ELIGIBILITY_SQL
+from lineageweave.project_history import build_project_history_projection, normalize_project_key
+
+PROJECT_HISTORY_DEFAULT_LIMIT = 64
+PROJECT_HISTORY_MAXIMUM_LIMIT = 128
+
+
+class ProjectHistoryConnection(Protocol):
+    """Minimal asynchronous query port required by this repository."""
+
+    async def fetch(self, query: str, *args: object) -> Sequence[Mapping[str, Any]]:
+        """Execute a bounded read query and return mapping-like rows."""
+
+        ...
+
+
+_ELIGIBILITY = SOURCE_POST_ELIGIBILITY_SQL.format(alias="post")
+_PROJECT_MATCH = """
+(
+    lower(normalize(btrim(coalesce(post.source_project_code, '')), NFKC)) = $1
+    or lower(normalize(btrim(coalesce(post.source_project_name, '')), NFKC)) = $1
+    or exists (
+        select 1
+          from post_project_mention mention
+         where mention.post_id = post.post_id
+           and (
+                lower(normalize(btrim(mention.project_key), NFKC)) = $1
+                or lower(normalize(btrim(mention.project_name), NFKC)) = $1
+           )
+    )
+)
+"""
+_EVENT_SQL = f"""
+select post.post_id,
+       post.post_title,
+       post.created_at,
+       post.voc_type_code,
+       post.source_stage_code,
+       post.source_detail_state_code
+  from source_post post
+ where (post.visibility_code = 'public'
+    or post.corporate_entity_id::text = any($2::text[]))
+   and {_ELIGIBILITY}
+   and post.created_at <= $3
+   and {_PROJECT_MATCH}
+ order by post.created_at, post.post_id
+ limit $4
+"""
+_FOCUS_SQL = f"""
+select post.post_id,
+       post.post_title,
+       post.created_at,
+       post.voc_type_code,
+       post.source_stage_code,
+       post.source_detail_state_code
+  from source_post post
+ where (post.visibility_code = 'public'
+    or post.corporate_entity_id::text = any($2::text[]))
+   and {_ELIGIBILITY}
+   and post.created_at <= $3
+   and post.post_id = $4::uuid
+   and {_PROJECT_MATCH}
+ limit 1
+"""
+_MATCH_SQL = """
+select post.post_id,
+       'source_project_code'::text as match_kind_code,
+       post.source_project_code as matched_value,
+       null::numeric as confidence,
+       null::text as ontology_iri,
+       'source_post.source_project_code'::text as provenance
+  from source_post post
+ where post.post_id = any($1::uuid[])
+   and lower(normalize(btrim(coalesce(post.source_project_code, '')), NFKC)) = $2
+union all
+select post.post_id,
+       'source_project_name'::text,
+       post.source_project_name,
+       null::numeric,
+       null::text,
+       'source_post.source_project_name'::text
+  from source_post post
+ where post.post_id = any($1::uuid[])
+   and lower(normalize(btrim(coalesce(post.source_project_name, '')), NFKC)) = $2
+union all
+select mention.post_id,
+       'semantic_project_key'::text,
+       mention.project_key,
+       mention.confidence,
+       mention.ontology_iri,
+       'post_project_mention.project_key'::text
+  from post_project_mention mention
+ where mention.post_id = any($1::uuid[])
+   and lower(normalize(btrim(mention.project_key), NFKC)) = $2
+union all
+select mention.post_id,
+       'semantic_project_name'::text,
+       mention.project_name,
+       mention.confidence,
+       mention.ontology_iri,
+       'post_project_mention.project_name'::text
+  from post_project_mention mention
+ where mention.post_id = any($1::uuid[])
+   and lower(normalize(btrim(mention.project_name), NFKC)) = $2
+order by post_id, match_kind_code, matched_value
+"""
+_ROLE_SQL = """
+select role.post_id,
+       role.actor_name,
+       role.responsibility,
+       role.actor_type_code,
+       role.affiliated_organization_name,
+       role.cataloged_person_id,
+       role.cataloged_team_id,
+       role.cataloged_corporate_entity_id
+  from post_summary_role role
+ where role.post_id = any($1::uuid[])
+ order by role.post_id, role.actor_type_code, role.actor_name, role.responsibility
+"""
+_EDGE_SQL = """
+select edge.parent_post_id, edge.child_post_id, edge.fused_score
+  from post_lineage_edge edge
+ where edge.parent_post_id = any($1::uuid[])
+   and edge.child_post_id = any($1::uuid[])
+ order by edge.child_post_id, edge.parent_post_id
+"""
+
+
+class ProjectHistoryNotFound(LookupError):
+    """No authorized project history matched the requested identity."""
+
+
+async def fetch_project_history_projection(
+    conn: ProjectHistoryConnection,
+    *,
+    project_key: str,
+    focus_post_id: str | None,
+    knowledge_cutoff: datetime,
+    corporate_entity_ids: Sequence[str],
+    limit: int = PROJECT_HISTORY_DEFAULT_LIMIT,
+) -> dict[str, Any]:
+    """Return a bounded project history from authorized PostgreSQL evidence.
+
+    The query applies source eligibility, cutoff, and ABAC before selecting
+    event IDs. All subsequent match, role, and lineage reads are constrained to
+    that visible ID set, so hidden rows cannot affect counts, transitions, or
+    prior-history paths. An authorized focus event remains in a truncated
+    projection even when it falls beyond the earliest page.
+    """
+
+    if limit < 1 or limit > PROJECT_HISTORY_MAXIMUM_LIMIT:
+        raise ValueError("project history limit is outside the supported bound")
+    normalized_key = normalize_project_key(project_key)
+    rows = list(
+        await conn.fetch(
+            _EVENT_SQL,
+            normalized_key,
+            list(corporate_entity_ids),
+            knowledge_cutoff,
+            limit + 1,
+        )
+    )
+    truncated = len(rows) > limit
+    event_rows = rows[:limit]
+    if not event_rows:
+        raise ProjectHistoryNotFound(project_key)
+    visible_ids = [str(row["post_id"]) for row in event_rows]
+    if focus_post_id is not None and focus_post_id not in set(visible_ids):
+        focus_rows = list(
+            await conn.fetch(
+                _FOCUS_SQL,
+                normalized_key,
+                list(corporate_entity_ids),
+                knowledge_cutoff,
+                focus_post_id,
+            )
+        )
+        if not focus_rows:
+            raise ProjectHistoryNotFound(project_key)
+        truncated = True
+        event_rows = (event_rows[: limit - 1] if limit > 1 else []) + [focus_rows[0]]
+        event_rows.sort(key=lambda row: (row["created_at"], str(row["post_id"])))
+        visible_ids = [str(row["post_id"]) for row in event_rows]
+
+    match_rows, role_rows, edge_rows = await _fetch_project_children(
+        conn,
+        visible_ids=visible_ids,
+        normalized_key=normalized_key,
+    )
+    return build_project_history_projection(
+        project_key=project_key,
+        focus_event_id=focus_post_id,
+        event_rows=event_rows,
+        match_rows=match_rows,
+        role_rows=role_rows,
+        edge_rows=edge_rows,
+        truncated=truncated,
+    )
+
+
+async def _fetch_project_children(
+    conn: ProjectHistoryConnection,
+    *,
+    visible_ids: Sequence[str],
+    normalized_key: str,
+) -> tuple[list[Mapping[str, Any]], list[Mapping[str, Any]], list[Mapping[str, Any]]]:
+    """Fetch only child evidence whose endpoints are already authorized."""
+
+    matches = list(await conn.fetch(_MATCH_SQL, list(visible_ids), normalized_key))
+    roles = list(await conn.fetch(_ROLE_SQL, list(visible_ids)))
+    edges = list(await conn.fetch(_EDGE_SQL, list(visible_ids)))
+    return matches, roles, edges