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/events/envelope.py

@@ -0,0 +1,55 @@
+"""EventEnvelope — schema for state-hub lifecycle events published to NATS.
+
+Mirrors the EventEnvelope contract defined in activity-core
+(`src/activity_core/models.py`). The state-hub publishes; activity-core
+consumes and routes to ActivityDefinitions.
+
+Subject naming convention (see docs/nats-event-subjects.md):
+
+    org.statehub.{noun}.{verb}
+
+Examples:
+    org.statehub.repo.registered
+    org.statehub.workstream.completed
+    org.statehub.decision.resolved
+    org.statehub.domain.goal.activated
+    org.statehub.task.stale
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+PUBLISHER = "the-custodian/state-hub"
+
+
+class EventEnvelope(BaseModel):
+    """Standard envelope shared with activity-core. Do not break compatibility.
+
+    All inbound events on activity-core's side are normalised into this shape.
+    """
+
+    id: str = Field(description="UUID v4 — stable unique ID for deduplication.")
+    type: str = Field(description="Dot-namespaced event type, e.g. 'org.statehub.repo.registered'.")
+    version: str = Field(default="1.0", description="Schema version string.")
+    timestamp: datetime = Field(description="When the event occurred (UTC).")
+    publisher: str = Field(default=PUBLISHER, description="Originating service.")
+    attributes: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Event-specific attributes; structure varies by event type.",
+    )
+
+    @classmethod
+    def new(cls, event_type: str, attributes: dict[str, Any] | None = None) -> "EventEnvelope":
+        """Construct an envelope with a fresh UUID and current UTC timestamp."""
+        return cls(
+            id=str(uuid.uuid4()),
+            type=event_type,
+            timestamp=datetime.now(tz=timezone.utc),
+            publisher=PUBLISHER,
+            attributes=attributes or {},
+        )