feat: add workplan aliases and legacy meter

Adds preferred workplan REST/event surfaces, legacy-meter telemetry and weekly review summaries, documentation/dashboard terminology updates, dashboard API loading fixes, and close-out sync for STATE-WP-0052 and STATE-WP-0054.
2026-06-04 08:25:31 +02:00
parent 355f80b078
commit 166aedfa8d
43 changed files with 1851 additions and 145 deletions
--- a/api/routers/workstreams.py
+++ b/api/routers/workstreams.py
@@ -1,4 +1,5 @@
 import asyncio
+import logging
 import uuid
 import socket
 import time
@@ -6,7 +7,7 @@ from pathlib import Path
 from typing import Any

 import yaml
-from fastapi import APIRouter, Depends, HTTPException, Query, status
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response, status
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession

@@ -20,18 +21,30 @@ from api.schemas.workstream import (
    WorkstreamUpdate,
 )
 from api.services.lifecycle import transition_workstream_status
+from api.services.legacy_meter import (
+    LegacyUsageIdentity,
+    identity_from_request,
+    record_legacy_usage,
+)
 from api.workplan_status import (
    is_supported_workstream_status,
    normalize_workstream_status,
    ready_review_status,
 )

+logger = logging.getLogger(__name__)
+
 router = APIRouter(prefix="/workstreams", tags=["workstreams"])
+workplan_router = APIRouter(prefix="/workplans", tags=["workplans"])

 _INDEX_CACHE: dict[str, Any] | None = None
 _INDEX_CACHE_AT: float = 0.0
 _INDEX_TTL = 30.0

+_LEGACY_OWNER = "state-hub.api"
+_COMPLETED_WORKSTREAM_EVENT = "org.statehub.workstream.completed"
+_COMPLETED_WORKPLAN_EVENT = "org.statehub.workplan.completed"
+

 def _repo_path(repo: ManagedRepo) -> Path | None:
    hostname = socket.gethostname()
@@ -65,15 +78,72 @@ def _frontmatter(path: Path) -> dict[str, Any]:
        return {}


-@router.get("/", response_model=list[WorkstreamRead])
-async def list_workstreams(
-    topic_id: uuid.UUID | None = None,
-    repo_id: uuid.UUID | None = None,
-    repo_goal_id: uuid.UUID | None = None,
-    status: str | None = None,
-    owner: str | None = None,
-    slug: str | None = None,
-    session: AsyncSession = Depends(get_session),
+def _legacy_key(method: str, route: str) -> str:
+    return f"rest_api:{method} {route}"
+
+
+def _mark_legacy_response(response: Response | None, replacement_ref: str) -> None:
+    if response is None:
+        return
+    response.headers["Deprecation"] = "true"
+    response.headers["X-StateHub-Replacement"] = replacement_ref
+    response.headers.append("Link", f"<{replacement_ref}>; rel=\"successor-version\"")
+
+
+async def _meter_legacy_route(
+    *,
+    session: AsyncSession,
+    request: Request | None,
+    response: Response | None,
+    interface_key: str,
+    replacement_ref: str,
+) -> None:
+    _mark_legacy_response(response, replacement_ref)
+    try:
+        await record_legacy_usage(
+            session,
+            interface_key=interface_key,
+            interface_kind="rest_api",
+            replacement_ref=replacement_ref,
+            owner_component=_LEGACY_OWNER,
+            replacement_verified=True,
+            identity=identity_from_request(request),
+        )
+    except Exception:
+        await session.rollback()
+        logger.warning("legacy-meter failed to record %s", interface_key, exc_info=True)
+
+
+async def _meter_legacy_event(
+    *,
+    session: AsyncSession,
+    subject: str,
+    replacement_ref: str,
+) -> None:
+    try:
+        await record_legacy_usage(
+            session,
+            interface_key=f"event_subject:{subject}",
+            interface_kind="event_subject",
+            replacement_ref=replacement_ref,
+            owner_component="state-hub.events",
+            replacement_verified=True,
+            identity=LegacyUsageIdentity(component_key="state-hub.events"),
+        )
+    except Exception:
+        await session.rollback()
+        logger.warning("legacy-meter failed to record event subject %s", subject, exc_info=True)
+
+
+async def _list_workstreams(
+    *,
+    topic_id: uuid.UUID | None,
+    repo_id: uuid.UUID | None,
+    repo_goal_id: uuid.UUID | None,
+    status_filter: str | None,
+    owner: str | None,
+    slug: str | None,
+    session: AsyncSession,
 ) -> list[Workstream]:
    q = select(Workstream)
    if topic_id:
@@ -82,10 +152,10 @@ async def list_workstreams(
        q = q.where(Workstream.repo_id == repo_id)
    if repo_goal_id:
        q = q.where(Workstream.repo_goal_id == repo_goal_id)
-    if status:
-        normalised_status = normalize_workstream_status(status)
-        if not is_supported_workstream_status(status):
-            raise HTTPException(status_code=422, detail=f"Unsupported workstream status '{status}'")
+    if status_filter:
+        normalised_status = normalize_workstream_status(status_filter)
+        if not is_supported_workstream_status(status_filter):
+            raise HTTPException(status_code=422, detail=f"Unsupported workplan status '{status_filter}'")
        q = q.where(Workstream.status == normalised_status)
    if owner:
        q = q.where(Workstream.owner == owner)
@@ -100,12 +170,12 @@ async def list_workstreams(
    return list(result.scalars().all())


-@router.get("/workplan-index")
-async def workplan_index(
-    refresh: bool = Query(False, description="Force cache invalidation"),
-    session: AsyncSession = Depends(get_session),
+async def _workplan_index(
+    *,
+    refresh: bool,
+    session: AsyncSession,
 ) -> dict[str, Any]:
-    """Map file-backed workstream ids to their local workplan filenames."""
+    """Map file-backed workplan ids to their local workplan filenames."""
    global _INDEX_CACHE, _INDEX_CACHE_AT
    if not refresh and _INDEX_CACHE is not None and (time.monotonic() - _INDEX_CACHE_AT) < _INDEX_TTL:
        return _INDEX_CACHE
@@ -148,15 +218,15 @@ async def workplan_index(
                    "needs_review": bool(review and review.needs_review),
                    "health_labels": ["needs_review"] if review and review.needs_review else [],
                }
-    _INDEX_CACHE = {"workstreams": index}
+    _INDEX_CACHE = {"workplans": index, "workstreams": index}
    _INDEX_CACHE_AT = time.monotonic()
    return _INDEX_CACHE


-@router.post("/", response_model=WorkstreamRead, status_code=status.HTTP_201_CREATED)
-async def create_workstream(
+async def _create_workstream(
+    *,
    body: WorkstreamCreate,
-    session: AsyncSession = Depends(get_session),
+    session: AsyncSession,
 ) -> Workstream:
    ws = Workstream(**body.model_dump())
    session.add(ws)
@@ -165,26 +235,26 @@ async def create_workstream(
    return ws


-@router.get("/{workstream_id}", response_model=WorkstreamRead)
-async def get_workstream(
+async def _get_workstream(
+    *,
    workstream_id: uuid.UUID,
-    session: AsyncSession = Depends(get_session),
+    session: AsyncSession,
 ) -> Workstream:
    ws = await session.get(Workstream, workstream_id)
    if ws is None:
-        raise HTTPException(status_code=404, detail="Workstream not found")
+        raise HTTPException(status_code=404, detail="Workplan not found")
    return ws


-@router.patch("/{workstream_id}", response_model=WorkstreamRead)
-async def update_workstream(
+async def _update_workstream(
+    *,
    workstream_id: uuid.UUID,
    body: WorkstreamUpdate,
-    session: AsyncSession = Depends(get_session),
+    session: AsyncSession,
 ) -> Workstream:
    ws = await session.get(Workstream, workstream_id)
    if ws is None:
-        raise HTTPException(status_code=404, detail="Workstream not found")
+        raise HTTPException(status_code=404, detail="Workplan not found")
    update_data = body.model_dump(exclude_unset=True)
    status_update = update_data.pop("status", None)
    prev_status = ws.status
@@ -196,32 +266,232 @@ async def update_workstream(
    await session.refresh(ws)

    if normalize_workstream_status(prev_status) != "finished" and ws.status == "finished":
-        subject = "org.statehub.workstream.completed"
-        envelope = EventEnvelope.new(
-            subject,
-            attributes={
-                "workstream_id": str(ws.id),
-                "slug": ws.slug,
-                "title": ws.title,
-                "topic_id": str(ws.topic_id),
-                "repo_id": str(ws.repo_id) if ws.repo_id else None,
-                "repo_goal_id": str(ws.repo_goal_id) if ws.repo_goal_id else None,
-            },
-        )
-        asyncio.create_task(publish_event(subject, envelope))
+        await _publish_completion_events(ws, session)

    return ws


-@router.delete("/{workstream_id}", response_model=WorkstreamRead)
-async def archive_workstream(
+async def _archive_workstream(
+    *,
    workstream_id: uuid.UUID,
-    session: AsyncSession = Depends(get_session),
+    session: AsyncSession,
 ) -> Workstream:
    ws = await session.get(Workstream, workstream_id)
    if ws is None:
-        raise HTTPException(status_code=404, detail="Workstream not found")
+        raise HTTPException(status_code=404, detail="Workplan not found")
    transition_workstream_status(ws, "archived")
    await session.commit()
    await session.refresh(ws)
    return ws
+
+
+async def _publish_completion_events(ws: Workstream, session: AsyncSession) -> None:
+    workplan_envelope = EventEnvelope.new(
+        _COMPLETED_WORKPLAN_EVENT,
+        attributes={
+            "workplan_id": str(ws.id),
+            "legacy_workstream_id": str(ws.id),
+            "slug": ws.slug,
+            "title": ws.title,
+            "topic_id": str(ws.topic_id),
+            "repo_id": str(ws.repo_id) if ws.repo_id else None,
+            "repo_goal_id": str(ws.repo_goal_id) if ws.repo_goal_id else None,
+        },
+    )
+    asyncio.create_task(publish_event(_COMPLETED_WORKPLAN_EVENT, workplan_envelope))
+
+    await _meter_legacy_event(
+        session=session,
+        subject=_COMPLETED_WORKSTREAM_EVENT,
+        replacement_ref=_COMPLETED_WORKPLAN_EVENT,
+    )
+    legacy_envelope = EventEnvelope.new(
+        _COMPLETED_WORKSTREAM_EVENT,
+        attributes={
+            "workstream_id": str(ws.id),
+            "slug": ws.slug,
+            "title": ws.title,
+            "topic_id": str(ws.topic_id),
+            "repo_id": str(ws.repo_id) if ws.repo_id else None,
+            "repo_goal_id": str(ws.repo_goal_id) if ws.repo_goal_id else None,
+        },
+    )
+    asyncio.create_task(publish_event(_COMPLETED_WORKSTREAM_EVENT, legacy_envelope))
+
+
+@router.get("/", response_model=list[WorkstreamRead])
+async def list_workstreams(
+    request: Request,
+    response: Response,
+    topic_id: uuid.UUID | None = None,
+    repo_id: uuid.UUID | None = None,
+    repo_goal_id: uuid.UUID | None = None,
+    status: str | None = None,
+    owner: str | None = None,
+    slug: str | None = None,
+    session: AsyncSession = Depends(get_session),
+) -> list[Workstream]:
+    await _meter_legacy_route(
+        session=session,
+        request=request,
+        response=response,
+        interface_key=_legacy_key("GET", "/workstreams/"),
+        replacement_ref="/workplans/",
+    )
+    return await _list_workstreams(
+        topic_id=topic_id,
+        repo_id=repo_id,
+        repo_goal_id=repo_goal_id,
+        status_filter=status,
+        owner=owner,
+        slug=slug,
+        session=session,
+    )
+
+
+@workplan_router.get("/", response_model=list[WorkstreamRead])
+async def list_workplans(
+    topic_id: uuid.UUID | None = None,
+    repo_id: uuid.UUID | None = None,
+    repo_goal_id: uuid.UUID | None = None,
+    status: str | None = None,
+    owner: str | None = None,
+    slug: str | None = None,
+    session: AsyncSession = Depends(get_session),
+) -> list[Workstream]:
+    return await _list_workstreams(
+        topic_id=topic_id,
+        repo_id=repo_id,
+        repo_goal_id=repo_goal_id,
+        status_filter=status,
+        owner=owner,
+        slug=slug,
+        session=session,
+    )
+
+
+@router.get("/workplan-index")
+async def workplan_index(
+    request: Request,
+    response: Response,
+    refresh: bool = Query(False, description="Force cache invalidation"),
+    session: AsyncSession = Depends(get_session),
+) -> dict[str, Any]:
+    await _meter_legacy_route(
+        session=session,
+        request=request,
+        response=response,
+        interface_key=_legacy_key("GET", "/workstreams/workplan-index"),
+        replacement_ref="/workplans/index",
+    )
+    return await _workplan_index(refresh=refresh, session=session)
+
+
+@workplan_router.get("/index")
+async def workplan_index_preferred(
+    refresh: bool = Query(False, description="Force cache invalidation"),
+    session: AsyncSession = Depends(get_session),
+) -> dict[str, Any]:
+    return await _workplan_index(refresh=refresh, session=session)
+
+
+@router.post("/", response_model=WorkstreamRead, status_code=status.HTTP_201_CREATED)
+async def create_workstream(
+    request: Request,
+    response: Response,
+    body: WorkstreamCreate,
+    session: AsyncSession = Depends(get_session),
+) -> Workstream:
+    await _meter_legacy_route(
+        session=session,
+        request=request,
+        response=response,
+        interface_key=_legacy_key("POST", "/workstreams/"),
+        replacement_ref="/workplans/",
+    )
+    return await _create_workstream(body=body, session=session)
+
+
+@workplan_router.post("/", response_model=WorkstreamRead, status_code=status.HTTP_201_CREATED)
+async def create_workplan(
+    body: WorkstreamCreate,
+    session: AsyncSession = Depends(get_session),
+) -> Workstream:
+    return await _create_workstream(body=body, session=session)
+
+
+@router.get("/{workstream_id}", response_model=WorkstreamRead)
+async def get_workstream(
+    request: Request,
+    response: Response,
+    workstream_id: uuid.UUID,
+    session: AsyncSession = Depends(get_session),
+) -> Workstream:
+    await _meter_legacy_route(
+        session=session,
+        request=request,
+        response=response,
+        interface_key=_legacy_key("GET", "/workstreams/{workstream_id}"),
+        replacement_ref="/workplans/{workplan_id}",
+    )
+    return await _get_workstream(workstream_id=workstream_id, session=session)
+
+
+@workplan_router.get("/{workplan_id}", response_model=WorkstreamRead)
+async def get_workplan(
+    workplan_id: uuid.UUID,
+    session: AsyncSession = Depends(get_session),
+) -> Workstream:
+    return await _get_workstream(workstream_id=workplan_id, session=session)
+
+
+@router.patch("/{workstream_id}", response_model=WorkstreamRead)
+async def update_workstream(
+    request: Request,
+    response: Response,
+    workstream_id: uuid.UUID,
+    body: WorkstreamUpdate,
+    session: AsyncSession = Depends(get_session),
+) -> Workstream:
+    await _meter_legacy_route(
+        session=session,
+        request=request,
+        response=response,
+        interface_key=_legacy_key("PATCH", "/workstreams/{workstream_id}"),
+        replacement_ref="/workplans/{workplan_id}",
+    )
+    return await _update_workstream(workstream_id=workstream_id, body=body, session=session)
+
+
+@workplan_router.patch("/{workplan_id}", response_model=WorkstreamRead)
+async def update_workplan(
+    workplan_id: uuid.UUID,
+    body: WorkstreamUpdate,
+    session: AsyncSession = Depends(get_session),
+) -> Workstream:
+    return await _update_workstream(workstream_id=workplan_id, body=body, session=session)
+
+
+@router.delete("/{workstream_id}", response_model=WorkstreamRead)
+async def archive_workstream(
+    request: Request,
+    response: Response,
+    workstream_id: uuid.UUID,
+    session: AsyncSession = Depends(get_session),
+) -> Workstream:
+    await _meter_legacy_route(
+        session=session,
+        request=request,
+        response=response,
+        interface_key=_legacy_key("DELETE", "/workstreams/{workstream_id}"),
+        replacement_ref="/workplans/{workplan_id}",
+    )
+    return await _archive_workstream(workstream_id=workstream_id, session=session)
+
+
+@workplan_router.delete("/{workplan_id}", response_model=WorkstreamRead)
+async def archive_workplan(
+    workplan_id: uuid.UUID,
+    session: AsyncSession = Depends(get_session),
+) -> Workstream:
+    return await _archive_workstream(workstream_id=workplan_id, session=session)