coulomb/the-custodian
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e0f8bbfbfc3f8632e92232f022b615afecd79881
the-custodian/workplans/CUST-WP-0040-state-hub-nats-activity-core-integration.md
tegwick ee63051a50 chore(workplan): stub CUST-WP-0040 state hub NATS / activity-core integration 
Workplan for delegating maintenance automation from the state hub to
activity-core via NATS JetStream. Covers NATS publisher wiring, subject
schema, lifecycle event emission, cron migration stubs, and delegation
protocol docs.

Hub workstream: d8ac100b-a844-46a5-9684-415df0d32539

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-14 18:12:29 +02:00

6.9 KiB
Raw Blame History

id, type, domain, repo, status, state_hub_workstream_id, tasks, created
id type domain repo status state_hub_workstream_id tasks created
CUST-WP-0040 workplan custodian the-custodian active d8ac100b-a844-46a5-9684-415df0d32539
id title state_hub_task_id status
T01 Connect state hub event publisher to NATS JetStream c4bfa299-0000-0000-0000-000000000000 todo
id title state_hub_task_id status
T02 Define NATS subject schema for state hub lifecycle events 2ae236a4-0000-0000-0000-000000000000 todo
id title state_hub_task_id status
T03 Implement state hub lifecycle events as NATS EventEnvelopes ccb5a3fb-0000-0000-0000-000000000000 todo
id title state_hub_task_id status
T04 Migrate state hub maintenance crons to activity-core ActivityDefinitions (design stub) 933b2a80-0000-0000-0000-000000000000 todo
id title state_hub_task_id status
T05 Document state hub → activity-core delegation protocol b261d4b8-0000-0000-0000-000000000000 todo
id title state_hub_task_id status
T06 Update SCOPE.md to reflect activity-core delegation 356682e6-e608-4f58-b418-cdef2b9435f2 todo
2026-05-14

CUST-WP-0040: State Hub NATS / Activity-Core Integration

Purpose

The Custodian State Hub currently runs bespoke maintenance cron jobs and ad-hoc event handling internally. With activity-core established as the org-wide Event Bridge, the state hub should delegate maintenance automation to activity-core by publishing lifecycle events on NATS JetStream — rather than implementing task creation itself.

This workplan makes the state hub an event publisher and removes it from the task-generation business. The result: maintenance automations are governed by ActivityDefinitions in activity-core (auditable, rule-based, testable) rather than scattered cron code in the-custodian.

Context

  • activity-core (WP-0003 in progress): event loop that receives NATS events and evaluates rules/instructions to create tasks in issue-core.
  • State hub: tracks domain state, workstreams, decisions, and progress events. It knows when things happen (repo registered, workstream completed, stale task).
  • The gap: the state hub knows about org events but has no way to publish them to NATS so that activity-core can react. This workplan closes that gap.

See: docs/adr/adr-001-event-bridge-architecture.md in activity-core for the delegation protocol design.

Scope

In scope:

  • NATS JetStream publisher client in the state hub
  • EventEnvelope schema for state hub lifecycle events
  • NATS subject naming convention for state hub events
  • Design stub for migrating existing maintenance crons to ActivityDefinitions
  • Protocol documentation

Out of scope:

  • activity-core rule/instruction implementation (lives in activity-core WP-0003)
  • Removing existing state hub crons before activity-core is ready (sequencing risk)
  • project-core (future)

Tasks

T01 — Connect state hub event publisher to NATS JetStream

Add a NATS JetStream publisher client to the state hub. It should:

  • Connect to the NATS server on startup (use existing NATS config pattern)
  • Expose a publish_event(envelope: EventEnvelope) function
  • Be disabled/no-op when NATS_URL is not set (for environments without NATS)
  • Log publish success/failure with event ID

Key file: state_hub/events/nats_publisher.py (new)

T02 — Define NATS subject schema for state hub lifecycle events

Document and agree on the NATS subject naming convention for state hub events. Proposed pattern: org.statehub.{noun}.{verb} — e.g.:

  • org.statehub.repo.registered
  • org.statehub.workstream.completed
  • org.statehub.task.stale
  • org.statehub.domain.goal.activated

Write the subject schema as a section in docs/nats-event-subjects.md. Cross-reference with activity-core's event-types registry.

T03 — Implement state hub lifecycle events as NATS EventEnvelopes

Wire the NATS publisher into state hub write operations. Candidate events:

  • org.statehub.repo.registered — when a repo is registered in the hub
  • org.statehub.workstream.completed — when a workstream status → completed
  • org.statehub.task.stale — periodic check, tasks not updated in 14+ days

Each event must conform to the EventEnvelope schema defined in activity-core's event type registry. Write a stub event type definition file in activity-core at event-types/org.statehub.repo.registered.md (or coordinate with the activity-core agent to do so).

T04 — Migrate state hub maintenance crons to activity-core ActivityDefinitions (design stub)

Design stub only — not yet implemented.

List the existing maintenance cron jobs in the state hub codebase. For each:

  • Identify the equivalent ActivityDefinition trigger (cron expression, event type)
  • Draft the rule/instruction that would replace the cron logic
  • Note any context sources required (state hub API, repo-scoping)
  • Flag blockers (e.g., activity-core WP-0003 phase not yet complete)

Output: a markdown table in this workplan and/or in docs/cron-migration.md.

T05 — Document state hub → activity-core delegation protocol

Write docs/activity-core-delegation.md explaining:

  • Why state hub delegates maintenance automation to activity-core
  • Which lifecycle events the state hub publishes and why
  • How activity-core ActivityDefinitions react (cross-reference WP-0003)
  • What remains in the state hub vs. what moves to ActivityDefinitions
  • Operational checklist: what to verify when a maintenance cron is being migrated

T06 — Update SCOPE.md to reflect activity-core delegation

Update the state hub's SCOPE.md (or write one if missing):

  • Add activity-core as a downstream consumer of state hub lifecycle events
  • Clarify that maintenance task creation moves to activity-core
  • Note that the state hub remains the authoritative read model (not a task factory)

Build Order

T01 (NATS publisher) → T03 (wire events)
T02 (subject schema) → T03
T03 → T04 (migration stub, requires events to exist)
T04 → T05 (docs, requires migration list)
T06 (independent — SCOPE.md update)

Completion Criteria

  1. State hub publishes at least one lifecycle event type to NATS on relevant writes
  2. Subject naming convention documented and agreed with activity-core team
  3. Migration stub completed — all existing crons listed with ActivityDefinition drafts
  4. Delegation protocol documented
  5. SCOPE.md updated

Notes

  • Sequencing: complete T01–T03 before activity-core WP-0003 is done, so the first ActivityDefinitions that consume state hub events can be tested end-to-end.
  • No removal yet: do not remove existing state hub crons until activity-core ActivityDefinitions are validated in staging. Run both in parallel initially.
  • The state hub must never write directly to activity-core's database — only via NATS.

Change History

  • v0.1 (2026-05-14): Stub created by activity-core agent during WP-0003 planning. Local agent to flesh out and implement.
Reference in New Issue View Git Blame Copy Permalink