feat(state-hub): CUST-WP-0040 — NATS lifecycle event publishing for activity-core

Makes the state hub an event publisher so activity-core can drive
maintenance automation declaratively via ActivityDefinitions, rather
than the hub creating tasks itself.

- api/events/: lazy JetStream publisher + EventEnvelope mirroring
  activity-core's contract; no-op when NATS_URL unset, fire-and-forget
  with logged failures so publishing never breaks an API request.
- Wired publishers on the five v1.0 lifecycle events:
    org.statehub.repo.registered        (POST /repos/)
    org.statehub.workstream.completed   (PATCH /workstreams/* on transition)
    org.statehub.decision.resolved      (POST /decisions/*/resolve)
    org.statehub.domain.goal.activated  (POST /domain-goals/*/activate)
    org.statehub.task.stale             (scripts/cleanup_stale_tasks.py)
- docs/nats-event-subjects.md: subject naming convention + catalog.
- docs/cron-migration.md: design stub for replacing custodian-sync
  systemd timer and cleanup-stale cron with ActivityDefinitions
  (depends on activity-core WP-0003).
- docs/activity-core-delegation.md: protocol, invariants, cutover plan.
- SCOPE.md: declares activity-core as downstream event consumer and
  restates that the state hub stays a read model, not a task factory.

Workplan: workplans/CUST-WP-0040-state-hub-nats-activity-core-integration.md
242 tests pass.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

state-hub/api/routers/decisions.py

@@ -1,3 +1,4 @@
+import asyncio
 import logging
 import uuid
 from datetime import datetime, timezone
@@ -10,6 +11,7 @@ from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from api.database import get_session
+from api.events import EventEnvelope, publish_event
 from api.models.decision import Decision, DecisionStatus, DecisionType
 from api.models.progress_event import ProgressEvent
 from api.schemas.decision import DecisionCreate, DecisionRead, DecisionResolve, DecisionUpdate
@@ -150,6 +152,20 @@ async def resolve_decision_action(
     if body.write_log:
         await _write_project_log(decision, body.rationale, body.decided_by, session)
 
+    subject = "org.statehub.decision.resolved"
+    envelope = EventEnvelope.new(
+        subject,
+        attributes={
+            "decision_id": str(decision.id),
+            "title": decision.title,
+            "topic_id": str(decision.topic_id) if decision.topic_id else None,
+            "workstream_id": str(decision.workstream_id) if decision.workstream_id else None,
+            "decided_by": body.decided_by,
+            "rationale_snippet": (body.rationale or "")[:240],
+        },
+    )
+    asyncio.create_task(publish_event(subject, envelope))
+
     return decision
 
 

state-hub/api/routers/domain_goals.py

@@ -1,3 +1,4 @@
+import asyncio
 import uuid
 
 from fastapi import APIRouter, Depends, HTTPException, status
@@ -5,6 +6,7 @@ from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from api.database import get_session
+from api.events import EventEnvelope, publish_event
 from api.models.domain import Domain
 from api.models.domain_goal import DomainGoal, DomainGoalStatus  # noqa: F401 (DomainGoalStatus used in activate)
 from api.schemas.domain_goal import DomainGoalCreate, DomainGoalRead, DomainGoalUpdate
@@ -96,6 +98,7 @@ async def activate_domain_goal(
     goal = await session.get(DomainGoal, goal_id)
     if goal is None:
         raise HTTPException(status_code=404, detail="Domain goal not found")
+    was_active = goal.status == DomainGoalStatus.active
 
     # Supersede any other active goal for this domain
     existing = await session.execute(
@@ -105,10 +108,28 @@ async def activate_domain_goal(
             DomainGoal.id != goal_id,
         )
     )
+    superseded_ids: list[str] = []
     for old in existing.scalars().all():
         old.status = DomainGoalStatus.superseded
+        superseded_ids.append(str(old.id))
 
     goal.status = DomainGoalStatus.active
     await session.commit()
     await session.refresh(goal)
+
+    if not was_active:
+        domain = await session.get(Domain, goal.domain_id)
+        subject = "org.statehub.domain.goal.activated"
+        envelope = EventEnvelope.new(
+            subject,
+            attributes={
+                "goal_id": str(goal.id),
+                "domain_id": str(goal.domain_id),
+                "domain_slug": domain.slug if domain else None,
+                "title": goal.title,
+                "superseded_goal_ids": superseded_ids,
+            },
+        )
+        asyncio.create_task(publish_event(subject, envelope))
+
     return goal

state-hub/api/routers/repos.py

@@ -16,6 +16,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from api.config import settings
 from api.database import get_session
+from api.events import EventEnvelope, publish_event
 from api.doi_engine import (
     compute_fingerprint,
     evaluate as _doi_evaluate,
@@ -94,6 +95,20 @@ async def register_repo(
     session.add(repo)
     await session.commit()
     await session.refresh(repo)
+
+    subject = "org.statehub.repo.registered"
+    envelope = EventEnvelope.new(
+        subject,
+        attributes={
+            "repo_id": str(repo.id),
+            "repo_slug": repo.slug,
+            "domain_slug": body.domain_slug,
+            "remote_url": repo.remote_url,
+            "local_path": repo.local_path,
+        },
+    )
+    asyncio.create_task(publish_event(subject, envelope))
+
     return repo
 
 

state-hub/api/routers/workstreams.py

@@ -1,3 +1,4 @@
+import asyncio
 import uuid
 import socket
 import time
@@ -9,6 +10,7 @@ from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from api.database import get_session
+from api.events import EventEnvelope, publish_event
 from api.models.managed_repo import ManagedRepo
 from api.models.workstream import Workstream
 from api.schemas.workstream import (
@@ -168,10 +170,27 @@ async def update_workstream(
     ws = await session.get(Workstream, workstream_id)
     if ws is None:
         raise HTTPException(status_code=404, detail="Workstream not found")
+    prev_status = ws.status
     for field, value in body.model_dump(exclude_unset=True).items():
         setattr(ws, field, value)
     await session.commit()
     await session.refresh(ws)
+
+    if prev_status != "completed" and ws.status == "completed":
+        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))
+
     return ws